@brightlocal/ui-components 3.4.0 → 3.5.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 (196) hide show
  1. package/AI_USAGE.md +22 -3
  2. package/README.md +177 -109
  3. package/component-meta.json +1061 -102
  4. package/dist/alert-dialog.cjs +1 -1
  5. package/dist/alert-dialog.d.ts +13 -2
  6. package/dist/alert-dialog.d.ts.map +1 -1
  7. package/dist/alert-dialog.js +4 -3
  8. package/dist/banner.cjs +1 -1
  9. package/dist/banner.d.ts +47 -11
  10. package/dist/banner.d.ts.map +1 -1
  11. package/dist/banner.js +156 -79
  12. package/dist/blocks/empty-state.cjs +1 -1
  13. package/dist/blocks/empty-state.d.ts +40 -5
  14. package/dist/blocks/empty-state.d.ts.map +1 -1
  15. package/dist/blocks/empty-state.js +59 -52
  16. package/dist/blocks/input-list.d.ts +1 -0
  17. package/dist/blocks/input-list.d.ts.map +1 -1
  18. package/dist/blocks/sidebar.cjs +1 -1
  19. package/dist/blocks/sidebar.d.ts +12 -6
  20. package/dist/blocks/sidebar.d.ts.map +1 -1
  21. package/dist/blocks/sidebar.js +64 -63
  22. package/dist/button.cjs +1 -1
  23. package/dist/button.d.ts.map +1 -1
  24. package/dist/button.js +47 -43
  25. package/dist/card.cjs +1 -1
  26. package/dist/card.d.ts +12 -0
  27. package/dist/card.d.ts.map +1 -1
  28. package/dist/card.js +115 -97
  29. package/dist/chart.cjs +6 -6
  30. package/dist/chart.d.ts +6 -10
  31. package/dist/chart.d.ts.map +1 -1
  32. package/dist/chart.js +281 -296
  33. package/dist/combobox.cjs +3 -3
  34. package/dist/combobox.d.ts.map +1 -1
  35. package/dist/combobox.js +430 -343
  36. package/dist/command.cjs +1 -1
  37. package/dist/command.d.ts +23 -2
  38. package/dist/command.d.ts.map +1 -1
  39. package/dist/command.js +212 -207
  40. package/dist/count-indicator.cjs +1 -0
  41. package/dist/count-indicator.d.ts +85 -0
  42. package/dist/count-indicator.d.ts.map +1 -0
  43. package/dist/count-indicator.js +72 -0
  44. package/dist/data-table.cjs +1 -1
  45. package/dist/data-table.d.ts +101 -11
  46. package/dist/data-table.d.ts.map +1 -1
  47. package/dist/data-table.js +593 -523
  48. package/dist/dialog.cjs +1 -1
  49. package/dist/dialog.d.ts +26 -3
  50. package/dist/dialog.d.ts.map +1 -1
  51. package/dist/dialog.js +62 -47
  52. package/dist/drawer.cjs +1 -1
  53. package/dist/drawer.d.ts +8 -4
  54. package/dist/drawer.d.ts.map +1 -1
  55. package/dist/drawer.js +37 -38
  56. package/dist/file-upload.cjs +1 -0
  57. package/dist/file-upload.d.ts +546 -0
  58. package/dist/file-upload.d.ts.map +1 -0
  59. package/dist/file-upload.js +1103 -0
  60. package/dist/global-layout.cjs +1 -1
  61. package/dist/global-layout.d.ts +7 -2
  62. package/dist/global-layout.d.ts.map +1 -1
  63. package/dist/global-layout.js +52 -52
  64. package/dist/hooks/use-file-dropzone.cjs +1 -0
  65. package/dist/hooks/use-file-dropzone.d.ts +75 -0
  66. package/dist/hooks/use-file-dropzone.d.ts.map +1 -0
  67. package/dist/hooks/use-file-dropzone.js +133 -0
  68. package/dist/hover-card.cjs +1 -1
  69. package/dist/hover-card.d.ts +29 -16
  70. package/dist/hover-card.d.ts.map +1 -1
  71. package/dist/hover-card.js +153 -36
  72. package/dist/index.cjs +1 -1
  73. package/dist/index.d.ts +3 -0
  74. package/dist/index.d.ts.map +1 -1
  75. package/dist/index.js +676 -640
  76. package/dist/input-chip.cjs +1 -1
  77. package/dist/input-chip.d.ts +30 -1
  78. package/dist/input-chip.d.ts.map +1 -1
  79. package/dist/input-chip.js +131 -115
  80. package/dist/input-group.cjs +1 -1
  81. package/dist/input-group.d.ts +37 -2
  82. package/dist/input-group.d.ts.map +1 -1
  83. package/dist/input-group.js +131 -114
  84. package/dist/input-password.cjs +1 -1
  85. package/dist/input-password.js +6 -6
  86. package/dist/lib/empty-canvas.cjs +1 -1
  87. package/dist/lib/empty-canvas.d.ts +27 -1
  88. package/dist/lib/empty-canvas.d.ts.map +1 -1
  89. package/dist/lib/empty-canvas.js +27 -23
  90. package/dist/lib/empty-chip.cjs +1 -1
  91. package/dist/lib/empty-chip.d.ts +19 -2
  92. package/dist/lib/empty-chip.d.ts.map +1 -1
  93. package/dist/lib/empty-chip.js +14 -9
  94. package/dist/lib/field-aria.cjs +1 -1
  95. package/dist/lib/field-aria.d.ts +4 -4
  96. package/dist/lib/field-aria.d.ts.map +1 -1
  97. package/dist/lib/field-aria.js +7 -5
  98. package/dist/lib/media-viewer-content.cjs +1 -1
  99. package/dist/lib/media-viewer-content.js +1 -1
  100. package/dist/lib/table-internal.cjs +1 -1
  101. package/dist/lib/table-internal.d.ts +19 -0
  102. package/dist/lib/table-internal.d.ts.map +1 -1
  103. package/dist/lib/table-internal.js +22 -7
  104. package/dist/list.cjs +1 -1
  105. package/dist/list.d.ts +13 -0
  106. package/dist/list.d.ts.map +1 -1
  107. package/dist/list.js +103 -82
  108. package/dist/logo-mark.cjs +1 -1
  109. package/dist/logo-mark.d.ts +18 -2
  110. package/dist/logo-mark.d.ts.map +1 -1
  111. package/dist/logo-mark.js +159 -79
  112. package/dist/media-empty.cjs +1 -1
  113. package/dist/media-empty.d.ts +50 -7
  114. package/dist/media-empty.d.ts.map +1 -1
  115. package/dist/media-empty.js +14 -13
  116. package/dist/media-viewer.cjs +1 -1
  117. package/dist/media-viewer.js +6 -6
  118. package/dist/multi-select-filter.cjs +1 -1
  119. package/dist/multi-select-filter.d.ts.map +1 -1
  120. package/dist/multi-select-filter.js +92 -101
  121. package/dist/pagination.cjs +1 -1
  122. package/dist/pagination.d.ts +11 -0
  123. package/dist/pagination.d.ts.map +1 -1
  124. package/dist/pagination.js +17 -17
  125. package/dist/relative-date.d.ts +6 -0
  126. package/dist/relative-date.d.ts.map +1 -1
  127. package/dist/resizable.d.ts +1 -1
  128. package/dist/result-count.cjs +1 -1
  129. package/dist/result-count.d.ts +13 -16
  130. package/dist/result-count.d.ts.map +1 -1
  131. package/dist/result-count.js +24 -33
  132. package/dist/sheet.cjs +1 -1
  133. package/dist/sheet.d.ts +22 -3
  134. package/dist/sheet.d.ts.map +1 -1
  135. package/dist/sheet.js +152 -125
  136. package/dist/single-select-filter.cjs +1 -1
  137. package/dist/single-select-filter.d.ts.map +1 -1
  138. package/dist/single-select-filter.js +67 -76
  139. package/dist/table.cjs +1 -1
  140. package/dist/table.d.ts.map +1 -1
  141. package/dist/table.js +77 -76
  142. package/dist/tabs.cjs +1 -1
  143. package/dist/tabs.d.ts +39 -3
  144. package/dist/tabs.d.ts.map +1 -1
  145. package/dist/tabs.js +127 -76
  146. package/dist/textarea.cjs +1 -1
  147. package/dist/textarea.d.ts +34 -0
  148. package/dist/textarea.d.ts.map +1 -1
  149. package/dist/textarea.js +115 -19
  150. package/dist/tooltip.cjs +1 -1
  151. package/dist/tooltip.d.ts.map +1 -1
  152. package/dist/tooltip.js +137 -131
  153. package/dist/typography-text.cjs +1 -1
  154. package/dist/typography-text.d.ts +6 -2
  155. package/dist/typography-text.d.ts.map +1 -1
  156. package/dist/typography-text.js +14 -13
  157. package/package.json +3 -4
  158. package/src/blocks/empty-state.tsx +108 -48
  159. package/src/blocks/input-list.tsx +1 -0
  160. package/src/blocks/sidebar.tsx +39 -16
  161. package/src/components/alert-dialog.tsx +18 -2
  162. package/src/components/banner.tsx +247 -68
  163. package/src/components/button.tsx +27 -10
  164. package/src/components/card.tsx +89 -7
  165. package/src/components/chart.tsx +47 -67
  166. package/src/components/combobox.tsx +221 -12
  167. package/src/components/command.tsx +83 -37
  168. package/src/components/count-indicator.tsx +188 -0
  169. package/src/components/data-table.tsx +506 -159
  170. package/src/components/dialog.tsx +74 -5
  171. package/src/components/drawer.tsx +52 -32
  172. package/src/components/file-upload.tsx +2574 -0
  173. package/src/components/global-layout.tsx +18 -5
  174. package/src/components/hover-card.tsx +395 -65
  175. package/src/components/input-chip.tsx +67 -2
  176. package/src/components/input-group.tsx +89 -6
  177. package/src/components/list.tsx +40 -3
  178. package/src/components/logo-mark.tsx +109 -25
  179. package/src/components/media-empty.tsx +62 -7
  180. package/src/components/multi-select-filter.tsx +9 -16
  181. package/src/components/pagination.tsx +15 -2
  182. package/src/components/relative-date.tsx +6 -0
  183. package/src/components/result-count.tsx +27 -54
  184. package/src/components/sheet.tsx +86 -8
  185. package/src/components/single-select-filter.tsx +9 -16
  186. package/src/components/table.tsx +16 -1
  187. package/src/components/tabs.tsx +223 -41
  188. package/src/components/textarea.tsx +271 -4
  189. package/src/components/tooltip.tsx +29 -2
  190. package/src/components/typography-text.tsx +7 -2
  191. package/src/hooks/use-file-dropzone.ts +325 -0
  192. package/src/index.ts +3 -0
  193. package/src/lib/empty-canvas.tsx +47 -20
  194. package/src/lib/empty-chip.tsx +38 -3
  195. package/src/lib/field-aria.tsx +11 -6
  196. package/src/lib/table-internal.ts +38 -0
@@ -58,8 +58,10 @@ declare module "@tanstack/react-table" {
58
58
  * (DS-1205). Pin ONE column — the first, normally; two pinned columns
59
59
  * would stack on the same edge. The pinned header and body cells get an
60
60
  * opaque background that follows the row state (selected, expanded,
61
- * sub-row) and a divider on the pinned edge. Only has a visible effect
62
- * when the table scrolls horizontally (`minWidth`).
61
+ * sub-row) and a divider on the pinned edge. The pin is live only while
62
+ * the table is wider than its view (`minWidth`, column min widths or wide
63
+ * content on a narrow screen); a table that fits draws no pin and no
64
+ * divider, and `data-pinned="left"` marks the cells only while it is live.
63
65
  */
64
66
  pinned?: "left";
65
67
  }
@@ -89,6 +91,7 @@ import {
89
91
  } from "@brightlocal/icons";
90
92
 
91
93
  import { cn } from "@brightlocal/ui-components/lib/utils";
94
+ import { useDevWarning } from "@brightlocal/ui-components/lib/use-dev-warning";
92
95
  import { useIsBelowBreakpoint } from "@brightlocal/ui-components/hooks/use-breakpoint";
93
96
  import { useControllable } from "../lib/use-controllable";
94
97
  import { Button } from "./button";
@@ -127,6 +130,8 @@ import {
127
130
  scrollRegionProps,
128
131
  type TableFrame,
129
132
  type TableSize,
133
+ TableSizeContext,
134
+ useTableViewInlineSize,
130
135
  } from "../lib/table-internal";
131
136
  import { TypographyMuted } from "./typography";
132
137
 
@@ -485,6 +490,15 @@ export function useDataTable<TData>(
485
490
 
486
491
  const DataTableRefetchingContext = React.createContext(false);
487
492
 
493
+ /**
494
+ * The table's `sortLoading`: a server-side sort refetch in flight. Every
495
+ * `DataTableColumnHeader` without its own `loading` prop reads it, so the
496
+ * consumer sets the flag once and the columns array never has to be rebuilt
497
+ * (DS-1236). Kept apart from `refetching`, which also covers page, filter and
498
+ * search changes — those must not mark the sort headers busy.
499
+ */
500
+ const DataTableSortLoadingContext = React.createContext(false);
501
+
488
502
  export interface DataTableProps<TData> {
489
503
  /** TanStack Table instance (usually returned from `useDataTable`). */
490
504
  table: TanStackTable<TData>;
@@ -494,6 +508,21 @@ export interface DataTableProps<TData> {
494
508
  trackingEl?: string;
495
509
  /** Analytics label. */
496
510
  trackingLabel?: string;
511
+ /**
512
+ * Accessible name for the `<table>` element. Use when no visible heading
513
+ * labels the table — a page with one table, or a table whose purpose is
514
+ * clear from context. Prefer `aria-labelledby` when a heading is visible.
515
+ * @default undefined
516
+ */
517
+ "aria-label"?: string;
518
+ /**
519
+ * ID of the visible heading that names this table. Links the `<table>`
520
+ * to an existing heading so screen-reader users can tell several tables
521
+ * apart (e.g. Volume, Rating, Sources on a timeline page). Use instead
522
+ * of `aria-label` when a heading is already on screen.
523
+ * @default undefined
524
+ */
525
+ "aria-labelledby"?: string;
497
526
  /**
498
527
  * Row density, passed through to the underlying `Table` (DS-556):
499
528
  * `default` rows are `h-12` (48px) under `h-12` (48px) column headers;
@@ -529,23 +558,44 @@ export interface DataTableProps<TData> {
529
558
  /**
530
559
  * Marks a server-side refetch (page, sort, filter or search change) as in
531
560
  * flight. Unlike `isLoading` — the initial load, which swaps rows for
532
- * skeletons — `refetching` never touches the rows: they stay rendered at
533
- * full contrast (keep the stale data with TanStack Query's
561
+ * skeletons — `refetching` never touches the rows: they stay rendered
562
+ * (keep the stale data with TanStack Query's
534
563
  * `placeholderData: keepPreviousData` or `useTransition`). The table sets
535
564
  * `aria-busy` (never the wrapper — the live region must stay outside the
536
565
  * busy subtree to be announced), a polite live region announces
537
566
  * `refetchingLabel`, and the
538
567
  * selection checkboxes (`DataTableSelectAllCheckbox`,
539
568
  * `DataTableSelectRowCheckbox`) set `aria-disabled` and ignore toggles —
540
- * selecting rows that are about to be replaced acts on stale data. The busy *visual* belongs to the
541
- * control that requested the refetch (the pagination button, the sort
542
- * header's or search field's `loading`), not to the body.
569
+ * selecting rows that are about to be replaced acts on stale data. Where
570
+ * the busy *visual* goes depends on the refetch (Patterns/Filtering):
571
+ * - An in-place refresh (page, sort, search) shows it at the control that
572
+ * asked: the pagination button, or the sort header's or search field's
573
+ * `loading`. The rows stay at full contrast.
574
+ * - A scope change (a filter, tabs used as a filter) shows it on
575
+ * the list: the consumer dims the rows. The count holds its previous
576
+ * value until new data arrives. The control that changed the scope
577
+ * shows no busy state.
543
578
  *
544
579
  * Wrap a raw `isFetching` in `useDelayedPending` before passing it, so a
545
580
  * refetch that resolves inside the flash threshold shows nothing at all.
546
581
  * @default false
547
582
  */
548
583
  refetching?: boolean;
584
+ /**
585
+ * Marks a server-side sort refetch as in flight, for every
586
+ * `DataTableColumnHeader` in the table at once: each header without its own
587
+ * `loading` prop behaves as if it were given this value (busy, inert sort
588
+ * buttons; a spinner on the column whose click requested the refetch).
589
+ * Set it here instead of passing `loading` into every header, and the
590
+ * columns array no longer has to be rebuilt when the flag flips — the
591
+ * headers stay mounted, so keyboard focus never leaves the sort button
592
+ * (DS-1236). A header's own `loading` prop still wins when set.
593
+ *
594
+ * Usually set together with `refetching` for a sort change. Wrap a raw
595
+ * `isFetching` in `useDelayedPending` before passing it.
596
+ * @default false
597
+ */
598
+ sortLoading?: boolean;
549
599
  /**
550
600
  * What the polite live region announces to screen readers while
551
601
  * `refetching` is set.
@@ -689,6 +739,32 @@ export interface DataTableProps<TData> {
689
739
  * class (for example `bg-red-50`) replaces the built-in expanded-zone tint.
690
740
  */
691
741
  getRowClassName?: (row: Row<TData>) => string | undefined;
742
+ /**
743
+ * Called when a body row is clicked or activated with Enter / Space.
744
+ * Clicks that land on an interactive element inside the row (a button,
745
+ * link, input, select, textarea, checkbox, or anything with
746
+ * `role="button"` / `role="link"`) are skipped — those controls keep
747
+ * their own behaviour. When set, the row gets `cursor-pointer`, a hover
748
+ * tint, `tabIndex={0}` and keyboard activation (DS-1123).
749
+ */
750
+ onRowClick?: (row: Row<TData>, event: React.SyntheticEvent) => void;
751
+ /**
752
+ * Accessible label for clickable rows — announced by screen readers so
753
+ * the row's action is discoverable. Called per row; return a string that
754
+ * names the record ("Open keyword 'plumber near me'", "View review by
755
+ * John"). Required when `onRowClick` is set; omitting it leaves the row
756
+ * without an accessible name, which violates WCAG.
757
+ */
758
+ getRowAriaLabel?: (row: Row<TData>) => string;
759
+ /**
760
+ * `row.id` of the row whose detail view is open — the sheet or panel that
761
+ * `onRowClick` opened. That row takes the selected surface (kept on hover,
762
+ * followed by pinned cells) and carries `aria-current="true"` and
763
+ * `data-active="true"`, so the open row is announced, not only shown.
764
+ * Pass `undefined` once the view closes. With `getRowId`, pass your own id.
765
+ * @default undefined
766
+ */
767
+ activeRowId?: string;
692
768
  /**
693
769
  * Render a full-width detail panel below each expanded row: an extra
694
770
  * `<tr>` with a single cell spanning all visible columns. Designed for
@@ -741,10 +817,17 @@ function DataTableNoResults<TData>({
741
817
  );
742
818
  }
743
819
 
820
+ /**
821
+ * Whether `meta.pinned` columns are pinned right now: only while the table is
822
+ * wider than its view, so a table that fits draws no sticky edge.
823
+ */
824
+ const DataTablePinActiveContext = React.createContext(false);
825
+
744
826
  /**
745
827
  * Whether the table is wider than its view wrapper — `minWidth`, a column's
746
828
  * `meta.minWidth` or wide content forces a sideways scroll (DS-1215). Only
747
- * measured when `enabled` (page-sticky headings); otherwise always `false`. Under
829
+ * measured when `enabled` (page-sticky headings or a pinned column); otherwise
830
+ * always `false`. Under
748
831
  * `overflow-clip` the table still lays out at its full width, so the
749
832
  * comparison holds in both wrapper modes and never oscillates.
750
833
  */
@@ -816,11 +899,14 @@ function DataTableInner<TData>(
816
899
  dataHook,
817
900
  trackingEl,
818
901
  trackingLabel,
902
+ "aria-label": ariaLabel,
903
+ "aria-labelledby": ariaLabelledBy,
819
904
  size = "default",
820
905
  frame = "own",
821
906
  rowDividers = false,
822
907
  isLoading = false,
823
908
  refetching = false,
909
+ sortLoading = false,
824
910
  refetchingLabel,
825
911
  loadingLabel,
826
912
  skeletonRowCount,
@@ -834,6 +920,9 @@ function DataTableInner<TData>(
834
920
  scrollRegionLabel,
835
921
  footer,
836
922
  getRowClassName,
923
+ onRowClick,
924
+ getRowAriaLabel,
925
+ activeRowId,
837
926
  renderExpandedContent,
838
927
  }: DataTableProps<TData>,
839
928
  ref: React.ForwardedRef<HTMLDivElement>
@@ -852,14 +941,27 @@ function DataTableInner<TData>(
852
941
  const pageSticky = stickyHeader === "page";
853
942
  const viewRef = React.useRef<HTMLDivElement>(null);
854
943
  React.useImperativeHandle(ref, () => viewRef.current!, []);
855
- // Measured for every page-sticky table: `minWidth`, a column's
944
+ const hasPinned = table
945
+ .getVisibleLeafColumns()
946
+ .some((column) => column.columnDef.meta?.pinned === "left");
947
+ // Measured for every page-sticky or pinned table: `minWidth`, a column's
856
948
  // `meta.minWidth` or wide cell content can all push it past the view.
857
- const overflowing = useTableOverflowing(viewRef, pageSticky);
949
+ const overflowing = useTableOverflowing(viewRef, pageSticky || hasPinned);
950
+ // A pinned column pins only while the table is wider than its view.
951
+ const pinActive = hasPinned && overflowing;
858
952
  // Page-sticky headings need a wrapper that is not a scroll container (any
859
953
  // `overflow: auto` axis would trap the sticky <thead>), so it only scrolls
860
954
  // sideways once the table is actually wider than it (DS-1215) — and is a
861
955
  // focusable region exactly then, never an inert tab stop.
862
956
  const scrolls = !pageSticky || overflowing;
957
+ // DS-1105: as the scroll container, publish the visible width TableEmpty
958
+ // caps its message at.
959
+ useTableViewInlineSize(viewRef, scrolls);
960
+ useDevWarning(
961
+ () => onRowClick !== undefined && getRowAriaLabel === undefined,
962
+ "DataTable: `onRowClick` without `getRowAriaLabel` — a clickable row needs an accessible name so screen readers announce what activating it does (DS-1123).",
963
+ [onRowClick !== undefined, getRowAriaLabel !== undefined]
964
+ );
863
965
  const isScrollRegion = pageSticky
864
966
  ? overflowing
865
967
  : Boolean(minWidth) ||
@@ -886,7 +988,7 @@ function DataTableInner<TData>(
886
988
  )}
887
989
  data-frame={frame}
888
990
  data-hook={dataHook}
889
- data-overflowing={pageSticky && overflowing ? "" : undefined}
991
+ data-overflowing={overflowing ? "" : undefined}
890
992
  data-slot="data-table-view"
891
993
  data-sticky-header={
892
994
  stickyHeader === false ? undefined : pageSticky ? "page" : "self"
@@ -901,73 +1003,82 @@ function DataTableInner<TData>(
901
1003
  {refetching ? (refetchingLabel ?? "Loading results…") : null}
902
1004
  </div>
903
1005
  <DataTableRefetchingContext.Provider value={refetching}>
904
- <Table
905
- // Busy on the table, never on the wrapper: `aria-busy` on an
906
- // ancestor defers the live region above until the busy state clears,
907
- // by which point its text is gone and nothing is announced.
908
- aria-busy={isLoading || refetching || undefined}
909
- dataHook={`${dataHook}-table`}
910
- frame={frame}
911
- layout={layout}
912
- minWidth={minWidth}
913
- rowDividers={rowDividers}
914
- scrollOwner="parent"
915
- size={size}
916
- >
917
- <DataTableHeaderRows
918
- sticky={
919
- pageSticky
920
- ? !overflowing && "page"
921
- : stickyHeader === true && "self"
922
- }
923
- table={table}
924
- />
925
- <TableBody>
926
- {isLoading ? (
927
- <>
928
- <LoadingRows
929
- colCount={columnCount}
930
- rowCount={resolvedSkeletonCount}
931
- />
932
- <TableRow className="sr-only">
933
- <TableCell colSpan={columnCount}>
934
- <div aria-live="polite" role="status">
935
- {loadingLabel ?? "Loading data…"}
936
- </div>
937
- </TableCell>
938
- </TableRow>
939
- </>
940
- ) : (
941
- <>
942
- {table.getRowModel().rows.length > 0 ? (
943
- table
944
- .getRowModel()
945
- .rows.map((row) => (
946
- <DataTableRow
947
- key={row.id}
948
- columnCount={columnCount}
949
- getRowClassName={getRowClassName}
950
- renderExpandedContent={renderExpandedContent}
951
- row={row}
952
- />
953
- ))
1006
+ <DataTableSortLoadingContext.Provider value={sortLoading}>
1007
+ <DataTablePinActiveContext.Provider value={pinActive}>
1008
+ <Table
1009
+ // Busy on the table, never on the wrapper: `aria-busy` on an
1010
+ // ancestor defers the live region above until the busy state clears,
1011
+ // by which point its text is gone and nothing is announced.
1012
+ aria-busy={isLoading || refetching || undefined}
1013
+ aria-label={ariaLabel}
1014
+ aria-labelledby={ariaLabelledBy}
1015
+ dataHook={`${dataHook}-table`}
1016
+ frame={frame}
1017
+ layout={layout}
1018
+ minWidth={minWidth}
1019
+ rowDividers={rowDividers}
1020
+ scrollOwner="parent"
1021
+ size={size}
1022
+ >
1023
+ <DataTableHeaderRows
1024
+ sticky={
1025
+ pageSticky
1026
+ ? !overflowing && "page"
1027
+ : stickyHeader === true && "self"
1028
+ }
1029
+ table={table}
1030
+ />
1031
+ <TableBody>
1032
+ {isLoading ? (
1033
+ <>
1034
+ <LoadingRows
1035
+ colCount={columnCount}
1036
+ rowCount={resolvedSkeletonCount}
1037
+ />
1038
+ <TableRow className="sr-only">
1039
+ <TableCell colSpan={columnCount}>
1040
+ <div aria-live="polite" role="status">
1041
+ {loadingLabel ?? "Loading data…"}
1042
+ </div>
1043
+ </TableCell>
1044
+ </TableRow>
1045
+ </>
954
1046
  ) : (
955
- <TableEmpty colSpan={columnCount}>
956
- {noResultsMessage ?? (
957
- <DataTableNoResults
958
- dataHook={dataHook}
959
- description={noResultsDescription}
960
- table={table}
961
- title={noResultsTitle}
962
- />
1047
+ <>
1048
+ {table.getRowModel().rows.length > 0 ? (
1049
+ table
1050
+ .getRowModel()
1051
+ .rows.map((row) => (
1052
+ <DataTableRow
1053
+ key={row.id}
1054
+ active={row.id === activeRowId}
1055
+ columnCount={columnCount}
1056
+ getRowAriaLabel={getRowAriaLabel}
1057
+ getRowClassName={getRowClassName}
1058
+ renderExpandedContent={renderExpandedContent}
1059
+ row={row}
1060
+ onRowClick={onRowClick}
1061
+ />
1062
+ ))
1063
+ ) : (
1064
+ <TableEmpty colSpan={columnCount}>
1065
+ {noResultsMessage ?? (
1066
+ <DataTableNoResults
1067
+ dataHook={dataHook}
1068
+ description={noResultsDescription}
1069
+ table={table}
1070
+ title={noResultsTitle}
1071
+ />
1072
+ )}
1073
+ </TableEmpty>
963
1074
  )}
964
- </TableEmpty>
1075
+ </>
965
1076
  )}
966
- </>
967
- )}
968
- </TableBody>
969
- {footer}
970
- </Table>
1077
+ </TableBody>
1078
+ {footer}
1079
+ </Table>
1080
+ </DataTablePinActiveContext.Provider>
1081
+ </DataTableSortLoadingContext.Provider>
971
1082
  </DataTableRefetchingContext.Provider>
972
1083
  </div>
973
1084
  );
@@ -1031,6 +1142,15 @@ interface SortOverrideStore {
1031
1142
  */
1032
1143
  anyHeld: () => boolean;
1033
1144
  subscribe: (listener: () => void) => () => void;
1145
+ /**
1146
+ * Column whose sort button holds focus across the header remounts a
1147
+ * server-side sort causes (DS-1236). Set by the sort click handler while
1148
+ * the button is focused; `DataTableHeaderRows` hands focus back after each
1149
+ * remount and clears it once the reader moves on. Mutable — no reactivity
1150
+ * needed.
1151
+ */
1152
+ pendingFocusColumnId: string | null;
1153
+ setPendingFocus: (columnId: string | null) => void;
1034
1154
  }
1035
1155
 
1036
1156
  const DataTableSortOverridesContext =
@@ -1044,6 +1164,7 @@ function useSortOverrideStore(): SortOverrideStore {
1044
1164
  const listeners = new Set<() => void>();
1045
1165
  const read = (columnId: string): SortOverrideEntry | null =>
1046
1166
  entries.get(columnId) ?? null;
1167
+ let _pendingFocusColumnId: string | null = null;
1047
1168
  return {
1048
1169
  set: (columnId, entry) => {
1049
1170
  const current = read(columnId);
@@ -1078,6 +1199,12 @@ function useSortOverrideStore(): SortOverrideStore {
1078
1199
  listeners.delete(listener);
1079
1200
  };
1080
1201
  },
1202
+ get pendingFocusColumnId() {
1203
+ return _pendingFocusColumnId;
1204
+ },
1205
+ setPendingFocus: (id: string | null) => {
1206
+ _pendingFocusColumnId = id;
1207
+ },
1081
1208
  };
1082
1209
  });
1083
1210
  return store;
@@ -1101,9 +1228,61 @@ function DataTableHeaderRows<TData>({
1101
1228
  sticky: false | "self" | "page";
1102
1229
  }) {
1103
1230
  const sortOverrides = useSortOverrideStore();
1231
+ const headerRef = React.useRef<HTMLTableSectionElement>(null);
1232
+ const pendingSortButton = React.useCallback(() => {
1233
+ const columnId = sortOverrides.pendingFocusColumnId;
1234
+ if (!columnId) return null;
1235
+ return (
1236
+ headerRef.current?.querySelector<HTMLElement>(
1237
+ `[data-column-id="${CSS.escape(columnId)}"] [data-slot="button"]`
1238
+ ) ?? null
1239
+ );
1240
+ }, [sortOverrides]);
1241
+
1242
+ // DS-1236: restore focus after a sort-triggered header remount. The sort
1243
+ // click handler records its column on the store (which survives the
1244
+ // remount); after every commit, if focus has dropped to the document — the
1245
+ // focused button was unmounted — that column's new button takes it back.
1246
+ // A sort can remount the header twice (the `loading` flag flipping on,
1247
+ // then off), so the target is not cleared here.
1248
+ React.useLayoutEffect(() => {
1249
+ const active = document.activeElement;
1250
+ if (
1251
+ active &&
1252
+ active !== document.body &&
1253
+ active !== document.documentElement
1254
+ ) {
1255
+ return;
1256
+ }
1257
+ pendingSortButton()?.focus();
1258
+ });
1259
+
1260
+ // The target is dropped the moment the reader moves on: focus settling
1261
+ // anywhere else (Tab, a click on another control) or any pointer press — a
1262
+ // click on dead space blurs to <body>, which the effect above must never
1263
+ // mistake for a remount on some later render. The programmatic restore
1264
+ // fires `focusin` on the target button itself, so it is kept.
1265
+ React.useEffect(() => {
1266
+ const clearUnlessPendingButton = (event: Event) => {
1267
+ if (!sortOverrides.pendingFocusColumnId) return;
1268
+ const target = event.target;
1269
+ if (target instanceof Node && pendingSortButton()?.contains(target)) {
1270
+ return;
1271
+ }
1272
+ sortOverrides.setPendingFocus(null);
1273
+ };
1274
+ document.addEventListener("focusin", clearUnlessPendingButton);
1275
+ document.addEventListener("pointerdown", clearUnlessPendingButton);
1276
+ return () => {
1277
+ document.removeEventListener("focusin", clearUnlessPendingButton);
1278
+ document.removeEventListener("pointerdown", clearUnlessPendingButton);
1279
+ };
1280
+ }, [sortOverrides, pendingSortButton]);
1281
+
1104
1282
  return (
1105
1283
  <DataTableSortOverridesContext.Provider value={sortOverrides}>
1106
1284
  <TableHeader
1285
+ ref={headerRef}
1107
1286
  className={cn(
1108
1287
  sticky === "self" && "sticky top-0 z-10",
1109
1288
  sticky === "page" && "sticky top-[var(--content-sticky-top,0px)] z-9"
@@ -1156,12 +1335,14 @@ function DataTableHeadCell<TData>({
1156
1335
  ? "none"
1157
1336
  : undefined;
1158
1337
  const meta = header.column.columnDef.meta;
1338
+ const pinned =
1339
+ React.useContext(DataTablePinActiveContext) && meta?.pinned === "left";
1159
1340
  return (
1160
1341
  <TableHead
1161
1342
  aria-sort={ariaSort}
1162
- className={meta?.pinned === "left" ? PINNED_HEAD_CLASS : undefined}
1343
+ className={pinned ? PINNED_HEAD_CLASS : undefined}
1163
1344
  colSpan={header.colSpan}
1164
- data-pinned={meta?.pinned === "left" ? "left" : undefined}
1345
+ data-pinned={pinned ? "left" : undefined}
1165
1346
  minWidth={meta?.minWidth}
1166
1347
  width={meta?.width}
1167
1348
  >
@@ -1172,6 +1353,32 @@ function DataTableHeadCell<TData>({
1172
1353
  );
1173
1354
  }
1174
1355
 
1356
+ /**
1357
+ * Controls inside a clickable row that keep their own activation (DS-1123): a
1358
+ * click or Enter/Space landing on or inside one never reaches `onRowClick`.
1359
+ * `[tabindex]` covers anything else made focusable — a scrollable cell, a
1360
+ * custom widget; `[contenteditable]` is focusable without an explicit
1361
+ * tabindex, so it's listed separately; the row carries `tabIndex={0}` itself,
1362
+ * so a match on the row is the row's own activation, not a nested control.
1363
+ */
1364
+ const INTERACTIVE_SELECTOR =
1365
+ "a[href],button,input,select,textarea,label,summary,[tabindex],[role='button'],[role='link'],[role='checkbox'],[role='switch'],[role='menuitem'],[role='option'],[role='tab'],[data-slot='dropdown-menu-trigger'],[contenteditable]:not([contenteditable='false'])";
1366
+
1367
+ /**
1368
+ * Whether an event on a clickable row is the row's own activation: the target
1369
+ * sits inside the row's DOM — React also bubbles events from portaled content
1370
+ * (a Dialog or DropdownMenu opened from a row control) up through the row —
1371
+ * and no nested control claims it.
1372
+ */
1373
+ function isRowActivation(
1374
+ row: HTMLTableRowElement,
1375
+ target: EventTarget | null
1376
+ ): boolean {
1377
+ if (!(target instanceof Element) || !row.contains(target)) return false;
1378
+ const control = target.closest(INTERACTIVE_SELECTOR);
1379
+ return control === null || control === row;
1380
+ }
1381
+
1175
1382
  /**
1176
1383
  * Internal: render a single data (or pinned) row.
1177
1384
  * Kept internal because pinned rows share the same visual contract as data rows.
@@ -1183,16 +1390,23 @@ function DataTableHeadCell<TData>({
1183
1390
  * its presence marks an expandable row.
1184
1391
  * - `data-slot="data-table-expanded-row"` — the full-width detail-panel row.
1185
1392
  * - `data-state="selected"` — the pre-existing selection hook.
1393
+ * - `data-active="true"` — the open row (`activeRowId`), with `aria-current`.
1186
1394
  */
1187
1395
  function DataTableRow<TData>({
1188
1396
  row,
1189
1397
  columnCount,
1398
+ active = false,
1190
1399
  getRowClassName,
1400
+ onRowClick,
1401
+ getRowAriaLabel,
1191
1402
  renderExpandedContent,
1192
1403
  }: {
1193
1404
  row: Row<TData>;
1194
1405
  columnCount: number;
1406
+ active?: boolean;
1195
1407
  getRowClassName?: (row: Row<TData>) => string | undefined;
1408
+ onRowClick?: (row: Row<TData>, event: React.SyntheticEvent) => void;
1409
+ getRowAriaLabel?: (row: Row<TData>) => string;
1196
1410
  renderExpandedContent?: (row: Row<TData>) => React.ReactNode;
1197
1411
  }) {
1198
1412
  const canExpand = row.getCanExpand();
@@ -1201,9 +1415,34 @@ function DataTableRow<TData>({
1201
1415
  renderExpandedContent && canExpand && expanded
1202
1416
  ? renderExpandedContent(row)
1203
1417
  : null;
1418
+ const clickable = onRowClick !== undefined;
1419
+ const pinActive = React.useContext(DataTablePinActiveContext);
1420
+
1421
+ const handleRowClick =
1422
+ onRowClick &&
1423
+ ((event: React.MouseEvent<HTMLTableRowElement>) => {
1424
+ if (!isRowActivation(event.currentTarget, event.target)) return;
1425
+ onRowClick(row, event);
1426
+ });
1427
+
1428
+ const handleRowKeyDown =
1429
+ onRowClick &&
1430
+ ((event: React.KeyboardEvent<HTMLTableRowElement>) => {
1431
+ if (event.key !== "Enter" && event.key !== " ") return;
1432
+ if (!isRowActivation(event.currentTarget, event.target)) return;
1433
+ // Space would scroll the page; Enter on a focused row has no default.
1434
+ // Prevent it on every repeat too, so holding the key can't scroll once
1435
+ // the first press has claimed it — but only fire the callback once.
1436
+ event.preventDefault();
1437
+ if (event.repeat) return;
1438
+ onRowClick(row, event);
1439
+ });
1440
+
1204
1441
  return (
1205
1442
  <>
1206
1443
  <TableRow
1444
+ aria-current={active ? "true" : undefined}
1445
+ aria-label={clickable ? getRowAriaLabel?.(row) : undefined}
1207
1446
  className={cn(
1208
1447
  // Rows have no hover of their own — the chevron/action buttons are
1209
1448
  // the interactive elements. Ghost buttons (the only bg-transparent
@@ -1224,14 +1463,34 @@ function DataTableRow<TData>({
1224
1463
  ? "[--dt-row-bg:var(--muted)]"
1225
1464
  : row.depth > 0 &&
1226
1465
  "[--dt-row-bg:color-mix(in_oklab,var(--accent)_50%,var(--background))]",
1466
+ // The open row (activeRowId) shares the selected surface until the
1467
+ // surfaces agreement gives "current" its own (DS-1010). Listed after
1468
+ // the depth wash so it wins on a sub-row too.
1469
+ active && "bg-muted [--dt-row-bg:var(--muted)]",
1470
+ // DS-1123: clickable row — pointer cursor and focus ring; the hover
1471
+ // tint skips rows already holding a surface (selected, active,
1472
+ // expanded parent) and is mirrored into `--dt-row-bg` so an opaque
1473
+ // pinned cell tints with its row.
1474
+ clickable &&
1475
+ "focus-visible:shadow-default cursor-pointer outline-none",
1476
+ clickable &&
1477
+ !active &&
1478
+ !(canExpand && expanded) &&
1479
+ "[&:not([data-state=selected]):hover]:bg-muted/50 [&:not([data-state=selected]):hover]:[--dt-row-bg:color-mix(in_oklab,var(--muted)_50%,var(--background))]",
1227
1480
  getRowClassName?.(row)
1228
1481
  )}
1482
+ data-active={active ? "true" : undefined}
1483
+ data-clickable={clickable ? "" : undefined}
1229
1484
  data-depth={row.depth}
1230
1485
  data-expanded={canExpand ? String(expanded) : undefined}
1231
1486
  data-state={row.getIsSelected() ? "selected" : undefined}
1487
+ tabIndex={clickable ? 0 : undefined}
1488
+ onClick={handleRowClick}
1489
+ onKeyDown={handleRowKeyDown}
1232
1490
  >
1233
1491
  {row.getVisibleCells().map((cell) => {
1234
- const pinned = cell.column.columnDef.meta?.pinned === "left";
1492
+ const pinned =
1493
+ pinActive && cell.column.columnDef.meta?.pinned === "left";
1235
1494
  return (
1236
1495
  <TableCell
1237
1496
  key={cell.id}
@@ -1363,11 +1622,14 @@ function VirtualizedDataTableInner<TData>(
1363
1622
  dataHook,
1364
1623
  trackingEl,
1365
1624
  trackingLabel,
1625
+ "aria-label": ariaLabel,
1626
+ "aria-labelledby": ariaLabelledBy,
1366
1627
  size = "default",
1367
1628
  frame = "own",
1368
1629
  rowDividers = false,
1369
1630
  isLoading = false,
1370
1631
  refetching = false,
1632
+ sortLoading = false,
1371
1633
  refetchingLabel,
1372
1634
  loadingLabel,
1373
1635
  skeletonRowCount,
@@ -1381,6 +1643,9 @@ function VirtualizedDataTableInner<TData>(
1381
1643
  scrollRegionLabel,
1382
1644
  footer,
1383
1645
  getRowClassName,
1646
+ onRowClick,
1647
+ getRowAriaLabel,
1648
+ activeRowId,
1384
1649
  height,
1385
1650
  estimateSize: estimateSizeProp,
1386
1651
  overscan = 5,
@@ -1398,6 +1663,21 @@ function VirtualizedDataTableInner<TData>(
1398
1663
 
1399
1664
  const rows = table.getRowModel().rows;
1400
1665
 
1666
+ // DS-1105: always the scroll container — publish the visible width
1667
+ // TableEmpty caps its message at.
1668
+ useTableViewInlineSize(scrollContainerRef, true);
1669
+ const hasPinned = table
1670
+ .getVisibleLeafColumns()
1671
+ .some((column) => column.columnDef.meta?.pinned === "left");
1672
+ // A pinned column pins only while the table is wider than its view.
1673
+ const overflowing = useTableOverflowing(scrollContainerRef, hasPinned);
1674
+ const pinActive = hasPinned && overflowing;
1675
+ useDevWarning(
1676
+ () => onRowClick !== undefined && getRowAriaLabel === undefined,
1677
+ "VirtualizedDataTable: `onRowClick` without `getRowAriaLabel` — a clickable row needs an accessible name so screen readers announce what activating it does (DS-1123).",
1678
+ [onRowClick !== undefined, getRowAriaLabel !== undefined]
1679
+ );
1680
+
1401
1681
  // eslint-disable-next-line react-hooks/incompatible-library -- TanStack Virtual API is designed for React and works correctly with this pattern
1402
1682
  const virtualizer = useVirtualizer({
1403
1683
  count: rows.length,
@@ -1434,6 +1714,7 @@ function VirtualizedDataTableInner<TData>(
1434
1714
  )}
1435
1715
  data-frame={frame}
1436
1716
  data-hook={dataHook}
1717
+ data-overflowing={overflowing ? "" : undefined}
1437
1718
  data-slot="data-table-view"
1438
1719
  data-tracking-el={trackingEl}
1439
1720
  data-tracking-label={trackingLabel}
@@ -1446,77 +1727,92 @@ function VirtualizedDataTableInner<TData>(
1446
1727
  {refetching ? (refetchingLabel ?? "Loading results…") : null}
1447
1728
  </div>
1448
1729
  <DataTableRefetchingContext.Provider value={refetching}>
1449
- <Table
1450
- // Busy on the table, never on the wrapper: `aria-busy` on an
1451
- // ancestor defers the live region above until the busy state clears,
1452
- // by which point its text is gone and nothing is announced.
1453
- aria-busy={isLoading || refetching || undefined}
1454
- dataHook={`${dataHook}-table`}
1455
- frame={frame}
1456
- layout={layout}
1457
- minWidth={minWidth}
1458
- rowDividers={rowDividers}
1459
- scrollOwner="parent"
1460
- size={size}
1461
- >
1462
- <DataTableHeaderRows sticky={stickyHeader && "self"} table={table} />
1463
- <TableBody>
1464
- {isLoading ? (
1465
- <>
1466
- <LoadingRows
1467
- colCount={columnCount}
1468
- rowCount={resolvedSkeletonCount}
1469
- />
1470
- <TableRow className="sr-only">
1471
- <TableCell colSpan={columnCount}>
1472
- <div aria-live="polite" role="status">
1473
- {loadingLabel ?? "Loading data…"}
1474
- </div>
1475
- </TableCell>
1476
- </TableRow>
1477
- </>
1478
- ) : rows.length > 0 ? (
1479
- <>
1480
- {paddingTop > 0 && (
1481
- <tr aria-hidden="true">
1482
- <td colSpan={columnCount} style={{ height: paddingTop }} />
1483
- </tr>
1484
- )}
1485
- {virtualItems.map((virtualItem) => {
1486
- const row = rows[virtualItem.index]!;
1487
- return (
1488
- <DataTableRow
1489
- key={row.id}
1490
- columnCount={columnCount}
1491
- getRowClassName={getRowClassName}
1492
- row={row}
1493
- />
1494
- );
1495
- })}
1496
- {paddingBottom > 0 && (
1497
- <tr aria-hidden="true">
1498
- <td
1499
- colSpan={columnCount}
1500
- style={{ height: paddingBottom }}
1730
+ <DataTableSortLoadingContext.Provider value={sortLoading}>
1731
+ <DataTablePinActiveContext.Provider value={pinActive}>
1732
+ <Table
1733
+ // Busy on the table, never on the wrapper: `aria-busy` on an
1734
+ // ancestor defers the live region above until the busy state clears,
1735
+ // by which point its text is gone and nothing is announced.
1736
+ aria-busy={isLoading || refetching || undefined}
1737
+ aria-label={ariaLabel}
1738
+ aria-labelledby={ariaLabelledBy}
1739
+ dataHook={`${dataHook}-table`}
1740
+ frame={frame}
1741
+ layout={layout}
1742
+ minWidth={minWidth}
1743
+ rowDividers={rowDividers}
1744
+ scrollOwner="parent"
1745
+ size={size}
1746
+ >
1747
+ <DataTableHeaderRows
1748
+ sticky={stickyHeader && "self"}
1749
+ table={table}
1750
+ />
1751
+ <TableBody>
1752
+ {isLoading ? (
1753
+ <>
1754
+ <LoadingRows
1755
+ colCount={columnCount}
1756
+ rowCount={resolvedSkeletonCount}
1501
1757
  />
1502
- </tr>
1503
- )}
1504
- </>
1505
- ) : (
1506
- <TableEmpty colSpan={columnCount}>
1507
- {noResultsMessage ?? (
1508
- <DataTableNoResults
1509
- dataHook={dataHook}
1510
- description={noResultsDescription}
1511
- table={table}
1512
- title={noResultsTitle}
1513
- />
1758
+ <TableRow className="sr-only">
1759
+ <TableCell colSpan={columnCount}>
1760
+ <div aria-live="polite" role="status">
1761
+ {loadingLabel ?? "Loading data…"}
1762
+ </div>
1763
+ </TableCell>
1764
+ </TableRow>
1765
+ </>
1766
+ ) : rows.length > 0 ? (
1767
+ <>
1768
+ {paddingTop > 0 && (
1769
+ <tr aria-hidden="true">
1770
+ <td
1771
+ colSpan={columnCount}
1772
+ style={{ height: paddingTop }}
1773
+ />
1774
+ </tr>
1775
+ )}
1776
+ {virtualItems.map((virtualItem) => {
1777
+ const row = rows[virtualItem.index]!;
1778
+ return (
1779
+ <DataTableRow
1780
+ key={row.id}
1781
+ active={row.id === activeRowId}
1782
+ columnCount={columnCount}
1783
+ getRowAriaLabel={getRowAriaLabel}
1784
+ getRowClassName={getRowClassName}
1785
+ row={row}
1786
+ onRowClick={onRowClick}
1787
+ />
1788
+ );
1789
+ })}
1790
+ {paddingBottom > 0 && (
1791
+ <tr aria-hidden="true">
1792
+ <td
1793
+ colSpan={columnCount}
1794
+ style={{ height: paddingBottom }}
1795
+ />
1796
+ </tr>
1797
+ )}
1798
+ </>
1799
+ ) : (
1800
+ <TableEmpty colSpan={columnCount}>
1801
+ {noResultsMessage ?? (
1802
+ <DataTableNoResults
1803
+ dataHook={dataHook}
1804
+ description={noResultsDescription}
1805
+ table={table}
1806
+ title={noResultsTitle}
1807
+ />
1808
+ )}
1809
+ </TableEmpty>
1514
1810
  )}
1515
- </TableEmpty>
1516
- )}
1517
- </TableBody>
1518
- {footer}
1519
- </Table>
1811
+ </TableBody>
1812
+ {footer}
1813
+ </Table>
1814
+ </DataTablePinActiveContext.Provider>
1815
+ </DataTableSortLoadingContext.Provider>
1520
1816
  </DataTableRefetchingContext.Provider>
1521
1817
  </div>
1522
1818
  );
@@ -1587,7 +1883,11 @@ export interface DataTableColumnHeaderProps<
1587
1883
  * requesting one can no longer be told apart; button and `<th>` stay
1588
1884
  * consistent with each other either way. Rendered standalone (outside a
1589
1885
  * DataTable), the settled order is held in header-local state instead.
1590
- * @default false
1886
+ *
1887
+ * Inside a DataTable, prefer the table's `sortLoading`: set once, it
1888
+ * reaches every header without this prop, so the columns array is not
1889
+ * rebuilt when the flag flips. This prop overrides it when set.
1890
+ * @default the DataTable's `sortLoading` (`false` standalone)
1591
1891
  */
1592
1892
  loading?: boolean;
1593
1893
  }
@@ -1622,8 +1922,11 @@ export function DataTableColumnHeader<TData, TValue>({
1622
1922
  trackingLabel,
1623
1923
  align = "left",
1624
1924
  getSortLabel,
1625
- loading = false,
1925
+ loading: loadingProp,
1626
1926
  }: DataTableColumnHeaderProps<TData, TValue>) {
1927
+ // Its own `loading` wins; otherwise the table's `sortLoading` (DS-1236).
1928
+ const tableSortLoading = React.useContext(DataTableSortLoadingContext);
1929
+ const loading = loadingProp ?? tableSortLoading;
1627
1930
  const currentSort = column.getIsSorted();
1628
1931
  // Clicking a header flips TanStack's sort state immediately, but during a
1629
1932
  // server-side refetch the rows still show the previous order. The settled
@@ -1733,6 +2036,7 @@ export function DataTableColumnHeader<TData, TValue>({
1733
2036
  align === "center" && "justify-center",
1734
2037
  className
1735
2038
  )}
2039
+ data-column-id={column.id}
1736
2040
  data-slot="data-table-column-header"
1737
2041
  data-tracking-el={trackingEl}
1738
2042
  data-tracking-label={trackingLabel}
@@ -1744,12 +2048,20 @@ export function DataTableColumnHeader<TData, TValue>({
1744
2048
  dataHook={dataHook || `column-header-${column.id}`}
1745
2049
  size="sm"
1746
2050
  variant="ghost"
1747
- onClick={() => {
2051
+ onClick={(event) => {
1748
2052
  // Inert while a refetch is in flight — busy, not disabled, so the
1749
2053
  // button keeps its look and stays focusable but cannot double-fetch.
1750
- if (!loading) {
1751
- column.toggleSorting(nextSortDesc);
2054
+ if (loading) return;
2055
+ // DS-1236: while the button holds focus (keyboard, or a click in a
2056
+ // browser that focuses buttons on click), record the column so
2057
+ // DataTableHeaderRows hands focus back after the header remount a
2058
+ // server-side sort typically causes (the consumer rebuilds the
2059
+ // columns array). A click that never focused the button (Safari)
2060
+ // leaves focus where it was.
2061
+ if (document.activeElement === event.currentTarget) {
2062
+ sortOverrides?.setPendingFocus(column.id);
1752
2063
  }
2064
+ column.toggleSorting(nextSortDesc);
1753
2065
  }}
1754
2066
  >
1755
2067
  <span aria-hidden="true">{title}</span>
@@ -1997,7 +2309,7 @@ export const DataTableSearch = React.forwardRef(function DataTableSearch<TData>(
1997
2309
  data-slot="data-table-search"
1998
2310
  {...inputGroupProps}
1999
2311
  >
2000
- <InputGroupAddon className="pl-3">
2312
+ <InputGroupAddon>
2001
2313
  {/* The spinner takes the search icon's slot, never the clear button's:
2002
2314
  the way out of a slow search must stay where it always is. */}
2003
2315
  {loading ? (
@@ -2207,6 +2519,17 @@ export interface DataTablePaginationRowCountProps {
2207
2519
  * `ResultCount` live region.
2208
2520
  */
2209
2521
  renderText?: (info: RowCountRenderInfo) => React.ReactNode;
2522
+ /**
2523
+ * @deprecated No-op since 3.5.0 — the count holds its previous value
2524
+ * during a refetch; the DataTable's `refetchingLabel` live region covers
2525
+ * SR announcements. Will be removed in the next major version.
2526
+ */
2527
+ updating?: boolean;
2528
+ /**
2529
+ * @deprecated No-op since 3.5.0 — removed together with `updating`.
2530
+ * Will be removed in the next major version.
2531
+ */
2532
+ updatingLabel?: string;
2210
2533
  /** Data hook for the count. @default "{paginationDataHook}-row-count" */
2211
2534
  dataHook?: string;
2212
2535
  /** Additional class name. */
@@ -2230,6 +2553,10 @@ function DataTablePaginationRowCount({
2230
2553
  labelOne,
2231
2554
  emptyLabel,
2232
2555
  renderText,
2556
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars -- deprecated no-ops
2557
+ updating,
2558
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars
2559
+ updatingLabel,
2233
2560
  dataHook,
2234
2561
  className,
2235
2562
  }: DataTablePaginationRowCountProps) {
@@ -2435,6 +2762,17 @@ export interface DataTablePaginationProps<TData> {
2435
2762
  * Ignored when `children` are provided — use `DataTablePaginationRowCount` instead.
2436
2763
  */
2437
2764
  renderRowCount?: ((info: RowCountRenderInfo) => React.ReactNode) | null;
2765
+ /**
2766
+ * @deprecated No-op since 3.5.0 — the count holds its previous value
2767
+ * during a refetch; the DataTable's `refetchingLabel` live region covers
2768
+ * SR announcements. Will be removed in the next major version.
2769
+ */
2770
+ rowCountUpdating?: boolean;
2771
+ /**
2772
+ * @deprecated No-op since 3.5.0 — removed together with `rowCountUpdating`.
2773
+ * Will be removed in the next major version.
2774
+ */
2775
+ rowCountUpdatingLabel?: string;
2438
2776
  /** Analytics element identifier. */
2439
2777
  trackingEl?: string;
2440
2778
  /** Analytics label. */
@@ -2511,6 +2849,10 @@ export function DataTablePagination<TData>({
2511
2849
  rowCountLabelOne,
2512
2850
  rowCountEmptyLabel,
2513
2851
  renderRowCount,
2852
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars -- deprecated no-ops
2853
+ rowCountUpdating,
2854
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars
2855
+ rowCountUpdatingLabel,
2514
2856
  trackingEl,
2515
2857
  trackingLabel,
2516
2858
  className,
@@ -2567,8 +2909,6 @@ export function DataTablePagination<TData>({
2567
2909
  showRowCount &&
2568
2910
  renderRowCount !== null &&
2569
2911
  (renderRowCount ? customRowCount != null : true);
2570
- // At zero rows the default count is only its screen-reader empty label,
2571
- // so the bar keeps no height for it and nothing is visible.
2572
2912
  const rowCountVisible =
2573
2913
  hasRowCount && (Boolean(renderRowCount) || info.totalRows > 0);
2574
2914
  const showNav = info.totalPages > 1;
@@ -2785,13 +3125,20 @@ export function DataTableExpandRowButton<TData>({
2785
3125
  collapseLabel,
2786
3126
  className,
2787
3127
  }: DataTableExpandRowButtonProps<TData>) {
3128
+ const tableSize = React.useContext(TableSizeContext);
3129
+ const buttonSize = tableSize === "sm" ? "sm" : "default";
3130
+
2788
3131
  if (!row.getCanExpand()) {
2789
- // Spacer matches the iconOnly Button footprint (size-9) so leaf-row
2790
- // cell content aligns with expandable siblings.
3132
+ // Spacer matches the iconOnly Button footprint so leaf-row cell
3133
+ // content aligns with expandable siblings.
2791
3134
  return (
2792
3135
  <span
2793
3136
  aria-hidden="true"
2794
- className={cn("inline-block size-9", className)}
3137
+ className={cn(
3138
+ "inline-block",
3139
+ buttonSize === "sm" ? "size-8" : "size-9",
3140
+ className
3141
+ )}
2795
3142
  data-slot="data-table-expand-row-spacer"
2796
3143
  />
2797
3144
  );
@@ -2820,7 +3167,7 @@ export function DataTableExpandRowButton<TData>({
2820
3167
  className={className}
2821
3168
  data-state={expanded ? "open" : "closed"}
2822
3169
  dataHook={dataHook || `expand-row-${row.id}`}
2823
- size="sm"
3170
+ size={buttonSize}
2824
3171
  trackingEl={trackingEl}
2825
3172
  trackingLabel={trackingLabel}
2826
3173
  variant="ghost"