@dloizides/ui-tables 1.10.0 → 1.11.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/ADOPTION.md 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,34 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.11.0
4
+
5
+ Additive: a **declarative `Filters` bar** + **Pager** enhancements. Every change is additive and
6
+ backward compatible — existing `FilterBar` / `Pager` / `DataTable` consumers (aml-v2, agora,
7
+ zygos, kefi, erevna, katalogos) are untouched and every new prop is optional, so a MINOR bump.
8
+ No app is migrated by this release; adoption is a later wave (see `ADOPTION.md`).
9
+
10
+ - **`Filters`** — the declarative, configurable filter bar built ON the existing `FilterBar`
11
+ shell (reusing its live results count + WCAG live region + actions slot). A caller passes a
12
+ `fields` schema — the SUPERSET harvested from every portal's hand-rolled filters — of kinds
13
+ `select` / `text` / `number` / `dateRange` / `typeahead` / `boolean`, plus a value map and
14
+ `onChange`. Two value models: **LIVE** (edits apply immediately — agora, zygos) and
15
+ **DRAFT/APPLY** (edits accumulate in a draft, an Apply button + Enter-in-a-field commit it —
16
+ aml, kefi audit), the latter driven by the new `useFilterDraft` hook. Customisation is style
17
+ (theme) + slots only: every label/option/placeholder/error is a pre-localized string; no
18
+ FM/router/store. Apps can inject `@dloizides/ui-layout`'s `ModalDropdown` for the `select`
19
+ field via `renderSelect` (the in-tree dropdown is the dependency-free default).
20
+ - **`useFilterDraft`** — the draft-vs-applied state engine (draft + committed + `apply` / `reset`
21
+ / `setField` / `dirty`), with `onApply` / `onReset` callbacks the caller wires to `setPage(1)`
22
+ (the universal reset-to-page-1-on-narrowing invariant, kept free of pagination coupling).
23
+ - **`suggestOptions` / `isUnmatched`** — the ranked substring matcher behind the `typeahead`
24
+ field (generalized from aml's `suggestCountries`), exported for reuse.
25
+ - **`Pager`** — three additive props reconciling the variants across apps: `showFirstLast`
26
+ (First/Last jump buttons, disabled at bounds — erevna's `PaginationControls`),
27
+ `unitLabelSingular` (renders `1 result` when `total === 1` — the singularisation apps did in
28
+ the FilterBar noun), and `responsive` + `stackBreakpoint` (collapse to a compact
29
+ Prev/Next-only nav below the breakpoint — the mobile fallback, mirroring the DataTable
30
+ card-stack). New pager test ids `ui-pager-first` / `ui-pager-last`.
31
+
3
32
  ## 1.10.0
4
33
 
5
34
  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
package/dist/index.d.mts CHANGED
@@ -314,6 +314,26 @@ interface PagerProps {
314
314
  * count line stays the generic `from–to of N` (byte-identical to prior behaviour).
315
315
  */
316
316
  unitLabel?: string;
317
+ /**
318
+ * Optional, already-translated SINGULAR unit noun, used in place of `unitLabel` when
319
+ * `total === 1` (e.g. `unitLabel="results"` + `unitLabelSingular="result"` → `1–1 of 1 result`).
320
+ * Ignored unless `unitLabel` is also set; when omitted, `unitLabel` is used at every count.
321
+ */
322
+ unitLabelSingular?: string;
323
+ /**
324
+ * Render First / Last jump buttons flanking Prev / Next (reconciling erevna's
325
+ * `PaginationControls`). Off by default (byte-identical to prior behaviour) — the two
326
+ * buttons only appear when explicitly enabled.
327
+ */
328
+ showFirstLast?: boolean;
329
+ /**
330
+ * Collapse to a compact, mobile-friendly nav below `stackBreakpoint`: the rows-per-page
331
+ * control and the First/Last jumps are hidden, leaving Prev / Next + the count line. Off by
332
+ * default (byte-identical). Auto-driven by the window width, mirroring the DataTable card-stack.
333
+ */
334
+ responsive?: boolean;
335
+ /** Width (px) below which `responsive` collapses to the compact nav. Default 640 (shared with DataTable). */
336
+ stackBreakpoint?: number;
317
337
  /**
318
338
  * Optional, already-translated word prefixed to the count line, e.g. `"Showing"` renders
319
339
  * `Showing 1–50 of 3,023 leadership terms`. Omit for the bare `from–to of N` line
@@ -333,7 +353,7 @@ interface PagerProps {
333
353
  styleOverrides?: PagerStyleOverrides;
334
354
  testID?: string;
335
355
  }
336
- declare function Pager({ page, pageSize, total, onPageChange, onPageSizeChange, pageSizeOptions, rowsVariant, unitLabel, infoPrefix, boldNumbers, styleOverrides: o, testID, }: PagerProps): React.ReactElement;
356
+ declare function Pager({ page, pageSize, total, onPageChange, onPageSizeChange, pageSizeOptions, rowsVariant, unitLabel, unitLabelSingular, showFirstLast, responsive, stackBreakpoint, infoPrefix, boldNumbers, styleOverrides: o, testID, }: PagerProps): React.ReactElement;
337
357
 
338
358
  /**
339
359
  * Shared constants for the DataTable family (DataTable / FilterBar / Pager).
@@ -364,8 +384,10 @@ declare const TABLE_TEST_IDS: {
364
384
  readonly results: "ui-results";
365
385
  readonly pager: "ui-pager";
366
386
  readonly pagerInfo: "ui-pager-info";
387
+ readonly pagerFirst: "ui-pager-first";
367
388
  readonly pagerPrev: "ui-pager-prev";
368
389
  readonly pagerNext: "ui-pager-next";
390
+ readonly pagerLast: "ui-pager-last";
369
391
  };
370
392
  /** The test id of a row: `${tableTestID}-row-${key}` (key from `keyExtractor`). */
371
393
  declare const rowTestID: (tableTestID: string, key: string) => string;
@@ -413,14 +435,271 @@ declare const TABLE_I18N: {
413
435
  readonly selectClearHint: "uiTables.select.clearHint";
414
436
  readonly results: "uiTables.results";
415
437
  readonly pagerInfo: "uiTables.pager.info";
438
+ readonly pagerFirst: "uiTables.pager.first";
416
439
  readonly pagerPrev: "uiTables.pager.prev";
417
440
  readonly pagerNext: "uiTables.pager.next";
441
+ readonly pagerLast: "uiTables.pager.last";
442
+ readonly pagerFirstHint: "uiTables.pager.firstHint";
418
443
  readonly pagerPrevHint: "uiTables.pager.prevHint";
419
444
  readonly pagerNextHint: "uiTables.pager.nextHint";
445
+ readonly pagerLastHint: "uiTables.pager.lastHint";
420
446
  readonly pagerRows: "uiTables.pager.rows";
421
447
  readonly pagerRowsOptionHint: "uiTables.pager.rowsOptionHint";
422
448
  /** Accessible hint for the dropdown-variant rows-per-page trigger button. */
423
449
  readonly pagerRowsTriggerHint: "uiTables.pager.rowsTriggerHint";
424
450
  };
425
451
 
426
- export { CARD_STACK_BREAKPOINT, DEFAULT_PAGE_SIZE_OPTIONS, DataTable, type DataTableColumn, type DataTableProps, type DataTableStyleOverrides, FilterBar, type FilterBarProps, type FilterBarStyleOverrides, Pager, type PagerProps, type PagerStyleOverrides, StatCard, type StatCardProps, TABLE_I18N, TABLE_TEST_IDS, rowDetailTestID, rowSelectTestID, rowTestID, selectAllTestID };
452
+ /**
453
+ * Declarative filter schema for the shared {@link Filters} bar. A consuming screen
454
+ * describes its filters as data — an array of {@link FilterField} — and the bar renders
455
+ * the SAME structure + behaviour everywhere; only the theme colours change per app.
456
+ *
457
+ * The capability set is the SUPERSET harvested from every portal's hand-rolled filters
458
+ * (aml-v2 cases/leaders/peps, zygos instructions, agora products/orders, kefi audit,
459
+ * erevna/katalogos menus): select/enum, free-text search, numeric, date-range, a
460
+ * search-as-you-type typeahead (the country-picker), and a boolean switch.
461
+ *
462
+ * Contract discipline: every user-facing string (labels, placeholders, option labels,
463
+ * error text) is a PRE-LOCALIZED string passed in by the caller — the package never
464
+ * calls FM/i18n for content and never touches a router or store.
465
+ */
466
+
467
+ /** The kinds of field the declarative bar can render. */
468
+ type FilterFieldKind = 'select' | 'text' | 'number' | 'dateRange' | 'typeahead' | 'boolean';
469
+ /** A single choice for a `select` / `typeahead` field. Label is pre-localized. */
470
+ interface FilterOption {
471
+ readonly label: string;
472
+ readonly value: string;
473
+ }
474
+ /** The inclusive from/to value of a `dateRange` field (each an ISO `YYYY-MM-DD` string, or ''). */
475
+ interface DateRangeValue {
476
+ readonly from: string;
477
+ readonly to: string;
478
+ }
479
+ /** The runtime value a field holds, by kind. */
480
+ type FilterValue = string | boolean | DateRangeValue;
481
+ /** The applied/draft value map, keyed by each field's `key`. */
482
+ type FilterValues = Record<string, FilterValue>;
483
+ interface FilterFieldBase {
484
+ /** Stable id — the key into {@link FilterValues} AND the field's testID infix. */
485
+ key: string;
486
+ /** Pre-localized field label rendered above the control. */
487
+ label: string;
488
+ /** Override the derived testID (`${barTestID}-field-${key}` by default). */
489
+ testID?: string;
490
+ /** Let the field grow to fill spare width (search boxes usually do). Default false. */
491
+ grow?: boolean;
492
+ /** Minimum width (px) before the field wraps to the next line. Sensible per-kind default. */
493
+ minWidth?: number;
494
+ /** Merged LAST onto the field's wrapper — the consumer always wins over the shared style. */
495
+ style?: StyleProp<ViewStyle>;
496
+ /** Pre-localized accessibility hint for the field's primary control. */
497
+ accessibilityHint?: string;
498
+ }
499
+ /** A single-select enum/status dropdown. `value` is the chosen option's `value` (''=unset). */
500
+ interface SelectFilterField extends FilterFieldBase {
501
+ kind: 'select';
502
+ options: readonly FilterOption[];
503
+ /** Pre-localized text shown when the value matches no option (unset). */
504
+ placeholder?: string;
505
+ }
506
+ /** A free-text search input. Submits (Enter) trigger the bar's `onSubmit` (Apply). */
507
+ interface TextFilterField extends FilterFieldBase {
508
+ kind: 'text';
509
+ placeholder?: string;
510
+ }
511
+ /** A numeric text input (`keyboardType="numeric"`). Value stays a string (''=unset). */
512
+ interface NumberFilterField extends FilterFieldBase {
513
+ kind: 'number';
514
+ placeholder?: string;
515
+ }
516
+ /** An inclusive from/to date range (two `YYYY-MM-DD` inputs). */
517
+ interface DateRangeFilterField extends FilterFieldBase {
518
+ kind: 'dateRange';
519
+ /** Pre-localized sub-label for the FROM input (e.g. "From"). */
520
+ fromLabel?: string;
521
+ /** Pre-localized sub-label for the TO input (e.g. "To"). */
522
+ toLabel?: string;
523
+ fromPlaceholder?: string;
524
+ toPlaceholder?: string;
525
+ }
526
+ /** A search-as-you-type combobox (the country-picker pattern). */
527
+ interface TypeaheadFilterField extends FilterFieldBase {
528
+ kind: 'typeahead';
529
+ options: readonly FilterOption[];
530
+ placeholder?: string;
531
+ /** Minimum characters before suggestions surface. Default 1. */
532
+ minChars?: number;
533
+ /** Cap on rendered suggestions. Default 8. */
534
+ maxSuggestions?: number;
535
+ /** Pre-localized inline error (e.g. "Unrecognised country"). Shows a persistent banner. */
536
+ error?: string;
537
+ }
538
+ /** A boolean toggle (RN `Switch`). */
539
+ interface BooleanFilterField extends FilterFieldBase {
540
+ kind: 'boolean';
541
+ }
542
+ /** The discriminated union of every declarative filter field. */
543
+ type FilterField = SelectFilterField | TextFilterField | NumberFilterField | DateRangeFilterField | TypeaheadFilterField | BooleanFilterField;
544
+
545
+ /**
546
+ * FilterFieldView — dispatches one {@link FilterField} to its renderer, wired to the value map.
547
+ * Reads the field's typed value out of {@link FilterValues} (coercing a missing/mismatched
548
+ * entry to that kind's empty value) and writes edits back via `setField`. `boolean` renders its
549
+ * own inline switch-row; every other kind is wrapped in the label-over-control {@link FieldShell}.
550
+ */
551
+
552
+ /** Resolved, pre-localized strings the bar passes down to every field. */
553
+ interface FieldStrings {
554
+ selectPlaceholder: string;
555
+ dropdownHint: string;
556
+ optionHint: string;
557
+ fromLabel: string;
558
+ toLabel: string;
559
+ }
560
+ /**
561
+ * Args for a custom select renderer — the injection point apps use to swap the built-in
562
+ * in-tree dropdown for `@dloizides/ui-layout`'s responsive ModalDropdown (modal on mobile /
563
+ * native, inline menu on desktop). The label wrapper (FieldShell) is still supplied by the bar.
564
+ */
565
+ interface RenderSelectArgs {
566
+ field: SelectFilterField;
567
+ value: string;
568
+ onChange: (value: string) => void;
569
+ /** The field's canonical testID (`${barTestID}-field-${key}` unless overridden). */
570
+ testID: string;
571
+ }
572
+
573
+ /**
574
+ * Filters — the declarative, configurable filter bar every portal shares. A caller passes a
575
+ * `fields` schema + a `values` map + `onChange`; the bar renders the same structure + behaviour
576
+ * everywhere, themed per app. It builds ON the existing {@link FilterBar} shell (so its live
577
+ * results count + WCAG live region + actions slot are reused unchanged).
578
+ *
579
+ * Two value models, selected by whether `onApply` is passed:
580
+ * - LIVE (no `onApply`): each edit calls `onChange` immediately (agora, zygos). No Apply button.
581
+ * - DRAFT/APPLY (`onApply` set): edits accumulate in the caller's draft (see {@link useFilterDraft});
582
+ * an Apply button + Enter-in-a-field commit it (aml, kefi audit). Pass `onClear` for a Reset.
583
+ *
584
+ * Contract discipline: every user-facing string is a pre-localized value — supplied per-field, via
585
+ * the `*Label`/`*Placeholder` props, or resolved through the UiProvider `t` (which defaults to the
586
+ * i18n KEY, never a hardcoded literal). No FM/router/store; customisation is style + slots only.
587
+ */
588
+
589
+ interface FiltersProps {
590
+ /** The declarative field schema — the SUPERSET of every portal's filters, as data. */
591
+ fields: readonly FilterField[];
592
+ /** The current value map (applied values in live mode, or the draft in draft/apply mode). */
593
+ values: FilterValues;
594
+ /** Called with the next full value map on every edit. */
595
+ onChange: (next: FilterValues) => void;
596
+ /** Live results count shown by the FilterBar (WCAG live region). Omit to hide. */
597
+ resultsCount?: number;
598
+ /** Pre-localized noun for the count (already singularised by the caller if needed). */
599
+ resultsLabel?: string;
600
+ /** When set, shows an Apply button + commits on Enter — the draft/apply model. Omit for live. */
601
+ onApply?: () => void;
602
+ /** Pre-localized Apply label / hint (default via UiProvider `t`). */
603
+ applyLabel?: string;
604
+ applyHint?: string;
605
+ /** Disable Apply (e.g. while busy or when a date field is invalid — aml's gate). */
606
+ applyDisabled?: boolean;
607
+ /** When set, shows a Clear/Reset button. */
608
+ onClear?: () => void;
609
+ clearLabel?: string;
610
+ clearHint?: string;
611
+ /** Extra actions (Export CSV/PDF, bulk bar) rendered BEFORE the built-in Apply/Clear. */
612
+ actions?: React.ReactNode;
613
+ /** Pre-localized fallback placeholder for an unset select (default via `t`). */
614
+ selectPlaceholder?: string;
615
+ /** Pre-localized default sub-labels for date-range fields (default via `t`). */
616
+ fromLabel?: string;
617
+ toLabel?: string;
618
+ /**
619
+ * Optional custom renderer for `select` fields — the injection point for
620
+ * `@dloizides/ui-layout`'s responsive `ModalDropdown` (or any other select). When omitted, the
621
+ * dependency-free in-tree dropdown is used. The label wrapper stays supplied by the bar.
622
+ */
623
+ renderSelect?: (args: RenderSelectArgs) => React.ReactNode;
624
+ /** FilterBar per-slot style overrides — merged LAST, so a consumer always wins. */
625
+ styleOverrides?: FilterBarStyleOverrides;
626
+ testID?: string;
627
+ }
628
+ declare function Filters({ fields, values, onChange, resultsCount, resultsLabel, onApply, applyLabel, applyHint, applyDisabled, onClear, clearLabel, clearHint, actions, selectPlaceholder, fromLabel, toLabel, renderSelect, styleOverrides, testID, }: FiltersProps): React.ReactElement;
629
+
630
+ interface UseFilterDraftOptions<V extends FilterValues> {
631
+ /** The initial (and reset target) value — the "all filters cleared" state. */
632
+ initial: V;
633
+ /** Fired when a draft is committed. Wire your `setPage(1)` + query refresh here. */
634
+ onApply?: (committed: V) => void;
635
+ /** Fired when the draft + committed are reset to `initial` (e.g. clear an inline error). */
636
+ onReset?: () => void;
637
+ }
638
+ interface FilterDraft<V extends FilterValues> {
639
+ /** The live, uncommitted value the bar edits. */
640
+ draft: V;
641
+ /** The committed value the query reads. */
642
+ committed: V;
643
+ /** Patch one field of the draft (merge, like aml's per-bar `set`). */
644
+ setField: (key: string, value: FilterValue) => void;
645
+ /** Replace the whole draft (the bar's `onChange`). */
646
+ setDraft: (next: V) => void;
647
+ /** Commit the draft → committed and fire `onApply`. */
648
+ apply: () => void;
649
+ /** Reset draft + committed to `initial` and fire `onReset`. */
650
+ reset: () => void;
651
+ /** True when the draft differs from the committed value (an Apply would change the result). */
652
+ dirty: boolean;
653
+ }
654
+ declare function useFilterDraft<V extends FilterValues>({ initial, onApply, onReset }: UseFilterDraftOptions<V>): FilterDraft<V>;
655
+
656
+ /**
657
+ * suggestOptions — the ranked substring matcher behind the `typeahead` field, generalized
658
+ * from aml-v2's `suggestCountries`. Ranks: value exact (0) > value prefix (1) > label prefix
659
+ * (2) > label contains (3); ties broken by `label.localeCompare`. Empty/short queries return
660
+ * `[]` (nothing surfaces until `minChars` is typed, mirroring a native `<datalist>`).
661
+ */
662
+
663
+ /**
664
+ * Rank + cap the options matching `query`. Returns `[]` until `query` (trimmed) is at least
665
+ * `minChars` long, then the best `limit` matches, ranked as documented above.
666
+ */
667
+ declare function suggestOptions(options: readonly FilterOption[], query: string, minChars: number, limit: number): readonly FilterOption[];
668
+ /** True when `text` is non-empty yet matches no option's value or label exactly (case-insensitive). */
669
+ declare function isUnmatched(options: readonly FilterOption[], text: string): boolean;
670
+
671
+ /**
672
+ * Constants for the declarative Filters bar — every test id, i18n key and layout number in
673
+ * one place so the components carry no magic numbers and no ad-hoc strings.
674
+ */
675
+
676
+ /** Root testID of the declarative filter bar. */
677
+ declare const FILTERS_TEST_ID = "ui-filters-declarative";
678
+ /** Default minimum widths (px) per field kind before it wraps. */
679
+ declare const FIELD_MIN_WIDTH: Record<FilterFieldKind, number>;
680
+ /** Default min characters before a typeahead surfaces suggestions. */
681
+ declare const DEFAULT_TYPEAHEAD_MIN_CHARS = 1;
682
+ /** Default cap on typeahead suggestions rendered. */
683
+ declare const DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS = 8;
684
+ /** Derived testIDs for the declarative bar. */
685
+ declare const fieldTestID: (barTestID: string, key: string) => string;
686
+ declare const applyTestID: (barTestID: string) => string;
687
+ declare const clearTestID: (barTestID: string) => string;
688
+ /**
689
+ * Translation keys for the bar's own controls. Apps map these in their UiProvider `t`; the
690
+ * neutral default `t` returns the key, so a forgotten key degrades to the key, never a literal.
691
+ * A caller may also override any of them with a pre-localized string prop on {@link Filters}.
692
+ */
693
+ declare const FILTERS_I18N: {
694
+ readonly apply: "uiTables.filters.apply";
695
+ readonly applyHint: "uiTables.filters.applyHint";
696
+ readonly clear: "uiTables.filters.clear";
697
+ readonly clearHint: "uiTables.filters.clearHint";
698
+ readonly selectPlaceholder: "uiTables.filters.selectPlaceholder";
699
+ readonly dropdownHint: "uiTables.filters.dropdownHint";
700
+ readonly optionHint: "uiTables.filters.optionHint";
701
+ readonly from: "uiTables.filters.from";
702
+ readonly to: "uiTables.filters.to";
703
+ };
704
+
705
+ export { type BooleanFilterField, CARD_STACK_BREAKPOINT, DEFAULT_PAGE_SIZE_OPTIONS, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DataTable, type DataTableColumn, type DataTableProps, type DataTableStyleOverrides, type DateRangeFilterField, type DateRangeValue, FIELD_MIN_WIDTH, FILTERS_I18N, FILTERS_TEST_ID, type FieldStrings, FilterBar, type FilterBarProps, type FilterBarStyleOverrides, type FilterDraft, type FilterField, type FilterFieldKind, type FilterOption, type FilterValue, type FilterValues, Filters, type FiltersProps, type NumberFilterField, Pager, type PagerProps, type PagerStyleOverrides, type RenderSelectArgs, type SelectFilterField, StatCard, type StatCardProps, TABLE_I18N, TABLE_TEST_IDS, type TextFilterField, type TypeaheadFilterField, type UseFilterDraftOptions, applyTestID, clearTestID, fieldTestID, isUnmatched, rowDetailTestID, rowSelectTestID, rowTestID, selectAllTestID, suggestOptions, useFilterDraft };