Pixel UI — @wface/pixel-ui

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.

Bu README, bileşenin nasıl kurulacağı, kullanılacağı, geliştirileceği ve paketleneceği hakkında pratik bilgiler içerir.

İç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

Ne işe yarar?

• 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.

Hızlı kurulum

Projeye bağımlılık olarak eklemek için:

# npm
npm install @wface/pixel-ui

# veya yarn
yarn add @wface/pixel-ui

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:

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:

import React, { useState } from 'react'
import { PiTable } from '@wface/pixel-ui'

const data = [
  { id: 'u1', name: 'Ali', email: '[email protected]' },
  { id: 'u2', name: 'Ayşe', email: '[email protected]' },
]

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:

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