@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 +163 -0
- package/CHANGELOG.md +84 -0
- package/README.md +102 -3
- package/dist/index.d.mts +308 -2
- package/dist/index.d.ts +308 -2
- package/dist/index.js +973 -142
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +932 -117
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -2
package/ADOPTION.md
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# Adopting the shared `Filters` + `Pager` (migration wave)
|
|
2
|
+
|
|
3
|
+
`@dloizides/ui-tables@1.11.0` ships the declarative **`Filters`** bar, the **`useFilterDraft`**
|
|
4
|
+
state engine, and additive **`Pager`** props (`showFirstLast`, `unitLabelSingular`, `responsive`).
|
|
5
|
+
This doc maps each portal's CURRENT hand-rolled filters + pagination onto the shared API so a
|
|
6
|
+
follow-up wave can migrate them one screen at a time. **Nothing here is done yet** — this release
|
|
7
|
+
delivers the package + tests only; adoption is deliberately separate to avoid colliding with other
|
|
8
|
+
agents' in-flight work.
|
|
9
|
+
|
|
10
|
+
Everything is additive and backward compatible: existing `FilterBar` / `Pager` / `DataTable`
|
|
11
|
+
usage is unchanged. Adopt `Filters` screen-by-screen; there is no big-bang cutover.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## The shared API in one screen
|
|
16
|
+
|
|
17
|
+
```tsx
|
|
18
|
+
import { Filters, useFilterDraft, Pager, type FilterField, type FilterValues } from '@dloizides/ui-tables';
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
- **`Filters`** renders a `fields: FilterField[]` schema into the `FilterBar` shell.
|
|
22
|
+
- **Field kinds**: `select`, `text`, `number`, `dateRange`, `typeahead`, `boolean`.
|
|
23
|
+
- **Value map** `FilterValues = Record<string, string | boolean | { from; to }>`, keyed by `field.key`.
|
|
24
|
+
- **Value model** is chosen by whether you pass `onApply`:
|
|
25
|
+
- no `onApply` → **LIVE** (each edit calls `onChange`).
|
|
26
|
+
- `onApply` set → **DRAFT/APPLY** (Apply button + Enter-in-a-field commit; pass `onClear` for Reset).
|
|
27
|
+
- **`useFilterDraft({ initial, onApply, onReset })`** is the draft engine — wire `onApply`/`onReset` to `setPage(1)`.
|
|
28
|
+
- Every user-facing string is a **pre-localized** value you pass in (labels, option labels, placeholders, errors).
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## aml-v2 — cases / leaders / peps (DRAFT/APPLY; the richest filter set)
|
|
33
|
+
|
|
34
|
+
Today: `CasesFilters` / `LeadersFilters` / `PepsFilters` render `<Text label>` + a per-field
|
|
35
|
+
control (ModalDropdown / ThemedTextInput / DateField / CountryPicker / FormSwitch); each host
|
|
36
|
+
holds `draft` + `committed` + `page` + `pageSize`, commits on Apply, resets page to 1.
|
|
37
|
+
|
|
38
|
+
Map onto the shared API:
|
|
39
|
+
|
|
40
|
+
| aml field | current control | → `FilterField` kind |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| `decision` / `reviewStatus` / `source` / `riskBand` / `isMatch` / `role` / `status` / `category` | `ModalDropdown` (leading "Any", value `''`) | `select` (options with a leading `{ label: FM('..any'), value: '' }`) |
|
|
43
|
+
| `q` | `ThemedTextInput`, submit → apply | `text` (`grow: true`) |
|
|
44
|
+
| `yearFrom` / `yearTo` | `ThemedTextInput keyboardType="numeric"` | `number` |
|
|
45
|
+
| `from` / `to` | `DateField` (native `<input type=date>`) | one `dateRange` field `{ key: 'dates' }` |
|
|
46
|
+
| `country` | `CountryPicker` (bespoke typeahead) | `typeahead` (`options: countryOptions, minChars: 1`) |
|
|
47
|
+
| `includeRelatives` / `prioritize` | `FormSwitch` | `boolean` |
|
|
48
|
+
|
|
49
|
+
- Replace the twin `draft`/`committed` `useState`s with `useFilterDraft({ initial: EMPTY, onApply: () => setPage(1), onReset: () => { setPage(1); clearCountryError(); } })`.
|
|
50
|
+
- `values={draft.draft}`, `onChange={draft.setDraft}`, `onApply={draft.apply}`, `onClear={draft.reset}` (leaders/peps have Reset; cases did not — omit `onClear` there).
|
|
51
|
+
- `applyDisabled={busy}` (aml disables Apply while loading).
|
|
52
|
+
- Export CSV/PDF buttons → the `actions` slot; keep operating on `draft.committed`.
|
|
53
|
+
- Country validation → set the field's `error` (pre-localized `FM('leaders.error.unrecognisedCountry')`); the `typeahead` renders the persistent `role="alert"` banner. Use the exported `isUnmatched(countryOptions, text)` to detect an unrecognised entry, or keep aml's `codeOf`.
|
|
54
|
+
- Results count: keep passing `resultsCount` + `resultsLabel` (aml already singularises the noun caller-side — `resultOne`/`resultMany`).
|
|
55
|
+
- **Select rendering**: to keep aml's exact ModalDropdown UX (responsive modal on mobile), pass `renderSelect={({ field, value, onChange, testID }) => <ModalDropdown … />}`. Otherwise use the built-in in-tree dropdown.
|
|
56
|
+
- Pager is already the shared `Pager` (rowsVariant="dropdown"); no change needed. Optionally add `unitLabelSingular` now that it exists.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## kefi-web — audit log (DRAFT/APPLY; the prime migration candidate)
|
|
61
|
+
|
|
62
|
+
Today: bespoke `AuditFilters` (local `draft`, Apply/Clear, date-validity gate) + bespoke
|
|
63
|
+
`AuditPager` (two lines: "showing X–Y of N" + "page X of N", Prev/Next only). Uses `DataTable`
|
|
64
|
+
already (via `KefiDataTable`) but NOT the shared `FilterBar`/`Pager`.
|
|
65
|
+
|
|
66
|
+
Map:
|
|
67
|
+
|
|
68
|
+
| audit field | current | → kind |
|
|
69
|
+
|---|---|---|
|
|
70
|
+
| `action` / `entityType` | exact-match text | `text` |
|
|
71
|
+
| `from` / `to` (`YYYY-MM-DD`) | two date text inputs | one `dateRange` field |
|
|
72
|
+
|
|
73
|
+
- `useFilterDraft({ initial: { action:'', entityType:'', dates:{from:'',to:''} }, onApply: () => setPage(1) })`.
|
|
74
|
+
- `onApply={draft.apply}` (Apply), `onClear={draft.reset}` (Clear resets draft AND committed — matches today).
|
|
75
|
+
- `applyDisabled={!datesValid}` — keep the `isValidDateInput` gate; keep the inline `FeedbackBanner` above (or move the message onto a field `error`).
|
|
76
|
+
- Convert `toQuery` to read `dates.from` / `dates.to` (was `from` / `to`).
|
|
77
|
+
- Replace `AuditPager` with `Pager` (`page`, `pageSize`, `total={totalCount}`, `unitLabel`, `infoPrefix={FM('common.showing')}`). The "page X of N" line is not encoded in `Pager` — either drop it (the `from–to of N` covers it) or keep a small caption alongside.
|
|
78
|
+
|
|
79
|
+
---
|
|
80
|
+
|
|
81
|
+
## zygos-web — instructions / approvals (LIVE; the canonical model)
|
|
82
|
+
|
|
83
|
+
Today: `InstructionsFilters` renders text search + three `ModalDropdown`s; `useInstructionsQuery`
|
|
84
|
+
patch-merges edits (`patchFilter`) and resets to page 1 on any change. Already uses shared
|
|
85
|
+
`FilterBar` + `Pager` + `DataTable`.
|
|
86
|
+
|
|
87
|
+
Map (LIVE — no `onApply`):
|
|
88
|
+
|
|
89
|
+
| field | current | → kind |
|
|
90
|
+
|---|---|---|
|
|
91
|
+
| `search` | `ThemedTextInput` | `text` (`grow: true`) |
|
|
92
|
+
| `statuses` | `ModalDropdown` (single control emitting a 1-element list) | `select` — keep the control single; map `value` ↔ `statuses[0]` in `onChange` |
|
|
93
|
+
| `direction` / `currency` | `ModalDropdown` | `select` |
|
|
94
|
+
| `valueDateFrom`/`To`, `minAmount`/`maxAmount`, `sortBy` | latent in types, not yet rendered | add as `dateRange` / two `number` / a `select` when you surface them |
|
|
95
|
+
|
|
96
|
+
- `values` = the current filter; `onChange` = replace-then-`patchFilter` (or adapt `patchFilter` to accept the full map).
|
|
97
|
+
- The pinned/locked-key pattern (approvals' `APPROVALS_FILTER` + `LOCKED_KEYS`) → simply **omit** the locked field from the `fields` array for that screen (the shared bar renders exactly the fields you pass).
|
|
98
|
+
- `BulkApproveBar` → the `actions` slot (it already goes into `FilterBar.actions`).
|
|
99
|
+
- Pager already shared with `pageSizeOptions={[25,50,100]}` (API cap) + `boldNumbers` — unchanged.
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## agora-web — products / orders (LIVE)
|
|
104
|
+
|
|
105
|
+
Today: `ProductsFilters` (text search + category `ModalDropdown`), `OrdersFilters` (status
|
|
106
|
+
`ModalDropdown`); `useProductsQuery`/`useOrdersQuery` set values live and reset page to 1. Already
|
|
107
|
+
uses shared `FilterBar` + `Pager` + `DataTable`.
|
|
108
|
+
|
|
109
|
+
Map (LIVE):
|
|
110
|
+
|
|
111
|
+
| field | → kind |
|
|
112
|
+
|---|---|
|
|
113
|
+
| products `search` | `text` (`grow: true`) |
|
|
114
|
+
| products `categoryId` (sentinel `''`) | `select` |
|
|
115
|
+
| orders `status` (`OrderStatus \| ''`) | `select` (map `'' → undefined` in `onChange`) |
|
|
116
|
+
|
|
117
|
+
- Trivial migration: build the two/one field(s), pass `values` + `onChange`, keep `resultsCount`.
|
|
118
|
+
- Pager unchanged (kit defaults, pills variant).
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
## erevna-web / katalogos-web — menus / users / public menu (LIVE)
|
|
123
|
+
|
|
124
|
+
Today: hand-rolled, using ui-tables **only for `StatCard`** — no `FilterBar`/`Pager`. Several
|
|
125
|
+
distinct surfaces:
|
|
126
|
+
|
|
127
|
+
- **Public-menu filter** (`useMenuFilter`): text-search-with-clear + dietary-tag multi-select
|
|
128
|
+
chips. Map the search to a `text` field; the tag chips are a **multi-select** — not one of the
|
|
129
|
+
six first-class kinds yet. Options for now: keep the bespoke chip row in the `actions`/children,
|
|
130
|
+
OR model each tag as a `boolean` field, OR wait for a `multiSelect` kind (candidate for a
|
|
131
|
+
future minor). The `hasActiveFilters` + `clearAllFilters` contract maps to `onClear`.
|
|
132
|
+
- **Menus admin list** (`MenuTabBar`, `MenuTabFilter` enum All/Active): a single `select`
|
|
133
|
+
(`{All, Active}`) — or keep the tab bar (it is a segmented control, a different UI affordance).
|
|
134
|
+
- **Users list** (`TenantSelector` pills): a `select` of tenants (+ "All Users" = value `''`).
|
|
135
|
+
- **Generic `PaginationControls`** (first/prev/next/last, "Showing a-b of N", "p / total",
|
|
136
|
+
0-based) + `PaginatedList`: replace with `Pager` using `showFirstLast`. Note `Pager` is
|
|
137
|
+
**1-based** — add 1 when mapping from the 0-based `currentPage`. `unitLabelSingular` covers the
|
|
138
|
+
singular the current templates lack.
|
|
139
|
+
- **`VersionHistoryPanel`** "Load More": `Pager` does not do load-more; keep it bespoke, or
|
|
140
|
+
switch that panel to page-based `Pager`.
|
|
141
|
+
- **`BillingHistoryTable`** (server prev/next-only + mobile horizontal-scroll): `Pager` without
|
|
142
|
+
`showFirstLast`; the DataTable card-stack replaces the manual `minWidth:500` scroll wrapper.
|
|
143
|
+
|
|
144
|
+
---
|
|
145
|
+
|
|
146
|
+
## Not yet first-class (candidates for a future minor)
|
|
147
|
+
|
|
148
|
+
Surfaced by the harvest but intentionally out of the initial six kinds — add on real second use:
|
|
149
|
+
|
|
150
|
+
- **`multiSelect`** — zygos `statuses` (list-shaped), erevna dietary-tag chips, katalogos tags.
|
|
151
|
+
- **`sort`** control — zygos `sortBy` + `sortDescending` (in types, no UI yet).
|
|
152
|
+
- **Load-more / infinite pager** — erevna `VersionHistoryPanel` (only one consumer).
|
|
153
|
+
- **"page X of N" position line** — kefi audit's second pager line (the `from–to of N` covers it).
|
|
154
|
+
|
|
155
|
+
---
|
|
156
|
+
|
|
157
|
+
## Pager prop cheatsheet (new in 1.11.0)
|
|
158
|
+
|
|
159
|
+
| Prop | Effect | Adopt where |
|
|
160
|
+
|---|---|---|
|
|
161
|
+
| `showFirstLast` | First/Last jump buttons (disabled at bounds) | erevna `PaginationControls`, any large dataset |
|
|
162
|
+
| `unitLabelSingular` | `1 result` when `total === 1` | anywhere a unit noun is shown |
|
|
163
|
+
| `responsive` + `stackBreakpoint` | compact Prev/Next-only nav below the breakpoint | mobile / narrow surfaces |
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,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
|
-
| `
|
|
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 `
|
|
182
|
-
`analytics.statCardLabel` (provide these
|
|
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
|
|