@brightlocal/ui-components 3.1.0 → 3.2.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.
Files changed (176) hide show
  1. package/README.md +6 -1
  2. package/component-meta.json +663 -38
  3. package/deprecations.json +1 -1
  4. package/dist/alert-dialog.cjs +1 -1
  5. package/dist/alert-dialog.d.ts +32 -3
  6. package/dist/alert-dialog.d.ts.map +1 -1
  7. package/dist/alert-dialog.js +61 -58
  8. package/dist/alert.cjs +1 -1
  9. package/dist/alert.d.ts.map +1 -1
  10. package/dist/alert.js +58 -57
  11. package/dist/badge.cjs +1 -1
  12. package/dist/badge.d.ts +9 -0
  13. package/dist/badge.d.ts.map +1 -1
  14. package/dist/badge.js +50 -30
  15. package/dist/banner.cjs +1 -0
  16. package/dist/banner.d.ts +81 -0
  17. package/dist/banner.d.ts.map +1 -0
  18. package/dist/banner.js +176 -0
  19. package/dist/blocks/empty-state.cjs +1 -1
  20. package/dist/blocks/empty-state.d.ts +4 -3
  21. package/dist/blocks/empty-state.d.ts.map +1 -1
  22. package/dist/blocks/empty-state.js +21 -20
  23. package/dist/blocks/progress-state.d.ts +2 -2
  24. package/dist/blocks/sidebar.cjs +1 -1
  25. package/dist/blocks/sidebar.d.ts +17 -0
  26. package/dist/blocks/sidebar.d.ts.map +1 -1
  27. package/dist/blocks/sidebar.js +8 -2
  28. package/dist/brand-illustration-motif.d.ts +1 -1
  29. package/dist/card.cjs +1 -1
  30. package/dist/card.d.ts +86 -6
  31. package/dist/card.d.ts.map +1 -1
  32. package/dist/card.js +185 -96
  33. package/dist/chart.cjs +3 -3
  34. package/dist/chart.d.ts +231 -13
  35. package/dist/chart.d.ts.map +1 -1
  36. package/dist/chart.js +466 -306
  37. package/dist/checkbox.cjs +1 -1
  38. package/dist/checkbox.d.ts +1 -1
  39. package/dist/checkbox.d.ts.map +1 -1
  40. package/dist/checkbox.js +2 -1
  41. package/dist/combobox.cjs +1 -1
  42. package/dist/combobox.js +2 -2
  43. package/dist/command.cjs +1 -1
  44. package/dist/command.js +1 -1
  45. package/dist/data-table.cjs +1 -1
  46. package/dist/data-table.d.ts +169 -22
  47. package/dist/data-table.d.ts.map +1 -1
  48. package/dist/data-table.js +695 -561
  49. package/dist/grid.d.ts +24 -1
  50. package/dist/grid.d.ts.map +1 -1
  51. package/dist/hooks/use-breakpoint.cjs +1 -1
  52. package/dist/hooks/use-breakpoint.d.ts +1 -1
  53. package/dist/hooks/use-breakpoint.d.ts.map +1 -1
  54. package/dist/hooks/use-breakpoint.js +1 -0
  55. package/dist/index.cjs +1 -1
  56. package/dist/index.d.ts +5 -0
  57. package/dist/index.d.ts.map +1 -1
  58. package/dist/index.js +593 -561
  59. package/dist/info-tooltip.cjs +1 -0
  60. package/dist/info-tooltip.d.ts +39 -0
  61. package/dist/info-tooltip.d.ts.map +1 -0
  62. package/dist/info-tooltip.js +41 -0
  63. package/dist/input-chip.cjs +1 -1
  64. package/dist/input-chip.js +1 -1
  65. package/dist/input-group.cjs +1 -1
  66. package/dist/input-group.d.ts +33 -2
  67. package/dist/input-group.d.ts.map +1 -1
  68. package/dist/input-group.js +167 -54
  69. package/dist/input-otp.cjs +1 -1
  70. package/dist/input-otp.js +9 -9
  71. package/dist/input-password.cjs +1 -1
  72. package/dist/input-password.d.ts +28 -6
  73. package/dist/input-password.d.ts.map +1 -1
  74. package/dist/input-password.js +5 -5
  75. package/dist/input.cjs +1 -1
  76. package/dist/input.js +10 -10
  77. package/dist/lib/block-illustration.cjs +1 -1
  78. package/dist/lib/block-illustration.d.ts +4 -1
  79. package/dist/lib/block-illustration.d.ts.map +1 -1
  80. package/dist/lib/block-illustration.js +12 -11
  81. package/dist/lib/utils.cjs +1 -1
  82. package/dist/lib/utils.d.ts.map +1 -1
  83. package/dist/lib/utils.js +4 -3
  84. package/dist/list.cjs +1 -1
  85. package/dist/list.js +1 -1
  86. package/dist/multi-select-filter.cjs +1 -0
  87. package/dist/multi-select-filter.d.ts +178 -0
  88. package/dist/multi-select-filter.d.ts.map +1 -0
  89. package/dist/multi-select-filter.js +463 -0
  90. package/dist/progress.cjs +1 -1
  91. package/dist/progress.d.ts +123 -16
  92. package/dist/progress.d.ts.map +1 -1
  93. package/dist/progress.js +89 -75
  94. package/dist/rating.cjs +1 -1
  95. package/dist/rating.js +18 -18
  96. package/dist/relative-date.cjs +1 -0
  97. package/dist/relative-date.d.ts +65 -0
  98. package/dist/relative-date.d.ts.map +1 -0
  99. package/dist/relative-date.js +128 -0
  100. package/dist/select.cjs +2 -2
  101. package/dist/select.d.ts +11 -1
  102. package/dist/select.d.ts.map +1 -1
  103. package/dist/select.js +97 -81
  104. package/dist/sheet.cjs +1 -1
  105. package/dist/sheet.d.ts +78 -2
  106. package/dist/sheet.d.ts.map +1 -1
  107. package/dist/sheet.js +192 -85
  108. package/dist/single-select-filter.cjs +1 -0
  109. package/dist/single-select-filter.d.ts +81 -0
  110. package/dist/single-select-filter.d.ts.map +1 -0
  111. package/dist/single-select-filter.js +226 -0
  112. package/dist/sonner.cjs +1 -1
  113. package/dist/sonner.d.ts.map +1 -1
  114. package/dist/sonner.js +22 -22
  115. package/dist/split-layout.cjs +1 -1
  116. package/dist/split-layout.d.ts +1 -1
  117. package/dist/split-layout.js +13 -13
  118. package/dist/table.cjs +1 -1
  119. package/dist/table.d.ts +45 -4
  120. package/dist/table.d.ts.map +1 -1
  121. package/dist/table.js +90 -73
  122. package/dist/tabs.cjs +1 -1
  123. package/dist/tabs.d.ts +12 -1
  124. package/dist/tabs.d.ts.map +1 -1
  125. package/dist/tabs.js +148 -126
  126. package/dist/textarea.cjs +1 -1
  127. package/dist/textarea.js +1 -1
  128. package/dist/tooltip.cjs +1 -1
  129. package/dist/tooltip.d.ts +38 -36
  130. package/dist/tooltip.d.ts.map +1 -1
  131. package/dist/tooltip.js +262 -73
  132. package/dist/typography-text.d.ts +1 -2
  133. package/dist/typography-text.d.ts.map +1 -1
  134. package/dist/typography.d.ts +1 -1
  135. package/package.json +5 -6
  136. package/src/blocks/empty-state.tsx +8 -3
  137. package/src/blocks/progress-state.tsx +2 -2
  138. package/src/blocks/sidebar.tsx +26 -2
  139. package/src/components/alert-dialog.tsx +50 -5
  140. package/src/components/alert.tsx +16 -8
  141. package/src/components/badge.tsx +40 -3
  142. package/src/components/banner.tsx +288 -0
  143. package/src/components/brand-illustration-motif.tsx +1 -1
  144. package/src/components/card.tsx +211 -24
  145. package/src/components/chart.tsx +523 -35
  146. package/src/components/checkbox.tsx +1 -1
  147. package/src/components/combobox.tsx +2 -2
  148. package/src/components/command.tsx +1 -1
  149. package/src/components/data-table.tsx +778 -195
  150. package/src/components/grid.tsx +32 -1
  151. package/src/components/info-tooltip.tsx +94 -0
  152. package/src/components/input-chip.tsx +1 -1
  153. package/src/components/input-group.tsx +246 -11
  154. package/src/components/input-otp.tsx +1 -1
  155. package/src/components/input-password.tsx +33 -11
  156. package/src/components/input.tsx +1 -1
  157. package/src/components/list.tsx +1 -1
  158. package/src/components/multi-select-filter.tsx +912 -0
  159. package/src/components/progress.tsx +190 -31
  160. package/src/components/rating.tsx +1 -1
  161. package/src/components/relative-date.tsx +230 -0
  162. package/src/components/select.tsx +35 -5
  163. package/src/components/sheet.tsx +240 -4
  164. package/src/components/single-select-filter.tsx +443 -0
  165. package/src/components/sonner.tsx +16 -5
  166. package/src/components/split-layout.tsx +2 -2
  167. package/src/components/table.tsx +71 -11
  168. package/src/components/tabs.tsx +93 -46
  169. package/src/components/textarea.tsx +1 -1
  170. package/src/components/tooltip.tsx +440 -68
  171. package/src/components/typography-text.tsx +1 -2
  172. package/src/components/typography.tsx +1 -1
  173. package/src/hooks/use-breakpoint.ts +2 -1
  174. package/src/index.ts +5 -0
  175. package/src/lib/block-illustration.tsx +5 -1
  176. package/src/lib/utils.ts +1 -0
@@ -25,6 +25,7 @@ import {
25
25
  type Column,
26
26
  type ColumnDef,
27
27
  type ExpandedState,
28
+ type Header,
28
29
  type PaginationState,
29
30
  type Row,
30
31
  type RowData,
@@ -56,14 +57,18 @@ import {
56
57
  ArrowUpDown,
57
58
  ChevronRight,
58
59
  Search,
59
- X,
60
60
  } from "@brightlocal/icons";
61
61
 
62
62
  import { cn } from "@brightlocal/ui-components/lib/utils";
63
63
  import { useIsBelowBreakpoint } from "@brightlocal/ui-components/hooks/use-breakpoint";
64
64
  import { Button } from "./button";
65
65
  import { Checkbox } from "./checkbox";
66
- import { InputGroup, InputGroupAddon, InputGroupInput } from "./input-group";
66
+ import {
67
+ InputGroup,
68
+ InputGroupAddon,
69
+ InputGroupClear,
70
+ InputGroupInput,
71
+ } from "./input-group";
67
72
  import {
68
73
  Pagination,
69
74
  PaginationContent,
@@ -75,6 +80,7 @@ import {
75
80
  usePagination,
76
81
  } from "./pagination";
77
82
  import { Skeleton } from "./skeleton";
83
+ import { Spinner } from "./spinner";
78
84
  import {
79
85
  Table,
80
86
  TableBody,
@@ -82,6 +88,7 @@ import {
82
88
  TableHead,
83
89
  TableHeader,
84
90
  TableRow,
91
+ scrollRegionProps,
85
92
  } from "./table";
86
93
  import { TypographyMuted } from "./typography";
87
94
 
@@ -461,6 +468,22 @@ export function useDataTable<TData>(
461
468
  * rendering-focused — wire toolbars, pagination, and search components
462
469
  * outside of it via composition.
463
470
  */
471
+ /* -------------------------------------------------------------------------------------------------
472
+ * Internal: refetch context (DS-916)
473
+ *
474
+ * While a server-side refetch is in flight the rows on screen are stale.
475
+ * Selection controls rendered inside the table (`DataTableSelectAllCheckbox`,
476
+ * `DataTableSelectRowCheckbox`) read this context and block interaction:
477
+ * `aria-disabled` plus a guarded change handler (the checkbox is controlled,
478
+ * so a guarded handler stops pointer and keyboard alike). Not `inert` — that
479
+ * removes the checkbox from the accessibility tree, leaving the select-all
480
+ * `<th>` with no screen-reader-visible content (axe `empty-table-header`)
481
+ * and yanking focus from a user mid-interaction. The bulk-actions bar lives
482
+ * outside the table's subtree, so it takes its own `refetching` prop instead.
483
+ * -----------------------------------------------------------------------------------------------*/
484
+
485
+ const DataTableRefetchingContext = React.createContext(false);
486
+
464
487
  export interface DataTableProps<TData> {
465
488
  /** TanStack Table instance (usually returned from `useDataTable`). */
466
489
  table: TanStackTable<TData>;
@@ -472,6 +495,32 @@ export interface DataTableProps<TData> {
472
495
  trackingLabel?: string;
473
496
  /** Show skeleton rows instead of data while loading async data. */
474
497
  isLoading?: boolean;
498
+ /**
499
+ * Marks a server-side refetch (page, sort, filter or search change) as in
500
+ * flight. Unlike `isLoading` — the initial load, which swaps rows for
501
+ * skeletons — `refetching` never touches the rows: they stay rendered at
502
+ * full contrast (keep the stale data with TanStack Query's
503
+ * `placeholderData: keepPreviousData` or `useTransition`). The table sets
504
+ * `aria-busy` (never the wrapper — the live region must stay outside the
505
+ * busy subtree to be announced), a polite live region announces
506
+ * `refetchingLabel`, and the
507
+ * selection checkboxes (`DataTableSelectAllCheckbox`,
508
+ * `DataTableSelectRowCheckbox`) set `aria-disabled` and ignore toggles —
509
+ * selecting rows that are about to be replaced acts on stale data. The busy *visual* belongs to the
510
+ * control that requested the refetch (the pagination button, the sort
511
+ * header's or search field's `loading`), not to the body.
512
+ *
513
+ * Wrap a raw `isFetching` in `useDelayedPending` before passing it, so a
514
+ * refetch that resolves inside the flash threshold shows nothing at all.
515
+ * @default false
516
+ */
517
+ refetching?: boolean;
518
+ /**
519
+ * What the polite live region announces to screen readers while
520
+ * `refetching` is set.
521
+ * @default "Loading results…"
522
+ */
523
+ refetchingLabel?: string;
475
524
  /** Number of skeleton rows when loading. Falls back to the table's page size, then 10. */
476
525
  skeletonRowCount?: number;
477
526
  /**
@@ -491,13 +540,38 @@ export interface DataTableProps<TData> {
491
540
  */
492
541
  noResultsMessage?: React.ReactNode;
493
542
  /**
494
- * Pin the `<thead>` to the top of the scroll container so column headers
495
- * remain visible while scrolling. The header keeps its opaque `bg-muted`
496
- * background to separate it from body rows.
543
+ * Pin the `<thead>` to the top of the component's own scroll container
544
+ * (the outer wrapper) so column headers remain visible while the rows
545
+ * scroll. Bound the height through `className` — a fixed cap
546
+ * (`max-h-96`) or flex sizing inside a height-capped parent
547
+ * (`min-h-0 flex-1`) — and the header sticks while rows scroll beneath
548
+ * it (DS-912). The header keeps its opaque `bg-muted` background to
549
+ * separate it from body rows.
550
+ *
551
+ * Setting this also makes the outer wrapper a focusable scroll region
552
+ * (`role="region"` + `tabIndex`, labelled by `scrollRegionLabel`), so
553
+ * keyboard users can focus and scroll the rows — the height bound lives
554
+ * in `className`, which the component cannot inspect, so the sticky
555
+ * intent is the signal. For the same reason, don't set it on a table
556
+ * with no height bound: the wrapper never scrolls, and the region
557
+ * becomes an inert tab stop.
497
558
  * @default false
498
559
  */
499
560
  stickyHeader?: boolean;
500
- /** Additional class name for the outer wrapper. */
561
+ /**
562
+ * Additional class name for the outer wrapper — the component's single
563
+ * scroll container for both axes. Height bounds belong here: `max-h-*`
564
+ * for a fixed cap, or `min-h-0 flex-1` to fill a height-capped parent
565
+ * such as a dialog body.
566
+ *
567
+ * A height bound almost always wants `stickyHeader` with it — that also
568
+ * grants the keyboard-focusable scroll-region semantics. If you cap the
569
+ * height and deliberately let the header scroll away, pass
570
+ * `scrollRegionLabel` instead: it opts the wrapper into the same
571
+ * focusable scroll-region semantics without pinning the header, so the
572
+ * region semantics sit on the element that actually scrolls — keyboard
573
+ * arrow keys only scroll the focused element itself or an ancestor.
574
+ */
501
575
  className?: string;
502
576
  /**
503
577
  * Table layout algorithm.
@@ -518,8 +592,23 @@ export interface DataTableProps<TData> {
518
592
  */
519
593
  minWidth?: string;
520
594
  /**
521
- * Accessible label for the scroll container region.
522
- * Used when `minWidth` is set to provide context for keyboard users.
595
+ * Accessible label for the scroll container region (the outer wrapper).
596
+ * Applied whenever the wrapper is a focusable scroll region: `minWidth`
597
+ * is set (horizontal scrolling), `stickyHeader` is set (vertical
598
+ * scrolling under a pinned header), or always on `VirtualizedDataTable`
599
+ * (its viewport is bounded by definition).
600
+ *
601
+ * Passing it is also itself the opt-in for tables that scroll without
602
+ * either signal — a `className` height cap with the header deliberately
603
+ * left unpinned. The height bound lives in `className`, which the
604
+ * component cannot inspect, so the supplied label tells it the rows
605
+ * scroll and the wrapper becomes a focusable region. Don't pass it on a
606
+ * table that never scrolls: the region would be an inert tab stop.
607
+ *
608
+ * Give each table on a page a distinct label ("Invoices", "Team
609
+ * members") — several region landmarks sharing the default name violate
610
+ * axe's landmark-unique rule and are indistinguishable to screen-reader
611
+ * users.
523
612
  * @default "Scrollable table"
524
613
  */
525
614
  scrollRegionLabel?: string;
@@ -575,13 +664,15 @@ export interface DataTableProps<TData> {
575
664
  *
576
665
  * @example
577
666
  * // One slot inside a gapped parent (dialog, card, page section).
578
- * // min-h-0/flex-1 keep the table scrollable in height-capped parents.
667
+ * // min-h-0/flex-1 keep the table scrollable in height-capped parents;
668
+ * // the outer wrapper is the scroll container, so stickyHeader keeps the
669
+ * // column headers visible while the rows scroll (DS-912).
579
670
  * <div className="flex min-h-0 flex-1 flex-col">
580
671
  * <DataTableToolbar dataHook="toolbar-top">
581
672
  * <DataTableToolbarLeft>{heading or search}</DataTableToolbarLeft>
582
673
  * <DataTableToolbarRight>{filters}</DataTableToolbarRight>
583
674
  * </DataTableToolbar>
584
- * <DataTable table={table} dataHook="my-table" className="min-h-0 flex-1 overflow-y-auto" />
675
+ * <DataTable table={table} dataHook="my-table" stickyHeader className="min-h-0 flex-1" />
585
676
  * <DataTableToolbar dataHook="toolbar-bottom">
586
677
  * <DataTableToolbarLeft>{selection counter}</DataTableToolbarLeft>
587
678
  * <DataTableToolbarRight>{pagination}</DataTableToolbarRight>
@@ -594,6 +685,8 @@ export function DataTable<TData>({
594
685
  trackingEl,
595
686
  trackingLabel,
596
687
  isLoading = false,
688
+ refetching = false,
689
+ refetchingLabel,
597
690
  skeletonRowCount,
598
691
  noResultsMessage = "No results.",
599
692
  stickyHeader = false,
@@ -609,78 +702,204 @@ export function DataTable<TData>({
609
702
  const resolvedSkeletonCount =
610
703
  skeletonRowCount ?? table.getState().pagination.pageSize ?? 10;
611
704
 
705
+ // A focusable scroll region whenever scrolling is part of the contract:
706
+ // minWidth (horizontal), stickyHeader, or an explicit scrollRegionLabel
707
+ // (the consumer bounds the height via className, which we cannot see,
708
+ // so the sticky intent — or the supplied label — is the signal that
709
+ // keyboard users must be able to focus and scroll the rows). One const
710
+ // gates both the focus classes and the region props so the two can
711
+ // never drift apart.
712
+ const isScrollRegion =
713
+ Boolean(minWidth) || stickyHeader || scrollRegionLabel !== undefined;
714
+
612
715
  return (
613
716
  <div
614
- aria-busy={isLoading || undefined}
615
- className={cn("border-border overflow-auto rounded-md border", className)}
717
+ // `relative`: the sr-only live region below positions absolutely and
718
+ // must not escape to a distant containing block (double-scrollbar bug).
719
+ className={cn(
720
+ // `scrollbar` themes the native scrollbar with DS colors — the same
721
+ // treatment Command/Combobox lists use for bounded scroll containers.
722
+ "border-border scrollbar relative overflow-auto rounded-md border",
723
+ isScrollRegion && "focus-visible:shadow-default outline-none",
724
+ className
725
+ )}
616
726
  data-hook={dataHook}
617
727
  data-slot="data-table-view"
618
728
  data-tracking-el={trackingEl}
619
729
  data-tracking-label={trackingLabel}
730
+ {...(isScrollRegion ? scrollRegionProps(scrollRegionLabel) : undefined)}
620
731
  >
621
- <Table
622
- dataHook={`${dataHook}-table`}
623
- layout={layout}
624
- minWidth={minWidth}
625
- scrollRegionLabel={scrollRegionLabel}
626
- >
627
- <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
628
- <TableBody>
629
- {isLoading ? (
630
- <>
631
- <LoadingRows
632
- colCount={columnCount}
633
- rowCount={resolvedSkeletonCount}
634
- />
635
- <TableRow className="sr-only">
636
- <TableCell colSpan={columnCount}>
637
- <div aria-live="polite" role="status">
638
- Loading data…
639
- </div>
640
- </TableCell>
641
- </TableRow>
642
- </>
643
- ) : (
644
- <>
645
- {table.getRowModel().rows.length > 0 ? (
646
- table
647
- .getRowModel()
648
- .rows.map((row) => (
649
- <DataTableRow
650
- key={row.id}
651
- columnCount={columnCount}
652
- getRowClassName={getRowClassName}
653
- renderExpandedContent={renderExpandedContent}
654
- row={row}
655
- />
656
- ))
657
- ) : (
658
- <TableRow>
659
- <TableCell align="center" colSpan={columnCount} size="lg">
660
- {/* Padded for a block, not for a line: an `EmptyState` passed
732
+ {/* Always mounted so screen readers reliably announce the text change —
733
+ a live region inserted together with its content can be skipped. */}
734
+ <div aria-live="polite" className="sr-only" role="status">
735
+ {refetching ? (refetchingLabel ?? "Loading results…") : null}
736
+ </div>
737
+ <DataTableRefetchingContext.Provider value={refetching}>
738
+ <Table
739
+ // Busy on the table, never on the wrapper: `aria-busy` on an
740
+ // ancestor defers the live region above until the busy state clears,
741
+ // by which point its text is gone and nothing is announced.
742
+ aria-busy={isLoading || refetching || undefined}
743
+ dataHook={`${dataHook}-table`}
744
+ layout={layout}
745
+ minWidth={minWidth}
746
+ scrollOwner="parent"
747
+ >
748
+ <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
749
+ <TableBody>
750
+ {isLoading ? (
751
+ <>
752
+ <LoadingRows
753
+ colCount={columnCount}
754
+ rowCount={resolvedSkeletonCount}
755
+ />
756
+ <TableRow className="sr-only">
757
+ <TableCell colSpan={columnCount}>
758
+ <div aria-live="polite" role="status">
759
+ Loading data…
760
+ </div>
761
+ </TableCell>
762
+ </TableRow>
763
+ </>
764
+ ) : (
765
+ <>
766
+ {table.getRowModel().rows.length > 0 ? (
767
+ table
768
+ .getRowModel()
769
+ .rows.map((row) => (
770
+ <DataTableRow
771
+ key={row.id}
772
+ columnCount={columnCount}
773
+ getRowClassName={getRowClassName}
774
+ renderExpandedContent={renderExpandedContent}
775
+ row={row}
776
+ />
777
+ ))
778
+ ) : (
779
+ <TableRow>
780
+ <TableCell align="center" colSpan={columnCount} size="lg">
781
+ {/* Padded for a block, not for a line: an `EmptyState` passed
661
782
  as the message needs the same room here that it gets
662
783
  anywhere else, and a prop API gives the consumer nowhere
663
784
  to add it. 24 rather than 32, because this sits inside
664
785
  the cell's own 8: together they give the block its 32,
665
786
  and a one-line message still measures under `size="lg"`'s
666
787
  min-height, so the plain-string row does not move. */}
667
- <div aria-live="polite" className="py-6" role="status">
668
- {noResultsMessage}
669
- </div>
670
- </TableCell>
671
- </TableRow>
672
- )}
673
- </>
674
- )}
675
- </TableBody>
676
- {footer}
677
- </Table>
788
+ <div aria-live="polite" className="py-6" role="status">
789
+ {noResultsMessage}
790
+ </div>
791
+ </TableCell>
792
+ </TableRow>
793
+ )}
794
+ </>
795
+ )}
796
+ </TableBody>
797
+ {footer}
798
+ </Table>
799
+ </DataTableRefetchingContext.Provider>
678
800
  </div>
679
801
  );
680
802
  }
681
803
 
682
804
  DataTable.displayName = "DataTable";
683
805
 
806
+ /* -------------------------------------------------------------------------------------------------
807
+ * Internal: settled-sort override store (DS-916)
808
+ *
809
+ * During a server-side sort refetch, `DataTableColumnHeader` keeps announcing
810
+ * the settled sort order — the one the visible rows still reflect. ARIA
811
+ * requires `aria-sort` on the `<th>` (the columnheader element), which is
812
+ * rendered by `DataTableHeaderRows`, above the header button. This store is
813
+ * the single source of the per-column settled direction, with no consumer
814
+ * wiring: the button publishes every render from a layout effect (the live
815
+ * direction while idle, the held one while `loading`), the cell subscribes.
816
+ * Living at the table level, the value survives header remounts — the common
817
+ * wiring rebuilds the columns array when the fetching flag flips, which
818
+ * remounts every header through flexRender and would wipe header-local
819
+ * state. Outside a DataTable (no provider) both sides fall back to the live
820
+ * TanStack sort state.
821
+ * -----------------------------------------------------------------------------------------------*/
822
+
823
+ type SortOverride = "asc" | "desc" | false;
824
+
825
+ interface SortOverrideEntry {
826
+ /**
827
+ * What the header announces — the settled order while `loading`, the live
828
+ * one while idle.
829
+ */
830
+ displayed: SortOverride;
831
+ /**
832
+ * The live TanStack direction at the same publish. It differs from
833
+ * `displayed` exactly while a settled order is being held, which is how the
834
+ * store identifies the column whose click requested the refetch.
835
+ */
836
+ live: SortOverride;
837
+ }
838
+
839
+ interface SortOverrideStore {
840
+ set: (columnId: string, entry: SortOverrideEntry | null) => void;
841
+ get: (columnId: string) => SortOverrideEntry | null;
842
+ /**
843
+ * Whether any column is holding a settled order its live sort has moved
844
+ * away from — i.e. the in-flight refetch has an identifiable requesting
845
+ * column. When it does, only that column shows the spinner; when it does
846
+ * not (the flag flipped on a later render, e.g. wrapped in
847
+ * `useDelayedPending`), every sorted column falls back to showing it.
848
+ */
849
+ anyHeld: () => boolean;
850
+ subscribe: (listener: () => void) => () => void;
851
+ }
852
+
853
+ const DataTableSortOverridesContext =
854
+ React.createContext<SortOverrideStore | null>(null);
855
+
856
+ const noopSubscribe = () => () => {};
857
+
858
+ function useSortOverrideStore(): SortOverrideStore {
859
+ const [store] = React.useState<SortOverrideStore>(() => {
860
+ const entries = new Map<string, SortOverrideEntry>();
861
+ const listeners = new Set<() => void>();
862
+ const read = (columnId: string): SortOverrideEntry | null =>
863
+ entries.get(columnId) ?? null;
864
+ return {
865
+ set: (columnId, entry) => {
866
+ const current = read(columnId);
867
+ if (
868
+ current === entry ||
869
+ (current !== null &&
870
+ entry !== null &&
871
+ current.displayed === entry.displayed &&
872
+ current.live === entry.live)
873
+ ) {
874
+ return;
875
+ }
876
+ if (entry === null) {
877
+ entries.delete(columnId);
878
+ } else {
879
+ entries.set(columnId, entry);
880
+ }
881
+ listeners.forEach((listener) => listener());
882
+ },
883
+ get: read,
884
+ anyHeld: () => {
885
+ for (const entry of entries.values()) {
886
+ if (entry.displayed !== entry.live) {
887
+ return true;
888
+ }
889
+ }
890
+ return false;
891
+ },
892
+ subscribe: (listener) => {
893
+ listeners.add(listener);
894
+ return () => {
895
+ listeners.delete(listener);
896
+ };
897
+ },
898
+ };
899
+ });
900
+ return store;
901
+ }
902
+
684
903
  /**
685
904
  * Internal: render all header groups with `aria-sort` attributes.
686
905
  * Shared between `DataTable` and `VirtualizedDataTable`.
@@ -692,43 +911,68 @@ function DataTableHeaderRows<TData>({
692
911
  table: TanStackTable<TData>;
693
912
  stickyHeader: boolean;
694
913
  }) {
914
+ const sortOverrides = useSortOverrideStore();
695
915
  return (
696
- <TableHeader className={cn(stickyHeader && "sticky top-0 z-10")}>
697
- {table.getHeaderGroups().map((headerGroup) => (
698
- <TableRow key={headerGroup.id}>
699
- {headerGroup.headers.map((header) => {
700
- const sortDirection = header.column.getCanSort()
701
- ? header.column.getIsSorted()
702
- : false;
703
- const ariaSort =
704
- sortDirection === "asc"
705
- ? "ascending"
706
- : sortDirection === "desc"
707
- ? "descending"
708
- : header.column.getCanSort()
709
- ? "none"
710
- : undefined;
711
- const meta = header.column.columnDef.meta;
712
- return (
713
- <TableHead
714
- key={header.id}
715
- aria-sort={ariaSort}
716
- colSpan={header.colSpan}
717
- minWidth={meta?.minWidth}
718
- width={meta?.width}
719
- >
720
- {header.isPlaceholder
721
- ? null
722
- : flexRender(
723
- header.column.columnDef.header,
724
- header.getContext()
725
- )}
726
- </TableHead>
727
- );
728
- })}
729
- </TableRow>
730
- ))}
731
- </TableHeader>
916
+ <DataTableSortOverridesContext.Provider value={sortOverrides}>
917
+ <TableHeader className={cn(stickyHeader && "sticky top-0 z-10")}>
918
+ {table.getHeaderGroups().map((headerGroup) => (
919
+ <TableRow key={headerGroup.id}>
920
+ {headerGroup.headers.map((header) => (
921
+ <DataTableHeadCell key={header.id} header={header} />
922
+ ))}
923
+ </TableRow>
924
+ ))}
925
+ </TableHeader>
926
+ </DataTableSortOverridesContext.Provider>
927
+ );
928
+ }
929
+
930
+ /**
931
+ * Internal: one `<th>` of the header row.
932
+ *
933
+ * `aria-sort` belongs on the columnheader element, but during a sort refetch
934
+ * the direction the rows still reflect is tracked inside
935
+ * `DataTableColumnHeader` (rendered below this cell). The cell subscribes to
936
+ * that settled direction through the override store, so the `<th>` and the
937
+ * sort button never announce two different orders (DS-916).
938
+ */
939
+ function DataTableHeadCell<TData>({
940
+ header,
941
+ }: {
942
+ header: Header<TData, unknown>;
943
+ }) {
944
+ const overrides = React.useContext(DataTableSortOverridesContext);
945
+ const override = React.useSyncExternalStore(
946
+ overrides ? overrides.subscribe : noopSubscribe,
947
+ () =>
948
+ overrides ? (overrides.get(header.column.id)?.displayed ?? null) : null,
949
+ // Server render: no header has published yet — fall back to live state.
950
+ () => null
951
+ );
952
+ const canSort = header.column.getCanSort();
953
+ const sortDirection = canSort
954
+ ? (override ?? header.column.getIsSorted())
955
+ : false;
956
+ const ariaSort =
957
+ sortDirection === "asc"
958
+ ? "ascending"
959
+ : sortDirection === "desc"
960
+ ? "descending"
961
+ : canSort
962
+ ? "none"
963
+ : undefined;
964
+ const meta = header.column.columnDef.meta;
965
+ return (
966
+ <TableHead
967
+ aria-sort={ariaSort}
968
+ colSpan={header.colSpan}
969
+ minWidth={meta?.minWidth}
970
+ width={meta?.width}
971
+ >
972
+ {header.isPlaceholder
973
+ ? null
974
+ : flexRender(header.column.columnDef.header, header.getContext())}
975
+ </TableHead>
732
976
  );
733
977
  }
734
978
 
@@ -899,6 +1143,8 @@ export function VirtualizedDataTable<TData>({
899
1143
  trackingEl,
900
1144
  trackingLabel,
901
1145
  isLoading = false,
1146
+ refetching = false,
1147
+ refetchingLabel,
902
1148
  skeletonRowCount,
903
1149
  noResultsMessage = "No results.",
904
1150
  stickyHeader = false,
@@ -941,74 +1187,99 @@ export function VirtualizedDataTable<TData>({
941
1187
  return (
942
1188
  <div
943
1189
  ref={scrollContainerRef}
944
- aria-busy={isLoading || undefined}
945
- className={cn("border-border overflow-auto rounded-md border", className)}
1190
+ // `relative`: the sr-only live region below positions absolutely and
1191
+ // must not escape to a distant containing block (double-scrollbar bug).
1192
+ className={cn(
1193
+ // `scrollbar` themes the native scrollbar with DS colors (the
1194
+ // Command/Combobox treatment for bounded scroll containers).
1195
+ "border-border scrollbar relative overflow-auto rounded-md border",
1196
+ // Always a focusable scroll region: virtualization requires a
1197
+ // bounded viewport (height or a className bound), so this wrapper
1198
+ // always scrolls vertically and keyboard users need to reach it.
1199
+ "focus-visible:shadow-default outline-none",
1200
+ className
1201
+ )}
946
1202
  data-hook={dataHook}
947
1203
  data-slot="data-table-view"
948
1204
  data-tracking-el={trackingEl}
949
1205
  data-tracking-label={trackingLabel}
950
1206
  style={height != null ? { height } : undefined}
1207
+ {...scrollRegionProps(scrollRegionLabel)}
951
1208
  >
952
- <Table
953
- dataHook={`${dataHook}-table`}
954
- layout={layout}
955
- minWidth={minWidth}
956
- scrollRegionLabel={scrollRegionLabel}
957
- >
958
- <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
959
- <TableBody>
960
- {isLoading ? (
961
- <>
962
- <LoadingRows
963
- colCount={columnCount}
964
- rowCount={resolvedSkeletonCount}
965
- />
966
- <TableRow className="sr-only">
967
- <TableCell colSpan={columnCount}>
968
- <div aria-live="polite" role="status">
969
- Loading data…
1209
+ {/* Always mounted so screen readers reliably announce the text change —
1210
+ a live region inserted together with its content can be skipped. */}
1211
+ <div aria-live="polite" className="sr-only" role="status">
1212
+ {refetching ? (refetchingLabel ?? "Loading results…") : null}
1213
+ </div>
1214
+ <DataTableRefetchingContext.Provider value={refetching}>
1215
+ <Table
1216
+ // Busy on the table, never on the wrapper: `aria-busy` on an
1217
+ // ancestor defers the live region above until the busy state clears,
1218
+ // by which point its text is gone and nothing is announced.
1219
+ aria-busy={isLoading || refetching || undefined}
1220
+ dataHook={`${dataHook}-table`}
1221
+ layout={layout}
1222
+ minWidth={minWidth}
1223
+ scrollOwner="parent"
1224
+ >
1225
+ <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
1226
+ <TableBody>
1227
+ {isLoading ? (
1228
+ <>
1229
+ <LoadingRows
1230
+ colCount={columnCount}
1231
+ rowCount={resolvedSkeletonCount}
1232
+ />
1233
+ <TableRow className="sr-only">
1234
+ <TableCell colSpan={columnCount}>
1235
+ <div aria-live="polite" role="status">
1236
+ Loading data…
1237
+ </div>
1238
+ </TableCell>
1239
+ </TableRow>
1240
+ </>
1241
+ ) : rows.length > 0 ? (
1242
+ <>
1243
+ {paddingTop > 0 && (
1244
+ <tr aria-hidden="true">
1245
+ <td colSpan={columnCount} style={{ height: paddingTop }} />
1246
+ </tr>
1247
+ )}
1248
+ {virtualItems.map((virtualItem) => {
1249
+ const row = rows[virtualItem.index]!;
1250
+ return (
1251
+ <DataTableRow
1252
+ key={row.id}
1253
+ columnCount={columnCount}
1254
+ getRowClassName={getRowClassName}
1255
+ row={row}
1256
+ />
1257
+ );
1258
+ })}
1259
+ {paddingBottom > 0 && (
1260
+ <tr aria-hidden="true">
1261
+ <td
1262
+ colSpan={columnCount}
1263
+ style={{ height: paddingBottom }}
1264
+ />
1265
+ </tr>
1266
+ )}
1267
+ </>
1268
+ ) : (
1269
+ <TableRow>
1270
+ <TableCell align="center" colSpan={columnCount} size="lg">
1271
+ {/* Padded for a block — see the note on the non-virtualised
1272
+ table's no-results cell. */}
1273
+ <div aria-live="polite" className="py-6" role="status">
1274
+ {noResultsMessage}
970
1275
  </div>
971
1276
  </TableCell>
972
1277
  </TableRow>
973
- </>
974
- ) : rows.length > 0 ? (
975
- <>
976
- {paddingTop > 0 && (
977
- <tr aria-hidden="true">
978
- <td colSpan={columnCount} style={{ height: paddingTop }} />
979
- </tr>
980
- )}
981
- {virtualItems.map((virtualItem) => {
982
- const row = rows[virtualItem.index]!;
983
- return (
984
- <DataTableRow
985
- key={row.id}
986
- columnCount={columnCount}
987
- getRowClassName={getRowClassName}
988
- row={row}
989
- />
990
- );
991
- })}
992
- {paddingBottom > 0 && (
993
- <tr aria-hidden="true">
994
- <td colSpan={columnCount} style={{ height: paddingBottom }} />
995
- </tr>
996
- )}
997
- </>
998
- ) : (
999
- <TableRow>
1000
- <TableCell align="center" colSpan={columnCount} size="lg">
1001
- {/* Padded for a block — see the note on the non-virtualised
1002
- table's no-results cell. */}
1003
- <div aria-live="polite" className="py-6" role="status">
1004
- {noResultsMessage}
1005
- </div>
1006
- </TableCell>
1007
- </TableRow>
1008
- )}
1009
- </TableBody>
1010
- {footer}
1011
- </Table>
1278
+ )}
1279
+ </TableBody>
1280
+ {footer}
1281
+ </Table>
1282
+ </DataTableRefetchingContext.Provider>
1012
1283
  </div>
1013
1284
  );
1014
1285
  }
@@ -1042,9 +1313,35 @@ export interface DataTableColumnHeaderProps<
1042
1313
  /**
1043
1314
  * Builds the accessible label for the sort button.
1044
1315
  * Receives the column title and current sort direction (`"asc"`, `"desc"`, or `false`).
1316
+ * While `loading` is true the direction passed is the settled one — the
1317
+ * order the visible rows still reflect, not the one just requested.
1045
1318
  * @default (title, dir) => `Sort by ${title}${dir ? `, currently ${dir === "asc" ? "ascending" : "descending"}` : ""}`
1046
1319
  */
1047
1320
  getSortLabel?: (title: string, direction: "asc" | "desc" | false) => string;
1321
+ /**
1322
+ * Marks a server-side sort refetch as in flight. Pass the same fetching
1323
+ * flag to every column's header: every sort button sets `aria-busy` and
1324
+ * becomes inert — clicks are ignored to prevent a double-fetch — without a
1325
+ * disabled look, and the column whose click requested the refetch (the one
1326
+ * whose requested order differs from the settled one it still shows) swaps
1327
+ * its sort icon for a spinner. Icons, labels and the `<th>`'s `aria-sort`
1328
+ * keep describing the settled sort order — the order the visible rows still
1329
+ * reflect — until the flag clears.
1330
+ *
1331
+ * The settled order is captured when the sort change and this flag land in
1332
+ * the same render commit: a click handler that sets both, or React Query's
1333
+ * `isFetching` in the same batch — the normal wirings. It is tracked at the
1334
+ * table level, so it survives the columns array being rebuilt (and every
1335
+ * header remounting) when the flag flips. A flag that only flips on a later
1336
+ * render (e.g. wrapped in `useDelayedPending`) degrades gracefully to
1337
+ * announcing the requested order (the standard behavior of sortable
1338
+ * tables), with the spinner on the sorted column or columns — the
1339
+ * requesting one can no longer be told apart; button and `<th>` stay
1340
+ * consistent with each other either way. Rendered standalone (outside a
1341
+ * DataTable), the settled order is held in header-local state instead.
1342
+ * @default false
1343
+ */
1344
+ loading?: boolean;
1048
1345
  }
1049
1346
 
1050
1347
  /**
@@ -1077,7 +1374,74 @@ export function DataTableColumnHeader<TData, TValue>({
1077
1374
  trackingLabel,
1078
1375
  align = "left",
1079
1376
  getSortLabel,
1377
+ loading = false,
1080
1378
  }: DataTableColumnHeaderProps<TData, TValue>) {
1379
+ const currentSort = column.getIsSorted();
1380
+ // Clicking a header flips TanStack's sort state immediately, but during a
1381
+ // server-side refetch the rows still show the previous order. The settled
1382
+ // sort — what the visible rows actually reflect — lives in the table-level
1383
+ // override store, not in local state: the common wiring rebuilds the
1384
+ // columns array when the fetching flag flips, which remounts every header
1385
+ // through flexRender and would wipe component state. The store (owned by
1386
+ // DataTableHeaderRows) survives those remounts, and a remounting header
1387
+ // reads the previous value during render, before the old instance's
1388
+ // cleanup runs (DS-916).
1389
+ const sortOverrides = React.useContext(DataTableSortOverridesContext);
1390
+ const storedSort = React.useSyncExternalStore(
1391
+ sortOverrides ? sortOverrides.subscribe : noopSubscribe,
1392
+ () =>
1393
+ sortOverrides ? (sortOverrides.get(column.id)?.displayed ?? null) : null,
1394
+ () => null
1395
+ );
1396
+ // Standalone fallback: rendered outside a DataTable (no provider) the
1397
+ // settled order lives in local state instead — the previous-render-value
1398
+ // pattern. It cannot survive a header remount, but without the table there
1399
+ // is no DataTableHeaderRows rebuilding the columns array either, so the
1400
+ // remount hazard the store exists for does not apply.
1401
+ const [localSettled, setLocalSettled] = React.useState(currentSort);
1402
+ if (!sortOverrides && !loading && localSettled !== currentSort) {
1403
+ setLocalSettled(currentSort);
1404
+ }
1405
+ const settledSort = sortOverrides
1406
+ ? (storedSort ?? currentSort)
1407
+ : localSettled;
1408
+ const displayedSort = loading ? settledSort : currentSort;
1409
+
1410
+ // The column whose click requested the refetch is the one holding a settled
1411
+ // order its live sort has moved away from — only it gets the spinner, so a
1412
+ // multi-sorted table never animates every sorted header at once. When no
1413
+ // column is held (the flag flipped on a later render — e.g. wrapped in
1414
+ // `useDelayedPending` — so the settled order was never captured), fall back
1415
+ // to showing the spinner on the sorted column(s).
1416
+ const heldSelf = displayedSort !== currentSort;
1417
+ const storeAnyHeld = React.useSyncExternalStore(
1418
+ sortOverrides ? sortOverrides.subscribe : noopSubscribe,
1419
+ () => (sortOverrides ? sortOverrides.anyHeld() : false),
1420
+ () => false
1421
+ );
1422
+ const anyHeld = sortOverrides ? storeAnyHeld : heldSelf;
1423
+ const sortRefetching =
1424
+ loading && (heldSelf || (!anyHeld && currentSort !== false));
1425
+
1426
+ // Publish what this header announces so the enclosing `<th>` mirrors it in
1427
+ // `aria-sort` — the two must never contradict each other. While idle the
1428
+ // store tracks the live sort (the rows reflect it); while loading it holds
1429
+ // the settled value. A layout effect flushes before paint, so no frame is
1430
+ // painted with the `<th>` and the button disagreeing. Rendered standalone
1431
+ // (no provider) the local fallback above holds the settled order instead.
1432
+ React.useLayoutEffect(() => {
1433
+ if (!sortOverrides) {
1434
+ return;
1435
+ }
1436
+ sortOverrides.set(column.id, {
1437
+ displayed: displayedSort,
1438
+ live: currentSort,
1439
+ });
1440
+ return () => {
1441
+ sortOverrides.set(column.id, null);
1442
+ };
1443
+ }, [sortOverrides, column.id, displayedSort, currentSort]);
1444
+
1081
1445
  if (!column.getCanSort()) {
1082
1446
  return (
1083
1447
  <div
@@ -1097,20 +1461,19 @@ export function DataTableColumnHeader<TData, TValue>({
1097
1461
  );
1098
1462
  }
1099
1463
 
1100
- const sortState = column.getIsSorted();
1101
1464
  // First click on an unsorted column follows the column def's explicit
1102
1465
  // `sortDescFirst`; later clicks reverse the current direction. TanStack's
1103
1466
  // `getFirstSortDir()` is not used here — its automatic numeric detection
1104
1467
  // would silently flip existing tables to descending-first (DS-953).
1105
1468
  const nextSortDesc =
1106
- sortState === false
1469
+ currentSort === false
1107
1470
  ? column.columnDef.sortDescFirst === true
1108
- : sortState === "asc";
1471
+ : currentSort === "asc";
1109
1472
  const sortLabel = getSortLabel
1110
- ? getSortLabel(title, sortState)
1111
- : sortState === "desc"
1473
+ ? getSortLabel(title, displayedSort)
1474
+ : displayedSort === "desc"
1112
1475
  ? `Sort by ${title}, currently descending`
1113
- : sortState === "asc"
1476
+ : displayedSort === "asc"
1114
1477
  ? `Sort by ${title}, currently ascending`
1115
1478
  : `Sort by ${title}`;
1116
1479
 
@@ -1127,21 +1490,30 @@ export function DataTableColumnHeader<TData, TValue>({
1127
1490
  data-tracking-label={trackingLabel}
1128
1491
  >
1129
1492
  <Button
1493
+ aria-busy={loading ? "true" : undefined}
1130
1494
  aria-label={sortLabel}
1131
1495
  className="text-muted-foreground text-label h-auto p-0 font-semibold"
1132
1496
  dataHook={dataHook || `column-header-${column.id}`}
1133
1497
  size="sm"
1134
1498
  variant="ghost"
1135
- onClick={() => column.toggleSorting(nextSortDesc)}
1499
+ onClick={() => {
1500
+ // Inert while a refetch is in flight — busy, not disabled, so the
1501
+ // button keeps its look and stays focusable but cannot double-fetch.
1502
+ if (!loading) {
1503
+ column.toggleSorting(nextSortDesc);
1504
+ }
1505
+ }}
1136
1506
  >
1137
1507
  <span aria-hidden="true">{title}</span>
1138
1508
  <span
1139
1509
  aria-hidden="true"
1140
1510
  className="flex size-3 items-center justify-center"
1141
1511
  >
1142
- {sortState === "desc" ? (
1512
+ {sortRefetching ? (
1513
+ <Spinner size="sm" />
1514
+ ) : displayedSort === "desc" ? (
1143
1515
  <ArrowDown size={12} />
1144
- ) : sortState === "asc" ? (
1516
+ ) : displayedSort === "asc" ? (
1145
1517
  <ArrowUp size={12} />
1146
1518
  ) : (
1147
1519
  <ArrowUpDown size={12} />
@@ -1177,8 +1549,38 @@ export interface DataTableSearchProps<TData> extends Omit<
1177
1549
  placeholder?: string;
1178
1550
  /** Accessible label for the clear button. @default "Clear search" */
1179
1551
  clearSearchAriaLabel?: string;
1552
+ /**
1553
+ * Search refetch in flight — the leading search icon swaps to a spinner
1554
+ * and the group sets `aria-busy`. The input stays fully editable, and the
1555
+ * clear button keeps its place in the trailing slot whenever there is a
1556
+ * value: the way out of a slow search never disappears.
1557
+ * @default false
1558
+ */
1559
+ loading?: boolean;
1560
+ /**
1561
+ * Debounce between keystrokes and the table's global filter, in
1562
+ * milliseconds. The input echoes instantly; the filter (and any server
1563
+ * refetch keyed off it) only updates after the pause. Clearing via the
1564
+ * clear button skips the debounce.
1565
+ *
1566
+ * The default is derived from the table's filtering mode: `300` when the
1567
+ * table uses `manualFiltering` (server-side — one refetch per pause,
1568
+ * "debounce the request"), `0` for client-side filtering (rows keep
1569
+ * narrowing per keystroke, as before). Pass a value to override either mode.
1570
+ * @default table.options.manualFiltering ? 300 : 0
1571
+ */
1572
+ debounceMs?: number;
1180
1573
  }
1181
1574
 
1575
+ /**
1576
+ * How many of DataTableSearch's own unacknowledged filter writes are
1577
+ * remembered for telling them apart from external writes. Writes echo back
1578
+ * within a render or two even through a transition- or URL-synced filter, so
1579
+ * anything beyond this is a consumer that never echoes at all — the cap keeps
1580
+ * that wiring from growing the list forever.
1581
+ */
1582
+ const MAX_TRACKED_FILTER_PUSHES = 10;
1583
+
1182
1584
  /**
1183
1585
  * Search input for filtering DataTable rows.
1184
1586
  *
@@ -1187,48 +1589,170 @@ export interface DataTableSearchProps<TData> extends Omit<
1187
1589
  * customize width or shape.
1188
1590
  *
1189
1591
  * Uses the table's global filter (requires `enableGlobalFiltering` on the hook).
1592
+ *
1593
+ * With `manualFiltering` (server-side search) keystrokes echo in the input
1594
+ * instantly while the global filter — and any server refetch keyed off it —
1595
+ * only updates after `debounceMs` of inactivity. Client-side filtering stays
1596
+ * synchronous: rows narrow per keystroke, exactly as the Filtering pattern
1597
+ * promises ("debounce the request, never the input").
1190
1598
  */
1191
1599
  export function DataTableSearch<TData>({
1192
1600
  table,
1193
1601
  ariaLabel,
1194
1602
  placeholder,
1195
1603
  clearSearchAriaLabel,
1604
+ loading = false,
1605
+ debounceMs,
1196
1606
  ...inputGroupProps
1197
1607
  }: DataTableSearchProps<TData>) {
1198
1608
  const filterValue = (table.getState().globalFilter ?? "") as string;
1609
+ const [inputValue, setInputValue] = React.useState(filterValue);
1610
+ // manualFiltering is the consumer's own declaration that filter changes are
1611
+ // server requests — those get the 300ms debounce (DS-916). Without it the
1612
+ // filter is an in-memory narrowing the reader watches, so it stays
1613
+ // per-keystroke. An explicit debounceMs wins in either mode.
1614
+ const effectiveDebounceMs =
1615
+ debounceMs ?? (table.options.manualFiltering === true ? 300 : 0);
1616
+
1617
+ // The debounce is a plain timer owned by this component — no debounced
1618
+ // value lives in state. A remembered value is exactly what made clearing
1619
+ // and then retyping the same query silently skip its push (the memory
1620
+ // bailed out on the equal value and the filter never updated), and what
1621
+ // made a mode flip replay a stale value over the live filter.
1622
+ const pushTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
1623
+ const cancelPendingPush = React.useCallback(() => {
1624
+ if (pushTimerRef.current !== null) {
1625
+ clearTimeout(pushTimerRef.current);
1626
+ pushTimerRef.current = null;
1627
+ }
1628
+ }, []);
1629
+ React.useEffect(() => cancelPendingPush, [cancelPendingPush]);
1630
+
1631
+ // The latest input value, readable from the timer callback. Synced in a
1632
+ // passive effect (never during render); the shortest debounce that
1633
+ // schedules a timer still fires long after the commit's effects, so a
1634
+ // pending push always compares against the current value.
1635
+ const inputValueRef = React.useRef(inputValue);
1636
+ React.useEffect(() => {
1637
+ inputValueRef.current = inputValue;
1638
+ });
1639
+
1640
+ // `filter` mirrors the last observed table filter (the previous-render
1641
+ // value); `pushed` lists the values THIS component wrote that have not been
1642
+ // observed back yet, so a push's own echo is not mistaken for an external
1643
+ // write. Acknowledgment is by value and recency, not true write identity —
1644
+ // the filter is a plain string in table state, so there is no channel for a
1645
+ // revision token. That leaves one ambiguous case: an external write whose
1646
+ // value exactly equals an in-flight unacknowledged push is read as that
1647
+ // push's echo, and keystrokes typed since are kept rather than overwritten.
1648
+ // Every external write that differs from the in-flight pushes is adopted.
1649
+ // A list, not a single slot: with writes landing a render late (a
1650
+ // transition- or URL-synced filter) several pushes can be in flight at
1651
+ // once. Recorded via setState (not a ref) so render never touches a mutable
1652
+ // value, and batched with the table write itself.
1653
+ const [filterSync, setFilterSync] = React.useState<{
1654
+ filter: string;
1655
+ pushed: string[];
1656
+ }>({ filter: filterValue, pushed: [] });
1657
+
1658
+ // Write the filter and record the write — called from handlers and timer
1659
+ // callbacks only, never during render. The record is capped: a consumer
1660
+ // that never echoes pushes back (a controlled filter without a handler, or
1661
+ // one that normalizes values) must not grow it for the component's
1662
+ // lifetime, and more than a handful of unacknowledged writes can no longer
1663
+ // be meaningfully "in flight" anyway.
1664
+ const pushFilter = (next: string) => {
1665
+ if ((table.getState().globalFilter ?? "") === next) {
1666
+ return;
1667
+ }
1668
+ setFilterSync((sync) => ({
1669
+ filter: sync.filter,
1670
+ pushed: [...sync.pushed, next].slice(-MAX_TRACKED_FILTER_PUSHES),
1671
+ }));
1672
+ table.setGlobalFilter(next);
1673
+ };
1674
+
1675
+ const schedulePush = (next: string) => {
1676
+ cancelPendingPush();
1677
+ if (effectiveDebounceMs > 0) {
1678
+ pushTimerRef.current = setTimeout(() => {
1679
+ pushTimerRef.current = null;
1680
+ // An adopted external write (which replaces `inputValue` below) or a
1681
+ // clear supersedes this push — stale keystrokes never win over them.
1682
+ if (inputValueRef.current === next) {
1683
+ pushFilter(next);
1684
+ }
1685
+ }, effectiveDebounceMs);
1686
+ } else {
1687
+ pushFilter(next);
1688
+ }
1689
+ };
1690
+
1691
+ // Adopt filter changes made outside this input (a consumer reset, another
1692
+ // control writing the filter) — state adjusted during render. A pending
1693
+ // debounced push cannot write over the adopted value: its timer compares
1694
+ // against the adopted `inputValue` and skips itself.
1695
+ if (filterValue !== filterSync.filter) {
1696
+ // Acknowledge own pushes by identity: the observed value is the most
1697
+ // recent matching push, and everything pushed before it was superseded
1698
+ // (renders can skip intermediate states, so earlier entries may never be
1699
+ // observed on their own). An unmatched value is an external write; later
1700
+ // own pushes may still be observed, so the list is kept.
1701
+ const ackIndex = filterSync.pushed.lastIndexOf(filterValue);
1702
+ const isOwnPush = ackIndex !== -1;
1703
+ setFilterSync({
1704
+ filter: filterValue,
1705
+ pushed: isOwnPush
1706
+ ? filterSync.pushed.slice(ackIndex + 1)
1707
+ : filterSync.pushed,
1708
+ });
1709
+ if (!isOwnPush && filterValue !== inputValue) {
1710
+ setInputValue(filterValue);
1711
+ }
1712
+ }
1199
1713
 
1200
- const handleFilterChange = (value: string) => {
1201
- table.setGlobalFilter(value);
1714
+ const handleClear = () => {
1715
+ // Clearing skips the debounce — the filter resets immediately, and any
1716
+ // pending keystroke push is cancelled rather than resurrecting the query.
1717
+ cancelPendingPush();
1718
+ setInputValue("");
1719
+ pushFilter("");
1202
1720
  };
1203
1721
 
1204
1722
  return (
1205
- <InputGroup data-slot="data-table-search" {...inputGroupProps}>
1723
+ <InputGroup
1724
+ aria-busy={loading ? "true" : undefined}
1725
+ data-slot="data-table-search"
1726
+ {...inputGroupProps}
1727
+ >
1206
1728
  <InputGroupAddon className="pl-3">
1207
- <Search />
1729
+ {/* The spinner takes the search icon's slot, never the clear button's:
1730
+ the way out of a slow search must stay where it always is. */}
1731
+ {loading ? (
1732
+ <Spinner dataHook={`${inputGroupProps.dataHook}-loading`} />
1733
+ ) : (
1734
+ <Search />
1735
+ )}
1208
1736
  </InputGroupAddon>
1209
1737
  <InputGroupInput
1210
1738
  aria-label={ariaLabel ?? "Search table"}
1211
1739
  placeholder={placeholder ?? "Search..."}
1212
1740
  type="text"
1213
- value={filterValue}
1214
- onChange={(event) => handleFilterChange(event.target.value)}
1741
+ value={inputValue}
1742
+ onChange={(event) => {
1743
+ const next = event.target.value;
1744
+ setInputValue(next);
1745
+ // Debounced (server-side) mode schedules the push; synchronous mode
1746
+ // pushes in the handler for same-keystroke narrowing.
1747
+ schedulePush(next);
1748
+ }}
1749
+ />
1750
+ <InputGroupClear
1751
+ clearSearchAriaLabel={clearSearchAriaLabel}
1752
+ data-slot="data-table-search-clear"
1753
+ dataHook={`${inputGroupProps.dataHook}-clear`}
1754
+ onClear={effectiveDebounceMs > 0 ? handleClear : undefined}
1215
1755
  />
1216
- {filterValue && (
1217
- <InputGroupAddon className="pr-1">
1218
- <Button
1219
- aria-label={clearSearchAriaLabel ?? "Clear search"}
1220
- /* Fixed square hit area — h-auto p-1 let the ghost hover hug the
1221
- 14px icon into a squashed pill. */
1222
- className="size-6 p-0"
1223
- data-slot="data-table-search-clear"
1224
- dataHook={`${inputGroupProps.dataHook}-clear`}
1225
- variant="ghost"
1226
- onClick={() => handleFilterChange("")}
1227
- >
1228
- <X size={14} />
1229
- </Button>
1230
- </InputGroupAddon>
1231
- )}
1232
1756
  </InputGroup>
1233
1757
  );
1234
1758
  }
@@ -1744,6 +2268,11 @@ export interface DataTableSelectAllCheckboxProps<TData> {
1744
2268
  /**
1745
2269
  * Header checkbox for selecting all visible page rows. Renders as
1746
2270
  * indeterminate when some (but not all) rows are selected.
2271
+ *
2272
+ * While the surrounding `DataTable` is `refetching`, the checkbox is
2273
+ * `aria-disabled` and toggles are ignored (visually unchanged, still exposed
2274
+ * to screen readers so the select-all `<th>` never reads as empty): the rows
2275
+ * it would select are stale and about to be replaced (DS-916).
1747
2276
  */
1748
2277
  export function DataTableSelectAllCheckbox<TData>({
1749
2278
  table,
@@ -1752,8 +2281,10 @@ export function DataTableSelectAllCheckbox<TData>({
1752
2281
  trackingLabel,
1753
2282
  selectAllAriaLabel,
1754
2283
  }: DataTableSelectAllCheckboxProps<TData>) {
2284
+ const refetching = React.useContext(DataTableRefetchingContext);
1755
2285
  return (
1756
2286
  <Checkbox
2287
+ aria-disabled={refetching || undefined}
1757
2288
  aria-label={selectAllAriaLabel ?? "Select all"}
1758
2289
  checked={
1759
2290
  table.getIsAllPageRowsSelected() ||
@@ -1762,7 +2293,13 @@ export function DataTableSelectAllCheckbox<TData>({
1762
2293
  dataHook={dataHook || "select-all-checkbox"}
1763
2294
  trackingEl={trackingEl}
1764
2295
  trackingLabel={trackingLabel}
1765
- onCheckedChange={(value) => table.toggleAllPageRowsSelected(!!value)}
2296
+ onCheckedChange={(value) => {
2297
+ // The guard is the real block: the checkbox is controlled, so pointer
2298
+ // and keyboard toggles alike are ignored while refetching.
2299
+ if (!refetching) {
2300
+ table.toggleAllPageRowsSelected(!!value);
2301
+ }
2302
+ }}
1766
2303
  />
1767
2304
  );
1768
2305
  }
@@ -1787,6 +2324,11 @@ export interface DataTableSelectRowCheckboxProps<TData> {
1787
2324
 
1788
2325
  /**
1789
2326
  * Row-level selection checkbox. Disabled when the row cannot be selected.
2327
+ *
2328
+ * While the surrounding `DataTable` is `refetching`, the checkbox is
2329
+ * `aria-disabled` and toggles are ignored (visually unchanged, still exposed
2330
+ * to screen readers): the row it would select is stale and about to be
2331
+ * replaced (DS-916).
1790
2332
  */
1791
2333
  export function DataTableSelectRowCheckbox<TData>({
1792
2334
  row,
@@ -1795,15 +2337,23 @@ export function DataTableSelectRowCheckbox<TData>({
1795
2337
  trackingLabel,
1796
2338
  selectRowAriaLabel,
1797
2339
  }: DataTableSelectRowCheckboxProps<TData>) {
2340
+ const refetching = React.useContext(DataTableRefetchingContext);
1798
2341
  return (
1799
2342
  <Checkbox
2343
+ aria-disabled={refetching || undefined}
1800
2344
  aria-label={selectRowAriaLabel ?? "Select row"}
1801
2345
  checked={row.getIsSelected()}
1802
2346
  dataHook={dataHook || `select-row-${row.id}`}
1803
2347
  disabled={!row.getCanSelect()}
1804
2348
  trackingEl={trackingEl}
1805
2349
  trackingLabel={trackingLabel}
1806
- onCheckedChange={(value) => row.toggleSelected(!!value)}
2350
+ onCheckedChange={(value) => {
2351
+ // The guard is the real block: the checkbox is controlled, so pointer
2352
+ // and keyboard toggles alike are ignored while refetching.
2353
+ if (!refetching) {
2354
+ row.toggleSelected(!!value);
2355
+ }
2356
+ }}
1807
2357
  />
1808
2358
  );
1809
2359
  }
@@ -2010,6 +2560,13 @@ export interface DataTableBulkActionsContextValue {
2010
2560
  * `useDataTable` — the same option `DataTablePagination` relies on.
2011
2561
  */
2012
2562
  totalCount: number;
2563
+ /**
2564
+ * Whether a server-side refetch is in flight (the bar's `refetching` prop).
2565
+ * `DataTableBulkActionsActions` goes inert on it; custom action parts built
2566
+ * on this context should do the same — the selection they would act on is
2567
+ * stale (DS-916).
2568
+ */
2569
+ refetching: boolean;
2013
2570
  }
2014
2571
 
2015
2572
  const DataTableBulkActionsContext =
@@ -2056,6 +2613,16 @@ export interface DataTableBulkActionsProps<TData> {
2056
2613
  * `DataTableBulkActionsActions`, and any custom parts in any order.
2057
2614
  */
2058
2615
  children?: React.ReactNode;
2616
+ /**
2617
+ * Marks a server-side refetch as in flight — pass the same flag given to
2618
+ * the `DataTable`'s `refetching`. The bar sets `aria-busy` and
2619
+ * `DataTableBulkActionsActions` becomes inert (unfocusable and unclickable,
2620
+ * visually unchanged): bulk actions would act on stale rows about to be
2621
+ * replaced. The bar lives outside the table's subtree, so it cannot inherit
2622
+ * the flag from `DataTable` — it must be passed here too (DS-916).
2623
+ * @default false
2624
+ */
2625
+ refetching?: boolean;
2059
2626
  }
2060
2627
 
2061
2628
  /**
@@ -2094,6 +2661,7 @@ export function DataTableBulkActions<TData>({
2094
2661
  trackingLabel,
2095
2662
  className,
2096
2663
  children,
2664
+ refetching = false,
2097
2665
  }: DataTableBulkActionsProps<TData>) {
2098
2666
  const selectedCount = table.getFilteredSelectedRowModel().rows.length;
2099
2667
  // getRowCount() = the rowCount option in manual mode, the filtered row
@@ -2101,8 +2669,8 @@ export function DataTableBulkActions<TData>({
2101
2669
  const totalCount = table.getRowCount();
2102
2670
 
2103
2671
  const contextValue = React.useMemo<DataTableBulkActionsContextValue>(
2104
- () => ({ selectedCount, totalCount }),
2105
- [selectedCount, totalCount]
2672
+ () => ({ selectedCount, totalCount, refetching }),
2673
+ [selectedCount, totalCount, refetching]
2106
2674
  );
2107
2675
 
2108
2676
  if (selectedCount === 0) return null;
@@ -2110,6 +2678,7 @@ export function DataTableBulkActions<TData>({
2110
2678
  return (
2111
2679
  <DataTableBulkActionsContext.Provider value={contextValue}>
2112
2680
  <div
2681
+ aria-busy={refetching || undefined}
2113
2682
  className={cn("flex items-center gap-2.5", className)}
2114
2683
  data-hook={dataHook}
2115
2684
  data-slot="data-table-bulk-actions"
@@ -2178,11 +2747,12 @@ export function DataTableBulkActionsSummary({
2178
2747
  className,
2179
2748
  children,
2180
2749
  }: DataTableBulkActionsSummaryProps) {
2181
- const { selectedCount, totalCount } = useDataTableBulkActionsContext();
2750
+ const context = useDataTableBulkActionsContext();
2751
+ const { selectedCount, totalCount } = context;
2182
2752
 
2183
2753
  let content: React.ReactNode;
2184
2754
  if (typeof children === "function") {
2185
- content = children({ selectedCount, totalCount });
2755
+ content = children(context);
2186
2756
  } else if (children != null) {
2187
2757
  content = children;
2188
2758
  } else {
@@ -2230,17 +2800,26 @@ export interface DataTableBulkActionsActionsProps {
2230
2800
  * Optional: a single action can sit directly inside
2231
2801
  * `DataTableBulkActions`. Use this when you have several, or need them
2232
2802
  * grouped and protected from shrinking.
2803
+ *
2804
+ * While the bar's `refetching` flag is set, the slot is `inert` — its buttons
2805
+ * cannot be clicked or focused (without a disabled look), because the
2806
+ * selection they would act on is stale (DS-916).
2233
2807
  */
2234
2808
  export function DataTableBulkActionsActions({
2235
2809
  dataHook = "data-table-bulk-actions-actions",
2236
2810
  className,
2237
2811
  children,
2238
2812
  }: DataTableBulkActionsActionsProps) {
2813
+ // Read null-safely rather than via the throwing hook: the slot renders fine
2814
+ // outside the bar, it just has no refetch flag to honor there.
2815
+ const refetching =
2816
+ React.useContext(DataTableBulkActionsContext)?.refetching ?? false;
2239
2817
  return (
2240
2818
  <div
2241
2819
  className={cn("flex shrink-0 items-center gap-2", className)}
2242
2820
  data-hook={dataHook}
2243
2821
  data-slot="data-table-bulk-actions-actions"
2822
+ inert={refetching || undefined}
2244
2823
  >
2245
2824
  {children}
2246
2825
  </div>
@@ -2278,6 +2857,10 @@ export interface DataTableToolbarProps {
2278
2857
  * note on `DataTable`. The built-in vertical padding provides the spacing
2279
2858
  * between a toolbar and its table; don't add custom margins or padding.
2280
2859
  *
2860
+ * Inside a Card with a header, filters that narrow what the card shows
2861
+ * (`DataTableSearch` included) go in the header's `CardToolbar`; this toolbar
2862
+ * keeps pagination beside the table. A report card uses both.
2863
+ *
2281
2864
  * @example
2282
2865
  * <DataTableToolbar dataHook="locations-toolbar">
2283
2866
  * <DataTableToolbarLeft>