@dloizides/ui-tables 1.9.2 → 1.11.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/ADOPTION.md ADDED
@@ -0,0 +1,163 @@
1
+ # Adopting the shared `Filters` + `Pager` (migration wave)
2
+
3
+ `@dloizides/ui-tables@1.11.0` ships the declarative **`Filters`** bar, the **`useFilterDraft`**
4
+ state engine, and additive **`Pager`** props (`showFirstLast`, `unitLabelSingular`, `responsive`).
5
+ This doc maps each portal's CURRENT hand-rolled filters + pagination onto the shared API so a
6
+ follow-up wave can migrate them one screen at a time. **Nothing here is done yet** — this release
7
+ delivers the package + tests only; adoption is deliberately separate to avoid colliding with other
8
+ agents' in-flight work.
9
+
10
+ Everything is additive and backward compatible: existing `FilterBar` / `Pager` / `DataTable`
11
+ usage is unchanged. Adopt `Filters` screen-by-screen; there is no big-bang cutover.
12
+
13
+ ---
14
+
15
+ ## The shared API in one screen
16
+
17
+ ```tsx
18
+ import { Filters, useFilterDraft, Pager, type FilterField, type FilterValues } from '@dloizides/ui-tables';
19
+ ```
20
+
21
+ - **`Filters`** renders a `fields: FilterField[]` schema into the `FilterBar` shell.
22
+ - **Field kinds**: `select`, `text`, `number`, `dateRange`, `typeahead`, `boolean`.
23
+ - **Value map** `FilterValues = Record<string, string | boolean | { from; to }>`, keyed by `field.key`.
24
+ - **Value model** is chosen by whether you pass `onApply`:
25
+ - no `onApply` → **LIVE** (each edit calls `onChange`).
26
+ - `onApply` set → **DRAFT/APPLY** (Apply button + Enter-in-a-field commit; pass `onClear` for Reset).
27
+ - **`useFilterDraft({ initial, onApply, onReset })`** is the draft engine — wire `onApply`/`onReset` to `setPage(1)`.
28
+ - Every user-facing string is a **pre-localized** value you pass in (labels, option labels, placeholders, errors).
29
+
30
+ ---
31
+
32
+ ## aml-v2 — cases / leaders / peps (DRAFT/APPLY; the richest filter set)
33
+
34
+ Today: `CasesFilters` / `LeadersFilters` / `PepsFilters` render `<Text label>` + a per-field
35
+ control (ModalDropdown / ThemedTextInput / DateField / CountryPicker / FormSwitch); each host
36
+ holds `draft` + `committed` + `page` + `pageSize`, commits on Apply, resets page to 1.
37
+
38
+ Map onto the shared API:
39
+
40
+ | aml field | current control | → `FilterField` kind |
41
+ |---|---|---|
42
+ | `decision` / `reviewStatus` / `source` / `riskBand` / `isMatch` / `role` / `status` / `category` | `ModalDropdown` (leading "Any", value `''`) | `select` (options with a leading `{ label: FM('..any'), value: '' }`) |
43
+ | `q` | `ThemedTextInput`, submit → apply | `text` (`grow: true`) |
44
+ | `yearFrom` / `yearTo` | `ThemedTextInput keyboardType="numeric"` | `number` |
45
+ | `from` / `to` | `DateField` (native `<input type=date>`) | one `dateRange` field `{ key: 'dates' }` |
46
+ | `country` | `CountryPicker` (bespoke typeahead) | `typeahead` (`options: countryOptions, minChars: 1`) |
47
+ | `includeRelatives` / `prioritize` | `FormSwitch` | `boolean` |
48
+
49
+ - Replace the twin `draft`/`committed` `useState`s with `useFilterDraft({ initial: EMPTY, onApply: () => setPage(1), onReset: () => { setPage(1); clearCountryError(); } })`.
50
+ - `values={draft.draft}`, `onChange={draft.setDraft}`, `onApply={draft.apply}`, `onClear={draft.reset}` (leaders/peps have Reset; cases did not — omit `onClear` there).
51
+ - `applyDisabled={busy}` (aml disables Apply while loading).
52
+ - Export CSV/PDF buttons → the `actions` slot; keep operating on `draft.committed`.
53
+ - Country validation → set the field's `error` (pre-localized `FM('leaders.error.unrecognisedCountry')`); the `typeahead` renders the persistent `role="alert"` banner. Use the exported `isUnmatched(countryOptions, text)` to detect an unrecognised entry, or keep aml's `codeOf`.
54
+ - Results count: keep passing `resultsCount` + `resultsLabel` (aml already singularises the noun caller-side — `resultOne`/`resultMany`).
55
+ - **Select rendering**: to keep aml's exact ModalDropdown UX (responsive modal on mobile), pass `renderSelect={({ field, value, onChange, testID }) => <ModalDropdown … />}`. Otherwise use the built-in in-tree dropdown.
56
+ - Pager is already the shared `Pager` (rowsVariant="dropdown"); no change needed. Optionally add `unitLabelSingular` now that it exists.
57
+
58
+ ---
59
+
60
+ ## kefi-web — audit log (DRAFT/APPLY; the prime migration candidate)
61
+
62
+ Today: bespoke `AuditFilters` (local `draft`, Apply/Clear, date-validity gate) + bespoke
63
+ `AuditPager` (two lines: "showing X–Y of N" + "page X of N", Prev/Next only). Uses `DataTable`
64
+ already (via `KefiDataTable`) but NOT the shared `FilterBar`/`Pager`.
65
+
66
+ Map:
67
+
68
+ | audit field | current | → kind |
69
+ |---|---|---|
70
+ | `action` / `entityType` | exact-match text | `text` |
71
+ | `from` / `to` (`YYYY-MM-DD`) | two date text inputs | one `dateRange` field |
72
+
73
+ - `useFilterDraft({ initial: { action:'', entityType:'', dates:{from:'',to:''} }, onApply: () => setPage(1) })`.
74
+ - `onApply={draft.apply}` (Apply), `onClear={draft.reset}` (Clear resets draft AND committed — matches today).
75
+ - `applyDisabled={!datesValid}` — keep the `isValidDateInput` gate; keep the inline `FeedbackBanner` above (or move the message onto a field `error`).
76
+ - Convert `toQuery` to read `dates.from` / `dates.to` (was `from` / `to`).
77
+ - Replace `AuditPager` with `Pager` (`page`, `pageSize`, `total={totalCount}`, `unitLabel`, `infoPrefix={FM('common.showing')}`). The "page X of N" line is not encoded in `Pager` — either drop it (the `from–to of N` covers it) or keep a small caption alongside.
78
+
79
+ ---
80
+
81
+ ## zygos-web — instructions / approvals (LIVE; the canonical model)
82
+
83
+ Today: `InstructionsFilters` renders text search + three `ModalDropdown`s; `useInstructionsQuery`
84
+ patch-merges edits (`patchFilter`) and resets to page 1 on any change. Already uses shared
85
+ `FilterBar` + `Pager` + `DataTable`.
86
+
87
+ Map (LIVE — no `onApply`):
88
+
89
+ | field | current | → kind |
90
+ |---|---|---|
91
+ | `search` | `ThemedTextInput` | `text` (`grow: true`) |
92
+ | `statuses` | `ModalDropdown` (single control emitting a 1-element list) | `select` — keep the control single; map `value` ↔ `statuses[0]` in `onChange` |
93
+ | `direction` / `currency` | `ModalDropdown` | `select` |
94
+ | `valueDateFrom`/`To`, `minAmount`/`maxAmount`, `sortBy` | latent in types, not yet rendered | add as `dateRange` / two `number` / a `select` when you surface them |
95
+
96
+ - `values` = the current filter; `onChange` = replace-then-`patchFilter` (or adapt `patchFilter` to accept the full map).
97
+ - The pinned/locked-key pattern (approvals' `APPROVALS_FILTER` + `LOCKED_KEYS`) → simply **omit** the locked field from the `fields` array for that screen (the shared bar renders exactly the fields you pass).
98
+ - `BulkApproveBar` → the `actions` slot (it already goes into `FilterBar.actions`).
99
+ - Pager already shared with `pageSizeOptions={[25,50,100]}` (API cap) + `boldNumbers` — unchanged.
100
+
101
+ ---
102
+
103
+ ## agora-web — products / orders (LIVE)
104
+
105
+ Today: `ProductsFilters` (text search + category `ModalDropdown`), `OrdersFilters` (status
106
+ `ModalDropdown`); `useProductsQuery`/`useOrdersQuery` set values live and reset page to 1. Already
107
+ uses shared `FilterBar` + `Pager` + `DataTable`.
108
+
109
+ Map (LIVE):
110
+
111
+ | field | → kind |
112
+ |---|---|
113
+ | products `search` | `text` (`grow: true`) |
114
+ | products `categoryId` (sentinel `''`) | `select` |
115
+ | orders `status` (`OrderStatus \| ''`) | `select` (map `'' → undefined` in `onChange`) |
116
+
117
+ - Trivial migration: build the two/one field(s), pass `values` + `onChange`, keep `resultsCount`.
118
+ - Pager unchanged (kit defaults, pills variant).
119
+
120
+ ---
121
+
122
+ ## erevna-web / katalogos-web — menus / users / public menu (LIVE)
123
+
124
+ Today: hand-rolled, using ui-tables **only for `StatCard`** — no `FilterBar`/`Pager`. Several
125
+ distinct surfaces:
126
+
127
+ - **Public-menu filter** (`useMenuFilter`): text-search-with-clear + dietary-tag multi-select
128
+ chips. Map the search to a `text` field; the tag chips are a **multi-select** — not one of the
129
+ six first-class kinds yet. Options for now: keep the bespoke chip row in the `actions`/children,
130
+ OR model each tag as a `boolean` field, OR wait for a `multiSelect` kind (candidate for a
131
+ future minor). The `hasActiveFilters` + `clearAllFilters` contract maps to `onClear`.
132
+ - **Menus admin list** (`MenuTabBar`, `MenuTabFilter` enum All/Active): a single `select`
133
+ (`{All, Active}`) — or keep the tab bar (it is a segmented control, a different UI affordance).
134
+ - **Users list** (`TenantSelector` pills): a `select` of tenants (+ "All Users" = value `''`).
135
+ - **Generic `PaginationControls`** (first/prev/next/last, "Showing a-b of N", "p / total",
136
+ 0-based) + `PaginatedList`: replace with `Pager` using `showFirstLast`. Note `Pager` is
137
+ **1-based** — add 1 when mapping from the 0-based `currentPage`. `unitLabelSingular` covers the
138
+ singular the current templates lack.
139
+ - **`VersionHistoryPanel`** "Load More": `Pager` does not do load-more; keep it bespoke, or
140
+ switch that panel to page-based `Pager`.
141
+ - **`BillingHistoryTable`** (server prev/next-only + mobile horizontal-scroll): `Pager` without
142
+ `showFirstLast`; the DataTable card-stack replaces the manual `minWidth:500` scroll wrapper.
143
+
144
+ ---
145
+
146
+ ## Not yet first-class (candidates for a future minor)
147
+
148
+ Surfaced by the harvest but intentionally out of the initial six kinds — add on real second use:
149
+
150
+ - **`multiSelect`** — zygos `statuses` (list-shaped), erevna dietary-tag chips, katalogos tags.
151
+ - **`sort`** control — zygos `sortBy` + `sortDescending` (in types, no UI yet).
152
+ - **Load-more / infinite pager** — erevna `VersionHistoryPanel` (only one consumer).
153
+ - **"page X of N" position line** — kefi audit's second pager line (the `from–to of N` covers it).
154
+
155
+ ---
156
+
157
+ ## Pager prop cheatsheet (new in 1.11.0)
158
+
159
+ | Prop | Effect | Adopt where |
160
+ |---|---|---|
161
+ | `showFirstLast` | First/Last jump buttons (disabled at bounds) | erevna `PaginationControls`, any large dataset |
162
+ | `unitLabelSingular` | `1 result` when `total === 1` | anywhere a unit noun is shown |
163
+ | `responsive` + `stackBreakpoint` | compact Prev/Next-only nav below the breakpoint | mobile / narrow surfaces |
package/CHANGELOG.md CHANGED
@@ -1,5 +1,79 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.11.0
4
+
5
+ Additive: a **declarative `Filters` bar** + **Pager** enhancements. Every change is additive and
6
+ backward compatible — existing `FilterBar` / `Pager` / `DataTable` consumers (aml-v2, agora,
7
+ zygos, kefi, erevna, katalogos) are untouched and every new prop is optional, so a MINOR bump.
8
+ No app is migrated by this release; adoption is a later wave (see `ADOPTION.md`).
9
+
10
+ - **`Filters`** — the declarative, configurable filter bar built ON the existing `FilterBar`
11
+ shell (reusing its live results count + WCAG live region + actions slot). A caller passes a
12
+ `fields` schema — the SUPERSET harvested from every portal's hand-rolled filters — of kinds
13
+ `select` / `text` / `number` / `dateRange` / `typeahead` / `boolean`, plus a value map and
14
+ `onChange`. Two value models: **LIVE** (edits apply immediately — agora, zygos) and
15
+ **DRAFT/APPLY** (edits accumulate in a draft, an Apply button + Enter-in-a-field commit it —
16
+ aml, kefi audit), the latter driven by the new `useFilterDraft` hook. Customisation is style
17
+ (theme) + slots only: every label/option/placeholder/error is a pre-localized string; no
18
+ FM/router/store. Apps can inject `@dloizides/ui-layout`'s `ModalDropdown` for the `select`
19
+ field via `renderSelect` (the in-tree dropdown is the dependency-free default).
20
+ - **`useFilterDraft`** — the draft-vs-applied state engine (draft + committed + `apply` / `reset`
21
+ / `setField` / `dirty`), with `onApply` / `onReset` callbacks the caller wires to `setPage(1)`
22
+ (the universal reset-to-page-1-on-narrowing invariant, kept free of pagination coupling).
23
+ - **`suggestOptions` / `isUnmatched`** — the ranked substring matcher behind the `typeahead`
24
+ field (generalized from aml's `suggestCountries`), exported for reuse.
25
+ - **`Pager`** — three additive props reconciling the variants across apps: `showFirstLast`
26
+ (First/Last jump buttons, disabled at bounds — erevna's `PaginationControls`),
27
+ `unitLabelSingular` (renders `1 result` when `total === 1` — the singularisation apps did in
28
+ the FilterBar noun), and `responsive` + `stackBreakpoint` (collapse to a compact
29
+ Prev/Next-only nav below the breakpoint — the mobile fallback, mirroring the DataTable
30
+ card-stack). New pager test ids `ui-pager-first` / `ui-pager-last`.
31
+
32
+ ## 1.10.0
33
+
34
+ Additive: **bulk-select** + **keyboard navigation** on `DataTable` (ZY-08). Every new prop is
35
+ optional and CONTROLLED — omit them all and the table renders exactly as it did on 1.9.2, so
36
+ erevna / katalogos / kefi / agora are unaffected. Hence a MINOR bump.
37
+
38
+ - **Bulk-select** — `selectedRowKeys` + `onSelectionChange` add a checkbox gutter to the
39
+ header and every row. Controlled, following the `expandedRowKeys` precedent exactly: the
40
+ table keeps no internal selection state, and `onSelectionChange` is the enabler (as
41
+ `renderRowDetail` is for expansion). The header checkbox is genuinely tri-state
42
+ (`accessibilityState.checked: 'mixed'` + `aria-checked="mixed"`), and only ever adds or
43
+ removes keys belonging to the CURRENT page — off-page keys the caller holds are preserved,
44
+ because the table must not drop a selection it cannot see.
45
+ - **Select all matching the filter — a FLAG, never an id list.** `matchingCount` +
46
+ `onSelectAllMatchingChange` add a banner once the page is fully selected and more rows
47
+ match. It emits `true`/`false`; the table never enumerates the matching rows (they are on
48
+ pages it never fetched, and the ZY-02 spike measured ~2–3 ms and ~16 DOM nodes per row, so
49
+ materialising thousands of them is indistinguishable from an outage). Toggling a single row
50
+ under the flag drops it — the operator is no longer acting on *the filter*.
51
+ - **Keyboard navigation** — `keyboardNavigation` (default **off**, because giving rows a
52
+ `tabIndex` changes a page's tab order) implements the ARIA grid **roving tabindex**: one tab
53
+ stop for the whole grid, ↑/↓ to move (clamped, never wrapping), Home/End, Space to toggle
54
+ selection, Enter to activate via the existing `onRowPress`. Keys the table does not handle
55
+ are never `preventDefault`ed, so Tab and browser shortcuts keep working. When the page
56
+ changes underneath it the tab stop re-homes onto the new first row rather than vanishing —
57
+ without that guard the grid would become keyboard-unreachable the moment an operator paged.
58
+ Web-only in effect (focus movement and key events are DOM concerns); inert on native, via
59
+ the same deliberate split as the `position: 'sticky'` header.
60
+ - **a11y** — `role="grid"` / `row` / `columnheader` / `cell` when navigable; `aria-selected`
61
+ on rows when selectable; row checkboxes are labelled with the ROW's name, so they announce
62
+ as "Instruction ABC, checkbox" rather than an anonymous "checkbox" repeated down the page.
63
+ - **🔴 A selectable row's checkbox sits OUTSIDE its pressable area** — a sibling, never a
64
+ descendant. A checkbox nested inside an interactive row's `Pressable` is precisely the shape
65
+ the 1.9.2 fix identified as broken: the row's pointer responders CAPTURE the gesture and
66
+ cancel the child's press, so the checkbox would pass a synthetic `element.click()` test and
67
+ silently do nothing under a real mouse, touch or Playwright click. A selectable row is now a
68
+ plain `<View>` frame holding the checkbox and a separate pressable content area.
69
+ - New exports: `rowSelectTestID(tableTestID, key)`, `selectAllTestID(tableTestID)`, the
70
+ `uiTables.select.*` keys on `TABLE_I18N`, and the `selectCell` / `selectBanner`
71
+ `styleOverrides` slots. No existing export changed.
72
+ - Internals split for clarity as the row grew three shapes: `DataTableRow`, `TableRow`,
73
+ `TableHeader`, `RowCells`, plus pure `selection.ts` / `rowNav.ts` rule modules and the
74
+ `useTableSelection` / `useRovingFocus` hooks. No behaviour change for existing consumers
75
+ (the full 1.9.2 suite passes untouched).
76
+
3
77
  ## 1.9.2
4
78
 
5
79
  - **🔴 In-cell action buttons (Edit/Delete/Stop) now fire on a real pointer gesture, not just a bare
package/README.md CHANGED
@@ -10,7 +10,8 @@ portfolio. Reads theme + translations from the shared `@dloizides/ui-feedback` U
10
10
  | `StatCard` | ✅ Available — labelled metric tile (label + locale-formatted value). |
11
11
  | `DataTable` | ✅ Available — the shared, tokenized RN-web grid (the `GRID.md` contract): `columns + rows` API, sticky header, zebra striping, per-row tint, pressable rows, per-row `testID` + a11y, optional **expandable rows**, and a responsive label:value **card-stack** below `stackBreakpoint`. |
12
12
  | `FilterBar` | ✅ Available — the `.ui-filters` shell: wrapping field row + live results count + actions slot. |
13
- | `Pager` | ✅ Available — the `.ui-pager` control: `from–to of N` page-info + rows-per-page control + Prev/Next. Pass an optional, already-translated `unitLabel` (e.g. `"leadership terms"`) to render `1–50 of 3,023 leadership terms`. The rows-per-page control defaults to a row of size **pills** (`rowsVariant="pills"`); pass `rowsVariant="dropdown"` for the compact v1-console `<select>`-style anchored dropdown (trigger + chevron + popover, mixed-case "Rows" caption). |
13
+ | `Filters` | ✅ Available — the **declarative** filter bar built ON `FilterBar`: pass a `fields` schema (`select` / `text` / `number` / `dateRange` / `typeahead` / `boolean`) + a value map + `onChange`. Two value models (LIVE, or DRAFT/APPLY via `useFilterDraft` + an Apply button). The superset of every portal's hand-rolled filters; only the theme changes. See [Filters](#filters--declarative-filter-bar). |
14
+ | `Pager` | ✅ Available — the `.ui-pager` control: `from–to of N` page-info + rows-per-page control + Prev/Next (+ optional **First/Last** via `showFirstLast`). Pass an optional, already-translated `unitLabel` (e.g. `"leadership terms"`) — plus `unitLabelSingular` for `1 result` **singularisation** — to render `1–50 of 3,023 leadership terms`. `responsive` collapses to a compact Prev/Next-only nav below `stackBreakpoint` (mobile fallback). The rows-per-page control defaults to size **pills** (`rowsVariant="pills"`); pass `rowsVariant="dropdown"` for the compact `<select>`-style anchored dropdown. |
14
15
  | `StatGrid` | ⏳ Deferred — exists only in kefi-web (n=1); moves in when a 2nd consumer appears. |
15
16
 
16
17
  ### DataTable / FilterBar / Pager
@@ -28,6 +29,70 @@ const columns: DataTableColumn<Row>[] = [
28
29
  <Pager page={page} pageSize={size} total={total} onPageChange={setPage} onPageSizeChange={setSize} />
29
30
  ```
30
31
 
32
+ ### Filters — declarative filter bar
33
+
34
+ `FilterBar` is the *shell* (layout + results count + actions). `Filters` is the *declarative*
35
+ bar built on it: describe your filters as **data** and the bar renders the same structure +
36
+ behaviour everywhere — only the theme changes. Field kinds: `select`, `text`, `number`,
37
+ `dateRange`, `typeahead` (search-as-you-type), `boolean`.
38
+
39
+ Every user-facing string is **pre-localized** and passed in (labels, option labels, placeholders,
40
+ errors) — the package never calls FM/i18n for content, touches a router, or reads a store.
41
+
42
+ ```tsx
43
+ import { Filters, useFilterDraft, type FilterField, type FilterValues } from '@dloizides/ui-tables';
44
+
45
+ const fields: FilterField[] = [
46
+ { key: 'q', kind: 'text', label: FM('cases.q'), grow: true, placeholder: FM('cases.qHint') },
47
+ { key: 'status', kind: 'select', label: FM('cases.status'),
48
+ options: [{ label: FM('common.any'), value: '' }, { label: FM('status.open'), value: 'open' }] },
49
+ { key: 'dates', kind: 'dateRange', label: FM('cases.valueDate') },
50
+ { key: 'country', kind: 'typeahead', label: FM('leaders.country'), options: countryOptions, minChars: 1 },
51
+ { key: 'active', kind: 'boolean', label: FM('cases.activeOnly') },
52
+ ];
53
+ ```
54
+
55
+ **Live model** (agora / zygos) — each edit applies immediately, no Apply button:
56
+
57
+ ```tsx
58
+ const [values, setValues] = useState<FilterValues>(EMPTY);
59
+ <Filters fields={fields} values={values} onChange={setValues} resultsCount={total} resultsLabel={FM('cases.results')} />
60
+ ```
61
+
62
+ **Draft / apply model** (aml / kefi audit) — edits accumulate in a draft; Apply (or Enter in a
63
+ field) commits it, and page resets to 1 via your `onApply`. `useFilterDraft` is the state engine:
64
+
65
+ ```tsx
66
+ const draft = useFilterDraft({ initial: EMPTY, onApply: () => setPage(1) });
67
+ <Filters
68
+ fields={fields}
69
+ values={draft.draft}
70
+ onChange={draft.setDraft}
71
+ onApply={draft.apply} // presence of onApply → shows the Apply button + Enter-to-commit
72
+ applyDisabled={datesInvalid} // aml's validity gate
73
+ onClear={draft.reset} // presence of onClear → shows Clear/Reset
74
+ actions={<ExportButtons query={draft.committed} />} // custom actions (Export CSV/PDF, bulk bar)
75
+ resultsCount={total}
76
+ resultsLabel={total === 1 ? FM('cases.resultOne') : FM('cases.resultMany')} // caller singularises
77
+ />
78
+ ```
79
+
80
+ **Injecting `ModalDropdown`** — the built-in `select` is a dependency-free in-tree dropdown. To
81
+ use `@dloizides/ui-layout`'s responsive `ModalDropdown` (modal on mobile/native) instead, pass
82
+ `renderSelect`:
83
+
84
+ ```tsx
85
+ <Filters
86
+ fields={fields}
87
+ values={values}
88
+ onChange={setValues}
89
+ renderSelect={({ field, value, onChange, testID }) => (
90
+ <ModalDropdown testID={testID} accessibilityLabel={field.label} accessibilityHint={field.label}
91
+ value={value} options={field.options} onChange={onChange} />
92
+ )}
93
+ />
94
+ ```
95
+
31
96
  #### Expandable rows (optional)
32
97
 
33
98
  For surfaces that open a full-width detail panel under a row (e.g. an audit log's
@@ -57,6 +122,76 @@ with the exported `rowDetailTestID(tableTestID, key)` (rows: `rowTestID(tableTes
57
122
  exposed to assistive tech as a labelled region (provide the `uiTables.rowDetail` key), and the row
58
123
  reports `aria-expanded`. Omit both props and nothing about the table changes.
59
124
 
125
+ #### Bulk-select (optional)
126
+
127
+ Pass `onSelectionChange` to add a checkbox gutter (header + every row). **Selection is
128
+ controlled by you**, exactly like `expandedRowKeys`: the table keeps no internal selection
129
+ state. The header checkbox is tri-state and reports `aria-checked="mixed"` when only part of
130
+ the page is ticked.
131
+
132
+ ```tsx
133
+ const [selected, setSelected] = useState<readonly string[]>([]);
134
+
135
+ <DataTable
136
+ columns={columns}
137
+ rows={rows}
138
+ keyExtractor={(r) => r.id} // the SAME key is matched against selectedRowKeys
139
+ selectedRowKeys={selected}
140
+ onSelectionChange={setSelected}
141
+ testID="grid"
142
+ />
143
+ ```
144
+
145
+ The header only ever adds or removes **this page's** keys — any off-page keys you hold are
146
+ preserved, because the table cannot see the rows they belong to. Test ids:
147
+ `rowSelectTestID(tableTestID, key)` and `selectAllTestID(tableTestID)`.
148
+
149
+ #### Select all matching the filter — a flag, not ids (optional)
150
+
151
+ This table is **server-paged and deliberately not virtualized** (see the ZY-02 grid spike:
152
+ render cost is linear at ~2–3 ms and ~16 DOM nodes per row, so a huge page is
153
+ indistinguishable from an outage). "Select all 3,023 matching" therefore **cannot** and
154
+ **must not** be an id list — the other pages were never fetched.
155
+
156
+ Add `matchingCount` (the server's total) + `onSelectAllMatchingChange` and, once the whole
157
+ page is ticked and more rows match, a banner offers the flag:
158
+
159
+ ```tsx
160
+ <DataTable
161
+ /* …selection props… */
162
+ matchingCount={total} // same number your Pager shows
163
+ allMatchingSelected={allMatching} // controlled FLAG
164
+ onSelectAllMatchingChange={setAllMatching} // emits `true` / `false` — never ids
165
+ />
166
+ ```
167
+
168
+ Resolve the flag **server-side against the same filter your list endpoint took**. That is a
169
+ better design anyway: the work survives the operator closing the tab. While the flag is set
170
+ every row reads as selected with an empty `selectedRowKeys`; toggling any single row drops
171
+ the flag (the operator is no longer acting on *the filter*).
172
+
173
+ #### Keyboard navigation (optional)
174
+
175
+ `keyboardNavigation` turns the table into a real ARIA grid using the **roving tabindex**
176
+ pattern — exactly one row is tabbable, so Tab crosses the grid in one hop instead of 100.
177
+
178
+ | Key | Action |
179
+ |---|---|
180
+ | ↑ / ↓ | Move the focused row (clamped — never wraps) |
181
+ | Home / End | First / last row on the page |
182
+ | Space | Toggle selection (when selectable) |
183
+ | Enter | Activate the row, via the existing `onRowPress` |
184
+
185
+ ```tsx
186
+ <DataTable columns={columns} rows={rows} keyExtractor={(r) => r.id} keyboardNavigation onRowPress={open} />
187
+ ```
188
+
189
+ **Off by default**, because adding `tabIndex` to rows changes a page's tab order. Web-only in
190
+ effect (focus movement and key events are DOM concerns); inert on native. Keys the table does
191
+ not handle are never `preventDefault`ed, so Tab and browser shortcuts keep working. When the
192
+ page changes underneath it, the tab stop re-homes onto the new first row rather than
193
+ disappearing.
194
+
60
195
  #### Pixel-perfect overrides (optional)
61
196
 
62
197
  **The defaults are opinionated but never mandatory.** When a surface must match an existing