@brightlocal/ui-components 3.0.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 (235) hide show
  1. package/README.md +7 -1
  2. package/component-meta.json +749 -53
  3. package/deprecations.json +114 -4
  4. package/dist/accordion.cjs +1 -1
  5. package/dist/accordion.d.ts +36 -0
  6. package/dist/accordion.d.ts.map +1 -1
  7. package/dist/accordion.js +74 -61
  8. package/dist/alert-dialog.cjs +1 -1
  9. package/dist/alert-dialog.d.ts +32 -3
  10. package/dist/alert-dialog.d.ts.map +1 -1
  11. package/dist/alert-dialog.js +61 -58
  12. package/dist/alert.cjs +1 -1
  13. package/dist/alert.d.ts.map +1 -1
  14. package/dist/alert.js +58 -57
  15. package/dist/badge.cjs +1 -1
  16. package/dist/badge.d.ts +9 -0
  17. package/dist/badge.d.ts.map +1 -1
  18. package/dist/badge.js +50 -30
  19. package/dist/banner.cjs +1 -0
  20. package/dist/banner.d.ts +81 -0
  21. package/dist/banner.d.ts.map +1 -0
  22. package/dist/banner.js +176 -0
  23. package/dist/blocks/empty-state.cjs +1 -1
  24. package/dist/blocks/empty-state.d.ts +4 -3
  25. package/dist/blocks/empty-state.d.ts.map +1 -1
  26. package/dist/blocks/empty-state.js +50 -57
  27. package/dist/blocks/progress-state.d.ts +2 -2
  28. package/dist/blocks/sidebar.cjs +1 -1
  29. package/dist/blocks/sidebar.d.ts +17 -0
  30. package/dist/blocks/sidebar.d.ts.map +1 -1
  31. package/dist/blocks/sidebar.js +8 -2
  32. package/dist/brand-illustration-motif.d.ts +1 -1
  33. package/dist/button-group.cjs +1 -0
  34. package/dist/button-group.d.ts +36 -0
  35. package/dist/button-group.d.ts.map +1 -0
  36. package/dist/button-group.js +47 -0
  37. package/dist/button.cjs +1 -1
  38. package/dist/button.js +1 -1
  39. package/dist/card.cjs +1 -1
  40. package/dist/card.d.ts +105 -7
  41. package/dist/card.d.ts.map +1 -1
  42. package/dist/card.js +198 -101
  43. package/dist/chart.cjs +3 -3
  44. package/dist/chart.d.ts +270 -24
  45. package/dist/chart.d.ts.map +1 -1
  46. package/dist/chart.js +497 -322
  47. package/dist/checkbox.cjs +1 -1
  48. package/dist/checkbox.d.ts +1 -1
  49. package/dist/checkbox.d.ts.map +1 -1
  50. package/dist/checkbox.js +2 -1
  51. package/dist/chip.cjs +1 -1
  52. package/dist/chip.d.ts +38 -4
  53. package/dist/chip.d.ts.map +1 -1
  54. package/dist/chip.js +95 -81
  55. package/dist/combobox.cjs +1 -1
  56. package/dist/combobox.js +2 -2
  57. package/dist/command.cjs +1 -1
  58. package/dist/command.d.ts +23 -1
  59. package/dist/command.d.ts.map +1 -1
  60. package/dist/command.js +251 -225
  61. package/dist/data-table.cjs +1 -1
  62. package/dist/data-table.d.ts +201 -23
  63. package/dist/data-table.d.ts.map +1 -1
  64. package/dist/data-table.js +712 -568
  65. package/dist/date-picker.cjs +1 -1
  66. package/dist/date-picker.d.ts +13 -5
  67. package/dist/date-picker.d.ts.map +1 -1
  68. package/dist/date-picker.js +54 -53
  69. package/dist/field.cjs +1 -1
  70. package/dist/field.d.ts +8 -1
  71. package/dist/field.d.ts.map +1 -1
  72. package/dist/field.js +79 -52
  73. package/dist/global-layout.cjs +1 -1
  74. package/dist/global-layout.d.ts +105 -13
  75. package/dist/global-layout.d.ts.map +1 -1
  76. package/dist/global-layout.js +146 -129
  77. package/dist/grid.d.ts +26 -3
  78. package/dist/grid.d.ts.map +1 -1
  79. package/dist/hooks/use-breakpoint.cjs +1 -1
  80. package/dist/hooks/use-breakpoint.d.ts +1 -1
  81. package/dist/hooks/use-breakpoint.d.ts.map +1 -1
  82. package/dist/hooks/use-breakpoint.js +1 -0
  83. package/dist/hooks/use-mobile.cjs +1 -0
  84. package/dist/hooks/use-mobile.js +8 -0
  85. package/dist/index.cjs +1 -1
  86. package/dist/index.d.ts +6 -0
  87. package/dist/index.d.ts.map +1 -1
  88. package/dist/index.js +594 -553
  89. package/dist/info-tooltip.cjs +1 -0
  90. package/dist/info-tooltip.d.ts +39 -0
  91. package/dist/info-tooltip.d.ts.map +1 -0
  92. package/dist/info-tooltip.js +41 -0
  93. package/dist/input-chip.cjs +1 -1
  94. package/dist/input-chip.js +1 -1
  95. package/dist/input-group.cjs +1 -1
  96. package/dist/input-group.d.ts +33 -2
  97. package/dist/input-group.d.ts.map +1 -1
  98. package/dist/input-group.js +167 -54
  99. package/dist/input-otp.cjs +1 -1
  100. package/dist/input-otp.js +9 -9
  101. package/dist/input-password.cjs +1 -1
  102. package/dist/input-password.d.ts +45 -15
  103. package/dist/input-password.d.ts.map +1 -1
  104. package/dist/input-password.js +31 -30
  105. package/dist/input.cjs +1 -1
  106. package/dist/input.js +10 -10
  107. package/dist/lib/block-illustration.cjs +1 -1
  108. package/dist/lib/block-illustration.d.ts +4 -1
  109. package/dist/lib/block-illustration.d.ts.map +1 -1
  110. package/dist/lib/block-illustration.js +12 -11
  111. package/dist/lib/empty-chip.cjs +1 -0
  112. package/dist/lib/empty-chip.d.ts +4 -0
  113. package/dist/lib/empty-chip.d.ts.map +1 -0
  114. package/dist/lib/empty-chip.js +13 -0
  115. package/dist/lib/utils.cjs +1 -1
  116. package/dist/lib/utils.d.ts.map +1 -1
  117. package/dist/lib/utils.js +4 -3
  118. package/dist/list.cjs +1 -1
  119. package/dist/list.js +1 -1
  120. package/dist/multi-select-filter.cjs +1 -0
  121. package/dist/multi-select-filter.d.ts +178 -0
  122. package/dist/multi-select-filter.d.ts.map +1 -0
  123. package/dist/multi-select-filter.js +463 -0
  124. package/dist/pagination.cjs +1 -1
  125. package/dist/pagination.d.ts +3 -0
  126. package/dist/pagination.d.ts.map +1 -1
  127. package/dist/pagination.js +57 -57
  128. package/dist/progress.cjs +1 -1
  129. package/dist/progress.d.ts +123 -16
  130. package/dist/progress.d.ts.map +1 -1
  131. package/dist/progress.js +89 -75
  132. package/dist/rating.cjs +1 -1
  133. package/dist/rating.js +18 -18
  134. package/dist/relative-date.cjs +1 -0
  135. package/dist/relative-date.d.ts +65 -0
  136. package/dist/relative-date.d.ts.map +1 -0
  137. package/dist/relative-date.js +128 -0
  138. package/dist/scroll-area.cjs +1 -1
  139. package/dist/scroll-area.d.ts +15 -6
  140. package/dist/scroll-area.d.ts.map +1 -1
  141. package/dist/scroll-area.js +38 -36
  142. package/dist/select.cjs +2 -2
  143. package/dist/select.d.ts +24 -3
  144. package/dist/select.d.ts.map +1 -1
  145. package/dist/select.js +130 -110
  146. package/dist/sheet.cjs +1 -1
  147. package/dist/sheet.d.ts +78 -2
  148. package/dist/sheet.d.ts.map +1 -1
  149. package/dist/sheet.js +192 -85
  150. package/dist/single-select-filter.cjs +1 -0
  151. package/dist/single-select-filter.d.ts +81 -0
  152. package/dist/single-select-filter.d.ts.map +1 -0
  153. package/dist/single-select-filter.js +226 -0
  154. package/dist/sonner.cjs +1 -1
  155. package/dist/sonner.d.ts.map +1 -1
  156. package/dist/sonner.js +22 -22
  157. package/dist/split-layout.cjs +1 -1
  158. package/dist/split-layout.d.ts +1 -1
  159. package/dist/split-layout.js +13 -13
  160. package/dist/table.cjs +1 -1
  161. package/dist/table.d.ts +45 -4
  162. package/dist/table.d.ts.map +1 -1
  163. package/dist/table.js +90 -73
  164. package/dist/tabs.cjs +1 -1
  165. package/dist/tabs.d.ts +12 -1
  166. package/dist/tabs.d.ts.map +1 -1
  167. package/dist/tabs.js +148 -126
  168. package/dist/textarea.cjs +1 -1
  169. package/dist/textarea.js +1 -1
  170. package/dist/tooltip.cjs +1 -1
  171. package/dist/tooltip.d.ts +38 -36
  172. package/dist/tooltip.d.ts.map +1 -1
  173. package/dist/tooltip.js +262 -73
  174. package/dist/typography-heading.cjs +1 -1
  175. package/dist/typography-heading.d.ts +13 -0
  176. package/dist/typography-heading.d.ts.map +1 -1
  177. package/dist/typography-heading.js +32 -21
  178. package/dist/typography-text.cjs +1 -1
  179. package/dist/typography-text.d.ts +15 -2
  180. package/dist/typography-text.d.ts.map +1 -1
  181. package/dist/typography-text.js +35 -24
  182. package/dist/typography.d.ts +1 -1
  183. package/package.json +5 -6
  184. package/src/blocks/empty-state.tsx +17 -24
  185. package/src/blocks/progress-state.tsx +2 -2
  186. package/src/blocks/sidebar.tsx +26 -2
  187. package/src/components/accordion.tsx +82 -27
  188. package/src/components/alert-dialog.tsx +50 -5
  189. package/src/components/alert.tsx +16 -8
  190. package/src/components/badge.tsx +40 -3
  191. package/src/components/banner.tsx +288 -0
  192. package/src/components/brand-illustration-motif.tsx +1 -1
  193. package/src/components/button-group.tsx +112 -0
  194. package/src/components/button.tsx +1 -1
  195. package/src/components/card.tsx +249 -27
  196. package/src/components/chart.tsx +586 -53
  197. package/src/components/checkbox.tsx +1 -1
  198. package/src/components/chip.tsx +83 -10
  199. package/src/components/combobox.tsx +2 -2
  200. package/src/components/command.tsx +56 -4
  201. package/src/components/data-table.tsx +842 -199
  202. package/src/components/date-picker.tsx +18 -7
  203. package/src/components/field.tsx +81 -12
  204. package/src/components/global-layout.tsx +176 -38
  205. package/src/components/grid.tsx +34 -3
  206. package/src/components/info-tooltip.tsx +94 -0
  207. package/src/components/input-chip.tsx +1 -1
  208. package/src/components/input-group.tsx +246 -11
  209. package/src/components/input-otp.tsx +1 -1
  210. package/src/components/input-password.tsx +56 -22
  211. package/src/components/input.tsx +1 -1
  212. package/src/components/list.tsx +1 -1
  213. package/src/components/multi-select-filter.tsx +912 -0
  214. package/src/components/pagination.tsx +10 -3
  215. package/src/components/progress.tsx +190 -31
  216. package/src/components/rating.tsx +1 -1
  217. package/src/components/relative-date.tsx +230 -0
  218. package/src/components/scroll-area.tsx +23 -10
  219. package/src/components/select.tsx +65 -11
  220. package/src/components/sheet.tsx +240 -4
  221. package/src/components/single-select-filter.tsx +443 -0
  222. package/src/components/sonner.tsx +16 -5
  223. package/src/components/split-layout.tsx +2 -2
  224. package/src/components/table.tsx +71 -11
  225. package/src/components/tabs.tsx +93 -46
  226. package/src/components/textarea.tsx +1 -1
  227. package/src/components/tooltip.tsx +440 -68
  228. package/src/components/typography-heading.tsx +24 -0
  229. package/src/components/typography-text.tsx +27 -3
  230. package/src/components/typography.tsx +1 -1
  231. package/src/hooks/use-breakpoint.ts +2 -1
  232. package/src/index.ts +6 -0
  233. package/src/lib/block-illustration.tsx +5 -1
  234. package/src/lib/empty-chip.ts +24 -0
  235. 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,13 +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
+ import { useIsBelowBreakpoint } from "@brightlocal/ui-components/hooks/use-breakpoint";
63
64
  import { Button } from "./button";
64
65
  import { Checkbox } from "./checkbox";
65
- import { InputGroup, InputGroupAddon, InputGroupInput } from "./input-group";
66
+ import {
67
+ InputGroup,
68
+ InputGroupAddon,
69
+ InputGroupClear,
70
+ InputGroupInput,
71
+ } from "./input-group";
66
72
  import {
67
73
  Pagination,
68
74
  PaginationContent,
@@ -74,6 +80,7 @@ import {
74
80
  usePagination,
75
81
  } from "./pagination";
76
82
  import { Skeleton } from "./skeleton";
83
+ import { Spinner } from "./spinner";
77
84
  import {
78
85
  Table,
79
86
  TableBody,
@@ -81,6 +88,7 @@ import {
81
88
  TableHead,
82
89
  TableHeader,
83
90
  TableRow,
91
+ scrollRegionProps,
84
92
  } from "./table";
85
93
  import { TypographyMuted } from "./typography";
86
94
 
@@ -460,6 +468,22 @@ export function useDataTable<TData>(
460
468
  * rendering-focused — wire toolbars, pagination, and search components
461
469
  * outside of it via composition.
462
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
+
463
487
  export interface DataTableProps<TData> {
464
488
  /** TanStack Table instance (usually returned from `useDataTable`). */
465
489
  table: TanStackTable<TData>;
@@ -471,6 +495,32 @@ export interface DataTableProps<TData> {
471
495
  trackingLabel?: string;
472
496
  /** Show skeleton rows instead of data while loading async data. */
473
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;
474
524
  /** Number of skeleton rows when loading. Falls back to the table's page size, then 10. */
475
525
  skeletonRowCount?: number;
476
526
  /**
@@ -490,13 +540,38 @@ export interface DataTableProps<TData> {
490
540
  */
491
541
  noResultsMessage?: React.ReactNode;
492
542
  /**
493
- * Pin the `<thead>` to the top of the scroll container so column headers
494
- * remain visible while scrolling. The header keeps its opaque `bg-muted`
495
- * 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.
496
558
  * @default false
497
559
  */
498
560
  stickyHeader?: boolean;
499
- /** 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
+ */
500
575
  className?: string;
501
576
  /**
502
577
  * Table layout algorithm.
@@ -517,8 +592,23 @@ export interface DataTableProps<TData> {
517
592
  */
518
593
  minWidth?: string;
519
594
  /**
520
- * Accessible label for the scroll container region.
521
- * 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.
522
612
  * @default "Scrollable table"
523
613
  */
524
614
  scrollRegionLabel?: string;
@@ -574,13 +664,15 @@ export interface DataTableProps<TData> {
574
664
  *
575
665
  * @example
576
666
  * // One slot inside a gapped parent (dialog, card, page section).
577
- * // 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).
578
670
  * <div className="flex min-h-0 flex-1 flex-col">
579
671
  * <DataTableToolbar dataHook="toolbar-top">
580
672
  * <DataTableToolbarLeft>{heading or search}</DataTableToolbarLeft>
581
673
  * <DataTableToolbarRight>{filters}</DataTableToolbarRight>
582
674
  * </DataTableToolbar>
583
- * <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" />
584
676
  * <DataTableToolbar dataHook="toolbar-bottom">
585
677
  * <DataTableToolbarLeft>{selection counter}</DataTableToolbarLeft>
586
678
  * <DataTableToolbarRight>{pagination}</DataTableToolbarRight>
@@ -593,6 +685,8 @@ export function DataTable<TData>({
593
685
  trackingEl,
594
686
  trackingLabel,
595
687
  isLoading = false,
688
+ refetching = false,
689
+ refetchingLabel,
596
690
  skeletonRowCount,
597
691
  noResultsMessage = "No results.",
598
692
  stickyHeader = false,
@@ -608,78 +702,204 @@ export function DataTable<TData>({
608
702
  const resolvedSkeletonCount =
609
703
  skeletonRowCount ?? table.getState().pagination.pageSize ?? 10;
610
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
+
611
715
  return (
612
716
  <div
613
- aria-busy={isLoading || undefined}
614
- 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
+ )}
615
726
  data-hook={dataHook}
616
727
  data-slot="data-table-view"
617
728
  data-tracking-el={trackingEl}
618
729
  data-tracking-label={trackingLabel}
730
+ {...(isScrollRegion ? scrollRegionProps(scrollRegionLabel) : undefined)}
619
731
  >
620
- <Table
621
- dataHook={`${dataHook}-table`}
622
- layout={layout}
623
- minWidth={minWidth}
624
- scrollRegionLabel={scrollRegionLabel}
625
- >
626
- <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
627
- <TableBody>
628
- {isLoading ? (
629
- <>
630
- <LoadingRows
631
- colCount={columnCount}
632
- rowCount={resolvedSkeletonCount}
633
- />
634
- <TableRow className="sr-only">
635
- <TableCell colSpan={columnCount}>
636
- <div aria-live="polite" role="status">
637
- Loading data…
638
- </div>
639
- </TableCell>
640
- </TableRow>
641
- </>
642
- ) : (
643
- <>
644
- {table.getRowModel().rows.length > 0 ? (
645
- table
646
- .getRowModel()
647
- .rows.map((row) => (
648
- <DataTableRow
649
- key={row.id}
650
- columnCount={columnCount}
651
- getRowClassName={getRowClassName}
652
- renderExpandedContent={renderExpandedContent}
653
- row={row}
654
- />
655
- ))
656
- ) : (
657
- <TableRow>
658
- <TableCell align="center" colSpan={columnCount} size="lg">
659
- {/* 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
660
782
  as the message needs the same room here that it gets
661
783
  anywhere else, and a prop API gives the consumer nowhere
662
784
  to add it. 24 rather than 32, because this sits inside
663
785
  the cell's own 8: together they give the block its 32,
664
786
  and a one-line message still measures under `size="lg"`'s
665
787
  min-height, so the plain-string row does not move. */}
666
- <div aria-live="polite" className="py-6" role="status">
667
- {noResultsMessage}
668
- </div>
669
- </TableCell>
670
- </TableRow>
671
- )}
672
- </>
673
- )}
674
- </TableBody>
675
- {footer}
676
- </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>
677
800
  </div>
678
801
  );
679
802
  }
680
803
 
681
804
  DataTable.displayName = "DataTable";
682
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
+
683
903
  /**
684
904
  * Internal: render all header groups with `aria-sort` attributes.
685
905
  * Shared between `DataTable` and `VirtualizedDataTable`.
@@ -691,43 +911,68 @@ function DataTableHeaderRows<TData>({
691
911
  table: TanStackTable<TData>;
692
912
  stickyHeader: boolean;
693
913
  }) {
914
+ const sortOverrides = useSortOverrideStore();
694
915
  return (
695
- <TableHeader className={cn(stickyHeader && "sticky top-0 z-10")}>
696
- {table.getHeaderGroups().map((headerGroup) => (
697
- <TableRow key={headerGroup.id}>
698
- {headerGroup.headers.map((header) => {
699
- const sortDirection = header.column.getCanSort()
700
- ? header.column.getIsSorted()
701
- : false;
702
- const ariaSort =
703
- sortDirection === "asc"
704
- ? "ascending"
705
- : sortDirection === "desc"
706
- ? "descending"
707
- : header.column.getCanSort()
708
- ? "none"
709
- : undefined;
710
- const meta = header.column.columnDef.meta;
711
- return (
712
- <TableHead
713
- key={header.id}
714
- aria-sort={ariaSort}
715
- colSpan={header.colSpan}
716
- minWidth={meta?.minWidth}
717
- width={meta?.width}
718
- >
719
- {header.isPlaceholder
720
- ? null
721
- : flexRender(
722
- header.column.columnDef.header,
723
- header.getContext()
724
- )}
725
- </TableHead>
726
- );
727
- })}
728
- </TableRow>
729
- ))}
730
- </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>
731
976
  );
732
977
  }
733
978
 
@@ -898,6 +1143,8 @@ export function VirtualizedDataTable<TData>({
898
1143
  trackingEl,
899
1144
  trackingLabel,
900
1145
  isLoading = false,
1146
+ refetching = false,
1147
+ refetchingLabel,
901
1148
  skeletonRowCount,
902
1149
  noResultsMessage = "No results.",
903
1150
  stickyHeader = false,
@@ -940,74 +1187,99 @@ export function VirtualizedDataTable<TData>({
940
1187
  return (
941
1188
  <div
942
1189
  ref={scrollContainerRef}
943
- aria-busy={isLoading || undefined}
944
- 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
+ )}
945
1202
  data-hook={dataHook}
946
1203
  data-slot="data-table-view"
947
1204
  data-tracking-el={trackingEl}
948
1205
  data-tracking-label={trackingLabel}
949
1206
  style={height != null ? { height } : undefined}
1207
+ {...scrollRegionProps(scrollRegionLabel)}
950
1208
  >
951
- <Table
952
- dataHook={`${dataHook}-table`}
953
- layout={layout}
954
- minWidth={minWidth}
955
- scrollRegionLabel={scrollRegionLabel}
956
- >
957
- <DataTableHeaderRows stickyHeader={stickyHeader} table={table} />
958
- <TableBody>
959
- {isLoading ? (
960
- <>
961
- <LoadingRows
962
- colCount={columnCount}
963
- rowCount={resolvedSkeletonCount}
964
- />
965
- <TableRow className="sr-only">
966
- <TableCell colSpan={columnCount}>
967
- <div aria-live="polite" role="status">
968
- 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}
969
1275
  </div>
970
1276
  </TableCell>
971
1277
  </TableRow>
972
- </>
973
- ) : rows.length > 0 ? (
974
- <>
975
- {paddingTop > 0 && (
976
- <tr aria-hidden="true">
977
- <td colSpan={columnCount} style={{ height: paddingTop }} />
978
- </tr>
979
- )}
980
- {virtualItems.map((virtualItem) => {
981
- const row = rows[virtualItem.index]!;
982
- return (
983
- <DataTableRow
984
- key={row.id}
985
- columnCount={columnCount}
986
- getRowClassName={getRowClassName}
987
- row={row}
988
- />
989
- );
990
- })}
991
- {paddingBottom > 0 && (
992
- <tr aria-hidden="true">
993
- <td colSpan={columnCount} style={{ height: paddingBottom }} />
994
- </tr>
995
- )}
996
- </>
997
- ) : (
998
- <TableRow>
999
- <TableCell align="center" colSpan={columnCount} size="lg">
1000
- {/* Padded for a block — see the note on the non-virtualised
1001
- table's no-results cell. */}
1002
- <div aria-live="polite" className="py-6" role="status">
1003
- {noResultsMessage}
1004
- </div>
1005
- </TableCell>
1006
- </TableRow>
1007
- )}
1008
- </TableBody>
1009
- {footer}
1010
- </Table>
1278
+ )}
1279
+ </TableBody>
1280
+ {footer}
1281
+ </Table>
1282
+ </DataTableRefetchingContext.Provider>
1011
1283
  </div>
1012
1284
  );
1013
1285
  }
@@ -1041,9 +1313,35 @@ export interface DataTableColumnHeaderProps<
1041
1313
  /**
1042
1314
  * Builds the accessible label for the sort button.
1043
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.
1044
1318
  * @default (title, dir) => `Sort by ${title}${dir ? `, currently ${dir === "asc" ? "ascending" : "descending"}` : ""}`
1045
1319
  */
1046
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;
1047
1345
  }
1048
1346
 
1049
1347
  /**
@@ -1052,6 +1350,20 @@ export interface DataTableColumnHeaderProps<
1052
1350
  * Falls back to a non-interactive label when the column is not sortable.
1053
1351
  * Otherwise renders a ghost button that toggles sort on click, with an
1054
1352
  * accessible label describing the current sort state.
1353
+ *
1354
+ * **First-click direction:** clicking an unsorted column starts ascending
1355
+ * (A–Z, lowest first). Numeric columns (counts, rates, scores) usually want
1356
+ * highest-first on the first click — opt in per column with TanStack's
1357
+ * `sortDescFirst` on the column def:
1358
+ *
1359
+ * ```tsx
1360
+ * { accessorKey: "score", sortDescFirst: true, header: ... }
1361
+ * ```
1362
+ *
1363
+ * Only an explicit `sortDescFirst` is honoured — TanStack's automatic
1364
+ * "numbers sort descending first" detection is deliberately not consulted,
1365
+ * so tables that do not opt in keep first-click-ascending. Once a column is
1366
+ * sorted, clicking again reverses the direction as before.
1055
1367
  */
1056
1368
  export function DataTableColumnHeader<TData, TValue>({
1057
1369
  column,
@@ -1062,7 +1374,74 @@ export function DataTableColumnHeader<TData, TValue>({
1062
1374
  trackingLabel,
1063
1375
  align = "left",
1064
1376
  getSortLabel,
1377
+ loading = false,
1065
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
+
1066
1445
  if (!column.getCanSort()) {
1067
1446
  return (
1068
1447
  <div
@@ -1082,12 +1461,19 @@ export function DataTableColumnHeader<TData, TValue>({
1082
1461
  );
1083
1462
  }
1084
1463
 
1085
- const sortState = column.getIsSorted();
1464
+ // First click on an unsorted column follows the column def's explicit
1465
+ // `sortDescFirst`; later clicks reverse the current direction. TanStack's
1466
+ // `getFirstSortDir()` is not used here — its automatic numeric detection
1467
+ // would silently flip existing tables to descending-first (DS-953).
1468
+ const nextSortDesc =
1469
+ currentSort === false
1470
+ ? column.columnDef.sortDescFirst === true
1471
+ : currentSort === "asc";
1086
1472
  const sortLabel = getSortLabel
1087
- ? getSortLabel(title, sortState)
1088
- : sortState === "desc"
1473
+ ? getSortLabel(title, displayedSort)
1474
+ : displayedSort === "desc"
1089
1475
  ? `Sort by ${title}, currently descending`
1090
- : sortState === "asc"
1476
+ : displayedSort === "asc"
1091
1477
  ? `Sort by ${title}, currently ascending`
1092
1478
  : `Sort by ${title}`;
1093
1479
 
@@ -1104,21 +1490,30 @@ export function DataTableColumnHeader<TData, TValue>({
1104
1490
  data-tracking-label={trackingLabel}
1105
1491
  >
1106
1492
  <Button
1493
+ aria-busy={loading ? "true" : undefined}
1107
1494
  aria-label={sortLabel}
1108
1495
  className="text-muted-foreground text-label h-auto p-0 font-semibold"
1109
1496
  dataHook={dataHook || `column-header-${column.id}`}
1110
1497
  size="sm"
1111
1498
  variant="ghost"
1112
- onClick={() => column.toggleSorting(sortState === "asc")}
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
+ }}
1113
1506
  >
1114
1507
  <span aria-hidden="true">{title}</span>
1115
1508
  <span
1116
1509
  aria-hidden="true"
1117
1510
  className="flex size-3 items-center justify-center"
1118
1511
  >
1119
- {sortState === "desc" ? (
1512
+ {sortRefetching ? (
1513
+ <Spinner size="sm" />
1514
+ ) : displayedSort === "desc" ? (
1120
1515
  <ArrowDown size={12} />
1121
- ) : sortState === "asc" ? (
1516
+ ) : displayedSort === "asc" ? (
1122
1517
  <ArrowUp size={12} />
1123
1518
  ) : (
1124
1519
  <ArrowUpDown size={12} />
@@ -1154,8 +1549,38 @@ export interface DataTableSearchProps<TData> extends Omit<
1154
1549
  placeholder?: string;
1155
1550
  /** Accessible label for the clear button. @default "Clear search" */
1156
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;
1157
1573
  }
1158
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
+
1159
1584
  /**
1160
1585
  * Search input for filtering DataTable rows.
1161
1586
  *
@@ -1164,48 +1589,170 @@ export interface DataTableSearchProps<TData> extends Omit<
1164
1589
  * customize width or shape.
1165
1590
  *
1166
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").
1167
1598
  */
1168
1599
  export function DataTableSearch<TData>({
1169
1600
  table,
1170
1601
  ariaLabel,
1171
1602
  placeholder,
1172
1603
  clearSearchAriaLabel,
1604
+ loading = false,
1605
+ debounceMs,
1173
1606
  ...inputGroupProps
1174
1607
  }: DataTableSearchProps<TData>) {
1175
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
+ }
1176
1713
 
1177
- const handleFilterChange = (value: string) => {
1178
- 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("");
1179
1720
  };
1180
1721
 
1181
1722
  return (
1182
- <InputGroup data-slot="data-table-search" {...inputGroupProps}>
1723
+ <InputGroup
1724
+ aria-busy={loading ? "true" : undefined}
1725
+ data-slot="data-table-search"
1726
+ {...inputGroupProps}
1727
+ >
1183
1728
  <InputGroupAddon className="pl-3">
1184
- <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
+ )}
1185
1736
  </InputGroupAddon>
1186
1737
  <InputGroupInput
1187
1738
  aria-label={ariaLabel ?? "Search table"}
1188
1739
  placeholder={placeholder ?? "Search..."}
1189
1740
  type="text"
1190
- value={filterValue}
1191
- 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}
1192
1755
  />
1193
- {filterValue && (
1194
- <InputGroupAddon className="pr-1">
1195
- <Button
1196
- aria-label={clearSearchAriaLabel ?? "Clear search"}
1197
- /* Fixed square hit area — h-auto p-1 let the ghost hover hug the
1198
- 14px icon into a squashed pill. */
1199
- className="size-6 p-0"
1200
- data-slot="data-table-search-clear"
1201
- dataHook={`${inputGroupProps.dataHook}-clear`}
1202
- variant="ghost"
1203
- onClick={() => handleFilterChange("")}
1204
- >
1205
- <X size={14} />
1206
- </Button>
1207
- </InputGroupAddon>
1208
- )}
1209
1756
  </InputGroup>
1210
1757
  );
1211
1758
  }
@@ -1369,6 +1916,8 @@ export interface DataTablePaginationRowCountProps {
1369
1916
  *
1370
1917
  * Renders "start–end of total" by default. Pass `renderText` for i18n-friendly
1371
1918
  * custom text with full control over wording, pluralization, and order.
1919
+ * Renders nothing below the `sm` viewport breakpoint — on small screens the
1920
+ * label is removed so the page buttons get the full width (DS-998).
1372
1921
  *
1373
1922
  * Must be rendered inside `<DataTablePagination>`.
1374
1923
  */
@@ -1377,8 +1926,14 @@ function DataTablePaginationRowCount({
1377
1926
  className,
1378
1927
  }: DataTablePaginationRowCountProps) {
1379
1928
  const { info } = useDataTablePaginationContext();
1929
+ const isMobile = useIsBelowBreakpoint("sm");
1380
1930
  const { startRow, endRow, totalRows, pageIndex, pageSize } = info;
1381
1931
 
1932
+ // Below `sm` the label is removed so the page buttons get the full width
1933
+ // and centre (DS-998) — same rule as the default layout and
1934
+ // `PaginationControls`.
1935
+ if (isMobile) return null;
1936
+
1382
1937
  const content = renderText
1383
1938
  ? renderText({ startRow, endRow, totalRows, pageIndex, pageSize })
1384
1939
  : totalRows === 0
@@ -1389,7 +1944,10 @@ function DataTablePaginationRowCount({
1389
1944
 
1390
1945
  return (
1391
1946
  <span
1392
- className={cn("text-body-sm text-muted-foreground", className)}
1947
+ className={cn(
1948
+ "text-body-sm text-muted-foreground whitespace-nowrap",
1949
+ className
1950
+ )}
1393
1951
  data-slot="data-table-pagination-row-count"
1394
1952
  >
1395
1953
  {content}
@@ -1417,7 +1975,8 @@ export interface DataTablePaginationNavProps {
1417
1975
  *
1418
1976
  * Renders previous/next buttons and page links. Renders nothing when there
1419
1977
  * is at most one page — navigation controls are noise when there is nowhere
1420
- * to navigate. Must be rendered inside `<DataTablePagination>`.
1978
+ * to navigate. Below the `sm` viewport breakpoint the buttons centre in the
1979
+ * available width (DS-998). Must be rendered inside `<DataTablePagination>`.
1421
1980
  */
1422
1981
  function DataTablePaginationNav({
1423
1982
  ariaLabel = "Table pagination",
@@ -1425,6 +1984,7 @@ function DataTablePaginationNav({
1425
1984
  className,
1426
1985
  }: DataTablePaginationNavProps) {
1427
1986
  const { info } = useDataTablePaginationContext();
1987
+ const isMobile = useIsBelowBreakpoint("sm");
1428
1988
 
1429
1989
  const paginationItems = usePagination({
1430
1990
  page: info.currentPage,
@@ -1438,7 +1998,9 @@ function DataTablePaginationNav({
1438
1998
  return (
1439
1999
  <Pagination
1440
2000
  ariaLabel={ariaLabel}
1441
- className={cn("mx-0 w-auto justify-end", className)}
2001
+ // Below `sm` keep the base centred layout (the row count is removed
2002
+ // there); at `sm` and up hug the content and align right.
2003
+ className={cn(!isMobile && "mx-0 w-auto justify-end", className)}
1442
2004
  dataHook={dataHook ?? "pagination-nav"}
1443
2005
  >
1444
2006
  <PaginationContent>
@@ -1551,6 +2113,20 @@ export interface DataTablePaginationProps<TData> {
1551
2113
  * row count and the nav are empty, the component renders nothing — no
1552
2114
  * consumer render gate needed.
1553
2115
  *
2116
+ * **Responsive behaviour:** below the `sm` viewport breakpoint the row-count
2117
+ * label is removed and the page buttons centre in the available width — the
2118
+ * same rule `PaginationControls` follows for its caption. This applies to
2119
+ * both layouts: the default row count and `DataTablePaginationRowCount`
2120
+ * render nothing below `sm`, and `DataTablePaginationNav` centres itself.
2121
+ * From `sm` up the bar wraps inside narrow containers: when the row count
2122
+ * and the page buttons no longer fit on one line, the buttons move to their
2123
+ * own line below the row count — no consumer layout classes needed. The row
2124
+ * of page buttons itself does not wrap or shrink, so the **minimum supported
2125
+ * container width** is the width of the button row: **300px** below the `sm`
2126
+ * viewport breakpoint (compact five-slot list) and **388px** from `sm` up
2127
+ * (seven-slot list). Narrower containers than that are outside the
2128
+ * component's supported range (DS-998).
2129
+ *
1554
2130
  * **Compositional mode** (with children): acts as a context provider.
1555
2131
  * Compose `DataTablePaginationRowCount` and `DataTablePaginationNav`
1556
2132
  * in any order/layout.
@@ -1588,6 +2164,7 @@ export function DataTablePagination<TData>({
1588
2164
  children,
1589
2165
  }: DataTablePaginationProps<TData>) {
1590
2166
  const info = useDataTablePagination(table);
2167
+ const isMobile = useIsBelowBreakpoint("sm");
1591
2168
 
1592
2169
  const contextValue = React.useMemo<DataTablePaginationContextValue>(
1593
2170
  () => ({ info }),
@@ -1605,7 +2182,10 @@ export function DataTablePagination<TData>({
1605
2182
  return (
1606
2183
  <DataTablePaginationContext.Provider value={contextValue}>
1607
2184
  <div
1608
- className={cn("flex w-full items-center gap-4", className)}
2185
+ className={cn(
2186
+ "flex w-full flex-wrap items-center gap-x-4 gap-y-2",
2187
+ className
2188
+ )}
1609
2189
  {...wrapperDataAttrs}
1610
2190
  >
1611
2191
  {children}
@@ -1615,6 +2195,9 @@ export function DataTablePagination<TData>({
1615
2195
  }
1616
2196
 
1617
2197
  const rowCountContent = (() => {
2198
+ // Below `sm` the label is removed so the page buttons get the full width
2199
+ // and centre (DS-998).
2200
+ if (isMobile) return null;
1618
2201
  if (!showRowCount) return null;
1619
2202
  if (renderRowCount === null) return null;
1620
2203
  if (renderRowCount) {
@@ -1638,19 +2221,20 @@ export function DataTablePagination<TData>({
1638
2221
  <DataTablePaginationContext.Provider value={contextValue}>
1639
2222
  <div
1640
2223
  className={cn(
1641
- "flex min-h-9 w-full items-center gap-4",
2224
+ "flex min-h-9 w-full flex-wrap items-center gap-x-4 gap-y-2",
1642
2225
  rowCountContent != null ? "justify-between" : "justify-end",
1643
2226
  className
1644
2227
  )}
1645
2228
  {...wrapperDataAttrs}
1646
2229
  >
1647
2230
  {rowCountContent != null && (
1648
- <span className="text-body-sm text-muted-foreground">
2231
+ <span className="text-body-sm text-muted-foreground whitespace-nowrap">
1649
2232
  {rowCountContent}
1650
2233
  </span>
1651
2234
  )}
1652
2235
  <DataTablePaginationNav
1653
2236
  ariaLabel={ariaLabel}
2237
+ className="grow"
1654
2238
  dataHook={`${dataHook}-nav`}
1655
2239
  />
1656
2240
  </div>
@@ -1684,6 +2268,11 @@ export interface DataTableSelectAllCheckboxProps<TData> {
1684
2268
  /**
1685
2269
  * Header checkbox for selecting all visible page rows. Renders as
1686
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).
1687
2276
  */
1688
2277
  export function DataTableSelectAllCheckbox<TData>({
1689
2278
  table,
@@ -1692,8 +2281,10 @@ export function DataTableSelectAllCheckbox<TData>({
1692
2281
  trackingLabel,
1693
2282
  selectAllAriaLabel,
1694
2283
  }: DataTableSelectAllCheckboxProps<TData>) {
2284
+ const refetching = React.useContext(DataTableRefetchingContext);
1695
2285
  return (
1696
2286
  <Checkbox
2287
+ aria-disabled={refetching || undefined}
1697
2288
  aria-label={selectAllAriaLabel ?? "Select all"}
1698
2289
  checked={
1699
2290
  table.getIsAllPageRowsSelected() ||
@@ -1702,7 +2293,13 @@ export function DataTableSelectAllCheckbox<TData>({
1702
2293
  dataHook={dataHook || "select-all-checkbox"}
1703
2294
  trackingEl={trackingEl}
1704
2295
  trackingLabel={trackingLabel}
1705
- 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
+ }}
1706
2303
  />
1707
2304
  );
1708
2305
  }
@@ -1727,6 +2324,11 @@ export interface DataTableSelectRowCheckboxProps<TData> {
1727
2324
 
1728
2325
  /**
1729
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).
1730
2332
  */
1731
2333
  export function DataTableSelectRowCheckbox<TData>({
1732
2334
  row,
@@ -1735,15 +2337,23 @@ export function DataTableSelectRowCheckbox<TData>({
1735
2337
  trackingLabel,
1736
2338
  selectRowAriaLabel,
1737
2339
  }: DataTableSelectRowCheckboxProps<TData>) {
2340
+ const refetching = React.useContext(DataTableRefetchingContext);
1738
2341
  return (
1739
2342
  <Checkbox
2343
+ aria-disabled={refetching || undefined}
1740
2344
  aria-label={selectRowAriaLabel ?? "Select row"}
1741
2345
  checked={row.getIsSelected()}
1742
2346
  dataHook={dataHook || `select-row-${row.id}`}
1743
2347
  disabled={!row.getCanSelect()}
1744
2348
  trackingEl={trackingEl}
1745
2349
  trackingLabel={trackingLabel}
1746
- 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
+ }}
1747
2357
  />
1748
2358
  );
1749
2359
  }
@@ -1950,6 +2560,13 @@ export interface DataTableBulkActionsContextValue {
1950
2560
  * `useDataTable` — the same option `DataTablePagination` relies on.
1951
2561
  */
1952
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;
1953
2570
  }
1954
2571
 
1955
2572
  const DataTableBulkActionsContext =
@@ -1996,6 +2613,16 @@ export interface DataTableBulkActionsProps<TData> {
1996
2613
  * `DataTableBulkActionsActions`, and any custom parts in any order.
1997
2614
  */
1998
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;
1999
2626
  }
2000
2627
 
2001
2628
  /**
@@ -2034,6 +2661,7 @@ export function DataTableBulkActions<TData>({
2034
2661
  trackingLabel,
2035
2662
  className,
2036
2663
  children,
2664
+ refetching = false,
2037
2665
  }: DataTableBulkActionsProps<TData>) {
2038
2666
  const selectedCount = table.getFilteredSelectedRowModel().rows.length;
2039
2667
  // getRowCount() = the rowCount option in manual mode, the filtered row
@@ -2041,8 +2669,8 @@ export function DataTableBulkActions<TData>({
2041
2669
  const totalCount = table.getRowCount();
2042
2670
 
2043
2671
  const contextValue = React.useMemo<DataTableBulkActionsContextValue>(
2044
- () => ({ selectedCount, totalCount }),
2045
- [selectedCount, totalCount]
2672
+ () => ({ selectedCount, totalCount, refetching }),
2673
+ [selectedCount, totalCount, refetching]
2046
2674
  );
2047
2675
 
2048
2676
  if (selectedCount === 0) return null;
@@ -2050,6 +2678,7 @@ export function DataTableBulkActions<TData>({
2050
2678
  return (
2051
2679
  <DataTableBulkActionsContext.Provider value={contextValue}>
2052
2680
  <div
2681
+ aria-busy={refetching || undefined}
2053
2682
  className={cn("flex items-center gap-2.5", className)}
2054
2683
  data-hook={dataHook}
2055
2684
  data-slot="data-table-bulk-actions"
@@ -2118,11 +2747,12 @@ export function DataTableBulkActionsSummary({
2118
2747
  className,
2119
2748
  children,
2120
2749
  }: DataTableBulkActionsSummaryProps) {
2121
- const { selectedCount, totalCount } = useDataTableBulkActionsContext();
2750
+ const context = useDataTableBulkActionsContext();
2751
+ const { selectedCount, totalCount } = context;
2122
2752
 
2123
2753
  let content: React.ReactNode;
2124
2754
  if (typeof children === "function") {
2125
- content = children({ selectedCount, totalCount });
2755
+ content = children(context);
2126
2756
  } else if (children != null) {
2127
2757
  content = children;
2128
2758
  } else {
@@ -2170,17 +2800,26 @@ export interface DataTableBulkActionsActionsProps {
2170
2800
  * Optional: a single action can sit directly inside
2171
2801
  * `DataTableBulkActions`. Use this when you have several, or need them
2172
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).
2173
2807
  */
2174
2808
  export function DataTableBulkActionsActions({
2175
2809
  dataHook = "data-table-bulk-actions-actions",
2176
2810
  className,
2177
2811
  children,
2178
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;
2179
2817
  return (
2180
2818
  <div
2181
2819
  className={cn("flex shrink-0 items-center gap-2", className)}
2182
2820
  data-hook={dataHook}
2183
2821
  data-slot="data-table-bulk-actions-actions"
2822
+ inert={refetching || undefined}
2184
2823
  >
2185
2824
  {children}
2186
2825
  </div>
@@ -2218,6 +2857,10 @@ export interface DataTableToolbarProps {
2218
2857
  * note on `DataTable`. The built-in vertical padding provides the spacing
2219
2858
  * between a toolbar and its table; don't add custom margins or padding.
2220
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
+ *
2221
2864
  * @example
2222
2865
  * <DataTableToolbar dataHook="locations-toolbar">
2223
2866
  * <DataTableToolbarLeft>