poyraz-portfolio/docs/usage-guide.md

Poyraz UI - Usage Guide (Detayli)

Bu dokuman, d:/Poyraz/kodlama/poyraz-ui reposunun guncel kaynak kodu uzerinden hazirlandi. Hedef: UI kitin hem kullanici (consumer) tarafini hem de bu repoyu gelistirme tarafini tek yerde toplamak.

Versiyon referansi: 2.0.1

---

1) Proje Ozeti

Poyraz UI, React tabanli, Tailwind CSS v4 ile calisan, atomic design yaklasimi kullanan bir UI kit. Repo iki ana amaca hizmet ediyor:

1. npm paketi olarak dagitilan UI kutuphanesi (src, components/ui, dist)
2. Next.js App Router ile yazilmis canli dokumantasyon sitesi (app)

Temel karakter:

• clean border odakli, minimum shadow
• rounded-sm kullanimina dayali yalin gorunum
• semantic token sistemi (--poyraz-*)
• dark mode uyumlu
• atoms -> molecules -> organisms katmanlamasi

---

2) Dizin Yapisi (Gercek Kod Yapisi)

poyraz-ui/
|- app/                    # Next.js docs sitesi
|  |- docs/                # component/template dokumantasyon sayfalari
|  |- globals.css          # docs sitesi global css + dark override
|  |- layout.tsx           # next-themes + Toaster entegrasyonu
|  `- page.tsx             # landing/showcase
|- bin/
|  `- cli.mjs              # npx poyraz-ui init
|- components/
|  |- ui/
|  |  |- atoms/            # 17 atom dosyasi
|  |  |- molecules/        # 22 molecule dosyasi
|  |  `- organisms/        # 5 organism dosyasi
|  |- theme-provider.tsx   # docs sitesi next-themes wrapper
|  `- theme-toggle.tsx     # docs sitesi toggle
|- lib/
|  `- navigation.ts        # docs nav/registry merkezi config
|- src/
|  |- index.ts             # ana export
|  |- atoms/index.ts       # atom export map
|  |- molecules/index.ts   # molecule export map
|  |- organisms/index.ts   # organism export map
|  |- themes/index.ts      # poyrazLightTheme / poyrazDarkTheme
|  |- preset.css           # token layer + @theme bridge
|  `- utils.ts             # cn()
|- dist/                   # tsup output (publish edilen paket)
|- tsup.config.ts          # 5 entry point, esm+cjs, dts
`- package.json

---

3) Kullanici Tarafi Kurulum (Consumer App)

3.1 Paket kurulumu

pnpm add poyraz-ui
# veya
npm install poyraz-ui
# veya
yarn add poyraz-ui

3.2 Zorunlu peer dependencies

• react >= 18
• react-dom >= 18
• tailwindcss >= 4

Opsiyonel peer dependencies:

• react-hook-form, @hookform/resolvers, zod (Form molecule icin)
• reactive-switcher (hazir theme objectleriyle dinamik tema gecisi icin)

3.3 CSS import (kritik)

Root global stylesheet dosyana ekle:

@import "tailwindcss";
@import "poyraz-ui/preset.css";

preset.css olmadan renk/font tokenlari dogru resolve edilmez.

3.4 Hemen kullanim

import { Button, Card, CardContent } from "poyraz-ui/atoms";

export function Demo() {
  return (
    <Card>
      <CardContent className="p-4">
        <Button>Merhaba</Button>
      </CardContent>
    </Card>
  );
}

---

4) Import Stratejisi ve Entry Pointler

Paket 5 entry point sunuyor:

• poyraz-ui
• poyraz-ui/atoms
• poyraz-ui/molecules
• poyraz-ui/organisms
• poyraz-ui/themes

Onerilen yaklasim:

• Uretim projelerinde alt path importlarini kullan (/atoms, /molecules, /organisms)
• Gecis surecinde hiz icin ana barrel (poyraz-ui) kullanabilirsin

Ornek:

import { Button, Badge } from "poyraz-ui/atoms";
import { Dialog } from "poyraz-ui/molecules";
import { Navbar } from "poyraz-ui/organisms";
import { poyrazLightTheme, poyrazDarkTheme } from "poyraz-ui/themes";

---

5) Tema Sistemi (En Onemli Altyapi)

Tema zinciri su sekilde calisiyor:

1. Component classlari bg-background, text-foreground, border-border gibi semantic utility kullaniyor.
2. src/preset.css, @theme ile bunlari --color-* tokenlarina bagliyor.
3. --color-* tokenlari, var(--poyraz-*, fallback) ile semantic CSS variable'a mapleniyor.
4. Sen --poyraz-* degistirdiginde tum kit yeni temaya gecer.

5.1 Token katmanlari

• Base semantic variables: --poyraz-background, --poyraz-foreground, --poyraz-primary, ...
• Tailwind v4 bridge: --color-background, --color-foreground, ...
• Utility kullanim: bg-background, text-muted-foreground, ...

5.2 Dark mode (class tabanli)

Docs sitesi next-themes kullaniyor ve html.dark altinda --poyraz-* override ediyor (app/globals.css).

5.3 reactive-switcher entegrasyonu

src/themes/index.ts icinde hazir theme objectleri var:

• poyrazLightTheme
• poyrazDarkTheme
• poyrazThemes

Ornek:

import { ThemeProvider } from "reactive-switcher";
import { poyrazThemes } from "poyraz-ui/themes";

export function AppTheme({ children }: { children: React.ReactNode }) {
  return <ThemeProvider themes={poyrazThemes}>{children}</ThemeProvider>;
}

---

6) Component Katalogu

Bu bolum src/*/index.ts export maplerine gore hazirlandi.

6.1 Atoms (17 component dosyasi)

• Avatar
• Badge
• Button
• Card
• Checkbox
• Input
• Label
• Logo
• Radio Group
• Separator
• Skeleton
• Switch
• Textarea
• Typography
• Form Fields (NumberInput, SearchInput, PhoneInput, PasswordInput, UrlInput)
• BG Patterns (PatternDots, PatternGrid, PatternLines, PatternDiagonal, PatternCross, PatternCheckerboard, PatternDiamond, PatternZigzag, PatternDashedGrid, PatternRadial)
• ScrollArea

6.2 Molecules (22 component dosyasi)

Core molecules:

• Accordion
• Alert
• Autocomplete
• Breadcrumb
• Calendar
• Command Palette
• Date Picker
• Dialog
• Drawer
• Dropdown Menu
• Form
• Hover Card
• Modal
• Pagination
• Popover
• Select
• Sheet
• Sonner (Toaster, toast)
• Tabs
• Tooltip

Template molecules (card-templates):

• ArticleCard
• ImageCard
• NewsCard
• StatsCard
• TestimonialCard
• PricingCard
• ProductCard

6.3 Organisms (5 component dosyasi)

• Navbar
• Sidebar
• Footer
• AnnouncementBar
• DataTable

---

7) Hazir Template Sayfalari (Docs Icinde)

app/docs/templates altinda 4 kopyalanabilir sayfa semasi var:

• Hero
• Pricing
• Dashboard
• Auth

Onemli not:

• Bunlar npm paketi icinde "template component" olarak export edilmiyor.
• Kaynagi kopyalayip projenin ihtiyacina gore duzenleme modeli kullaniliyor.

---

8) Dokumantasyon Sitesi Mimarisi

app/docs altinda:

• toplam 53 adet page.tsx
• atoms: 18
• molecules: 22
• organisms: 6
• templates: 5

Merkezi nav/registry:

• lib/navigation.ts
• sidebardaki kategori sayilari ve slug donusumu burada yonetiliyor (toSlug)

---

9) CLI: npx poyraz-ui init

CLI (bin/cli.mjs) su adimlari yapar:

1. CSS dosyasini otomatik tespit eder (app/globals.css, src/app/globals.css vb.)
2. @import "poyraz-ui/preset.css"; satirini ekler
3. Opsiyonel olarak reactive-switcher tema dosyasi scaffold eder
4. Layout icin ThemeProvider snippet'i gosterir

Manual kurulum yerine hizli onboarding icin ideal.

---

10) Build, Bundle ve Publish Akisi

10.1 Scriptler

• pnpm dev: docs sitesi
• pnpm build: library + docs production build
• pnpm build:lib: sadece library (tsup)
• pnpm start: next production serve
• pnpm prepublishOnly: publish oncesi otomatik build:lib

10.2 tsup ozeti

tsup.config.ts:

• 5 entry point uretir (index, atoms/index, molecules/index, organisms/index, themes/index)
• format: esm + cjs
• dts: true
• splitting + treeshake + clean
• build sonrasi dist dosyalarina "use client" directive inject eder

10.3 package export haritasi

package.json exports alani:

• alt path importlarini hem ESM hem CJS ile aciklar
• ./preset.css dogrudan src/preset.css'e yonlenir

---

11) Bu Repoda Yeni Component Ekleme Rehberi

11.1 Kod ekleme

1. Component dosyasini components/ui/<layer>/ altina ekle
2. Gerekirse type exportlarini component dosyasinda tanimla

11.2 Export haritasi

3. src/<layer>/index.ts icine export satirlarini ekle
4. Gerekliyse src/index.ts ana barrel kontrol et

11.3 Docs entegrasyonu

5. app/docs/<layer>/<component>/page.tsx olustur
6. Kategori index sayfasina link ekle (app/docs/<layer>/page.tsx)
7. lib/navigation.ts icindeki componentRegistry listesine ekle

11.4 Dogrulama

8. pnpm build:lib
9. pnpm dev ile docs sayfasini ve importlarini test et

---

12) Sik Kullanilan Kullanim Patternleri

12.1 Form stack

• Atoms: Input, Label, Checkbox, Button
• Molecules: Form, Select, DatePicker, Autocomplete

12.2 Overlay stack

• Dialog, Modal, Drawer, Sheet, Popover, Tooltip
• Her biri Radix/Vaul primitive uzerinden geldigi icin a11y ve keyboard destegi yuksek

12.3 Navigation stack

• Navbar (desktop + mobile panel)
• Sidebar (collapsible/floating/mini varyantlar)
• Footer (layout varyantlari)

12.4 Data stack

• DataTable + Badge + Pagination
• dashboard tarzinda StatsCard, Card, Avatar ile birlikte kullaniliyor

---

13) Bilinen Durumlar / Dikkat Noktalari

1. Mermaid dokumantasyon sayfasi var (app/docs/molecules/mermaid/page.tsx) ancak su anda src/molecules/index.ts icinden export edilmiyor.
2. componentRegistry molecules listesi ile molecules landing page listesi tam birebir degil (sidebar listesinde Mermaid yok).
3. Template sayfalari (Hero/Pricing/Dashboard/Auth) paket exportu degil; kopyala-ozellestir modeli.
4. Rehber ve README metinlerinde bilesen sayilari bazen farkli geciyor; son karar noktasi her zaman src/*/index.ts export mapidir.

---

14) Hizli Referans

14.1 Consumer app checklist

1. poyraz-ui paketini kur
2. @import "poyraz-ui/preset.css"; ekle
3. poyraz-ui/atoms veya poyraz-ui/molecules uzerinden import et
4. Tema gerekiyorsa --poyraz-* override et veya poyraz-ui/themes kullan

14.2 Repo contributor checklist

1. component dosyasi ekle (components/ui)
2. export map guncelle (src/*/index.ts)
3. docs page ekle (app/docs/...)
4. navigation registry guncelle (lib/navigation.ts)
5. pnpm build:lib ve pnpm dev ile dogrula

---

15) Ek Kaynaklar

• Paket genel tanitim: README.md
• Genis API referansi: COMPONENTS.md
• Theme switcher notlari: theme-switcher.md
• Kurulum sayfasi referansi: app/docs/installation/page.tsx

---

Bu dokuman "proje ici operasyonel guide" amaciyla yazildi. Paketin public-facing README'sini sade tutup, bu dosyayi teknik detay merkezi olarak kullanman tavsiye edilir.