# LivaMonthAdjustPopup
Package: @dataliva/livalib
Description: @dataliva/livalib aylık bütçe değerlerini toplu ayarlama popup'ı.

Dataliva'ya özgü, 12 aylık bütçe satırındaki değerleri toplu olarak artırıp
azaltmaya yarayan popup. Bir satır ve ay kolonu için
`createMonthAdjustSession` ile oturum oluşturulur; popup her ay için mevcut
tutarı ve düzenlenebilir bir ayar kolonu gösterir. **Uygula** düğmesi taslak
değerleri `onApply` ile geri verir, yeni tutarlar `applyMonthAdjustSession`
ile hesaplanır. İki mod vardır:

- `cumulative` — satırdaki tüm aylar listelenir; varsayılan ayar tipi
  `percent`'tir (100 = değişiklik yok, 110 = yüzde 10 artış).
- `single` — yalnızca tıklanan ayın satırı listelenir; varsayılan ayar tipi
  `amount`'tır (0 = değişiklik yok, pozitif/negatif tutar eklenir).

```tsx
import {
  LivaMonthAdjustPopup,
  createMonthAdjustSession,
  applyMonthAdjustSession,
  sumMonthValues,
  STANDARD_MONTH_FIELDS,
  type MonthAdjustSession,
  type LivaMonthAdjustSummaryField,
} from "@dataliva/livalib";
```

## Kümülatif yüzde ayarı

Düğmeye tıklayınca 12 ayın tamamı için yüzde bazlı ayar oturumu açılır.
Örneğin bir aya 110 yazıp uyguladığınızda o ayın tutarı yüzde 10 artar;
100 bırakılan aylar değişmez. `summaryFields` popup başlığının altında
hesap/departman gibi satır bilgilerini rozet olarak gösterir
(`stripLeadingAccountCode` baştaki "770 -" benzeri hesap kodunu ayıklar).

**Örnek — Kümülatif yüzde ayarı:**

```tsx
const [satir, setSatir] = useState<ButceSatiri>({
  hesapAdi: "770 - Pazarlama Giderleri",
  departman: "Pazarlama",
  V001: 12000, V002: 12500, /* ... */ V012: 16000,
});
const [oturum, setOturum] = useState<MonthAdjustSession | null>(null);

<LivaButton
  text="Tüm Yılı Ayarla (%)"
  onClick={() =>
    setOturum(
      createMonthAdjustSession({
        rowId: "1",
        rowData: satir,
        columnField: "V001",
        mode: "cumulative", // adjustType varsayılanı: "percent"
      })
    )
  }
/>

{oturum && (
  <LivaMonthAdjustPopup
    session={oturum}
    monthFields={STANDARD_MONTH_FIELDS}
    monthCaptions={AY_BASLIKLARI}
    summaryFields={ozetAlanlari}
    onApply={(taslakDegerler) => {
      const guncellemeler = applyMonthAdjustSession(
        { ...oturum, draftValues: taslakDegerler },
        STANDARD_MONTH_FIELDS
      );
      setSatir((onceki) => ({ ...onceki, ...guncellemeler }));
      setOturum(null);
    }}
    onCancel={() => setOturum(null)}
  />
)}
```

## Tek ay tutar ayarı

`mode: "single"` yalnızca `columnField` ile verilen ayı düzenler; girilen
tutar mevcut değere eklenir (negatif değer azaltır). Gerçek uygulamada bu
oturum, grid hücresinin sağ tık menüsünden tıklanan kolona göre açılır.

**Örnek — Tek ay tutar ayarı:**

```tsx
<LivaButton
  text="Mart Ayını Ayarla (Tutar)"
  variant="outlined"
  onClick={() =>
    setOturum(
      createMonthAdjustSession({
        rowId: "2",
        rowData: satir,
        columnField: "V003", // Mart
        mode: "single",
        adjustType: "amount",
      })
    )
  }
/>

{oturum && (
  <LivaMonthAdjustPopup
    session={oturum}
    monthFields={STANDARD_MONTH_FIELDS}
    monthCaptions={AY_BASLIKLARI}
    summaryFields={ozetAlanlari}
    onApply={(taslakDegerler) => {
      const guncellemeler = applyMonthAdjustSession(
        { ...oturum, draftValues: taslakDegerler },
        STANDARD_MONTH_FIELDS
      );
      setSatir((onceki) => ({ ...onceki, ...guncellemeler }));
      setOturum(null);
    }}
    onCancel={() => setOturum(null)}
  />
)}
```

## Yardımcı fonksiyonlar

Popup, `utils/monthAdjust` modülündeki yardımcılarla birlikte çalışır;
tümü paket kökünden dışa aktarılır:

| Fonksiyon / Sabit | Açıklama |
|------|------|
| `STANDARD_MONTH_FIELDS` | Standart ay alanları: `["V001", "V002", …, "V012"]` |
| `MONTH_FIELD_PATTERN` | Ay alanı deseni: `/^[vV]\d{3}$/` |
| `createMonthAdjustSession(params)` | Satır, kolon ve moddan `MonthAdjustSession` üretir |
| `applyMonthAdjustSession(session, monthFields)` | Taslak değerlerden `alan → yeni tutar` haritası hesaplar |
| `sumMonthValues(rowData, monthFields, updates)` | Güncellemeler uygulanmış yıllık toplamı verir |
| `getAffectedMonthIndices(mode, columnField, monthFields)` | Moda göre etkilenecek ay indekslerini verir |
| `getDefaultMonthAdjustDraftValues(adjustType)` | Başlangıç taslağı: percent için 100, amount için 0 |
| `getRowFieldValue(row, fieldName)` | Alan adını büyük/küçük harf duyarsız çözerek değeri okur |
| `resolveMonthFieldsFromColumns(columns)` | Grid kolon tanımlarından ay alanlarını çıkarır |

`LivaDataGrid` bileşeni bu akışı `monthAdjustOptions` prop'uyla hazır
olarak sunar; bu sayfadaki gibi elle oturum yönetimi yalnızca özel
senaryolarda gerekir.

## MonthAdjustSession

```ts
type MonthAdjustSession = {
  rowId: string;
  rowData: Record<string, unknown>;
  columnField: string;            // oturum oluşturulurken büyük harfe çevrilir
  mode: "single" | "cumulative";
  adjustType: "percent" | "amount";
  draftValues: number[];          // 12 elemanlı taslak dizisi
};
```

## Prop'lar

| Prop | Tip | Varsayılan |
|------|------|---------|
| `session` | `MonthAdjustSession` | — |
| `monthFields` | `string[]` | — |
| `monthCaptions` | `string[]` | — |
| `summaryFields` | `LivaMonthAdjustSummaryField[]` | `[]` |
| `onApply` | `(draftValues: number[]) => void` | — |
| `onCancel` | `() => void` | — |

`LivaMonthAdjustSummaryField` alanları: `label` (rozet etiketi),
`fieldNames` (sırayla denenecek satır alanları), `fallback` (değer
bulunamazsa gösterilecek metin), `stripLeadingAccountCode` (baştaki hesap
kodunu ayıklar), `wide` (rozeti geniş gösterir). Popup her render
edildiğinde açık gelir; kapatma davranışı `onCancel` üzerinden koşullu
render ile yönetilir.