@dloizides/ui-tables 1.9.2 → 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 +163 -0
- package/CHANGELOG.md +74 -0
- package/README.md +136 -1
- package/dist/index.d.mts +388 -8
- package/dist/index.d.ts +388 -8
- package/dist/index.js +1567 -218
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +1542 -207
- package/dist/index.mjs.map +1 -1
- package/package.json +3 -2
package/dist/index.d.mts
CHANGED
|
@@ -54,6 +54,10 @@ interface DataTableStyleOverrides {
|
|
|
54
54
|
stateText?: StyleProp<TextStyle>;
|
|
55
55
|
/** The full-width detail panel under an expanded row. */
|
|
56
56
|
rowDetail?: StyleProp<ViewStyle>;
|
|
57
|
+
/** The fixed-width checkbox gutter, in the header and in every row. */
|
|
58
|
+
selectCell?: StyleProp<ViewStyle>;
|
|
59
|
+
/** The select-all-matching banner above the header. */
|
|
60
|
+
selectBanner?: StyleProp<ViewStyle>;
|
|
57
61
|
/** A card in the responsive card-stack (below `stackBreakpoint`). */
|
|
58
62
|
card?: StyleProp<ViewStyle>;
|
|
59
63
|
/** One label:value line inside a card. */
|
|
@@ -102,6 +106,59 @@ interface DataTableProps<T> {
|
|
|
102
106
|
* table adds no chevron and keeps no internal expand state.
|
|
103
107
|
*/
|
|
104
108
|
expandedRowKeys?: readonly string[];
|
|
109
|
+
/**
|
|
110
|
+
* Keys (as produced by `keyExtractor`) of the rows currently selected. Selection is
|
|
111
|
+
* CONTROLLED by the caller — the same contract as `expandedRowKeys`: own the state,
|
|
112
|
+
* update it from `onSelectionChange`. The table keeps no internal selection state.
|
|
113
|
+
*
|
|
114
|
+
* Keys the table cannot see (rows on other pages) are preserved, never dropped: the
|
|
115
|
+
* header checkbox only ever adds or removes keys belonging to the CURRENT page.
|
|
116
|
+
*/
|
|
117
|
+
selectedRowKeys?: readonly string[];
|
|
118
|
+
/**
|
|
119
|
+
* **Enables bulk-select** (the way `renderRowDetail` enables expansion): a checkbox
|
|
120
|
+
* gutter appears in the header and in every row. Emits the NEXT selection whenever a row
|
|
121
|
+
* or the header checkbox is toggled. Omit and nothing about the table changes.
|
|
122
|
+
*/
|
|
123
|
+
onSelectionChange?: (selectedRowKeys: readonly string[]) => void;
|
|
124
|
+
/**
|
|
125
|
+
* Total rows matching the CURRENT filter across EVERY page, as reported by the server
|
|
126
|
+
* (the same number the `Pager`'s `total` shows). Enables the "select all N matching this
|
|
127
|
+
* filter" affordance once the whole page is selected and more rows match than fit on it.
|
|
128
|
+
*
|
|
129
|
+
* Omit and bulk-select stays page-scoped.
|
|
130
|
+
*/
|
|
131
|
+
matchingCount?: number;
|
|
132
|
+
/**
|
|
133
|
+
* Whether "every row matching the filter" is selected — **a FLAG, not a set of ids.**
|
|
134
|
+
* CONTROLLED, like `selectedRowKeys`.
|
|
135
|
+
*
|
|
136
|
+
* While set, every row reads as selected without the caller enumerating anything.
|
|
137
|
+
*/
|
|
138
|
+
allMatchingSelected?: boolean;
|
|
139
|
+
/**
|
|
140
|
+
* Emits the select-all-matching **FLAG** (`true` to select all matching, `false` to
|
|
141
|
+
* clear). Enables the banner, together with `matchingCount`.
|
|
142
|
+
*
|
|
143
|
+
* 🔴 The table will NEVER hand you an id list for this. It cannot — the matching rows are
|
|
144
|
+
* on pages it never fetched — and it must not: the ZY-02 spike measured this grid at
|
|
145
|
+
* ~2–3 ms and ~16 DOM nodes per row, so materialising 5,000 selected rows is
|
|
146
|
+
* indistinguishable from an outage. Resolve the flag server-side against the same filter
|
|
147
|
+
* your list endpoint took; the work then survives the operator closing the tab.
|
|
148
|
+
*/
|
|
149
|
+
onSelectAllMatchingChange?: (allMatching: boolean) => void;
|
|
150
|
+
/**
|
|
151
|
+
* Enables keyboard navigation across rows (the ARIA grid roving-tabindex pattern):
|
|
152
|
+
* ArrowUp/ArrowDown move the focused row (clamped — never wrapping), Home/End jump to the
|
|
153
|
+
* first/last row on the page, Space toggles selection (when selectable), and Enter
|
|
154
|
+
* activates the row via the existing `onRowPress`.
|
|
155
|
+
*
|
|
156
|
+
* Default **off**: switching it on gives rows a `tabIndex`, which changes a page's tab
|
|
157
|
+
* order — so an existing table must opt in rather than silently shift under its users.
|
|
158
|
+
*
|
|
159
|
+
* Web-only in effect (focus movement and key events are DOM concerns); inert on native.
|
|
160
|
+
*/
|
|
161
|
+
keyboardNavigation?: boolean;
|
|
105
162
|
loading?: boolean;
|
|
106
163
|
/** Loading text (already translated). Falls back to the kit's `loading` translation. */
|
|
107
164
|
loadingLabel?: string;
|
|
@@ -134,14 +191,26 @@ interface DataTableProps<T> {
|
|
|
134
191
|
* `useWindowDimensions` (the CSS `data-label` card-stack does not port).
|
|
135
192
|
* Pass `stackBreakpoint={0}` to keep the desktop grid at every width.
|
|
136
193
|
* - per-row `testID` + `accessibilityLabel`/`accessibilityHint` (kit standard).
|
|
137
|
-
* - optional CONTROLLED expandable rows: `renderRowDetail` + `expandedRowKeys
|
|
138
|
-
*
|
|
139
|
-
*
|
|
140
|
-
*
|
|
194
|
+
* - optional CONTROLLED expandable rows: `renderRowDetail` + `expandedRowKeys`.
|
|
195
|
+
* - optional CONTROLLED **bulk-select**: `selectedRowKeys` + `onSelectionChange` add a
|
|
196
|
+
* checkbox gutter; `matchingCount` + `onSelectAllMatchingChange` add the "select all N
|
|
197
|
+
* matching this filter" banner, which emits a **FLAG, never an id list**.
|
|
198
|
+
* - optional **keyboard navigation** (`keyboardNavigation`): the ARIA grid roving-tabindex
|
|
199
|
+
* pattern — one tab stop for the whole grid, arrows to move, Space to select, Enter to
|
|
200
|
+
* activate. Off by default: giving rows a `tabIndex` changes a page's tab order.
|
|
141
201
|
* - optional per-slot `styleOverrides`, merged LAST so a consumer that needs to be
|
|
142
|
-
* pixel-perfect beats both the base StyleSheet and the inline theme colour.
|
|
143
|
-
* shared defaults never change for anyone who does not opt in.
|
|
202
|
+
* pixel-perfect beats both the base StyleSheet and the inline theme colour.
|
|
144
203
|
* - every colour from `useUi().theme`; every component-authored string via `t`.
|
|
204
|
+
*
|
|
205
|
+
* **Omit the optional props and the table renders exactly as it always has** — that is the
|
|
206
|
+
* contract every feature here is built to, and what keeps this a MINOR bump.
|
|
207
|
+
*
|
|
208
|
+
* **No virtualization, deliberately** (`zygos/docs/03-zy02-grid-spike.md`): this is a
|
|
209
|
+
* server-paged table — that is what `Pager` and `FilterBar` are for — and paging already
|
|
210
|
+
* buys everything virtualization would, without the surface area.
|
|
211
|
+
*
|
|
212
|
+
* This component is the ORCHESTRATOR: the frame, the state views, the header and the two
|
|
213
|
+
* layout branches. A row's own behaviour lives in `DataTableRow`.
|
|
145
214
|
*/
|
|
146
215
|
|
|
147
216
|
declare function DataTable<T>(props: DataTableProps<T>): React.ReactElement;
|
|
@@ -245,6 +314,26 @@ interface PagerProps {
|
|
|
245
314
|
* count line stays the generic `from–to of N` (byte-identical to prior behaviour).
|
|
246
315
|
*/
|
|
247
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;
|
|
248
337
|
/**
|
|
249
338
|
* Optional, already-translated word prefixed to the count line, e.g. `"Showing"` renders
|
|
250
339
|
* `Showing 1–50 of 3,023 leadership terms`. Omit for the bare `from–to of N` line
|
|
@@ -264,7 +353,7 @@ interface PagerProps {
|
|
|
264
353
|
styleOverrides?: PagerStyleOverrides;
|
|
265
354
|
testID?: string;
|
|
266
355
|
}
|
|
267
|
-
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;
|
|
268
357
|
|
|
269
358
|
/**
|
|
270
359
|
* Shared constants for the DataTable family (DataTable / FilterBar / Pager).
|
|
@@ -283,12 +372,22 @@ declare const TABLE_TEST_IDS: {
|
|
|
283
372
|
readonly rowInfix: "row";
|
|
284
373
|
/** Infix of an expanded row's detail panel: `${tableTestID}-row-detail-${key}`. */
|
|
285
374
|
readonly rowDetailInfix: "row-detail";
|
|
375
|
+
/** Infix of a row's select checkbox: `${tableTestID}-select-${key}`. */
|
|
376
|
+
readonly rowSelectInfix: "select";
|
|
377
|
+
/** Suffix of the header (select-all-on-page) checkbox: `${tableTestID}-select-all`. */
|
|
378
|
+
readonly selectAllSuffix: "select-all";
|
|
379
|
+
/** Suffix of the select-all-matching banner: `${tableTestID}-select-banner`. */
|
|
380
|
+
readonly selectBannerSuffix: "select-banner";
|
|
381
|
+
/** Suffix of the banner's action: `${tableTestID}-select-banner-action`. */
|
|
382
|
+
readonly selectBannerActionSuffix: "select-banner-action";
|
|
286
383
|
readonly filterBar: "ui-filters";
|
|
287
384
|
readonly results: "ui-results";
|
|
288
385
|
readonly pager: "ui-pager";
|
|
289
386
|
readonly pagerInfo: "ui-pager-info";
|
|
387
|
+
readonly pagerFirst: "ui-pager-first";
|
|
290
388
|
readonly pagerPrev: "ui-pager-prev";
|
|
291
389
|
readonly pagerNext: "ui-pager-next";
|
|
390
|
+
readonly pagerLast: "ui-pager-last";
|
|
292
391
|
};
|
|
293
392
|
/** The test id of a row: `${tableTestID}-row-${key}` (key from `keyExtractor`). */
|
|
294
393
|
declare const rowTestID: (tableTestID: string, key: string) => string;
|
|
@@ -298,6 +397,14 @@ declare const rowTestID: (tableTestID: string, key: string) => string;
|
|
|
298
397
|
* consumers and e2e specs target the panel without re-deriving the shape.
|
|
299
398
|
*/
|
|
300
399
|
declare const rowDetailTestID: (tableTestID: string, key: string) => string;
|
|
400
|
+
/**
|
|
401
|
+
* The test id of a row's select checkbox: `${tableTestID}-select-${key}` (key from
|
|
402
|
+
* `keyExtractor`). Exported so consumers and e2e specs target a row's checkbox without
|
|
403
|
+
* re-deriving the shape.
|
|
404
|
+
*/
|
|
405
|
+
declare const rowSelectTestID: (tableTestID: string, key: string) => string;
|
|
406
|
+
/** The test id of the header (select-all-on-page) checkbox: `${tableTestID}-select-all`. */
|
|
407
|
+
declare const selectAllTestID: (tableTestID: string) => string;
|
|
301
408
|
/**
|
|
302
409
|
* Translation keys for every component-authored, user-facing string. Apps map
|
|
303
410
|
* these in their UiProvider `t` (FM); the neutral default `t` returns the key, so
|
|
@@ -310,16 +417,289 @@ declare const TABLE_I18N: {
|
|
|
310
417
|
readonly rowHint: "uiTables.rowHint";
|
|
311
418
|
/** Accessible name of the full-width detail panel under an expanded row. */
|
|
312
419
|
readonly rowDetail: "uiTables.rowDetail";
|
|
420
|
+
/** Accessible name of a row's select checkbox. */
|
|
421
|
+
readonly selectRow: "uiTables.select.row";
|
|
422
|
+
readonly selectRowHint: "uiTables.select.rowHint";
|
|
423
|
+
/** Accessible name of the header (select-all-on-page) checkbox. */
|
|
424
|
+
readonly selectAll: "uiTables.select.all";
|
|
425
|
+
readonly selectAllHint: "uiTables.select.allHint";
|
|
426
|
+
/** Banner, offer state: "All {{p1}} rows on this page are selected." */
|
|
427
|
+
readonly selectPageSelected: "uiTables.select.pageSelected";
|
|
428
|
+
/** Banner, offer action: "Select all {{p1}} matching this filter". */
|
|
429
|
+
readonly selectAllMatching: "uiTables.select.allMatching";
|
|
430
|
+
readonly selectAllMatchingHint: "uiTables.select.allMatchingHint";
|
|
431
|
+
/** Banner, active state: "All {{p1}} rows matching this filter are selected." */
|
|
432
|
+
readonly selectMatchingSelected: "uiTables.select.matchingSelected";
|
|
433
|
+
/** Banner, active action: "Clear selection". */
|
|
434
|
+
readonly selectClear: "uiTables.select.clear";
|
|
435
|
+
readonly selectClearHint: "uiTables.select.clearHint";
|
|
313
436
|
readonly results: "uiTables.results";
|
|
314
437
|
readonly pagerInfo: "uiTables.pager.info";
|
|
438
|
+
readonly pagerFirst: "uiTables.pager.first";
|
|
315
439
|
readonly pagerPrev: "uiTables.pager.prev";
|
|
316
440
|
readonly pagerNext: "uiTables.pager.next";
|
|
441
|
+
readonly pagerLast: "uiTables.pager.last";
|
|
442
|
+
readonly pagerFirstHint: "uiTables.pager.firstHint";
|
|
317
443
|
readonly pagerPrevHint: "uiTables.pager.prevHint";
|
|
318
444
|
readonly pagerNextHint: "uiTables.pager.nextHint";
|
|
445
|
+
readonly pagerLastHint: "uiTables.pager.lastHint";
|
|
319
446
|
readonly pagerRows: "uiTables.pager.rows";
|
|
320
447
|
readonly pagerRowsOptionHint: "uiTables.pager.rowsOptionHint";
|
|
321
448
|
/** Accessible hint for the dropdown-variant rows-per-page trigger button. */
|
|
322
449
|
readonly pagerRowsTriggerHint: "uiTables.pager.rowsTriggerHint";
|
|
323
450
|
};
|
|
324
451
|
|
|
325
|
-
|
|
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 };
|