@dloizides/ui-tables 1.9.1 → 1.10.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 +58 -0
- package/README.md +70 -0
- package/dist/index.d.mts +108 -7
- package/dist/index.d.ts +108 -7
- package/dist/index.js +724 -152
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +711 -137
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,63 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.10.0
|
|
4
|
+
|
|
5
|
+
Additive: **bulk-select** + **keyboard navigation** on `DataTable` (ZY-08). Every new prop is
|
|
6
|
+
optional and CONTROLLED — omit them all and the table renders exactly as it did on 1.9.2, so
|
|
7
|
+
erevna / katalogos / kefi / agora are unaffected. Hence a MINOR bump.
|
|
8
|
+
|
|
9
|
+
- **Bulk-select** — `selectedRowKeys` + `onSelectionChange` add a checkbox gutter to the
|
|
10
|
+
header and every row. Controlled, following the `expandedRowKeys` precedent exactly: the
|
|
11
|
+
table keeps no internal selection state, and `onSelectionChange` is the enabler (as
|
|
12
|
+
`renderRowDetail` is for expansion). The header checkbox is genuinely tri-state
|
|
13
|
+
(`accessibilityState.checked: 'mixed'` + `aria-checked="mixed"`), and only ever adds or
|
|
14
|
+
removes keys belonging to the CURRENT page — off-page keys the caller holds are preserved,
|
|
15
|
+
because the table must not drop a selection it cannot see.
|
|
16
|
+
- **Select all matching the filter — a FLAG, never an id list.** `matchingCount` +
|
|
17
|
+
`onSelectAllMatchingChange` add a banner once the page is fully selected and more rows
|
|
18
|
+
match. It emits `true`/`false`; the table never enumerates the matching rows (they are on
|
|
19
|
+
pages it never fetched, and the ZY-02 spike measured ~2–3 ms and ~16 DOM nodes per row, so
|
|
20
|
+
materialising thousands of them is indistinguishable from an outage). Toggling a single row
|
|
21
|
+
under the flag drops it — the operator is no longer acting on *the filter*.
|
|
22
|
+
- **Keyboard navigation** — `keyboardNavigation` (default **off**, because giving rows a
|
|
23
|
+
`tabIndex` changes a page's tab order) implements the ARIA grid **roving tabindex**: one tab
|
|
24
|
+
stop for the whole grid, ↑/↓ to move (clamped, never wrapping), Home/End, Space to toggle
|
|
25
|
+
selection, Enter to activate via the existing `onRowPress`. Keys the table does not handle
|
|
26
|
+
are never `preventDefault`ed, so Tab and browser shortcuts keep working. When the page
|
|
27
|
+
changes underneath it the tab stop re-homes onto the new first row rather than vanishing —
|
|
28
|
+
without that guard the grid would become keyboard-unreachable the moment an operator paged.
|
|
29
|
+
Web-only in effect (focus movement and key events are DOM concerns); inert on native, via
|
|
30
|
+
the same deliberate split as the `position: 'sticky'` header.
|
|
31
|
+
- **a11y** — `role="grid"` / `row` / `columnheader` / `cell` when navigable; `aria-selected`
|
|
32
|
+
on rows when selectable; row checkboxes are labelled with the ROW's name, so they announce
|
|
33
|
+
as "Instruction ABC, checkbox" rather than an anonymous "checkbox" repeated down the page.
|
|
34
|
+
- **🔴 A selectable row's checkbox sits OUTSIDE its pressable area** — a sibling, never a
|
|
35
|
+
descendant. A checkbox nested inside an interactive row's `Pressable` is precisely the shape
|
|
36
|
+
the 1.9.2 fix identified as broken: the row's pointer responders CAPTURE the gesture and
|
|
37
|
+
cancel the child's press, so the checkbox would pass a synthetic `element.click()` test and
|
|
38
|
+
silently do nothing under a real mouse, touch or Playwright click. A selectable row is now a
|
|
39
|
+
plain `<View>` frame holding the checkbox and a separate pressable content area.
|
|
40
|
+
- New exports: `rowSelectTestID(tableTestID, key)`, `selectAllTestID(tableTestID)`, the
|
|
41
|
+
`uiTables.select.*` keys on `TABLE_I18N`, and the `selectCell` / `selectBanner`
|
|
42
|
+
`styleOverrides` slots. No existing export changed.
|
|
43
|
+
- Internals split for clarity as the row grew three shapes: `DataTableRow`, `TableRow`,
|
|
44
|
+
`TableHeader`, `RowCells`, plus pure `selection.ts` / `rowNav.ts` rule modules and the
|
|
45
|
+
`useTableSelection` / `useRovingFocus` hooks. No behaviour change for existing consumers
|
|
46
|
+
(the full 1.9.2 suite passes untouched).
|
|
47
|
+
|
|
48
|
+
## 1.9.2
|
|
49
|
+
|
|
50
|
+
- **🔴 In-cell action buttons (Edit/Delete/Stop) now fire on a real pointer gesture, not just a bare
|
|
51
|
+
synthetic click.** A NON-interactive row (no `onRowPress`) was still rendered as a `<Pressable>`.
|
|
52
|
+
On react-native-web a `Pressable` installs pointer responders (pointerdown/up/cancel) on the row
|
|
53
|
+
container that CAPTURE a real mouse/touch gesture and cancel the press of any interactive child in
|
|
54
|
+
a cell — so a Delete/Stop/Edit button inside a static row looked clickable, fired on a bare
|
|
55
|
+
`element.click()`, but silently did nothing on an actual click/tap (and on a Playwright `.click()`,
|
|
56
|
+
which is why the AML v2 settings webhook-delete + stop-monitoring E2Es were red). A non-pressable
|
|
57
|
+
row is now a plain `<View>` (new `RowContainer`), so its cell controls receive the full gesture.
|
|
58
|
+
Interactive tables (`onRowPress`) are unchanged. Same class as the earlier `disabled`→
|
|
59
|
+
`pointer-events:none` fix; this closes the remaining pointer-responder-capture path.
|
|
60
|
+
|
|
3
61
|
## 1.9.0
|
|
4
62
|
|
|
5
63
|
- **`Pager` dropdown-variant rows menu now escapes ancestor stacking contexts (web).** The
|
package/README.md
CHANGED
|
@@ -57,6 +57,76 @@ with the exported `rowDetailTestID(tableTestID, key)` (rows: `rowTestID(tableTes
|
|
|
57
57
|
exposed to assistive tech as a labelled region (provide the `uiTables.rowDetail` key), and the row
|
|
58
58
|
reports `aria-expanded`. Omit both props and nothing about the table changes.
|
|
59
59
|
|
|
60
|
+
#### Bulk-select (optional)
|
|
61
|
+
|
|
62
|
+
Pass `onSelectionChange` to add a checkbox gutter (header + every row). **Selection is
|
|
63
|
+
controlled by you**, exactly like `expandedRowKeys`: the table keeps no internal selection
|
|
64
|
+
state. The header checkbox is tri-state and reports `aria-checked="mixed"` when only part of
|
|
65
|
+
the page is ticked.
|
|
66
|
+
|
|
67
|
+
```tsx
|
|
68
|
+
const [selected, setSelected] = useState<readonly string[]>([]);
|
|
69
|
+
|
|
70
|
+
<DataTable
|
|
71
|
+
columns={columns}
|
|
72
|
+
rows={rows}
|
|
73
|
+
keyExtractor={(r) => r.id} // the SAME key is matched against selectedRowKeys
|
|
74
|
+
selectedRowKeys={selected}
|
|
75
|
+
onSelectionChange={setSelected}
|
|
76
|
+
testID="grid"
|
|
77
|
+
/>
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
The header only ever adds or removes **this page's** keys — any off-page keys you hold are
|
|
81
|
+
preserved, because the table cannot see the rows they belong to. Test ids:
|
|
82
|
+
`rowSelectTestID(tableTestID, key)` and `selectAllTestID(tableTestID)`.
|
|
83
|
+
|
|
84
|
+
#### Select all matching the filter — a flag, not ids (optional)
|
|
85
|
+
|
|
86
|
+
This table is **server-paged and deliberately not virtualized** (see the ZY-02 grid spike:
|
|
87
|
+
render cost is linear at ~2–3 ms and ~16 DOM nodes per row, so a huge page is
|
|
88
|
+
indistinguishable from an outage). "Select all 3,023 matching" therefore **cannot** and
|
|
89
|
+
**must not** be an id list — the other pages were never fetched.
|
|
90
|
+
|
|
91
|
+
Add `matchingCount` (the server's total) + `onSelectAllMatchingChange` and, once the whole
|
|
92
|
+
page is ticked and more rows match, a banner offers the flag:
|
|
93
|
+
|
|
94
|
+
```tsx
|
|
95
|
+
<DataTable
|
|
96
|
+
/* …selection props… */
|
|
97
|
+
matchingCount={total} // same number your Pager shows
|
|
98
|
+
allMatchingSelected={allMatching} // controlled FLAG
|
|
99
|
+
onSelectAllMatchingChange={setAllMatching} // emits `true` / `false` — never ids
|
|
100
|
+
/>
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Resolve the flag **server-side against the same filter your list endpoint took**. That is a
|
|
104
|
+
better design anyway: the work survives the operator closing the tab. While the flag is set
|
|
105
|
+
every row reads as selected with an empty `selectedRowKeys`; toggling any single row drops
|
|
106
|
+
the flag (the operator is no longer acting on *the filter*).
|
|
107
|
+
|
|
108
|
+
#### Keyboard navigation (optional)
|
|
109
|
+
|
|
110
|
+
`keyboardNavigation` turns the table into a real ARIA grid using the **roving tabindex**
|
|
111
|
+
pattern — exactly one row is tabbable, so Tab crosses the grid in one hop instead of 100.
|
|
112
|
+
|
|
113
|
+
| Key | Action |
|
|
114
|
+
|---|---|
|
|
115
|
+
| ↑ / ↓ | Move the focused row (clamped — never wraps) |
|
|
116
|
+
| Home / End | First / last row on the page |
|
|
117
|
+
| Space | Toggle selection (when selectable) |
|
|
118
|
+
| Enter | Activate the row, via the existing `onRowPress` |
|
|
119
|
+
|
|
120
|
+
```tsx
|
|
121
|
+
<DataTable columns={columns} rows={rows} keyExtractor={(r) => r.id} keyboardNavigation onRowPress={open} />
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
**Off by default**, because adding `tabIndex` to rows changes a page's tab order. Web-only in
|
|
125
|
+
effect (focus movement and key events are DOM concerns); inert on native. Keys the table does
|
|
126
|
+
not handle are never `preventDefault`ed, so Tab and browser shortcuts keep working. When the
|
|
127
|
+
page changes underneath it, the tab stop re-homes onto the new first row rather than
|
|
128
|
+
disappearing.
|
|
129
|
+
|
|
60
130
|
#### Pixel-perfect overrides (optional)
|
|
61
131
|
|
|
62
132
|
**The defaults are opinionated but never mandatory.** When a surface must match an existing
|
package/dist/index.d.mts
CHANGED
|
@@ -54,6 +54,10 @@ interface DataTableStyleOverrides {
|
|
|
54
54
|
stateText?: StyleProp<TextStyle>;
|
|
55
55
|
/** The full-width detail panel under an expanded row. */
|
|
56
56
|
rowDetail?: StyleProp<ViewStyle>;
|
|
57
|
+
/** The fixed-width checkbox gutter, in the header and in every row. */
|
|
58
|
+
selectCell?: StyleProp<ViewStyle>;
|
|
59
|
+
/** The select-all-matching banner above the header. */
|
|
60
|
+
selectBanner?: StyleProp<ViewStyle>;
|
|
57
61
|
/** A card in the responsive card-stack (below `stackBreakpoint`). */
|
|
58
62
|
card?: StyleProp<ViewStyle>;
|
|
59
63
|
/** One label:value line inside a card. */
|
|
@@ -102,6 +106,59 @@ interface DataTableProps<T> {
|
|
|
102
106
|
* table adds no chevron and keeps no internal expand state.
|
|
103
107
|
*/
|
|
104
108
|
expandedRowKeys?: readonly string[];
|
|
109
|
+
/**
|
|
110
|
+
* Keys (as produced by `keyExtractor`) of the rows currently selected. Selection is
|
|
111
|
+
* CONTROLLED by the caller — the same contract as `expandedRowKeys`: own the state,
|
|
112
|
+
* update it from `onSelectionChange`. The table keeps no internal selection state.
|
|
113
|
+
*
|
|
114
|
+
* Keys the table cannot see (rows on other pages) are preserved, never dropped: the
|
|
115
|
+
* header checkbox only ever adds or removes keys belonging to the CURRENT page.
|
|
116
|
+
*/
|
|
117
|
+
selectedRowKeys?: readonly string[];
|
|
118
|
+
/**
|
|
119
|
+
* **Enables bulk-select** (the way `renderRowDetail` enables expansion): a checkbox
|
|
120
|
+
* gutter appears in the header and in every row. Emits the NEXT selection whenever a row
|
|
121
|
+
* or the header checkbox is toggled. Omit and nothing about the table changes.
|
|
122
|
+
*/
|
|
123
|
+
onSelectionChange?: (selectedRowKeys: readonly string[]) => void;
|
|
124
|
+
/**
|
|
125
|
+
* Total rows matching the CURRENT filter across EVERY page, as reported by the server
|
|
126
|
+
* (the same number the `Pager`'s `total` shows). Enables the "select all N matching this
|
|
127
|
+
* filter" affordance once the whole page is selected and more rows match than fit on it.
|
|
128
|
+
*
|
|
129
|
+
* Omit and bulk-select stays page-scoped.
|
|
130
|
+
*/
|
|
131
|
+
matchingCount?: number;
|
|
132
|
+
/**
|
|
133
|
+
* Whether "every row matching the filter" is selected — **a FLAG, not a set of ids.**
|
|
134
|
+
* CONTROLLED, like `selectedRowKeys`.
|
|
135
|
+
*
|
|
136
|
+
* While set, every row reads as selected without the caller enumerating anything.
|
|
137
|
+
*/
|
|
138
|
+
allMatchingSelected?: boolean;
|
|
139
|
+
/**
|
|
140
|
+
* Emits the select-all-matching **FLAG** (`true` to select all matching, `false` to
|
|
141
|
+
* clear). Enables the banner, together with `matchingCount`.
|
|
142
|
+
*
|
|
143
|
+
* 🔴 The table will NEVER hand you an id list for this. It cannot — the matching rows are
|
|
144
|
+
* on pages it never fetched — and it must not: the ZY-02 spike measured this grid at
|
|
145
|
+
* ~2–3 ms and ~16 DOM nodes per row, so materialising 5,000 selected rows is
|
|
146
|
+
* indistinguishable from an outage. Resolve the flag server-side against the same filter
|
|
147
|
+
* your list endpoint took; the work then survives the operator closing the tab.
|
|
148
|
+
*/
|
|
149
|
+
onSelectAllMatchingChange?: (allMatching: boolean) => void;
|
|
150
|
+
/**
|
|
151
|
+
* Enables keyboard navigation across rows (the ARIA grid roving-tabindex pattern):
|
|
152
|
+
* ArrowUp/ArrowDown move the focused row (clamped — never wrapping), Home/End jump to the
|
|
153
|
+
* first/last row on the page, Space toggles selection (when selectable), and Enter
|
|
154
|
+
* activates the row via the existing `onRowPress`.
|
|
155
|
+
*
|
|
156
|
+
* Default **off**: switching it on gives rows a `tabIndex`, which changes a page's tab
|
|
157
|
+
* order — so an existing table must opt in rather than silently shift under its users.
|
|
158
|
+
*
|
|
159
|
+
* Web-only in effect (focus movement and key events are DOM concerns); inert on native.
|
|
160
|
+
*/
|
|
161
|
+
keyboardNavigation?: boolean;
|
|
105
162
|
loading?: boolean;
|
|
106
163
|
/** Loading text (already translated). Falls back to the kit's `loading` translation. */
|
|
107
164
|
loadingLabel?: string;
|
|
@@ -134,14 +191,26 @@ interface DataTableProps<T> {
|
|
|
134
191
|
* `useWindowDimensions` (the CSS `data-label` card-stack does not port).
|
|
135
192
|
* Pass `stackBreakpoint={0}` to keep the desktop grid at every width.
|
|
136
193
|
* - per-row `testID` + `accessibilityLabel`/`accessibilityHint` (kit standard).
|
|
137
|
-
* - optional CONTROLLED expandable rows: `renderRowDetail` + `expandedRowKeys
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
*
|
|
194
|
+
* - optional CONTROLLED expandable rows: `renderRowDetail` + `expandedRowKeys`.
|
|
195
|
+
* - optional CONTROLLED **bulk-select**: `selectedRowKeys` + `onSelectionChange` add a
|
|
196
|
+
* checkbox gutter; `matchingCount` + `onSelectAllMatchingChange` add the "select all N
|
|
197
|
+
* matching this filter" banner, which emits a **FLAG, never an id list**.
|
|
198
|
+
* - optional **keyboard navigation** (`keyboardNavigation`): the ARIA grid roving-tabindex
|
|
199
|
+
* pattern — one tab stop for the whole grid, arrows to move, Space to select, Enter to
|
|
200
|
+
* activate. Off by default: giving rows a `tabIndex` changes a page's tab order.
|
|
141
201
|
* - optional per-slot `styleOverrides`, merged LAST so a consumer that needs to be
|
|
142
|
-
* pixel-perfect beats both the base StyleSheet and the inline theme colour.
|
|
143
|
-
* shared defaults never change for anyone who does not opt in.
|
|
202
|
+
* pixel-perfect beats both the base StyleSheet and the inline theme colour.
|
|
144
203
|
* - every colour from `useUi().theme`; every component-authored string via `t`.
|
|
204
|
+
*
|
|
205
|
+
* **Omit the optional props and the table renders exactly as it always has** — that is the
|
|
206
|
+
* contract every feature here is built to, and what keeps this a MINOR bump.
|
|
207
|
+
*
|
|
208
|
+
* **No virtualization, deliberately** (`zygos/docs/03-zy02-grid-spike.md`): this is a
|
|
209
|
+
* server-paged table — that is what `Pager` and `FilterBar` are for — and paging already
|
|
210
|
+
* buys everything virtualization would, without the surface area.
|
|
211
|
+
*
|
|
212
|
+
* This component is the ORCHESTRATOR: the frame, the state views, the header and the two
|
|
213
|
+
* layout branches. A row's own behaviour lives in `DataTableRow`.
|
|
145
214
|
*/
|
|
146
215
|
|
|
147
216
|
declare function DataTable<T>(props: DataTableProps<T>): React.ReactElement;
|
|
@@ -283,6 +352,14 @@ declare const TABLE_TEST_IDS: {
|
|
|
283
352
|
readonly rowInfix: "row";
|
|
284
353
|
/** Infix of an expanded row's detail panel: `${tableTestID}-row-detail-${key}`. */
|
|
285
354
|
readonly rowDetailInfix: "row-detail";
|
|
355
|
+
/** Infix of a row's select checkbox: `${tableTestID}-select-${key}`. */
|
|
356
|
+
readonly rowSelectInfix: "select";
|
|
357
|
+
/** Suffix of the header (select-all-on-page) checkbox: `${tableTestID}-select-all`. */
|
|
358
|
+
readonly selectAllSuffix: "select-all";
|
|
359
|
+
/** Suffix of the select-all-matching banner: `${tableTestID}-select-banner`. */
|
|
360
|
+
readonly selectBannerSuffix: "select-banner";
|
|
361
|
+
/** Suffix of the banner's action: `${tableTestID}-select-banner-action`. */
|
|
362
|
+
readonly selectBannerActionSuffix: "select-banner-action";
|
|
286
363
|
readonly filterBar: "ui-filters";
|
|
287
364
|
readonly results: "ui-results";
|
|
288
365
|
readonly pager: "ui-pager";
|
|
@@ -298,6 +375,14 @@ declare const rowTestID: (tableTestID: string, key: string) => string;
|
|
|
298
375
|
* consumers and e2e specs target the panel without re-deriving the shape.
|
|
299
376
|
*/
|
|
300
377
|
declare const rowDetailTestID: (tableTestID: string, key: string) => string;
|
|
378
|
+
/**
|
|
379
|
+
* The test id of a row's select checkbox: `${tableTestID}-select-${key}` (key from
|
|
380
|
+
* `keyExtractor`). Exported so consumers and e2e specs target a row's checkbox without
|
|
381
|
+
* re-deriving the shape.
|
|
382
|
+
*/
|
|
383
|
+
declare const rowSelectTestID: (tableTestID: string, key: string) => string;
|
|
384
|
+
/** The test id of the header (select-all-on-page) checkbox: `${tableTestID}-select-all`. */
|
|
385
|
+
declare const selectAllTestID: (tableTestID: string) => string;
|
|
301
386
|
/**
|
|
302
387
|
* Translation keys for every component-authored, user-facing string. Apps map
|
|
303
388
|
* these in their UiProvider `t` (FM); the neutral default `t` returns the key, so
|
|
@@ -310,6 +395,22 @@ declare const TABLE_I18N: {
|
|
|
310
395
|
readonly rowHint: "uiTables.rowHint";
|
|
311
396
|
/** Accessible name of the full-width detail panel under an expanded row. */
|
|
312
397
|
readonly rowDetail: "uiTables.rowDetail";
|
|
398
|
+
/** Accessible name of a row's select checkbox. */
|
|
399
|
+
readonly selectRow: "uiTables.select.row";
|
|
400
|
+
readonly selectRowHint: "uiTables.select.rowHint";
|
|
401
|
+
/** Accessible name of the header (select-all-on-page) checkbox. */
|
|
402
|
+
readonly selectAll: "uiTables.select.all";
|
|
403
|
+
readonly selectAllHint: "uiTables.select.allHint";
|
|
404
|
+
/** Banner, offer state: "All {{p1}} rows on this page are selected." */
|
|
405
|
+
readonly selectPageSelected: "uiTables.select.pageSelected";
|
|
406
|
+
/** Banner, offer action: "Select all {{p1}} matching this filter". */
|
|
407
|
+
readonly selectAllMatching: "uiTables.select.allMatching";
|
|
408
|
+
readonly selectAllMatchingHint: "uiTables.select.allMatchingHint";
|
|
409
|
+
/** Banner, active state: "All {{p1}} rows matching this filter are selected." */
|
|
410
|
+
readonly selectMatchingSelected: "uiTables.select.matchingSelected";
|
|
411
|
+
/** Banner, active action: "Clear selection". */
|
|
412
|
+
readonly selectClear: "uiTables.select.clear";
|
|
413
|
+
readonly selectClearHint: "uiTables.select.clearHint";
|
|
313
414
|
readonly results: "uiTables.results";
|
|
314
415
|
readonly pagerInfo: "uiTables.pager.info";
|
|
315
416
|
readonly pagerPrev: "uiTables.pager.prev";
|
|
@@ -322,4 +423,4 @@ declare const TABLE_I18N: {
|
|
|
322
423
|
readonly pagerRowsTriggerHint: "uiTables.pager.rowsTriggerHint";
|
|
323
424
|
};
|
|
324
425
|
|
|
325
|
-
export { CARD_STACK_BREAKPOINT, DEFAULT_PAGE_SIZE_OPTIONS, DataTable, type DataTableColumn, type DataTableProps, type DataTableStyleOverrides, FilterBar, type FilterBarProps, type FilterBarStyleOverrides, Pager, type PagerProps, type PagerStyleOverrides, StatCard, type StatCardProps, TABLE_I18N, TABLE_TEST_IDS, rowDetailTestID, rowTestID };
|
|
426
|
+
export { CARD_STACK_BREAKPOINT, DEFAULT_PAGE_SIZE_OPTIONS, DataTable, type DataTableColumn, type DataTableProps, type DataTableStyleOverrides, FilterBar, type FilterBarProps, type FilterBarStyleOverrides, Pager, type PagerProps, type PagerStyleOverrides, StatCard, type StatCardProps, TABLE_I18N, TABLE_TEST_IDS, rowDetailTestID, rowSelectTestID, rowTestID, selectAllTestID };
|
package/dist/index.d.ts
CHANGED
|
@@ -54,6 +54,10 @@ interface DataTableStyleOverrides {
|
|
|
54
54
|
stateText?: StyleProp<TextStyle>;
|
|
55
55
|
/** The full-width detail panel under an expanded row. */
|
|
56
56
|
rowDetail?: StyleProp<ViewStyle>;
|
|
57
|
+
/** The fixed-width checkbox gutter, in the header and in every row. */
|
|
58
|
+
selectCell?: StyleProp<ViewStyle>;
|
|
59
|
+
/** The select-all-matching banner above the header. */
|
|
60
|
+
selectBanner?: StyleProp<ViewStyle>;
|
|
57
61
|
/** A card in the responsive card-stack (below `stackBreakpoint`). */
|
|
58
62
|
card?: StyleProp<ViewStyle>;
|
|
59
63
|
/** One label:value line inside a card. */
|
|
@@ -102,6 +106,59 @@ interface DataTableProps<T> {
|
|
|
102
106
|
* table adds no chevron and keeps no internal expand state.
|
|
103
107
|
*/
|
|
104
108
|
expandedRowKeys?: readonly string[];
|
|
109
|
+
/**
|
|
110
|
+
* Keys (as produced by `keyExtractor`) of the rows currently selected. Selection is
|
|
111
|
+
* CONTROLLED by the caller — the same contract as `expandedRowKeys`: own the state,
|
|
112
|
+
* update it from `onSelectionChange`. The table keeps no internal selection state.
|
|
113
|
+
*
|
|
114
|
+
* Keys the table cannot see (rows on other pages) are preserved, never dropped: the
|
|
115
|
+
* header checkbox only ever adds or removes keys belonging to the CURRENT page.
|
|
116
|
+
*/
|
|
117
|
+
selectedRowKeys?: readonly string[];
|
|
118
|
+
/**
|
|
119
|
+
* **Enables bulk-select** (the way `renderRowDetail` enables expansion): a checkbox
|
|
120
|
+
* gutter appears in the header and in every row. Emits the NEXT selection whenever a row
|
|
121
|
+
* or the header checkbox is toggled. Omit and nothing about the table changes.
|
|
122
|
+
*/
|
|
123
|
+
onSelectionChange?: (selectedRowKeys: readonly string[]) => void;
|
|
124
|
+
/**
|
|
125
|
+
* Total rows matching the CURRENT filter across EVERY page, as reported by the server
|
|
126
|
+
* (the same number the `Pager`'s `total` shows). Enables the "select all N matching this
|
|
127
|
+
* filter" affordance once the whole page is selected and more rows match than fit on it.
|
|
128
|
+
*
|
|
129
|
+
* Omit and bulk-select stays page-scoped.
|
|
130
|
+
*/
|
|
131
|
+
matchingCount?: number;
|
|
132
|
+
/**
|
|
133
|
+
* Whether "every row matching the filter" is selected — **a FLAG, not a set of ids.**
|
|
134
|
+
* CONTROLLED, like `selectedRowKeys`.
|
|
135
|
+
*
|
|
136
|
+
* While set, every row reads as selected without the caller enumerating anything.
|
|
137
|
+
*/
|
|
138
|
+
allMatchingSelected?: boolean;
|
|
139
|
+
/**
|
|
140
|
+
* Emits the select-all-matching **FLAG** (`true` to select all matching, `false` to
|
|
141
|
+
* clear). Enables the banner, together with `matchingCount`.
|
|
142
|
+
*
|
|
143
|
+
* 🔴 The table will NEVER hand you an id list for this. It cannot — the matching rows are
|
|
144
|
+
* on pages it never fetched — and it must not: the ZY-02 spike measured this grid at
|
|
145
|
+
* ~2–3 ms and ~16 DOM nodes per row, so materialising 5,000 selected rows is
|
|
146
|
+
* indistinguishable from an outage. Resolve the flag server-side against the same filter
|
|
147
|
+
* your list endpoint took; the work then survives the operator closing the tab.
|
|
148
|
+
*/
|
|
149
|
+
onSelectAllMatchingChange?: (allMatching: boolean) => void;
|
|
150
|
+
/**
|
|
151
|
+
* Enables keyboard navigation across rows (the ARIA grid roving-tabindex pattern):
|
|
152
|
+
* ArrowUp/ArrowDown move the focused row (clamped — never wrapping), Home/End jump to the
|
|
153
|
+
* first/last row on the page, Space toggles selection (when selectable), and Enter
|
|
154
|
+
* activates the row via the existing `onRowPress`.
|
|
155
|
+
*
|
|
156
|
+
* Default **off**: switching it on gives rows a `tabIndex`, which changes a page's tab
|
|
157
|
+
* order — so an existing table must opt in rather than silently shift under its users.
|
|
158
|
+
*
|
|
159
|
+
* Web-only in effect (focus movement and key events are DOM concerns); inert on native.
|
|
160
|
+
*/
|
|
161
|
+
keyboardNavigation?: boolean;
|
|
105
162
|
loading?: boolean;
|
|
106
163
|
/** Loading text (already translated). Falls back to the kit's `loading` translation. */
|
|
107
164
|
loadingLabel?: string;
|
|
@@ -134,14 +191,26 @@ interface DataTableProps<T> {
|
|
|
134
191
|
* `useWindowDimensions` (the CSS `data-label` card-stack does not port).
|
|
135
192
|
* Pass `stackBreakpoint={0}` to keep the desktop grid at every width.
|
|
136
193
|
* - per-row `testID` + `accessibilityLabel`/`accessibilityHint` (kit standard).
|
|
137
|
-
* - optional CONTROLLED expandable rows: `renderRowDetail` + `expandedRowKeys
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
*
|
|
194
|
+
* - optional CONTROLLED expandable rows: `renderRowDetail` + `expandedRowKeys`.
|
|
195
|
+
* - optional CONTROLLED **bulk-select**: `selectedRowKeys` + `onSelectionChange` add a
|
|
196
|
+
* checkbox gutter; `matchingCount` + `onSelectAllMatchingChange` add the "select all N
|
|
197
|
+
* matching this filter" banner, which emits a **FLAG, never an id list**.
|
|
198
|
+
* - optional **keyboard navigation** (`keyboardNavigation`): the ARIA grid roving-tabindex
|
|
199
|
+
* pattern — one tab stop for the whole grid, arrows to move, Space to select, Enter to
|
|
200
|
+
* activate. Off by default: giving rows a `tabIndex` changes a page's tab order.
|
|
141
201
|
* - optional per-slot `styleOverrides`, merged LAST so a consumer that needs to be
|
|
142
|
-
* pixel-perfect beats both the base StyleSheet and the inline theme colour.
|
|
143
|
-
* shared defaults never change for anyone who does not opt in.
|
|
202
|
+
* pixel-perfect beats both the base StyleSheet and the inline theme colour.
|
|
144
203
|
* - every colour from `useUi().theme`; every component-authored string via `t`.
|
|
204
|
+
*
|
|
205
|
+
* **Omit the optional props and the table renders exactly as it always has** — that is the
|
|
206
|
+
* contract every feature here is built to, and what keeps this a MINOR bump.
|
|
207
|
+
*
|
|
208
|
+
* **No virtualization, deliberately** (`zygos/docs/03-zy02-grid-spike.md`): this is a
|
|
209
|
+
* server-paged table — that is what `Pager` and `FilterBar` are for — and paging already
|
|
210
|
+
* buys everything virtualization would, without the surface area.
|
|
211
|
+
*
|
|
212
|
+
* This component is the ORCHESTRATOR: the frame, the state views, the header and the two
|
|
213
|
+
* layout branches. A row's own behaviour lives in `DataTableRow`.
|
|
145
214
|
*/
|
|
146
215
|
|
|
147
216
|
declare function DataTable<T>(props: DataTableProps<T>): React.ReactElement;
|
|
@@ -283,6 +352,14 @@ declare const TABLE_TEST_IDS: {
|
|
|
283
352
|
readonly rowInfix: "row";
|
|
284
353
|
/** Infix of an expanded row's detail panel: `${tableTestID}-row-detail-${key}`. */
|
|
285
354
|
readonly rowDetailInfix: "row-detail";
|
|
355
|
+
/** Infix of a row's select checkbox: `${tableTestID}-select-${key}`. */
|
|
356
|
+
readonly rowSelectInfix: "select";
|
|
357
|
+
/** Suffix of the header (select-all-on-page) checkbox: `${tableTestID}-select-all`. */
|
|
358
|
+
readonly selectAllSuffix: "select-all";
|
|
359
|
+
/** Suffix of the select-all-matching banner: `${tableTestID}-select-banner`. */
|
|
360
|
+
readonly selectBannerSuffix: "select-banner";
|
|
361
|
+
/** Suffix of the banner's action: `${tableTestID}-select-banner-action`. */
|
|
362
|
+
readonly selectBannerActionSuffix: "select-banner-action";
|
|
286
363
|
readonly filterBar: "ui-filters";
|
|
287
364
|
readonly results: "ui-results";
|
|
288
365
|
readonly pager: "ui-pager";
|
|
@@ -298,6 +375,14 @@ declare const rowTestID: (tableTestID: string, key: string) => string;
|
|
|
298
375
|
* consumers and e2e specs target the panel without re-deriving the shape.
|
|
299
376
|
*/
|
|
300
377
|
declare const rowDetailTestID: (tableTestID: string, key: string) => string;
|
|
378
|
+
/**
|
|
379
|
+
* The test id of a row's select checkbox: `${tableTestID}-select-${key}` (key from
|
|
380
|
+
* `keyExtractor`). Exported so consumers and e2e specs target a row's checkbox without
|
|
381
|
+
* re-deriving the shape.
|
|
382
|
+
*/
|
|
383
|
+
declare const rowSelectTestID: (tableTestID: string, key: string) => string;
|
|
384
|
+
/** The test id of the header (select-all-on-page) checkbox: `${tableTestID}-select-all`. */
|
|
385
|
+
declare const selectAllTestID: (tableTestID: string) => string;
|
|
301
386
|
/**
|
|
302
387
|
* Translation keys for every component-authored, user-facing string. Apps map
|
|
303
388
|
* these in their UiProvider `t` (FM); the neutral default `t` returns the key, so
|
|
@@ -310,6 +395,22 @@ declare const TABLE_I18N: {
|
|
|
310
395
|
readonly rowHint: "uiTables.rowHint";
|
|
311
396
|
/** Accessible name of the full-width detail panel under an expanded row. */
|
|
312
397
|
readonly rowDetail: "uiTables.rowDetail";
|
|
398
|
+
/** Accessible name of a row's select checkbox. */
|
|
399
|
+
readonly selectRow: "uiTables.select.row";
|
|
400
|
+
readonly selectRowHint: "uiTables.select.rowHint";
|
|
401
|
+
/** Accessible name of the header (select-all-on-page) checkbox. */
|
|
402
|
+
readonly selectAll: "uiTables.select.all";
|
|
403
|
+
readonly selectAllHint: "uiTables.select.allHint";
|
|
404
|
+
/** Banner, offer state: "All {{p1}} rows on this page are selected." */
|
|
405
|
+
readonly selectPageSelected: "uiTables.select.pageSelected";
|
|
406
|
+
/** Banner, offer action: "Select all {{p1}} matching this filter". */
|
|
407
|
+
readonly selectAllMatching: "uiTables.select.allMatching";
|
|
408
|
+
readonly selectAllMatchingHint: "uiTables.select.allMatchingHint";
|
|
409
|
+
/** Banner, active state: "All {{p1}} rows matching this filter are selected." */
|
|
410
|
+
readonly selectMatchingSelected: "uiTables.select.matchingSelected";
|
|
411
|
+
/** Banner, active action: "Clear selection". */
|
|
412
|
+
readonly selectClear: "uiTables.select.clear";
|
|
413
|
+
readonly selectClearHint: "uiTables.select.clearHint";
|
|
313
414
|
readonly results: "uiTables.results";
|
|
314
415
|
readonly pagerInfo: "uiTables.pager.info";
|
|
315
416
|
readonly pagerPrev: "uiTables.pager.prev";
|
|
@@ -322,4 +423,4 @@ declare const TABLE_I18N: {
|
|
|
322
423
|
readonly pagerRowsTriggerHint: "uiTables.pager.rowsTriggerHint";
|
|
323
424
|
};
|
|
324
425
|
|
|
325
|
-
export { CARD_STACK_BREAKPOINT, DEFAULT_PAGE_SIZE_OPTIONS, DataTable, type DataTableColumn, type DataTableProps, type DataTableStyleOverrides, FilterBar, type FilterBarProps, type FilterBarStyleOverrides, Pager, type PagerProps, type PagerStyleOverrides, StatCard, type StatCardProps, TABLE_I18N, TABLE_TEST_IDS, rowDetailTestID, rowTestID };
|
|
426
|
+
export { CARD_STACK_BREAKPOINT, DEFAULT_PAGE_SIZE_OPTIONS, DataTable, type DataTableColumn, type DataTableProps, type DataTableStyleOverrides, FilterBar, type FilterBarProps, type FilterBarStyleOverrides, Pager, type PagerProps, type PagerStyleOverrides, StatCard, type StatCardProps, TABLE_I18N, TABLE_TEST_IDS, rowDetailTestID, rowSelectTestID, rowTestID, selectAllTestID };
|