@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 +163 -0
- package/CHANGELOG.md +74 -0
- package/README.md +136 -1
- package/dist/index.d.mts +388 -8
- package/dist/index.d.ts +388 -8
- package/dist/index.js +1567 -218
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1542 -207
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -2
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
|
-
| `
|
|
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
|