@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.
- package/CHANGELOG.md +617 -369
- package/README.md +111 -55
- package/charts/src/lib/llms.txt +17 -17
- package/chat/src/lib/llms.txt +61 -35
- package/fesm2022/konce-pt-angular-charts.mjs +11 -11
- package/fesm2022/konce-pt-angular-charts.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-chat.mjs +236 -127
- package/fesm2022/konce-pt-angular-chat.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-grid.mjs +16 -16
- package/fesm2022/konce-pt-angular-grid.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-icons.mjs +5 -5
- package/fesm2022/konce-pt-angular-icons.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-map.mjs +308 -280
- package/fesm2022/konce-pt-angular-map.mjs.map +1 -1
- package/fesm2022/konce-pt-angular-roadmap.mjs +23 -23
- package/fesm2022/konce-pt-angular-roadmap.mjs.map +1 -1
- package/fesm2022/konce-pt-angular.mjs +4416 -2132
- package/fesm2022/konce-pt-angular.mjs.map +1 -1
- package/grid/src/lib/llms.txt +18 -18
- package/map/src/lib/llms.txt +142 -141
- package/package.json +14 -12
- package/roadmap/src/lib/llms.txt +27 -27
- package/src/lib/accordion/llms.txt +18 -6
- package/src/lib/alert/llms.txt +5 -5
- package/src/lib/app-shell/llms.txt +23 -21
- package/src/lib/auth/llms.txt +22 -22
- package/src/lib/autocomplete/llms.txt +15 -4
- package/src/lib/avatar/llms.txt +3 -3
- package/src/lib/avatar-group/llms.txt +5 -5
- package/src/lib/backdrop/llms.txt +35 -35
- package/src/lib/badge/llms.txt +7 -7
- package/src/lib/bottom-sheet/llms.txt +4 -4
- package/src/lib/breadcrumb/llms.txt +2 -2
- package/src/lib/breakpoint/llms.txt +8 -8
- package/src/lib/button/llms.txt +26 -18
- package/src/lib/button-group/llms.txt +37 -31
- package/src/lib/card/llms.txt +19 -19
- package/src/lib/carousel/llms.txt +6 -6
- package/src/lib/checkbox/llms.txt +15 -3
- package/src/lib/chip/llms.txt +6 -6
- package/src/lib/chips-input/llms.txt +11 -4
- package/src/lib/color-picker/llms.txt +4 -4
- package/src/lib/confirm/llms.txt +5 -5
- package/src/lib/context-menu/llms.txt +4 -4
- package/src/lib/data-table/llms.txt +280 -239
- package/src/lib/data-view/llms.txt +25 -4
- package/src/lib/date-range/llms.txt +27 -27
- package/src/lib/datepicker/llms.txt +34 -34
- package/src/lib/dialog/llms.txt +22 -28
- package/src/lib/divider/llms.txt +2 -2
- package/src/lib/drawer/llms.txt +7 -7
- package/src/lib/empty/llms.txt +4 -4
- package/src/lib/fab/llms.txt +6 -2
- package/src/lib/fieldset/llms.txt +22 -4
- package/src/lib/file-upload/llms.txt +1 -1
- package/src/lib/form-field/llms.txt +33 -19
- package/src/lib/galleria/llms.txt +3 -3
- package/src/lib/i18n/llms.txt +9 -9
- package/src/lib/icon/llms.txt +8 -8
- package/src/lib/icon-button/llms.txt +8 -3
- package/src/lib/image/llms.txt +4 -4
- package/src/lib/input/llms.txt +21 -7
- package/src/lib/input-mask/llms.txt +2 -2
- package/src/lib/input-number/llms.txt +14 -14
- package/src/lib/input-otp/llms.txt +6 -6
- package/src/lib/knob/llms.txt +11 -6
- package/src/lib/listbox/llms.txt +6 -6
- package/src/lib/loader/llms.txt +72 -0
- package/src/lib/megamenu/llms.txt +7 -7
- package/src/lib/mention/llms.txt +15 -15
- package/src/lib/menu/llms.txt +12 -12
- package/src/lib/menubar/llms.txt +7 -7
- package/src/lib/meter-group/llms.txt +7 -7
- package/src/lib/order-list/llms.txt +18 -6
- package/src/lib/paginator/llms.txt +5 -5
- package/src/lib/panel/llms.txt +20 -8
- package/src/lib/password/llms.txt +14 -6
- package/src/lib/peek/llms.txt +10 -10
- package/src/lib/pick-list/llms.txt +26 -6
- package/src/lib/popover/llms.txt +7 -7
- package/src/lib/progress/llms.txt +16 -16
- package/src/lib/radio-group/llms.txt +10 -3
- package/src/lib/rating/llms.txt +13 -6
- package/src/lib/rich-text/llms.txt +34 -29
- package/src/lib/scroll-top/llms.txt +3 -3
- package/src/lib/select/llms.txt +20 -13
- package/src/lib/sidenav/llms.txt +8 -8
- package/src/lib/slider/llms.txt +21 -8
- package/src/lib/speech/llms.txt +108 -0
- package/src/lib/speed-dial/llms.txt +9 -3
- package/src/lib/spinner/llms.txt +2 -2
- package/src/lib/split-button/llms.txt +14 -8
- package/src/lib/splitter/llms.txt +8 -8
- package/src/lib/stepper/llms.txt +24 -8
- package/src/lib/switch/llms.txt +10 -3
- package/src/lib/switch-group/llms.txt +10 -10
- package/src/lib/tabs/llms.txt +5 -5
- package/src/lib/textarea/llms.txt +16 -5
- package/src/lib/timeline/llms.txt +1 -1
- package/src/lib/toast/llms.txt +33 -5
- package/src/lib/toolbar/llms.txt +3 -3
- package/src/lib/tooltip/llms.txt +10 -10
- package/src/lib/tree/llms.txt +19 -6
- package/src/lib/update/llms.txt +52 -0
- package/types/konce-pt-angular-charts.d.ts +2 -2
- package/types/konce-pt-angular-chat.d.ts +87 -44
- package/types/konce-pt-angular-chat.d.ts.map +1 -1
- package/types/konce-pt-angular-grid.d.ts +14 -14
- package/types/konce-pt-angular-icons.d.ts +3 -3
- package/types/konce-pt-angular-map.d.ts +137 -121
- package/types/konce-pt-angular-map.d.ts.map +1 -1
- package/types/konce-pt-angular-roadmap.d.ts +13 -13
- package/types/konce-pt-angular.d.ts +1391 -628
- 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
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- `
|
|
21
|
-
- `
|
|
22
|
-
- `
|
|
23
|
-
- `
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
`
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
- `
|
|
41
|
-
- `
|
|
42
|
-
- `
|
|
43
|
-
- `
|
|
44
|
-
- `
|
|
45
|
-
- `
|
|
46
|
-
- `
|
|
47
|
-
- `
|
|
48
|
-
- `
|
|
49
|
-
- `
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
- `
|
|
53
|
-
- `
|
|
54
|
-
- `
|
|
55
|
-
- `
|
|
56
|
-
- `
|
|
57
|
-
- `
|
|
58
|
-
- `
|
|
59
|
-
- `
|
|
60
|
-
- `
|
|
61
|
-
|
|
62
|
-
- `
|
|
63
|
-
|
|
64
|
-
- `
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
- `
|
|
69
|
-
- `
|
|
70
|
-
- `
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
the panel
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
- **
|
|
176
|
-
|
|
177
|
-
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
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 />
|