@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/dist/index.d.ts 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 };