@konce-pt/angular 0.7.10 → 0.7.12

package/src/lib/data-table/llms.txt

@@ -1,91 +1,91 @@
 # KptDataTable (kpt-data-table)
 
-Flagowa tabela danych: kolumny konfiguracją, sortowanie, filtr globalny,
-paginacja, zaznaczanie wierszy i własne szablony komórek. Sygnałowa, OnPush.
+The flagship data table: columns from configuration, sorting, a global filter,
+pagination, row selection and custom cell templates. Signal-based, OnPush.
 Import: `import { KptDataTable, KptColumn, KptCellDef, KptCellEditDef, KptRowDetailDef } from '@konce-pt/angular';`
 
-## Selektor
+## Selector
 `kpt-data-table`
 
-## Model kolumny (KptColumn)
+## The column model (KptColumn)
 `{ field: string; header: string; sortable?: boolean; align?: 'start'|'center'|'end'; width?: string; frozen?: boolean; filter?: KptColumnFilter; edit?: KptColumnEdit; summary?: KptColumnSummary }`
-Kolumny `frozen` (wiodące, sąsiadujące) przyklejają się przy poziomym przewijaniu — wymagają `width`.
+`frozen` columns (leading, adjacent) stick during horizontal scrolling — they require `width`.
 
-### Filtr kolumny (KptColumnFilter)
+### The column filter (KptColumnFilter)
 `{ type: 'text'|'number'|'select'|'dateRange'|'numberRange'|'slider'; options?: KptOption[]; multiple?: boolean; placeholder?: string; min?: number; max?: number; step?: number }`
-Gdy którakolwiek kolumna ma `filter`, w nagłówku renderuje się wiersz filtrów:
-- `text` — input tekstowy (dopasowanie „zawiera"), `number` — input tylko cyfry (dopasowanie po cyfrach),
-- `select` — lista wyboru (z `multiple` = wiele; dopasowanie OR). Gdy wartość pola jest **tablicą** (np. lista tagów/członków), dopasowuje, gdy tablica zawiera dowolną z wybranych wartości,
-- `numberRange` — dwa pola (min–max); dopasowuje, gdy liczbowa wartość pola mieści się w zakresie (puste ograniczenie = otwarte),
-- `slider` — suwak zakresu (dwa uchwyty; `min`/`max`/`step`); wartość filtra to `[lo, hi]`, dopasowuje liczbę w `[lo, hi]`,
-- `dateRange` — zakres dat (pole ISO/Date w `[start,end]`).
-Filtry kolumn łączą się AND ze sobą i z filtrem globalnym; zmiana resetuje stronę.
-Filtry działają na **surowej wartości pola** (`row[field]`), niezależnie od własnego szablonu `kptCell` — można filtrować także kolumny z custom cell (np. status-badge).
-Filtry `select`/`dateRange` wymagają `import '@angular/cdk/overlay-prebuilt.css';`.
-
-### Edycja kolumny (KptColumnEdit)
+As soon as any column has a `filter`, a filter row is rendered in the header:
+- `text` — a text input ("contains" matching), `number` — a digits-only input (matching on digits),
+- `select` — a selection list (with `multiple` = many; OR matching). When the field's value is an **array** (a list of tags or members, say), it matches when the array contains any of the selected values,
+- `numberRange` — two fields (min–max); it matches when the field's numeric value falls inside the range (an empty bound = open),
+- `slider` — a range slider (two handles; `min`/`max`/`step`); the filter value is `[lo, hi]`, matching a number inside `[lo, hi]`,
+- `dateRange` — a date range (an ISO/Date field within `[start,end]`).
+Column filters combine with AND, both with each other and with the global filter; a change resets the page.
+Filters work on the **raw field value** (`row[field]`), regardless of any custom `kptCell` template — so columns with a custom cell (a status badge, for instance) can be filtered too.
+The `select`/`dateRange` filters require `import '@angular/cdk/overlay-prebuilt.css';`.
+
+### Column editing (KptColumnEdit)
 `{ type: 'text'|'number'|'date'|'select'|'multiselect'; options?: KptOption[]; placeholder?: string; min?: number; max?: number; step?: number }`
-Gdy kolumna ma `edit`, jej komórki są klikalne — klik (albo Enter na sfokusowanej komórce) zamienia
-wartość na kontrolkę: `text` → `kpt-input`, `number` → `kpt-input-number`, `date` → `kpt-datepicker`,
-`select` → `kpt-select`, `multiselect` → `kpt-select multiple filter`. Patrz sekcja „Edycja inline” niżej.
+When a column has `edit`, its cells become clickable — a click (or Enter on a focused cell) swaps
+the value for a control: `text` → `kpt-input`, `number` → `kpt-input-number`, `date` → `kpt-datepicker`,
+`select` → `kpt-select`, `multiselect` → `kpt-select multiple filter`. See the "Inline editing" section below.
 
-### Podsumowanie kolumny (KptColumnSummary)
+### The column summary (KptColumnSummary)
 `{ fn: 'sum'|'avg'|'min'|'max'|'count' | ((rows) => unknown); format?: (value) => string }`
-Kolumna z `summary` jest agregowana w wierszu podsumowania — patrz sekcja „Wiersz podsumowania” niżej.
-
-## Wejścia
-- `columns`: KptColumn[] (wymagane)
-- `data`: T[] (domyślnie [])
-- `filterable`: boolean — pole filtra globalnego
-- `filterRowPosition`: 'top' | 'bottom' (domyślnie 'bottom') — wiersz filtrów kolumn nad/pod etykietami
-- `pageSize`: number — 0 wyłącza paginację
-- `pageSizeOptions`: number[] (domyślnie [5,10,20,50])
+A column with `summary` is aggregated in the summary row — see the "Summary row" section below.
+
+## Inputs
+- `columns`: KptColumn[] (required)
+- `data`: T[] (default [])
+- `filterable`: boolean — the global filter field
+- `filterRowPosition`: 'top' | 'bottom' (default 'bottom') — the column filter row above/below the labels
+- `pageSize`: number — 0 disables pagination
+- `pageSizeOptions`: number[] (default [5,10,20,50])
 - `selectable`: 'none' | 'single' | 'multiple'
-- `loading`: boolean — wiersz „Ładowanie…"
-- `emptyMessage`: string — bez wartości używa i18n (`dataTable.empty`); input ma priorytet
-- `rowKey`: string | null — pole identyfikujące wiersz (dla zaznaczania); bez niego porównanie po referencji
-- `reorderable`: boolean — przestawianie kolumn przeciągnij-i-upuść (natywny HTML5 DnD); kolumny `frozen` są wyłączone z przenoszenia (pozostają wiodące) i nie można upuszczać innych kolumn przed nie
-- `exportable`: boolean — przycisk „Eksport CSV" w toolbarze
-- `exportFilename`: string (domyślnie 'export.csv')
-- `lazy`: boolean — tryb serwerowy (bez filtr/sort/paginacji po stronie klienta)
-- `totalRecords`: number | null — łączna liczba rekordów (wymagane przy lazy)
-- `scrollHeight`: string | null — wysokość przewijalnego obszaru (np. '400px'); sticky header pozostaje
-- `virtualScroll`: boolean — wirtualizacja wierszy (renderuje tylko widoczne); wymaga `scrollHeight`
-- `rowHeight`: number — stała wysokość wiersza w px (domyślnie 41), potrzebna przy virtualScroll
-- `expandable`: boolean — kolumna z przełącznikiem rozwijającym wiersz (renderuje szablon `kptRowDetail`)
-- `multiExpand`: boolean (domyślnie true) — pozwala rozwinąć wiele wierszy naraz; false = tylko jeden
-- `summaryLabel`: string — etykieta wiersza podsumowania; bez wartości używa i18n (`dataTable.total`)
-- `summaryValues`: Record<string, unknown> | null — gotowe wartości podsumowania (pole → wartość);
-  nadpisują wyliczenia, przy `lazy` są jedynym źródłem
-
-## Model / zdarzenia
-- `selection`: model<T[]> — dwukierunkowe `[(selection)]`
-- `expandedRows`: model<T[]> — dwukierunkowe `[(expandedRows)]` (rozwinięte wiersze)
-- `hiddenFields`: model<readonly string[]> — dwukierunkowe `[(hiddenFields)]`; zbiór `KptColumn.field`
-  aktualnie ukrytych. Komponent sam nie dostarcza UI do zarządzania tym stanem (bez przycisku,
-  bez dialogu, bez persystencji) — to celowo minimalny hak do podpięcia zewnętrznego przełącznika
-  kolumn. Przykład gotowego UI (przycisk + dialog z checkboxami + zapis w localStorage), zbudowany
-  z `kpt-dialog`/`kpt-checkbox`/`kpt-button`, jest w playground jako `pg-column-toggle`
-  (`apps/playground/src/pg-column-toggle.component.ts`) — nie jest eksportowany z biblioteki.
-  Ukrycie kolumny nie wyłącza jej z globalnego wyszukiwania ani z filtrów per-kolumna — tylko
-  z widoku (i z eksportu CSV, patrz niżej). Kolejność zapamiętana przez `reorderable` przetrwa
-  ukrycie/pokazanie kolumny. Do umieszczenia kompaktowej (ikonowej) wersji takiego przycisku
-  obok paginatora służy slot projekcji `[kptPaginatorActions]` — patrz sekcja „Wiersz
-  paginatora” niżej.
+- `loading`: boolean — a "Loading…" row
+- `emptyMessage`: string — with no value it uses i18n (`dataTable.empty`); the input takes priority
+- `rowKey`: string | null — the field identifying a row (for selection); without it rows are compared by reference
+- `reorderable`: boolean — drag-and-drop column reordering (native HTML5 DnD); `frozen` columns are excluded from moving (they stay leading) and no other column can be dropped in front of them
+- `exportable`: boolean — an "Export CSV" button in the toolbar
+- `exportFilename`: string (default 'export.csv')
+- `lazy`: boolean — server-side mode (no client-side filtering/sorting/pagination)
+- `totalRecords`: number | null — the total record count (required with lazy)
+- `scrollHeight`: string | null — the height of the scrollable area (e.g. '400px'); the sticky header stays
+- `virtualScroll`: boolean — row virtualization (only visible rows are rendered); requires `scrollHeight`
+- `rowHeight`: number — a fixed row height in px (default 41), needed with virtualScroll
+- `expandable`: boolean — a column with a toggle that expands the row (rendering the `kptRowDetail` template)
+- `multiExpand`: boolean (default true) — allows several rows open at once; false = only one
+- `summaryLabel`: string — the summary row's label; with no value it uses i18n (`dataTable.total`)
+- `summaryValues`: Record<string, unknown> | null — ready-made summary values (field → value);
+  they override the computed ones, and with `lazy` they are the only source
+
+## Model / events
+- `selection`: model<T[]> — two-way `[(selection)]`
+- `expandedRows`: model<T[]> — two-way `[(expandedRows)]` (the expanded rows)
+- `hiddenFields`: model<readonly string[]> — two-way `[(hiddenFields)]`; the set of `KptColumn.field`
+  values currently hidden. The component provides no UI for managing that state itself (no button,
+  no dialog, no persistence) — it is a deliberately minimal hook for wiring up an external column
+  switcher. An example of a finished UI (a button + a dialog with checkboxes + localStorage persistence), built
+  from `kpt-dialog`/`kpt-checkbox`/`kpt-button`, lives in the playground as `pg-column-toggle`
+  (`apps/playground/src/pg-column-toggle.component.ts`) — it is not exported from the library.
+  Hiding a column does not take it out of the global search or the per-column filters — only
+  out of the view (and out of the CSV export, see below). The order remembered by `reorderable` survives
+  hiding and showing a column. To place a compact (icon) version of such a button
+  next to the paginator there is the `[kptPaginatorActions]` projection slot — see the "The paginator
+  row" section below.
 - `rowClick`: output<T>
-- `lazyLoad`: output<KptTableLazyState> — { pageIndex, pageSize, sortField, sortDir, filter, columnFilters }; emitowane w trybie lazy przy każdej zmianie stanu
-- `cellEdit`: output<KptCellEditEvent<T>> — `{ row, field, value, updatedRow }`; emitowane po
-  zatwierdzeniu edycji komórki (patrz „Edycja inline” niżej), tylko gdy wartość faktycznie się
-  zmieniła. Tabela sama niczego nie zapisuje (brak HTTP, brak stanu ładowania/błędu) — `updatedRow`
-  to gotowe body żądania, resztą (zapis, optymistyczna aktualizacja, rollback przy błędzie) zajmuje
-  się konsument, dokładnie jak przy `lazyLoad`.
+- `lazyLoad`: output<KptTableLazyState> — { pageIndex, pageSize, sortField, sortDir, filter, columnFilters }; emitted in lazy mode on every state change
+- `cellEdit`: output<KptCellEditEvent<T>> — `{ row, field, value, updatedRow }`; emitted once a cell
+  edit is committed (see "Inline editing" below), and only when the value actually
+  changed. The table saves nothing itself (no HTTP, no loading/error state) — `updatedRow`
+  is a ready request body, and the rest (saving, an optimistic update, a rollback on error) is handled
+  by the consumer, exactly as with `lazyLoad`.
 
-## Eksport / metody
-- `exportCsv()`: publiczna metoda — eksportuje bieżące (filtr+sort) dane do CSV (separator `;`, BOM dla
-  Excela). Eksportuje tylko aktualnie **widoczne** kolumny (bez tych w `hiddenFields`).
+## Export / methods
+- `exportCsv()`: a public method — exports the current (filtered+sorted) data to CSV (the `;` separator, a BOM for
+  Excel). It exports only the currently **visible** columns (those in `hiddenFields` are left out).
 
-## Własne szablony komórek (dyrektywa kptCell)
-Kontekst: `$implicit` = wiersz, `value` = wartość pola.
+## Custom cell templates (the kptCell directive)
+Context: `$implicit` = the row, `value` = the field's value.
 
     <kpt-data-table [columns]="cols" [data]="rows" filterable [pageSize]="10"
                     selectable="multiple" rowKey="id" [(selection)]="picked">
@@ -94,48 +94,48 @@ Kontekst: `$implicit` = wiersz, `value` = wartość pola.
       </ng-template>
     </kpt-data-table>
 
-## Rozwijane wiersze (dyrektywa kptRowDetail)
-Włącz `expandable` i podaj szablon `kptRowDetail` (kontekst: `$implicit` = wiersz).
-Dodaje wiodącą kolumnę z przełącznikiem; rozwinięty wiersz renderuje szablon w pełnej szerokości pod wierszem.
-Stan przez `[(expandedRows)]`; `multiExpand=false` ogranicza do jednego otwartego naraz.
-Niezależne od `selectable` (można łączyć z zaznaczaniem). Nieaktywne przy `virtualScroll`.
+## Expandable rows (the kptRowDetail directive)
+Turn on `expandable` and supply a `kptRowDetail` template (context: `$implicit` = the row).
+It adds a leading column with a toggle; an expanded row renders the template at full width below the row.
+The state goes through `[(expandedRows)]`; `multiExpand=false` limits it to one open at a time.
+Independent of `selectable` (it can be combined with selection). Not available with `virtualScroll`.
 
     <kpt-data-table [columns]="cols" [data]="rows" expandable rowKey="id" [(expandedRows)]="open">
       <ng-template kptRowDetail let-row>
-        <div class="detale">{{ row.opis }}</div>
+        <div class="details">{{ row.description }}</div>
       </ng-template>
     </kpt-data-table>
 
-## Edycja inline (column.edit / kptCellEdit)
-Klik w komórkę edytowalnej kolumny (albo Enter, gdy komórka ma fokus — jest wtedy `tabindex="0"`)
-zamienia jej wartość na kontrolkę z `column.edit.type`. Zatwierdzanie zależy od rodzaju kontrolki:
-
-- `text`/`number` (`kpt-input`, `kpt-input-number`) — brak overlaya, więc zatwierdza wyjście fokusu
-  **poza cały edytor** (`focusout` z kontrolą `relatedTarget`) albo Enter; Escape odrzuca zmianę.
-  Świadomie nie na `touch`/blur samej kontrolki: `kpt-input-number` ma fokusowalne strzałki `+`/`-`
-  obok pola (i jeszcze emituje `touch` w `step_()`), więc każde kliknięcie strzałki zamykałoby
-  edycję, zanim zdąży zmienić wartość.
-- `date`/`select`/`multiselect` (`kpt-datepicker`, `kpt-select`) — panel otwiera się **od razu** po
-  kliknięciu komórki, a zatwierdzenie następuje przy jego **zamknięciu**: wybór wartości (single),
-  klik poza panelem albo Escape. W `multiselect` zaznaczanie kolejnych opcji nie zatwierdza nic po
-  drodze — panel zostaje otwarty, aż user kliknie poza nim, i wtedy leci jedno zdarzenie z pełną listą.
-
-Tabela **nigdzie nie zatwierdza na `touch`** — i nie należy tego przywracać. `touch` w tych
-kontrolkach nie znaczy „user skończył": leci z blur triggera (a panel żyje w kontenerze CDK Overlay
-przy `<body>`, więc naciśnięcie myszy na opcji/dniu blurruje trigger) i dodatkowo ze `step_()`
-w `kpt-input-number`. Zatwierdzanie na `touch` niszczyło edytor razem z panelem, zanim kliknięcie
-zdążyło wybrać wartość. Zamiast tego: edytory overlayowe wiążą się z `open` (`[open]`/`(openChange)`),
-a pozostałe z `focusout` na całym edytorze (fokus przeniesiony wewnątrz edytora nie zatwierdza).
-
-**Ograniczenie**: dla edytorów overlayowych Escape **zatwierdza** (zamyka panel), a nie odrzuca —
-klawiaturę panelu obsługują wewnętrznie `kpt-select`/`kpt-datepicker`, a keydown z overlaya nie
-dociera do komórki. Escape odrzuca zmianę tylko w `text`/`number`.
-
-Wartości porównywane są przed emisją: `cellEdit` nie leci, gdy user otworzył i zamknął panel bez
-zmiany, ani gdy w `multiselect` wróci do tego samego zestawu (tablice porównywane po zawartości).
-
-Gdy 5 wbudowanych typów nie wystarcza, dyrektywa `kptCellEdit` daje pełny, własny edytor. Kontekst:
-`$implicit` = bieżąca wartość, `row` = wiersz, `commit(value)` = zatwierdź i zamknij, `cancel()` = odrzuć.
+## Inline editing (column.edit / kptCellEdit)
+Clicking a cell in an editable column (or pressing Enter while the cell has focus — it carries `tabindex="0"` then)
+swaps its value for a control from `column.edit.type`. How it commits depends on the kind of control:
+
+- `text`/`number` (`kpt-input`, `kpt-input-number`) — there is no overlay, so it commits when focus leaves
+  **the whole editor** (`focusout` with a `relatedTarget` check) or on Enter; Escape discards the change.
+  Deliberately not on the control's own `touch`/blur: `kpt-input-number` has focusable `+`/`-` arrows
+  next to the field (and it also emits `touch` in `step_()`), so every arrow click would close
+  the edit before it had a chance to change the value.
+- `date`/`select`/`multiselect` (`kpt-datepicker`, `kpt-select`) — the panel opens **immediately** after
+  the cell is clicked, and the commit happens when it **closes**: picking a value (single),
+  a click outside the panel or Escape. In `multiselect`, ticking further options commits nothing along
+  the way — the panel stays open until the user clicks outside it, and then a single event fires with the full list.
+
+The table **never commits on `touch`** — and that must not be reinstated. `touch` in these
+controls does not mean "the user is done": it fires on the trigger's blur (and the panel lives in a CDK Overlay
+container next to `<body>`, so pressing the mouse on an option/day blurs the trigger) and, on top of that, from `step_()`
+in `kpt-input-number`. Committing on `touch` destroyed the editor together with the panel before the click
+had a chance to pick a value. Instead: overlay editors bind to `open` (`[open]`/`(openChange)`),
+and the rest to `focusout` on the whole editor (focus moved within the editor does not commit).
+
+**A limitation**: for overlay editors Escape **commits** (it closes the panel) rather than discarding —
+the panel's keyboard handling lives inside `kpt-select`/`kpt-datepicker`, and a keydown from the overlay does not
+reach the cell. Escape discards a change only in `text`/`number`.
+
+Values are compared before emitting: `cellEdit` does not fire when the user opened and closed a panel without
+a change, nor when a `multiselect` returns to the same set (arrays are compared by content).
+
+When the 5 built-in types are not enough, the `kptCellEdit` directive gives you a full custom editor. Context:
+`$implicit` = the current value, `row` = the row, `commit(value)` = commit and close, `cancel()` = discard.
 
     <kpt-data-table [columns]="cols" [data]="rows" rowKey="id" (cellEdit)="onCellEdit($event)">
       <ng-template kptCellEdit="team" let-value let-commit="commit">
@@ -143,84 +143,84 @@ Gdy 5 wbudowanych typów nie wystarcza, dyrektywa `kptCellEdit` daje pełny, wł
       </ng-template>
     </kpt-data-table>
 
-## Wiersz podsumowania (column.summary)
-Kolumny z `summary` renderują `<tfoot>` — ostatni wiersz tabeli, **nad paginatorem**, przyklejony
-do dołu obszaru przewijania (`position: sticky; bottom: 0`, jak sticky header).
-
-- **Etykieta** (`summaryLabel`, domyślnie i18n `dataTable.total` → „Total”/„Razem”) renderuje się
-  w jednej komórce scalonej (`colspan`) od początku wiersza do pierwszej liczonej kolumny,
-  wyrównana do prawej. Colspan obejmuje też kolumny systemowe (rozwijanie, zaznaczanie).
-  Przykład: `summary` na 3. kolumnie → scalone kolumny 1–2. Gdy liczona jest **pierwsza** widoczna
-  kolumna (i nie ma kolumn systemowych), etykieta nie ma się gdzie zmieścić i nie renderuje się.
-- **Zakres**: agregacja obejmuje **wszystkie wiersze po filtrach** — całą stronę 1 i każdą następną,
-  nie tylko widoczną. Filtr globalny i filtry kolumn zawężają zbiór (zgodnie z licznikiem paginatora),
-  sortowanie i strona nie zmieniają wyniku.
-- **Na żywo przy edycji inline**: `data` jest zwykłym inputem, więc gdy konsument po `cellEdit`
-  podmieni tablicę w sygnale, podsumowanie przelicza się samo (zwykły `computed`).
-- **Agregacje**: `sum`, `avg`, `min`, `max`, `count`. `count` liczy wiersze; pozostałe pomijają
-  wartości nieliczbowe (string z liczbą jest parsowany). Pusty zbiór: `sum` = 0, reszta — pusta
-  komórka. `sum`/`avg` przycinają ogony zmiennoprzecinkowe (bez tego `0.1+0.2` = `0.30000000000000004`).
-  Własna funkcja `fn: (rows) => unknown` dostaje ten sam zbiór (np. suma ważona).
-- **Formatowanie**: `format: (value) => string` (np. `Intl.NumberFormat`); bez niego wartość leci
-  surowa. Komórki podsumowania są domyślnie do prawej — jawne `align` kolumny ma priorytet.
-  Etykieta wiersza („Razem”) jest jedna na cały wiersz, więc kolumnę liczoną inaczej niż sumą
-  (`avg`, `min`, `max`) nazwij w `format` (np. `ø 662,57 zł`) — inaczej czyta się jak suma.
-- **Ukryte kolumny** (`hiddenFields`) wypadają też z podsumowania; kolejność po `reorderable`
-  jest respektowana (etykieta scala się do aktualnie pierwszej liczonej kolumny).
-- **Tryb `lazy`**: tabela ma tylko bieżącą stronę, więc nie liczy nic sama — podaj `summaryValues`
-  (pole → gotowa wartość z serwera). `summaryValues` działa też poza `lazy`, nadpisując wyliczenia.
-  Kolumna wymieniona wyłącznie w `summaryValues` (bez `summary`) też pokazuje wartość.
-- Wiersz nie renderuje się przy `loading` ani gdy tabela jest pusta (nie dublujemy komunikatu stanu).
-- Eksport CSV **nie zawiera** wiersza podsumowania — `exportCsv()` eksportuje same dane.
+## The summary row (column.summary)
+Columns with a `summary` render a `<tfoot>` — the table's last row, **above the paginator**, stuck
+to the bottom of the scrolling area (`position: sticky; bottom: 0`, like the sticky header).
+
+- **The label** (`summaryLabel`, i18n `dataTable.total` by default → "Total"/"Razem") is rendered
+  in one merged cell (`colspan`) reaching from the start of the row to the first aggregated column,
+  right-aligned. The colspan also covers the system columns (expand, select).
+  For example: a `summary` on the 3rd column → columns 1–2 merged. When the **first** visible
+  column is the aggregated one (and there are no system columns), the label has nowhere to fit and is not rendered.
+- **The scope**: the aggregation covers **every row after filtering** — the whole of page 1 and every following one,
+  not just what is visible. The global filter and the column filters narrow the set (in step with the paginator's counter),
+  while sorting and the current page do not change the result.
+- **Live under inline editing**: `data` is an ordinary input, so once the consumer swaps the array in a signal
+  after `cellEdit`, the summary recomputes itself (a plain `computed`).
+- **Aggregations**: `sum`, `avg`, `min`, `max`, `count`. `count` counts rows; the rest skip
+  non-numeric values (a string holding a number is parsed). On an empty set: `sum` = 0, the rest — an empty
+  cell. `sum`/`avg` trim floating-point tails (without that `0.1+0.2` = `0.30000000000000004`).
+  A custom `fn: (rows) => unknown` receives the same set (a weighted sum, for instance).
+- **Formatting**: `format: (value) => string` (`Intl.NumberFormat`, say); without it the value goes out
+  raw. Summary cells are right-aligned by default — an explicit column `align` takes priority.
+  The row label ("Total") is one for the whole row, so name a column aggregated by anything other than a sum
+  (`avg`, `min`, `max`) inside `format` (e.g. `ø 662.57 USD`) — otherwise it reads as a sum.
+- **Hidden columns** (`hiddenFields`) drop out of the summary too; the order after `reorderable`
+  is respected (the label merges up to whatever is now the first aggregated column).
+- **`lazy` mode**: the table only holds the current page, so it computes nothing itself — supply `summaryValues`
+  (field → a ready value from the server). `summaryValues` also works outside `lazy`, overriding the computed values.
+  A column listed only in `summaryValues` (with no `summary`) shows a value too.
+- The row is not rendered while `loading`, nor when the table is empty (we do not duplicate the state message).
+- The CSV export **does not include** the summary row — `exportCsv()` exports the data alone.
 
     cols = [
-      { field: 'product', header: 'Produkt' },
-      { field: 'qty', header: 'Ilość', align: 'end', summary: { fn: 'sum' } },
-      { field: 'net', header: 'Netto', align: 'end', summary: { fn: 'sum', format: pln } },
+      { field: 'product', header: 'Product' },
+      { field: 'qty', header: 'Quantity', align: 'end', summary: { fn: 'sum' } },
+      { field: 'net', header: 'Net', align: 'end', summary: { fn: 'sum', format: usd } },
     ];
 
     <kpt-data-table [columns]="cols" [data]="rows()" [pageSize]="5" rowKey="id"
-                    summaryLabel="Razem" (cellEdit)="onCellEdit($event)" />
+                    summaryLabel="Total" (cellEdit)="onCellEdit($event)" />
 
-## Zachowanie
-- Sortowanie: klik w nagłówek sortowalnej kolumny cyklicznie asc → desc → brak.
-- Filtr: dopasowanie tekstu we wszystkich polach kolumn; reset strony do 0.
-- Zaznaczanie 'multiple': nagłówkowy checkbox zaznacza/odznacza bieżącą stronę.
-- Sticky header, stany pusty/ładowanie, wyrównanie i szerokości per kolumna.
+## Behavior
+- Sorting: clicking a sortable column's header cycles asc → desc → none.
+- Filtering: text matching across every column field; the page resets to 0.
+- 'multiple' selection: the header checkbox selects/deselects the current page.
+- A sticky header, empty/loading states, per-column alignment and widths.
 
 ## i18n
-Etykiety toolbaru/stanów/aria (Szukaj, Eksport CSV, Ładowanie, Brak danych, zaznaczanie, filtry kolumn:
-Filtr/Filtr min/Filtr max z `{column}`, Wszystkie, min, max, Zakres dat) pochodzą z i18n (namespace `dataTable`).
-Domyślnie EN; konfiguracja przez `provideKptI18n` — patrz `i18n/llms.txt`.
-
-## Wiersz paginatora (slot [kptPaginatorActions])
-Wiersz z `kpt-paginator` (renderowany gdy `pageSize > 0` i bez `virtualScroll`) to flex
-z opcjonalnym slotem projekcji po lewej stronie: `<div kptPaginatorActions>…</div>` wstawione
-jako zawartość `kpt-data-table` renderuje się przed paginatorem, w tym samym wierszu (`kpt-paginator`
-ma `flex: 1 1 auto` i własne `justify-content: flex-end` — bez projekcji zachowuje się identycznie
-jak wcześniej, w pełni po prawej). Miejsce na kompaktowy (ikonowy) przycisk dostosowywania kolumn —
-patrz `hiddenFields` wyżej i przykład `pg-column-toggle` w playground.
+The toolbar/state/aria labels (Search, Export CSV, Loading, No data, selection, the column filters:
+Filter/Filter min/Filter max with `{column}`, All, min, max, Date range) come from i18n (the `dataTable` namespace).
+English by default; configured through `provideKptI18n` — see `i18n/llms.txt`.
+
+## The paginator row (the [kptPaginatorActions] slot)
+The row holding `kpt-paginator` (rendered when `pageSize > 0` and there is no `virtualScroll`) is a flex
+container with an optional projection slot on the left: a `<div kptPaginatorActions>…</div>` placed
+as content of `kpt-data-table` renders before the paginator, in the same row (`kpt-paginator`
+has `flex: 1 1 auto` and its own `justify-content: flex-end` — with no projection it behaves exactly
+as it did before, fully to the right). This is the place for a compact (icon) column-customization button —
+see `hiddenFields` above and the `pg-column-toggle` example in the playground.
 
     <kpt-data-table [columns]="cols" [data]="rows" [pageSize]="10" [(hiddenFields)]="hidden">
-      <kpt-icon-button kptPaginatorActions ariaLabel="Kolumny" (click)="open.set(true)">
+      <kpt-icon-button kptPaginatorActions ariaLabel="Columns" (click)="open.set(true)">
         <kpt-icon name="adjustments-horizontal" />
       </kpt-icon-button>
     </kpt-data-table>
 
-## Tokeny
+## Tokens
 `--kpt-table-{bg,fg,border,radius,header-bg,header-fg,row-hover,row-selected,cell-padding}`.
-Rozwijany wiersz: `--kpt-table-detail-bg` (fallback: surface-variant → row-hover).
-Wiersz podsumowania: `--kpt-table-summary-bg` (fallback: header-bg).
-Paginacja: komponent `kpt-paginator`.
+The expanded row: `--kpt-table-detail-bg` (fallback: surface-variant → row-hover).
+The summary row: `--kpt-table-summary-bg` (fallback: header-bg).
+Pagination: the `kpt-paginator` component.
 
-## Do zrobienia (roadmap)
-Kolumny grupowane.
+## To do (roadmap)
+Grouped columns.
 
-Show/hide kolumn: gotowe (hak `hiddenFields`; UI dostosowywania — patrz sekcja „Model / zdarzenia”
-i przykład `pg-column-toggle` w playground).
+Column show/hide: done (the `hiddenFields` hook; the customization UI — see the "Model / events" section
+and the `pg-column-toggle` example in the playground).
 
-Edycja komórek inline: gotowe (`column.edit` + `cellEdit` + `kptCellEdit`; zapis do API —
-patrz przykład w playground, `pg-fake-users-api.ts`).
+Inline cell editing: done (`column.edit` + `cellEdit` + `kptCellEdit`; saving to an API —
+see the playground example, `pg-fake-users-api.ts`).
 
-Wiersz podsumowania: gotowe (`column.summary` + `summaryLabel` + `summaryValues` — patrz sekcja
-„Wiersz podsumowania” i przykład „Inline editing + summary row” w playground).
+The summary row: done (`column.summary` + `summaryLabel` + `summaryValues` — see the
+"The summary row" section and the "Inline editing + summary row" example in the playground).

package/src/lib/data-view/llms.txt

@@ -1,18 +1,18 @@
 # KptDataView (kpt-data-view)
 
-Prezentacja listy elementów w układzie lista/siatka, z opcjonalną paginacją (reuse `kpt-paginator`).
-Szablon elementu przez projekcję `<ng-template let-item>`.
+Presents a list of items in a list or grid layout, with optional pagination (reusing `kpt-paginator`).
+The item template comes through projection: `<ng-template let-item>`.
 Import: `import { KptDataView } from '@konce-pt/angular';`
 
-## Wejścia / model
+## Inputs / model
 - `items`: T[]
-- `layout`: model<'list' | 'grid'> (przełącznik w pasku)
-- `pageSize`: number (0 = bez paginacji); `paginated`: boolean
+- `layout`: model<'list' | 'grid'> (the toggle in the bar)
+- `pageSize`: number (0 = no pagination); `paginated`: boolean
 
-## Przykład
+## Example
     <kpt-data-view [items]="products" [pageSize]="6">
       <ng-template let-p><div>{{ p.name }}</div></ng-template>
     </kpt-data-view>
 
-## Tokeny
-Karty elementów `--kpt-color-surface-raised`; przełącznik `--kpt-color-primary`.
+## Tokens
+Item cards `--kpt-color-surface-raised`; the toggle `--kpt-color-primary`.

package/src/lib/date-range/llms.txt

@@ -1,31 +1,31 @@
 # KptDateRange (kpt-date-range)
 
-Wybór zakresu dat/godzin z kalendarzem (CDK Overlay) na Signal Forms.
-`mode`: 'date' (domyślnie), 'datetime' (data+godzina, tarcza zegara `kpt-clock`), 'time' (sama godzina).
-Wartość `{ start, end }` (KptDateRangeValue): daty 'RRRR-MM-DD', datetime 'RRRR-MM-DDTHH:mm', godziny 'HH:mm'.
+Picking a date/time range with a calendar (CDK Overlay) on Signal Forms.
+`mode`: 'date' (default), 'datetime' (date+time, the `kpt-clock` dial), 'time' (time only).
+The value is `{ start, end }` (KptDateRangeValue): dates 'YYYY-MM-DD', datetime 'YYYY-MM-DDTHH:mm', times 'HH:mm'.
 Import: `import { KptDateRange, KptDateRangeValue } from '@konce-pt/angular';`
-Wymaga `import '@angular/cdk/overlay-prebuilt.css';`
+Requires `import '@angular/cdk/overlay-prebuilt.css';`
 
-## Wejścia / model
-- `value`: model<KptDateRangeValue> (lub `formField`)
-- `mode`: 'date' | 'datetime' | 'time' (domyślnie 'date')
-- `visibleMonths`: number (domyślnie 1, przycinane do 1–3) — liczba miesięcy obok siebie.
-  Strzałki ‹ › stoją na skrajnych panelach i przesuwają całość o jeden miesiąc.
-  Ignorowane w trybie 'time'. Przy >1 dni sąsiednich miesięcy są ukrywane (puste sloty) —
-  inaczej ta sama data byłaby klikalna w dwóch panelach naraz.
-- `hourFormat`: 12 | 24 (domyślnie 24) — tarcza z AM/PM lub 24h; czas zawsze 24h w wartości
-- `minuteStep`: number (domyślnie 1) — snap minut na tarczy
-- `placeholder`: string — bez wartości używa i18n (`dateRange.placeholder`); input ma priorytet
-- `displayFormat`: 'pl' | 'iso' (domyślnie 'pl') — format wyświetlania start/end
+## Inputs / model
+- `value`: model<KptDateRangeValue> (or `formField`)
+- `mode`: 'date' | 'datetime' | 'time' (default 'date')
+- `visibleMonths`: number (default 1, clamped to 1–3) — how many months sit side by side.
+  The ‹ › arrows stand on the outermost panels and move the whole set by one month.
+  Ignored in 'time' mode. With more than one, days from adjacent months are hidden (empty slots) —
+  otherwise the same date would be clickable in two panels at once.
+- `hourFormat`: 12 | 24 (default 24) — an AM/PM or a 24h dial; the value is always 24h
+- `minuteStep`: number (default 1) — minute snapping on the dial
+- `placeholder`: string — with no value it uses i18n (`dateRange.placeholder`); the input takes priority
+- `displayFormat`: 'pl' | 'iso' (default 'pl') — the display format for start/end
 - `disabled`/`invalid`/`touched`: boolean; `touch`: output
 
-## Zachowanie
-Pierwszy klik ustawia `start`, drugi `end` (kolejność normalizowana). „×" czyści.
-Zakres podświetla ciągłe pasmo biegnące przez wszystkie panele: dni skrajne mają plamę
-zaznaczenia, a pasmo wychodzi z ich środka, zaokrąglając się na krańcach wiersza siatki.
-Tryby datetime/time: przełącznik „Od / Koniec" + tarcza zegara, zatwierdzenie przyciskiem „Gotowe".
+## Behavior
+The first click sets `start`, the second `end` (the order is normalized). The "×" clears it.
+The range highlights one continuous band running across every panel: the end days carry the selection
+blob, and the band leaves their center, rounding off at the ends of a grid row.
+The datetime/time modes: a "From / To" toggle + the clock dial, confirmed with the "Done" button.
 
-## Przykład
+## Example
     <kpt-date-range [formField]="f.period" />
     <kpt-date-range [(value)]="period" />
     <kpt-date-range [visibleMonths]="2" [(value)]="period" />
@@ -33,8 +33,8 @@ Tryby datetime/time: przełącznik „Od / Koniec" + tarcza zegara, zatwierdzeni
     period = signal<KptDateRangeValue>({ start: '', end: '' });
 
 ## i18n
-Nazwy dni/miesięcy z `Intl` wg locale; etykiety („Od/Koniec", nawigacja, „Gotowe", placeholder) z i18n
-(namespace `dateRange` + `datepicker`/`common`). Domyślnie EN — patrz `i18n/llms.txt`.
+Day and month names come from `Intl` per locale; the labels ("From/To", navigation, "Done", the placeholder) come from i18n
+(the `dateRange` namespace + `datepicker`/`common`). English by default — see `i18n/llms.txt`.
 
-## Tokeny
-Pole `--kpt-form-field-*`; kalendarz `--kpt-color-surface-raised`, zakres `--kpt-color-primary`.
+## Tokens
+The field `--kpt-form-field-*`; the calendar `--kpt-color-surface-raised`, the range `--kpt-color-primary`.