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