# Dashboard Bileşenleri
Package: @dataliva/livalib
Description: Livalib dashboard kartları, grafik ön ayarları ve tema uyumlu palet yardımcıları.

Dashboard paketi KPI kartları, grafik kapsayıcıları, metrik listeleri, bölüm
sekmeleri ve duyarlı yerleşim bileşenleri sunar. Tamamı Livalib tema
değişkenlerini kullanır.

```tsx
import {
  LivaDashboardGrid, LivaDashboardSection, LivaStatCard, LivaChartCard,
  LivaTrendChart, LivaMetricBar, LivaDonutStat, LivaSectionTabs,
} from "@dataliva/livalib";
```

## KPI ve trend

```tsx
<LivaDashboardSection title="Finansal Özet" description="Son 6 ay">
  <LivaDashboardGrid minColumnWidth={240}>
    <LivaStatCard
      label="Net Satış" value={1_248_500} unit="₺"
      delta="%12,4" trend="up" footnote="Geçen aya göre"
      icon="money" sparkline={[82, 91, 88, 103, 112, 124]}
    />
    <LivaStatCard
      label="Gider" value={640_000} unit="₺"
      delta="%5,1" trend="up" deltaTone="critical"
    />
  </LivaDashboardGrid>
</LivaDashboardSection>
```

`trend` yönü, `deltaTone` ise iş anlamını belirtir. Gider artışı gibi olumsuz
bir yükselişte `trend="up"` ve `deltaTone="critical"` birlikte kullanılır.

```tsx
<LivaChartCard title="Aylık Gerçekleşme" subtitle="2026" height={280}>
  <LivaTrendChart
    dataSource={monthlyData}
    argumentField="month"
    series={[
      { valueField: "actual", name: "Gerçekleşen" },
      { valueField: "budget", name: "Bütçe" },
    ]}
  />
</LivaChartCard>
```

`LivaChartCard`, `loading` durumunda iskelet; `empty` durumunda boş veri mesajı
gösterir. `LivaTrendChart` tek değer ekseni içindir; ölçekleri farklı serileri
ayrı grafiklere ayırın.

## Dağılım ve oranlar

```tsx
<LivaMetricBar items={departments} total={totalBudget} showShare sorted maxItems={5} />

<LivaDonutStat
  items={[{ label: "Tamamlanan", value: 72 }, { label: "Kalan", value: 28 }]}
  centerLabel="Tamamlanma" centerValue="%72" legend="bottom"
/>
```

`LivaMetricBar`, `maxItems` sonrasındaki kayıtları **Diğer** satırında toplar.
`showShare` için `total` verin. Donut grafikte ikiden fazla seri varsa lejantı
açık tutun.

## Proplar

Tüm bileşenler ayrıca `className` ve `style` alır.

### LivaDashboardGrid

| Prop | Tip | Varsayılan |
|------|------|---------|
| `minColumnWidth` | `number` | `240` (bir kolonun sarmadan önceki en küçük genişliği) |
| `columns` | `number` | — (verilirse `minColumnWidth` yok sayılır) |
| `gap` | `number` | `16` |
| `children` | `React.ReactNode` | — |

### LivaDashboardSection

| Prop | Tip | Varsayılan |
|------|------|---------|
| `title` | `React.ReactNode` | — |
| `description` | `React.ReactNode` | — |
| `actions` | `React.ReactNode` | — (başlığın sağındaki kontroller) |
| `children` | `React.ReactNode` | — |

### LivaStatCard

| Prop | Tip | Varsayılan |
|------|------|---------|
| `label` | `string` | — (zorunlu; kart başlığı, cümle değil) |
| `value` | `number \| string \| null` | — |
| `unit` | `string` | — (değerin sağında küçük punto: `"₺"`, `"adet"`) |
| `formatValue` | `(value: number) => string` | — (verilmezse yerel sayı biçimi) |
| `delta` | `string` | — (verilmezse rozet çizilmez) |
| `trend` | `'up' \| 'down' \| 'flat'` | — |
| `deltaTone` | `'good' \| 'critical' \| 'neutral'` | — (verilmezse `trend`'ten türetilir) |
| `footnote` | `React.ReactNode` | — |
| `icon` | `React.ReactNode` | — (DevExtreme ikon adı ya da düğüm) |
| `accent` | `string` | — (verilmezse paletin ilk slotu) |
| `sparkline` | `number[]` | — (en az iki nokta gerekir) |
| `loading` | `boolean` | `false` |
| `onClick` | `() => void` | — |

### LivaChartCard

| Prop | Tip | Varsayılan |
|------|------|---------|
| `title` | `React.ReactNode` | — (zorunlu) |
| `subtitle` | `React.ReactNode` | — |
| `actions` | `React.ReactNode` | — |
| `footer` | `React.ReactNode` | — (grafiğin altındaki lejant/rozet şeridi) |
| `height` | `number \| string` | `260` (kartlar arası hizayı korur) |
| `loading` | `boolean` | `false` |
| `empty` | `boolean` | `false` |
| `emptyText` | `React.ReactNode` | `'Görüntülenecek veri yok'` |
| `emptyIcon` | `string` | `'chart'` |
| `bodyClassName` | `string` | — |
| `children` | `React.ReactNode` | — |

### LivaTrendChart

| Prop | Tip | Varsayılan |
|------|------|---------|
| `dataSource` | `readonly object[]` | — (zorunlu) |
| `argumentField` | `string` | — (zorunlu; X eksenini besleyen alan) |
| `series` | `LivaTrendSeries[]` | — (zorunlu) |
| `type` | `'line' \| 'spline' \| 'area' \| 'splinearea' \| 'bar' \| 'stackedbar'` | `'spline'` |
| `rotated` | `boolean` | `false` (çubukları yatay çizer) |
| `height` | `number` | `260` |
| `formatValue` | `(value: number) => string` | — |
| `hideValueAxis` | `boolean` | `false` |

`LivaTrendSeries`: `valueField`, `name`, `color?`.

### LivaMetricBar

| Prop | Tip | Varsayılan |
|------|------|---------|
| `items` | `LivaMetricBarItem[]` | — (zorunlu) |
| `total` | `number` | — (verilmezse en büyük değere göre ölçeklenir) |
| `showShare` | `boolean` | `false` (`total` gerektirir) |
| `formatValue` | `(value: number) => string` | — |
| `maxItems` | `number` | — (kalanı `otherLabel` satırına katlar) |
| `otherLabel` | `string` | `'Diğer'` |
| `sorted` | `boolean` | `false` |

`LivaMetricBarItem`: `label`, `value`, `color?`.

### LivaDonutStat

| Prop | Tip | Varsayılan |
|------|------|---------|
| `items` | `LivaDonutStatItem[]` | — (zorunlu) |
| `centerValue` | `React.ReactNode` | — (verilmezse kalemlerin toplamı) |
| `centerLabel` | `React.ReactNode` | — |
| `formatValue` | `(value: number) => string` | — |
| `size` | `number` | `180` |
| `legend` | `'right' \| 'bottom' \| 'none'` | `'none'` |
| `palette` | `readonly string[]` | — (verilmezse aktif kategorik palet) |

`LivaDonutStatItem`: `label`, `value`.

### LivaSectionTabs

| Prop | Tip | Varsayılan |
|------|------|---------|
| `items` | `LivaSectionTabItem[]` | — (zorunlu) |
| `selectedId` | `string` | — (zorunlu) |
| `onSelect` | `(id: string) => void` | — (zorunlu) |
| `ariaLabel` | `string` | — |
| `stretch` | `boolean` | `false` (sekmeler satırı eşit paylaşır) |

`LivaSectionTabs` içerik render etmez; yalnızca seçilen `id`'yi yayar ve ok
tuşlarıyla gezinmeyi destekler. `LivaSectionTabItem`:
`{ id, text, icon?, count?, disabled? }`.

## Palet yardımcıları

`useLivaChartPalette()` aktif temaya uygun `categorical`, `sequential`, `surface`,
`gridline`, `axis` ve metin renklerini döndürür. `buildChartPalette`,
`categoricalColor`, `LIVA_CHART_PALETTE_LIGHT`, `LIVA_CHART_PALETTE_DARK`,
`LIVA_SEQUENTIAL_LIGHT`, `LIVA_SEQUENTIAL_DARK` ve `LIVA_STATUS_COLORS` da paket
kökünden dışa aktarılır.