From ffc6c65db1bb08ea19c34a5e1961a36dc9ef02fe Mon Sep 17 00:00:00 2001 From: Poyraz Avsever Date: Mon, 9 Mar 2026 10:25:39 +0300 Subject: [PATCH] feat: integrate poyraz-ui and reactive-switcher for theme management - Added poyraz-ui preset CSS import to globals.css for styling. - Created theme-switcher.md documentation for reactive-switcher usage. - Added usage-guide.md for comprehensive Poyraz UI instructions. - Updated package.json to include reactive-switcher as a dependency. - Modified pnpm-lock.yaml to reflect the addition of reactive-switcher. - Established themes.ts to export Poyraz UI themes for use in the application. --- app/globals.css | 1 + docs/theme-switcher.md | 934 +++++++++++++++++++++++++++++++++++++++++ docs/usage-guide.md | 413 ++++++++++++++++++ package.json | 3 +- pnpm-lock.yaml | 14 + src/lib/themes.ts | 15 + 6 files changed, 1379 insertions(+), 1 deletion(-) create mode 100644 docs/theme-switcher.md create mode 100644 docs/usage-guide.md create mode 100644 src/lib/themes.ts diff --git a/app/globals.css b/app/globals.css index f1d8c73..4a15d17 100644 --- a/app/globals.css +++ b/app/globals.css @@ -1 +1,2 @@ @import "tailwindcss"; +@import "poyraz-ui/preset.css"; diff --git a/docs/theme-switcher.md b/docs/theme-switcher.md new file mode 100644 index 0000000..be13ffe --- /dev/null +++ b/docs/theme-switcher.md @@ -0,0 +1,934 @@ +

+ Reactive Switcher Logo +

+ +

Reactive Switcher

+ +

+ Type-safe, modular, and instant theme switching for React & Tailwind CSS v4 +

+ +

+ + npm version + + + License: MIT + + + TypeScript + + + Bundle Size + +

+ +

+ Features • + Installation • + Quick Start • + API • + Demo • + Türkçe +

+ +--- + +## ✨ Features + +- 🚀 **Zero Runtime Overhead** - Uses CSS variables for instant theme switching +- 📦 **TypeScript First** - Full type safety with autocomplete support +- 🎨 **Tailwind CSS v4 Ready** - Seamless integration with the new engine +- 💾 **Persistent Themes** - LocalStorage support out of the box +- 🌙 **System Theme Detection** - Respects `prefers-color-scheme` +- ⚡ **No Flash** - SSR compatible with hydration flash prevention +- 🎯 **Scoped Theming** - Apply different themes to different parts of your app +- 🧩 **Ready-to-use Components** - `ThemeSwitcher` and `ThemeToggle` included + +--- + +## 📦 Installation + +```bash +npm install reactive-switcher +# or +pnpm add reactive-switcher +# or +yarn add reactive-switcher +``` + +--- + +## 🚀 Quick Start + +### 1. Define Your Themes + +```typescript +// themes.ts +import { ThemesConfig } from "reactive-switcher"; + +export const themes: ThemesConfig = { + light: { + name: "light", + type: "light", + colors: { + background: "#ffffff", + foreground: "#0f172a", + primary: { + DEFAULT: "#3b82f6", + foreground: "#ffffff", + 50: "#eff6ff", + 500: "#3b82f6", + 600: "#2563eb", + }, + secondary: { + DEFAULT: "#64748b", + foreground: "#ffffff", + }, + surface: { + 50: "#f8fafc", + 100: "#f1f5f9", + 200: "#e2e8f0", + }, + }, + }, + dark: { + name: "dark", + type: "dark", + colors: { + background: "#020617", + foreground: "#f8fafc", + primary: { + DEFAULT: "#60a5fa", + foreground: "#0f172a", + }, + secondary: { + DEFAULT: "#94a3b8", + foreground: "#0f172a", + }, + surface: { + 50: "#0f172a", + 100: "#1e293b", + 200: "#334155", + }, + }, + }, +}; +``` + +### 2. Wrap Your App with ThemeProvider + +```tsx +// app/layout.tsx (Next.js) +import { ThemeProvider } from "reactive-switcher"; +import { themes } from "./themes"; + +export default function RootLayout({ children }) { + return ( + + + + {children} + + + + ); +} +``` + +### 3. Use the Theme + +```tsx +"use client"; +import { useTheme, ThemeToggle } from "reactive-switcher"; + +export function Header() { + const { theme, setTheme, toggleTheme } = useTheme(); + + return ( +
+

Current Theme: {theme}

+ + {/* Ready-to-use toggle */} + + + {/* Or manual control */} + + +
+ ); +} +``` + +### 4. Configure Tailwind CSS v4 + +```css +/* globals.css */ +@import "tailwindcss"; + +@theme { + --color-background: var(--color-background); + --color-foreground: var(--color-foreground); + --color-primary: var(--color-primary-DEFAULT); + --color-primary-foreground: var(--color-primary-foreground); + --color-secondary: var(--color-secondary-DEFAULT); + --color-surface-50: var(--color-surface-50); + --color-surface-100: var(--color-surface-100); + --color-surface-200: var(--color-surface-200); +} + +@layer base { + body { + background-color: var(--color-background); + color: var(--color-foreground); + transition: background-color 0.3s, color 0.3s; + } +} +``` + +--- + +## 📖 API Reference + +### ThemeProvider Props + +| Prop | Type | Default | Description | +| --------------- | ------------------------- | ---------------------------- | ------------------------------- | +| `themes` | `ThemesConfig` | **required** | Theme configurations object | +| `defaultTheme` | `string` | `"light"` | Initial theme name | +| `enableStorage` | `boolean` | `true` | Persist theme to localStorage | +| `storageKey` | `string` | `"reactive-switcher-theme"` | localStorage key | +| `enableSystem` | `boolean` | `true` | Detect system color scheme | +| `selector` | `string` | `":root"` | CSS selector for scoped theming | +| `styleId` | `string` | `"reactive-switcher-styles"` | Style tag ID | +| `attribute` | `"class" \| "data-theme"` | `"class"` | HTML attribute for theme | + +### useTheme() Hook + +```typescript +const { + theme, // Current theme name (string) + resolvedTheme, // Actual theme (resolves "system") + setTheme, // (name: string) => void + toggleTheme, // () => void - Cycle through themes + themes, // Available theme names (string[]) + systemTheme, // System preference ("light" | "dark") +} = useTheme(); +``` + +### Built-in Components + +```tsx +import { ThemeSwitcher, ThemeToggle } from "reactive-switcher"; + +// Dropdown/Button switcher with multiple variants + // Side-by-side buttons + // Dropdown menu + // Toggle button + +// Simple two-theme toggle + +``` + +--- + +## 🎯 Advanced Usage + +### Scoped Theming + +Apply different themes to different parts of your app: + +```tsx +import { ThemeProvider } from "reactive-switcher"; +import { themes } from "./themes"; + +function App() { + return ( + +
Main content with light theme
+ + {/* Scoped dark theme section */} + +
This section has its own theme!
+ + + ); +} +``` + +### Custom Color Palettes + +Define nested color tokens: + +```typescript +const themes: ThemesConfig = { + ocean: { + name: "ocean", + type: "dark", + colors: { + background: "#042f2e", + foreground: "#ccfbf1", + primary: { + DEFAULT: "#2dd4bf", + foreground: "#042f2e", + 50: "#042f2e", + 100: "#115e59", + 200: "#0f766e", + // ... more shades + }, + accent: { + DEFAULT: "#facc15", + foreground: "#422006", + }, + }, + }, +}; +``` + +--- + +## 🌐 Demo + +Check out the live demo: [reactive-switcher.vercel.app](https://reactive-switcher.vercel.app) + +--- + +## 🤝 Contributing + +Contributions are welcome! Please feel free to submit a Pull Request. + +1. Fork the repository +2. Create your feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add some amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +--- + +## 📄 License + +MIT © [Poyraz Avsever](https://github.com/poyrazavsever) + +--- + +
+ +# Türkçe + +

+ React ve Tailwind CSS v4 için tip güvenli, modüler ve anlık tema değiştirici +

+ +--- + +## ✨ Özellikler + +- 🚀 **Sıfır Çalışma Zamanı Yükü** - Anlık tema değişimi için CSS değişkenleri kullanır +- 📦 **TypeScript Öncelikli** - Otomatik tamamlama desteği ile tam tip güvenliği +- 🎨 **Tailwind CSS v4 Uyumlu** - Yeni motor ile kusursuz entegrasyon +- 💾 **Kalıcı Temalar** - Kutudan çıktığı gibi localStorage desteği +- 🌙 **Sistem Teması Algılama** - `prefers-color-scheme` tercihine uyar +- ⚡ **Yanıp Sönme Yok** - SSR uyumlu, hidrasyon flash önleme +- 🎯 **Kapsamlı Tema** - Uygulamanızın farklı bölümlerine farklı temalar uygulayın +- 🧩 **Kullanıma Hazır Bileşenler** - `ThemeSwitcher` ve `ThemeToggle` dahil + +--- + +## 📦 Kurulum + +```bash +npm install reactive-switcher +# veya +pnpm add reactive-switcher +# veya +yarn add reactive-switcher +``` + +--- + +## 🚀 Hızlı Başlangıç + +### 1. Temalarınızı Tanımlayın + +```typescript +// themes.ts +import { ThemesConfig } from "reactive-switcher"; + +export const themes: ThemesConfig = { + light: { + name: "light", + type: "light", + colors: { + background: "#ffffff", + foreground: "#0f172a", + primary: { + DEFAULT: "#3b82f6", + foreground: "#ffffff", + 50: "#eff6ff", + 500: "#3b82f6", + 600: "#2563eb", + }, + secondary: { + DEFAULT: "#64748b", + foreground: "#ffffff", + }, + surface: { + 50: "#f8fafc", + 100: "#f1f5f9", + 200: "#e2e8f0", + }, + }, + }, + dark: { + name: "dark", + type: "dark", + colors: { + background: "#020617", + foreground: "#f8fafc", + primary: { + DEFAULT: "#60a5fa", + foreground: "#0f172a", + }, + secondary: { + DEFAULT: "#94a3b8", + foreground: "#0f172a", + }, + surface: { + 50: "#0f172a", + 100: "#1e293b", + 200: "#334155", + }, + }, + }, +}; +``` + +### 2. Uygulamanızı ThemeProvider ile Sarmalayın + +```tsx +// app/layout.tsx (Next.js) +import { ThemeProvider } from "reactive-switcher"; +import { themes } from "./themes"; + +export default function RootLayout({ children }) { + return ( + + + + {children} + + + + ); +} +``` + +### 3. Temayı Kullanın + +```tsx +"use client"; +import { useTheme, ThemeToggle } from "reactive-switcher"; + +export function Header() { + const { theme, setTheme, toggleTheme } = useTheme(); + + return ( +
+

Aktif Tema: {theme}

+ + {/* Kullanıma hazır toggle */} + + + {/* Veya manuel kontrol */} + + +
+ ); +} +``` + +### 4. Tailwind CSS v4 Yapılandırması + +```css +/* globals.css */ +@import "tailwindcss"; + +@theme { + --color-background: var(--color-background); + --color-foreground: var(--color-foreground); + --color-primary: var(--color-primary-DEFAULT); + --color-primary-foreground: var(--color-primary-foreground); + --color-secondary: var(--color-secondary-DEFAULT); + --color-surface-50: var(--color-surface-50); + --color-surface-100: var(--color-surface-100); + --color-surface-200: var(--color-surface-200); +} + +@layer base { + body { + background-color: var(--color-background); + color: var(--color-foreground); + transition: background-color 0.3s, color 0.3s; + } +} +``` + +--- + +## 📖 API Referansı + +### ThemeProvider Props + +| Prop | Tip | Varsayılan | Açıklama | +| --------------- | -------------- | --------------------------- | ----------------------------- | +| `themes` | `ThemesConfig` | **zorunlu** | Tema yapılandırma objesi | +| `defaultTheme` | `string` | `"light"` | Başlangıç teması | +| `enableStorage` | `boolean` | `true` | localStorage'a kaydet | +| `storageKey` | `string` | `"reactive-switcher-theme"` | localStorage anahtarı | +| `enableSystem` | `boolean` | `true` | Sistem teması algılama | +| `selector` | `string` | `":root"` | Kapsamlı tema için CSS seçici | + +### useTheme() Hook + +```typescript +const { + theme, // Aktif tema adı (string) + resolvedTheme, // Gerçek tema ("system" çözümlenir) + setTheme, // (name: string) => void + toggleTheme, // () => void - Temalar arasında geçiş + themes, // Mevcut tema adları (string[]) + systemTheme, // Sistem tercihi ("light" | "dark") +} = useTheme(); +``` + +--- + +## 🌐 Demo + +Canlı demoyu inceleyin: [reactive-switcher.vercel.app](https://reactive-switcher.vercel.app) + +--- + +## 🤝 Katkıda Bulunma + +Katkılarınızı bekliyoruz! Pull Request göndermekten çekinmeyin. + +1. Repoyu fork edin +2. Feature branch oluşturun (`git checkout -b feature/harika-ozellik`) +3. Değişikliklerinizi commit edin (`git commit -m 'Harika özellik ekle'`) +4. Branch'i push edin (`git push origin feature/harika-ozellik`) +5. Pull Request açın + +--- + +## 📄 Lisans + +MIT © [Poyraz Avsever](https://github.com/poyrazavsever) + +--- + +[![Star History Chart](https://api.star-history.com/svg?repos=poyrazavsever/reactive-switcher&type=date&legend=top-left)](https://www.star-history.com/#poyrazavsever/reactive-switcher&type=date&legend=top-left) + +

+ Made with ❤️ by Poyraz Avsever +

+ + +--- + +# Reactive Switcher 🎨 + +> Type-safe, modular, and instant theme switching for React & Tailwind CSS v4 + +[![npm version](https://badge.fury.io/js/reactive-switcher.svg)](https://www.npmjs.com/package/reactive-switcher) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +## ✨ Features + +- **Zero Runtime Overhead** - Uses CSS variables for instant theme switching +- **TypeScript First** - Full type safety with autocomplete support +- **Tailwind CSS v4 Ready** - Seamless integration with the new engine +- **Persistent Themes** - LocalStorage support out of the box +- **System Theme Detection** - Respects `prefers-color-scheme` +- **No Flash** - SSR compatible with hydration flash prevention +- **Scoped Theming** - Apply different themes to different parts of your app +- **Ready-to-use Components** - `ThemeSwitcher` and `ThemeToggle` included + +## 📦 Installation + +```bash +npm install reactive-switcher +# or +pnpm add reactive-switcher +# or +yarn add reactive-switcher +``` + +## 🚀 Quick Start + +### 1. Define Your Themes + +Create a file to define your theme configurations: + +```typescript +// themes.ts +import { ThemesConfig } from "reactive-switcher"; + +export const themes: ThemesConfig = { + light: { + name: "light", + type: "light", + colors: { + background: "#ffffff", + foreground: "#0f172a", + primary: { + DEFAULT: "#3b82f6", + foreground: "#ffffff", + 50: "#eff6ff", + 100: "#dbeafe", + 500: "#3b82f6", + 600: "#2563eb", + }, + secondary: { + DEFAULT: "#64748b", + foreground: "#ffffff", + }, + surface: { + 50: "#f8fafc", + 100: "#f1f5f9", + 200: "#e2e8f0", + }, + }, + }, + dark: { + name: "dark", + type: "dark", + colors: { + background: "#020617", + foreground: "#f8fafc", + primary: { + DEFAULT: "#60a5fa", + foreground: "#0f172a", + 50: "#172554", + 100: "#1e3a8a", + 500: "#3b82f6", + 600: "#60a5fa", + }, + secondary: { + DEFAULT: "#94a3b8", + foreground: "#0f172a", + }, + surface: { + 50: "#0f172a", + 100: "#1e293b", + 200: "#334155", + }, + }, + }, +}; +``` + +### 2. Wrap Your App with ThemeProvider + +```tsx +// app/layout.tsx (Next.js) or main.tsx (Vite) +import { ThemeProvider } from "reactive-switcher"; +import { themes } from "./themes"; + +export default function RootLayout({ children }) { + return ( + + + + {children} + + + + ); +} +``` + +### 3. Use the Theme + +```tsx +// components/Header.tsx +"use client"; +import { useTheme, ThemeToggle } from "reactive-switcher"; + +export function Header() { + const { theme, setTheme, toggleTheme } = useTheme(); + + return ( +
+

Current Theme: {theme}

+ + {/* Option 1: Simple toggle button */} + + + {/* Option 2: Manual control */} + + + + + {/* Option 3: Cycle through themes */} + +
+ ); +} +``` + +### 4. Configure Tailwind CSS v4 + +```css +/* globals.css */ +@import "tailwindcss"; + +@theme { + --color-background: var(--color-background); + --color-foreground: var(--color-foreground); + + --color-primary: var(--color-primary-DEFAULT); + --color-primary-foreground: var(--color-primary-foreground); + --color-primary-50: var(--color-primary-50); + --color-primary-100: var(--color-primary-100); + --color-primary-500: var(--color-primary-500); + --color-primary-600: var(--color-primary-600); + + --color-secondary: var(--color-secondary-DEFAULT); + --color-secondary-foreground: var(--color-secondary-foreground); + + --color-surface-50: var(--color-surface-50); + --color-surface-100: var(--color-surface-100); + --color-surface-200: var(--color-surface-200); +} + +@layer base { + body { + background-color: var(--color-background); + color: var(--color-foreground); + transition: background-color 0.3s, color 0.3s; + } +} +``` + +Now you can use Tailwind classes like `bg-primary`, `text-foreground`, `bg-surface-100` etc. + +--- + +## 📖 API Reference + +### ThemeProvider + +The main provider component that wraps your application. + +```tsx + + {children} + +``` + +### useTheme Hook + +Access theme state and controls anywhere in your app. + +```tsx +const { + theme, // Current theme name (e.g., "light", "dark", "system") + resolvedTheme, // Actual theme when "system" is selected + setTheme, // Function to set theme by name + toggleTheme, // Function to cycle to next theme + activeThemeObject, // Full theme object with colors + themes, // Array of available theme names + systemTheme, // System preference ("light" | "dark") +} = useTheme(); +``` + +### ThemeSwitcher Component + +A ready-to-use theme switcher component with multiple variants. + +```tsx +// Buttons variant (default) + + +// Dropdown variant + + +// Toggle variant (cycles through themes) + + +// With custom labels + + +// Hide labels, show only icons + + +// Custom render function + + {({ theme, setTheme, themes }) => ( +
+ {themes.map(t => ( + + ))} +
+ )} + +``` + +### ThemeToggle Component + +A simple light/dark toggle button. + +```tsx +// Default + + +// Different sizes + + + + +// Custom icons +} + darkIcon={} +/> +``` + +--- + +## 🎯 Advanced Usage + +### Scoped Theming + +Apply different themes to different parts of your app: + +```tsx +// Main app uses light theme + +
+ {/* This section has its own theme */} + +
{/* This area will have dark theme */}
+ +
+ +``` + +### Custom Theme Type + +```typescript +import { Theme, ThemesConfig } from "reactive-switcher"; + +// Define your custom theme structure +const myTheme: Theme = { + name: "ocean", + type: "dark", + colors: { + background: "#042f2e", + foreground: "#ccfbf1", + primary: { + DEFAULT: "#2dd4bf", + foreground: "#042f2e", + }, + // Add any custom color tokens + accent: { + DEFAULT: "#facc15", + subtle: "#fef3c7", + }, + }, +}; +``` + +### System Theme Only + +```tsx + + {children} + +``` + +--- + +## 🔧 Utility Functions + +```typescript +import { + flattenTheme, + createCssString, + getSystemTheme, + getStoredTheme, + setStoredTheme, +} from "reactive-switcher"; + +// Flatten nested colors to CSS variables +const vars = flattenTheme(theme.colors); +// { '--color-primary-DEFAULT': '#3b82f6', '--color-primary-500': '#3b82f6' } + +// Create CSS string +const css = createCssString(theme); +// ":root { --color-primary-DEFAULT: #3b82f6; ... }" + +// Get system preference +const systemTheme = getSystemTheme(); // 'light' | 'dark' + +// Storage utilities +const stored = getStoredTheme("theme-key"); +setStoredTheme("theme-key", "dark"); +``` + +--- + +## 📋 TypeScript Support + +Full type definitions are included. Enable autocomplete for your theme tokens: + +```typescript +import { Theme, ThemesConfig } from 'reactive-switcher'; + +// Your themes will have full type checking +const themes: ThemesConfig = { + light: { ... }, + dark: { ... }, +}; +``` + +--- + +## 🤝 Contributing + +Contributions are welcome! Please read our contributing guidelines first. + +## 📄 License + +MIT © [Poyraz Avsever](https://github.com/poyrazavsever) + +--- + +

+ Made with ❤️ for the React community +

\ No newline at end of file diff --git a/docs/usage-guide.md b/docs/usage-guide.md new file mode 100644 index 0000000..d13315f --- /dev/null +++ b/docs/usage-guide.md @@ -0,0 +1,413 @@ +# 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 ( + + + + + + ); +} +``` + +--- + +## 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 {children}; +} +``` + +--- + +## 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//` altina ekle +2. Gerekirse type exportlarini component dosyasinda tanimla + +### 11.2 Export haritasi + +3. `src//index.ts` icine export satirlarini ekle +4. Gerekliyse `src/index.ts` ana barrel kontrol et + +### 11.3 Docs entegrasyonu + +5. `app/docs///page.tsx` olustur +6. Kategori index sayfasina link ekle (`app/docs//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. diff --git a/package.json b/package.json index df88274..da184b3 100644 --- a/package.json +++ b/package.json @@ -11,7 +11,8 @@ "dependencies": { "next": "16.1.6", "react": "19.2.3", - "react-dom": "19.2.3" + "react-dom": "19.2.3", + "reactive-switcher": "^1.0.3" }, "devDependencies": { "@tailwindcss/postcss": "^4", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 608fc39..057128f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -17,6 +17,9 @@ importers: react-dom: specifier: 19.2.3 version: 19.2.3(react@19.2.3) + reactive-switcher: + specifier: ^1.0.3 + version: 1.0.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3) devDependencies: '@tailwindcss/postcss': specifier: ^4 @@ -1641,6 +1644,12 @@ packages: resolution: {integrity: sha512-Ku/hhYbVjOQnXDZFv2+RibmLFGwFdeeKHFcOTlrt7xplBnya5OGn/hIRDsqDiSUcfORsDC7MPxwork8jBwsIWA==} engines: {node: '>=0.10.0'} + reactive-switcher@1.0.3: + resolution: {integrity: sha512-d5kGGUdDZ0z4kdgmBwNOL9Z6qQKYqv6tyifde+6XXbWQZpY5oNbkuA2WNXut6ETwbIbBNa3+dvHWR66XIapqlw==} + peerDependencies: + react: '>=18.0.0' + react-dom: '>=18.0.0' + reflect.getprototypeof@1.0.10: resolution: {integrity: sha512-00o4I+DVrefhv+nX0ulyi3biSHCPDe+yLv5o/p6d/UVlirijB8E16FtfwSAi4g3tcqrQ4lRAqQSoFEZJehYEcw==} engines: {node: '>= 0.4'} @@ -3626,6 +3635,11 @@ snapshots: react@19.2.3: {} + reactive-switcher@1.0.3(react-dom@19.2.3(react@19.2.3))(react@19.2.3): + dependencies: + react: 19.2.3 + react-dom: 19.2.3(react@19.2.3) + reflect.getprototypeof@1.0.10: dependencies: call-bind: 1.0.8 diff --git a/src/lib/themes.ts b/src/lib/themes.ts new file mode 100644 index 0000000..9ce6eae --- /dev/null +++ b/src/lib/themes.ts @@ -0,0 +1,15 @@ +import { poyrazLightTheme, poyrazDarkTheme, poyrazThemes } from "poyraz-ui/themes"; + +// You can customise themes by spreading and overriding variables: +// +// const customLight = { +// ...poyrazLightTheme, +// name: "custom-light", +// variables: { +// ...poyrazLightTheme.variables, +// "--poyraz-primary": "#2563eb", // blue-600 +// "--poyraz-primary-foreground": "#ffffff", +// }, +// }; + +export { poyrazLightTheme, poyrazDarkTheme, poyrazThemes };