@konce-pt/angular 0.11.2 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (116) hide show
  1. package/CHANGELOG.md +792 -333
  2. package/README.md +111 -55
  3. package/charts/src/lib/llms.txt +23 -15
  4. package/chat/src/lib/llms.txt +68 -33
  5. package/fesm2022/konce-pt-angular-charts.mjs +149 -68
  6. package/fesm2022/konce-pt-angular-charts.mjs.map +1 -1
  7. package/fesm2022/konce-pt-angular-chat.mjs +296 -135
  8. package/fesm2022/konce-pt-angular-chat.mjs.map +1 -1
  9. package/fesm2022/konce-pt-angular-grid.mjs +16 -16
  10. package/fesm2022/konce-pt-angular-grid.mjs.map +1 -1
  11. package/fesm2022/konce-pt-angular-icons.mjs +5 -5
  12. package/fesm2022/konce-pt-angular-icons.mjs.map +1 -1
  13. package/fesm2022/konce-pt-angular-map.mjs +360 -293
  14. package/fesm2022/konce-pt-angular-map.mjs.map +1 -1
  15. package/fesm2022/konce-pt-angular-roadmap.mjs +120 -34
  16. package/fesm2022/konce-pt-angular-roadmap.mjs.map +1 -1
  17. package/fesm2022/konce-pt-angular.mjs +7117 -3373
  18. package/fesm2022/konce-pt-angular.mjs.map +1 -1
  19. package/grid/src/lib/llms.txt +18 -18
  20. package/map/src/lib/llms.txt +142 -140
  21. package/package.json +14 -12
  22. package/roadmap/src/lib/llms.txt +37 -27
  23. package/src/lib/accordion/llms.txt +18 -6
  24. package/src/lib/alert/llms.txt +5 -4
  25. package/src/lib/app-shell/llms.txt +25 -22
  26. package/src/lib/auth/llms.txt +26 -22
  27. package/src/lib/autocomplete/llms.txt +18 -4
  28. package/src/lib/avatar/llms.txt +3 -3
  29. package/src/lib/avatar-group/llms.txt +5 -5
  30. package/src/lib/backdrop/llms.txt +35 -35
  31. package/src/lib/badge/llms.txt +7 -7
  32. package/src/lib/bottom-sheet/llms.txt +6 -3
  33. package/src/lib/breadcrumb/llms.txt +9 -1
  34. package/src/lib/breakpoint/llms.txt +8 -8
  35. package/src/lib/button/llms.txt +26 -18
  36. package/src/lib/button-group/llms.txt +40 -31
  37. package/src/lib/card/llms.txt +19 -19
  38. package/src/lib/carousel/llms.txt +6 -6
  39. package/src/lib/checkbox/llms.txt +17 -2
  40. package/src/lib/chip/llms.txt +6 -6
  41. package/src/lib/chips-input/llms.txt +14 -4
  42. package/src/lib/color-picker/llms.txt +7 -4
  43. package/src/lib/confirm/llms.txt +9 -3
  44. package/src/lib/context-menu/llms.txt +7 -4
  45. package/src/lib/data-table/llms.txt +280 -227
  46. package/src/lib/data-view/llms.txt +25 -4
  47. package/src/lib/date-range/llms.txt +37 -18
  48. package/src/lib/datepicker/llms.txt +46 -29
  49. package/src/lib/dialog/llms.txt +29 -26
  50. package/src/lib/divider/llms.txt +2 -1
  51. package/src/lib/drawer/llms.txt +9 -6
  52. package/src/lib/empty/llms.txt +4 -4
  53. package/src/lib/fab/llms.txt +6 -2
  54. package/src/lib/fieldset/llms.txt +22 -4
  55. package/src/lib/file-upload/llms.txt +3 -0
  56. package/src/lib/form-field/llms.txt +33 -19
  57. package/src/lib/galleria/llms.txt +3 -3
  58. package/src/lib/i18n/llms.txt +15 -8
  59. package/src/lib/icon/llms.txt +9 -9
  60. package/src/lib/icon-button/llms.txt +8 -3
  61. package/src/lib/image/llms.txt +4 -4
  62. package/src/lib/input/llms.txt +21 -7
  63. package/src/lib/input-mask/llms.txt +5 -2
  64. package/src/lib/input-number/llms.txt +18 -15
  65. package/src/lib/input-otp/llms.txt +15 -4
  66. package/src/lib/knob/llms.txt +14 -7
  67. package/src/lib/listbox/llms.txt +8 -5
  68. package/src/lib/loader/llms.txt +72 -0
  69. package/src/lib/megamenu/llms.txt +16 -5
  70. package/src/lib/mention/llms.txt +15 -15
  71. package/src/lib/menu/llms.txt +12 -12
  72. package/src/lib/menubar/llms.txt +16 -5
  73. package/src/lib/meter-group/llms.txt +7 -7
  74. package/src/lib/order-list/llms.txt +20 -5
  75. package/src/lib/paginator/llms.txt +5 -5
  76. package/src/lib/panel/llms.txt +20 -8
  77. package/src/lib/password/llms.txt +17 -5
  78. package/src/lib/peek/llms.txt +11 -11
  79. package/src/lib/pick-list/llms.txt +28 -5
  80. package/src/lib/popover/llms.txt +9 -6
  81. package/src/lib/progress/llms.txt +16 -16
  82. package/src/lib/radio-group/llms.txt +13 -3
  83. package/src/lib/rating/llms.txt +13 -6
  84. package/src/lib/rich-text/llms.txt +42 -24
  85. package/src/lib/scroll-top/llms.txt +3 -3
  86. package/src/lib/select/llms.txt +23 -13
  87. package/src/lib/sidenav/llms.txt +8 -8
  88. package/src/lib/slider/llms.txt +23 -7
  89. package/src/lib/speech/llms.txt +108 -0
  90. package/src/lib/speed-dial/llms.txt +9 -3
  91. package/src/lib/spinner/llms.txt +2 -2
  92. package/src/lib/split-button/llms.txt +14 -8
  93. package/src/lib/splitter/llms.txt +8 -8
  94. package/src/lib/stepper/llms.txt +26 -7
  95. package/src/lib/switch/llms.txt +13 -3
  96. package/src/lib/switch-group/llms.txt +12 -9
  97. package/src/lib/tabs/llms.txt +7 -4
  98. package/src/lib/textarea/llms.txt +16 -5
  99. package/src/lib/timeline/llms.txt +1 -1
  100. package/src/lib/toast/llms.txt +36 -5
  101. package/src/lib/toolbar/llms.txt +3 -3
  102. package/src/lib/tooltip/llms.txt +13 -10
  103. package/src/lib/tree/llms.txt +19 -5
  104. package/src/lib/update/llms.txt +52 -0
  105. package/types/konce-pt-angular-charts.d.ts +11 -0
  106. package/types/konce-pt-angular-charts.d.ts.map +1 -1
  107. package/types/konce-pt-angular-chat.d.ts +98 -40
  108. package/types/konce-pt-angular-chat.d.ts.map +1 -1
  109. package/types/konce-pt-angular-grid.d.ts +14 -14
  110. package/types/konce-pt-angular-icons.d.ts +3 -3
  111. package/types/konce-pt-angular-map.d.ts +147 -119
  112. package/types/konce-pt-angular-map.d.ts.map +1 -1
  113. package/types/konce-pt-angular-roadmap.d.ts +34 -9
  114. package/types/konce-pt-angular-roadmap.d.ts.map +1 -1
  115. package/types/konce-pt-angular.d.ts +1774 -651
  116. package/types/konce-pt-angular.d.ts.map +1 -1
@@ -1,227 +1,280 @@
1
- # KptDataTable (kpt-data-table)
2
-
3
- The flagship data table: columns from configuration, sorting, a global filter,
4
- pagination, row selection and custom cell templates. Signal-based, OnPush.
5
- Import: `import { KptDataTable, KptColumn, KptCellDef, KptCellEditDef, KptRowDetailDef } from '@konce-pt/angular';`
6
-
7
- ## Selector
8
- `kpt-data-table`
9
-
10
- ## The column model (KptColumn)
11
- `{ field: string; header: string; sortable?: boolean; align?: 'start'|'center'|'end'; width?: string; frozen?: boolean; filter?: KptColumnFilter; edit?: KptColumnEdit; summary?: KptColumnSummary }`
12
- `frozen` columns (leading, adjacent) stick during horizontal scrolling — they require `width`.
13
-
14
- ### The column filter (KptColumnFilter)
15
- `{ type: 'text'|'number'|'select'|'dateRange'|'numberRange'|'slider'; options?: KptOption[]; multiple?: boolean; placeholder?: string; min?: number; max?: number; step?: number }`
16
- As soon as any column has a `filter`, a filter row is rendered in the header:
17
- - `text` — a text input ("contains" matching), `number` — a digits-only input (matching on digits),
18
- - `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,
19
- - `numberRange` — two fields (min–max); it matches when the field's numeric value falls inside the range (an empty bound = open),
20
- - `slider` — a range slider (two handles; `min`/`max`/`step`); the filter value is `[lo, hi]`, matching a number inside `[lo, hi]`,
21
- - `dateRange` — a date range (an ISO/Date field within `[start,end]`).
22
- Column filters combine with AND, both with each other and with the global filter; a change resets the page.
23
- 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.
24
- The `select`/`dateRange` filters require `import '@angular/cdk/overlay-prebuilt.css';`.
25
-
26
- ### Column editing (KptColumnEdit)
27
- `{ type: 'text'|'number'|'date'|'select'|'multiselect'; options?: KptOption[]; placeholder?: string; min?: number; max?: number; step?: number }`
28
- When a column has `edit`, its cells become clickable — a click (or Enter on a focused cell) swaps
29
- the value for a control: `text` → `kpt-input`, `number` → `kpt-input-number`, `date` → `kpt-datepicker`,
30
- `select` → `kpt-select`, `multiselect` → `kpt-select multiple filter`. See the "Inline editing" section below.
31
-
32
- ### The column summary (KptColumnSummary)
33
- `{ fn: 'sum'|'avg'|'min'|'max'|'count' | ((rows) => unknown); format?: (value) => string }`
34
- A column with `summary` is aggregated in the summary row — see the "Summary row" section below.
35
-
36
- ## Inputs
37
- - `columns`: KptColumn[] (required)
38
- - `data`: T[] (default [])
39
- - `filterable`: boolean — the global filter field
40
- - `filterRowPosition`: 'top' | 'bottom' (default 'bottom') — the column filter row above/below the labels
41
- - `pageSize`: number — 0 disables pagination
42
- - `pageSizeOptions`: number[] (default [5,10,20,50])
43
- - `selectable`: 'none' | 'single' | 'multiple'
44
- - `loading`: boolean — a "Loading…" row
45
- - `emptyMessage`: string — with no value it uses i18n (`dataTable.empty`); the input takes priority
46
- - `rowKey`: string | null — the field identifying a row (for selection); without it rows are compared by reference
47
- - `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
48
- - `exportable`: boolean — an "Export CSV" button in the toolbar
49
- - `exportFilename`: string (default 'export.csv')
50
- - `lazy`: boolean — server-side mode (no client-side filtering/sorting/pagination)
51
- - `totalRecords`: number | null — the total record count (required with lazy)
52
- - `scrollHeight`: string | null — the height of the scrollable area (e.g. '400px'); the sticky header stays
53
- - `virtualScroll`: boolean — row virtualization (only visible rows are rendered); requires `scrollHeight`
54
- - `rowHeight`: number — a fixed row height in px (default 41), needed with virtualScroll
55
- - `expandable`: boolean — a column with a toggle that expands the row (rendering the `kptRowDetail` template)
56
- - `multiExpand`: boolean (default true) — allows several rows open at once; false = only one
57
- - `summaryLabel`: string — the summary row's label; with no value it uses i18n (`dataTable.total`)
58
- - `summaryValues`: Record<string, unknown> | null — ready-made summary values (field → value);
59
- they override the computed ones, and with `lazy` they are the only source
60
-
61
- ## Model / events
62
- - `selection`: model<T[]> — two-way `[(selection)]`
63
- - `expandedRows`: model<T[]> — two-way `[(expandedRows)]` (the expanded rows)
64
- - `hiddenFields`: model<readonly string[]> — two-way `[(hiddenFields)]`; the set of `KptColumn.field`
65
- values currently hidden. The component provides no UI for managing that state itself (no button,
66
- no dialog, no persistence) — it is a deliberately minimal hook for wiring up an external column
67
- switcher. An example of a finished UI (a button + a dialog with checkboxes + localStorage persistence), built
68
- from `kpt-dialog`/`kpt-checkbox`/`kpt-button`, lives in the playground as `pg-column-toggle`
69
- (`apps/playground/src/pg-column-toggle.component.ts`) — it is not exported from the library.
70
- Hiding a column does not take it out of the global search or the per-column filters — only
71
- out of the view (and out of the CSV export, see below). The order remembered by `reorderable` survives
72
- hiding and showing a column. To place a compact (icon) version of such a button
73
- next to the paginator there is the `[kptPaginatorActions]` projection slot — see the "The paginator
74
- row" section below.
75
- - `rowClick`: output<T>
76
- - `lazyLoad`: output<KptTableLazyState> — { pageIndex, pageSize, sortField, sortDir, filter, columnFilters }; emitted in lazy mode on every state change
77
- - `cellEdit`: output<KptCellEditEvent<T>> — `{ row, field, value, updatedRow }`; emitted once a cell
78
- edit is committed (see "Inline editing" below), and only when the value actually
79
- changed. The table saves nothing itself (no HTTP, no loading/error state) — `updatedRow`
80
- is a ready request body, and the rest (saving, an optimistic update, a rollback on error) is handled
81
- by the consumer, exactly as with `lazyLoad`.
82
-
83
- ## Export / methods
84
- - `exportCsv()`: a public method — exports the current (filtered+sorted) data to CSV (the `;` separator, a BOM for
85
- Excel). It exports only the currently **visible** columns (those in `hiddenFields` are left out).
86
-
87
- ## Custom cell templates (the kptCell directive)
88
- Context: `$implicit` = the row, `value` = the field's value.
89
-
90
- <kpt-data-table [columns]="cols" [data]="rows" filterable [pageSize]="10"
91
- selectable="multiple" rowKey="id" [(selection)]="picked">
92
- <ng-template kptCell="status" let-row let-value="value">
93
- <span class="badge">{{ value }}</span>
94
- </ng-template>
95
- </kpt-data-table>
96
-
97
- ## Expandable rows (the kptRowDetail directive)
98
- Turn on `expandable` and supply a `kptRowDetail` template (context: `$implicit` = the row).
99
- It adds a leading column with a toggle; an expanded row renders the template at full width below the row.
100
- The state goes through `[(expandedRows)]`; `multiExpand=false` limits it to one open at a time.
101
- Independent of `selectable` (it can be combined with selection). Not available with `virtualScroll`.
102
-
103
- <kpt-data-table [columns]="cols" [data]="rows" expandable rowKey="id" [(expandedRows)]="open">
104
- <ng-template kptRowDetail let-row>
105
- <div class="details">{{ row.description }}</div>
106
- </ng-template>
107
- </kpt-data-table>
108
-
109
- ## Inline editing (column.edit / kptCellEdit)
110
- Clicking a cell in an editable column (or pressing Enter while the cell has focus — it carries `tabindex="0"` then)
111
- swaps its value for a control from `column.edit.type`. How it commits depends on the kind of control:
112
-
113
- - `text`/`number` (`kpt-input`, `kpt-input-number`) — there is no overlay, so it commits when focus leaves
114
- **the whole editor** (`focusout` with a `relatedTarget` check) or on Enter; Escape discards the change.
115
- Deliberately not on the control's own `touch`/blur: `kpt-input-number` has focusable `+`/`-` arrows
116
- next to the field (and it also emits `touch` in `step_()`), so every arrow click would close
117
- the edit before it had a chance to change the value.
118
- - `date`/`select`/`multiselect` (`kpt-datepicker`, `kpt-select`) — the panel opens **immediately** after
119
- the cell is clicked, and the commit happens when it **closes**: picking a value (single),
120
- a click outside the panel or Escape. In `multiselect`, ticking further options commits nothing along
121
- the way — the panel stays open until the user clicks outside it, and then a single event fires with the full list.
122
-
123
- The table **never commits on `touch`** — and that must not be reinstated. `touch` in these
124
- controls does not mean "the user is done": it fires on the trigger's blur and, on top of that, from `step_()`
125
- in `kpt-input-number`. Committing on `touch` once destroyed the editor together with the panel before the click
126
- had a chance to pick a value (the panel lives in a CDK Overlay container next to `<body>`, and pressing the mouse
127
- on an option used to blur the trigger). The select and date pickers no longer emit `touch` while their panel
128
- is open, but `open` remains the only signal that says "the choice is over". Instead: overlay editors bind to `open` (`[open]`/`(openChange)`),
129
- and the rest to `focusout` on the whole editor (focus moved within the editor does not commit).
130
-
131
- **A limitation**: for overlay editors Escape **commits** (it closes the panel) rather than discarding —
132
- the panel's keyboard handling lives inside `kpt-select`/`kpt-datepicker`, and a keydown from the overlay does not
133
- reach the cell. Escape discards a change only in `text`/`number`.
134
-
135
- Values are compared before emitting: `cellEdit` does not fire when the user opened and closed a panel without
136
- a change, nor when a `multiselect` returns to the same set (arrays are compared by content).
137
-
138
- When the 5 built-in types are not enough, the `kptCellEdit` directive gives you a full custom editor. Context:
139
- `$implicit` = the current value, `row` = the row, `commit(value)` = commit and close, `cancel()` = discard.
140
-
141
- <kpt-data-table [columns]="cols" [data]="rows" rowKey="id" (cellEdit)="onCellEdit($event)">
142
- <ng-template kptCellEdit="team" let-value let-commit="commit">
143
- <my-custom-picker [value]="value" (valueChange)="commit($event)" />
144
- </ng-template>
145
- </kpt-data-table>
146
-
147
- ## The summary row (column.summary)
148
- Columns with a `summary` render a `<tfoot>` — the table's last row, **above the paginator**, stuck
149
- to the bottom of the scrolling area (`position: sticky; bottom: 0`, like the sticky header).
150
-
151
- - **The label** (`summaryLabel`, i18n `dataTable.total` by default → "Total"/"Razem") is rendered
152
- in one merged cell (`colspan`) reaching from the start of the row to the first aggregated column,
153
- right-aligned. The colspan also covers the system columns (expand, select).
154
- For example: a `summary` on the 3rd column → columns 1–2 merged. When the **first** visible
155
- column is the aggregated one (and there are no system columns), the label has nowhere to fit and is not rendered.
156
- - **The scope**: the aggregation covers **every row after filtering** — the whole of page 1 and every following one,
157
- not just what is visible. The global filter and the column filters narrow the set (in step with the paginator's counter),
158
- while sorting and the current page do not change the result.
159
- - **Live under inline editing**: `data` is an ordinary input, so once the consumer swaps the array in a signal
160
- after `cellEdit`, the summary recomputes itself (a plain `computed`).
161
- - **Aggregations**: `sum`, `avg`, `min`, `max`, `count`. `count` counts rows; the rest skip
162
- non-numeric values (a string holding a number is parsed). On an empty set: `sum` = 0, the rest — an empty
163
- cell. `sum`/`avg` trim floating-point tails (without that `0.1+0.2` = `0.30000000000000004`).
164
- A custom `fn: (rows) => unknown` receives the same set (a weighted sum, for instance).
165
- - **Formatting**: `format: (value) => string` (`Intl.NumberFormat`, say); without it the value goes out
166
- raw. Summary cells are right-aligned by default — an explicit column `align` takes priority.
167
- The row label ("Total") is one for the whole row, so name a column aggregated by anything other than a sum
168
- (`avg`, `min`, `max`) inside `format` (e.g. `ø 662.57 USD`) — otherwise it reads as a sum.
169
- - **Hidden columns** (`hiddenFields`) drop out of the summary too; the order after `reorderable`
170
- is respected (the label merges up to whatever is now the first aggregated column).
171
- - **`lazy` mode**: the table only holds the current page, so it computes nothing itself — supply `summaryValues`
172
- (field → a ready value from the server). `summaryValues` also works outside `lazy`, overriding the computed values.
173
- A column listed only in `summaryValues` (with no `summary`) shows a value too.
174
- - The row is not rendered while `loading`, nor when the table is empty (we do not duplicate the state message).
175
- - The CSV export **does not include** the summary row — `exportCsv()` exports the data alone.
176
-
177
- cols = [
178
- { field: 'product', header: 'Product' },
179
- { field: 'qty', header: 'Quantity', align: 'end', summary: { fn: 'sum' } },
180
- { field: 'net', header: 'Net', align: 'end', summary: { fn: 'sum', format: usd } },
181
- ];
182
-
183
- <kpt-data-table [columns]="cols" [data]="rows()" [pageSize]="5" rowKey="id"
184
- summaryLabel="Total" (cellEdit)="onCellEdit($event)" />
185
-
186
- ## Behavior
187
- - Sorting: clicking a sortable column's header cycles asc → desc → none.
188
- - Filtering: text matching across every column field; the page resets to 0.
189
- - 'multiple' selection: the header checkbox selects/deselects the current page.
190
- - A sticky header, empty/loading states, per-column alignment and widths.
191
-
192
- ## i18n
193
- The toolbar/state/aria labels (Search, Export CSV, Loading, No data, selection, the column filters:
194
- Filter/Filter min/Filter max with `{column}`, All, min, max, Date range) come from i18n (the `dataTable` namespace).
195
- English by default; configured through `provideKptI18n` — see `i18n/llms.txt`.
196
-
197
- ## The paginator row (the [kptPaginatorActions] slot)
198
- The row holding `kpt-paginator` (rendered when `pageSize > 0` and there is no `virtualScroll`) is a flex
199
- container with an optional projection slot on the left: a `<div kptPaginatorActions>…</div>` placed
200
- as content of `kpt-data-table` renders before the paginator, in the same row (`kpt-paginator`
201
- has `flex: 1 1 auto` and its own `justify-content: flex-end` — with no projection it behaves exactly
202
- as it did before, fully to the right). This is the place for a compact (icon) column-customization button —
203
- see `hiddenFields` above and the `pg-column-toggle` example in the playground.
204
-
205
- <kpt-data-table [columns]="cols" [data]="rows" [pageSize]="10" [(hiddenFields)]="hidden">
206
- <kpt-icon-button kptPaginatorActions ariaLabel="Columns" (click)="open.set(true)">
207
- <kpt-icon name="adjustments-horizontal" />
208
- </kpt-icon-button>
209
- </kpt-data-table>
210
-
211
- ## Tokens
212
- `--kpt-table-{bg,fg,border,radius,header-bg,header-fg,row-hover,row-selected,cell-padding}`.
213
- The expanded row: `--kpt-table-detail-bg` (fallback: surface-variant → row-hover).
214
- The summary row: `--kpt-table-summary-bg` (fallback: header-bg).
215
- Pagination: the `kpt-paginator` component.
216
-
217
- ## To do (roadmap)
218
- Grouped columns.
219
-
220
- Column show/hide: done (the `hiddenFields` hook; the customization UI — see the "Model / events" section
221
- and the `pg-column-toggle` example in the playground).
222
-
223
- Inline cell editing: done (`column.edit` + `cellEdit` + `kptCellEdit`; saving to an API —
224
- see the playground example, `pg-fake-users-api.ts`).
225
-
226
- The summary row: done (`column.summary` + `summaryLabel` + `summaryValues` — see the
227
- "The summary row" section and the "Inline editing + summary row" example in the playground).
1
+ # KptDataTable (kpt-data-table)
2
+
3
+ The flagship data table: columns from configuration, sorting, a global filter,
4
+ pagination, row selection and custom cell templates. Signal-based, OnPush.
5
+ Import: `import { KptDataTable, KptColumn, KptCellDef, KptCellEditDef, KptRowDetailDef } from '@konce-pt/angular';`
6
+
7
+ ## Selector
8
+ `kpt-data-table`
9
+
10
+ ## The column model (KptColumn)
11
+ `{ field: string; header: string; sortable?: boolean; align?: 'start'|'center'|'end'; width?: string; frozen?: boolean; filter?: KptColumnFilter; edit?: KptColumnEdit; summary?: KptColumnSummary }`
12
+ `frozen` columns (leading, adjacent) stick during horizontal scrolling. Their offsets come from `width`:
13
+ `px`/`rem`/`em` are computed up front, other units (`%`, `ch`) and a missing width are measured from
14
+ the rendered header after the first render. The system columns (expand, select) stick together with
15
+ them; to stick only the system columns, with every data column scrolling, set `frozenSystemColumns`.
16
+
17
+ ### The column filter (KptColumnFilter)
18
+ `{ type: 'text'|'number'|'select'|'dateRange'|'numberRange'|'slider'; options?: KptOption[]; multiple?: boolean; placeholder?: string; min?: number; max?: number; step?: number }`
19
+ As soon as any column has a `filter`, a filter row is rendered in the header:
20
+ - `text` - a text input ("contains" matching), `number` - a digits-only input (matching on digits),
21
+ - `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,
22
+ - `numberRange` - two fields (min-max); it matches when the field's numeric value falls inside the range (an empty bound = open),
23
+ - `slider` - a range slider (two handles; `min`/`max`/`step`); the filter value is `[lo, hi]`, matching a number inside `[lo, hi]`,
24
+ - `dateRange` - a date range (an ISO/Date field within `[start,end]`).
25
+ Column filters combine with AND, both with each other and with the global filter; a change resets the page.
26
+ 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.
27
+ The `select`/`dateRange` filters require `import '@angular/cdk/overlay-prebuilt.css';`.
28
+
29
+ ### Column editing (KptColumnEdit)
30
+ `{ type: 'text'|'number'|'date'|'select'|'multiselect'; options?: KptOption[]; placeholder?: string; min?: number; max?: number; step?: number }`
31
+ When a column has `edit`, its cells become clickable - a click (or Enter on a focused cell) swaps
32
+ the value for a control: `text` -> `kpt-input`, `number` -> `kpt-input-number`, `date` -> `kpt-datepicker`,
33
+ `select` -> `kpt-select`, `multiselect` -> `kpt-select multiple filter`. See the "Inline editing" section below.
34
+
35
+ ### The column summary (KptColumnSummary)
36
+ `{ fn: 'sum'|'avg'|'min'|'max'|'count' | ((rows) => unknown); format?: (value) => string }`
37
+ A column with `summary` is aggregated in the summary row - see the "Summary row" section below.
38
+
39
+ ## Inputs
40
+ - `columns`: KptColumn[] (required)
41
+ - `data`: T[] (default [])
42
+ - `filterable`: boolean - the global filter field
43
+ - `filterRowPosition`: 'top' | 'bottom' (default 'bottom') - the column filter row above/below the labels
44
+ - `pageSize`: number - 0 disables pagination
45
+ - `pageSizeOptions`: number[] (default [5,10,20,50])
46
+ - `selectable`: 'none' | 'single' | 'multiple'
47
+ - `loading`: boolean - a "Loading..." row; the table gets `aria-busy="true"`
48
+ - `ariaLabel`: string | null - the table's accessible name when there is no visible `caption`
49
+ - `caption`: string | null - a visible `<caption>`, which is also the table's name
50
+ - `clickableRows`: boolean - rows become focusable (Tab) and Enter/Space emits `rowClick`; turn it on when
51
+ clicking a row does something and the row has no other link/button for the same action
52
+ - `emptyMessage`: string - with no value it uses i18n (`dataTable.empty`); the input takes priority
53
+ - `rowKey`: string | null - the field identifying a row (for selection); without it rows are compared by reference
54
+ - `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. The grip is a button: `ArrowLeft`/`ArrowRight` on it move the column by one place and the new position is announced
55
+ - `exportable`: boolean - an "Export CSV" button in the toolbar
56
+ - `exportFilename`: string (default 'export.csv')
57
+ - `lazy`: boolean - server-side mode (no client-side filtering/sorting/pagination)
58
+ - `totalRecords`: number | null - the total record count (required with lazy)
59
+ - `scrollHeight`: string | null - the height of the scrollable area (e.g. '400px'); the sticky header stays
60
+ - `virtualScroll`: boolean - virtualization of rows **and columns** (only the visible window plus a small
61
+ buffer is rendered); requires `scrollHeight`. See "Large data sets" below
62
+ - `columnWidth`: string - with `virtualScroll`: the width of a column without a `px`/`rem`/`em` `width`
63
+ (default '10rem')
64
+ - `rowHeight`: number - a fixed row height in px (default 41), needed with virtualScroll
65
+ - `frozenSystemColumns`: boolean - sticks the system columns (expand, select) to the left edge even
66
+ when no data column is `frozen`; with `frozen` columns they stick anyway
67
+ - `expandable`: boolean - a column with a toggle that expands the row (rendering the `kptRowDetail` template)
68
+ - `multiExpand`: boolean (default true) - allows several rows open at once; false = only one
69
+ - `summaryLabel`: string - the summary row's label; with no value it uses i18n (`dataTable.total`)
70
+ - `summaryValues`: Record<string, unknown> | null - ready-made summary values (field -> value);
71
+ they override the computed ones, and with `lazy` they are the only source
72
+
73
+ ## Model / events
74
+ - `selection`: model<T[]> - two-way `[(selection)]`
75
+ - `expandedRows`: model<T[]> - two-way `[(expandedRows)]` (the expanded rows)
76
+ - `hiddenFields`: model<readonly string[]> - two-way `[(hiddenFields)]`; the set of `KptColumn.field`
77
+ values currently hidden. The component provides no UI for managing that state itself (no button,
78
+ no dialog, no persistence) - it is a deliberately minimal hook for wiring up an external column
79
+ switcher. An example of a finished UI (a button + a dialog with checkboxes + localStorage persistence), built
80
+ from `kpt-dialog`/`kpt-checkbox`/`kpt-button`, lives in the playground as `pg-column-toggle`
81
+ (`apps/playground/src/pg-column-toggle.component.ts`) - it is not exported from the library.
82
+ Hiding a column does not take it out of the global search or the per-column filters - only
83
+ out of the view (and out of the CSV export, see below). The order remembered by `reorderable` survives
84
+ hiding and showing a column. To place a compact (icon) version of such a button
85
+ next to the paginator there is the `[kptPaginatorActions]` projection slot - see the "The paginator
86
+ row" section below.
87
+ - `rowClick`: output<T> - mouse only unless `clickableRows` is on
88
+ - `lazyLoad`: output<KptTableLazyState> - { pageIndex, pageSize, sortField, sortDir, filter, columnFilters }; emitted in lazy mode on every state change, including once on start (the first page) and after the parent changes `pageSize`
89
+ - `cellEdit`: output<KptCellEditEvent<T>> - `{ row, field, value, updatedRow }`; emitted once a cell
90
+ edit is committed (see "Inline editing" below), and only when the value actually
91
+ changed. The table saves nothing itself (no HTTP, no loading/error state) - `updatedRow`
92
+ is a ready request body, and the rest (saving, an optimistic update, a rollback on error) is handled
93
+ by the consumer, exactly as with `lazyLoad`.
94
+
95
+ ## Export / methods
96
+ - `exportCsv()`: a public method - exports the current (filtered+sorted) data to CSV (the `;` separator, `\r\n`
97
+ line endings as in RFC 4180, a BOM for Excel). It exports only the currently **visible** columns (those in `hiddenFields` are left out).
98
+
99
+ ## Custom cell templates (the kptCell directive)
100
+ Context: `$implicit` = the row, `value` = the field's value.
101
+
102
+ <kpt-data-table [columns]="cols" [data]="rows" filterable [pageSize]="10"
103
+ selectable="multiple" rowKey="id" [(selection)]="picked">
104
+ <ng-template kptCell="status" let-row let-value="value">
105
+ <span class="badge">{{ value }}</span>
106
+ </ng-template>
107
+ </kpt-data-table>
108
+
109
+ ## Expandable rows (the kptRowDetail directive)
110
+ Turn on `expandable` and supply a `kptRowDetail` template (context: `$implicit` = the row).
111
+ It adds a leading column with a toggle; an expanded row renders the template at full width below the row.
112
+ The state goes through `[(expandedRows)]`; `multiExpand=false` limits it to one open at a time.
113
+ Independent of `selectable` (it can be combined with selection). Not available with `virtualScroll`.
114
+
115
+ <kpt-data-table [columns]="cols" [data]="rows" expandable rowKey="id" [(expandedRows)]="open">
116
+ <ng-template kptRowDetail let-row>
117
+ <div class="details">{{ row.description }}</div>
118
+ </ng-template>
119
+ </kpt-data-table>
120
+
121
+ ## Inline editing (column.edit / kptCellEdit)
122
+ Clicking a cell in an editable column (or pressing Enter while the cell has focus - it carries `tabindex="0"` then)
123
+ swaps its value for a control from `column.edit.type`. How it commits depends on the kind of control:
124
+
125
+ - `text`/`number` (`kpt-input`, `kpt-input-number`) - there is no overlay, so it commits when focus leaves
126
+ **the whole editor** (`focusout` with a `relatedTarget` check) or on Enter; Escape discards the change.
127
+ Deliberately not on the control's own `touch`/blur: `kpt-input-number` has focusable `+`/`-` arrows
128
+ next to the field (and it also emits `touch` in `step_()`), so every arrow click would close
129
+ the edit before it had a chance to change the value.
130
+ - `date`/`select`/`multiselect` (`kpt-datepicker`, `kpt-select`) - the panel opens **immediately** after
131
+ the cell is clicked, and the commit happens when it **closes**: picking a value (single),
132
+ a click outside the panel or Escape. In `multiselect`, ticking further options commits nothing along
133
+ the way - the panel stays open until the user clicks outside it, and then a single event fires with the full list.
134
+
135
+ The table **never commits on `touch`** - and that must not be reinstated. `touch` in these
136
+ controls does not mean "the user is done": it fires on the trigger's blur and, on top of that, from `step_()`
137
+ in `kpt-input-number`. Committing on `touch` once destroyed the editor together with the panel before the click
138
+ had a chance to pick a value (the panel lives in a CDK Overlay container next to `<body>`, and pressing the mouse
139
+ on an option used to blur the trigger). The select and date pickers no longer emit `touch` while their panel
140
+ is open, but `open` remains the only signal that says "the choice is over". Instead: overlay editors bind to `open` (`[open]`/`(openChange)`),
141
+ and the rest to `focusout` on the whole editor (focus moved within the editor does not commit).
142
+
143
+ **A limitation**: for overlay editors Escape **commits** (it closes the panel) rather than discarding -
144
+ the panel's keyboard handling lives inside `kpt-select`/`kpt-datepicker`, and a keydown from the overlay does not
145
+ reach the cell. Escape discards a change only in `text`/`number`.
146
+
147
+ Values are compared before emitting: `cellEdit` does not fire when the user opened and closed a panel without
148
+ a change, nor when a `multiselect` returns to the same set (arrays are compared by content).
149
+
150
+ When the 5 built-in types are not enough, the `kptCellEdit` directive gives you a full custom editor. Context:
151
+ `$implicit` = the current value, `row` = the row, `commit(value)` = commit and close, `cancel()` = discard.
152
+
153
+ <kpt-data-table [columns]="cols" [data]="rows" rowKey="id" (cellEdit)="onCellEdit($event)">
154
+ <ng-template kptCellEdit="team" let-value let-commit="commit">
155
+ <my-custom-picker [value]="value" (valueChange)="commit($event)" />
156
+ </ng-template>
157
+ </kpt-data-table>
158
+
159
+ ## The summary row (column.summary)
160
+ Columns with a `summary` render a `<tfoot>` - the table's last row, **above the paginator**, stuck
161
+ to the bottom of the scrolling area (`position: sticky; bottom: 0`, like the sticky header).
162
+
163
+ - **The label** (`summaryLabel`, i18n `dataTable.total` by default -> "Total"/"Razem") is rendered
164
+ in one merged cell (`colspan`) reaching from the start of the row to the first aggregated column,
165
+ left-aligned, so it stays put when columns are reordered. The colspan also covers the system columns
166
+ (expand, select). With frozen columns the label stops at their edge (it is sticky, like them) and the
167
+ scrolling columns before the first aggregated one get empty cells. With `frozenSystemColumns` alone the
168
+ system columns are too narrow for it: they get an empty sticky cell and the label scrolls with the columns
169
+ before the first aggregated one.
170
+ For example: a `summary` on the 3rd column -> columns 1-2 merged. When the **first** visible
171
+ column is the aggregated one (and there are no system columns), the label has nowhere to fit and is not rendered.
172
+ - **The scope**: the aggregation covers **every row after filtering** - the whole of page 1 and every following one,
173
+ not just what is visible. The global filter and the column filters narrow the set (in step with the paginator's counter),
174
+ while sorting and the current page do not change the result.
175
+ - **Live under inline editing**: `data` is an ordinary input, so once the consumer swaps the array in a signal
176
+ after `cellEdit`, the summary recomputes itself (a plain `computed`).
177
+ - **Aggregations**: `sum`, `avg`, `min`, `max`, `count`. `count` counts rows; the rest skip
178
+ non-numeric values (a string holding a number is parsed). On an empty set: `sum` = 0, the rest - an empty
179
+ cell. `sum`/`avg` trim floating-point tails (without that `0.1+0.2` = `0.30000000000000004`).
180
+ A custom `fn: (rows) => unknown` receives the same set (a weighted sum, for instance).
181
+ - **Formatting**: `format: (value) => string` (`Intl.NumberFormat`, say); without it the value goes out
182
+ raw. Summary cells are right-aligned by default - an explicit column `align` takes priority.
183
+ The row label ("Total") is one for the whole row, so name a column aggregated by anything other than a sum
184
+ (`avg`, `min`, `max`) inside `format` (e.g. `ø 662.57 USD`) - otherwise it reads as a sum.
185
+ - **Hidden columns** (`hiddenFields`) drop out of the summary too; the order after `reorderable`
186
+ is respected (the label merges up to whatever is now the first aggregated column).
187
+ - **`lazy` mode**: the table only holds the current page, so it computes nothing itself - supply `summaryValues`
188
+ (field -> a ready value from the server). `summaryValues` also works outside `lazy`, overriding the computed values.
189
+ A column listed only in `summaryValues` (with no `summary`) shows a value too.
190
+ - The row is not rendered while `loading`, nor when the table is empty (we do not duplicate the state message).
191
+ - The CSV export **does not include** the summary row - `exportCsv()` exports the data alone.
192
+
193
+ cols = [
194
+ { field: 'product', header: 'Product' },
195
+ { field: 'qty', header: 'Quantity', align: 'end', summary: { fn: 'sum' } },
196
+ { field: 'net', header: 'Net', align: 'end', summary: { fn: 'sum', format: usd } },
197
+ ];
198
+
199
+ <kpt-data-table [columns]="cols" [data]="rows()" [pageSize]="5" rowKey="id"
200
+ summaryLabel="Total" (cellEdit)="onCellEdit($event)" />
201
+
202
+ ## Behavior
203
+ - Sorting: the sortable header is a button (Tab, Enter/Space) and cycles asc -> desc -> none; `aria-sort` sits
204
+ on the `<th>`. Text is compared with `Intl.Collator` for the `KptI18n` language (natural numbers:
205
+ "Item 2" before "Item 10"), empty cells go last in both directions.
206
+ - Filtering: text matching across every column field, ignoring case and diacritics ("lodz" finds "Łódź");
207
+ the page resets to 0. The column text filter folds diacritics too.
208
+ - 'single' selection renders radios (one group per table); clicking the selected one clears it.
209
+ - 'multiple' selection: the header checkbox selects/deselects the current page (with `virtualScroll` -
210
+ every row after filtering).
211
+ - An editable cell keeps its value as its name; "Edit: {column}" is its description (`aria-describedby`).
212
+ - A sticky header, empty/loading states, per-column alignment and widths.
213
+
214
+ ## Large data sets (virtualScroll)
215
+ Tested at 20,000 rows x 100 columns: a few hundred cells live in the DOM, scrolling, search, sorting and
216
+ "select all" stay free of long tasks.
217
+
218
+ <kpt-data-table [columns]="cols" [data]="rows()" virtualScroll scrollHeight="480px"
219
+ filterable selectable="multiple" rowKey="id" [(selection)]="picked" />
220
+
221
+ - Rows: a fixed `rowHeight` (px). Columns: the table switches to `table-layout: fixed` with a `<colgroup>`;
222
+ a column width comes from `width` in `px`/`rem`/`em`, anything else (no width, `%`, `ch`) gets
223
+ `columnWidth`. Leading `frozen` columns are always rendered, the rest is windowed horizontally.
224
+ - The table width is the sum of the columns (`min-width: 100%` stretches narrow tables).
225
+ - `aria-rowcount`/`aria-colcount` on the table and `aria-rowindex`/`aria-colindex` on rows and cells
226
+ give assistive technology the real size, not the window.
227
+ - Global search on sets above 2,000 rows waits ~150 ms for a pause in typing; the folded text of every
228
+ row is prepared in idle time after the data arrives, so the first keystroke does not pay for the set.
229
+ Rows are treated as immutable - replace a changed row object instead of mutating it in place.
230
+ - A new search, column filter or sort scrolls back to the top.
231
+ - Not available in this mode: pagination and expandable rows.
232
+ - Selection uses `rowKey` (or the row reference) in a `Set` - selecting 20,000 rows is O(n).
233
+
234
+ ## i18n
235
+ The toolbar/state/aria labels (Search, Export CSV, Loading, No data, selection, the column filters:
236
+ Filter/Filter min/Filter max with `{column}`, All, min, max, Date range, Move column, the column-moved
237
+ announcement) come from i18n (the `dataTable` namespace).
238
+ English by default; configured through `provideKptI18n` - see `i18n/llms.txt`.
239
+
240
+ ## The paginator row (the [kptPaginatorActions] slot)
241
+ The row holding `kpt-paginator` (rendered when `pageSize > 0` and there is no `virtualScroll`) is a flex
242
+ container with an optional projection slot on the left: a `<div kptPaginatorActions>...</div>` placed
243
+ as content of `kpt-data-table` renders before the paginator, in the same row (`kpt-paginator`
244
+ has `flex: 1 1 auto` and its own `justify-content: flex-end` - with no projection it behaves exactly
245
+ as it did before, fully to the right). This is the place for a compact (icon) column-customization button -
246
+ see `hiddenFields` above and the `pg-column-toggle` example in the playground.
247
+
248
+ <kpt-data-table [columns]="cols" [data]="rows" [pageSize]="10" [(hiddenFields)]="hidden">
249
+ <kpt-icon-button kptPaginatorActions ariaLabel="Columns" (click)="open.set(true)">
250
+ <kpt-icon name="adjustments-horizontal" />
251
+ </kpt-icon-button>
252
+ </kpt-data-table>
253
+
254
+ ## Tokens
255
+ `--kpt-table-{bg,fg,border,radius,header-bg,header-fg,row-hover,row-selected,cell-padding}`.
256
+ The expanded row: `--kpt-table-detail-bg` (fallback: surface-variant -> row-hover).
257
+ The summary row: `--kpt-table-summary-bg` (fallback: header-bg).
258
+ Pagination: the `kpt-paginator` component.
259
+
260
+ ## To do (roadmap)
261
+ Grouped columns.
262
+
263
+ Column show/hide: done (the `hiddenFields` hook; the customization UI - see the "Model / events" section
264
+ and the `pg-column-toggle` example in the playground).
265
+
266
+ Inline cell editing: done (`column.edit` + `cellEdit` + `kptCellEdit`; saving to an API -
267
+ see the playground example, `pg-fake-users-api.ts`).
268
+
269
+ The summary row: done (`column.summary` + `summaryLabel` + `summaryValues` - see the
270
+ "The summary row" section and the "Inline editing + summary row" example in the playground).
271
+
272
+ ## Filter by voice
273
+ - `filterSpeech`: boolean = false (needs `filterable`) - a microphone in the global filter field. A click
274
+ clears the filter and one spoken phrase becomes the new filter, with the same debounce for large data
275
+ as typing. Hidden without browser support.
276
+ - `filterSpeechLang`: string | null - BCP 47 tag; without it from `KptI18n.locale`.
277
+ - `filterSpeechColor`: `'primary' | 'danger' | 'success' | 'warning' | 'info'` = `'primary'` - colour of "stop" and the wave while listening.
278
+ The filter field now sits in `.kpt-data-table__search` (the box that positions the microphone).
279
+
280
+ <kpt-data-table [columns]="columns" [data]="rows" filterable filterSpeech />