From 33db400ef320d81a1518b8178a704d421a862ac5 Mon Sep 17 00:00:00 2001 From: poyrazavsever Date: Tue, 14 Jul 2026 09:41:15 +0300 Subject: [PATCH] feat: updated baseline and roadmap --- docs/poyraz-ui-v3-migration-plan.md | 380 ++++++++++++++++++++++++++++ pnpm-workspace.yaml | 12 +- 2 files changed, 386 insertions(+), 6 deletions(-) create mode 100644 docs/poyraz-ui-v3-migration-plan.md diff --git a/docs/poyraz-ui-v3-migration-plan.md b/docs/poyraz-ui-v3-migration-plan.md new file mode 100644 index 0000000..b419cb2 --- /dev/null +++ b/docs/poyraz-ui-v3-migration-plan.md @@ -0,0 +1,380 @@ +# Poyraz Portfolio — poyraz-ui v3 Migration Plan + +Bu planın amacı `poyraz-portfolio` projesini `poyraz-ui@2.x` kullanımından `poyraz-ui@3.0.0` kullanımına, mevcut sayfa düzenini ve portfolio kimliğini bozmadan geçirmek. + +Öncelik sırası: + +1. Önce paket geçişi ve build/type güvenliği. +2. Sonra mevcut layout davranışını koruma. +3. En son görsel polish ve yeni v3 tasarım yeteneklerini kontrollü ekleme. + +> Not: Bu dokümandaki tasarım iyileştirmeleri v3 geçişinden sonra ayrı küçük fazlara bölünebilir. İlk migration hedefi “çalışan ve görsel olarak kırılmamış portfolio”dur. + +--- + +## Mevcut Durum Özeti + +- Proje Next.js `16.1.6`, React `19.2.3`, Tailwind CSS v4 kullanıyor. +- `poyraz-ui` şu anda npm paketi olarak `^2.0.1` kullanılıyor. +- `app/globals.css` içinde `@import "poyraz-ui/preset.css";` zaten mevcut. +- Componentler local registry copy olarak değil, doğrudan paket exportları üzerinden kullanılıyor. +- Aktif poyraz-ui importları şu alanlarda: + - `poyraz-ui/atoms` + - `poyraz-ui/molecules` + - `poyraz-ui/organisms` + - `poyraz-ui/themes` + +Migration için avantajlı nokta: v3 tarafında kullanılan temel exportların çoğu korunmuş görünüyor. Bu nedenle geçişin büyük kısmı dependency bump + görsel/behavior doğrulama şeklinde ilerleyebilir. + +--- + +## Risk Haritası + +### Yüksek Öncelikli Riskler + +- [ ] `poyraz-ui@3.0.0` Node `>=22` istediği için local/Vercel Node versiyonu doğrulanmalı. +- [ ] `pnpm-lock.yaml` v3 dependency graph ile temiz güncellenmeli. +- [ ] `poyraz-ui/preset.css` v3 tokenları mevcut layout renklerini beklenmedik şekilde değiştirebilir. +- [ ] Card template componentleri (`NewsCard`, `ImageCard`, `ArticleCard`, `TestimonialCard`) v3’te daha modern/glassy defaultlara sahip olduğu için mevcut compact tasarımda kayma oluşturabilir. +- [ ] `CommandPalette`, `Sheet`, `Modal`, `Select`, `DropdownMenu` gibi Radix tabanlı componentlerde overlay, focus ve portal davranışı görsel olarak kontrol edilmeli. + +### Orta Öncelikli Riskler + +- [ ] `Typography` variant ölçüleri v3 tokenlarıyla farklılaşabilir. +- [ ] `Badge`, `Card`, `Button`, `Input` default radius/spacing değerleri mevcut `rounded-sm` class override’larıyla büyük ölçüde korunacak ama sayfa bazlı kontrol edilmeli. +- [ ] `AnnouncementBar` v3 animasyon ve spacing’i `AppShell` içinde ekstra yükseklik/boşluk yaratabilir. +- [ ] Mobile navbar sheet davranışı v3 overlay/close butonu nedeniyle farklı görünebilir. + +### Düşük Öncelikli Riskler + +- [ ] `src/lib/themes.ts` aktif kullanılmıyor; v3 theme exportlarıyla uyumlu kalması yeterli. +- [ ] `reactive-switcher` şu an kullanılmıyor; dark mode geçişi v3 migration kapsamına alınmamalı. +- [ ] Portfolio tasarım polish istekleri migration sonrasına bırakılmalı. + +--- + +## Faz 0 — Hazırlık ve Baseline + +Amaç: Değişiklik yapmadan önce projenin mevcut sağlığını ve migration başlangıç noktasını netleştirmek. + +### Görevler + +- [ ] `git status --short` ile mevcut dirty dosyaları not al. +- [ ] Mevcut kullanıcı değişikliklerine dokunma. +- [ ] `pnpm-workspace.yaml` içinde önceden yapılmış `allowBuilds` değişikliğini kullanıcı değişikliği olarak koru. +- [ ] Paket yöneticisi versiyonunu doğrula. +- [ ] Node versiyonunu doğrula. +- [ ] `pnpm lint` çalıştır. +- [ ] `pnpm build` çalıştır. +- [ ] Varsa mevcut lint/build uyarılarını migration öncesi baseline olarak not al. + +### Kabul Kriterleri + +- [ ] Migration öncesi proje durumu belgelenmiş olmalı. +- [ ] Mevcut build hatası varsa v3 geçişinden bağımsız olduğu anlaşılmalı. +- [ ] Kullanıcı değişiklikleri ezilmemeli. + +--- + +## Faz 1 — Dependency Geçişi + +Amaç: `poyraz-ui` paketini v3’e almak ve lockfile’ı temiz güncellemek. + +### Görevler + +- [ ] `package.json` içindeki `poyraz-ui` sürümünü `^3.0.0` yap. +- [ ] `pnpm install` ile `pnpm-lock.yaml` güncelle. +- [ ] `pnpm-lock.yaml` içinde `poyraz-ui@3.0.0` çözümlendiğini doğrula. +- [ ] `package.json` içine gerekirse Node engine eklemeyi değerlendir: + - `node >=22` + - Bu değişiklik Vercel deploy ile uyumlu olmalı. +- [ ] Vercel tarafında Node 22 kullanılacağından emin olmak için proje ayarı/notu ekle. + +### Kabul Kriterleri + +- [ ] `package.json` v3 dependency kullanıyor. +- [ ] Lockfile v3’e güncellendi. +- [ ] Paket kurulumu temiz tamamlandı. +- [ ] Kullanılmayan geçici paket/alias eklenmedi. + +--- + +## Faz 2 — Import ve API Uyumluluk Kontrolü + +Amaç: v3 sonrası TypeScript/Next build seviyesinde kırılan import veya prop kullanımlarını düzeltmek. + +### Kontrol Edilecek Import Grupları + +- [ ] `poyraz-ui/atoms` + - `Avatar` + - `Badge` + - `Button` + - `Card` + - `Input` + - `Separator` + - `Skeleton` + - `Typography` +- [ ] `poyraz-ui/molecules` + - `ArticleCard` + - `CommandPalette` + - `DropdownMenu` + - `ImageCard` + - `Modal` + - `NewsCard` + - `Pagination` + - `Select` + - `Sheet` + - `TestimonialCard` +- [ ] `poyraz-ui/organisms` + - `AnnouncementBar` +- [ ] `poyraz-ui/themes` + - `poyrazLightTheme` + - `poyrazDarkTheme` + - `poyrazThemes` + +### Görevler + +- [ ] `rg "poyraz-ui"` ile tüm kullanım noktalarını tekrar listele. +- [ ] `pnpm lint` çalıştır. +- [ ] `pnpm build` çalıştır. +- [ ] Kırılan import varsa en küçük değişiklikle düzelt. +- [ ] Kırılan prop varsa component davranışını koruyarak v3 API’ya uyarla. +- [ ] Gereksiz refactor yapma. + +### Kabul Kriterleri + +- [ ] Tüm importlar v3 exportlarıyla uyumlu. +- [ ] Type/build hatası kalmadı. +- [ ] Sayfa düzenini etkileyecek gereksiz class değişikliği yapılmadı. + +--- + +## Faz 3 — Global CSS ve Token Uyumluluğu + +Amaç: v3 preset tokenlarının portfolio genel görünümünü bozmadığını doğrulamak. + +### Görevler + +- [ ] `app/globals.css` içindeki import sırasını koru: + - `@import "tailwindcss";` + - `@import "poyraz-ui/preset.css";` +- [ ] Custom utility’leri kontrol et: + - `animate-marquee` + - `pause-on-hover` +- [ ] `bg-background`, `text-foreground`, `border-border`, `muted-foreground` gibi semantic tokenların v3 karşılığını görsel olarak kontrol et. +- [ ] Light mode temel kontrastı kontrol et. +- [ ] Dark mode aktif değilse migration kapsamında dark mode ekleme. + +### Kabul Kriterleri + +- [ ] Global CSS minimal kaldı. +- [ ] Tailwind v4 compile sorunu yok. +- [ ] Semantic tokenlar sayfa genelinde okunabilir. + +--- + +## Faz 4 — Layout ve Shell Doğrulaması + +Amaç: Site iskeletini korumak. + +### Kontrol Edilecek Dosyalar + +- [ ] `app/[locale]/layout.tsx` +- [ ] `components/app-shell.tsx` +- [ ] `components/site-navbar.tsx` +- [ ] `components/search-command.tsx` +- [ ] `components/language-switcher.tsx` + +### Görevler + +- [ ] Locale layout render zincirini kontrol et. +- [ ] `AppShell` max width ve spacing değerlerinin değişmediğini doğrula. +- [ ] `AnnouncementBar` yüksekliği ve border davranışını kontrol et. +- [ ] Desktop navbar hizasını kontrol et. +- [ ] Mobile navbar sheet aç/kapat davranışını kontrol et. +- [ ] Search command palette aç/kapat davranışını kontrol et. +- [ ] Cmd/Ctrl + K shortcut davranışını doğrula. + +### Kabul Kriterleri + +- [ ] Navbar layout bozulmadı. +- [ ] Mobile menü çalışıyor. +- [ ] Search command çalışıyor. +- [ ] Announcement bar sayfa içeriğini itip bozmadı. + +--- + +## Faz 5 — Sayfa Bazlı Görsel Regression Kontrolü + +Amaç: Mevcut portfolio düzenini v3 sonrası sayfa sayfa korumak. + +### Ana Sayfa + +- [ ] `HomeHero` kart yerleşimi korunuyor. +- [ ] `NewsCard` yükseklikleri düzgün. +- [ ] Hero görsel alanı taşmıyor. +- [ ] References marquee çalışıyor. +- [ ] Sponsor kartları hizalı. + +### About + +- [ ] Eğitim ve deneyim kartları compact kalıyor. +- [ ] Sertifika sheet açılıyor. +- [ ] Bookmark sheet açılıyor. +- [ ] Referans ve gönüllülük link kartları hizalı. + +### Blog + +- [ ] Kategori badge’leri doğru görünüyor. +- [ ] Search input focus state rahatsız etmiyor. +- [ ] `ArticleCard` grid yüksekliği dengeli. +- [ ] Pagination active state düzgün. +- [ ] Empty state bozulmadı. + +### Blog Detail + +- [ ] Markdown typography okunabilir. +- [ ] Code block görünümü korunuyor. +- [ ] Mermaid block loading/error kartları düzgün. +- [ ] TOC paneli taşmıyor. +- [ ] Progress bar çalışıyor. + +### Projects + +- [ ] `ImageCard` square grid düzenini bozmuyor. +- [ ] NPM/GitHub kartları aynı yükseklik mantığında kalıyor. +- [ ] Badge ve icon spacingleri düzgün. + +### Content + +- [ ] YouTube cardları düzgün. +- [ ] PDF preview kartları düzgün. +- [ ] PDF modal açılıyor. +- [ ] Prev/Next buttonları çalışıyor. + +### Links + +- [ ] Profile card rounded/glass görünüm korunuyor. +- [ ] `Select` ve `Input` aynı satırda düzgün. +- [ ] Link kartları hover’da layout shift yapmıyor. +- [ ] Mobile layout taşmıyor. + +### Contact / Gallery / Volunteer / References + +- [ ] Kartlar compact düzeni koruyor. +- [ ] Linkler çalışıyor. +- [ ] Galeri modal/preview davranışı korunuyor. + +### Kabul Kriterleri + +- [ ] Kritik sayfalarda layout kırığı yok. +- [ ] Horizontal overflow yok. +- [ ] Component default değişimleri mevcut tasarımı bozmadı. + +--- + +## Faz 6 — Davranış ve Etkileşim Testleri + +Amaç: Sadece build almakla kalmayıp interaktif alanları doğrulamak. + +### Manuel Test Listesi + +- [ ] Navbar linkleri locale-aware route ediyor. +- [ ] Language switcher route’u bozmadan locale değiştiriyor. +- [ ] Social dropdown açılıyor/kapanıyor. +- [ ] Mobile sheet açılıyor/kapanıyor. +- [ ] Search palette: + - [ ] Click ile açılıyor. + - [ ] Cmd/Ctrl + K ile açılıyor. + - [ ] Arama filtreliyor. + - [ ] Internal linke gidiyor. + - [ ] External link yeni sekme açıyor. +- [ ] About sheetleri açılıyor/kapanıyor. +- [ ] Atatürk widget modal açılıyor. +- [ ] PDF modal açılıyor. +- [ ] PDF modal içinde prev/next çalışıyor. +- [ ] Blog pagination linkleri doğru query üretir. + +### Kabul Kriterleri + +- [ ] Temel kullanıcı akışlarında regression yok. +- [ ] Focus trap/overlay kilitlenmesi yok. +- [ ] Body scroll lock sorun çıkarmıyor. + +--- + +## Faz 7 — Build, Lint ve Release Readiness + +Amaç: Deploy edilebilir temiz durum elde etmek. + +### Görevler + +- [ ] `pnpm lint` +- [ ] `pnpm build` +- [ ] `git diff --check` +- [ ] `git status --short` +- [ ] Build sırasında Next warningleri not al. +- [ ] Vercel Node 22 gereksinimi için deploy notu çıkar. + +### Kabul Kriterleri + +- [ ] Build başarılı. +- [ ] Lint başarılı ya da mevcut baseline dışı yeni hata yok. +- [ ] Diff sadece migration kapsamındaki dosyalardan oluşuyor. + +--- + +## Faz 8 — Commit ve Handoff + +Amaç: Migration değişikliklerini okunabilir şekilde teslim etmek. + +### Önerilen Commit Gruplaması + +1. `docs: plan poyraz-ui v3 migration` + - Sadece bu plan dosyası. + +2. `chore: migrate portfolio to poyraz-ui v3` + - `package.json` + - `pnpm-lock.yaml` + - Gerekirse `pnpm-workspace.yaml` + - Gerekirse küçük API uyumluluk düzeltmeleri. + +3. Eğer görsel uyumluluk düzeltmesi gerekiyorsa: + - `fix: preserve portfolio layout with poyraz-ui v3` + +### Kabul Kriterleri + +- [ ] Commitler anlamlı ve review edilebilir. +- [ ] Kullanıcı değişiklikleri commit kapsamına yanlışlıkla alınmadı. +- [ ] Final notta test sonuçları açıkça yazıldı. + +--- + +## Migration Sonrasına Bırakılacak Tasarım İşleri + +Bu işler v3 geçişinden sonra ayrıca ele alınmalı: + +- [ ] Portfolio genelini daha glassy/soft v3 tarzına yaklaştırma. +- [ ] Button hover animasyonlarını portfolio CTA’larına uygulama. +- [ ] Typography text effectlerini hero/blog başlıklarında kullanma. +- [ ] Card variantlarını sayfa bazlı standardize etme. +- [ ] Dark mode/theme switcher ekleme. +- [ ] Links sayfasını daha modern micro-landing görünümüne taşıma. +- [ ] Navbar ve command palette görsel polish. +- [ ] Blog kartlarında daha zengin image/metadata layout. + +--- + +## İlk Uygulama Sırası + +Migration’a başlarken uygulanacak pratik sıra: + +1. Faz 0 baseline. +2. Faz 1 dependency geçişi. +3. Faz 2 import/API kontrolü. +4. Faz 7 build/lint doğrulaması. +5. Faz 4 ve Faz 5 hızlı görsel kontrol. +6. Gerekiyorsa küçük düzeltmeler. +7. Commit. + +Bu sıra major geçişi hızlı tamamlamaya, tasarım detaylarını ise yayın sonrası küçük ve güvenli iterasyonlara bırakmaya uygundur. diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 537e4a2..2c74ad5 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -10,9 +10,9 @@ ignoredBuiltDependencies: - unrs-resolver allowBuilds: - '@parcel/watcher': set this to true or false - '@swc/core': set this to true or false - electron: set this to true or false - puppeteer: set this to true or false - sharp: set this to true or false - unrs-resolver: set this to true or false + '@parcel/watcher': true + '@swc/core': true + electron: true + puppeteer: true + sharp: true + unrs-resolver: true