@dloizides/ui-tables 1.19.1 → 1.20.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 CHANGED
@@ -1,497 +1,516 @@
1
- # Changelog
2
-
3
- ## Unreleased
4
-
5
- **The `Filters` / `FilterBar` actions cluster wraps (TABLES-MOBILE-1 "Filter bar and pager overflow at 360").**
6
-
7
- Visual QA of aml-v2 `/app/leaders` at 360 measured the actions row (Reset, Export CSV/PDF, Apply)
8
- at 431px inside a 255px bar: a nowrap row is one unbreakable flex item, so Apply rendered at x=373,
9
- off-screen. `filtersActions` now has `flexWrap: 'wrap'`, `flexShrink: 1` and `maxWidth: '100%'`,
10
- so the cluster fits its line and its buttons break onto further lines. Desktop is unchanged: where
11
- the row fits, nothing wraps. The 44px Apply / pager hit boxes shipped in 1.19.0.
12
-
13
- ## 1.19.0
14
-
15
- **Every pressable renders a 44x44 hit box (SHOWCASE-1 "Publish the UI showcase at ui.dloizides.com").**
16
-
17
- Live QA on ui.dloizides.com/tables at 360x640 measured switches at 40x20, page-size buttons at
18
- 32-39x30 and pager buttons 31px tall. `hitSlop` is inert on react-native-web, so the rendered box
19
- is the target. Pager buttons, page-size pills, the dropdown trigger and its options, filter action
20
- buttons, the select checkbox (gutter now 44px wide) and the select-all banner action now carry
21
- `minHeight`/`minWidth` of `MIN_TARGET_PX` (44). The filter `Switch` keeps its 40x20 track inside a
22
- 44x44 `Pressable` (`-switch-hit` test id); the inner Switch keeps focus and the switch role.
23
- The inert `hitSlop` props were removed.
24
-
25
- ## 1.18.0
26
-
27
- **`DataTable` rows now fade in on load — the Ant-design-like list entrance — via `@dloizides/ui-motion`.**
28
-
29
- When a `DataTable` mounts its rows (first load, and whenever the row set changes — sort / filter /
30
- page), each row now fades in with a small upward translate, staggered across the first few rows. It
31
- is a subtle polish layer, gated hard so it never becomes jank on a large page, and **entirely
32
- opt-outable** — omit nothing and the table behaves exactly as before minus the fade.
33
-
34
- ### What changed
35
-
36
- | Area | Detail |
37
- |---|---|
38
- | **New optional prop** | `animateRows?: boolean` (default **`true`**). Each row (and its expanded detail panel, if any) is wrapped in `@dloizides/ui-motion`'s `<FadeIn>`, keyed by the row key. |
39
- | **Capped stagger** | Only the first `ROW_ENTRANCE_STAGGER_CAP` (10) rows stagger, `ROW_ENTRANCE_STAGGER_STEP_MS` (30 ms) apart; every row past the cap shares the capped delay. A 100- or 5,000-row page settles in a fixed ~300 ms, **never** row-by-row. |
40
- | **Reduced-motion** | Honoured: rows render instantly, with **no wrapper node and no delay** (`FadeIn` gates too, but the wrapper is skipped entirely so the reduced-motion DOM is identical to the un-animated table). |
41
- | **No re-fade on re-render** | Each row's `<FadeIn>` is keyed by its row key, so React keeps its identity across unrelated re-renders (hover, a re-fetch that resolves to the SAME keys) — the entrance plays once per key, not on every render. A genuine row-set change (new keys) re-fades, as intended. |
42
- | **New test id** | `rowFadeTestID(tableTestID, key)` → `${tableTestID}-fade-${key}` (present only while animating), exported alongside the other row test-id helpers. |
43
-
44
- ### Backward compatibility
45
-
46
- - **MINOR, additive.** The public API gains one optional prop and one test-id helper; nothing is
47
- renamed or removed.
48
- - All existing behaviour is preserved: zebra, sticky header, mobile card-stack, row/per-cell/head/
49
- detail-panel/select-checkbox test ids, `onRowPress`, bulk-select, keyboard navigation, the pager,
50
- and the refetch-does-not-blank-the-grid guard.
51
- - Pass `animateRows={false}` (or run under `prefers-reduced-motion`) and rows render with no
52
- wrapper node — DOM identical to before this release.
53
- - New peer of the kit: `@dloizides/ui-motion` (`^1.0.1`) is added as a dependency.
54
-
55
- ## 1.16.0
56
-
57
- **The responsive card-stack now reads as a proper mobile layout — and keeps every E2E hook.**
58
-
59
- `DataTable` has always collapsed to a label:value card-stack below a breakpoint (`stackBreakpoint`),
60
- but on a phone the multi-column tables it powers (e.g. the organizer Passes table) were still hard
61
- to read, and the card-stack silently dropped test hooks a wide-viewport E2E suite relies on. This
62
- release makes the card-stack the readable, self-explanatory mobile layout it was meant to be —
63
- **with no change to the desktop grid and no broken selectors.**
64
-
65
- ### What changed
66
-
67
- | Area | Before | Now |
68
- |---|---|---|
69
- | **Default breakpoint** | `640` | `768` — the kit-wide narrow-viewport threshold, aligned with `@dloizides/ui-layout`'s `MENU_BREAKPOINT` (already the collapse point for the nav menu and tabs). `CARD_STACK_BREAKPOINT` is re-exported at the new value. |
70
- | **Card line layout** | label LEFT, value RIGHT on one `space-between` row (cramped for long values / action buttons) | each column's header sits **ABOVE** its value, both left-aligned, so the value gets the full card width |
71
- | **Per-cell test id `${row}-${colKey}`** | resolved **only** on the desktop grid | resolves in **BOTH** layouts (the card line carries the same id the desktop cell does) |
72
- | **Head test id `ui-data-table-head`** | **absent** in card-stack mode | resolves in **BOTH** layouts via a hidden, a11y-inert carrier (`display: none`, `aria-hidden`) — E2E selectors survive at every width |
73
-
74
- ### Backward compatibility
75
-
76
- - **The desktop grid is byte-for-byte unchanged.** Opt out of the card-stack entirely, at every
77
- width, with `stackBreakpoint={0}` (unchanged).
78
- - A column's `render` node (badge, link, **action button**) renders identically in a card cell.
79
- - Row / per-cell / head / detail-panel / select-checkbox test ids are all preserved; the only
80
- net-new guarantee is that per-cell and head ids now ALSO resolve in the card-stack.
81
- - The one observable difference for an existing consumer is cosmetic: tables between 640px and
82
- 768px wide now show the card-stack (they showed the cramped desktop row before), and cards read
83
- vertically rather than as a `space-between` row. Both are strict readability improvements — which
84
- is what keeps this a MINOR bump.
85
-
86
- All 272 tests pass (6 added for the both-layouts test-hook contract + the vertical card layout).
87
-
88
- ## 1.15.0
89
-
90
- **A re-fetch no longer blanks the grid — the server-paged paging defect.**
91
-
92
- `DataTable` returned its full-bleed loading state whenever `loading` was true, unconditionally.
93
- On a server-paged grid that is not a cosmetic flicker, it is the paging bug: clicking **Next**
94
- replaced the table with "Loading…", so the grid visibly EMPTIED and only refilled once the next
95
- page arrived. To anyone watching — and to any assertion that samples the rows after the click —
96
- the grid appeared to page to nothing. The same applied to re-filtering and to any `reload()`.
97
-
98
- Evidence this was real and not theoretical: against the live AML v2 cases console, the API
99
- returned a correct, non-overlapping page at `skip=50`, yet the UI rendered **zero** rows after
100
- Next. The rows were being discarded by this component, not by the query.
101
-
102
- ### The rule now
103
-
104
- The state view is reserved for when there is genuinely nothing to show:
105
-
106
- | `loading` | `rows.length` | Renders |
107
- |---|---|---|
108
- | true | 0 | loading state (first load) |
109
- | false | 0 | empty state |
110
- | true | > 0 | **the existing rows** (stale for a moment), `aria-busy="true"` |
111
- | false | > 0 | the rows |
112
-
113
- Rows that already exist stay on screen and swap when the new page resolves. Because the content
114
- no longer vanishes, the in-flight fetch is announced explicitly via `aria-busy` on the table
115
- container rather than being implied by the table's destruction.
116
-
117
- **Behaviour is unchanged for every first load and every empty result**, which is what keeps this a
118
- MINOR bump. The only consumers that see a difference are those that were already passing `loading`
119
- alongside non-empty `rows` — i.e. exactly the ones that were silently blanking.
120
-
121
- All 266 pre-existing tests pass unmodified; 3 added for the retained-rows / busy / swap contract.
122
-
123
- ## 1.14.0
124
-
125
- **Campaign F2 — the private filter fields are now public, in `@dloizides/ui-forms`.**
126
-
127
- This package contained a complete, themed, a11y-wired set of form controls inside its `Filters`
128
- bar and exported NONE of them. Six portals could see them working and none could import them, so
129
- the fleet reimplemented them: **6 select implementations, 5 date fields, 2 typeaheads**. Same
130
- shape as `MultiTenancy.EntityFrameworkCore` shipping no EF Core. They now live in
131
- `@dloizides/ui-forms` 1.8.0 as `SelectControl` / `TypeaheadControl` / `DateRangeControl` /
132
- `AnchoredMenu` / `controlStyles`, and this package consumes them.
133
-
134
- **No behaviour changed. All 258 pre-existing tests pass UNMODIFIED** — including
135
- `Filters.test.tsx` (which drives every field kind through the bar), `selectAccessibleName.test.tsx`
136
- (the i18n path) and `suggest.test.ts` (now running against the moved implementation). That is the
137
- proof the move preserved behaviour rather than merely relocating it.
138
-
139
- ### What moved, and what deliberately did not
140
-
141
- The controls moved; the **schema** stayed. Each field was bound to this bar's `FilterField` types
142
- (`field: SelectFilterField`, `barTestID`, `fieldTestID`), so moving them verbatim would have
143
- dragged `FilterField`, `FilterFieldKind`, `FilterValues` and `FIELD_MIN_WIDTH` into `ui-forms` —
144
- i.e. `ui-forms` would have come to own "what a filter bar's field schema is". Wrong direction.
145
- The field files are now thin ADAPTERS mapping schema → plain props.
146
-
147
- `TextField` and `BooleanField` stayed. `ui-forms` already ships two text inputs (`ThemedTextInput`,
148
- `FormField`) and a switch row (`FormSwitch`); promoting a third of each would ADD duplicates to the
149
- package this campaign is de-duplicating. Converging onto the existing ones is right but VISIBLE
150
- (focus ring, hover border, `surfaceElevated` background, different switch-row metrics), so it
151
- belongs in the visual-QA-gated wave. Both now use the shared `controlStyles` boxes, so no metric
152
- is forked in the meantime.
153
-
154
- ### `FieldShell` is deleted
155
-
156
- The private label-wrapper fork existed only because `Field` hard-coded the 13/600 `field` label
157
- voice. `Field` 1.7.0 named both contract voices, so the bar now asks for `labelVariant="control"`
158
- — the 11/700/uppercase metrics `FieldShell` carried, verbatim. This ends the label-metric split
159
- between `Field` and `FieldShell` that caused several defects this campaign.
160
-
161
- The swap replaces the label implementation under six live portals, so it is guarded by a dedicated
162
- test (`fieldShellRetirement.test.tsx`) asserting the voice, the absence of `Field`'s 16px form
163
- rhythm, the per-kind reflow rules and the caller-override precedence. Removing `labelVariant`
164
- fails two of its five assertions — verified, not assumed.
165
-
166
- ### i18n manifests are untouched
167
-
168
- `FILTERS_I18N` and `TABLE_I18N` are unchanged, and every portal guard that binds to them keeps
169
- working. `ui-forms` never calls `t`, so the one field that resolved an i18n key —
170
- `SelectField`'s `FILTERS_I18N.selectTriggerLabel` accessible name — composes that string HERE, in
171
- the adapter, and passes the finished value down as `accessibilityLabel`. The i18n stayed with the
172
- package that owns the keys.
173
-
174
- ### Notes
175
-
176
- - New peer dependency: `@dloizides/ui-forms >= 1.8.0`, plus `@dloizides/ui-buttons >= 1.4.0`
177
- inherited through it (`ui-forms` bundles `FormActions`). All five portals consuming `ui-tables`
178
- already declare `ui-buttons ^1.4.0`, so this is a declaration of existing reality, not a new
179
- requirement.
180
- - `FilterOption` and `DateRangeValue` are now ALIASES of `ui-forms`' `ControlOption` /
181
- `DateRangeValue`. Public names unchanged; one definition instead of two structurally-identical
182
- twins free to drift.
183
- - `DEFAULT_TYPEAHEAD_MIN_CHARS` / `DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS` and `suggestOptions` /
184
- `isUnmatched` are re-exported from `ui-forms`. Public API unchanged.
185
- - Inherits the `AnchoredMenu` WCAG fix from `ui-forms` 1.8.0: the selected option now carries
186
- `aria-selected`. `accessibilityState` is native-only and react-native-web ignores it, so on web
187
- the current option had been conveyed by colour and font-weight alone (WCAG 1.4.1).
188
- - `AnchoredMenu` remains one of three near-identical anchored-menu implementations, with
189
- `ui-layout`'s `InlineMenu` and this package's `SizeDropdown`. Collapsing them was out of scope.
190
- The move makes it EASIER: two of the three now sit in packages that may depend on `ui-forms`, so
191
- a future collapse has an obvious home rather than needing a new shared package first.
192
-
193
- ## 1.13.0
194
-
195
- De-fork wave W1.1: pagination logic promoted from the byte-identical `PaginatedList`
196
- twins in erevna-web and katalogos-web.
197
-
198
- ### Added
199
-
200
- - `usePagedRows(rows, { pageSize })` — client-side pagination state for an already
201
- in-memory array. Returns `pageRows`, `currentPage`, `totalPages`, `setPage`,
202
- `hasPages`, `pageSize`. No new translation keys; no action required.
203
-
204
- Promoted as a **hook, not a component**, deliberately: the app-side `PaginatedList`
205
- hard-bound a `FlatList` plus app-specific empty and loading states. Only the paging
206
- maths is genuinely shared, so only that moved — callers keep their own list renderer.
207
- For server-side paging keep using `DataTable`'s pager.
208
-
209
- ### Fixed (behaviour differs from the app-side original)
210
-
211
- - The original only clamped the page index when `totalPages > 0`, so emptying the list
212
- left a stale non-zero page behind and the next non-empty render started on the wrong
213
- page. `usePagedRows` clamps to 0 in that case.
214
- - A `pageSize` of 0 divided by zero (`Math.ceil(n / 0)` → `Infinity` pages). Now floored
215
- to 1.
216
- - `setPage` clamps out-of-range input; the original trusted the caller.
217
-
218
- ## 1.12.0
219
-
220
- Accessibility fix: controls that announced a **bare number** now say what they are. Confirmed in
221
- a real browser, the rows-per-page trigger rendered `aria-label="50"` — a screen-reader user heard
222
- the value and nothing about the control. Fixed across the whole package, plus two more instances
223
- of the same defect class found while auditing.
224
-
225
- ### ⚠️ ACTION REQUIRED — add three translation keys
226
-
227
- The new accessible names are user-facing strings, so they come from the host app's locale files.
228
- **Every consuming app must add these three keys:**
229
-
230
- | Key | Params | Suggested English |
231
- |---|---|---|
232
- | `uiTables.pager.rowsTriggerLabel` | `{{p1}}` = current page size | `Rows per page, currently {{p1}}` |
233
- | `uiTables.pager.rowsOptionLabel` | `{{p1}}` = that option's size | `Show {{p1}} rows per page` |
234
- | `uiTables.filters.selectTriggerLabel` | `{{p1}}` = field label, `{{p2}}` = selection | `{{p1}}: {{p2}}` |
235
-
236
- They are exported as `TABLE_I18N.pagerRowsTriggerLabel`, `TABLE_I18N.pagerRowsOptionLabel` and
237
- `FILTERS_I18N.selectTriggerLabel`, so an app that derives its required-key list from those maps
238
- (as zygos' guard test does) picks them up automatically.
239
-
240
- **Upgrading without adding them is safe.** Unlike the usual kit contract — where an undefined key
241
- renders as its literal dotted name, the failure that put 44 raw keys on screen in zygos — a
242
- newly-introduced ACCESSIBLE-NAME key degrades to the value it replaced (the bare number, the field
243
- label). An aria-label is invisible to sighted reviewers, so a raw key there would ship silently and
244
- hurt only screen-reader users. Until you add the keys you simply keep the old, worse names.
245
-
246
- ### Fixed
247
-
248
- - **`Pager` rows-per-page trigger** (`dropdown` variant) — was `aria-label="50"`, now
249
- "Rows per page, currently 50".
250
- - **`Pager` rows-per-page options** (`dropdown` variant) — was `aria-label="100"`, now
251
- "Show 100 rows per page".
252
- - **`Pager` rows-per-page pills** (the **DEFAULT** `pills` variant) — carried the identical
253
- bare-number defect and was NOT in the original report, so it affected more consumers than the
254
- dropdown did. Same fix, same key.
255
- - **`Filters` select trigger** — `accessibilityLabel` replaces the trigger's visible text for a
256
- screen reader, so labelling it `field.label` alone silently hid the current selection: sighted
257
- users saw "Closed", screen-reader users heard only "Status". Now "Status: Closed".
258
- - **`StatCard`** — its two translation keys were string literals inlined in the component rather
259
- than members of an exported map, so an app deriving its required-key list from `TABLE_I18N`
260
- could not see them and would render them raw. Now exported as `TABLE_I18N.statCardLabel` /
261
- `TABLE_I18N.statHint`. **The key strings are unchanged** (`analytics.statCardLabel`,
262
- `analytics.statHint`) — renaming them would have broken every app that already defines them.
263
-
264
- ### Added
265
-
266
- - **`accessibleName(translated, key, fallback)`** — the internal degradation guard described
267
- above. Not exported; the kit's fallback-free i18n contract is unchanged for visible copy.
268
-
269
- Additive and backward compatible for consumers — no public prop changed, so a MINOR bump.
270
- `SizeDropdown`'s props gained `triggerLabel` / `getOptionLabel`, but that component is internal
271
- (never exported from the package root).
272
-
273
- ## 1.11.0
274
-
275
- Additive: a **declarative `Filters` bar** + **Pager** enhancements. Every change is additive and
276
- backward compatible — existing `FilterBar` / `Pager` / `DataTable` consumers (aml-v2, agora,
277
- zygos, kefi, erevna, katalogos) are untouched and every new prop is optional, so a MINOR bump.
278
- No app is migrated by this release; adoption is a later wave (see `ADOPTION.md`).
279
-
280
- - **`Filters`** — the declarative, configurable filter bar built ON the existing `FilterBar`
281
- shell (reusing its live results count + WCAG live region + actions slot). A caller passes a
282
- `fields` schema — the SUPERSET harvested from every portal's hand-rolled filters — of kinds
283
- `select` / `text` / `number` / `dateRange` / `typeahead` / `boolean`, plus a value map and
284
- `onChange`. Two value models: **LIVE** (edits apply immediately — agora, zygos) and
285
- **DRAFT/APPLY** (edits accumulate in a draft, an Apply button + Enter-in-a-field commit it —
286
- aml, kefi audit), the latter driven by the new `useFilterDraft` hook. Customisation is style
287
- (theme) + slots only: every label/option/placeholder/error is a pre-localized string; no
288
- FM/router/store. Apps can inject `@dloizides/ui-layout`'s `ModalDropdown` for the `select`
289
- field via `renderSelect` (the in-tree dropdown is the dependency-free default).
290
- - **`useFilterDraft`** — the draft-vs-applied state engine (draft + committed + `apply` / `reset`
291
- / `setField` / `dirty`), with `onApply` / `onReset` callbacks the caller wires to `setPage(1)`
292
- (the universal reset-to-page-1-on-narrowing invariant, kept free of pagination coupling).
293
- - **`suggestOptions` / `isUnmatched`** — the ranked substring matcher behind the `typeahead`
294
- field (generalized from aml's `suggestCountries`), exported for reuse.
295
- - **`Pager`** — three additive props reconciling the variants across apps: `showFirstLast`
296
- (First/Last jump buttons, disabled at bounds — erevna's `PaginationControls`),
297
- `unitLabelSingular` (renders `1 result` when `total === 1` — the singularisation apps did in
298
- the FilterBar noun), and `responsive` + `stackBreakpoint` (collapse to a compact
299
- Prev/Next-only nav below the breakpoint — the mobile fallback, mirroring the DataTable
300
- card-stack). New pager test ids `ui-pager-first` / `ui-pager-last`.
301
-
302
- ## 1.10.0
303
-
304
- Additive: **bulk-select** + **keyboard navigation** on `DataTable` (ZY-08). Every new prop is
305
- optional and CONTROLLED — omit them all and the table renders exactly as it did on 1.9.2, so
306
- erevna / katalogos / kefi / agora are unaffected. Hence a MINOR bump.
307
-
308
- - **Bulk-select** — `selectedRowKeys` + `onSelectionChange` add a checkbox gutter to the
309
- header and every row. Controlled, following the `expandedRowKeys` precedent exactly: the
310
- table keeps no internal selection state, and `onSelectionChange` is the enabler (as
311
- `renderRowDetail` is for expansion). The header checkbox is genuinely tri-state
312
- (`accessibilityState.checked: 'mixed'` + `aria-checked="mixed"`), and only ever adds or
313
- removes keys belonging to the CURRENT page — off-page keys the caller holds are preserved,
314
- because the table must not drop a selection it cannot see.
315
- - **Select all matching the filter — a FLAG, never an id list.** `matchingCount` +
316
- `onSelectAllMatchingChange` add a banner once the page is fully selected and more rows
317
- match. It emits `true`/`false`; the table never enumerates the matching rows (they are on
318
- pages it never fetched, and the ZY-02 spike measured ~2–3 ms and ~16 DOM nodes per row, so
319
- materialising thousands of them is indistinguishable from an outage). Toggling a single row
320
- under the flag drops it — the operator is no longer acting on *the filter*.
321
- - **Keyboard navigation** — `keyboardNavigation` (default **off**, because giving rows a
322
- `tabIndex` changes a page's tab order) implements the ARIA grid **roving tabindex**: one tab
323
- stop for the whole grid, ↑/↓ to move (clamped, never wrapping), Home/End, Space to toggle
324
- selection, Enter to activate via the existing `onRowPress`. Keys the table does not handle
325
- are never `preventDefault`ed, so Tab and browser shortcuts keep working. When the page
326
- changes underneath it the tab stop re-homes onto the new first row rather than vanishing —
327
- without that guard the grid would become keyboard-unreachable the moment an operator paged.
328
- Web-only in effect (focus movement and key events are DOM concerns); inert on native, via
329
- the same deliberate split as the `position: 'sticky'` header.
330
- - **a11y** — `role="grid"` / `row` / `columnheader` / `cell` when navigable; `aria-selected`
331
- on rows when selectable; row checkboxes are labelled with the ROW's name, so they announce
332
- as "Instruction ABC, checkbox" rather than an anonymous "checkbox" repeated down the page.
333
- - **🔴 A selectable row's checkbox sits OUTSIDE its pressable area** — a sibling, never a
334
- descendant. A checkbox nested inside an interactive row's `Pressable` is precisely the shape
335
- the 1.9.2 fix identified as broken: the row's pointer responders CAPTURE the gesture and
336
- cancel the child's press, so the checkbox would pass a synthetic `element.click()` test and
337
- silently do nothing under a real mouse, touch or Playwright click. A selectable row is now a
338
- plain `<View>` frame holding the checkbox and a separate pressable content area.
339
- - New exports: `rowSelectTestID(tableTestID, key)`, `selectAllTestID(tableTestID)`, the
340
- `uiTables.select.*` keys on `TABLE_I18N`, and the `selectCell` / `selectBanner`
341
- `styleOverrides` slots. No existing export changed.
342
- - Internals split for clarity as the row grew three shapes: `DataTableRow`, `TableRow`,
343
- `TableHeader`, `RowCells`, plus pure `selection.ts` / `rowNav.ts` rule modules and the
344
- `useTableSelection` / `useRovingFocus` hooks. No behaviour change for existing consumers
345
- (the full 1.9.2 suite passes untouched).
346
-
347
- ## 1.9.2
348
-
349
- - **🔴 In-cell action buttons (Edit/Delete/Stop) now fire on a real pointer gesture, not just a bare
350
- synthetic click.** A NON-interactive row (no `onRowPress`) was still rendered as a `<Pressable>`.
351
- On react-native-web a `Pressable` installs pointer responders (pointerdown/up/cancel) on the row
352
- container that CAPTURE a real mouse/touch gesture and cancel the press of any interactive child in
353
- a cell — so a Delete/Stop/Edit button inside a static row looked clickable, fired on a bare
354
- `element.click()`, but silently did nothing on an actual click/tap (and on a Playwright `.click()`,
355
- which is why the AML v2 settings webhook-delete + stop-monitoring E2Es were red). A non-pressable
356
- row is now a plain `<View>` (new `RowContainer`), so its cell controls receive the full gesture.
357
- Interactive tables (`onRowPress`) are unchanged. Same class as the earlier `disabled`→
358
- `pointer-events:none` fix; this closes the remaining pointer-responder-capture path.
359
-
360
- ## 1.9.0
361
-
362
- - **`Pager` dropdown-variant rows menu now escapes ancestor stacking contexts (web).** The
363
- `rowsVariant="dropdown"` `SizeDropdown` menu opened but painted UNDER the results table on wide
364
- web: react-native-web renders every `View` as `position: relative; z-index: 0`, so the in-tree
365
- `position: absolute; zIndex: 1000` menu was trapped inside its anchor's stacking context and lost
366
- to later-painting siblings (the table / cards below).
367
- - On **web** the open menu now renders in a PORTAL to `document.body` with `position: fixed` at the
368
- trigger's measured viewport rect (right-aligned, recomputed on scroll/resize) and a high `zIndex`
369
- — clipped by nothing, above everything. Mirrors `@dloizides/ui-layout`'s InlineMenu fix.
370
- - On **native** the menu is unchanged (in-tree `position: absolute` + `elevation`). All web-only code
371
- (portal, `document`/`window` listeners, `position: fixed`) is guarded behind `Platform.OS === 'web'`.
372
- - Outside-click dismissal now consults BOTH the anchor and the portalled menu node.
373
- - `react-dom` is added as an **optional** peer dependency (only touched on web; every RN-web consumer
374
- already has it). No API change: the `rowsVariant="dropdown"` contract, all test ids, the compact v1
375
- look and a11y (role/aria/keyboard) are unchanged.
376
-
377
- ## 1.8.0
378
-
379
- - `Pager` gains an additive, **default-off** `rowsVariant?: 'pills' | 'dropdown'` prop.
380
- - `'pills'` (default) is unchanged — the RN-idiom row of pressable size pills. Every existing
381
- consumer (erevna / katalogos / kefi / coverage) renders byte-identically.
382
- - `'dropdown'` swaps the size pills for a compact `<select>`-like anchored dropdown matching
383
- the v1 console's "Rows" select: a bordered trigger (height-matched to the Prev/Next ghost
384
- buttons) showing the current size + a chevron, opening a popover of the `pageSizeOptions`
385
- that fires `onPageSizeChange` and closes on select / outside-click / Escape. The "Rows"
386
- caption is mixed-case (not uppercase) in this variant, matching v1's muted `.hint` label.
387
- - Self-contained: the anchored dropdown is implemented inside ui-tables (new `SizeDropdown`),
388
- reusing ui-layout's InlineMenu click-outside/Escape pattern WITHOUT taking a hard dependency
389
- on `@dloizides/ui-layout` — its ModalDropdown trigger has fixed chunky padding and no chevron,
390
- so it cannot match v1's compact select, and a low-level table primitive should not depend on
391
- a higher-level layout package. New option/trigger test ids: `${testID}-size-trigger`,
392
- `${testID}-size-menu`, and the existing `${testID}-size-${size}` per option.
393
-
394
- ## 1.7.0
395
-
396
- - **Accessibility (WCAG 2.1 AA) hardening — additive + backward-compatible.**
397
- - `FilterBar`: the results-count line is now a `role="status"` / `aria-live="polite"` live
398
- region, so a screen reader announces the new count when filters change the result set
399
- (WCAG 4.1.3).
400
- - `Pager`: the Prev/Next controls and the rows-per-page pills gain a vertical `hitSlop` so the
401
- touch target reaches ~44px WITHOUT changing the rendered size (adjacent pills never overlap).
402
-
403
- ## 1.6.0
404
-
405
- - `DataTable` gains a **web row-hover highlight** on clickable rows, matching the v1 console's
406
- `.ui-table tr.clickable:hover` rule. Only interactive rows (those with an `onRowPress`) tint
407
- on hover — static rows never light up. The tint is the theme's soft brand fill
408
- (`palette.primary['500']` at low alpha via the new `softBrandTint` helper), so it re-themes
409
- per tenant, falling back to a subtle surface tint when `primary` is not a plain `#rrggbb`.
410
- The hover tint wins over zebra/`rowTint` while hovered (mirroring v1's `:hover td { background }`).
411
- - **Native-safe + backward-compatible**: hover is driven by `Pressable`'s `onHoverIn`/`onHoverOut`,
412
- which are no-ops on iOS/Android, and the handlers are wired only for interactive tables — a
413
- non-interactive table renders byte-identically to before. Benefits every consumer
414
- (erevna/katalogos/kefi/aml-v2) with clickable rows.
415
-
416
- ## 1.5.0
417
-
418
- - `Pager` gains two additive, **default-off** props so a paged grid can read exactly like the
419
- v1 AML console's `.ui-pager__info` line:
420
- - `infoPrefix?: string` — an already-translated word prefixed to the count
421
- (e.g. `"Showing"` → `Showing 1–50 of 3,023 leadership terms`).
422
- - `boldNumbers?: boolean` — renders the three counts (from / to / total) in bold
423
- `colors.text`, matching v1's `.ui-pager__info b`.
424
- - **Backward-compatible**: with both props omitted the count line is byte-identical to before
425
- (the concatenated text is unchanged even with `boldNumbers` on — bold is styling only), so
426
- existing consumers (`/coverage`, aml-v2) are unaffected.
427
-
428
- ## Unreleased
429
-
430
- - **Pixel-perfect overrides** (additive, backward-compatible). The kit's defaults are
431
- opinionated but never mandatory — a consumer that must match an existing look can now
432
- do so without forking:
433
- - `DataTable` gains `styleOverrides?: DataTableStyleOverrides` (slots: `wrap`, `headRow`,
434
- `headCell`, `row`, `cell`, `numCell`, `state`, `stateText`, `rowDetail`, `card`,
435
- `cardLine`, `cardLabel`, `cardValue`).
436
- - `Pager` gains `styleOverrides?: PagerStyleOverrides` (slots: `pager`, `pagerInfo`,
437
- `pagerNav`, `pagerRowsLabel`, `sizeGroup`, `control`, `controlText`, `sizePill`,
438
- `sizePillText`).
439
- - `FilterBar` gains `styleOverrides?: FilterBarStyleOverrides` (slots: `filters`,
440
- `filtersSpacer`, `results`, `filtersActions`).
441
- - Each slot is merged **LAST** into its style array, so an override beats the base
442
- StyleSheet **and** the inline colour the component applies from `useUi().theme`
443
- (colours are never in the StyleSheet in this kit).
444
- - Documented: `stackBreakpoint={0}` disables the responsive card-stack (`width < 0` is
445
- never true), for surfaces that never had one.
446
- - Omit `styleOverrides` and every render is byte-identical to before (verified by test).
447
-
448
- - `DataTable` — **expandable rows** (additive, backward-compatible). Two new optional props:
449
- - `renderRowDetail?: (row: T) => React.ReactNode` — renders a full-width detail panel
450
- (spanning every column) directly beneath a row, between it and the next row. Works in
451
- the desktop grid *and* in the responsive card-stack.
452
- - `expandedRowKeys?: readonly string[]` — the `keyExtractor` keys of the rows currently
453
- expanded. Expansion is **controlled by the caller** (own the state, toggle from
454
- `onRowPress`); the table keeps no internal expand state and adds no chevron.
455
- - The panel gets a stable test id `${testID}-row-detail-${key}` (new helpers
456
- `rowDetailTestID(tableTestID, key)` / `rowTestID(tableTestID, key)`), is exposed to
457
- assistive tech as a labelled region (`accessibilityRole="summary"` +
458
- the new `uiTables.rowDetail` translation key), and the row it belongs to reports
459
- `aria-expanded` / `accessibilityState.expanded`.
460
- - Omit both props and the table renders exactly as before: no extra DOM node, no extra
461
- row props, no behaviour change for existing consumers.
462
- - Unblocks kefi-web's audit log (before/after JSON snapshot panel) adopting `DataTable`.
463
-
464
- ## 1.2.0
465
-
466
- - `Pager` — new optional `unitLabel?: string` prop. When supplied it appends an
467
- already-translated unit noun to the count line, e.g. `unitLabel="leadership terms"`
468
- renders `1–50 of 3,023 leadership terms` (v1 parity). Backward-compatible: when the
469
- prop is omitted (or empty) the count line stays the generic `from–to of N`,
470
- byte-identical to prior behaviour.
471
- - Test tooling — added `src/jest-dom.d.ts` so ts-jest picks up the
472
- `@testing-library/jest-dom` matcher types (`toBeDisabled`, …) when type-checking each
473
- test file (`jest.setup.ts` sits outside the `src/**` include). Fixes the `Pager` suite
474
- failing to compile under the isolated ts-jest type-check.
475
-
476
- ## 1.1.0
477
-
478
- - `DataTable` — promoted from the `/coverage` RN-web POC and hardened into the shared,
479
- tokenized grid (the `wwwroot/shared/GRID.md` contract):
480
- - per-row `testID` + `accessibilityLabel`/`accessibilityHint`, pressable rows (`onRowPress`);
481
- - all user-facing chrome routed through the UiProvider `t` (no literals) — falls back to
482
- caller-supplied `loadingLabel`/`emptyLabel`;
483
- - fixed the POC's double `col.render()` call in the desktop path (now rendered once per cell);
484
- - added the rest of the GRID.md contract: `FilterBar`, `Pager` (page-info + Prev/Next +
485
- rows-per-page), an optional `zebra` modifier, and a `stickyHeader`;
486
- - responsive label:value card-stack via `useWindowDimensions` below `stackBreakpoint`;
487
- - every colour from `@dloizides/design-tokens` via the `useUi()` theme — no hardcoded colours.
488
- - Component tests (`DataTable`, `FilterBar`, `Pager`) added.
489
-
490
- ## 1.0.0
491
-
492
- Initial release (Capability Wave C1, batch 3).
493
-
494
- - `StatCard` — extracted from the proven erevna ↔ katalogos duplication; shares the
495
- `@dloizides/ui-feedback` UI context (`useUi`).
496
- - `DataTable` / `StatGrid` intentionally NOT included yet — they exist only in kefi-web (n=1);
497
- they'll be added when a 2nd consumer appears.
1
+ # Changelog
2
+
3
+ ## 1.20.0
4
+
5
+ **The rows-per-page menu opens above an RN-web Modal (UI-ZINDEX-SCALE-1 "Shared overlay z-index scale").**
6
+
7
+ react-native-web mounts `Modal` in a body-level layer at zIndex 9999. On web the `SizeDropdown`
8
+ menu portals to the body, and at zIndex 1000 it painted under an open Modal, so clicks fell through
9
+ to the dialog. The menu now uses `Z_INDEX.popover` (10000, below toasts) and the sticky header uses
10
+ `Z_INDEX.sticky` (2, unchanged), both from `@dloizides/design-tokens` ^1.13.0, which is now a dependency.
11
+
12
+ ## 1.19.2
13
+
14
+ **The pager shrinks and wraps beside a title (TABLES-MOBILE-1 "Filter bar and pager overflow at 360").**
15
+
16
+ Visual QA of aml-v2 `/app/cases` at 360 measured the pager, placed beside the "Cases" title in a
17
+ wrapping row, at 328px inside a 255px slot: `flex-shrink: 0`, no width cap, so Next ran to x=373
18
+ and an `overflow: hidden` ancestor clipped it. `pager` and `pagerNav` now carry `flexShrink: 1`,
19
+ `minWidth: 0` and `maxWidth: '100%'`, so they fit their line and their existing `flexWrap` breaks
20
+ the count / Rows / Prev / Next onto further lines. Desktop is unchanged where the row fits.
21
+
22
+ ## 1.19.1
23
+
24
+ **The `Filters` / `FilterBar` actions cluster wraps (TABLES-MOBILE-1 "Filter bar and pager overflow at 360").**
25
+
26
+ Visual QA of aml-v2 `/app/leaders` at 360 measured the actions row (Reset, Export CSV/PDF, Apply)
27
+ at 431px inside a 255px bar: a nowrap row is one unbreakable flex item, so Apply rendered at x=373,
28
+ off-screen. `filtersActions` now has `flexWrap: 'wrap'`, `flexShrink: 1` and `maxWidth: '100%'`,
29
+ so the cluster fits its line and its buttons break onto further lines. Desktop is unchanged: where
30
+ the row fits, nothing wraps. The 44px Apply / pager hit boxes shipped in 1.19.0.
31
+
32
+ ## 1.19.0
33
+
34
+ **Every pressable renders a 44x44 hit box (SHOWCASE-1 "Publish the UI showcase at ui.dloizides.com").**
35
+
36
+ Live QA on ui.dloizides.com/tables at 360x640 measured switches at 40x20, page-size buttons at
37
+ 32-39x30 and pager buttons 31px tall. `hitSlop` is inert on react-native-web, so the rendered box
38
+ is the target. Pager buttons, page-size pills, the dropdown trigger and its options, filter action
39
+ buttons, the select checkbox (gutter now 44px wide) and the select-all banner action now carry
40
+ `minHeight`/`minWidth` of `MIN_TARGET_PX` (44). The filter `Switch` keeps its 40x20 track inside a
41
+ 44x44 `Pressable` (`-switch-hit` test id); the inner Switch keeps focus and the switch role.
42
+ The inert `hitSlop` props were removed.
43
+
44
+ ## 1.18.0
45
+
46
+ **`DataTable` rows now fade in on load — the Ant-design-like list entrance — via `@dloizides/ui-motion`.**
47
+
48
+ When a `DataTable` mounts its rows (first load, and whenever the row set changes — sort / filter /
49
+ page), each row now fades in with a small upward translate, staggered across the first few rows. It
50
+ is a subtle polish layer, gated hard so it never becomes jank on a large page, and **entirely
51
+ opt-outable** — omit nothing and the table behaves exactly as before minus the fade.
52
+
53
+ ### What changed
54
+
55
+ | Area | Detail |
56
+ |---|---|
57
+ | **New optional prop** | `animateRows?: boolean` (default **`true`**). Each row (and its expanded detail panel, if any) is wrapped in `@dloizides/ui-motion`'s `<FadeIn>`, keyed by the row key. |
58
+ | **Capped stagger** | Only the first `ROW_ENTRANCE_STAGGER_CAP` (10) rows stagger, `ROW_ENTRANCE_STAGGER_STEP_MS` (30 ms) apart; every row past the cap shares the capped delay. A 100- or 5,000-row page settles in a fixed ~300 ms, **never** row-by-row. |
59
+ | **Reduced-motion** | Honoured: rows render instantly, with **no wrapper node and no delay** (`FadeIn` gates too, but the wrapper is skipped entirely so the reduced-motion DOM is identical to the un-animated table). |
60
+ | **No re-fade on re-render** | Each row's `<FadeIn>` is keyed by its row key, so React keeps its identity across unrelated re-renders (hover, a re-fetch that resolves to the SAME keys) — the entrance plays once per key, not on every render. A genuine row-set change (new keys) re-fades, as intended. |
61
+ | **New test id** | `rowFadeTestID(tableTestID, key)` → `${tableTestID}-fade-${key}` (present only while animating), exported alongside the other row test-id helpers. |
62
+
63
+ ### Backward compatibility
64
+
65
+ - **MINOR, additive.** The public API gains one optional prop and one test-id helper; nothing is
66
+ renamed or removed.
67
+ - All existing behaviour is preserved: zebra, sticky header, mobile card-stack, row/per-cell/head/
68
+ detail-panel/select-checkbox test ids, `onRowPress`, bulk-select, keyboard navigation, the pager,
69
+ and the refetch-does-not-blank-the-grid guard.
70
+ - Pass `animateRows={false}` (or run under `prefers-reduced-motion`) and rows render with no
71
+ wrapper node — DOM identical to before this release.
72
+ - New peer of the kit: `@dloizides/ui-motion` (`^1.0.1`) is added as a dependency.
73
+
74
+ ## 1.16.0
75
+
76
+ **The responsive card-stack now reads as a proper mobile layout — and keeps every E2E hook.**
77
+
78
+ `DataTable` has always collapsed to a label:value card-stack below a breakpoint (`stackBreakpoint`),
79
+ but on a phone the multi-column tables it powers (e.g. the organizer Passes table) were still hard
80
+ to read, and the card-stack silently dropped test hooks a wide-viewport E2E suite relies on. This
81
+ release makes the card-stack the readable, self-explanatory mobile layout it was meant to be —
82
+ **with no change to the desktop grid and no broken selectors.**
83
+
84
+ ### What changed
85
+
86
+ | Area | Before | Now |
87
+ |---|---|---|
88
+ | **Default breakpoint** | `640` | `768` — the kit-wide narrow-viewport threshold, aligned with `@dloizides/ui-layout`'s `MENU_BREAKPOINT` (already the collapse point for the nav menu and tabs). `CARD_STACK_BREAKPOINT` is re-exported at the new value. |
89
+ | **Card line layout** | label LEFT, value RIGHT on one `space-between` row (cramped for long values / action buttons) | each column's header sits **ABOVE** its value, both left-aligned, so the value gets the full card width |
90
+ | **Per-cell test id `${row}-${colKey}`** | resolved **only** on the desktop grid | resolves in **BOTH** layouts (the card line carries the same id the desktop cell does) |
91
+ | **Head test id `ui-data-table-head`** | **absent** in card-stack mode | resolves in **BOTH** layouts via a hidden, a11y-inert carrier (`display: none`, `aria-hidden`) — E2E selectors survive at every width |
92
+
93
+ ### Backward compatibility
94
+
95
+ - **The desktop grid is byte-for-byte unchanged.** Opt out of the card-stack entirely, at every
96
+ width, with `stackBreakpoint={0}` (unchanged).
97
+ - A column's `render` node (badge, link, **action button**) renders identically in a card cell.
98
+ - Row / per-cell / head / detail-panel / select-checkbox test ids are all preserved; the only
99
+ net-new guarantee is that per-cell and head ids now ALSO resolve in the card-stack.
100
+ - The one observable difference for an existing consumer is cosmetic: tables between 640px and
101
+ 768px wide now show the card-stack (they showed the cramped desktop row before), and cards read
102
+ vertically rather than as a `space-between` row. Both are strict readability improvements — which
103
+ is what keeps this a MINOR bump.
104
+
105
+ All 272 tests pass (6 added for the both-layouts test-hook contract + the vertical card layout).
106
+
107
+ ## 1.15.0
108
+
109
+ **A re-fetch no longer blanks the grid — the server-paged paging defect.**
110
+
111
+ `DataTable` returned its full-bleed loading state whenever `loading` was true, unconditionally.
112
+ On a server-paged grid that is not a cosmetic flicker, it is the paging bug: clicking **Next**
113
+ replaced the table with "Loading…", so the grid visibly EMPTIED and only refilled once the next
114
+ page arrived. To anyone watching — and to any assertion that samples the rows after the click —
115
+ the grid appeared to page to nothing. The same applied to re-filtering and to any `reload()`.
116
+
117
+ Evidence this was real and not theoretical: against the live AML v2 cases console, the API
118
+ returned a correct, non-overlapping page at `skip=50`, yet the UI rendered **zero** rows after
119
+ Next. The rows were being discarded by this component, not by the query.
120
+
121
+ ### The rule now
122
+
123
+ The state view is reserved for when there is genuinely nothing to show:
124
+
125
+ | `loading` | `rows.length` | Renders |
126
+ |---|---|---|
127
+ | true | 0 | loading state (first load) |
128
+ | false | 0 | empty state |
129
+ | true | > 0 | **the existing rows** (stale for a moment), `aria-busy="true"` |
130
+ | false | > 0 | the rows |
131
+
132
+ Rows that already exist stay on screen and swap when the new page resolves. Because the content
133
+ no longer vanishes, the in-flight fetch is announced explicitly via `aria-busy` on the table
134
+ container rather than being implied by the table's destruction.
135
+
136
+ **Behaviour is unchanged for every first load and every empty result**, which is what keeps this a
137
+ MINOR bump. The only consumers that see a difference are those that were already passing `loading`
138
+ alongside non-empty `rows` — i.e. exactly the ones that were silently blanking.
139
+
140
+ All 266 pre-existing tests pass unmodified; 3 added for the retained-rows / busy / swap contract.
141
+
142
+ ## 1.14.0
143
+
144
+ **Campaign F2 — the private filter fields are now public, in `@dloizides/ui-forms`.**
145
+
146
+ This package contained a complete, themed, a11y-wired set of form controls inside its `Filters`
147
+ bar and exported NONE of them. Six portals could see them working and none could import them, so
148
+ the fleet reimplemented them: **6 select implementations, 5 date fields, 2 typeaheads**. Same
149
+ shape as `MultiTenancy.EntityFrameworkCore` shipping no EF Core. They now live in
150
+ `@dloizides/ui-forms` 1.8.0 as `SelectControl` / `TypeaheadControl` / `DateRangeControl` /
151
+ `AnchoredMenu` / `controlStyles`, and this package consumes them.
152
+
153
+ **No behaviour changed. All 258 pre-existing tests pass UNMODIFIED** — including
154
+ `Filters.test.tsx` (which drives every field kind through the bar), `selectAccessibleName.test.tsx`
155
+ (the i18n path) and `suggest.test.ts` (now running against the moved implementation). That is the
156
+ proof the move preserved behaviour rather than merely relocating it.
157
+
158
+ ### What moved, and what deliberately did not
159
+
160
+ The controls moved; the **schema** stayed. Each field was bound to this bar's `FilterField` types
161
+ (`field: SelectFilterField`, `barTestID`, `fieldTestID`), so moving them verbatim would have
162
+ dragged `FilterField`, `FilterFieldKind`, `FilterValues` and `FIELD_MIN_WIDTH` into `ui-forms` —
163
+ i.e. `ui-forms` would have come to own "what a filter bar's field schema is". Wrong direction.
164
+ The field files are now thin ADAPTERS mapping schema → plain props.
165
+
166
+ `TextField` and `BooleanField` stayed. `ui-forms` already ships two text inputs (`ThemedTextInput`,
167
+ `FormField`) and a switch row (`FormSwitch`); promoting a third of each would ADD duplicates to the
168
+ package this campaign is de-duplicating. Converging onto the existing ones is right but VISIBLE
169
+ (focus ring, hover border, `surfaceElevated` background, different switch-row metrics), so it
170
+ belongs in the visual-QA-gated wave. Both now use the shared `controlStyles` boxes, so no metric
171
+ is forked in the meantime.
172
+
173
+ ### `FieldShell` is deleted
174
+
175
+ The private label-wrapper fork existed only because `Field` hard-coded the 13/600 `field` label
176
+ voice. `Field` 1.7.0 named both contract voices, so the bar now asks for `labelVariant="control"`
177
+ — the 11/700/uppercase metrics `FieldShell` carried, verbatim. This ends the label-metric split
178
+ between `Field` and `FieldShell` that caused several defects this campaign.
179
+
180
+ The swap replaces the label implementation under six live portals, so it is guarded by a dedicated
181
+ test (`fieldShellRetirement.test.tsx`) asserting the voice, the absence of `Field`'s 16px form
182
+ rhythm, the per-kind reflow rules and the caller-override precedence. Removing `labelVariant`
183
+ fails two of its five assertions — verified, not assumed.
184
+
185
+ ### i18n manifests are untouched
186
+
187
+ `FILTERS_I18N` and `TABLE_I18N` are unchanged, and every portal guard that binds to them keeps
188
+ working. `ui-forms` never calls `t`, so the one field that resolved an i18n key —
189
+ `SelectField`'s `FILTERS_I18N.selectTriggerLabel` accessible name — composes that string HERE, in
190
+ the adapter, and passes the finished value down as `accessibilityLabel`. The i18n stayed with the
191
+ package that owns the keys.
192
+
193
+ ### Notes
194
+
195
+ - New peer dependency: `@dloizides/ui-forms >= 1.8.0`, plus `@dloizides/ui-buttons >= 1.4.0`
196
+ inherited through it (`ui-forms` bundles `FormActions`). All five portals consuming `ui-tables`
197
+ already declare `ui-buttons ^1.4.0`, so this is a declaration of existing reality, not a new
198
+ requirement.
199
+ - `FilterOption` and `DateRangeValue` are now ALIASES of `ui-forms`' `ControlOption` /
200
+ `DateRangeValue`. Public names unchanged; one definition instead of two structurally-identical
201
+ twins free to drift.
202
+ - `DEFAULT_TYPEAHEAD_MIN_CHARS` / `DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS` and `suggestOptions` /
203
+ `isUnmatched` are re-exported from `ui-forms`. Public API unchanged.
204
+ - Inherits the `AnchoredMenu` WCAG fix from `ui-forms` 1.8.0: the selected option now carries
205
+ `aria-selected`. `accessibilityState` is native-only and react-native-web ignores it, so on web
206
+ the current option had been conveyed by colour and font-weight alone (WCAG 1.4.1).
207
+ - `AnchoredMenu` remains one of three near-identical anchored-menu implementations, with
208
+ `ui-layout`'s `InlineMenu` and this package's `SizeDropdown`. Collapsing them was out of scope.
209
+ The move makes it EASIER: two of the three now sit in packages that may depend on `ui-forms`, so
210
+ a future collapse has an obvious home rather than needing a new shared package first.
211
+
212
+ ## 1.13.0
213
+
214
+ De-fork wave W1.1: pagination logic promoted from the byte-identical `PaginatedList`
215
+ twins in erevna-web and katalogos-web.
216
+
217
+ ### Added
218
+
219
+ - `usePagedRows(rows, { pageSize })` — client-side pagination state for an already
220
+ in-memory array. Returns `pageRows`, `currentPage`, `totalPages`, `setPage`,
221
+ `hasPages`, `pageSize`. No new translation keys; no action required.
222
+
223
+ Promoted as a **hook, not a component**, deliberately: the app-side `PaginatedList`
224
+ hard-bound a `FlatList` plus app-specific empty and loading states. Only the paging
225
+ maths is genuinely shared, so only that moved — callers keep their own list renderer.
226
+ For server-side paging keep using `DataTable`'s pager.
227
+
228
+ ### Fixed (behaviour differs from the app-side original)
229
+
230
+ - The original only clamped the page index when `totalPages > 0`, so emptying the list
231
+ left a stale non-zero page behind and the next non-empty render started on the wrong
232
+ page. `usePagedRows` clamps to 0 in that case.
233
+ - A `pageSize` of 0 divided by zero (`Math.ceil(n / 0)` → `Infinity` pages). Now floored
234
+ to 1.
235
+ - `setPage` clamps out-of-range input; the original trusted the caller.
236
+
237
+ ## 1.12.0
238
+
239
+ Accessibility fix: controls that announced a **bare number** now say what they are. Confirmed in
240
+ a real browser, the rows-per-page trigger rendered `aria-label="50"` — a screen-reader user heard
241
+ the value and nothing about the control. Fixed across the whole package, plus two more instances
242
+ of the same defect class found while auditing.
243
+
244
+ ### ⚠️ ACTION REQUIRED — add three translation keys
245
+
246
+ The new accessible names are user-facing strings, so they come from the host app's locale files.
247
+ **Every consuming app must add these three keys:**
248
+
249
+ | Key | Params | Suggested English |
250
+ |---|---|---|
251
+ | `uiTables.pager.rowsTriggerLabel` | `{{p1}}` = current page size | `Rows per page, currently {{p1}}` |
252
+ | `uiTables.pager.rowsOptionLabel` | `{{p1}}` = that option's size | `Show {{p1}} rows per page` |
253
+ | `uiTables.filters.selectTriggerLabel` | `{{p1}}` = field label, `{{p2}}` = selection | `{{p1}}: {{p2}}` |
254
+
255
+ They are exported as `TABLE_I18N.pagerRowsTriggerLabel`, `TABLE_I18N.pagerRowsOptionLabel` and
256
+ `FILTERS_I18N.selectTriggerLabel`, so an app that derives its required-key list from those maps
257
+ (as zygos' guard test does) picks them up automatically.
258
+
259
+ **Upgrading without adding them is safe.** Unlike the usual kit contract — where an undefined key
260
+ renders as its literal dotted name, the failure that put 44 raw keys on screen in zygos — a
261
+ newly-introduced ACCESSIBLE-NAME key degrades to the value it replaced (the bare number, the field
262
+ label). An aria-label is invisible to sighted reviewers, so a raw key there would ship silently and
263
+ hurt only screen-reader users. Until you add the keys you simply keep the old, worse names.
264
+
265
+ ### Fixed
266
+
267
+ - **`Pager` rows-per-page trigger** (`dropdown` variant) — was `aria-label="50"`, now
268
+ "Rows per page, currently 50".
269
+ - **`Pager` rows-per-page options** (`dropdown` variant) — was `aria-label="100"`, now
270
+ "Show 100 rows per page".
271
+ - **`Pager` rows-per-page pills** (the **DEFAULT** `pills` variant) — carried the identical
272
+ bare-number defect and was NOT in the original report, so it affected more consumers than the
273
+ dropdown did. Same fix, same key.
274
+ - **`Filters` select trigger** — `accessibilityLabel` replaces the trigger's visible text for a
275
+ screen reader, so labelling it `field.label` alone silently hid the current selection: sighted
276
+ users saw "Closed", screen-reader users heard only "Status". Now "Status: Closed".
277
+ - **`StatCard`** — its two translation keys were string literals inlined in the component rather
278
+ than members of an exported map, so an app deriving its required-key list from `TABLE_I18N`
279
+ could not see them and would render them raw. Now exported as `TABLE_I18N.statCardLabel` /
280
+ `TABLE_I18N.statHint`. **The key strings are unchanged** (`analytics.statCardLabel`,
281
+ `analytics.statHint`) — renaming them would have broken every app that already defines them.
282
+
283
+ ### Added
284
+
285
+ - **`accessibleName(translated, key, fallback)`** — the internal degradation guard described
286
+ above. Not exported; the kit's fallback-free i18n contract is unchanged for visible copy.
287
+
288
+ Additive and backward compatible for consumers — no public prop changed, so a MINOR bump.
289
+ `SizeDropdown`'s props gained `triggerLabel` / `getOptionLabel`, but that component is internal
290
+ (never exported from the package root).
291
+
292
+ ## 1.11.0
293
+
294
+ Additive: a **declarative `Filters` bar** + **Pager** enhancements. Every change is additive and
295
+ backward compatible — existing `FilterBar` / `Pager` / `DataTable` consumers (aml-v2, agora,
296
+ zygos, kefi, erevna, katalogos) are untouched and every new prop is optional, so a MINOR bump.
297
+ No app is migrated by this release; adoption is a later wave (see `ADOPTION.md`).
298
+
299
+ - **`Filters`** — the declarative, configurable filter bar built ON the existing `FilterBar`
300
+ shell (reusing its live results count + WCAG live region + actions slot). A caller passes a
301
+ `fields` schema — the SUPERSET harvested from every portal's hand-rolled filters — of kinds
302
+ `select` / `text` / `number` / `dateRange` / `typeahead` / `boolean`, plus a value map and
303
+ `onChange`. Two value models: **LIVE** (edits apply immediately — agora, zygos) and
304
+ **DRAFT/APPLY** (edits accumulate in a draft, an Apply button + Enter-in-a-field commit it —
305
+ aml, kefi audit), the latter driven by the new `useFilterDraft` hook. Customisation is style
306
+ (theme) + slots only: every label/option/placeholder/error is a pre-localized string; no
307
+ FM/router/store. Apps can inject `@dloizides/ui-layout`'s `ModalDropdown` for the `select`
308
+ field via `renderSelect` (the in-tree dropdown is the dependency-free default).
309
+ - **`useFilterDraft`** — the draft-vs-applied state engine (draft + committed + `apply` / `reset`
310
+ / `setField` / `dirty`), with `onApply` / `onReset` callbacks the caller wires to `setPage(1)`
311
+ (the universal reset-to-page-1-on-narrowing invariant, kept free of pagination coupling).
312
+ - **`suggestOptions` / `isUnmatched`** — the ranked substring matcher behind the `typeahead`
313
+ field (generalized from aml's `suggestCountries`), exported for reuse.
314
+ - **`Pager`** — three additive props reconciling the variants across apps: `showFirstLast`
315
+ (First/Last jump buttons, disabled at bounds — erevna's `PaginationControls`),
316
+ `unitLabelSingular` (renders `1 result` when `total === 1` — the singularisation apps did in
317
+ the FilterBar noun), and `responsive` + `stackBreakpoint` (collapse to a compact
318
+ Prev/Next-only nav below the breakpoint — the mobile fallback, mirroring the DataTable
319
+ card-stack). New pager test ids `ui-pager-first` / `ui-pager-last`.
320
+
321
+ ## 1.10.0
322
+
323
+ Additive: **bulk-select** + **keyboard navigation** on `DataTable` (ZY-08). Every new prop is
324
+ optional and CONTROLLED — omit them all and the table renders exactly as it did on 1.9.2, so
325
+ erevna / katalogos / kefi / agora are unaffected. Hence a MINOR bump.
326
+
327
+ - **Bulk-select** — `selectedRowKeys` + `onSelectionChange` add a checkbox gutter to the
328
+ header and every row. Controlled, following the `expandedRowKeys` precedent exactly: the
329
+ table keeps no internal selection state, and `onSelectionChange` is the enabler (as
330
+ `renderRowDetail` is for expansion). The header checkbox is genuinely tri-state
331
+ (`accessibilityState.checked: 'mixed'` + `aria-checked="mixed"`), and only ever adds or
332
+ removes keys belonging to the CURRENT page — off-page keys the caller holds are preserved,
333
+ because the table must not drop a selection it cannot see.
334
+ - **Select all matching the filter — a FLAG, never an id list.** `matchingCount` +
335
+ `onSelectAllMatchingChange` add a banner once the page is fully selected and more rows
336
+ match. It emits `true`/`false`; the table never enumerates the matching rows (they are on
337
+ pages it never fetched, and the ZY-02 spike measured ~2–3 ms and ~16 DOM nodes per row, so
338
+ materialising thousands of them is indistinguishable from an outage). Toggling a single row
339
+ under the flag drops it — the operator is no longer acting on *the filter*.
340
+ - **Keyboard navigation** — `keyboardNavigation` (default **off**, because giving rows a
341
+ `tabIndex` changes a page's tab order) implements the ARIA grid **roving tabindex**: one tab
342
+ stop for the whole grid, ↑/↓ to move (clamped, never wrapping), Home/End, Space to toggle
343
+ selection, Enter to activate via the existing `onRowPress`. Keys the table does not handle
344
+ are never `preventDefault`ed, so Tab and browser shortcuts keep working. When the page
345
+ changes underneath it the tab stop re-homes onto the new first row rather than vanishing —
346
+ without that guard the grid would become keyboard-unreachable the moment an operator paged.
347
+ Web-only in effect (focus movement and key events are DOM concerns); inert on native, via
348
+ the same deliberate split as the `position: 'sticky'` header.
349
+ - **a11y** — `role="grid"` / `row` / `columnheader` / `cell` when navigable; `aria-selected`
350
+ on rows when selectable; row checkboxes are labelled with the ROW's name, so they announce
351
+ as "Instruction ABC, checkbox" rather than an anonymous "checkbox" repeated down the page.
352
+ - **🔴 A selectable row's checkbox sits OUTSIDE its pressable area** — a sibling, never a
353
+ descendant. A checkbox nested inside an interactive row's `Pressable` is precisely the shape
354
+ the 1.9.2 fix identified as broken: the row's pointer responders CAPTURE the gesture and
355
+ cancel the child's press, so the checkbox would pass a synthetic `element.click()` test and
356
+ silently do nothing under a real mouse, touch or Playwright click. A selectable row is now a
357
+ plain `<View>` frame holding the checkbox and a separate pressable content area.
358
+ - New exports: `rowSelectTestID(tableTestID, key)`, `selectAllTestID(tableTestID)`, the
359
+ `uiTables.select.*` keys on `TABLE_I18N`, and the `selectCell` / `selectBanner`
360
+ `styleOverrides` slots. No existing export changed.
361
+ - Internals split for clarity as the row grew three shapes: `DataTableRow`, `TableRow`,
362
+ `TableHeader`, `RowCells`, plus pure `selection.ts` / `rowNav.ts` rule modules and the
363
+ `useTableSelection` / `useRovingFocus` hooks. No behaviour change for existing consumers
364
+ (the full 1.9.2 suite passes untouched).
365
+
366
+ ## 1.9.2
367
+
368
+ - **🔴 In-cell action buttons (Edit/Delete/Stop) now fire on a real pointer gesture, not just a bare
369
+ synthetic click.** A NON-interactive row (no `onRowPress`) was still rendered as a `<Pressable>`.
370
+ On react-native-web a `Pressable` installs pointer responders (pointerdown/up/cancel) on the row
371
+ container that CAPTURE a real mouse/touch gesture and cancel the press of any interactive child in
372
+ a cell — so a Delete/Stop/Edit button inside a static row looked clickable, fired on a bare
373
+ `element.click()`, but silently did nothing on an actual click/tap (and on a Playwright `.click()`,
374
+ which is why the AML v2 settings webhook-delete + stop-monitoring E2Es were red). A non-pressable
375
+ row is now a plain `<View>` (new `RowContainer`), so its cell controls receive the full gesture.
376
+ Interactive tables (`onRowPress`) are unchanged. Same class as the earlier `disabled`→
377
+ `pointer-events:none` fix; this closes the remaining pointer-responder-capture path.
378
+
379
+ ## 1.9.0
380
+
381
+ - **`Pager` dropdown-variant rows menu now escapes ancestor stacking contexts (web).** The
382
+ `rowsVariant="dropdown"` `SizeDropdown` menu opened but painted UNDER the results table on wide
383
+ web: react-native-web renders every `View` as `position: relative; z-index: 0`, so the in-tree
384
+ `position: absolute; zIndex: 1000` menu was trapped inside its anchor's stacking context and lost
385
+ to later-painting siblings (the table / cards below).
386
+ - On **web** the open menu now renders in a PORTAL to `document.body` with `position: fixed` at the
387
+ trigger's measured viewport rect (right-aligned, recomputed on scroll/resize) and a high `zIndex`
388
+ — clipped by nothing, above everything. Mirrors `@dloizides/ui-layout`'s InlineMenu fix.
389
+ - On **native** the menu is unchanged (in-tree `position: absolute` + `elevation`). All web-only code
390
+ (portal, `document`/`window` listeners, `position: fixed`) is guarded behind `Platform.OS === 'web'`.
391
+ - Outside-click dismissal now consults BOTH the anchor and the portalled menu node.
392
+ - `react-dom` is added as an **optional** peer dependency (only touched on web; every RN-web consumer
393
+ already has it). No API change: the `rowsVariant="dropdown"` contract, all test ids, the compact v1
394
+ look and a11y (role/aria/keyboard) are unchanged.
395
+
396
+ ## 1.8.0
397
+
398
+ - `Pager` gains an additive, **default-off** `rowsVariant?: 'pills' | 'dropdown'` prop.
399
+ - `'pills'` (default) is unchanged — the RN-idiom row of pressable size pills. Every existing
400
+ consumer (erevna / katalogos / kefi / coverage) renders byte-identically.
401
+ - `'dropdown'` swaps the size pills for a compact `<select>`-like anchored dropdown matching
402
+ the v1 console's "Rows" select: a bordered trigger (height-matched to the Prev/Next ghost
403
+ buttons) showing the current size + a chevron, opening a popover of the `pageSizeOptions`
404
+ that fires `onPageSizeChange` and closes on select / outside-click / Escape. The "Rows"
405
+ caption is mixed-case (not uppercase) in this variant, matching v1's muted `.hint` label.
406
+ - Self-contained: the anchored dropdown is implemented inside ui-tables (new `SizeDropdown`),
407
+ reusing ui-layout's InlineMenu click-outside/Escape pattern WITHOUT taking a hard dependency
408
+ on `@dloizides/ui-layout` — its ModalDropdown trigger has fixed chunky padding and no chevron,
409
+ so it cannot match v1's compact select, and a low-level table primitive should not depend on
410
+ a higher-level layout package. New option/trigger test ids: `${testID}-size-trigger`,
411
+ `${testID}-size-menu`, and the existing `${testID}-size-${size}` per option.
412
+
413
+ ## 1.7.0
414
+
415
+ - **Accessibility (WCAG 2.1 AA) hardening — additive + backward-compatible.**
416
+ - `FilterBar`: the results-count line is now a `role="status"` / `aria-live="polite"` live
417
+ region, so a screen reader announces the new count when filters change the result set
418
+ (WCAG 4.1.3).
419
+ - `Pager`: the Prev/Next controls and the rows-per-page pills gain a vertical `hitSlop` so the
420
+ touch target reaches ~44px WITHOUT changing the rendered size (adjacent pills never overlap).
421
+
422
+ ## 1.6.0
423
+
424
+ - `DataTable` gains a **web row-hover highlight** on clickable rows, matching the v1 console's
425
+ `.ui-table tr.clickable:hover` rule. Only interactive rows (those with an `onRowPress`) tint
426
+ on hover — static rows never light up. The tint is the theme's soft brand fill
427
+ (`palette.primary['500']` at low alpha via the new `softBrandTint` helper), so it re-themes
428
+ per tenant, falling back to a subtle surface tint when `primary` is not a plain `#rrggbb`.
429
+ The hover tint wins over zebra/`rowTint` while hovered (mirroring v1's `:hover td { background }`).
430
+ - **Native-safe + backward-compatible**: hover is driven by `Pressable`'s `onHoverIn`/`onHoverOut`,
431
+ which are no-ops on iOS/Android, and the handlers are wired only for interactive tables — a
432
+ non-interactive table renders byte-identically to before. Benefits every consumer
433
+ (erevna/katalogos/kefi/aml-v2) with clickable rows.
434
+
435
+ ## 1.5.0
436
+
437
+ - `Pager` gains two additive, **default-off** props so a paged grid can read exactly like the
438
+ v1 AML console's `.ui-pager__info` line:
439
+ - `infoPrefix?: string` — an already-translated word prefixed to the count
440
+ (e.g. `"Showing"` → `Showing 1–50 of 3,023 leadership terms`).
441
+ - `boldNumbers?: boolean` — renders the three counts (from / to / total) in bold
442
+ `colors.text`, matching v1's `.ui-pager__info b`.
443
+ - **Backward-compatible**: with both props omitted the count line is byte-identical to before
444
+ (the concatenated text is unchanged even with `boldNumbers` on — bold is styling only), so
445
+ existing consumers (`/coverage`, aml-v2) are unaffected.
446
+
447
+ ## Unreleased
448
+
449
+ - **Pixel-perfect overrides** (additive, backward-compatible). The kit's defaults are
450
+ opinionated but never mandatory — a consumer that must match an existing look can now
451
+ do so without forking:
452
+ - `DataTable` gains `styleOverrides?: DataTableStyleOverrides` (slots: `wrap`, `headRow`,
453
+ `headCell`, `row`, `cell`, `numCell`, `state`, `stateText`, `rowDetail`, `card`,
454
+ `cardLine`, `cardLabel`, `cardValue`).
455
+ - `Pager` gains `styleOverrides?: PagerStyleOverrides` (slots: `pager`, `pagerInfo`,
456
+ `pagerNav`, `pagerRowsLabel`, `sizeGroup`, `control`, `controlText`, `sizePill`,
457
+ `sizePillText`).
458
+ - `FilterBar` gains `styleOverrides?: FilterBarStyleOverrides` (slots: `filters`,
459
+ `filtersSpacer`, `results`, `filtersActions`).
460
+ - Each slot is merged **LAST** into its style array, so an override beats the base
461
+ StyleSheet **and** the inline colour the component applies from `useUi().theme`
462
+ (colours are never in the StyleSheet in this kit).
463
+ - Documented: `stackBreakpoint={0}` disables the responsive card-stack (`width < 0` is
464
+ never true), for surfaces that never had one.
465
+ - Omit `styleOverrides` and every render is byte-identical to before (verified by test).
466
+
467
+ - `DataTable` — **expandable rows** (additive, backward-compatible). Two new optional props:
468
+ - `renderRowDetail?: (row: T) => React.ReactNode` — renders a full-width detail panel
469
+ (spanning every column) directly beneath a row, between it and the next row. Works in
470
+ the desktop grid *and* in the responsive card-stack.
471
+ - `expandedRowKeys?: readonly string[]` — the `keyExtractor` keys of the rows currently
472
+ expanded. Expansion is **controlled by the caller** (own the state, toggle from
473
+ `onRowPress`); the table keeps no internal expand state and adds no chevron.
474
+ - The panel gets a stable test id `${testID}-row-detail-${key}` (new helpers
475
+ `rowDetailTestID(tableTestID, key)` / `rowTestID(tableTestID, key)`), is exposed to
476
+ assistive tech as a labelled region (`accessibilityRole="summary"` +
477
+ the new `uiTables.rowDetail` translation key), and the row it belongs to reports
478
+ `aria-expanded` / `accessibilityState.expanded`.
479
+ - Omit both props and the table renders exactly as before: no extra DOM node, no extra
480
+ row props, no behaviour change for existing consumers.
481
+ - Unblocks kefi-web's audit log (before/after JSON snapshot panel) adopting `DataTable`.
482
+
483
+ ## 1.2.0
484
+
485
+ - `Pager` — new optional `unitLabel?: string` prop. When supplied it appends an
486
+ already-translated unit noun to the count line, e.g. `unitLabel="leadership terms"`
487
+ renders `1–50 of 3,023 leadership terms` (v1 parity). Backward-compatible: when the
488
+ prop is omitted (or empty) the count line stays the generic `from–to of N`,
489
+ byte-identical to prior behaviour.
490
+ - Test tooling — added `src/jest-dom.d.ts` so ts-jest picks up the
491
+ `@testing-library/jest-dom` matcher types (`toBeDisabled`, …) when type-checking each
492
+ test file (`jest.setup.ts` sits outside the `src/**` include). Fixes the `Pager` suite
493
+ failing to compile under the isolated ts-jest type-check.
494
+
495
+ ## 1.1.0
496
+
497
+ - `DataTable` — promoted from the `/coverage` RN-web POC and hardened into the shared,
498
+ tokenized grid (the `wwwroot/shared/GRID.md` contract):
499
+ - per-row `testID` + `accessibilityLabel`/`accessibilityHint`, pressable rows (`onRowPress`);
500
+ - all user-facing chrome routed through the UiProvider `t` (no literals) — falls back to
501
+ caller-supplied `loadingLabel`/`emptyLabel`;
502
+ - fixed the POC's double `col.render()` call in the desktop path (now rendered once per cell);
503
+ - added the rest of the GRID.md contract: `FilterBar`, `Pager` (page-info + Prev/Next +
504
+ rows-per-page), an optional `zebra` modifier, and a `stickyHeader`;
505
+ - responsive label:value card-stack via `useWindowDimensions` below `stackBreakpoint`;
506
+ - every colour from `@dloizides/design-tokens` via the `useUi()` theme — no hardcoded colours.
507
+ - Component tests (`DataTable`, `FilterBar`, `Pager`) added.
508
+
509
+ ## 1.0.0
510
+
511
+ Initial release (Capability Wave C1, batch 3).
512
+
513
+ - `StatCard` — extracted from the proven erevna ↔ katalogos duplication; shares the
514
+ `@dloizides/ui-feedback` UI context (`useUi`).
515
+ - `DataTable` / `StatGrid` intentionally NOT included yet — they exist only in kefi-web (n=1);
516
+ they'll be added when a 2nd consumer appears.