@wface/pixel-ui 0.5.2 → 0.5.8

package/README.md

@@ -1,73 +1,200 @@
-# React + TypeScript + Vite
+# Pixel UI — @wface/pixel-ui
 
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+Pixel UI, WFace ekosistemi için hazırlanmış, React + TypeScript ile yazılmış bir bileşen kütüphanesidir. Bu paket, yeniden kullanılabilir UI bileşenleri, tema/context sağlayıcıları ve yardımcı stiller (utilities) içerir. Kütüphane hem uygulama içinde (dev mode) hem de bağımsız paket olarak (npm/yarn) kullanılmak üzere hazırlanmıştır.
 
-Currently, two official plugins are available:
+Bu README, bileşenin nasıl kurulacağı, kullanılacağı, geliştirileceği ve paketleneceği hakkında pratik bilgiler içerir.
 
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
-- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+---
 
-## React Compiler
+İçindekiler
+- Ne işe yarar?
+- Hızlı kurulum
+- Örnek kullanım
+  - Temel kullanım
+  - `PiTable` örneği (alt tablo / expandable)
+- Stiller ve tema
+- Geliştirme & Build
+- Yayınlama
+- Yardımcı (utilities) sınıflar
+- Katkıda bulunma
+- Lisans
 
-The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+---
 
-## Expanding the ESLint configuration
+Ne işe yarar?
 
-If you are developing a production application, we recommend updating the configuration to enable type-aware lint rules:
+- Tek bir paket içinde ortak UI bileşenlerini sağlar (buton, input, table, dropdown, modal vb.).
+- Tasarım token'ları ve SCSS utilities ile tutarlı stilizasyon sunar.
+- Tema ve Toast gibi provider'lar ile uygulama seviyesinde kullanım sağlar.
 
-```js
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
+Hızlı kurulum
 
-      // Remove tseslint.configs.recommended and replace with this
-      tseslint.configs.recommendedTypeChecked,
-      // Alternatively, use this for stricter rules
-      tseslint.configs.strictTypeChecked,
-      // Optionally, add this for stylistic rules
-      tseslint.configs.stylisticTypeChecked,
+Projeye bağımlılık olarak eklemek için:
 
-      // Other configs...
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+```bash
+# npm
+npm install @wface/pixel-ui
+
+# veya yarn
+yarn add @wface/pixel-ui
 ```
 
-You can also install [eslint-plugin-react-x](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-x) and [eslint-plugin-react-dom](https://github.com/Rel1cx/eslint-react/tree/main/packages/plugins/eslint-plugin-react-dom) for React-specific lint rules:
-
-```js
-// eslint.config.js
-import reactX from 'eslint-plugin-react-x'
-import reactDom from 'eslint-plugin-react-dom'
-
-export default defineConfig([
-  globalIgnores(['dist']),
-  {
-    files: ['**/*.{ts,tsx}'],
-    extends: [
-      // Other configs...
-      // Enable lint rules for React
-      reactX.configs['recommended-typescript'],
-      // Enable lint rules for React DOM
-      reactDom.configs.recommended,
-    ],
-    languageOptions: {
-      parserOptions: {
-        project: ['./tsconfig.node.json', './tsconfig.app.json'],
-        tsconfigRootDir: import.meta.dirname,
-      },
-      // other options...
-    },
-  },
-])
+Peer-dependencies
+- react 18.2.0
+- react-dom 18.2.0
+- react-router-dom 6.x (pakette 6.2.2 hedeflenmiştir)
+
+Kullanım (örnek)
+
+Temel kullanımda kütüphaneyi import edip stilleri ekleyin:
+
+```tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import { Pixel, PiButton } from '@wface/pixel-ui'
+import '@wface/pixel-ui/styles.css' // veya uygulamanızın global stil yükleme noktasına ekleyin
+
+function App() {
+  return (
+    <Pixel>
+      <div style={{ padding: 24 }}>
+        <PiButton>Buton</PiButton>
+      </div>
+    </Pixel>
+  )
+}
+
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />)
 ```
+
+Not: `Pixel` provider'ı tema ve bazı global context'leri sağlar; bazı bileşenler (örn. `useTheme`) yalnızca provider içinde çalışır.
+
+PiTable örneği — alt tablo (subtable) ve expandable row
+
+Aşağıdaki örnek, `PiTable` kullanımını, alt tabloyu (subtable) ve bir `user.id` tıklamasıyla satırı genişletmeyi gösterir:
+
+```tsx
+import React, { useState } from 'react'
+import { PiTable } from '@wface/pixel-ui'
+
+const data = [
+  { id: 'u1', name: 'Ali', email: 'ali@example.com' },
+  { id: 'u2', name: 'Ayşe', email: 'ayse@example.com' },
+]
+
+function HomeTable() {
+  const [expanded, setExpanded] = useState<Record<string, boolean>>({})
+
+  const toggle = (id: string) => setExpanded(prev => ({ ...prev, [id]: !prev[id] }))
+
+  return (
+    <PiTable>
+      <PiTable.TableHeader>
+        <PiTable.TableRow>
+          <PiTable.TableCell width={120}>ID</PiTable.TableCell>
+          <PiTable.TableCell>İsim</PiTable.TableCell>
+          <PiTable.TableCell>Mail</PiTable.TableCell>
+        </PiTable.TableRow>
+      </PiTable.TableHeader>
+
+      <PiTable.TableBody>
+        {data.map((u) => (
+          <PiTable.TableRow
+            key={u.id}
+            id={`row-${u.id}`}
+            onClick={() => toggle(u.id)}
+            showSubTable={!!expanded[u.id]}
+            subTable={
+              <PiTable subTable variant="bordered">
+                <PiTable.TableHeader>
+                  <PiTable.TableRow>
+                    <PiTable.TableCell>Alt Bilgi</PiTable.TableCell>
+                  </PiTable.TableRow>
+                </PiTable.TableHeader>
+                <PiTable.TableBody>
+                  <PiTable.TableRow>
+                    <PiTable.TableCell>{`Detay: ${u.email}`}</PiTable.TableCell>
+                  </PiTable.TableRow>
+                </PiTable.TableBody>
+              </PiTable>
+            }
+          >
+            <PiTable.TableCell width={120}>{u.id}</PiTable.TableCell>
+            <PiTable.TableCell>{u.name}</PiTable.TableCell>
+            <PiTable.TableCell>{u.email}</PiTable.TableCell>
+          </PiTable.TableRow>
+        ))}
+      </PiTable.TableBody>
+    </PiTable>
+  )
+}
+```
+
+Açıklamalar:
+- `PiTable.TableRow`, `PiTable.TableCell`, `PiTable.TableHeader`, `PiTable.TableBody` alt bileşenleri `PiTable`'ın üzerine eklenmiş şekilde kullanılabilir.
+- `subTable` prop'u bir React düğüm (element) bekler; `showSubTable` ile görünürlüğü kontrol edebilirsiniz.
+- Satır genişletme (expand) davranışı örnekte tıklama ile yapıldı; isterseniz daha kontrollü state yönetimi sağlayabilirsiniz.
+
+Stiller & tema
+
+- Paket `styles.css` (dist içinde) ile birlikte gelir. Uygulamanıza dahil etmek için `import '@wface/pixel-ui/styles.css'` kullanın.
+- SCSS kaynakları `src/styles` içinde bulunur. Değiştirilebilir tokenlar ve temalar `tokens/` ve `theme.scss` içinde yer alır.
+- Utility sınıflar `src/styles/_utilities.scss` içinde tanımlıdır. `.pi-m-4`, `.pi-p-8`, `.pi-flex` gibi sınıflarla hızlı düzenlemeler yapabilirsiniz.
+
+Geliştirme & build
+
+Proje kökünde (paket dizini) yaygın script'ler:
+
+- `yarn dev` — kütüphaneyi uygulama modunda çalıştırır (Vite dev server).
+- `yarn dev:lib` — yalnızca kütüphane için Vite server (farklı port).
+- `yarn build` — kütüphaneyi üretim için derler (Vite build) ve TypeScript tiplerini (`.d.ts`) üretir.
+- `yarn clean` — `dist` klasörünü temizler.
+- `yarn prepublishOnly` — yayın öncesi temizleme ve build çalıştırır.
+
+Örnek: lokal geliştirme
+
+1. repo kökünde bağımlılıkları yükleyin (örn. `yarn` veya `npm install`).
+2. Bu pakete gelin: `cd packages/lib` (eğer monorepo düzeni varsa).
+3. `yarn dev` ile story/dev uygulamayı başlatın.
+
+Yayınlama
+
+Paket `dist` klasörünü içerir ve `package.json` içindeki `files` alanı sayesinde sadece `dist` yayımlanır. Paket yayınlamadan önce:
+
+```bash
+yarn clean && yarn build
+# ardından npm publish (veya yarn publish)
+```
+
+Paket `publishConfig.access` `public` olarak ayarlı, npm registry'ye public olarak yayınlar.
+
+Yardımcı (utilities)
+
+`_utilities.scss` içinde bir dizi yardımcı sınıf (spacing, typography, display, gap, border vb.) bulunur. Bu sınıflar hızlı layout ve spacing işleri için uygundur ve komponent modul SCSS'leri içinde `@extend` veya component className ile kullanılabilir.
+
+Örnekler:
+- `.pi-m-4` — tüm kenarlar için margin
+- `.pi-px-8` — yatay padding
+- `.pi-flex`, `.pi-items-center`, `.pi-justify-between` — flex helper'lar
+
+Katkıda bulunma
+
+- Yeni bileşen eklerken, `src/components` altında modüler şekilde oluşturun ve `src/index.ts` içinde export edin.
+- Stil değişiklikleri SCSS token ve utilities üzerinden yapılmalı.
+- Build ve test aşamalarını yerel olarak çalıştırıp kontrol edin.
+
+Sorun giderme / sık karşılaşılan hatalar
+
+- "useTheme must be used within ThemeProvider" hatası: `useTheme` hook'unu kullanmadan önce `ThemeProvider` veya `Pixel` provider'ı render ağacına eklediğinizden emin olun.
+- Stiller görünmüyorsa: uygulamanızın entry noktasında `@wface/pixel-ui/styles.css` import edildiğinden emin olun.
+- Peer dependency hataları: proje React versiyonunun paket peer dependency ile uyumlu olduğundan emin olun.
+
+İletişim & daha fazla bilgi
+
+Daha detaylı kullanım örnekleri ve demo uygulamalar `packages/lib/src/demo` ve `packages/docs` içinde bulunabilir (monorepo yapısına bağlı olarak). Hata bildirmek veya katkıda bulunmak için repository'de issue açabilirsiniz.
+
+Lisans
+
+Bu proje lisans bilgilerini repository kökünde bulundurur. (Burada proje lisansı belirtilmemişse, kök dizindeki `LICENSE` dosyasına bakın.)
+
+---