@dloizides/ui-tables 1.19.1 → 1.19.2

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