@dloizides/ui-tables 1.10.0 → 1.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/ADOPTION.md ADDED
@@ -0,0 +1,163 @@
1
+ # Adopting the shared `Filters` + `Pager` (migration wave)
2
+
3
+ `@dloizides/ui-tables@1.11.0` ships the declarative **`Filters`** bar, the **`useFilterDraft`**
4
+ state engine, and additive **`Pager`** props (`showFirstLast`, `unitLabelSingular`, `responsive`).
5
+ This doc maps each portal's CURRENT hand-rolled filters + pagination onto the shared API so a
6
+ follow-up wave can migrate them one screen at a time. **Nothing here is done yet** — this release
7
+ delivers the package + tests only; adoption is deliberately separate to avoid colliding with other
8
+ agents' in-flight work.
9
+
10
+ Everything is additive and backward compatible: existing `FilterBar` / `Pager` / `DataTable`
11
+ usage is unchanged. Adopt `Filters` screen-by-screen; there is no big-bang cutover.
12
+
13
+ ---
14
+
15
+ ## The shared API in one screen
16
+
17
+ ```tsx
18
+ import { Filters, useFilterDraft, Pager, type FilterField, type FilterValues } from '@dloizides/ui-tables';
19
+ ```
20
+
21
+ - **`Filters`** renders a `fields: FilterField[]` schema into the `FilterBar` shell.
22
+ - **Field kinds**: `select`, `text`, `number`, `dateRange`, `typeahead`, `boolean`.
23
+ - **Value map** `FilterValues = Record<string, string | boolean | { from; to }>`, keyed by `field.key`.
24
+ - **Value model** is chosen by whether you pass `onApply`:
25
+ - no `onApply` → **LIVE** (each edit calls `onChange`).
26
+ - `onApply` set → **DRAFT/APPLY** (Apply button + Enter-in-a-field commit; pass `onClear` for Reset).
27
+ - **`useFilterDraft({ initial, onApply, onReset })`** is the draft engine — wire `onApply`/`onReset` to `setPage(1)`.
28
+ - Every user-facing string is a **pre-localized** value you pass in (labels, option labels, placeholders, errors).
29
+
30
+ ---
31
+
32
+ ## aml-v2 — cases / leaders / peps (DRAFT/APPLY; the richest filter set)
33
+
34
+ Today: `CasesFilters` / `LeadersFilters` / `PepsFilters` render `<Text label>` + a per-field
35
+ control (ModalDropdown / ThemedTextInput / DateField / CountryPicker / FormSwitch); each host
36
+ holds `draft` + `committed` + `page` + `pageSize`, commits on Apply, resets page to 1.
37
+
38
+ Map onto the shared API:
39
+
40
+ | aml field | current control | → `FilterField` kind |
41
+ |---|---|---|
42
+ | `decision` / `reviewStatus` / `source` / `riskBand` / `isMatch` / `role` / `status` / `category` | `ModalDropdown` (leading "Any", value `''`) | `select` (options with a leading `{ label: FM('..any'), value: '' }`) |
43
+ | `q` | `ThemedTextInput`, submit → apply | `text` (`grow: true`) |
44
+ | `yearFrom` / `yearTo` | `ThemedTextInput keyboardType="numeric"` | `number` |
45
+ | `from` / `to` | `DateField` (native `<input type=date>`) | one `dateRange` field `{ key: 'dates' }` |
46
+ | `country` | `CountryPicker` (bespoke typeahead) | `typeahead` (`options: countryOptions, minChars: 1`) |
47
+ | `includeRelatives` / `prioritize` | `FormSwitch` | `boolean` |
48
+
49
+ - Replace the twin `draft`/`committed` `useState`s with `useFilterDraft({ initial: EMPTY, onApply: () => setPage(1), onReset: () => { setPage(1); clearCountryError(); } })`.
50
+ - `values={draft.draft}`, `onChange={draft.setDraft}`, `onApply={draft.apply}`, `onClear={draft.reset}` (leaders/peps have Reset; cases did not — omit `onClear` there).
51
+ - `applyDisabled={busy}` (aml disables Apply while loading).
52
+ - Export CSV/PDF buttons → the `actions` slot; keep operating on `draft.committed`.
53
+ - Country validation → set the field's `error` (pre-localized `FM('leaders.error.unrecognisedCountry')`); the `typeahead` renders the persistent `role="alert"` banner. Use the exported `isUnmatched(countryOptions, text)` to detect an unrecognised entry, or keep aml's `codeOf`.
54
+ - Results count: keep passing `resultsCount` + `resultsLabel` (aml already singularises the noun caller-side — `resultOne`/`resultMany`).
55
+ - **Select rendering**: to keep aml's exact ModalDropdown UX (responsive modal on mobile), pass `renderSelect={({ field, value, onChange, testID }) => <ModalDropdown … />}`. Otherwise use the built-in in-tree dropdown.
56
+ - Pager is already the shared `Pager` (rowsVariant="dropdown"); no change needed. Optionally add `unitLabelSingular` now that it exists.
57
+
58
+ ---
59
+
60
+ ## kefi-web — audit log (DRAFT/APPLY; the prime migration candidate)
61
+
62
+ Today: bespoke `AuditFilters` (local `draft`, Apply/Clear, date-validity gate) + bespoke
63
+ `AuditPager` (two lines: "showing X–Y of N" + "page X of N", Prev/Next only). Uses `DataTable`
64
+ already (via `KefiDataTable`) but NOT the shared `FilterBar`/`Pager`.
65
+
66
+ Map:
67
+
68
+ | audit field | current | → kind |
69
+ |---|---|---|
70
+ | `action` / `entityType` | exact-match text | `text` |
71
+ | `from` / `to` (`YYYY-MM-DD`) | two date text inputs | one `dateRange` field |
72
+
73
+ - `useFilterDraft({ initial: { action:'', entityType:'', dates:{from:'',to:''} }, onApply: () => setPage(1) })`.
74
+ - `onApply={draft.apply}` (Apply), `onClear={draft.reset}` (Clear resets draft AND committed — matches today).
75
+ - `applyDisabled={!datesValid}` — keep the `isValidDateInput` gate; keep the inline `FeedbackBanner` above (or move the message onto a field `error`).
76
+ - Convert `toQuery` to read `dates.from` / `dates.to` (was `from` / `to`).
77
+ - Replace `AuditPager` with `Pager` (`page`, `pageSize`, `total={totalCount}`, `unitLabel`, `infoPrefix={FM('common.showing')}`). The "page X of N" line is not encoded in `Pager` — either drop it (the `from–to of N` covers it) or keep a small caption alongside.
78
+
79
+ ---
80
+
81
+ ## zygos-web — instructions / approvals (LIVE; the canonical model)
82
+
83
+ Today: `InstructionsFilters` renders text search + three `ModalDropdown`s; `useInstructionsQuery`
84
+ patch-merges edits (`patchFilter`) and resets to page 1 on any change. Already uses shared
85
+ `FilterBar` + `Pager` + `DataTable`.
86
+
87
+ Map (LIVE — no `onApply`):
88
+
89
+ | field | current | → kind |
90
+ |---|---|---|
91
+ | `search` | `ThemedTextInput` | `text` (`grow: true`) |
92
+ | `statuses` | `ModalDropdown` (single control emitting a 1-element list) | `select` — keep the control single; map `value` ↔ `statuses[0]` in `onChange` |
93
+ | `direction` / `currency` | `ModalDropdown` | `select` |
94
+ | `valueDateFrom`/`To`, `minAmount`/`maxAmount`, `sortBy` | latent in types, not yet rendered | add as `dateRange` / two `number` / a `select` when you surface them |
95
+
96
+ - `values` = the current filter; `onChange` = replace-then-`patchFilter` (or adapt `patchFilter` to accept the full map).
97
+ - The pinned/locked-key pattern (approvals' `APPROVALS_FILTER` + `LOCKED_KEYS`) → simply **omit** the locked field from the `fields` array for that screen (the shared bar renders exactly the fields you pass).
98
+ - `BulkApproveBar` → the `actions` slot (it already goes into `FilterBar.actions`).
99
+ - Pager already shared with `pageSizeOptions={[25,50,100]}` (API cap) + `boldNumbers` — unchanged.
100
+
101
+ ---
102
+
103
+ ## agora-web — products / orders (LIVE)
104
+
105
+ Today: `ProductsFilters` (text search + category `ModalDropdown`), `OrdersFilters` (status
106
+ `ModalDropdown`); `useProductsQuery`/`useOrdersQuery` set values live and reset page to 1. Already
107
+ uses shared `FilterBar` + `Pager` + `DataTable`.
108
+
109
+ Map (LIVE):
110
+
111
+ | field | → kind |
112
+ |---|---|
113
+ | products `search` | `text` (`grow: true`) |
114
+ | products `categoryId` (sentinel `''`) | `select` |
115
+ | orders `status` (`OrderStatus \| ''`) | `select` (map `'' → undefined` in `onChange`) |
116
+
117
+ - Trivial migration: build the two/one field(s), pass `values` + `onChange`, keep `resultsCount`.
118
+ - Pager unchanged (kit defaults, pills variant).
119
+
120
+ ---
121
+
122
+ ## erevna-web / katalogos-web — menus / users / public menu (LIVE)
123
+
124
+ Today: hand-rolled, using ui-tables **only for `StatCard`** — no `FilterBar`/`Pager`. Several
125
+ distinct surfaces:
126
+
127
+ - **Public-menu filter** (`useMenuFilter`): text-search-with-clear + dietary-tag multi-select
128
+ chips. Map the search to a `text` field; the tag chips are a **multi-select** — not one of the
129
+ six first-class kinds yet. Options for now: keep the bespoke chip row in the `actions`/children,
130
+ OR model each tag as a `boolean` field, OR wait for a `multiSelect` kind (candidate for a
131
+ future minor). The `hasActiveFilters` + `clearAllFilters` contract maps to `onClear`.
132
+ - **Menus admin list** (`MenuTabBar`, `MenuTabFilter` enum All/Active): a single `select`
133
+ (`{All, Active}`) — or keep the tab bar (it is a segmented control, a different UI affordance).
134
+ - **Users list** (`TenantSelector` pills): a `select` of tenants (+ "All Users" = value `''`).
135
+ - **Generic `PaginationControls`** (first/prev/next/last, "Showing a-b of N", "p / total",
136
+ 0-based) + `PaginatedList`: replace with `Pager` using `showFirstLast`. Note `Pager` is
137
+ **1-based** — add 1 when mapping from the 0-based `currentPage`. `unitLabelSingular` covers the
138
+ singular the current templates lack.
139
+ - **`VersionHistoryPanel`** "Load More": `Pager` does not do load-more; keep it bespoke, or
140
+ switch that panel to page-based `Pager`.
141
+ - **`BillingHistoryTable`** (server prev/next-only + mobile horizontal-scroll): `Pager` without
142
+ `showFirstLast`; the DataTable card-stack replaces the manual `minWidth:500` scroll wrapper.
143
+
144
+ ---
145
+
146
+ ## Not yet first-class (candidates for a future minor)
147
+
148
+ Surfaced by the harvest but intentionally out of the initial six kinds — add on real second use:
149
+
150
+ - **`multiSelect`** — zygos `statuses` (list-shaped), erevna dietary-tag chips, katalogos tags.
151
+ - **`sort`** control — zygos `sortBy` + `sortDescending` (in types, no UI yet).
152
+ - **Load-more / infinite pager** — erevna `VersionHistoryPanel` (only one consumer).
153
+ - **"page X of N" position line** — kefi audit's second pager line (the `from–to of N` covers it).
154
+
155
+ ---
156
+
157
+ ## Pager prop cheatsheet (new in 1.11.0)
158
+
159
+ | Prop | Effect | Adopt where |
160
+ |---|---|---|
161
+ | `showFirstLast` | First/Last jump buttons (disabled at bounds) | erevna `PaginationControls`, any large dataset |
162
+ | `unitLabelSingular` | `1 result` when `total === 1` | anywhere a unit noun is shown |
163
+ | `responsive` + `stackBreakpoint` | compact Prev/Next-only nav below the breakpoint | mobile / narrow surfaces |
package/CHANGELOG.md CHANGED
@@ -1,5 +1,89 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.12.0
4
+
5
+ Accessibility fix: controls that announced a **bare number** now say what they are. Confirmed in
6
+ a real browser, the rows-per-page trigger rendered `aria-label="50"` — a screen-reader user heard
7
+ the value and nothing about the control. Fixed across the whole package, plus two more instances
8
+ of the same defect class found while auditing.
9
+
10
+ ### ⚠️ ACTION REQUIRED — add three translation keys
11
+
12
+ The new accessible names are user-facing strings, so they come from the host app's locale files.
13
+ **Every consuming app must add these three keys:**
14
+
15
+ | Key | Params | Suggested English |
16
+ |---|---|---|
17
+ | `uiTables.pager.rowsTriggerLabel` | `{{p1}}` = current page size | `Rows per page, currently {{p1}}` |
18
+ | `uiTables.pager.rowsOptionLabel` | `{{p1}}` = that option's size | `Show {{p1}} rows per page` |
19
+ | `uiTables.filters.selectTriggerLabel` | `{{p1}}` = field label, `{{p2}}` = selection | `{{p1}}: {{p2}}` |
20
+
21
+ They are exported as `TABLE_I18N.pagerRowsTriggerLabel`, `TABLE_I18N.pagerRowsOptionLabel` and
22
+ `FILTERS_I18N.selectTriggerLabel`, so an app that derives its required-key list from those maps
23
+ (as zygos' guard test does) picks them up automatically.
24
+
25
+ **Upgrading without adding them is safe.** Unlike the usual kit contract — where an undefined key
26
+ renders as its literal dotted name, the failure that put 44 raw keys on screen in zygos — a
27
+ newly-introduced ACCESSIBLE-NAME key degrades to the value it replaced (the bare number, the field
28
+ label). An aria-label is invisible to sighted reviewers, so a raw key there would ship silently and
29
+ hurt only screen-reader users. Until you add the keys you simply keep the old, worse names.
30
+
31
+ ### Fixed
32
+
33
+ - **`Pager` rows-per-page trigger** (`dropdown` variant) — was `aria-label="50"`, now
34
+ "Rows per page, currently 50".
35
+ - **`Pager` rows-per-page options** (`dropdown` variant) — was `aria-label="100"`, now
36
+ "Show 100 rows per page".
37
+ - **`Pager` rows-per-page pills** (the **DEFAULT** `pills` variant) — carried the identical
38
+ bare-number defect and was NOT in the original report, so it affected more consumers than the
39
+ dropdown did. Same fix, same key.
40
+ - **`Filters` select trigger** — `accessibilityLabel` replaces the trigger's visible text for a
41
+ screen reader, so labelling it `field.label` alone silently hid the current selection: sighted
42
+ users saw "Closed", screen-reader users heard only "Status". Now "Status: Closed".
43
+ - **`StatCard`** — its two translation keys were string literals inlined in the component rather
44
+ than members of an exported map, so an app deriving its required-key list from `TABLE_I18N`
45
+ could not see them and would render them raw. Now exported as `TABLE_I18N.statCardLabel` /
46
+ `TABLE_I18N.statHint`. **The key strings are unchanged** (`analytics.statCardLabel`,
47
+ `analytics.statHint`) — renaming them would have broken every app that already defines them.
48
+
49
+ ### Added
50
+
51
+ - **`accessibleName(translated, key, fallback)`** — the internal degradation guard described
52
+ above. Not exported; the kit's fallback-free i18n contract is unchanged for visible copy.
53
+
54
+ Additive and backward compatible for consumers — no public prop changed, so a MINOR bump.
55
+ `SizeDropdown`'s props gained `triggerLabel` / `getOptionLabel`, but that component is internal
56
+ (never exported from the package root).
57
+
58
+ ## 1.11.0
59
+
60
+ Additive: a **declarative `Filters` bar** + **Pager** enhancements. Every change is additive and
61
+ backward compatible — existing `FilterBar` / `Pager` / `DataTable` consumers (aml-v2, agora,
62
+ zygos, kefi, erevna, katalogos) are untouched and every new prop is optional, so a MINOR bump.
63
+ No app is migrated by this release; adoption is a later wave (see `ADOPTION.md`).
64
+
65
+ - **`Filters`** — the declarative, configurable filter bar built ON the existing `FilterBar`
66
+ shell (reusing its live results count + WCAG live region + actions slot). A caller passes a
67
+ `fields` schema — the SUPERSET harvested from every portal's hand-rolled filters — of kinds
68
+ `select` / `text` / `number` / `dateRange` / `typeahead` / `boolean`, plus a value map and
69
+ `onChange`. Two value models: **LIVE** (edits apply immediately — agora, zygos) and
70
+ **DRAFT/APPLY** (edits accumulate in a draft, an Apply button + Enter-in-a-field commit it —
71
+ aml, kefi audit), the latter driven by the new `useFilterDraft` hook. Customisation is style
72
+ (theme) + slots only: every label/option/placeholder/error is a pre-localized string; no
73
+ FM/router/store. Apps can inject `@dloizides/ui-layout`'s `ModalDropdown` for the `select`
74
+ field via `renderSelect` (the in-tree dropdown is the dependency-free default).
75
+ - **`useFilterDraft`** — the draft-vs-applied state engine (draft + committed + `apply` / `reset`
76
+ / `setField` / `dirty`), with `onApply` / `onReset` callbacks the caller wires to `setPage(1)`
77
+ (the universal reset-to-page-1-on-narrowing invariant, kept free of pagination coupling).
78
+ - **`suggestOptions` / `isUnmatched`** — the ranked substring matcher behind the `typeahead`
79
+ field (generalized from aml's `suggestCountries`), exported for reuse.
80
+ - **`Pager`** — three additive props reconciling the variants across apps: `showFirstLast`
81
+ (First/Last jump buttons, disabled at bounds — erevna's `PaginationControls`),
82
+ `unitLabelSingular` (renders `1 result` when `total === 1` — the singularisation apps did in
83
+ the FilterBar noun), and `responsive` + `stackBreakpoint` (collapse to a compact
84
+ Prev/Next-only nav below the breakpoint — the mobile fallback, mirroring the DataTable
85
+ card-stack). New pager test ids `ui-pager-first` / `ui-pager-last`.
86
+
3
87
  ## 1.10.0
4
88
 
5
89
  Additive: **bulk-select** + **keyboard navigation** on `DataTable` (ZY-08). Every new prop is
package/README.md CHANGED
@@ -10,7 +10,8 @@ portfolio. Reads theme + translations from the shared `@dloizides/ui-feedback` U
10
10
  | `StatCard` | ✅ Available — labelled metric tile (label + locale-formatted value). |
11
11
  | `DataTable` | ✅ Available — the shared, tokenized RN-web grid (the `GRID.md` contract): `columns + rows` API, sticky header, zebra striping, per-row tint, pressable rows, per-row `testID` + a11y, optional **expandable rows**, and a responsive label:value **card-stack** below `stackBreakpoint`. |
12
12
  | `FilterBar` | ✅ Available — the `.ui-filters` shell: wrapping field row + live results count + actions slot. |
13
- | `Pager` | ✅ Available — the `.ui-pager` control: `from–to of N` page-info + rows-per-page control + Prev/Next. Pass an optional, already-translated `unitLabel` (e.g. `"leadership terms"`) to render `1–50 of 3,023 leadership terms`. The rows-per-page control defaults to a row of size **pills** (`rowsVariant="pills"`); pass `rowsVariant="dropdown"` for the compact v1-console `<select>`-style anchored dropdown (trigger + chevron + popover, mixed-case "Rows" caption). |
13
+ | `Filters` | ✅ Available — the **declarative** filter bar built ON `FilterBar`: pass a `fields` schema (`select` / `text` / `number` / `dateRange` / `typeahead` / `boolean`) + a value map + `onChange`. Two value models (LIVE, or DRAFT/APPLY via `useFilterDraft` + an Apply button). The superset of every portal's hand-rolled filters; only the theme changes. See [Filters](#filters--declarative-filter-bar). |
14
+ | `Pager` | ✅ Available — the `.ui-pager` control: `from–to of N` page-info + rows-per-page control + Prev/Next (+ optional **First/Last** via `showFirstLast`). Pass an optional, already-translated `unitLabel` (e.g. `"leadership terms"`) — plus `unitLabelSingular` for `1 result` **singularisation** — to render `1–50 of 3,023 leadership terms`. `responsive` collapses to a compact Prev/Next-only nav below `stackBreakpoint` (mobile fallback). The rows-per-page control defaults to size **pills** (`rowsVariant="pills"`); pass `rowsVariant="dropdown"` for the compact `<select>`-style anchored dropdown. |
14
15
  | `StatGrid` | ⏳ Deferred — exists only in kefi-web (n=1); moves in when a 2nd consumer appears. |
15
16
 
16
17
  ### DataTable / FilterBar / Pager
@@ -28,6 +29,70 @@ const columns: DataTableColumn<Row>[] = [
28
29
  <Pager page={page} pageSize={size} total={total} onPageChange={setPage} onPageSizeChange={setSize} />
29
30
  ```
30
31
 
32
+ ### Filters — declarative filter bar
33
+
34
+ `FilterBar` is the *shell* (layout + results count + actions). `Filters` is the *declarative*
35
+ bar built on it: describe your filters as **data** and the bar renders the same structure +
36
+ behaviour everywhere — only the theme changes. Field kinds: `select`, `text`, `number`,
37
+ `dateRange`, `typeahead` (search-as-you-type), `boolean`.
38
+
39
+ Every user-facing string is **pre-localized** and passed in (labels, option labels, placeholders,
40
+ errors) — the package never calls FM/i18n for content, touches a router, or reads a store.
41
+
42
+ ```tsx
43
+ import { Filters, useFilterDraft, type FilterField, type FilterValues } from '@dloizides/ui-tables';
44
+
45
+ const fields: FilterField[] = [
46
+ { key: 'q', kind: 'text', label: FM('cases.q'), grow: true, placeholder: FM('cases.qHint') },
47
+ { key: 'status', kind: 'select', label: FM('cases.status'),
48
+ options: [{ label: FM('common.any'), value: '' }, { label: FM('status.open'), value: 'open' }] },
49
+ { key: 'dates', kind: 'dateRange', label: FM('cases.valueDate') },
50
+ { key: 'country', kind: 'typeahead', label: FM('leaders.country'), options: countryOptions, minChars: 1 },
51
+ { key: 'active', kind: 'boolean', label: FM('cases.activeOnly') },
52
+ ];
53
+ ```
54
+
55
+ **Live model** (agora / zygos) — each edit applies immediately, no Apply button:
56
+
57
+ ```tsx
58
+ const [values, setValues] = useState<FilterValues>(EMPTY);
59
+ <Filters fields={fields} values={values} onChange={setValues} resultsCount={total} resultsLabel={FM('cases.results')} />
60
+ ```
61
+
62
+ **Draft / apply model** (aml / kefi audit) — edits accumulate in a draft; Apply (or Enter in a
63
+ field) commits it, and page resets to 1 via your `onApply`. `useFilterDraft` is the state engine:
64
+
65
+ ```tsx
66
+ const draft = useFilterDraft({ initial: EMPTY, onApply: () => setPage(1) });
67
+ <Filters
68
+ fields={fields}
69
+ values={draft.draft}
70
+ onChange={draft.setDraft}
71
+ onApply={draft.apply} // presence of onApply → shows the Apply button + Enter-to-commit
72
+ applyDisabled={datesInvalid} // aml's validity gate
73
+ onClear={draft.reset} // presence of onClear → shows Clear/Reset
74
+ actions={<ExportButtons query={draft.committed} />} // custom actions (Export CSV/PDF, bulk bar)
75
+ resultsCount={total}
76
+ resultsLabel={total === 1 ? FM('cases.resultOne') : FM('cases.resultMany')} // caller singularises
77
+ />
78
+ ```
79
+
80
+ **Injecting `ModalDropdown`** — the built-in `select` is a dependency-free in-tree dropdown. To
81
+ use `@dloizides/ui-layout`'s responsive `ModalDropdown` (modal on mobile/native) instead, pass
82
+ `renderSelect`:
83
+
84
+ ```tsx
85
+ <Filters
86
+ fields={fields}
87
+ values={values}
88
+ onChange={setValues}
89
+ renderSelect={({ field, value, onChange, testID }) => (
90
+ <ModalDropdown testID={testID} accessibilityLabel={field.label} accessibilityHint={field.label}
91
+ value={value} options={field.options} onChange={onChange} />
92
+ )}
93
+ />
94
+ ```
95
+
31
96
  #### Expandable rows (optional)
32
97
 
33
98
  For surfaces that open a full-width detail panel under a row (e.g. an audit log's
@@ -161,6 +226,39 @@ renders exactly as it always has.
161
226
 
162
227
  Colours come entirely from `useUi().theme` (drive it with `@dloizides/design-tokens` via `tokensToUiTheme`), so the grid re-themes per tenant. Every component-authored string is routed through the UiProvider `t` — provide the `uiTables.*` keys (see `TABLE_I18N`) in your locale files; a caller may also pass already-translated `loadingLabel` / `emptyLabel` / `resultsLabel` directly.
163
228
 
229
+ ## ⚠️ New in 1.12.0 — three translation keys every host app must add
230
+
231
+ 1.12.0 gives three controls a real accessible name instead of a bare number. Those names are
232
+ user-facing strings, so they come from **your** locale files. **Add these three keys.**
233
+
234
+ | Key (constant) | Key (string) | Params | Suggested English |
235
+ |---|---|---|---|
236
+ | `TABLE_I18N.pagerRowsTriggerLabel` | `uiTables.pager.rowsTriggerLabel` | `{{p1}}` = current page size | `Rows per page, currently {{p1}}` |
237
+ | `TABLE_I18N.pagerRowsOptionLabel` | `uiTables.pager.rowsOptionLabel` | `{{p1}}` = that option's size | `Show {{p1}} rows per page` |
238
+ | `FILTERS_I18N.selectTriggerLabel` | `uiTables.filters.selectTriggerLabel` | `{{p1}}` = field label, `{{p2}}` = selected option | `{{p1}}: {{p2}}` |
239
+
240
+ Also newly **listed** in `TABLE_I18N` (not new keys — StatCard has always called them, they were
241
+ just inlined in the component where a key-coverage guard could not see them). If your app renders
242
+ `StatCard`, check you actually define them:
243
+
244
+ | Key (constant) | Key (string) | Params |
245
+ |---|---|---|
246
+ | `TABLE_I18N.statCardLabel` | `analytics.statCardLabel` | `{{p1}}` = label, `{{p2}}` = value |
247
+ | `TABLE_I18N.statHint` | `analytics.statHint` | `{{p1}}` = label |
248
+
249
+ **Your app will not visibly break if you skip this.** A key you have not defined degrades to the
250
+ value it replaced (the bare number, the field label alone) rather than to the raw dotted key —
251
+ so upgrading is safe, but until you add the keys your screen-reader users keep the old, worse
252
+ experience. Derive your required-key list from the exported maps rather than hand-maintaining it:
253
+
254
+ ```ts
255
+ import { TABLE_I18N, FILTERS_I18N } from '@dloizides/ui-tables';
256
+
257
+ // Guard test: every key the kit can ask for must exist in your locale file.
258
+ const required = [...Object.values(TABLE_I18N), ...Object.values(FILTERS_I18N)];
259
+ required.forEach((key) => expect(en).toHaveProperty(key));
260
+ ```
261
+
164
262
  ## Install
165
263
 
166
264
  ```bash
@@ -178,8 +276,9 @@ import { StatCard } from '@dloizides/ui-tables';
178
276
  ```
179
277
 
180
278
  Mount a `FeedbackUiProvider` / `UiProvider` (from `@dloizides/ui-feedback`) at your app root so the
181
- component picks up your theme + translations. The injected `t` is called with `analytics.statHint` and
182
- `analytics.statCardLabel` (provide these keys in your locale files).
279
+ component picks up your theme + translations. The injected `t` is called with `TABLE_I18N.statHint`
280
+ (`analytics.statHint`) and `TABLE_I18N.statCardLabel` (`analytics.statCardLabel`) — provide these
281
+ keys in your locale files.
183
282
 
184
283
  ## License
185
284