@brightlocal/ui-components 2.25.0 → 2.27.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 (98) hide show
  1. package/README.md +4 -2
  2. package/component-meta.json +3809 -182
  3. package/dist/alert.cjs +1 -1
  4. package/dist/alert.d.ts +23 -9
  5. package/dist/alert.d.ts.map +1 -1
  6. package/dist/alert.js +95 -87
  7. package/dist/blocks/progress-screen.cjs +1 -0
  8. package/dist/blocks/progress-screen.d.ts +109 -0
  9. package/dist/blocks/progress-screen.d.ts.map +1 -0
  10. package/dist/blocks/progress-screen.js +339 -0
  11. package/dist/blocks/sidebar.cjs +1 -1
  12. package/dist/blocks/sidebar.d.ts.map +1 -1
  13. package/dist/blocks/sidebar.js +155 -153
  14. package/dist/brand-illustration-motif.d.ts +1 -1
  15. package/dist/breadcrumb.cjs +1 -1
  16. package/dist/breadcrumb.d.ts.map +1 -1
  17. package/dist/breadcrumb.js +44 -40
  18. package/dist/button.cjs +1 -1
  19. package/dist/button.d.ts.map +1 -1
  20. package/dist/button.js +28 -28
  21. package/dist/chip.cjs +1 -1
  22. package/dist/chip.d.ts +1 -1
  23. package/dist/chip.d.ts.map +1 -1
  24. package/dist/chip.js +42 -41
  25. package/dist/combobox.cjs +3 -3
  26. package/dist/combobox.d.ts +4 -2
  27. package/dist/combobox.d.ts.map +1 -1
  28. package/dist/combobox.js +161 -161
  29. package/dist/data-table.cjs +1 -1
  30. package/dist/data-table.d.ts +155 -4
  31. package/dist/data-table.d.ts.map +1 -1
  32. package/dist/data-table.js +462 -309
  33. package/dist/global-layout.cjs +1 -1
  34. package/dist/global-layout.d.ts +31 -5
  35. package/dist/global-layout.d.ts.map +1 -1
  36. package/dist/global-layout.js +276 -194
  37. package/dist/index.cjs +1 -1
  38. package/dist/index.d.ts +3 -0
  39. package/dist/index.d.ts.map +1 -1
  40. package/dist/index.js +462 -451
  41. package/dist/lib/motion.cjs +1 -1
  42. package/dist/lib/motion.js +10 -8
  43. package/dist/link.cjs +1 -1
  44. package/dist/link.d.ts +5 -2
  45. package/dist/link.d.ts.map +1 -1
  46. package/dist/link.js +97 -91
  47. package/dist/list.cjs +1 -1
  48. package/dist/list.js +65 -63
  49. package/dist/progress.cjs +1 -1
  50. package/dist/progress.d.ts +61 -3
  51. package/dist/progress.d.ts.map +1 -1
  52. package/dist/progress.js +142 -65
  53. package/dist/route-progress.cjs +1 -0
  54. package/dist/route-progress.d.ts +103 -0
  55. package/dist/route-progress.d.ts.map +1 -0
  56. package/dist/route-progress.js +106 -0
  57. package/dist/sheet.cjs +1 -1
  58. package/dist/sheet.d.ts +35 -2
  59. package/dist/sheet.d.ts.map +1 -1
  60. package/dist/sheet.js +102 -65
  61. package/dist/sonner.cjs +1 -1
  62. package/dist/sonner.d.ts.map +1 -1
  63. package/dist/sonner.js +11 -15
  64. package/dist/spinner.cjs +1 -0
  65. package/dist/spinner.d.ts +57 -0
  66. package/dist/spinner.d.ts.map +1 -0
  67. package/dist/spinner.js +35 -0
  68. package/dist/stepper.cjs +1 -1
  69. package/dist/stepper.d.ts.map +1 -1
  70. package/dist/stepper.js +26 -25
  71. package/dist/table.cjs +1 -1
  72. package/dist/table.d.ts +1 -1
  73. package/dist/table.d.ts.map +1 -1
  74. package/dist/table.js +6 -2
  75. package/package.json +15 -6
  76. package/src/blocks/progress-screen.tsx +481 -0
  77. package/src/blocks/sidebar.tsx +22 -15
  78. package/src/components/alert.tsx +68 -33
  79. package/src/components/breadcrumb.tsx +9 -4
  80. package/src/components/button.tsx +2 -5
  81. package/src/components/chip.tsx +4 -3
  82. package/src/components/combobox.tsx +15 -8
  83. package/src/components/data-table.tsx +358 -16
  84. package/src/components/global-layout.tsx +228 -62
  85. package/src/components/link.tsx +88 -63
  86. package/src/components/list.tsx +5 -5
  87. package/src/components/progress.tsx +217 -30
  88. package/src/components/route-progress.tsx +354 -0
  89. package/src/components/sheet.tsx +87 -5
  90. package/src/components/sonner.tsx +3 -12
  91. package/src/components/spinner.tsx +94 -0
  92. package/src/components/stepper.tsx +3 -4
  93. package/src/components/table.tsx +6 -2
  94. package/src/index.ts +3 -0
  95. package/dist/browser-entry.d.ts +0 -19
  96. package/dist/browser-entry.d.ts.map +0 -1
  97. package/src/browser-entry.ts +0 -99
  98. package/src/browser-tokens.css +0 -1
@@ -52,7 +52,14 @@ declare module "@tanstack/react-table" {
52
52
  }
53
53
  }
54
54
  import { useVirtualizer } from "@tanstack/react-virtual";
55
- import { ArrowDown, ArrowUp, ArrowUpDown, Search, X } from "@brightlocal/icons";
55
+ import {
56
+ ArrowDown,
57
+ ArrowUp,
58
+ ArrowUpDown,
59
+ ChevronRight,
60
+ Search,
61
+ X,
62
+ } from "@brightlocal/icons";
56
63
 
57
64
  import { cn } from "@brightlocal/ui-components/lib/utils";
58
65
  import { Button } from "./button";
@@ -162,7 +169,16 @@ export interface UseDataTableOptions<TData> {
162
169
 
163
170
  // ---------- Common features ----------
164
171
 
165
- /** Enable column sorting. @default true */
172
+ /**
173
+ * Enable column sorting. Set to `false` to disable sorting for every
174
+ * column — `column.getCanSort()` returns `false`, so
175
+ * `DataTableColumnHeader` renders plain titles with no sort buttons and
176
+ * no `aria-sort`. TanStack ANDs this flag with each column def's own
177
+ * `enableSorting`: per-column `false` opts a column out under the
178
+ * default, but per-column `true` cannot re-enable sorting when this
179
+ * table-level flag is `false`.
180
+ * @default true
181
+ */
166
182
  enableSorting?: boolean;
167
183
  /** Enable global text search across rows (substring match). @default false */
168
184
  enableGlobalFiltering?: boolean;
@@ -214,6 +230,24 @@ export interface UseDataTableOptions<TData> {
214
230
  enableExpanding?: boolean;
215
231
  /** Advanced: return sub-rows for tree/expanding tables. */
216
232
  getSubRows?: (originalRow: TData, index: number) => TData[] | undefined;
233
+ /**
234
+ * Advanced: allow a row to expand without providing sub-rows — the
235
+ * detail-panel pattern. Return `true` for rows that should show an
236
+ * expander. Pair with `renderExpandedContent` on `DataTable`. Without
237
+ * this (and without `getSubRows`), `row.getCanExpand()` is `false`.
238
+ */
239
+ getRowCanExpand?: (row: Row<TData>) => boolean;
240
+ /**
241
+ * Advanced: whether expanded sub-rows count toward the page size when
242
+ * `enableExpanding` and `enablePagination` are combined. When `false`
243
+ * (default), each page holds `pageSize` top-level rows and expanded
244
+ * sub-rows render on their parent's page. Set `true` for TanStack's
245
+ * default, where sub-rows consume page slots and can spill onto later
246
+ * pages. Only applies with client-side `enablePagination`; without it
247
+ * (or with `manualPagination`) expansion order is unaffected.
248
+ * @default false
249
+ */
250
+ paginateExpandedRows?: boolean;
217
251
 
218
252
  // ---------- Controlled state (all optional) ----------
219
253
 
@@ -247,6 +281,13 @@ export interface UseDataTableOptions<TData> {
247
281
  * consumers to pass into `DataTable`, `DataTablePagination`,
248
282
  * `DataTableSearch`, etc.
249
283
  *
284
+ * Sorting is resolved per column: TanStack ANDs the table-level
285
+ * `enableSorting` flag (default `true`) with each column def's own
286
+ * `enableSorting`. Three cases — all columns sortable (default, configure
287
+ * nothing), whole table unsortable (`enableSorting: false` on the hook), or
288
+ * mixed (keep the table-level default and set `enableSorting: false` on the
289
+ * individual column defs that must not sort).
290
+ *
250
291
  * @example
251
292
  * const table = useDataTable({
252
293
  * columns,
@@ -276,6 +317,8 @@ export function useDataTable<TData>(
276
317
  pageCount,
277
318
  enableExpanding = false,
278
319
  getSubRows,
320
+ getRowCanExpand,
321
+ paginateExpandedRows = false,
279
322
  getRowId,
280
323
  pagination: paginationProp,
281
324
  onPaginationChange: onPaginationChangeProp,
@@ -334,6 +377,10 @@ export function useDataTable<TData>(
334
377
  ...(pageCount != null && { pageCount }),
335
378
  }),
336
379
 
380
+ // Always forward the flag — TanStack defaults `enableSorting` to true,
381
+ // so omitting it would leave `column.getCanSort()` returning true even
382
+ // when the consumer disabled sorting table-wide.
383
+ enableSorting,
337
384
  ...(enableSorting && {
338
385
  ...(!manualSorting && {
339
386
  getSortedRowModel: getSortedRowModel(),
@@ -351,15 +398,27 @@ export function useDataTable<TData>(
351
398
  globalFilterFn: "includesString",
352
399
  }),
353
400
 
401
+ // Always forward — TanStack defaults `enableRowSelection` to true, so
402
+ // omitting it would leave `row.getCanSelect()` returning true and
403
+ // `DataTableSelectRowCheckbox` enabled on tables without selection.
404
+ enableRowSelection,
354
405
  ...(enableRowSelection && {
355
- enableRowSelection: true,
356
406
  onRowSelectionChange: setRowSelectionState,
357
407
  }),
358
408
 
409
+ // Always forward the flag — TanStack defaults `enableExpanding` to true,
410
+ // so omitting it would leave `row.getCanExpand()` returning true and
411
+ // `DataTableExpandRowButton` interactive on tables without expanding.
412
+ enableExpanding,
359
413
  ...(enableExpanding && {
360
414
  getExpandedRowModel: getExpandedRowModel(),
361
415
  onExpandedChange: setExpandedState,
362
416
  getSubRows,
417
+ ...(getRowCanExpand && { getRowCanExpand }),
418
+ // Forward only with client-side pagination: `paginateExpandedRows:
419
+ // false` defers expansion to the pagination row model, so without one
420
+ // it would suppress row expansion entirely.
421
+ ...(enablePagination && !manualPagination && { paginateExpandedRows }),
363
422
  }),
364
423
 
365
424
  state: {
@@ -438,6 +497,29 @@ export interface DataTableProps<TData> {
438
497
  * Use for summary rows or totals. Pass a `<TableFooter>` with rows.
439
498
  */
440
499
  footer?: React.ReactNode;
500
+ /**
501
+ * Compute an extra class name for a body row. Called for every data row,
502
+ * including expanded sub-rows (check `row.depth` / `row.getIsExpanded()`).
503
+ * Not called for skeleton, empty-state, or expanded detail-panel rows.
504
+ * Merged after the base row classes via `cn`, so a plain background
505
+ * class (for example `bg-red-50`) replaces the built-in expanded-zone tint.
506
+ */
507
+ getRowClassName?: (row: Row<TData>) => string | undefined;
508
+ /**
509
+ * Render a full-width detail panel below each expanded row: an extra
510
+ * `<tr>` with a single cell spanning all visible columns. Designed for
511
+ * the detail-panel pattern (`getRowCanExpand` on `useDataTable`, no
512
+ * `getSubRows`); when combined with `getSubRows`, the panel renders
513
+ * between the parent row and its sub-rows. Return `null`/`undefined`
514
+ * to skip the panel for a given row. Not supported by
515
+ * `VirtualizedDataTable`.
516
+ *
517
+ * Lazy-load expensive detail: fetch on expand (trigger the request from
518
+ * `onExpandedChange` on `useDataTable`) and return
519
+ * `<DataTableExpandedSkeleton />` while the row's data is in flight so
520
+ * the panel keeps a stable height instead of jumping twice.
521
+ */
522
+ renderExpandedContent?: (row: Row<TData>) => React.ReactNode;
441
523
  }
442
524
 
443
525
  /**
@@ -489,6 +571,8 @@ export function DataTable<TData>({
489
571
  minWidth,
490
572
  scrollRegionLabel,
491
573
  footer,
574
+ getRowClassName,
575
+ renderExpandedContent,
492
576
  }: DataTableProps<TData>) {
493
577
  const columnCount = table.getVisibleLeafColumns().length;
494
578
  const resolvedSkeletonCount =
@@ -530,7 +614,15 @@ export function DataTable<TData>({
530
614
  {table.getRowModel().rows.length > 0 ? (
531
615
  table
532
616
  .getRowModel()
533
- .rows.map((row) => <DataTableRow key={row.id} row={row} />)
617
+ .rows.map((row) => (
618
+ <DataTableRow
619
+ key={row.id}
620
+ columnCount={columnCount}
621
+ getRowClassName={getRowClassName}
622
+ renderExpandedContent={renderExpandedContent}
623
+ row={row}
624
+ />
625
+ ))
534
626
  ) : (
535
627
  <TableRow>
536
628
  <TableCell align="center" colSpan={columnCount} size="lg">
@@ -605,16 +697,70 @@ function DataTableHeaderRows<TData>({
605
697
  /**
606
698
  * Internal: render a single data (or pinned) row.
607
699
  * Kept internal because pinned rows share the same visual contract as data rows.
700
+ *
701
+ * Addressable-row contract (styling and consumer CSS target these):
702
+ * - `data-depth` — row depth, `0` for top-level rows, on every data row
703
+ * (never on the detail-panel row, so depth selectors count data rows only).
704
+ * - `data-expanded="true" | "false"` — present only on rows that can expand;
705
+ * its presence marks an expandable row.
706
+ * - `data-slot="data-table-expanded-row"` — the full-width detail-panel row.
707
+ * - `data-state="selected"` — the pre-existing selection hook.
608
708
  */
609
- function DataTableRow<TData>({ row }: { row: Row<TData> }) {
709
+ function DataTableRow<TData>({
710
+ row,
711
+ columnCount,
712
+ getRowClassName,
713
+ renderExpandedContent,
714
+ }: {
715
+ row: Row<TData>;
716
+ columnCount: number;
717
+ getRowClassName?: (row: Row<TData>) => string | undefined;
718
+ renderExpandedContent?: (row: Row<TData>) => React.ReactNode;
719
+ }) {
720
+ const canExpand = row.getCanExpand();
721
+ const expanded = row.getIsExpanded();
722
+ const panel =
723
+ renderExpandedContent && canExpand && expanded
724
+ ? renderExpandedContent(row)
725
+ : null;
610
726
  return (
611
- <TableRow data-state={row.getIsSelected() ? "selected" : undefined}>
612
- {row.getVisibleCells().map((cell) => (
613
- <TableCell key={cell.id}>
614
- {flexRender(cell.column.columnDef.cell, cell.getContext())}
615
- </TableCell>
616
- ))}
617
- </TableRow>
727
+ <>
728
+ <TableRow
729
+ className={cn(
730
+ // Rows have no hover of their own — the chevron/action buttons are
731
+ // the interactive elements. Ghost buttons (the only bg-transparent
732
+ // variant) get bg-secondary on hover because their default
733
+ // hover:bg-accent is invisible on bg-muted rows (accent equals
734
+ // muted in light mode). Scoped to .bg-transparent so variant
735
+ // buttons in cells (primary, destructive, …) keep their own hover.
736
+ "[&_[data-slot=button].bg-transparent:hover]:bg-secondary",
737
+ // Surfaces are mutually exclusive: an expanded parent shares the
738
+ // table head's bg-muted at ANY depth; other expanded-zone rows
739
+ // (sub-rows) get the lighter accent wash.
740
+ canExpand && expanded ? "bg-muted" : row.depth > 0 && "bg-accent/50",
741
+ getRowClassName?.(row)
742
+ )}
743
+ data-depth={row.depth}
744
+ data-expanded={canExpand ? String(expanded) : undefined}
745
+ data-state={row.getIsSelected() ? "selected" : undefined}
746
+ >
747
+ {row.getVisibleCells().map((cell) => (
748
+ <TableCell key={cell.id}>
749
+ {flexRender(cell.column.columnDef.cell, cell.getContext())}
750
+ </TableCell>
751
+ ))}
752
+ </TableRow>
753
+ {panel != null && (
754
+ // No data-depth here: panels are not data rows, and sharing the
755
+ // parent's depth would break depth-based selectors and counts.
756
+ <TableRow
757
+ className="bg-accent/50 [&_[data-slot=button].bg-transparent:hover]:bg-secondary"
758
+ data-slot="data-table-expanded-row"
759
+ >
760
+ <TableCell colSpan={columnCount}>{panel}</TableCell>
761
+ </TableRow>
762
+ )}
763
+ </>
618
764
  );
619
765
  }
620
766
 
@@ -653,10 +799,17 @@ function LoadingRows({
653
799
  * Same contract as `DataTable` but renders only the visible rows using
654
800
  * `@tanstack/react-virtual`. The outer wrapper becomes the scroll container,
655
801
  * so a bounded `height` is required.
802
+ *
803
+ * `renderExpandedContent` is excluded: virtual indices map 1:1 to row-model
804
+ * rows, and injecting variable-height detail-panel rows would break index
805
+ * mapping and size estimation. Expanding via `getSubRows` still works —
806
+ * sub-rows are real row-model rows — as do `getRowClassName` and the
807
+ * addressable row attributes.
656
808
  */
657
- export interface VirtualizedDataTableProps<
658
- TData,
659
- > extends DataTableProps<TData> {
809
+ export interface VirtualizedDataTableProps<TData> extends Omit<
810
+ DataTableProps<TData>,
811
+ "renderExpandedContent"
812
+ > {
660
813
  /**
661
814
  * Height of the scroll container in pixels. Required — virtualization
662
815
  * needs a bounded viewport. Pass a CSS value via `className` instead
@@ -716,6 +869,7 @@ export function VirtualizedDataTable<TData>({
716
869
  minWidth,
717
870
  scrollRegionLabel,
718
871
  footer,
872
+ getRowClassName,
719
873
  height,
720
874
  estimateSize = 48,
721
875
  overscan = 5,
@@ -788,7 +942,14 @@ export function VirtualizedDataTable<TData>({
788
942
  )}
789
943
  {virtualItems.map((virtualItem) => {
790
944
  const row = rows[virtualItem.index]!;
791
- return <DataTableRow key={row.id} row={row} />;
945
+ return (
946
+ <DataTableRow
947
+ key={row.id}
948
+ columnCount={columnCount}
949
+ getRowClassName={getRowClassName}
950
+ row={row}
951
+ />
952
+ );
792
953
  })}
793
954
  {paddingBottom > 0 && (
794
955
  <tr aria-hidden="true">
@@ -1534,6 +1695,187 @@ export function DataTableSelectRowCheckbox<TData>({
1534
1695
 
1535
1696
  DataTableSelectRowCheckbox.displayName = "DataTableSelectRowCheckbox";
1536
1697
 
1698
+ /* -------------------------------------------------------------------------------------------------
1699
+ * DataTableExpandRowButton (row expansion toggle)
1700
+ * -----------------------------------------------------------------------------------------------*/
1701
+
1702
+ /**
1703
+ * Props for `DataTableExpandRowButton`.
1704
+ */
1705
+ export interface DataTableExpandRowButtonProps<TData> {
1706
+ /** TanStack row instance. */
1707
+ row: Row<TData>;
1708
+ /**
1709
+ * Human-readable name of the row, interpolated into the accessible
1710
+ * labels so every toggle identifies its row to screen-reader users
1711
+ * ("Expand details for Brighton — North Laine"). Pass the row's
1712
+ * primary display value (e.g. `row.original.name`). Without it the
1713
+ * labels fall back to the generic "Expand row" / "Collapse row" —
1714
+ * fifty identical buttons — so always provide it when rows have a
1715
+ * natural name.
1716
+ */
1717
+ rowName?: string;
1718
+ /**
1719
+ * Accessible label when the row is collapsed. Supports the `{name}`
1720
+ * placeholder, replaced with `rowName`.
1721
+ * @default "Expand details for {name}" when `rowName` is set, "Expand row" otherwise
1722
+ */
1723
+ expandLabel?: string;
1724
+ /**
1725
+ * Accessible label when the row is expanded. Supports the `{name}`
1726
+ * placeholder, replaced with `rowName`.
1727
+ * @default "Collapse details for {name}" when `rowName` is set, "Collapse row" otherwise
1728
+ */
1729
+ collapseLabel?: string;
1730
+ /** Data hook for automated testing. @default `expand-row-{row.id}` */
1731
+ dataHook?: string;
1732
+ /** Analytics element identifier. */
1733
+ trackingEl?: string;
1734
+ /** Analytics label. */
1735
+ trackingLabel?: string;
1736
+ /** Additional class name (external layout only). */
1737
+ className?: string;
1738
+ }
1739
+
1740
+ /**
1741
+ * Row expansion toggle: a ghost icon button with an animated chevron that
1742
+ * points right when collapsed and down when expanded. Rows that cannot
1743
+ * expand render an invisible spacer with the same footprint so cell
1744
+ * content stays aligned with expandable siblings. Requires
1745
+ * `enableExpanding` on `useDataTable` (with `getSubRows` for sub-rows or
1746
+ * `getRowCanExpand` for the detail-panel pattern).
1747
+ */
1748
+ export function DataTableExpandRowButton<TData>({
1749
+ row,
1750
+ rowName,
1751
+ dataHook,
1752
+ trackingEl,
1753
+ trackingLabel,
1754
+ expandLabel,
1755
+ collapseLabel,
1756
+ className,
1757
+ }: DataTableExpandRowButtonProps<TData>) {
1758
+ if (!row.getCanExpand()) {
1759
+ // Spacer matches the iconOnly Button footprint (size-9) so leaf-row
1760
+ // cell content aligns with expandable siblings.
1761
+ return (
1762
+ <span
1763
+ aria-hidden="true"
1764
+ className={cn("inline-block size-9", className)}
1765
+ data-slot="data-table-expand-row-spacer"
1766
+ />
1767
+ );
1768
+ }
1769
+ const expanded = row.getIsExpanded();
1770
+ // Resolve the accessible label. A custom template interpolates every
1771
+ // {name} occurrence; a template that needs {name} while rowName is
1772
+ // absent falls back to the defaults, so no toggle ever announces a
1773
+ // dangling label like "Expand details for ".
1774
+ const template = expanded ? collapseLabel : expandLabel;
1775
+ let label: string;
1776
+ if (template && (rowName !== undefined || !template.includes("{name}"))) {
1777
+ label = template.replaceAll("{name}", rowName ?? "");
1778
+ } else if (rowName !== undefined) {
1779
+ label = expanded
1780
+ ? `Collapse details for ${rowName}`
1781
+ : `Expand details for ${rowName}`;
1782
+ } else {
1783
+ label = expanded ? "Collapse row" : "Expand row";
1784
+ }
1785
+ return (
1786
+ <Button
1787
+ iconOnly
1788
+ aria-expanded={expanded}
1789
+ aria-label={label}
1790
+ className={className}
1791
+ data-state={expanded ? "open" : "closed"}
1792
+ dataHook={dataHook || `expand-row-${row.id}`}
1793
+ size="sm"
1794
+ trackingEl={trackingEl}
1795
+ trackingLabel={trackingLabel}
1796
+ variant="ghost"
1797
+ onClick={row.getToggleExpandedHandler()}
1798
+ >
1799
+ <ChevronRight
1800
+ aria-hidden="true"
1801
+ className={cn(
1802
+ "duration-base transition-transform ease-in-out",
1803
+ expanded && "rotate-90"
1804
+ )}
1805
+ />
1806
+ </Button>
1807
+ );
1808
+ }
1809
+
1810
+ DataTableExpandRowButton.displayName = "DataTableExpandRowButton";
1811
+
1812
+ /* -------------------------------------------------------------------------------------------------
1813
+ * DataTableExpandedSkeleton (loading state for a lazy-loaded detail panel)
1814
+ * -----------------------------------------------------------------------------------------------*/
1815
+
1816
+ /**
1817
+ * Props for `DataTableExpandedSkeleton`.
1818
+ */
1819
+ export interface DataTableExpandedSkeletonProps {
1820
+ /**
1821
+ * Number of field-shaped placeholder lines. Match the number of
1822
+ * key-value fields the loaded panel will render so the row height
1823
+ * stays stable when the content arrives.
1824
+ * @default 3
1825
+ */
1826
+ fields?: number;
1827
+ /**
1828
+ * Screen-reader announcement while the panel content loads.
1829
+ * @default "Loading details"
1830
+ */
1831
+ loadingLabel?: string;
1832
+ /** Data hook for automated testing. @default "data-table-expanded-skeleton" */
1833
+ dataHook?: string;
1834
+ /** Additional class name (external layout only). */
1835
+ className?: string;
1836
+ }
1837
+
1838
+ /**
1839
+ * Loading state for a lazy-loaded expanded detail panel: field-shaped
1840
+ * skeleton lines (label + value) sized to match the definition-list
1841
+ * layout the loaded panel renders. Return it from
1842
+ * `renderExpandedContent` while the row's detail request is in flight —
1843
+ * fetch on expand via `onExpandedChange`, never with the table.
1844
+ *
1845
+ * @example
1846
+ * renderExpandedContent={(row) =>
1847
+ * details[row.id]
1848
+ * ? <LocationDetail detail={details[row.id]} />
1849
+ * : <DataTableExpandedSkeleton fields={4} />
1850
+ * }
1851
+ */
1852
+ export function DataTableExpandedSkeleton({
1853
+ fields = 3,
1854
+ loadingLabel,
1855
+ dataHook,
1856
+ className,
1857
+ }: DataTableExpandedSkeletonProps) {
1858
+ return (
1859
+ <div
1860
+ // `relative` anchors the sr-only span's containing block.
1861
+ className={cn("relative flex flex-col gap-2 py-1", className)}
1862
+ data-hook={dataHook || "data-table-expanded-skeleton"}
1863
+ data-slot="data-table-expanded-skeleton"
1864
+ role="status"
1865
+ >
1866
+ <span className="sr-only">{loadingLabel ?? "Loading details"}</span>
1867
+ {Array.from({ length: fields }, (_, i) => (
1868
+ <div key={i} aria-hidden="true" className="flex items-center gap-4">
1869
+ <Skeleton className="h-4 w-24 shrink-0" />
1870
+ <Skeleton className="h-4 w-48 max-w-full" />
1871
+ </div>
1872
+ ))}
1873
+ </div>
1874
+ );
1875
+ }
1876
+
1877
+ DataTableExpandedSkeleton.displayName = "DataTableExpandedSkeleton";
1878
+
1537
1879
  /* -------------------------------------------------------------------------------------------------
1538
1880
  * DataTableBulkActions (selection summary + bulk action bar)
1539
1881
  * -----------------------------------------------------------------------------------------------*/