@brightlocal/ui-components 2.26.0 → 3.0.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 (284) hide show
  1. package/README.md +9 -2
  2. package/component-meta.json +4010 -255
  3. package/deprecations.json +189 -2
  4. package/dist/accordion.cjs +1 -1
  5. package/dist/accordion.js +2 -2
  6. package/dist/alert-dialog.cjs +1 -1
  7. package/dist/alert-dialog.js +18 -18
  8. package/dist/alert.cjs +1 -1
  9. package/dist/alert.d.ts +11 -1
  10. package/dist/alert.d.ts.map +1 -1
  11. package/dist/alert.js +31 -28
  12. package/dist/avatar.cjs +1 -1
  13. package/dist/avatar.js +4 -4
  14. package/dist/badge.cjs +1 -1
  15. package/dist/badge.d.ts.map +1 -1
  16. package/dist/badge.js +15 -11
  17. package/dist/blocks/empty-state.cjs +1 -0
  18. package/dist/blocks/empty-state.d.ts +172 -0
  19. package/dist/blocks/empty-state.d.ts.map +1 -0
  20. package/dist/blocks/empty-state.js +155 -0
  21. package/dist/blocks/input-list.cjs +2 -2
  22. package/dist/blocks/input-list.d.ts.map +1 -1
  23. package/dist/blocks/input-list.js +124 -108
  24. package/dist/blocks/progress-state.cjs +1 -0
  25. package/dist/blocks/progress-state.d.ts +121 -0
  26. package/dist/blocks/progress-state.d.ts.map +1 -0
  27. package/dist/blocks/progress-state.js +368 -0
  28. package/dist/blocks/sidebar.cjs +1 -1
  29. package/dist/blocks/sidebar.d.ts.map +1 -1
  30. package/dist/blocks/sidebar.js +297 -296
  31. package/dist/brand-illustration-motif.d.ts +1 -1
  32. package/dist/breadcrumb.cjs +1 -1
  33. package/dist/breadcrumb.d.ts.map +1 -1
  34. package/dist/breadcrumb.js +44 -40
  35. package/dist/button.cjs +1 -1
  36. package/dist/button.d.ts.map +1 -1
  37. package/dist/button.js +23 -23
  38. package/dist/calendar.cjs +1 -1
  39. package/dist/calendar.d.ts.map +1 -1
  40. package/dist/calendar.js +37 -38
  41. package/dist/callout.cjs +1 -1
  42. package/dist/callout.d.ts +24 -2
  43. package/dist/callout.d.ts.map +1 -1
  44. package/dist/callout.js +57 -55
  45. package/dist/card.cjs +1 -1
  46. package/dist/card.d.ts +23 -2
  47. package/dist/card.d.ts.map +1 -1
  48. package/dist/card.js +94 -91
  49. package/dist/chart-empty.cjs +1 -0
  50. package/dist/chart-empty.d.ts +59 -0
  51. package/dist/chart-empty.d.ts.map +1 -0
  52. package/dist/chart-empty.js +29 -0
  53. package/dist/chart.cjs +6 -6
  54. package/dist/chart.d.ts +6 -1
  55. package/dist/chart.d.ts.map +1 -1
  56. package/dist/chart.js +183 -183
  57. package/dist/chip.cjs +1 -1
  58. package/dist/chip.d.ts +1 -1
  59. package/dist/chip.d.ts.map +1 -1
  60. package/dist/chip.js +47 -44
  61. package/dist/combobox.cjs +3 -3
  62. package/dist/combobox.d.ts +4 -2
  63. package/dist/combobox.d.ts.map +1 -1
  64. package/dist/combobox.js +143 -141
  65. package/dist/command.cjs +1 -1
  66. package/dist/command.d.ts.map +1 -1
  67. package/dist/command.js +74 -77
  68. package/dist/context-menu.cjs +1 -1
  69. package/dist/context-menu.d.ts.map +1 -1
  70. package/dist/context-menu.js +26 -29
  71. package/dist/data-table.cjs +1 -1
  72. package/dist/data-table.d.ts +182 -13
  73. package/dist/data-table.d.ts.map +1 -1
  74. package/dist/data-table.js +462 -314
  75. package/dist/description.cjs +1 -1
  76. package/dist/description.js +5 -5
  77. package/dist/dialog.cjs +1 -1
  78. package/dist/dialog.js +20 -20
  79. package/dist/drawer.cjs +1 -1
  80. package/dist/drawer.d.ts.map +1 -1
  81. package/dist/drawer.js +8 -11
  82. package/dist/dropdown-menu.cjs +1 -1
  83. package/dist/dropdown-menu.d.ts.map +1 -1
  84. package/dist/dropdown-menu.js +17 -20
  85. package/dist/field.cjs +1 -1
  86. package/dist/field.d.ts.map +1 -1
  87. package/dist/field.js +29 -25
  88. package/dist/global-layout.cjs +1 -1
  89. package/dist/global-layout.d.ts +58 -6
  90. package/dist/global-layout.d.ts.map +1 -1
  91. package/dist/global-layout.js +278 -194
  92. package/dist/grid.cjs +1 -0
  93. package/dist/grid.d.ts +56 -0
  94. package/dist/grid.d.ts.map +1 -0
  95. package/dist/grid.js +32 -0
  96. package/dist/header.d.ts +13 -0
  97. package/dist/header.d.ts.map +1 -1
  98. package/dist/hooks/use-delayed-pending.cjs +1 -0
  99. package/dist/hooks/use-delayed-pending.d.ts +34 -0
  100. package/dist/hooks/use-delayed-pending.d.ts.map +1 -0
  101. package/dist/hooks/use-delayed-pending.js +17 -0
  102. package/dist/hover-card.cjs +1 -1
  103. package/dist/hover-card.js +13 -13
  104. package/dist/index.cjs +1 -1
  105. package/dist/index.d.ts +10 -0
  106. package/dist/index.d.ts.map +1 -1
  107. package/dist/index.js +523 -494
  108. package/dist/input-chip.cjs +1 -1
  109. package/dist/input-chip.js +25 -25
  110. package/dist/input-group.cjs +1 -1
  111. package/dist/input-group.js +9 -9
  112. package/dist/input-otp.cjs +1 -1
  113. package/dist/input-otp.js +9 -9
  114. package/dist/input-password.cjs +1 -1
  115. package/dist/input-password.js +51 -51
  116. package/dist/input.cjs +1 -1
  117. package/dist/input.js +9 -9
  118. package/dist/label.cjs +1 -1
  119. package/dist/label.d.ts.map +1 -1
  120. package/dist/label.js +25 -28
  121. package/dist/lib/block-illustration.cjs +1 -0
  122. package/dist/lib/block-illustration.d.ts +28 -0
  123. package/dist/lib/block-illustration.d.ts.map +1 -0
  124. package/dist/lib/block-illustration.js +21 -0
  125. package/dist/lib/empty-canvas.cjs +1 -0
  126. package/dist/lib/empty-canvas.d.ts +27 -0
  127. package/dist/lib/empty-canvas.d.ts.map +1 -0
  128. package/dist/lib/empty-canvas.js +62 -0
  129. package/dist/lib/motion.cjs +1 -1
  130. package/dist/lib/motion.js +10 -8
  131. package/dist/lib/optical-center.cjs +1 -0
  132. package/dist/lib/optical-center.d.ts +12 -0
  133. package/dist/lib/optical-center.d.ts.map +1 -0
  134. package/dist/lib/optical-center.js +11 -0
  135. package/dist/lib/utils.cjs +1 -1
  136. package/dist/lib/utils.d.ts.map +1 -1
  137. package/dist/lib/utils.js +28 -5
  138. package/dist/link.cjs +1 -1
  139. package/dist/link.d.ts +8 -6
  140. package/dist/link.d.ts.map +1 -1
  141. package/dist/link.js +52 -20
  142. package/dist/list.cjs +1 -1
  143. package/dist/list.d.ts.map +1 -1
  144. package/dist/list.js +87 -81
  145. package/dist/map.cjs +1 -1
  146. package/dist/map.d.ts +60 -2
  147. package/dist/map.d.ts.map +1 -1
  148. package/dist/map.js +187 -164
  149. package/dist/media-empty.cjs +1 -0
  150. package/dist/media-empty.d.ts +72 -0
  151. package/dist/media-empty.d.ts.map +1 -0
  152. package/dist/media-empty.js +45 -0
  153. package/dist/menubar.cjs +1 -1
  154. package/dist/menubar.d.ts.map +1 -1
  155. package/dist/menubar.js +17 -20
  156. package/dist/navigation-menu.cjs +1 -1
  157. package/dist/navigation-menu.js +7 -7
  158. package/dist/pagination.cjs +1 -1
  159. package/dist/pagination.d.ts +127 -1
  160. package/dist/pagination.d.ts.map +1 -1
  161. package/dist/pagination.js +189 -98
  162. package/dist/progress.cjs +1 -1
  163. package/dist/progress.d.ts +37 -3
  164. package/dist/progress.d.ts.map +1 -1
  165. package/dist/progress.js +102 -64
  166. package/dist/route-progress.cjs +1 -0
  167. package/dist/route-progress.d.ts +103 -0
  168. package/dist/route-progress.d.ts.map +1 -0
  169. package/dist/route-progress.js +106 -0
  170. package/dist/select.cjs +2 -2
  171. package/dist/select.d.ts.map +1 -1
  172. package/dist/select.js +19 -18
  173. package/dist/separator.cjs +1 -1
  174. package/dist/separator.js +8 -8
  175. package/dist/sheet.cjs +1 -1
  176. package/dist/sheet.d.ts +35 -2
  177. package/dist/sheet.d.ts.map +1 -1
  178. package/dist/sheet.js +103 -66
  179. package/dist/skeleton.cjs +1 -1
  180. package/dist/skeleton.d.ts +38 -3
  181. package/dist/skeleton.d.ts.map +1 -1
  182. package/dist/skeleton.js +43 -20
  183. package/dist/sonner.cjs +1 -1
  184. package/dist/sonner.d.ts.map +1 -1
  185. package/dist/sonner.js +32 -36
  186. package/dist/spinner.cjs +1 -0
  187. package/dist/spinner.d.ts +57 -0
  188. package/dist/spinner.d.ts.map +1 -0
  189. package/dist/spinner.js +35 -0
  190. package/dist/stepper.cjs +1 -1
  191. package/dist/stepper.d.ts.map +1 -1
  192. package/dist/stepper.js +23 -22
  193. package/dist/table.cjs +1 -1
  194. package/dist/table.d.ts +1 -1
  195. package/dist/table.d.ts.map +1 -1
  196. package/dist/table.js +36 -29
  197. package/dist/tabs.cjs +1 -1
  198. package/dist/tabs.js +1 -1
  199. package/dist/text-reveal-motion.d.ts +10 -0
  200. package/dist/text-reveal-motion.d.ts.map +1 -1
  201. package/dist/textarea.cjs +1 -1
  202. package/dist/textarea.js +11 -11
  203. package/dist/toggle.cjs +1 -1
  204. package/dist/toggle.js +8 -8
  205. package/dist/tooltip.cjs +1 -1
  206. package/dist/tooltip.js +8 -8
  207. package/dist/typography-heading.cjs +1 -0
  208. package/dist/typography-heading.d.ts +116 -0
  209. package/dist/typography-heading.d.ts.map +1 -0
  210. package/dist/typography-heading.js +84 -0
  211. package/dist/typography-text.cjs +1 -0
  212. package/dist/typography-text.d.ts +113 -0
  213. package/dist/typography-text.d.ts.map +1 -0
  214. package/dist/typography-text.js +81 -0
  215. package/dist/typography.d.ts +13 -0
  216. package/dist/typography.d.ts.map +1 -1
  217. package/package.json +42 -2
  218. package/src/blocks/empty-state.tsx +424 -0
  219. package/src/blocks/input-list.tsx +66 -36
  220. package/src/blocks/progress-state.tsx +542 -0
  221. package/src/blocks/sidebar.tsx +46 -40
  222. package/src/components/accordion.tsx +2 -2
  223. package/src/components/alert-dialog.tsx +2 -2
  224. package/src/components/alert.tsx +27 -13
  225. package/src/components/avatar.tsx +1 -1
  226. package/src/components/badge.tsx +8 -4
  227. package/src/components/breadcrumb.tsx +9 -4
  228. package/src/components/button.tsx +5 -8
  229. package/src/components/calendar.tsx +5 -6
  230. package/src/components/callout.tsx +48 -15
  231. package/src/components/card.tsx +52 -17
  232. package/src/components/chart-empty.tsx +116 -0
  233. package/src/components/chart.tsx +43 -17
  234. package/src/components/chip.tsx +9 -6
  235. package/src/components/combobox.tsx +21 -12
  236. package/src/components/command.tsx +9 -10
  237. package/src/components/context-menu.tsx +6 -9
  238. package/src/components/data-table.tsx +405 -31
  239. package/src/components/description.tsx +1 -1
  240. package/src/components/dialog.tsx +2 -2
  241. package/src/components/drawer.tsx +2 -5
  242. package/src/components/dropdown-menu.tsx +8 -11
  243. package/src/components/field.tsx +8 -4
  244. package/src/components/global-layout.tsx +264 -65
  245. package/src/components/grid.tsx +130 -0
  246. package/src/components/header.tsx +13 -0
  247. package/src/components/hover-card.tsx +1 -1
  248. package/src/components/input-chip.tsx +1 -1
  249. package/src/components/input-group.tsx +1 -1
  250. package/src/components/input-otp.tsx +1 -1
  251. package/src/components/input-password.tsx +1 -1
  252. package/src/components/input.tsx +1 -1
  253. package/src/components/label.tsx +10 -13
  254. package/src/components/link.tsx +39 -5
  255. package/src/components/list.tsx +18 -14
  256. package/src/components/map.tsx +101 -5
  257. package/src/components/media-empty.tsx +156 -0
  258. package/src/components/menubar.tsx +7 -10
  259. package/src/components/navigation-menu.tsx +1 -1
  260. package/src/components/pagination.tsx +279 -1
  261. package/src/components/progress.tsx +120 -11
  262. package/src/components/route-progress.tsx +354 -0
  263. package/src/components/select.tsx +5 -4
  264. package/src/components/separator.tsx +1 -1
  265. package/src/components/sheet.tsx +89 -7
  266. package/src/components/skeleton.tsx +78 -7
  267. package/src/components/sonner.tsx +5 -14
  268. package/src/components/spinner.tsx +94 -0
  269. package/src/components/stepper.tsx +6 -7
  270. package/src/components/table.tsx +11 -4
  271. package/src/components/tabs.tsx +1 -1
  272. package/src/components/text-reveal-motion.tsx +10 -0
  273. package/src/components/textarea.tsx +1 -1
  274. package/src/components/toggle.tsx +1 -1
  275. package/src/components/tooltip.tsx +1 -1
  276. package/src/components/typography-heading.tsx +229 -0
  277. package/src/components/typography-text.tsx +225 -0
  278. package/src/components/typography.tsx +13 -0
  279. package/src/hooks/use-delayed-pending.ts +60 -0
  280. package/src/index.ts +12 -0
  281. package/src/lib/block-illustration.tsx +88 -0
  282. package/src/lib/empty-canvas.tsx +128 -0
  283. package/src/lib/optical-center.tsx +45 -0
  284. package/src/lib/utils.ts +26 -0
@@ -18,8 +18,6 @@
18
18
  * - Layout: `DataTableToolbar`, `DataTableToolbarLeft`,
19
19
  * `DataTableToolbarRight` — responsive flex container for search +
20
20
  * pagination above (or below) the table.
21
- *
22
- * Block composition example — see `apps/sandbox/components/audit-table.tsx`.
23
21
  */
24
22
 
25
23
  import * as React from "react";
@@ -52,7 +50,14 @@ declare module "@tanstack/react-table" {
52
50
  }
53
51
  }
54
52
  import { useVirtualizer } from "@tanstack/react-virtual";
55
- import { ArrowDown, ArrowUp, ArrowUpDown, Search, X } from "@brightlocal/icons";
53
+ import {
54
+ ArrowDown,
55
+ ArrowUp,
56
+ ArrowUpDown,
57
+ ChevronRight,
58
+ Search,
59
+ X,
60
+ } from "@brightlocal/icons";
56
61
 
57
62
  import { cn } from "@brightlocal/ui-components/lib/utils";
58
63
  import { Button } from "./button";
@@ -175,8 +180,16 @@ export interface UseDataTableOptions<TData> {
175
180
  enableSorting?: boolean;
176
181
  /** Enable global text search across rows (substring match). @default false */
177
182
  enableGlobalFiltering?: boolean;
178
- /** Enable row selection via checkboxes. @default false */
179
- enableRowSelection?: boolean;
183
+ /**
184
+ * Enable row selection via checkboxes. Pass a predicate to decide per row:
185
+ * a row for which it returns `false` has `row.getCanSelect() === false`, so
186
+ * `DataTableSelectRowCheckbox` renders disabled and `DataTableSelectAllCheckbox`
187
+ * skips the row. Use it for caps and allowances — let already-selected rows
188
+ * stay selectable so the user can undo.
189
+ * @default false
190
+ * @example enableRowSelection: (row) => row.getIsSelected() || selectedCount < 20
191
+ */
192
+ enableRowSelection?: boolean | ((row: Row<TData>) => boolean);
180
193
  /** Enable client-side pagination. @default false */
181
194
  enablePagination?: boolean;
182
195
  /** Initial page size when pagination is enabled. @default 10 */
@@ -223,6 +236,24 @@ export interface UseDataTableOptions<TData> {
223
236
  enableExpanding?: boolean;
224
237
  /** Advanced: return sub-rows for tree/expanding tables. */
225
238
  getSubRows?: (originalRow: TData, index: number) => TData[] | undefined;
239
+ /**
240
+ * Advanced: allow a row to expand without providing sub-rows — the
241
+ * detail-panel pattern. Return `true` for rows that should show an
242
+ * expander. Pair with `renderExpandedContent` on `DataTable`. Without
243
+ * this (and without `getSubRows`), `row.getCanExpand()` is `false`.
244
+ */
245
+ getRowCanExpand?: (row: Row<TData>) => boolean;
246
+ /**
247
+ * Advanced: whether expanded sub-rows count toward the page size when
248
+ * `enableExpanding` and `enablePagination` are combined. When `false`
249
+ * (default), each page holds `pageSize` top-level rows and expanded
250
+ * sub-rows render on their parent's page. Set `true` for TanStack's
251
+ * default, where sub-rows consume page slots and can spill onto later
252
+ * pages. Only applies with client-side `enablePagination`; without it
253
+ * (or with `manualPagination`) expansion order is unaffected.
254
+ * @default false
255
+ */
256
+ paginateExpandedRows?: boolean;
226
257
 
227
258
  // ---------- Controlled state (all optional) ----------
228
259
 
@@ -263,6 +294,14 @@ export interface UseDataTableOptions<TData> {
263
294
  * mixed (keep the table-level default and set `enableSorting: false` on the
264
295
  * individual column defs that must not sort).
265
296
  *
297
+ * Row selection can be resolved per row the same way: `enableRowSelection`
298
+ * takes a predicate as well as a boolean, which backs `row.getCanSelect()`.
299
+ * A blocked row renders a disabled `DataTableSelectRowCheckbox` and is skipped
300
+ * by `DataTableSelectAllCheckbox`. Let already-selected rows pass the
301
+ * predicate, or a cap leaves the user no way to swap a choice — and leave
302
+ * select-all out of a capped table, since every row passes a count-based
303
+ * predicate while the selection is empty.
304
+ *
266
305
  * @example
267
306
  * const table = useDataTable({
268
307
  * columns,
@@ -292,6 +331,8 @@ export function useDataTable<TData>(
292
331
  pageCount,
293
332
  enableExpanding = false,
294
333
  getSubRows,
334
+ getRowCanExpand,
335
+ paginateExpandedRows = false,
295
336
  getRowId,
296
337
  pagination: paginationProp,
297
338
  onPaginationChange: onPaginationChangeProp,
@@ -375,14 +416,25 @@ export function useDataTable<TData>(
375
416
  // omitting it would leave `row.getCanSelect()` returning true and
376
417
  // `DataTableSelectRowCheckbox` enabled on tables without selection.
377
418
  enableRowSelection,
378
- ...(enableRowSelection && {
419
+ // A predicate turns selection on for the table as a whole; individual rows
420
+ // opt out through `row.getCanSelect()`, so the state wiring is still needed.
421
+ ...(enableRowSelection !== false && {
379
422
  onRowSelectionChange: setRowSelectionState,
380
423
  }),
381
424
 
425
+ // Always forward the flag — TanStack defaults `enableExpanding` to true,
426
+ // so omitting it would leave `row.getCanExpand()` returning true and
427
+ // `DataTableExpandRowButton` interactive on tables without expanding.
428
+ enableExpanding,
382
429
  ...(enableExpanding && {
383
430
  getExpandedRowModel: getExpandedRowModel(),
384
431
  onExpandedChange: setExpandedState,
385
432
  getSubRows,
433
+ ...(getRowCanExpand && { getRowCanExpand }),
434
+ // Forward only with client-side pagination: `paginateExpandedRows:
435
+ // false` defers expansion to the pagination row model, so without one
436
+ // it would suppress row expansion entirely.
437
+ ...(enablePagination && !manualPagination && { paginateExpandedRows }),
386
438
  }),
387
439
 
388
440
  state: {
@@ -421,8 +473,22 @@ export interface DataTableProps<TData> {
421
473
  isLoading?: boolean;
422
474
  /** Number of skeleton rows when loading. Falls back to the table's page size, then 10. */
423
475
  skeletonRowCount?: number;
424
- /** Empty state message. @default "No results." */
425
- noResultsMessage?: string;
476
+ /**
477
+ * What the table shows in place of rows when it has none.
478
+ *
479
+ * A string is the no-results case — a filter or search that excludes
480
+ * everything — and it is announced politely, because the reader's own query
481
+ * caused it and they are waiting to hear the outcome.
482
+ *
483
+ * Pass an `<EmptyState>` for a collection that is empty rather than filtered:
484
+ * nothing has been added yet, so the cell needs a title and a way to add the
485
+ * first one. The cell brings the block's breathing room with it — do not wrap
486
+ * it in a padding element. The block is wrapped in the same live region, so
487
+ * keep it to the standard anatomy — its title and one line are worth hearing;
488
+ * a wall of copy is not.
489
+ * @default "No results."
490
+ */
491
+ noResultsMessage?: React.ReactNode;
426
492
  /**
427
493
  * Pin the `<thead>` to the top of the scroll container so column headers
428
494
  * remain visible while scrolling. The header keeps its opaque `bg-muted`
@@ -461,6 +527,29 @@ export interface DataTableProps<TData> {
461
527
  * Use for summary rows or totals. Pass a `<TableFooter>` with rows.
462
528
  */
463
529
  footer?: React.ReactNode;
530
+ /**
531
+ * Compute an extra class name for a body row. Called for every data row,
532
+ * including expanded sub-rows (check `row.depth` / `row.getIsExpanded()`).
533
+ * Not called for skeleton, empty-state, or expanded detail-panel rows.
534
+ * Merged after the base row classes via `cn`, so a plain background
535
+ * class (for example `bg-red-50`) replaces the built-in expanded-zone tint.
536
+ */
537
+ getRowClassName?: (row: Row<TData>) => string | undefined;
538
+ /**
539
+ * Render a full-width detail panel below each expanded row: an extra
540
+ * `<tr>` with a single cell spanning all visible columns. Designed for
541
+ * the detail-panel pattern (`getRowCanExpand` on `useDataTable`, no
542
+ * `getSubRows`); when combined with `getSubRows`, the panel renders
543
+ * between the parent row and its sub-rows. Return `null`/`undefined`
544
+ * to skip the panel for a given row. Not supported by
545
+ * `VirtualizedDataTable`.
546
+ *
547
+ * Lazy-load expensive detail: fetch on expand (trigger the request from
548
+ * `onExpandedChange` on `useDataTable`) and return
549
+ * `<DataTableExpandedSkeleton />` while the row's data is in flight so
550
+ * the panel keeps a stable height instead of jumping twice.
551
+ */
552
+ renderExpandedContent?: (row: Row<TData>) => React.ReactNode;
464
553
  }
465
554
 
466
555
  /**
@@ -512,6 +601,8 @@ export function DataTable<TData>({
512
601
  minWidth,
513
602
  scrollRegionLabel,
514
603
  footer,
604
+ getRowClassName,
605
+ renderExpandedContent,
515
606
  }: DataTableProps<TData>) {
516
607
  const columnCount = table.getVisibleLeafColumns().length;
517
608
  const resolvedSkeletonCount =
@@ -553,11 +644,26 @@ export function DataTable<TData>({
553
644
  {table.getRowModel().rows.length > 0 ? (
554
645
  table
555
646
  .getRowModel()
556
- .rows.map((row) => <DataTableRow key={row.id} row={row} />)
647
+ .rows.map((row) => (
648
+ <DataTableRow
649
+ key={row.id}
650
+ columnCount={columnCount}
651
+ getRowClassName={getRowClassName}
652
+ renderExpandedContent={renderExpandedContent}
653
+ row={row}
654
+ />
655
+ ))
557
656
  ) : (
558
657
  <TableRow>
559
658
  <TableCell align="center" colSpan={columnCount} size="lg">
560
- <div aria-live="polite" role="status">
659
+ {/* Padded for a block, not for a line: an `EmptyState` passed
660
+ as the message needs the same room here that it gets
661
+ anywhere else, and a prop API gives the consumer nowhere
662
+ to add it. 24 rather than 32, because this sits inside
663
+ the cell's own 8: together they give the block its 32,
664
+ and a one-line message still measures under `size="lg"`'s
665
+ min-height, so the plain-string row does not move. */}
666
+ <div aria-live="polite" className="py-6" role="status">
561
667
  {noResultsMessage}
562
668
  </div>
563
669
  </TableCell>
@@ -628,16 +734,70 @@ function DataTableHeaderRows<TData>({
628
734
  /**
629
735
  * Internal: render a single data (or pinned) row.
630
736
  * Kept internal because pinned rows share the same visual contract as data rows.
737
+ *
738
+ * Addressable-row contract (styling and consumer CSS target these):
739
+ * - `data-depth` — row depth, `0` for top-level rows, on every data row
740
+ * (never on the detail-panel row, so depth selectors count data rows only).
741
+ * - `data-expanded="true" | "false"` — present only on rows that can expand;
742
+ * its presence marks an expandable row.
743
+ * - `data-slot="data-table-expanded-row"` — the full-width detail-panel row.
744
+ * - `data-state="selected"` — the pre-existing selection hook.
631
745
  */
632
- function DataTableRow<TData>({ row }: { row: Row<TData> }) {
746
+ function DataTableRow<TData>({
747
+ row,
748
+ columnCount,
749
+ getRowClassName,
750
+ renderExpandedContent,
751
+ }: {
752
+ row: Row<TData>;
753
+ columnCount: number;
754
+ getRowClassName?: (row: Row<TData>) => string | undefined;
755
+ renderExpandedContent?: (row: Row<TData>) => React.ReactNode;
756
+ }) {
757
+ const canExpand = row.getCanExpand();
758
+ const expanded = row.getIsExpanded();
759
+ const panel =
760
+ renderExpandedContent && canExpand && expanded
761
+ ? renderExpandedContent(row)
762
+ : null;
633
763
  return (
634
- <TableRow data-state={row.getIsSelected() ? "selected" : undefined}>
635
- {row.getVisibleCells().map((cell) => (
636
- <TableCell key={cell.id}>
637
- {flexRender(cell.column.columnDef.cell, cell.getContext())}
638
- </TableCell>
639
- ))}
640
- </TableRow>
764
+ <>
765
+ <TableRow
766
+ className={cn(
767
+ // Rows have no hover of their own — the chevron/action buttons are
768
+ // the interactive elements. Ghost buttons (the only bg-transparent
769
+ // variant) get bg-secondary on hover because their default
770
+ // hover:bg-accent is invisible on bg-muted rows (accent equals
771
+ // muted in light mode). Scoped to .bg-transparent so variant
772
+ // buttons in cells (primary, destructive, …) keep their own hover.
773
+ "[&_[data-slot=button].bg-transparent:hover]:bg-secondary",
774
+ // Surfaces are mutually exclusive: an expanded parent shares the
775
+ // table head's bg-muted at ANY depth; other expanded-zone rows
776
+ // (sub-rows) get the lighter accent wash.
777
+ canExpand && expanded ? "bg-muted" : row.depth > 0 && "bg-accent/50",
778
+ getRowClassName?.(row)
779
+ )}
780
+ data-depth={row.depth}
781
+ data-expanded={canExpand ? String(expanded) : undefined}
782
+ data-state={row.getIsSelected() ? "selected" : undefined}
783
+ >
784
+ {row.getVisibleCells().map((cell) => (
785
+ <TableCell key={cell.id}>
786
+ {flexRender(cell.column.columnDef.cell, cell.getContext())}
787
+ </TableCell>
788
+ ))}
789
+ </TableRow>
790
+ {panel != null && (
791
+ // No data-depth here: panels are not data rows, and sharing the
792
+ // parent's depth would break depth-based selectors and counts.
793
+ <TableRow
794
+ className="bg-accent/50 [&_[data-slot=button].bg-transparent:hover]:bg-secondary"
795
+ data-slot="data-table-expanded-row"
796
+ >
797
+ <TableCell colSpan={columnCount}>{panel}</TableCell>
798
+ </TableRow>
799
+ )}
800
+ </>
641
801
  );
642
802
  }
643
803
 
@@ -676,10 +836,17 @@ function LoadingRows({
676
836
  * Same contract as `DataTable` but renders only the visible rows using
677
837
  * `@tanstack/react-virtual`. The outer wrapper becomes the scroll container,
678
838
  * so a bounded `height` is required.
839
+ *
840
+ * `renderExpandedContent` is excluded: virtual indices map 1:1 to row-model
841
+ * rows, and injecting variable-height detail-panel rows would break index
842
+ * mapping and size estimation. Expanding via `getSubRows` still works —
843
+ * sub-rows are real row-model rows — as do `getRowClassName` and the
844
+ * addressable row attributes.
679
845
  */
680
- export interface VirtualizedDataTableProps<
681
- TData,
682
- > extends DataTableProps<TData> {
846
+ export interface VirtualizedDataTableProps<TData> extends Omit<
847
+ DataTableProps<TData>,
848
+ "renderExpandedContent"
849
+ > {
683
850
  /**
684
851
  * Height of the scroll container in pixels. Required — virtualization
685
852
  * needs a bounded viewport. Pass a CSS value via `className` instead
@@ -739,6 +906,7 @@ export function VirtualizedDataTable<TData>({
739
906
  minWidth,
740
907
  scrollRegionLabel,
741
908
  footer,
909
+ getRowClassName,
742
910
  height,
743
911
  estimateSize = 48,
744
912
  overscan = 5,
@@ -811,7 +979,14 @@ export function VirtualizedDataTable<TData>({
811
979
  )}
812
980
  {virtualItems.map((virtualItem) => {
813
981
  const row = rows[virtualItem.index]!;
814
- return <DataTableRow key={row.id} row={row} />;
982
+ return (
983
+ <DataTableRow
984
+ key={row.id}
985
+ columnCount={columnCount}
986
+ getRowClassName={getRowClassName}
987
+ row={row}
988
+ />
989
+ );
815
990
  })}
816
991
  {paddingBottom > 0 && (
817
992
  <tr aria-hidden="true">
@@ -822,7 +997,9 @@ export function VirtualizedDataTable<TData>({
822
997
  ) : (
823
998
  <TableRow>
824
999
  <TableCell align="center" colSpan={columnCount} size="lg">
825
- <div aria-live="polite" role="status">
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">
826
1003
  {noResultsMessage}
827
1004
  </div>
828
1005
  </TableCell>
@@ -890,7 +1067,7 @@ export function DataTableColumnHeader<TData, TValue>({
890
1067
  return (
891
1068
  <div
892
1069
  className={cn(
893
- "text-muted-foreground text-left text-sm leading-normal font-medium",
1070
+ "text-muted-foreground text-label text-left font-semibold",
894
1071
  align === "right" && "text-right",
895
1072
  align === "center" && "text-center",
896
1073
  className
@@ -928,7 +1105,7 @@ export function DataTableColumnHeader<TData, TValue>({
928
1105
  >
929
1106
  <Button
930
1107
  aria-label={sortLabel}
931
- className="text-muted-foreground h-auto p-0 text-sm font-medium"
1108
+ className="text-muted-foreground text-label h-auto p-0 font-semibold"
932
1109
  dataHook={dataHook || `column-header-${column.id}`}
933
1110
  size="sm"
934
1111
  variant="ghost"
@@ -1017,7 +1194,9 @@ export function DataTableSearch<TData>({
1017
1194
  <InputGroupAddon className="pr-1">
1018
1195
  <Button
1019
1196
  aria-label={clearSearchAriaLabel ?? "Clear search"}
1020
- className="h-auto p-1"
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"
1021
1200
  data-slot="data-table-search-clear"
1022
1201
  dataHook={`${inputGroupProps.dataHook}-clear`}
1023
1202
  variant="ghost"
@@ -1210,7 +1389,7 @@ function DataTablePaginationRowCount({
1210
1389
 
1211
1390
  return (
1212
1391
  <span
1213
- className={cn("text-muted-foreground text-sm", className)}
1392
+ className={cn("text-body-sm text-muted-foreground", className)}
1214
1393
  data-slot="data-table-pagination-row-count"
1215
1394
  >
1216
1395
  {content}
@@ -1236,8 +1415,9 @@ export interface DataTablePaginationNavProps {
1236
1415
  /**
1237
1416
  * Pagination navigation for `DataTablePagination`.
1238
1417
  *
1239
- * Renders previous/next buttons and page links. Must be rendered inside
1240
- * `<DataTablePagination>`.
1418
+ * Renders previous/next buttons and page links. Renders nothing when there
1419
+ * is at most one page — navigation controls are noise when there is nowhere
1420
+ * to navigate. Must be rendered inside `<DataTablePagination>`.
1241
1421
  */
1242
1422
  function DataTablePaginationNav({
1243
1423
  ariaLabel = "Table pagination",
@@ -1251,6 +1431,10 @@ function DataTablePaginationNav({
1251
1431
  totalPages: info.totalPages,
1252
1432
  });
1253
1433
 
1434
+ if (info.totalPages <= 1) {
1435
+ return null;
1436
+ }
1437
+
1254
1438
  return (
1255
1439
  <Pagination
1256
1440
  ariaLabel={ariaLabel}
@@ -1362,6 +1546,11 @@ export interface DataTablePaginationProps<TData> {
1362
1546
  * optional "start–end of total" row count label. Use `renderRowCount` for
1363
1547
  * i18n-friendly text.
1364
1548
  *
1549
+ * The navigation hides itself when there is at most one page (the row count
1550
+ * stays, keeping the bar informative and the layout stable). When both the
1551
+ * row count and the nav are empty, the component renders nothing — no
1552
+ * consumer render gate needed.
1553
+ *
1365
1554
  * **Compositional mode** (with children): acts as a context provider.
1366
1555
  * Compose `DataTablePaginationRowCount` and `DataTablePaginationNav`
1367
1556
  * in any order/layout.
@@ -1441,18 +1630,22 @@ export function DataTablePagination<TData>({
1441
1630
  return `${info.startRow}-${info.endRow} of ${info.totalRows}`;
1442
1631
  })();
1443
1632
 
1633
+ if (rowCountContent == null && info.totalPages <= 1) {
1634
+ return null;
1635
+ }
1636
+
1444
1637
  return (
1445
1638
  <DataTablePaginationContext.Provider value={contextValue}>
1446
1639
  <div
1447
1640
  className={cn(
1448
- "flex w-full items-center gap-4",
1641
+ "flex min-h-9 w-full items-center gap-4",
1449
1642
  rowCountContent != null ? "justify-between" : "justify-end",
1450
1643
  className
1451
1644
  )}
1452
1645
  {...wrapperDataAttrs}
1453
1646
  >
1454
1647
  {rowCountContent != null && (
1455
- <span className="text-muted-foreground text-sm">
1648
+ <span className="text-body-sm text-muted-foreground">
1456
1649
  {rowCountContent}
1457
1650
  </span>
1458
1651
  )}
@@ -1557,6 +1750,187 @@ export function DataTableSelectRowCheckbox<TData>({
1557
1750
 
1558
1751
  DataTableSelectRowCheckbox.displayName = "DataTableSelectRowCheckbox";
1559
1752
 
1753
+ /* -------------------------------------------------------------------------------------------------
1754
+ * DataTableExpandRowButton (row expansion toggle)
1755
+ * -----------------------------------------------------------------------------------------------*/
1756
+
1757
+ /**
1758
+ * Props for `DataTableExpandRowButton`.
1759
+ */
1760
+ export interface DataTableExpandRowButtonProps<TData> {
1761
+ /** TanStack row instance. */
1762
+ row: Row<TData>;
1763
+ /**
1764
+ * Human-readable name of the row, interpolated into the accessible
1765
+ * labels so every toggle identifies its row to screen-reader users
1766
+ * ("Expand details for Brighton — North Laine"). Pass the row's
1767
+ * primary display value (e.g. `row.original.name`). Without it the
1768
+ * labels fall back to the generic "Expand row" / "Collapse row" —
1769
+ * fifty identical buttons — so always provide it when rows have a
1770
+ * natural name.
1771
+ */
1772
+ rowName?: string;
1773
+ /**
1774
+ * Accessible label when the row is collapsed. Supports the `{name}`
1775
+ * placeholder, replaced with `rowName`.
1776
+ * @default "Expand details for {name}" when `rowName` is set, "Expand row" otherwise
1777
+ */
1778
+ expandLabel?: string;
1779
+ /**
1780
+ * Accessible label when the row is expanded. Supports the `{name}`
1781
+ * placeholder, replaced with `rowName`.
1782
+ * @default "Collapse details for {name}" when `rowName` is set, "Collapse row" otherwise
1783
+ */
1784
+ collapseLabel?: string;
1785
+ /** Data hook for automated testing. @default `expand-row-{row.id}` */
1786
+ dataHook?: string;
1787
+ /** Analytics element identifier. */
1788
+ trackingEl?: string;
1789
+ /** Analytics label. */
1790
+ trackingLabel?: string;
1791
+ /** Additional class name (external layout only). */
1792
+ className?: string;
1793
+ }
1794
+
1795
+ /**
1796
+ * Row expansion toggle: a ghost icon button with an animated chevron that
1797
+ * points right when collapsed and down when expanded. Rows that cannot
1798
+ * expand render an invisible spacer with the same footprint so cell
1799
+ * content stays aligned with expandable siblings. Requires
1800
+ * `enableExpanding` on `useDataTable` (with `getSubRows` for sub-rows or
1801
+ * `getRowCanExpand` for the detail-panel pattern).
1802
+ */
1803
+ export function DataTableExpandRowButton<TData>({
1804
+ row,
1805
+ rowName,
1806
+ dataHook,
1807
+ trackingEl,
1808
+ trackingLabel,
1809
+ expandLabel,
1810
+ collapseLabel,
1811
+ className,
1812
+ }: DataTableExpandRowButtonProps<TData>) {
1813
+ if (!row.getCanExpand()) {
1814
+ // Spacer matches the iconOnly Button footprint (size-9) so leaf-row
1815
+ // cell content aligns with expandable siblings.
1816
+ return (
1817
+ <span
1818
+ aria-hidden="true"
1819
+ className={cn("inline-block size-9", className)}
1820
+ data-slot="data-table-expand-row-spacer"
1821
+ />
1822
+ );
1823
+ }
1824
+ const expanded = row.getIsExpanded();
1825
+ // Resolve the accessible label. A custom template interpolates every
1826
+ // {name} occurrence; a template that needs {name} while rowName is
1827
+ // absent falls back to the defaults, so no toggle ever announces a
1828
+ // dangling label like "Expand details for ".
1829
+ const template = expanded ? collapseLabel : expandLabel;
1830
+ let label: string;
1831
+ if (template && (rowName !== undefined || !template.includes("{name}"))) {
1832
+ label = template.replaceAll("{name}", rowName ?? "");
1833
+ } else if (rowName !== undefined) {
1834
+ label = expanded
1835
+ ? `Collapse details for ${rowName}`
1836
+ : `Expand details for ${rowName}`;
1837
+ } else {
1838
+ label = expanded ? "Collapse row" : "Expand row";
1839
+ }
1840
+ return (
1841
+ <Button
1842
+ iconOnly
1843
+ aria-expanded={expanded}
1844
+ aria-label={label}
1845
+ className={className}
1846
+ data-state={expanded ? "open" : "closed"}
1847
+ dataHook={dataHook || `expand-row-${row.id}`}
1848
+ size="sm"
1849
+ trackingEl={trackingEl}
1850
+ trackingLabel={trackingLabel}
1851
+ variant="ghost"
1852
+ onClick={row.getToggleExpandedHandler()}
1853
+ >
1854
+ <ChevronRight
1855
+ aria-hidden="true"
1856
+ className={cn(
1857
+ "duration-base transition-transform ease-in-out",
1858
+ expanded && "rotate-90"
1859
+ )}
1860
+ />
1861
+ </Button>
1862
+ );
1863
+ }
1864
+
1865
+ DataTableExpandRowButton.displayName = "DataTableExpandRowButton";
1866
+
1867
+ /* -------------------------------------------------------------------------------------------------
1868
+ * DataTableExpandedSkeleton (loading state for a lazy-loaded detail panel)
1869
+ * -----------------------------------------------------------------------------------------------*/
1870
+
1871
+ /**
1872
+ * Props for `DataTableExpandedSkeleton`.
1873
+ */
1874
+ export interface DataTableExpandedSkeletonProps {
1875
+ /**
1876
+ * Number of field-shaped placeholder lines. Match the number of
1877
+ * key-value fields the loaded panel will render so the row height
1878
+ * stays stable when the content arrives.
1879
+ * @default 3
1880
+ */
1881
+ fields?: number;
1882
+ /**
1883
+ * Screen-reader announcement while the panel content loads.
1884
+ * @default "Loading details"
1885
+ */
1886
+ loadingLabel?: string;
1887
+ /** Data hook for automated testing. @default "data-table-expanded-skeleton" */
1888
+ dataHook?: string;
1889
+ /** Additional class name (external layout only). */
1890
+ className?: string;
1891
+ }
1892
+
1893
+ /**
1894
+ * Loading state for a lazy-loaded expanded detail panel: field-shaped
1895
+ * skeleton lines (label + value) sized to match the definition-list
1896
+ * layout the loaded panel renders. Return it from
1897
+ * `renderExpandedContent` while the row's detail request is in flight —
1898
+ * fetch on expand via `onExpandedChange`, never with the table.
1899
+ *
1900
+ * @example
1901
+ * renderExpandedContent={(row) =>
1902
+ * details[row.id]
1903
+ * ? <LocationDetail detail={details[row.id]} />
1904
+ * : <DataTableExpandedSkeleton fields={4} />
1905
+ * }
1906
+ */
1907
+ export function DataTableExpandedSkeleton({
1908
+ fields = 3,
1909
+ loadingLabel,
1910
+ dataHook,
1911
+ className,
1912
+ }: DataTableExpandedSkeletonProps) {
1913
+ return (
1914
+ <div
1915
+ // `relative` anchors the sr-only span's containing block.
1916
+ className={cn("relative flex flex-col gap-2 py-1", className)}
1917
+ data-hook={dataHook || "data-table-expanded-skeleton"}
1918
+ data-slot="data-table-expanded-skeleton"
1919
+ role="status"
1920
+ >
1921
+ <span className="sr-only">{loadingLabel ?? "Loading details"}</span>
1922
+ {Array.from({ length: fields }, (_, i) => (
1923
+ <div key={i} aria-hidden="true" className="flex items-center gap-4">
1924
+ <Skeleton className="h-4 w-24 shrink-0" />
1925
+ <Skeleton className="h-4 w-48 max-w-full" />
1926
+ </div>
1927
+ ))}
1928
+ </div>
1929
+ );
1930
+ }
1931
+
1932
+ DataTableExpandedSkeleton.displayName = "DataTableExpandedSkeleton";
1933
+
1560
1934
  /* -------------------------------------------------------------------------------------------------
1561
1935
  * DataTableBulkActions (selection summary + bulk action bar)
1562
1936
  * -----------------------------------------------------------------------------------------------*/
@@ -41,7 +41,7 @@ const Description = React.forwardRef<HTMLParagraphElement, DescriptionProps>(
41
41
  <p
42
42
  ref={ref}
43
43
  className={cn(
44
- "text-muted-foreground text-left text-sm",
44
+ "text-body-sm text-muted-foreground text-left",
45
45
  "[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4",
46
46
  className
47
47
  )}
@@ -218,7 +218,7 @@ const DialogTitle = React.forwardRef<
218
218
  >(({ className, dataHook, ...props }, ref) => (
219
219
  <DialogPrimitive.Title
220
220
  ref={ref}
221
- className={cn("text-lg leading-none font-semibold", className)}
221
+ className={cn("text-heading-section", className)}
222
222
  data-hook={dataHook}
223
223
  data-slot="dialog-title"
224
224
  {...props}
@@ -249,7 +249,7 @@ const DialogDescription = React.forwardRef<
249
249
  >(({ className, dataHook, ...props }, ref) => (
250
250
  <DialogPrimitive.Description
251
251
  ref={ref}
252
- className={cn("text-muted-foreground text-sm", className)}
252
+ className={cn("text-body-sm text-muted-foreground", className)}
253
253
  data-hook={dataHook}
254
254
  data-slot="dialog-description"
255
255
  {...props}
@@ -196,10 +196,7 @@ function DrawerTitle({
196
196
  }: React.ComponentProps<typeof DrawerPrimitive.Title>) {
197
197
  return (
198
198
  <DrawerPrimitive.Title
199
- className={cn(
200
- "text-foreground text-lg leading-none font-semibold",
201
- className
202
- )}
199
+ className={cn("text-foreground text-heading-section", className)}
203
200
  data-slot="drawer-title"
204
201
  {...props}
205
202
  />
@@ -217,7 +214,7 @@ function DrawerDescription({
217
214
  }: React.ComponentProps<typeof DrawerPrimitive.Description>) {
218
215
  return (
219
216
  <DrawerPrimitive.Description
220
- className={cn("text-muted-foreground text-sm leading-normal", className)}
217
+ className={cn("text-body-sm text-muted-foreground", className)}
221
218
  data-slot="drawer-description"
222
219
  {...props}
223
220
  />