DataTable (MUI DataGrid Wrapper) Dokümantasyonu

1) Amaç

DataTable, şirket projelerinde ortak tablo yapısını kullanmak için geliştirilmiş generic tablo component'idir.

• MaterialUI Tablo Yapısı kullanılarak oluşturulmuştur.

• Başlık + aksiyon alanı (Filtreleme, Kolon ayarları, Excel Export)

• Sayfalama (Custom Footer + Pagination)

• Filtre paneli (Drawer)

• Kolon görünürlüğü ayarları (Settings Dialog)

• Detay butonu + Detay modal iskeleti

Bu component bazı UI davranışlarını standartlaştırır.

2) Bağımlılıklar

Bu component aşağıdaki eklentileri kullanır:

• @mui/material
• @mui/icons-material
• @mui/x-data-grid
• xlsx

Örnek:

npm i @mui/material @mui/icons-material @mui/x-data-grid xlsx

3) Stil / Tasarım Standartları

Component içerisinde kullanılan renkler theme.css dosyası içinde CSS Custom Property olarak tanımlanmıştır. Projenin temasına ve renklerine uygun olarak, theme.css içerisinden projedeki vurgu renkleri, arkaplan ve harici renkler tek yerden değiştirilmeye uygundur.

Override (Proje Bazlı Tema)

Kütüphane varsayılan olarak kendi theme.css dosyasını paket ile birlikte getirir.
Projeye özel renkler için, kütüphanedeki değişkenleri kendi projenizde override edebilirsiniz.

1. Örnek bir kullanım: Projenizde bir override dosyası oluşturun:

src/styles.css

:root {
  --primary-color: red;
  --primary-soft: rgba(255, 0, 0, 0.08);
}

Bu dosyayı uygulama girişinde import edin:

`src/main.tsx`
```ts
import "datatable-library/styles.css";
import "./styles.css";


| Değişken | Kullanıldığı Yer |

#### `--primary-color`
Aktif sayfa butonu arka planı, odak rengi

#### `--primary-soft`
Detay ikonu hover arka planı

#### `--background-color`
Tablo arka planı, header, pagination

#### `--border-color`
Tüm kenarlıklar (tablo, buton, drawer)

#### `--text-color`
Ana içerik metni

#### `--muted-color`
Kayıt sayacı, sayfa bilgisi, ikincil metinler

#### `--icon-muted-color`
İleri/Geri ok ikonları, üç nokta (dots)

#### `--row-hover-bg`
Satır hover arka planı

#### `--pagination-hover-bg`
Pasif sayfa numarası hover rengi

---

## 4) Hızlı Başlangıç

#### `mode?: "client" | "server"` *(default: `"client"`)*
Bileşenin çalışma modunu belirler.
- `DataTable.tsx` içinde varsayılan değer olarak tanımlıdır.
- `App.tsx` içinde kullanım moduna göre geçilir.

### 4.1 Minimal kullanım (client-side pagination)

`mode` varsayılan olarak `"client"`'tır. 
Girilen bilgilerle `rows` üzerinde otomatik filtreleme ve sayfalama yapılır. Ek bir konfigürasyon gerekmez.

### 4.2 Controlled kullanım (server-side'a uygun)

`mode="server"` kullanıldığında `onServerQueryChange` zorunludur. Sayfa değişimi, filtre uygulaması ve ilk yükleme bu callback üzerinden yönetilir.

---

## 5) Props Referansı (`DataTableProps`)

#### `title?: React.ReactNode`
Excel Tablosu Başlığı. 

#### `headerActions?: React.ReactNode`
Başlık satırının sağına eklenen ekstra buton veya elementlerdir. Örn: "Yeni Ekle" butonu.

#### `mode?: "client" | "server"` 
Bileşenin çalışma modunu belirler.
- `DataTable.tsx` içinde varsayılan değer olarak tanımlıdır.

#### `pageSize?: number` *(default: `5`)*
Tabloda sayfa başına satır sayısını temsil eder.

#### `page?: number`
Controlled pagination için mevcut sayfa (1-based).

#### `totalCount?: number`
Controlled modda toplam kayıt sayısı. Verilmezse `rows.length` alınır.

####  `showFilterButton?: boolean (default: true)`
Filtre butonunun görünürlüğünü tetikler. `false` yapılırsa filtre drawer'ı açılamaz. 
- Bu ikona tıklandığında sağdan açılan bir Drawer içinde, bulunan her sütun için otomatik olarak bir `TextField` oluşturulur.

#### `onServerQueryChange?: (params: DataTableServerQueryParams) => void`
`mode="server"` kullanıldığında zorunludur. Sayfa değişimi ve filtre uygulamasında tetiklenir. `{ page, pageSize, filters }` parametrelerini alır.

#### `loading?: boolean` *(default: `false`)*
Tablo üzerinde yüklenme göstergesini aktif eder. Server-side kullanımda API çağrısı süresince `true` olarak geçilmesi önerilir.

### Özel Alan Konvansiyonları

#### `__detail`
Otomatik eklenen 'Detay' sütunu. Her satırda `OpenInNew` ikonu gösterir. Tıklandığında custom component modal açılır.

#### `__*` (genel)
Excel export ve Filtreleme Modalı için sütunları otomatik olarak harici tutar.
- Aksiyon butonları gibi sütunlar için kullanılması tavsiye edilir.
- Kendi custom sütunlarınız için `__` prefix'i kullanmayın.

### Zorunlu Props

- **`rows: T[]`** — Tabloda gösterilecek kayıtlar.
- **`columns: GridColDef<T>[]`** — MUI DataGrid kolon tanımları.

---

## 6) Özellikler ve Davranışlar

### 6.1 Sayfalama (Pagination + Footer)

- Footer, `totalCount ?? rows.length` üzerinden hesap yapar.
- Sayfa numaraları `buildPages` ile üretilir (`…` "dots" mantığı).
- `page` verilmezse component kendi `internalPage` state'ini kullanır.
- `page` verilirse controlled moda geçer, `onPageChange` beklenir.

> **Not:** Şu an component `rows` üzerinde slice yapıyor. Server-side kullanımda `rows` zaten sayfa datası olacağı için slice beklenmeyebilir. Bu senaryoda iki seçenek var:
> - Server-side'da `rows` zaten `pageSize` kadar gönderilir ve slice etkisiz olur (uyumlu).
> - İleri versiyonda `serverMode` gibi bir flag eklenip slice kapatılabilir (roadmap).

---

### 6.2 Filtre Drawer

- Filtreleme modalı, tabloda sağ üst köşede yer alan "Filtre" ikonuyla açılır.
- Tabloda bulunan her sütun için otomatik olarak bir `TextField` oluşturulur.


**Filtre mantığı:** Tüm aktif filtreler AND koşuluyla uygulanır. Büyük/küçük harf ve Türkçe karakter duyarlılığı `toLocaleLowerCase('tr-TR')` ile normalleştirilir.

---

### 6.3 Kolon Ayarları (Settings Dialog)

- Kolon Ayarlarını Düzenlemek için gerekli modal, tabloda sağ üst köşede yer alan "Ayarlar" ikonuyla açılır.
- `visibility` state'i kolonların görünürlüğünü tutar.
- İlk açılışta, `allColumns` içindeki kolonlar `true` olarak initialize edilir.
- Checkbox ile kolonları gizleyip gösterebilirsin.
- "Sıfırla" hepsini tekrar `true` yapar.

---

### 6.4 Excel Export

- Tabloda sağ üst köşede yer alan "Excel İndir" butonu, `downloadTableAsXlsx` ile export eder.

**Export edilecek kolonlar:**
- `field` boş olanlar export edilmez
- `field` `__` ile başlıyorsa export edilmez (internal kolon standardı)
- ayrıca `__detail` explicit olarak hariç tutulur

**Dosya adı:**
- `title` string ise: `${title}-YYYY-MM-DD.xlsx`
- değilse: `Veri Seti-YYYY-MM-DD.xlsx`

> Proje bazında "Veri Seti" olarak belirtilen kısım özelleştirilebilir.


---

### 6.5 Detay Kolonu + Modal

- Component her zaman tabloda en sola `__detail` kolonu ekler.
- Detay ikonuna tıklanınca `DetailModal` açılır.
- Şu an Detay modal içeriği Header, Footer ve boş bırakılan body alanından oluşmaktadır. Sınırlandırmamak ve özelleştirme yapmak amacıyla body boş bırakılmıştır.

> **Projeler için önerilen yaklaşım:** Proje bazında içeriğe uygun olarak custom componentlar veya widgetlar kullanılabilir.

---

## 7) Kolon Konvansiyonları (Ekip Standardı)

Bu kütüphanenin sürdürülebilir olması için proje ekiplerine belirtilen yapıya uyması önerilmektedir:

- **Internal kolonlar `__` ile başlasın**
  Örn: `__actions`, `__statusIcon`
  → Excel export'a dahil edilmez.

- **Excel'e gitmesi istenen kolonlar** `field`'ı gerçek data alanı olmalı.

- **Numeric alanlar için öneri:**
  ```tsx
  { field: "amount", headerName: "Tutar", align: "left", headerAlign: "left" }