# 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)

```txt
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

```bash
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:

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

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

### 3.4 Hemen kullanim

```tsx
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:

```tsx
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:

```tsx
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.