@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/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,298 @@ 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";
450
+ /**
451
+ * Accessible NAME of the rows-per-page control, e.g. "Rows per page, currently {{p1}}".
452
+ * Without it the control is announced as the bare number ("50"), which says nothing about
453
+ * what it does. Untranslated it degrades to that bare number — never to the raw key.
454
+ */
455
+ readonly pagerRowsTriggerLabel: "uiTables.pager.rowsTriggerLabel";
456
+ /**
457
+ * Accessible NAME of ONE rows-per-page choice, e.g. "Show {{p1}} rows per page". Used by
458
+ * BOTH the `dropdown` options and the default `pills`. Untranslated it degrades to the
459
+ * bare number — never to the raw key.
460
+ */
461
+ readonly pagerRowsOptionLabel: "uiTables.pager.rowsOptionLabel";
462
+ /**
463
+ * StatCard's accessible name, e.g. "{{p1}}: {{p2}}". Note the `analytics.` prefix: these
464
+ * two keys predate this map and were only ever inlined in StatCard.tsx, so apps deriving
465
+ * their required-key list from TABLE_I18N could not see them. Registered here UNCHANGED
466
+ * (renaming them would break every app that already defines them).
467
+ */
468
+ readonly statCardLabel: "analytics.statCardLabel";
469
+ readonly statHint: "analytics.statHint";
470
+ };
471
+
472
+ /**
473
+ * Declarative filter schema for the shared {@link Filters} bar. A consuming screen
474
+ * describes its filters as data — an array of {@link FilterField} — and the bar renders
475
+ * the SAME structure + behaviour everywhere; only the theme colours change per app.
476
+ *
477
+ * The capability set is the SUPERSET harvested from every portal's hand-rolled filters
478
+ * (aml-v2 cases/leaders/peps, zygos instructions, agora products/orders, kefi audit,
479
+ * erevna/katalogos menus): select/enum, free-text search, numeric, date-range, a
480
+ * search-as-you-type typeahead (the country-picker), and a boolean switch.
481
+ *
482
+ * Contract discipline: every user-facing string (labels, placeholders, option labels,
483
+ * error text) is a PRE-LOCALIZED string passed in by the caller — the package never
484
+ * calls FM/i18n for content and never touches a router or store.
485
+ */
486
+
487
+ /** The kinds of field the declarative bar can render. */
488
+ type FilterFieldKind = 'select' | 'text' | 'number' | 'dateRange' | 'typeahead' | 'boolean';
489
+ /** A single choice for a `select` / `typeahead` field. Label is pre-localized. */
490
+ interface FilterOption {
491
+ readonly label: string;
492
+ readonly value: string;
493
+ }
494
+ /** The inclusive from/to value of a `dateRange` field (each an ISO `YYYY-MM-DD` string, or ''). */
495
+ interface DateRangeValue {
496
+ readonly from: string;
497
+ readonly to: string;
498
+ }
499
+ /** The runtime value a field holds, by kind. */
500
+ type FilterValue = string | boolean | DateRangeValue;
501
+ /** The applied/draft value map, keyed by each field's `key`. */
502
+ type FilterValues = Record<string, FilterValue>;
503
+ interface FilterFieldBase {
504
+ /** Stable id — the key into {@link FilterValues} AND the field's testID infix. */
505
+ key: string;
506
+ /** Pre-localized field label rendered above the control. */
507
+ label: string;
508
+ /** Override the derived testID (`${barTestID}-field-${key}` by default). */
509
+ testID?: string;
510
+ /** Let the field grow to fill spare width (search boxes usually do). Default false. */
511
+ grow?: boolean;
512
+ /** Minimum width (px) before the field wraps to the next line. Sensible per-kind default. */
513
+ minWidth?: number;
514
+ /** Merged LAST onto the field's wrapper — the consumer always wins over the shared style. */
515
+ style?: StyleProp<ViewStyle>;
516
+ /** Pre-localized accessibility hint for the field's primary control. */
517
+ accessibilityHint?: string;
518
+ }
519
+ /** A single-select enum/status dropdown. `value` is the chosen option's `value` (''=unset). */
520
+ interface SelectFilterField extends FilterFieldBase {
521
+ kind: 'select';
522
+ options: readonly FilterOption[];
523
+ /** Pre-localized text shown when the value matches no option (unset). */
524
+ placeholder?: string;
525
+ }
526
+ /** A free-text search input. Submits (Enter) trigger the bar's `onSubmit` (Apply). */
527
+ interface TextFilterField extends FilterFieldBase {
528
+ kind: 'text';
529
+ placeholder?: string;
530
+ }
531
+ /** A numeric text input (`keyboardType="numeric"`). Value stays a string (''=unset). */
532
+ interface NumberFilterField extends FilterFieldBase {
533
+ kind: 'number';
534
+ placeholder?: string;
535
+ }
536
+ /** An inclusive from/to date range (two `YYYY-MM-DD` inputs). */
537
+ interface DateRangeFilterField extends FilterFieldBase {
538
+ kind: 'dateRange';
539
+ /** Pre-localized sub-label for the FROM input (e.g. "From"). */
540
+ fromLabel?: string;
541
+ /** Pre-localized sub-label for the TO input (e.g. "To"). */
542
+ toLabel?: string;
543
+ fromPlaceholder?: string;
544
+ toPlaceholder?: string;
545
+ }
546
+ /** A search-as-you-type combobox (the country-picker pattern). */
547
+ interface TypeaheadFilterField extends FilterFieldBase {
548
+ kind: 'typeahead';
549
+ options: readonly FilterOption[];
550
+ placeholder?: string;
551
+ /** Minimum characters before suggestions surface. Default 1. */
552
+ minChars?: number;
553
+ /** Cap on rendered suggestions. Default 8. */
554
+ maxSuggestions?: number;
555
+ /** Pre-localized inline error (e.g. "Unrecognised country"). Shows a persistent banner. */
556
+ error?: string;
557
+ }
558
+ /** A boolean toggle (RN `Switch`). */
559
+ interface BooleanFilterField extends FilterFieldBase {
560
+ kind: 'boolean';
561
+ }
562
+ /** The discriminated union of every declarative filter field. */
563
+ type FilterField = SelectFilterField | TextFilterField | NumberFilterField | DateRangeFilterField | TypeaheadFilterField | BooleanFilterField;
564
+
565
+ /**
566
+ * FilterFieldView — dispatches one {@link FilterField} to its renderer, wired to the value map.
567
+ * Reads the field's typed value out of {@link FilterValues} (coercing a missing/mismatched
568
+ * entry to that kind's empty value) and writes edits back via `setField`. `boolean` renders its
569
+ * own inline switch-row; every other kind is wrapped in the label-over-control {@link FieldShell}.
570
+ */
571
+
572
+ /** Resolved, pre-localized strings the bar passes down to every field. */
573
+ interface FieldStrings {
574
+ selectPlaceholder: string;
575
+ dropdownHint: string;
576
+ optionHint: string;
577
+ fromLabel: string;
578
+ toLabel: string;
579
+ }
580
+ /**
581
+ * Args for a custom select renderer — the injection point apps use to swap the built-in
582
+ * in-tree dropdown for `@dloizides/ui-layout`'s responsive ModalDropdown (modal on mobile /
583
+ * native, inline menu on desktop). The label wrapper (FieldShell) is still supplied by the bar.
584
+ */
585
+ interface RenderSelectArgs {
586
+ field: SelectFilterField;
587
+ value: string;
588
+ onChange: (value: string) => void;
589
+ /** The field's canonical testID (`${barTestID}-field-${key}` unless overridden). */
590
+ testID: string;
591
+ }
592
+
593
+ /**
594
+ * Filters — the declarative, configurable filter bar every portal shares. A caller passes a
595
+ * `fields` schema + a `values` map + `onChange`; the bar renders the same structure + behaviour
596
+ * everywhere, themed per app. It builds ON the existing {@link FilterBar} shell (so its live
597
+ * results count + WCAG live region + actions slot are reused unchanged).
598
+ *
599
+ * Two value models, selected by whether `onApply` is passed:
600
+ * - LIVE (no `onApply`): each edit calls `onChange` immediately (agora, zygos). No Apply button.
601
+ * - DRAFT/APPLY (`onApply` set): edits accumulate in the caller's draft (see {@link useFilterDraft});
602
+ * an Apply button + Enter-in-a-field commit it (aml, kefi audit). Pass `onClear` for a Reset.
603
+ *
604
+ * Contract discipline: every user-facing string is a pre-localized value — supplied per-field, via
605
+ * the `*Label`/`*Placeholder` props, or resolved through the UiProvider `t` (which defaults to the
606
+ * i18n KEY, never a hardcoded literal). No FM/router/store; customisation is style + slots only.
607
+ */
608
+
609
+ interface FiltersProps {
610
+ /** The declarative field schema — the SUPERSET of every portal's filters, as data. */
611
+ fields: readonly FilterField[];
612
+ /** The current value map (applied values in live mode, or the draft in draft/apply mode). */
613
+ values: FilterValues;
614
+ /** Called with the next full value map on every edit. */
615
+ onChange: (next: FilterValues) => void;
616
+ /** Live results count shown by the FilterBar (WCAG live region). Omit to hide. */
617
+ resultsCount?: number;
618
+ /** Pre-localized noun for the count (already singularised by the caller if needed). */
619
+ resultsLabel?: string;
620
+ /** When set, shows an Apply button + commits on Enter — the draft/apply model. Omit for live. */
621
+ onApply?: () => void;
622
+ /** Pre-localized Apply label / hint (default via UiProvider `t`). */
623
+ applyLabel?: string;
624
+ applyHint?: string;
625
+ /** Disable Apply (e.g. while busy or when a date field is invalid — aml's gate). */
626
+ applyDisabled?: boolean;
627
+ /** When set, shows a Clear/Reset button. */
628
+ onClear?: () => void;
629
+ clearLabel?: string;
630
+ clearHint?: string;
631
+ /** Extra actions (Export CSV/PDF, bulk bar) rendered BEFORE the built-in Apply/Clear. */
632
+ actions?: React.ReactNode;
633
+ /** Pre-localized fallback placeholder for an unset select (default via `t`). */
634
+ selectPlaceholder?: string;
635
+ /** Pre-localized default sub-labels for date-range fields (default via `t`). */
636
+ fromLabel?: string;
637
+ toLabel?: string;
638
+ /**
639
+ * Optional custom renderer for `select` fields — the injection point for
640
+ * `@dloizides/ui-layout`'s responsive `ModalDropdown` (or any other select). When omitted, the
641
+ * dependency-free in-tree dropdown is used. The label wrapper stays supplied by the bar.
642
+ */
643
+ renderSelect?: (args: RenderSelectArgs) => React.ReactNode;
644
+ /** FilterBar per-slot style overrides — merged LAST, so a consumer always wins. */
645
+ styleOverrides?: FilterBarStyleOverrides;
646
+ testID?: string;
647
+ }
648
+ 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;
649
+
650
+ interface UseFilterDraftOptions<V extends FilterValues> {
651
+ /** The initial (and reset target) value — the "all filters cleared" state. */
652
+ initial: V;
653
+ /** Fired when a draft is committed. Wire your `setPage(1)` + query refresh here. */
654
+ onApply?: (committed: V) => void;
655
+ /** Fired when the draft + committed are reset to `initial` (e.g. clear an inline error). */
656
+ onReset?: () => void;
657
+ }
658
+ interface FilterDraft<V extends FilterValues> {
659
+ /** The live, uncommitted value the bar edits. */
660
+ draft: V;
661
+ /** The committed value the query reads. */
662
+ committed: V;
663
+ /** Patch one field of the draft (merge, like aml's per-bar `set`). */
664
+ setField: (key: string, value: FilterValue) => void;
665
+ /** Replace the whole draft (the bar's `onChange`). */
666
+ setDraft: (next: V) => void;
667
+ /** Commit the draft → committed and fire `onApply`. */
668
+ apply: () => void;
669
+ /** Reset draft + committed to `initial` and fire `onReset`. */
670
+ reset: () => void;
671
+ /** True when the draft differs from the committed value (an Apply would change the result). */
672
+ dirty: boolean;
673
+ }
674
+ declare function useFilterDraft<V extends FilterValues>({ initial, onApply, onReset }: UseFilterDraftOptions<V>): FilterDraft<V>;
675
+
676
+ /**
677
+ * suggestOptions — the ranked substring matcher behind the `typeahead` field, generalized
678
+ * from aml-v2's `suggestCountries`. Ranks: value exact (0) > value prefix (1) > label prefix
679
+ * (2) > label contains (3); ties broken by `label.localeCompare`. Empty/short queries return
680
+ * `[]` (nothing surfaces until `minChars` is typed, mirroring a native `<datalist>`).
681
+ */
682
+
683
+ /**
684
+ * Rank + cap the options matching `query`. Returns `[]` until `query` (trimmed) is at least
685
+ * `minChars` long, then the best `limit` matches, ranked as documented above.
686
+ */
687
+ declare function suggestOptions(options: readonly FilterOption[], query: string, minChars: number, limit: number): readonly FilterOption[];
688
+ /** True when `text` is non-empty yet matches no option's value or label exactly (case-insensitive). */
689
+ declare function isUnmatched(options: readonly FilterOption[], text: string): boolean;
690
+
691
+ /**
692
+ * Constants for the declarative Filters bar — every test id, i18n key and layout number in
693
+ * one place so the components carry no magic numbers and no ad-hoc strings.
694
+ */
695
+
696
+ /** Root testID of the declarative filter bar. */
697
+ declare const FILTERS_TEST_ID = "ui-filters-declarative";
698
+ /** Default minimum widths (px) per field kind before it wraps. */
699
+ declare const FIELD_MIN_WIDTH: Record<FilterFieldKind, number>;
700
+ /** Default min characters before a typeahead surfaces suggestions. */
701
+ declare const DEFAULT_TYPEAHEAD_MIN_CHARS = 1;
702
+ /** Default cap on typeahead suggestions rendered. */
703
+ declare const DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS = 8;
704
+ /** Derived testIDs for the declarative bar. */
705
+ declare const fieldTestID: (barTestID: string, key: string) => string;
706
+ declare const applyTestID: (barTestID: string) => string;
707
+ declare const clearTestID: (barTestID: string) => string;
708
+ /**
709
+ * Translation keys for the bar's own controls. Apps map these in their UiProvider `t`; the
710
+ * neutral default `t` returns the key, so a forgotten key degrades to the key, never a literal.
711
+ * A caller may also override any of them with a pre-localized string prop on {@link Filters}.
712
+ */
713
+ declare const FILTERS_I18N: {
714
+ readonly apply: "uiTables.filters.apply";
715
+ readonly applyHint: "uiTables.filters.applyHint";
716
+ readonly clear: "uiTables.filters.clear";
717
+ readonly clearHint: "uiTables.filters.clearHint";
718
+ readonly selectPlaceholder: "uiTables.filters.selectPlaceholder";
719
+ readonly dropdownHint: "uiTables.filters.dropdownHint";
720
+ readonly optionHint: "uiTables.filters.optionHint";
721
+ /**
722
+ * Accessible NAME of a select trigger, e.g. "{{p1}}: {{p2}}" → "Status: Active". The
723
+ * trigger's `accessibilityLabel` REPLACES its visible text for a screen reader, so labelling
724
+ * it with the field name alone silently hides the current selection. Untranslated it
725
+ * degrades to the field label alone (prior behaviour) — never to the raw key.
726
+ */
727
+ readonly selectTriggerLabel: "uiTables.filters.selectTriggerLabel";
728
+ readonly from: "uiTables.filters.from";
729
+ readonly to: "uiTables.filters.to";
424
730
  };
425
731
 
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 };
732
+ 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 };