> ## Documentation Index
> Fetch the complete documentation index at: https://docs.azalt.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Widget

> Bir göstergenin görselleştirmesi; ayarlar ve isteğe bağlı widget düzeyi filtre ile.

### Widget

Widget, bir Dashboard içinde tek bir Indicator’ü görselleştirir. Birleşik filtreleri (site, yıl aralığı, durumlar), farklı görselleştirme tiplerini, toplama ve gösterim seçeneklerini, dataset eşlemesini ve isteğe bağlı hedef (targets) katmanını destekler.

#### Türler

* `line_chart`: çok serili zaman trendleri
* `bar_chart`: kategorik/zamansal karşılaştırmalar (default/stacked/percent)
* `pie_chart`: oransal dağılımlar
* `value`: tek KPI değeri
* `periodic_values`: dönemsel/kalender özetleri
* `table`: hiyerarşik gösterge kırılım tablosu

#### Veri Yapısı

```typescript theme={null}
// apps/azalt/src/server/db/types/dashboard.ts (özet)
type DashboardWidgetType =
  | "line_chart" | "bar_chart" | "pie_chart" | "value" | "table" | "periodic_values";

interface DashboardFilter { siteIds?: string[]; startYear?: number; endYear?: number; statuses?: ("APPROVED"|"COMPLETED"|"REJECTED")[] }

interface DashboardWidgetSettings {
  indicatorDatasetMappings?: Record<string, {
    useDatasetValue: boolean;
    datasetId?: string;
    name?: string;
    field?: string;
  }> | null;
  aggregator?: "sum" | "avg" | "ratio";
  period?: "MONTHLY" | "QUARTERLY" | "YEARLY" | "TIMESTAMP";
  displayMode?: "sites" | "aggregated" | "groups";
  chartSettings?: "default" | "stacked" | "percent";
  showNumbers?: boolean;
  showIndicatorName?: boolean;
  angle?: number;
  siteGroups?: Array<{ id: string; name: string; siteIds: string[] }>;
  decimalPlaces: number;
  selectedTargetEntries?: string[];
  showTargets?: boolean;
}

interface DashboardWidget {
  id: string; dashboardId: string; indicatorId: string; name: string;
  type: DashboardWidgetType; x: number; y: number; w: number; h: number;
  settings: DashboardWidgetSettings; filter: DashboardFilter | null;
}
```

#### Filtreler ve Öncelik

* Widget düzeyi `filter`, `siteIds`, `startYear`, `endYear`, `statuses` belirtebilir.
* Belirtilmezse Dashboard `globalFilter` uygulanır.
* Durumlar (statuses), organizasyon varsayılanlarına; yoksa `APPROVED`’a düşer.
* Halka açık dashboard’larda, kaydedilmeyen per-widget geçici geçersiz kılmalar kabul edilir (public API).

#### Ayarlar

* Toplama: `sum`, `avg`, `ratio`
* Periyot: `MONTHLY`, `QUARTERLY`, `YEARLY` (grafikler için `TIMESTAMP` aylığa normalize edilir)
* Görünüm modu: `sites` (site bazlı), `aggregated` (tek seri), `groups` (özel site grupları)
* Çubuk grafiği: `default`, `stacked`, `percent`
* Biçimlendirme: `decimalPlaces`, `showNumbers`, `showIndicatorName`, `angle` (pie)
* Dataset eşlemesi: her gösterge girdisi için dataset/alan seçimi; eksik alan/yıl bazında veri yok gibi eşleme sorunları arayüzde gösterilir
* Hedefler: hedef çizgileri ve seçili hedef girdileri

#### Veri ve API

* İç (uygulama): `dashboardWidgets.getData` bir widget’ın göstergesi için, birleştirilmiş filtreler ve ayarları dikkate alarak hesaplanmış değerleri döner.
* Halka açık: `dashboards.getWithData` tüm widget’lar için birleşik bir yük döner (dashboard, widget’lar, dataset’ler, göstergeler, widgetData). Halka açık görünüm `viewOptions` (ör. tip) ve per-widget filtre geçersiz kılmalarını iletebilir.

#### Güvenlik ve Yetkiler

* Okuma: Viewer veya halka açık bağlantı (halka açık dashboard’larda)
* Widget oluştur/güncelle/sil: Manager ve üzeri

#### Sık Yapılan İşlemler

* Widget ekleme: gösterge, tip ve yerleşim (x,y,w,h) seç
* Ayarları düzenleme: periyot, toplama, görünüm modu, ondalık
* Dashboard varsayılanlarını geçersiz kılmak için widget filtresi uygula
* Gösterge girişleri için dataset eşlemesi yap; eşleme sorunlarını gider
* Widget’ı sürükle-bırak ile taşı veya kaldır

#### İlgili Kavramlar

* Dashboard — konteyner ve küresel filtre
* Indicator — widget’ın görselleştirdiği metrik
* Dataset — gösterge hesaplamalarında kullanılan katsayılar ve referans değerler