feat(ui): complete phase 4 Poyraz UI foundation

docs/self-hosted-redesign/neta-self-hosted-v3-master-plan.md

@@ -350,7 +350,7 @@ type BrandingSettings = {
 
 Tema checklist'i:
 
-- [ ] Poyraz UI semantic tokenları kullanılıyor.
+- [x] Poyraz UI semantic tokenları kullanılıyor.
 - [x] Marka ayarları root layout'ta server-side okunuyor.
 - [x] İlk render sırasında tema/renk parlaması yok.
 - [x] Primary ve accent renk girdileri doğrulanıyor.
@@ -378,31 +378,31 @@ Referans paket: `poyraz-ui@3.0.2`
 
 ### 12.2. Kurulum checklist'i
 
-- [ ] `poyraz-ui` v3'e yükseltildi.
-- [ ] `@import "poyraz-ui/preset.css";` global CSS'e eklendi.
-- [ ] Atom importları `poyraz-ui/atoms` üzerinden.
-- [ ] Molecule importları `poyraz-ui/molecules` üzerinden.
-- [ ] Organism importları `poyraz-ui/organisms` üzerinden.
-- [ ] Tema gerekiyorsa `poyraz-ui/themes` kullanımı değerlendirildi.
+- [x] `poyraz-ui` v3'e yükseltildi.
+- [x] `@import "poyraz-ui/preset.css";` global CSS'e eklendi.
+- [x] Atom importları `poyraz-ui/atoms` üzerinden.
+- [x] Molecule importları `poyraz-ui/molecules` üzerinden.
+- [x] Organism importları `poyraz-ui/organisms` üzerinden.
+- [x] Tema gerekiyorsa `poyraz-ui/themes` kullanımı değerlendirildi.
 - [x] Package modeli ana kullanım biçimi olarak belirlendi.
 - [x] Source registry yalnızca source ownership gereken istisnalar için kullanılacak.
 
 ### 12.3. Ortak UI standartları
 
-- [ ] Typography hiyerarşisi tanımlandı.
-- [ ] Page header standardı tanımlandı.
-- [ ] Primary ve secondary action standardı tanımlandı.
-- [ ] Form field ve validation standardı tanımlandı.
-- [ ] Status-to-Badge eşleme tablosu oluşturuldu.
-- [ ] Loading state standardı oluşturuldu.
-- [ ] Empty state standardı oluşturuldu.
-- [ ] Error state standardı oluşturuldu.
-- [ ] Permission/forbidden state standardı oluşturuldu.
-- [ ] Destructive confirmation standardı oluşturuldu.
-- [ ] Desktop Dialog/Sheet ve mobil Drawer kullanım kuralı belirlendi.
-- [ ] Toast ve inline feedback ayrımı belirlendi.
-- [ ] DataTable kullanım standardı belirlendi.
-- [ ] Dashboard KPI kart standardı belirlendi.
+- [x] Typography hiyerarşisi tanımlandı.
+- [x] Page header standardı tanımlandı.
+- [x] Primary ve secondary action standardı tanımlandı.
+- [x] Form field ve validation standardı tanımlandı.
+- [x] Status-to-Badge eşleme tablosu oluşturuldu.
+- [x] Loading state standardı oluşturuldu.
+- [x] Empty state standardı oluşturuldu.
+- [x] Error state standardı oluşturuldu.
+- [x] Permission/forbidden state standardı oluşturuldu.
+- [x] Destructive confirmation standardı oluşturuldu.
+- [x] Desktop Dialog/Sheet ve mobil Drawer kullanım kuralı belirlendi.
+- [x] Toast ve inline feedback ayrımı belirlendi.
+- [x] DataTable kullanım standardı belirlendi.
+- [x] Dashboard KPI kart standardı belirlendi.
 
 ### 12.4. Erişilebilirlik kalite kapısı
 
@@ -668,13 +668,13 @@ Mobil hazırlık checklist'i:
 
 ### 18.3. Poyraz UI v3 sonrası değerlendirilecekler
 
-- [ ] `@base-ui/react`
-- [ ] Doğrudan `@radix-ui/*` bağımlılıkları
-- [ ] `radix-ui`
-- [ ] `shadcn`
-- [ ] Kullanılmayan local UI primitive'leri
+- [x] `@base-ui/react`
+- [x] Doğrudan `@radix-ui/*` bağımlılıkları
+- [x] `radix-ui`
+- [x] `shadcn`
+- [x] Kullanılmayan local UI primitive'leri
 - [ ] `framer-motion`, kullanım kalmadıysa
-- [ ] `next-themes`, tema başka şekilde çözüldüyse
+- [x] `next-themes`, tema başka şekilde çözüldüyse
 - [ ] Kullanılmayan icon/form/theme yardımcıları
 
 ### 18.4. İşlevsel gerekçeyle korunabilecekler
@@ -693,12 +693,12 @@ Mobil hazırlık checklist'i:
 Dependency kalite kapısı:
 
 - [ ] Her production dependency için aktif import veya açık gerekçe var.
-- [ ] Aynı işi yapan iki UI primitive sistemi yok.
+- [x] Aynı işi yapan iki UI primitive sistemi yok.
 - [ ] Aynı işi yapan iki auth sistemi yok.
 - [ ] Aynı işi yapan iki runtime database sistemi yok.
 - [ ] Browser database bağımlılığı yok.
 - [ ] Build çıktısında Supabase referansı yok.
-- [ ] Build çıktısında Poyraz UI v2 referansı yok.
+- [x] Build çıktısında Poyraz UI v2 referansı yok.
 
 ## 19. Test stratejisi
 
@@ -769,7 +769,7 @@ Mümkün olduğunda küçük ve doğrudan test araçları tercih edilir; test al
 - [ ] Upgrade/migration akışı belgelendi.
 - [ ] Mobil API sınırı belgelendi.
 - [ ] Eski ve çelişkili Supabase belgeleri archive veya kaldırıldı.
-- [ ] ADR-0006 Poyraz UI v3 kararıyla güncellendi.
+- [x] ADR-0006 Poyraz UI v3 kararıyla güncellendi.
 - [ ] ADR-0007 ile PWA runtime durumu uyumlu hale getirildi.
 
 ## 22. Uygulama fazları
@@ -867,14 +867,24 @@ Faz 3 tamamlanma notu (2026-07-16):
 
 Amaç: Sayfa dönüşümleri başlamadan önce ortak UI sistemini kurmak.
 
-- [ ] Poyraz UI v3 kuruldu.
-- [ ] Preset CSS eklendi.
-- [ ] Global shell Poyraz Sidebar organism ile kuruldu.
-- [ ] Typography standardı tamamlandı.
-- [ ] Form standardı tamamlandı.
-- [ ] Feedback state'leri tamamlandı.
-- [ ] Tema/branding token bridge tamamlandı.
-- [ ] Local primitive kaldırma politikası uygulandı.
+- [x] Poyraz UI v3 kuruldu.
+- [x] Preset CSS eklendi.
+- [x] Global shell Poyraz Sidebar organism ile kuruldu.
+- [x] Typography standardı tamamlandı.
+- [x] Form standardı tamamlandı.
+- [x] Feedback state'leri tamamlandı.
+- [x] Tema/branding token bridge tamamlandı.
+- [x] Local primitive kaldırma politikası uygulandı.
+
+Faz 4 tamamlanma notu (2026-07-16):
+
+- `poyraz-ui@3.0.2`, preset CSS ve atoms/molecules/organisms subpath import sınırı pnpm/npm lockfile'larıyla birlikte kuruldu.
+- Freelancer ve portal global shell'i Poyraz Sidebar organism'e; hesap menüsü DropdownMenu'ye, global toast katmanı Poyraz Toaster'a taşındı.
+- Branding servisi primary, accent, focus ve radius değerlerini SSR sırasında doğrudan Poyraz semantic tokenlarına köprüler; system dark mode ilk paint öncesi uygulanır.
+- Typography, page header, action, form, status badge, loading/empty/error/forbidden, destructive confirmation, overlay, DataTable ve KPI standartları kod bileşimleri ve Faz 4 belgesiyle tanımlandı.
+- Duplicate local generic primitive'ler ve doğrudan UI dependency'leri kaldırıldı; yalnızca Neta'ya özgü pending/offline davranış bileşimleri Poyraz atomları üzerinde bırakıldı.
+- `phase4:ui-boundary`, typecheck, hedefli ESLint, storage/branding smoke, auth/SSR branding smoke, production build ve `git diff --check` başarılıdır. Repo genel lint'i legacy Faz 5–7 borçları nedeniyle açık tutuldu.
+- Uygulama ve doğrulama ayrıntıları `phase-4-poyraz-ui-foundation.md` belgesinde kaydedildi.
 
 Çıkış kriteri: Yeni sayfalar ek bir primitive sistemi oluşturmadan geliştirilebiliyor.
 
@@ -971,12 +981,12 @@ Amaç: React Native geliştirmesine başlamadan önce instance keşif ve stabil
 
 ### UI
 
-- [ ] Poyraz UI v3 kuruldu.
-- [ ] Preset ve token sistemi kuruldu.
-- [ ] Global shell taşındı.
+- [x] Poyraz UI v3 kuruldu.
+- [x] Preset ve token sistemi kuruldu.
+- [x] Global shell taşındı.
 - [ ] Freelancer sayfaları taşındı.
 - [ ] Portal sayfaları taşındı.
-- [ ] Local primitive tekrarı temizlendi.
+- [x] Local primitive tekrarı temizlendi.
 - [ ] Light/dark ve responsive kontroller tamamlandı.
 
 ### Özelleştirme
@@ -1012,7 +1022,7 @@ Amaç: React Native geliştirmesine başlamadan önce instance keşif ve stabil
 - [ ] Production Docker smoke başarılı.
 - [ ] README güncel.
 - [ ] Supabase runtime referansı kalmadı.
-- [ ] Poyraz UI v2 referansı kalmadı.
+- [x] Poyraz UI v2 referansı kalmadı.
 
 ## 24. Definition of Done
 

docs/self-hosted-redesign/phase-4-poyraz-ui-foundation.md

@@ -0,0 +1,145 @@
+# Faz 4 — Poyraz UI v3 foundation
+
+Tarih: 2026-07-16
+
+Bu faz, freelancer ve portal sayfalarının dikey dönüşümünden önce ortak UI sözleşmesini kurar. Sayfa bazlı bilgi mimarisi ve görsel revizyonlar Faz 5–6'da kullanıcı yönlendirmesiyle yapılacaktır.
+
+## Uygulanan temel
+
+- `poyraz-ui` `3.0.2` sürümüne yükseltildi; hem pnpm hem npm lockfile'ları eşitlendi.
+- Tailwind v4 girişine `poyraz-ui/preset.css` eklendi.
+- Atom, molecule ve organism importları yalnızca ilgili package subpath'inden yapılıyor.
+- Freelancer ve portal shell'i aynı Poyraz Sidebar organism bileşimini kullanıyor.
+- Masaüstü daraltma, mobil overlay ve mobil aç/kapat state'i `SidebarProvider` tarafından yönetiliyor.
+- Hesap menüsü custom event yönetimi yerine Poyraz `DropdownMenu`; icon-only shell aksiyonları Poyraz `Tooltip` kullanıyor.
+- Root feedback katmanı Poyraz `Toaster`; auth bildirimleri Poyraz `Alert` ve `toast` kullanıyor.
+- Auth alanları ve loading ekranları local kopyalar yerine Poyraz atomlarını kullanıyor.
+- Instance adı ve açık/koyu logo shell ile auth yüzeylerine taşındı.
+
+## Import ve ownership kuralı
+
+```ts
+import { Button, Input, Typography } from "poyraz-ui/atoms";
+import { Alert, Dialog, Form, Select, toast } from "poyraz-ui/molecules";
+import { DataTable, Sidebar } from "poyraz-ui/organisms";
+```
+
+`poyraz-ui` package root importu kullanılmaz. Genel amaçlı UI primitive'i `components/ui` altında yeniden yazılmaz. Neta'ya özgü durum veya davranış, Poyraz bileşenlerinden `components/system` altında compose edilir.
+
+İzin verilen local davranış yardımcıları:
+
+- `OfflineIndicator`: browser bağlantı durumu davranışı.
+- `PendingLink`: Next.js navigasyon pending davranışı.
+- `PendingSubmitButton`: server action pending davranışı; görsel primitive olarak Poyraz `Button` kullanır.
+
+Bu sınır `pnpm phase4:ui-boundary` ile otomatik doğrulanır.
+
+## Typography ve page header
+
+Poyraz `Typography` bütün yeni sayfalarda metin semantiğinin kaynağıdır:
+
+| Rol | Poyraz variant | HTML semantiği |
+| --- | --- | --- |
+| Sayfa başlığı | `h1` | `h1` |
+| Bölüm başlığı | `h2` / `h3` | sıradaki doğru heading seviyesi |
+| Kart başlığı | `h4` / `large` | bağlama göre `h2`–`h3` |
+| Gövde | `body` / `p` | `p` |
+| Yardımcı açıklama | `muted` | `p` |
+| Metadata | `caption` / `small` | `span` veya `p` |
+
+Yeni liste ve detay sayfaları `components/system/page-header.tsx` bileşimini kullanır. Header sırası: isteğe bağlı eyebrow, tek `h1`, kısa açıklama, secondary aksiyonlar ve en sağda bir primary aksiyon. Bir görünümde birincil aksiyon sayısı bir olmalıdır. Secondary aksiyonlar `secondary`, `outline` veya `ghost`; riskli aksiyonlar yalnızca `destructive` variant kullanır.
+
+## Form standardı
+
+İki form yolu vardır:
+
+1. Basit Server Action formları native `<form>` ile; görünür Poyraz `Label`, Poyraz `Input`/`Textarea`/`Select`, alan yanında açıklama ve inline hata kullanır.
+2. Client-side etkileşimli veya çok alanlı formlar `react-hook-form` ile Poyraz `Form`, `FormField`, `FormItem`, `FormLabel`, `FormControl`, `FormDescription` ve `FormMessage` bileşimini kullanır. Zod doğrulaması gerektiğinde mevcut resolver katmanı kullanılır.
+
+Kurallar:
+
+- Placeholder label yerine geçmez.
+- Server ve client aynı Zod/domain sözleşmesine göre doğrular; client doğrulaması güvenlik sınırı değildir.
+- Alan hatası `FormMessage` veya alanın hemen altındaki inline metinle gösterilir. Toast tek başına form hatası değildir.
+- Submit durumu Poyraz `Button` üzerindeki `loading`, `disabled` ve `aria-busy` proplarıyla gösterilir.
+- Başarılı, formun dışında etkisi olan işlem toast ile; kullanıcının karar vermesi gereken veya kalıcı bilgi inline `Alert` ile gösterilir.
+
+## Status-to-Badge standardı
+
+Merkezi eşleme `components/system/status-badge.tsx` içindedir.
+
+| Anlam | Örnek status'ler | Badge variant |
+| --- | --- | --- |
+| Başarılı/çalışır | `active`, `accepted`, `completed`, `done`, `paid` | `success` |
+| Süreçte/bilgi | `in_progress`, `sent` | `info` |
+| Bekliyor/dikkat | `pending`, `paused` | `warning` |
+| Plan/taslak | `planning`, `planned`, `todo`, `draft` | `secondary` |
+| Hata/risk | `overdue`, `rejected`, `revoked`, `expired` | `destructive` |
+| Pasif terminal | `cancelled`, `archived` | `outline` |
+
+Renk tek başına anlam taşımaz; badge her zaman Türkçe durum metni içerir.
+
+## Feedback state standardı
+
+`components/system/feedback-state.tsx` yeni sayfaların ortak state bileşimidir.
+
+- Loading: layout'a yakın Poyraz `Skeleton`; kapsayıcıda `aria-busy` ve screen-reader label.
+- Empty: nötr Poyraz `Card`, kısa neden ve mümkünse bir sonraki primary aksiyon.
+- Error: Poyraz destructive `Alert`, kullanıcıya uygun açıklama ve retry aksiyonu.
+- Forbidden: Poyraz warning `Alert`; var olmayan kaynağı açığa çıkarmayacak metin ve güvenli geri dönüş.
+- Toast: kısa ömürlü, sayfalar arası kalıcı olmayan işlem sonucu.
+- Inline Alert: kullanıcının okumadan devam etmemesi gereken, forma veya sayfaya bağlı durum.
+
+## Overlay, confirmation, table ve KPI
+
+- Geri döndürülemez işlem `components/system/destructive-confirmation.tsx` üzerinden açık `DialogTitle`, `DialogDescription`, vazgeç ve destructive onay aksiyonu ile kurulur.
+- Kısa desktop formu `Dialog`, bağlamsal yan panel `Sheet`; küçük ekranda uzun/çok adımlı akış `Drawer` olur. Ekranı kaplayan özel div overlay yazılmaz.
+- Veri listeleri seçim, arama, pagination, loading veya error gerektiriyorsa Poyraz organism `DataTable` kullanır. Basit iki sütunlu statik bilgiler native semantic table kalabilir.
+- Dashboard metrikleri Poyraz `StatsCard` ile kurulur: kısa label, formatlanmış value, isteğe bağlı trend ve tek anlamlı icon. Renk yalnızca trend/durum bilgisini destekler.
+
+## Branding token bridge
+
+Branding servisi eski `--primary` benzeri uygulama tokenları yerine Poyraz v3 sözleşmesini server-side üretir:
+
+- `--poyraz-primary` ve foreground/hover/active/scale rolleri
+- `--poyraz-accent` ve foreground/hover rolleri
+- `--poyraz-ring` ve `--poyraz-focus-ring`
+- `--poyraz-radius-xs` … `--poyraz-radius-xl`
+
+Değerler root `<html style>` içine SSR edilir; bu nedenle ilk render'da varsayılan renkten instance rengine geçiş parlaması oluşmaz. `system` renk modu ilk paint öncesi media query ile `.dark` sınıfına çevrilir ve işletim sistemi değişikliği dinlenir. Poyraz preset kalan surface, status, elevation, density ve motion rollerinin tek kaynağıdır.
+
+Recharts içindeki eski `hsl(var(--...))` ifadeleri geçerli Poyraz CSS renk tokenlarına taşındı.
+
+## Local primitive ve dependency sonucu
+
+Kaldırılan local generic primitive'ler: Button, Card, Checkbox, Dialog, DropdownMenu, Field/Form, Input/Label, Select, Separator, Skeleton, Textarea ve Toast/Toaster. Kullanılmayan eski toast hook'u ve `next-themes` provider'ı da kaldırıldı.
+
+Poyraz'ın kendi dependency ağacında yönettiği `@base-ui/react`, doğrudan Radix paketleri, `radix-ui`, `class-variance-authority`, `shadcn`, ayrıca kullanılmayan `@iconify/react` ve `next-themes` doğrudan Neta dependency listesinden çıkarıldı. Poyraz molecule entrypoint'i dinamik Mermaid importunu build sırasında çözdüğü için package'ın optional peer'i `mermaid` açık dependency olarak eklendi. Sonuçta doğrudan dependency sayısı net 14, pnpm kurulum ağacı yaklaşık 112 paket azaldı.
+
+## Erişilebilirlik foundation kuralları
+
+- Heading hiyerarşisi semantik component proplarıyla korunur.
+- Icon-only aksiyonlar görünür label yoksa `aria-label`; bağlam açıklaması gerekiyorsa Tooltip kullanır.
+- Dialog/Sheet/Drawer title ve description olmadan yayınlanmaz.
+- Focus ring utility ile kapatılmaz; Poyraz focus tokenı branding primary rengine bağlıdır.
+- Loading ve disabled görsel class taklidiyle değil component proplarıyla kurulur.
+- Global reduced-motion kuralı ve component seviyesinde `motion-reduce` korunur.
+- Durumlar renk yanında metin ve gerektiğinde icon ile anlatılır.
+
+Bu faz foundation sözleşmesini doğrular. Legacy feature sayfalarının tamamına uygulanması ilgili Faz 5–6 dikey dilimlerinin kalite kapısıdır.
+
+## Doğrulama
+
+```bash
+pnpm phase4:ui-boundary
+pnpm typecheck
+./node_modules/.bin/eslint app/layout.tsx components/layout components/system components/auth components/error-toaster.tsx components/ui/offline-indicator.tsx components/ui/pending-link.tsx components/ui/pending-submit-button.tsx app/login/page.tsx app/register/page.tsx 'app/invite/[token]/page.tsx' server/branding/service.ts scripts/phase4-ui-boundary.mjs
+pnpm phase3:storage-smoke
+pnpm phase1:auth-smoke
+pnpm build
+git diff --check
+```
+
+Boundary testi v3 major sürümünü, preset importunu, Sidebar bileşimini, package subpath importlarını, izin verilen local UI dosyalarını ve kaldırılan duplicate UI bağımlılıklarını doğrular.
+
+Foundation hedefli ESLint kontrolü temizdir. Repo genelindeki `pnpm lint`, henüz Faz 5–7'de taşınacak legacy feature/API dosyalarındaki mevcut `no-explicit-any`, `set-state-in-effect` ve benzeri borçlar nedeniyle bu fazda global kalite kapısı olarak kapatılmadı; master plandaki genel lint maddesi bu nedenle işaretlenmedi.