@logosphere-ui/core 0.0.0-alpha.3 → 0.0.0-alpha.30

package/AGENTS.md

@@ -0,0 +1,1118 @@
+# Logosphere UI — Agent Reference
+
+> **Bu dosya AI agent'lar için yazılmıştır.**  
+> Bir kullanıcı sana ekran görüntüsü/Figma/wireframe verip "bu sayfayı logosphere kullanarak yap" dediğinde, bu dosyadaki bileşenleri, property'leri ve örnekleri kullanarak layout'u oluştur.
+
+---
+
+## Kurulum ve İçe Aktarım
+
+```html
+<!-- CDN (tek dosya, tüm bileşenler) -->
+<script type="module" src="node_modules/@logosphere-ui/core/dist/index.js"></script>
+
+<!-- Veya yalnızca ihtiyaç duyulan bileşenler -->
+<script type="module" src="node_modules/@logosphere-ui/core/dist/button.js"></script>
+<script type="module" src="node_modules/@logosphere-ui/core/dist/input.js"></script>
+```
+
+```ts
+// ES modül import
+import "@logosphere-ui/core";
+// Ya da tekil:
+import "@logosphere-ui/core/button";
+import "@logosphere-ui/core/input";
+```
+
+---
+
+## Genel Kurallar
+
+| Kural | Açıklama |
+|-------|----------|
+| **Property bağlama** | Nesne/dizi/boolean prop'ları `.propName=${value}` ile bağla (Lit); HTML attribute için `propname="value"` |
+| **Boyut değerleri** | `size="default"` veya `size="large"` (bileşene göre `"sm"/"md"/"lg"` de olabilir) |
+| **Variant değerleri** | `variant="default"` veya `variant="subtle"` |
+| **Hata/yardım** | `error="..."` ve `helper="..."` prop'ları tüm form bileşenlerinde mevcuttur |
+| **Disabled/Readonly** | Tüm form bileşenlerinde `disabled` ve `readonly` boolean prop'ları bulunur |
+| **Event dinleme** | `element.addEventListener("change", handler)` veya inline `@change=${handler}` (Lit) |
+
+---
+
+## Bileşen Kataloğu
+
+### ATOMS
+
+---
+
+### `<logosphere-button>`
+
+Varyant, boyut ve tema destekli buton.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `variant` | `"solid" \| "outline" \| "text"` | `"solid"` | Görsel stil |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Boyut |
+| `theme` | `"primary" \| "success" \| "danger" \| "info" \| "warning" \| "light" \| "dark"` | `"primary"` | Renk teması |
+| `iconOnly` | `boolean` | `false` | Yalnızca ikon göster (metin gizlenir) |
+| `disabled` | `boolean` | `false` | Devre dışı bırak |
+
+**Slots:** varsayılan (etiket metni), `prefix` (sol ikon), `suffix` (sağ ikon)
+
+```html
+<!-- Temel kullanım -->
+<logosphere-button>Kaydet</logosphere-button>
+
+<!-- Varyantlar -->
+<logosphere-button variant="outline" theme="danger">Sil</logosphere-button>
+<logosphere-button variant="text" theme="primary">İptal</logosphere-button>
+
+<!-- İkon ile -->
+<logosphere-button size="sm">
+  <ui-icon slot="prefix" name="uil-check" size="16"></ui-icon>
+  Onayla
+</logosphere-button>
+
+<!-- Yalnızca ikon -->
+<logosphere-button iconOnly variant="outline">
+  <ui-icon name="uil-trash" size="16"></ui-icon>
+</logosphere-button>
+```
+
+---
+
+### `<logosphere-badge>`
+
+Etiket/chip bileşeni; kapatılabilir veya yuvarlak.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `text` | `string` | `""` | Badge metni |
+| `variant` | `BadgeVariant` | `"default"` | Renk varyantı |
+| `size` | `BadgeSize` | `"default"` | Boyut |
+| `closeable` | `boolean` | `false` | Kapatma (×) butonu göster |
+| `isRound` | `boolean` | `false` | Tam yuvarlak şekil |
+| `onClose` | `() => void` | — | Kapatma callback'i (attribute değil) |
+
+**Events:** `close`
+
+**Slots:** varsayılan (isteğe bağlı içerik)
+
+```html
+<logosphere-badge text="Yeni"></logosphere-badge>
+<logosphere-badge text="Aktif" variant="success" isRound></logosphere-badge>
+<logosphere-badge text="Hata" variant="danger" closeable></logosphere-badge>
+```
+
+---
+
+### `<logosphere-checkbox>`
+
+Onay kutusu veya toggle switch.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `label` | `string` | `""` | Etiket metni |
+| `value` | `string` | `""` | Form değeri |
+| `checked` | `boolean` | `false` | İşaretli mi |
+| `type` | `"checkbox" \| "switch"` | `"checkbox"` | Görünüm tipi |
+| `disabled` | `boolean` | `false` | Devre dışı |
+| `indeterminate` | `boolean` | `false` | Belirsiz durum |
+
+**Events:** `lgsChange` → `detail: { checked, indeterminate, value }`
+
+```html
+<logosphere-checkbox label="Beni hatırla" value="remember"></logosphere-checkbox>
+
+<!-- Switch görünümü -->
+<logosphere-checkbox type="switch" label="Bildirimleri etkinleştir" checked></logosphere-checkbox>
+
+<!-- Event dinleme -->
+<script>
+  document.querySelector("logosphere-checkbox")
+    .addEventListener("lgsChange", e => console.log(e.detail.checked));
+</script>
+```
+
+---
+
+### `<logosphere-switch>`
+
+Bağımsız toggle switch.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `checked` | `boolean` | `false` | Açık mı |
+| `disabled` | `boolean` | `false` | Devre dışı |
+| `size` | `"sm" \| "md"` | `"md"` | Boyut |
+
+**Events:** `change` → `detail: { checked }`
+
+```html
+<logosphere-switch></logosphere-switch>
+<logosphere-switch checked size="sm"></logosphere-switch>
+```
+
+---
+
+### `<logosphere-formfield>`
+
+Tüm form kontrolleri için temel sarmalayıcı; etiket, hata/yardım, kenarlıklı konteyner.
+
+> Genellikle doğrudan kullanılmaz; `logosphere-input`, `logosphere-textarea` gibi bileşenler içinde otomatik kullanılır. Özel kontrol oluştururken işe yarar.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `label` | `string` | `""` | Alan etiketi |
+| `helper` | `string` | `""` | Yardım metni (altında gösterilir) |
+| `error` | `string` | `""` | Hata mesajı (kırmızı, helper'ın yerini alır) |
+| `required` | `boolean` | `false` | Zorunlu alan işareti (*) |
+| `disabled` | `boolean` | `false` | Soluklaştır |
+| `readonly` | `boolean` | `false` | Salt okunur stili |
+| `size` | `"default" \| "large"` | `"default"` | Boyut |
+| `variant` | `"default" \| "subtle"` | `"default"` | Stil varyantı |
+| `cursor` | `"text" \| "pointer"` | `"text"` | İmleç tipi |
+| `multiline` | `boolean` | `false` | Textarea modu (daha yüksek) |
+| `forceFocused` | `boolean` | `false` | Odak stilini zorla (TimePicker/DatePicker için) |
+
+**Slots:** varsayılan (kontrol), `prefix` (sol), `clear` (temizle butonu), `suffix` (sağ)
+
+**Events:** `field-focus`, `field-blur` → `detail: { originalEvent }`
+
+---
+
+### MOLECULES
+
+---
+
+### `<logosphere-input>`
+
+Metin girişi; maske, parola, temizle ve tüm formfield özellikleri.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `value` | `string` | `""` | Geçerli değer |
+| `type` | `"text" \| "password" \| "email" \| "number" \| "tel" \| "url" \| "search" \| "date" \| "time"` | `"text"` | Input tipi |
+| `placeholder` | `string` | `""` | Yer tutucu |
+| `name` | `string` | `""` | Form adı |
+| `mask` | `string` | `""` | Giriş maskesi: `0`=rakam, `a`=harf, `*`=rakam/harf, diğerleri literal. Örn: `"(000) 000-0000"`, `"00/00/0000"`, `"00:00"` |
+| `label` | `string` | `""` | Etiket |
+| `helper` | `string` | `""` | Yardım metni |
+| `error` | `string` | `""` | Hata mesajı |
+| `required` | `boolean` | `false` | Zorunlu |
+| `disabled` | `boolean` | `false` | Devre dışı |
+| `readonly` | `boolean` | `false` | Salt okunur |
+| `size` | `"default" \| "large"` | `"default"` | Boyut |
+| `variant` | `"default" \| "subtle"` | `"default"` | Stil |
+| `minlength` | `number` | — | Min karakter |
+| `maxlength` | `number` | — | Maks karakter |
+| `min` / `max` | `number` | — | Sayısal sınırlar |
+| `pattern` | `string` | `""` | Regex doğrulama |
+| `autocomplete` | `string` | `""` | Tarayıcı otomatik doldurma |
+
+**Public Metotlar:** `focus()`, `blur()`, `select()`, `setSelectionRange(start, end)`, `checkValidity()`, `reportValidity()`, `setCustomValidity(msg)`
+
+**Events:**
+- `input` → `detail: { value, rawValue, originalEvent }`
+- `change` → `detail: { value, originalEvent }`
+- `clear` (temizle butonuna tıklanınca)
+- `keydown` / `keyup` → `detail: { key, originalEvent }`
+
+**Slots:** `prefix` (sol ikon/metin), `suffix` (sağ ikon/buton)
+
+```html
+<!-- Temel kullanım -->
+<logosphere-input label="Ad Soyad" placeholder="Adınızı girin"></logosphere-input>
+
+<!-- Email, zorunlu, hata -->
+<logosphere-input
+  type="email"
+  label="E-posta"
+  required
+  error="Geçersiz e-posta adresi"
+></logosphere-input>
+
+<!-- Telefon maskesi -->
+<logosphere-input
+  label="Telefon"
+  mask="(000) 000-0000"
+  placeholder="(555) 000-0000"
+></logosphere-input>
+
+<!-- Tarih maskesi -->
+<logosphere-input label="Doğum Tarihi" mask="00/00/0000" placeholder="GG/AA/YYYY"></logosphere-input>
+
+<!-- Parola -->
+<logosphere-input type="password" label="Şifre"></logosphere-input>
+
+<!-- Prefix/suffix ikon ile -->
+<logosphere-input label="Arama" placeholder="Ara...">
+  <ui-icon slot="prefix" name="uil-search" size="16"></ui-icon>
+</logosphere-input>
+
+<!-- Subtle varyant (kenarsız, arka plan yok) -->
+<logosphere-input variant="subtle" placeholder="Hızlı arama..."></logosphere-input>
+
+<!-- Büyük boyut -->
+<logosphere-input size="large" label="Başlık" placeholder="Başlık girin"></logosphere-input>
+```
+
+---
+
+### `<logosphere-textarea>`
+
+Çok satırlı metin girişi; otomatik boyutlandırma, karakter sayacı.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `value` | `string` | `""` | Metin değeri |
+| `placeholder` | `string` | `""` | Yer tutucu |
+| `rows` | `number` | `3` | Başlangıç satır sayısı |
+| `maxRows` | `number` | `8` | autoResize için max satır (sonra scroll) |
+| `maxlength` | `number` | — | Maks karakter (sayaç gösterir) |
+| `autoResize` | `boolean` | `true` | İçeriğe göre otomatik yükseklik |
+| `resize` | `"none" \| "vertical" \| "horizontal" \| "both"` | `"vertical"` | Manuel yeniden boyutlandırma (autoResize=false iken) |
+| `label` | `string` | `""` | Etiket |
+| `helper` | `string` | `""` | Yardım metni |
+| `error` | `string` | `""` | Hata mesajı |
+| `required` | `boolean` | `false` | Zorunlu |
+| `disabled` | `boolean` | `false` | Devre dışı |
+| `readonly` | `boolean` | `false` | Salt okunur |
+| `size` | `"default" \| "large"` | `"default"` | Boyut |
+| `variant` | `"default" \| "subtle"` | `"default"` | Stil |
+
+**Events:** `input`, `change`, `clear`, `keydown`, `keyup`
+
+```html
+<!-- Temel kullanım -->
+<logosphere-textarea label="Açıklama" placeholder="Açıklama girin..."></logosphere-textarea>
+
+<!-- Karakter sayacı ile -->
+<logosphere-textarea label="Yorum" maxlength="500" rows="4"></logosphere-textarea>
+
+<!-- Manuel resize, auto kapalı -->
+<logosphere-textarea .autoResize=${false} resize="vertical" rows="6"></logosphere-textarea>
+
+<!-- Max satır sınırı -->
+<logosphere-textarea label="Not" maxRows="5"></logosphere-textarea>
+```
+
+---
+
+### `<logosphere-breadcrumb>`
+
+Navigasyon izleri.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `items` | `{ label: string; href?: string; active?: boolean }[]` | `[]` | Navigasyon öğeleri |
+
+```html
+<logosphere-breadcrumb
+  .items=${[
+    { label: "Ana Sayfa", href: "/" },
+    { label: "Ürünler", href: "/products" },
+    { label: "Laptop", active: true }
+  ]}
+></logosphere-breadcrumb>
+```
+
+---
+
+### `<logosphere-card>`
+
+Başlık, içerik ve ayak bölümü olan kart.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `title` | `string` | `""` | Kart başlığı |
+| `description` | `string` | `""` | Başlık altı açıklama |
+| `header` | `boolean` | `true` | Başlık bölümünü göster |
+| `footer` | `boolean` | `true` | Ayak bölümünü göster |
+| `okLabel` | `string` | `"Tamam"` | Onay butonu etiketi |
+| `cancelLabel` | `string` | `"İptal"` | İptal butonu etiketi |
+| `onOk` | `() => void` | — | Onay callback'i |
+| `onCancel` | `() => void` | — | İptal callback'i |
+
+**Events:** `ok`, `cancel`
+
+**Slots:** `header` (özel başlık), varsayılan (gövde), `footer` (özel ayak)
+
+```html
+<!-- Temel kart -->
+<logosphere-card title="Kullanıcı Bilgileri" description="Profil bilgilerinizi güncelleyin">
+  <logosphere-input label="Ad" placeholder="Adınızı girin"></logosphere-input>
+  <logosphere-input label="E-posta" type="email"></logosphere-input>
+</logosphere-card>
+
+<!-- Onay diyaloğu gibi -->
+<logosphere-card title="Emin misiniz?" okLabel="Evet, Sil" cancelLabel="Hayır">
+  Bu işlem geri alınamaz.
+</logosphere-card>
+
+<!-- Sadece gövde -->
+<logosphere-card .header=${false} .footer=${false}>
+  İçerik buraya
+</logosphere-card>
+```
+
+---
+
+### `<logosphere-popover>`
+
+Tetikleyici elemana konumlanmış açılır panel.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `title` | `string` | `""` | Popover başlığı |
+| `trigger` | `"click" \| "hover"` | `"click"` | Açılma tetikleyicisi |
+| `placement` | Popper Placement | `"bottom"` | Konum (`"top"`, `"bottom"`, `"left"`, `"right"`, `"bottom-start"` vb.) |
+| `offset` | `number` | `8` | Tetikleyiciden mesafe (px) |
+| `open` | `boolean` | `false` | Açık mı (reflect) |
+| `closeOnOutsideClick` | `boolean` | `true` | Dışarı tıklayınca kapat |
+
+**Events:** `popover-open`, `popover-close`
+
+**Slots:** `trigger` (tetikleyici element), varsayılan (panel içeriği)
+
+```html
+<logosphere-popover title="Yardım">
+  <logosphere-button slot="trigger" variant="outline">?</logosphere-button>
+  Bu alan, kullanıcının tam adını içermelidir.
+</logosphere-popover>
+```
+
+---
+
+### `<logosphere-timepicker>`
+
+`HH:MM` formatında saat seçici; hem yazarak hem spinner ile kullanım.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `value` | `string` | `""` | `"HH:MM"` formatında değer |
+| `label` | `string` | `""` | Etiket |
+| `helper` | `string` | `""` | Yardım metni |
+| `error` | `string` | `""` | Hata mesajı |
+| `placeholder` | `string` | `"__:__"` | Yer tutucu |
+| `required` | `boolean` | `false` | Zorunlu |
+| `disabled` | `boolean` | `false` | Devre dışı |
+| `readonly` | `boolean` | `false` | Salt okunur |
+| `size` | `"default" \| "large"` | `"default"` | Boyut |
+| `variant` | `"default" \| "subtle"` | `"default"` | Stil |
+| `onChange` | `(value: string) => void` | — | Değişim callback'i (attribute değil) |
+
+**Events:** `change` → `detail: { value }`, `clear`
+
+```html
+<!-- Temel kullanım -->
+<logosphere-timepicker label="Başlangıç Saati"></logosphere-timepicker>
+
+<!-- Değer ile -->
+<logosphere-timepicker label="Bitiş Saati" value="17:30"></logosphere-timepicker>
+
+<!-- Zorunlu, hata ile -->
+<logosphere-timepicker
+  label="Toplantı Saati"
+  required
+  error="Saat seçimi zorunludur"
+></logosphere-timepicker>
+
+<!-- Event -->
+<script>
+  document.querySelector("logosphere-timepicker")
+    .addEventListener("change", e => console.log(e.detail.value)); // "14:30"
+</script>
+```
+
+---
+
+### ORGANISMS
+
+---
+
+### `<logosphere-combobox>`
+
+Seçim kutusu: tekli/çoklu seçim, filtreleme, tag desteği.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `items` | `Record<string, unknown>[]` | `[]` | Seçenek listesi |
+| `label` | `string` | `""` | Etiket |
+| `helper` | `string` | `""` | Yardım metni |
+| `error` | `string` | `""` | Hata mesajı |
+| `placeholder` | `string` | `"Seçim yapınız"` | Yer tutucu |
+| `multiple` | `boolean` | `false` | Çoklu seçim |
+| `filterable` | `boolean` | `false` | Arama/filtreleme |
+| `required` | `boolean` | `false` | Zorunlu |
+| `disabled` | `boolean` | `false` | Devre dışı |
+| `readOnly` | `boolean` | `false` | Salt okunur |
+| `size` | `"default" \| "large"` | `"default"` | Boyut |
+| `variant` | `"default" \| "subtle"` | `"default"` | Stil |
+| `optionLabel` | `string` | `"label"` | Seçenek nesnesindeki etiket alanı |
+| `optionValue` | `string` | `"value"` | Seçenek nesnesindeki değer alanı |
+| `emptyMessage` | `string` | `"Sonuç yok"` | Sonuç yokken gösterilecek mesaj |
+
+**Public Metotlar:** `selectedItems()` → seçili öğe dizisi, `isSelected(item)`, `setSelected(items[])`
+
+**Events:** `selected` → `detail: { selected }`, `change` → `detail: { value }`
+
+```html
+<logosphere-combobox
+  label="Şehir"
+  placeholder="Şehir seçin"
+  .items=${[
+    { label: "İstanbul", value: "ist" },
+    { label: "Ankara",   value: "ank" },
+    { label: "İzmir",    value: "izm" }
+  ]}
+></logosphere-combobox>
+
+<!-- Çoklu, filtrelenebilir -->
+<logosphere-combobox
+  label="Etiketler"
+  multiple
+  filterable
+  .items=${tags}
+></logosphere-combobox>
+
+<!-- Özel alan adları -->
+<logosphere-combobox
+  optionLabel="name"
+  optionValue="id"
+  .items=${users}
+></logosphere-combobox>
+```
+
+---
+
+### `<logosphere-datepicker>`
+
+Tarih seçici; manuel yazma ve takvim popup'ı. `dayjs` tabanlı.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `value` | `string \| null` | `null` | `"YYYY-MM-DD"` formatında değer |
+| `min` | `string \| null` | `null` | En erken tarih (`"YYYY-MM-DD"`) |
+| `max` | `string \| null` | `null` | En geç tarih |
+| `label` | `string` | `""` | Etiket |
+| `helper` | `string` | `""` | Yardım |
+| `error` | `string` | `""` | Hata |
+| `placeholder` | `string` | `"GG/AA/YYYY"` | Yer tutucu |
+| `required` | `boolean` | `false` | Zorunlu |
+| `disabled` | `boolean` | `false` | Devre dışı |
+| `readonly` | `boolean` | `false` | Salt okunur |
+| `rangeMode` | `boolean` | `false` | Aralık seçimi modu |
+| `rangeStart` | `string \| null` | `null` | Aralık başlangıcı |
+| `rangeEnd` | `string \| null` | `null` | Aralık bitişi |
+| `disabledDays` | `number[]` | `[]` | Devre dışı haftanın günleri (0=Pazar…6=Cumartesi) |
+| `expandFactor` | `number` | `1.05` | Popup genişlik çarpanı |
+| `onChange` | `(value: string) => void` | — | Değişim callback'i |
+| `onRangeChange` | `(range) => void` | — | Aralık callback'i |
+
+**Events:** `change` → `detail: { value }`, `rangeChange` → `detail: { start, end }`
+
+```html
+<!-- Temel kullanım -->
+<logosphere-datepicker label="Tarih"></logosphere-datepicker>
+
+<!-- Min/max sınırları -->
+<logosphere-datepicker
+  label="Başlangıç Tarihi"
+  min="2024-01-01"
+  max="2026-12-31"
+  value="2025-06-15"
+></logosphere-datepicker>
+
+<!-- Aralık modu -->
+<logosphere-datepicker
+  label="Tarih Aralığı"
+  .rangeMode=${true}
+></logosphere-datepicker>
+
+<!-- Hafta sonu kapalı -->
+<logosphere-datepicker
+  label="İş Günü"
+  .disabledDays=${[0, 6]}
+></logosphere-datepicker>
+```
+
+---
+
+### `<logosphere-calendar>`
+
+Bağımsız takvim bileşeni; ay/yıl görünümü, aralık seçimi.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `value` | `string \| null` | `null` | Seçili tarih (`"YYYY-MM-DD"`) |
+| `min` / `max` | `string \| null` | `null` | Sınır tarihleri |
+| `disabled` | `boolean` | `false` | Tüm takvim devre dışı |
+| `rangeMode` | `boolean` | `false` | Aralık seçimi |
+| `rangeStart` / `rangeEnd` | `string \| null` | `null` | Aralık uçları |
+| `disabledDays` | `number[]` | `[]` | Devre dışı günler |
+| `closable` | `boolean` | `false` | Kapat butonu göster |
+
+**Events:** `change`, `rangeChange`, `calendar-state-change`, `close-request`
+
+**Public Metotlar:** `focusGrid()`
+
+```html
+<logosphere-calendar value="2025-06-15"></logosphere-calendar>
+```
+
+---
+
+### `<logosphere-modal>`
+
+Tam ekran arka planlı modal diyalog.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `open` | `boolean` | `false` | Açık mı (reflect) |
+| `title` | `string` | `""` | Modal başlığı |
+| `closeOnEsc` | `boolean` | `true` | Esc ile kapat |
+| `closeOnBackdrop` | `boolean` | `true` | Arka plana tıklayınca kapat |
+| `showBack` | `boolean` | `false` | Geri butonu göster |
+| `showClose` | `boolean` | `false` | Kapat (×) butonu göster |
+
+**Public Metotlar:** `openModal()`, `closeModal()`
+
+**Events:** `modal-open`, `modal-close`
+
+**Slots:** `header`, varsayılan (gövde), `footer`
+
+```html
+<logosphere-modal id="my-modal" title="Düzenle" showClose>
+  <logosphere-input label="Ad"></logosphere-input>
+  <div slot="footer">
+    <logosphere-button variant="outline" id="cancel-btn">İptal</logosphere-button>
+    <logosphere-button>Kaydet</logosphere-button>
+  </div>
+</logosphere-modal>
+
+<logosphere-button onclick="document.getElementById('my-modal').openModal()">
+  Modal Aç
+</logosphere-button>
+```
+
+---
+
+### `<logosphere-drawer>`
+
+Yan panel; sağdan veya soldan açılır.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `open` | `boolean` | `false` | Açık mı (reflect) |
+| `title` | `string` | `""` | Panel başlığı |
+| `position` | `"left" \| "right"` | `"right"` | Hangi taraftan açılsın |
+| `width` | `number` | `360` | Genişlik (px) |
+| `closeOnEsc` | `boolean` | `true` | Esc ile kapat |
+| `containerSelector` | `string` | `""` | CSS selector; panel bu eleman içinde konumlanır |
+
+**Public Metotlar:** `openDrawer()`, `closeDrawer()`
+
+**Events:** `drawer-open`, `drawer-close`
+
+**Slots:** `trigger` (açma butonu), varsayılan (panel gövdesi)
+
+```html
+<logosphere-drawer title="Filtreler" position="right" width="400">
+  <logosphere-button slot="trigger" variant="outline">
+    Filtreleri Aç
+  </logosphere-button>
+
+  <logosphere-combobox label="Durum" .items=${statusOptions}></logosphere-combobox>
+  <logosphere-datepicker label="Tarih"></logosphere-datepicker>
+  <logosphere-button style="width:100%; margin-top:16px">Uygula</logosphere-button>
+</logosphere-drawer>
+```
+
+---
+
+### `<logosphere-toast>` ve `ToastService`
+
+Bildirim mesajı. Genellikle doğrudan kullanmak yerine `ToastService` kullanılır.
+
+**`logosphere-toast` Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `type` | `"info" \| "success" \| "warning" \| "danger"` | `"info"` | Ikon/renk tipi |
+| `title` | `string` | `""` | Başlık |
+| `text` | `string` | `""` | Açıklama metni |
+| `icon` | `string` | `""` | Özel ikon adı |
+| `closeable` | `boolean` | `true` | Manuel kapatma butonu |
+| `duration` | `number` | `6000` | Otomatik kapanma süresi (ms) |
+| `autoDismiss` | `boolean` | `true` | Otomatik kapat |
+| `action` | `ToastActionConfig` | — | Aksiyon butonu konfigürasyonu |
+
+**Events:** `toast-close` → `detail: { reason: "manual" | "auto" }`
+
+**`logosphere-toast-container`** — HTML'e ekle, sonra `ToastService` ile kullan:
+
+```html
+<!-- Sayfa başına bir kere ekle -->
+<logosphere-toast-container></logosphere-toast-container>
+```
+
+```ts
+import { ToastService } from "@logosphere-ui/core";
+
+// Kullanım
+ToastService.success("Başarılı", "Kayıt oluşturuldu.");
+ToastService.danger("Hata",     "Bir sorun oluştu.");
+ToastService.warning("Uyarı",   "Dikkat ediniz.");
+ToastService.info("Bilgi",      "Güncelleme mevcut.");
+
+// Özel seçenekler
+ToastService.show({
+  type:        "success",
+  title:       "Dosya yüklendi",
+  text:        "belge.pdf başarıyla yüklendi.",
+  duration:    4000,
+  autoDismiss: true,
+});
+```
+
+---
+
+### `<logosphere-tab>`
+
+Sekme gezinmesi; lazy yükleme desteği.
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `tabs` | `TabItem[]` | `[]` | Sekme konfigürasyonu |
+| `activeTab` | `string` | `""` | Aktif sekme id'si |
+| `lazy` | `boolean` | `true` | İçerikleri lazy yükle |
+| `variant` | `"default" \| "card"` | `"default"` | Görünüm |
+
+**`TabItem` yapısı:**
+
+```ts
+interface TabItem {
+  id:       string;
+  label:    string;
+  disabled?: boolean;
+  icon?:    string; // ui-icon adı
+}
+```
+
+**Events:** `tab-change` → `detail: { oldTab, newTab }`
+
+**Slots:** Her sekme için `panel-${tab.id}` adlı slot
+
+```html
+<logosphere-tab
+  .tabs=${[
+    { id: "genel",    label: "Genel",    icon: "uil-info-circle" },
+    { id: "guvenlik", label: "Güvenlik", icon: "uil-check-circle" },
+    { id: "fatura",   label: "Fatura",   disabled: true }
+  ]}
+  activeTab="genel"
+>
+  <div slot="panel-genel">
+    <logosphere-input label="Ad Soyad"></logosphere-input>
+  </div>
+  <div slot="panel-guvenlik">
+    <logosphere-input type="password" label="Mevcut Şifre"></logosphere-input>
+  </div>
+</logosphere-tab>
+```
+
+---
+
+### `<logosphere-leftmenu>` ve `<leftmenu-item>`
+
+Daraltılabilir kenar çubuğu; menü ağacı, arama, logo slotları.
+
+**`logosphere-leftmenu` Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `open` | `boolean` | `false` | Genişletilmiş mi (reflect) |
+| `pinned` | `boolean` | `false` | Sabitlenmiş mi (reflect) |
+| `closedWidth` | `number` | `64` | Kapalı genişlik (px) |
+| `openWidth` | `number` | `248` | Açık genişlik (px) |
+| `storageKey` | `string` | `"logosphere-leftmenu-state"` | localStorage anahtarı |
+
+**Events:** `pin-change` → `detail: { pinned }`, `item-click` → `detail: { item }`
+
+**Slots:** varsayılan (`leftmenu-item` elementler), `logo-open`, `logo-closed`, `custom-open`, `custom-closed`
+
+**`leftmenu-item` Properties**
+
+| Property | Tip | Varsayılan |
+|----------|-----|-----------|
+| `itemId` | `string` | `""` |
+| `label` | `string` | `""` |
+| `disabled` | `boolean` | `false` |
+| `active` | `boolean` | `false` |
+
+**Slots:** varsayılan (etiket), `icon` (ikon), `children` (alt öğeler)
+
+```html
+<logosphere-leftmenu open>
+  <img slot="logo-open"   src="/logo-full.svg"  alt="Logo" />
+  <img slot="logo-closed" src="/logo-icon.svg"  alt="L"    />
+
+  <leftmenu-item itemId="dashboard" label="Ana Sayfa" active>
+    <ui-icon slot="icon" name="uil-home" size="20"></ui-icon>
+  </leftmenu-item>
+
+  <leftmenu-item itemId="users" label="Kullanıcılar">
+    <ui-icon slot="icon" name="uil-users-alt" size="20"></ui-icon>
+    <div slot="children">
+      <leftmenu-item itemId="users-list"   label="Liste"></leftmenu-item>
+      <leftmenu-item itemId="users-create" label="Yeni Ekle"></leftmenu-item>
+    </div>
+  </leftmenu-item>
+</logosphere-leftmenu>
+```
+
+---
+
+### `<logosphere-tree-menu>`
+
+Özyinelemeli ağaç menü (veri tabanlı).
+
+**Properties**
+
+| Property | Tip | Varsayılan | Açıklama |
+|----------|-----|-----------|---------|
+| `items` | `TreeMenuItem[]` | — | Ağaç verisi (attribute değil, `.items=${...}`) |
+| `expandedIds` | `string[]` | `[]` | Açık düğüm id'leri |
+| `expandOnLabelClick` | `boolean` | `true` | Etikete tıklayınca aç/kapa |
+| `chevronPosition` | `"left" \| "right"` | `"left"` | Ok konumu |
+| `showLabels` | `boolean` | `true` | Etiketleri göster |
+| `iconSize` | `number` | `16` | İkon boyutu |
+
+**`TreeMenuItem` yapısı:**
+
+```ts
+interface TreeMenuItem {
+  id:        string;
+  label:     string;
+  icon?:     string;
+  children?: TreeMenuItem[];
+  disabled?: boolean;
+  data?:     unknown; // isteğe bağlı ek veri
+}
+```
+
+**Events:** `toggle`, `item-click`, `node-click` — her biri `detail: { item, ... }`
+
+```html
+<logosphere-tree-menu
+  .items=${[
+    {
+      id: "1", label: "Belgeler",
+      children: [
+        { id: "1-1", label: "Raporlar" },
+        { id: "1-2", label: "Sözleşmeler" }
+      ]
+    },
+    { id: "2", label: "Resimler" }
+  ]}
+></logosphere-tree-menu>
+```
+
+---
+
+### `<ui-icon>`
+
+SVG ikon bileşeni. `icon-map.ts`'deki kayıtlı ikonları isimle render eder.
+
+**Properties**
+
+| Property | Tip | Açıklama |
+|----------|-----|---------|
+| `name` | `string` | İkon adı (aşağıdaki tabloya bak) |
+| `size` | `number \| string` | Piksel boyutu (varsayılan: `16`) |
+
+**Mevcut İkon İsimleri**
+
+| İkon Adı | Kullanım Yeri |
+|----------|--------------|
+| `uil-times` | Kapatma/temizle |
+| `uil-clock` | Saat/zaman |
+| `uil-check` | Onay |
+| `uil-check-circle` | Başarı |
+| `uil-calendar` | Takvim |
+| `uil-calendar-alt` | Takvim (alternatif) |
+| `uil-arrow-left` | Sol ok |
+| `uil-arrow-right` | Sağ ok |
+| `uil-arrow-up` | Yukarı ok |
+| `uil-arrow-down` | Aşağı ok |
+| `uil-trash` | Silme |
+| `uil-compress-alt` | Küçült |
+| `uil-expand-alt` | Büyüt |
+| `uil-copy` | Kopyala |
+| `uil-thumbs-up` | Beğeni |
+| `uil-thumbs-down` | Beğenmeme |
+| `uil-arrow-circle-right` | Gönder |
+| `uil-eye` | Göster |
+| `uil-eye-slash` | Gizle |
+| `uil-search` | Arama |
+| `uil-left-arrow-to-left` | Sola sabitle |
+| `uil-right-arrow-to-right` | Sağa sabitle |
+| `uil-pin` | Sabitle |
+| `uil-exclamation-triangle` | Uyarı |
+| `uil-exclamation-octagon` | Hata |
+| `uil-info-circle` | Bilgi |
+| `uil-angle-up` | Yukarı köşeli |
+| `uil-angle-down` | Aşağı köşeli |
+
+```html
+<ui-icon name="uil-check" size="20"></ui-icon>
+<ui-icon name="uil-trash" size="16"></ui-icon>
+```
+
+---
+
+## Sayfa Katmanları: Örnek Kompozisyonlar
+
+### Giriş Sayfası (Login Form)
+
+```html
+<div style="min-height:100vh; display:flex; align-items:center; justify-content:center; background:var(--color-body-bg)">
+  <logosphere-card title="Giriş Yap" description="Hesabınıza erişin" style="width:400px">
+    <div style="display:flex; flex-direction:column; gap:16px">
+      <logosphere-input
+        type="email"
+        label="E-posta"
+        placeholder="ornek@sirket.com"
+        required
+      ></logosphere-input>
+
+      <logosphere-input
+        type="password"
+        label="Şifre"
+        required
+      ></logosphere-input>
+
+      <logosphere-checkbox label="Beni hatırla" value="remember"></logosphere-checkbox>
+
+      <logosphere-button style="width:100%">Giriş Yap</logosphere-button>
+    </div>
+  </logosphere-card>
+</div>
+```
+
+---
+
+### Filtreli Liste Sayfası (Drawer filtreli)
+
+```html
+<!-- Üst çubuk -->
+<div style="display:flex; gap:12px; align-items:center; padding:16px">
+  <logosphere-input placeholder="Ara..." style="flex:1">
+    <ui-icon slot="prefix" name="uil-search" size="16"></ui-icon>
+  </logosphere-input>
+
+  <logosphere-drawer title="Filtreler" position="right">
+    <logosphere-button slot="trigger" variant="outline">Filtre</logosphere-button>
+
+    <div style="display:flex; flex-direction:column; gap:12px; padding:16px">
+      <logosphere-combobox label="Durum"    .items=${statusItems}></logosphere-combobox>
+      <logosphere-combobox label="Kategori" .items=${categoryItems} multiple filterable></logosphere-combobox>
+      <logosphere-datepicker label="Tarih Aralığı" .rangeMode=${true}></logosphere-datepicker>
+      <logosphere-button style="width:100%">Uygula</logosphere-button>
+    </div>
+  </logosphere-drawer>
+</div>
+```
+
+---
+
+### Ayarlar Sayfası (Tab'lı form)
+
+```html
+<logosphere-tab
+  .tabs=${[
+    { id: "profil",   label: "Profil"   },
+    { id: "hesap",    label: "Hesap"    },
+    { id: "bildirim", label: "Bildirimler" }
+  ]}
+  activeTab="profil"
+>
+  <div slot="panel-profil" style="display:flex; flex-direction:column; gap:16px; padding:16px">
+    <logosphere-input label="Ad"    placeholder="Adınız"></logosphere-input>
+    <logosphere-input label="Soyad" placeholder="Soyadınız"></logosphere-input>
+    <logosphere-input type="email" label="E-posta"></logosphere-input>
+    <logosphere-textarea label="Biyografi" maxlength="300"></logosphere-textarea>
+    <logosphere-button>Kaydet</logosphere-button>
+  </div>
+
+  <div slot="panel-hesap" style="display:flex; flex-direction:column; gap:16px; padding:16px">
+    <logosphere-input type="password" label="Mevcut Şifre"></logosphere-input>
+    <logosphere-input type="password" label="Yeni Şifre"></logosphere-input>
+    <logosphere-input type="password" label="Şifreyi Onayla"></logosphere-input>
+    <logosphere-button theme="danger">Şifreyi Değiştir</logosphere-button>
+  </div>
+
+  <div slot="panel-bildirim" style="display:flex; flex-direction:column; gap:12px; padding:16px">
+    <logosphere-checkbox type="switch" label="E-posta bildirimleri" checked></logosphere-checkbox>
+    <logosphere-checkbox type="switch" label="SMS bildirimleri"></logosphere-checkbox>
+    <logosphere-checkbox type="switch" label="Tarayıcı bildirimleri"></logosphere-checkbox>
+  </div>
+</logosphere-tab>
+```
+
+---
+
+### Admin Paneli Layout (Sol menü + içerik)
+
+```html
+<div style="display:flex; height:100vh; overflow:hidden">
+  <!-- Kenar çubuğu -->
+  <logosphere-leftmenu open pinned style="flex-shrink:0">
+    <img slot="logo-open"   src="/logo.svg" alt="Logo" style="height:32px"/>
+    <img slot="logo-closed" src="/icon.svg" alt="L"    style="height:32px"/>
+
+    <leftmenu-item itemId="dashboard" label="Panel" active>
+      <ui-icon slot="icon" name="uil-info-circle" size="20"></ui-icon>
+    </leftmenu-item>
+    <leftmenu-item itemId="users" label="Kullanıcılar">
+      <ui-icon slot="icon" name="uil-check-circle" size="20"></ui-icon>
+    </leftmenu-item>
+    <leftmenu-item itemId="reports" label="Raporlar">
+      <ui-icon slot="icon" name="uil-calendar" size="20"></ui-icon>
+    </leftmenu-item>
+  </logosphere-leftmenu>
+
+  <!-- Ana içerik -->
+  <main style="flex:1; overflow:auto; padding:24px">
+    <logosphere-breadcrumb
+      .items=${[{ label: "Panel", href: "/" }, { label: "Kullanıcılar", active: true }]}
+    ></logosphere-breadcrumb>
+
+    <!-- İçerik buraya -->
+  </main>
+</div>
+
+<!-- Toast container (sayfa başında bir kere) -->
+<logosphere-toast-container></logosphere-toast-container>
+```
+
+---
+
+### Silme Onay Modalı
+
+```html
+<logosphere-modal id="delete-modal" title="Kaydı Sil" showClose closeOnEsc>
+  <p>Bu kaydı silmek istediğinizden emin misiniz? Bu işlem geri alınamaz.</p>
+
+  <div slot="footer" style="display:flex; gap:8px; justify-content:flex-end">
+    <logosphere-button
+      variant="outline"
+      onclick="document.getElementById('delete-modal').closeModal()"
+    >İptal</logosphere-button>
+    <logosphere-button theme="danger" id="confirm-delete">Evet, Sil</logosphere-button>
+  </div>
+</logosphere-modal>
+
+<script>
+  document.getElementById("confirm-delete").addEventListener("click", () => {
+    // silme işlemi
+    ToastService.success("Silindi", "Kayıt başarıyla silindi.");
+    document.getElementById("delete-modal").closeModal();
+  });
+</script>
+```
+
+---
+
+## Design Tokens (CSS Değişkenleri)
+
+Bileşenler bu token'ları kullanır; tema özelleştirmek için `:root` üzerinde override et.
+
+```css
+:root {
+  /* Renkler */
+  --color-primary:          #your-brand;
+  --color-body-bg:          #ffffff;
+  --color-body-bg-hover:    #f5f5f5;
+  --color-body-text:        #1a1a1a;
+  --color-secondary:        #6b7280;
+  --color-tertiary:         #9ca3af;
+  --color-border:           #e5e7eb;
+
+  /* Durum renkleri */
+  --color-success:          #22c55e;
+  --color-warning:          #f59e0b;
+  --color-danger:           #ef4444;
+  --color-info:             #3b82f6;
+
+  /* Tipografi */
+  --font-family-base:       "Inter", sans-serif;
+  --font-size-sm:           0.875rem;  /* 14px */
+  --font-size-base:         1rem;      /* 16px */
+  --font-weight-regular:    400;
+  --font-weight-medium:     500;
+  --font-weight-semibold:   600;
+
+  /* Spacing */
+  --spacing-1:  0.25rem;  /* 4px  */
+  --spacing-2:  0.5rem;   /* 8px  */
+  --spacing-3:  0.75rem;  /* 12px */
+  --spacing-4:  1rem;     /* 16px */
+  --spacing-5:  1.25rem;  /* 20px */
+  --spacing-6:  1.5rem;   /* 24px */
+
+  /* Border radius */
+  --radius-sm:   0.25rem;  /* 4px  */
+  --radius-base: 0.5rem;   /* 8px  */
+  --radius-md:   0.75rem;  /* 12px */
+  --radius-full: 9999px;
+
+  /* Gölge */
+  --shadow-sm:  0 1px 3px rgba(0,0,0,0.1);
+  --shadow-md:  0px 4px 8px -2px rgba(0,0,0,0.1);
+
+  /* Geçiş */
+  --transition-speed-fast:  150ms;
+  --transition-timing:      ease;
+
+  /* Z-index */
+  --z-index-dropdown: 1000;
+  --z-index-modal:    1050;
+  --z-index-toast:    1100;
+}
+```