@brightlocal/ui-components 2.23.0 → 2.24.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 (90) hide show
  1. package/AI_USAGE.md +1 -1
  2. package/README.md +3 -2
  3. package/component-meta.json +116 -25
  4. package/deprecations.json +22 -0
  5. package/dist/alert.cjs +1 -1
  6. package/dist/alert.d.ts.map +1 -1
  7. package/dist/alert.js +6 -9
  8. package/dist/blocks/sidebar.cjs +1 -1
  9. package/dist/blocks/sidebar.d.ts.map +1 -1
  10. package/dist/blocks/sidebar.js +151 -156
  11. package/dist/brand-illustration-motif.cjs +1 -0
  12. package/dist/brand-illustration-motif.d.ts +55 -0
  13. package/dist/brand-illustration-motif.d.ts.map +1 -0
  14. package/dist/brand-illustration-motif.js +67 -0
  15. package/dist/chart.cjs +7 -7
  16. package/dist/chart.d.ts +287 -2
  17. package/dist/chart.d.ts.map +1 -1
  18. package/dist/chart.js +408 -152
  19. package/dist/combobox.cjs +3 -3
  20. package/dist/combobox.d.ts +14 -1
  21. package/dist/combobox.d.ts.map +1 -1
  22. package/dist/combobox.js +387 -376
  23. package/dist/data-table.cjs +1 -0
  24. package/dist/{blocks/data-table.d.ts → data-table.d.ts} +159 -4
  25. package/dist/data-table.d.ts.map +1 -0
  26. package/dist/data-table.js +721 -0
  27. package/dist/field.cjs +1 -1
  28. package/dist/field.d.ts +16 -1
  29. package/dist/field.d.ts.map +1 -1
  30. package/dist/field.js +23 -7
  31. package/dist/global-layout.cjs +1 -1
  32. package/dist/global-layout.d.ts +32 -2
  33. package/dist/global-layout.d.ts.map +1 -1
  34. package/dist/global-layout.js +179 -109
  35. package/dist/index.cjs +1 -1
  36. package/dist/index.d.ts +2 -1
  37. package/dist/index.d.ts.map +1 -1
  38. package/dist/index.js +526 -511
  39. package/dist/label.cjs +1 -1
  40. package/dist/label.d.ts +9 -0
  41. package/dist/label.d.ts.map +1 -1
  42. package/dist/label.js +26 -22
  43. package/dist/lib/spring-settle.cjs +1 -0
  44. package/dist/lib/spring-settle.d.ts +20 -0
  45. package/dist/lib/spring-settle.d.ts.map +1 -0
  46. package/dist/lib/spring-settle.js +4 -0
  47. package/dist/link.cjs +1 -1
  48. package/dist/link.d.ts +3 -2
  49. package/dist/link.d.ts.map +1 -1
  50. package/dist/link.js +22 -11
  51. package/dist/loading.cjs +1 -1
  52. package/dist/loading.d.ts +2 -1
  53. package/dist/loading.d.ts.map +1 -1
  54. package/dist/loading.js +106 -85
  55. package/dist/select.cjs +2 -2
  56. package/dist/select.d.ts +16 -1
  57. package/dist/select.d.ts.map +1 -1
  58. package/dist/select.js +112 -79
  59. package/dist/table.cjs +1 -1
  60. package/dist/table.d.ts +29 -0
  61. package/dist/table.d.ts.map +1 -1
  62. package/dist/table.js +2 -2
  63. package/dist/text-reveal-motion.cjs +1 -1
  64. package/dist/text-reveal-motion.d.ts.map +1 -1
  65. package/dist/text-reveal-motion.js +236 -219
  66. package/dist/typography.cjs +1 -1
  67. package/dist/typography.d.ts +20 -4
  68. package/dist/typography.d.ts.map +1 -1
  69. package/dist/typography.js +263 -228
  70. package/package.json +7 -7
  71. package/src/blocks/sidebar.tsx +11 -23
  72. package/src/components/alert.tsx +1 -4
  73. package/src/components/brand-illustration-motif.tsx +143 -0
  74. package/src/components/chart.tsx +632 -1
  75. package/src/components/combobox.tsx +47 -0
  76. package/src/{blocks → components}/data-table.tsx +270 -16
  77. package/src/components/field.tsx +31 -0
  78. package/src/components/global-layout.tsx +144 -5
  79. package/src/components/label.tsx +13 -1
  80. package/src/components/link.tsx +13 -1
  81. package/src/components/loading.tsx +71 -38
  82. package/src/components/select.tsx +82 -2
  83. package/src/components/table.tsx +31 -2
  84. package/src/components/text-reveal-motion.tsx +90 -64
  85. package/src/components/typography.tsx +74 -18
  86. package/src/index.ts +2 -1
  87. package/src/lib/spring-settle.ts +19 -0
  88. package/dist/blocks/data-table.cjs +0 -1
  89. package/dist/blocks/data-table.d.ts.map +0 -1
  90. package/dist/blocks/data-table.js +0 -654
@@ -138,6 +138,19 @@ export interface ComboboxProps {
138
138
  open?: boolean;
139
139
  /** Callback when open state changes */
140
140
  onOpenChange?: (open: boolean) => void;
141
+ /**
142
+ * Close-commit callback — fired once each time the popover actually
143
+ * closes, and guaranteed to fire **after** any pending `onValueChange` has
144
+ * been delivered. Designed for blur-based form validation — in React Hook
145
+ * Form's onBlur mode, pass `field.onBlur` here so validation runs against
146
+ * the committed value when the dropdown closes, keeping `onOpenChange`
147
+ * free for product logic.
148
+ *
149
+ * Fires only on resolved closes: a controlled consumer that vetoes a close
150
+ * request gets no callback, while a programmatic controlled close does
151
+ * fire it. Unmounting while open counts as a close.
152
+ */
153
+ onClose?: () => void;
141
154
  /**
142
155
  * Whether to use built-in client-side filtering. Defaults to `true`.
143
156
  * Both `ComboboxList` (cmdk) and `ComboboxVirtualList` respect this flag.
@@ -158,6 +171,7 @@ function Combobox({
158
171
  onValueChange: controlledOnValueChange,
159
172
  open: controlledOpen,
160
173
  onOpenChange: controlledOnOpenChange,
174
+ onClose,
161
175
  shouldFilter = true,
162
176
  disabled = false,
163
177
  itemToStringValue,
@@ -200,6 +214,39 @@ function Combobox({
200
214
  [isValueControlled, controlledOnValueChange]
201
215
  );
202
216
 
217
+ // Close-commit callback (kept in sync with the identical block in
218
+ // select.tsx): watch the resolved open state — not close *requests* — so
219
+ // controlled consumers that veto a close never get a spurious onClose, and
220
+ // fire on the open → closed transition. Item selection calls onValueChange
221
+ // synchronously in the same event handler before closing, so by the time
222
+ // this effect runs post-commit the new value has always been delivered —
223
+ // that ordering is the contract.
224
+ const onCloseRef = React.useRef(onClose);
225
+ React.useEffect(() => {
226
+ onCloseRef.current = onClose;
227
+ }, [onClose]);
228
+
229
+ const prevOpenRef = React.useRef(open);
230
+ React.useEffect(() => {
231
+ if (prevOpenRef.current && !open) {
232
+ onCloseRef.current?.();
233
+ }
234
+ prevOpenRef.current = open;
235
+ }, [open]);
236
+
237
+ // An unmount can BE the close (e.g. the popover is open inside a Dialog the
238
+ // same click dismisses) — the transition effect above never runs for an
239
+ // unmounting component, so fire from cleanup instead. Cleanups run
240
+ // child-first, so a react-hook-form Controller wrapping this component is
241
+ // still registered when its onBlur is invoked here.
242
+ React.useEffect(() => {
243
+ return () => {
244
+ if (prevOpenRef.current) {
245
+ onCloseRef.current?.();
246
+ }
247
+ };
248
+ }, []);
249
+
203
250
  // Batch item registrations via microtask to avoid per-item state updates
204
251
  const itemLabelsRef = React.useRef<Map<string, string>>(new Map());
205
252
  const pendingFlushRef = React.useRef(false);
@@ -13,7 +13,8 @@
13
13
  * datasets (1 000+ rows) where full DOM rendering is too expensive.
14
14
  * - Helpers: `DataTableSearch`, `DataTablePagination`,
15
15
  * `DataTableColumnHeader`, `DataTableSelectAllCheckbox`,
16
- * `DataTableSelectRowCheckbox`.
16
+ * `DataTableSelectRowCheckbox`, `DataTableBulkActions` (+ `…Summary`,
17
+ * `…Actions`).
17
18
  * - Layout: `DataTableToolbar`, `DataTableToolbarLeft`,
18
19
  * `DataTableToolbarRight` — responsive flex container for search +
19
20
  * pagination above (or below) the table.
@@ -54,13 +55,9 @@ import { useVirtualizer } from "@tanstack/react-virtual";
54
55
  import { ArrowDown, ArrowUp, ArrowUpDown, Search, X } from "@brightlocal/icons";
55
56
 
56
57
  import { cn } from "@brightlocal/ui-components/lib/utils";
57
- import { Button } from "../components/button";
58
- import { Checkbox } from "../components/checkbox";
59
- import {
60
- InputGroup,
61
- InputGroupAddon,
62
- InputGroupInput,
63
- } from "../components/input-group";
58
+ import { Button } from "./button";
59
+ import { Checkbox } from "./checkbox";
60
+ import { InputGroup, InputGroupAddon, InputGroupInput } from "./input-group";
64
61
  import {
65
62
  Pagination,
66
63
  PaginationContent,
@@ -70,8 +67,8 @@ import {
70
67
  PaginationNext,
71
68
  PaginationPrevious,
72
69
  usePagination,
73
- } from "../components/pagination";
74
- import { Skeleton } from "../components/skeleton";
70
+ } from "./pagination";
71
+ import { Skeleton } from "./skeleton";
75
72
  import {
76
73
  Table,
77
74
  TableBody,
@@ -79,7 +76,8 @@ import {
79
76
  TableHead,
80
77
  TableHeader,
81
78
  TableRow,
82
- } from "../components/table";
79
+ } from "./table";
80
+ import { TypographyMuted } from "./typography";
83
81
 
84
82
  /* -------------------------------------------------------------------------------------------------
85
83
  * useDataTable (hook)
@@ -404,8 +402,8 @@ export interface DataTableProps<TData> {
404
402
  noResultsMessage?: string;
405
403
  /**
406
404
  * Pin the `<thead>` to the top of the scroll container so column headers
407
- * remain visible while scrolling. The header receives an opaque background
408
- * (`bg-background`) to separate it from body rows.
405
+ * remain visible while scrolling. The header keeps its opaque `bg-muted`
406
+ * background to separate it from body rows.
409
407
  * @default false
410
408
  */
411
409
  stickyHeader?: boolean;
@@ -541,9 +539,7 @@ function DataTableHeaderRows<TData>({
541
539
  stickyHeader: boolean;
542
540
  }) {
543
541
  return (
544
- <TableHeader
545
- className={cn(stickyHeader && "bg-background sticky top-0 z-10")}
546
- >
542
+ <TableHeader className={cn(stickyHeader && "sticky top-0 z-10")}>
547
543
  {table.getHeaderGroups().map((headerGroup) => (
548
544
  <TableRow key={headerGroup.id}>
549
545
  {headerGroup.headers.map((header) => {
@@ -1514,6 +1510,264 @@ export function DataTableSelectRowCheckbox<TData>({
1514
1510
 
1515
1511
  DataTableSelectRowCheckbox.displayName = "DataTableSelectRowCheckbox";
1516
1512
 
1513
+ /* -------------------------------------------------------------------------------------------------
1514
+ * DataTableBulkActions (selection summary + bulk action bar)
1515
+ * -----------------------------------------------------------------------------------------------*/
1516
+
1517
+ /** Selection counts shared with the `DataTableBulkActions` sub-components. */
1518
+ export interface DataTableBulkActionsContextValue {
1519
+ /**
1520
+ * Number of currently selected (filtered) rows. With `manualFiltering` /
1521
+ * `manualPagination`, only selections among the currently loaded rows are
1522
+ * counted — clear the selection on page change, or keep your own count, if
1523
+ * selections may span server pages.
1524
+ */
1525
+ selectedCount: number;
1526
+ /**
1527
+ * Total number of (filtered) rows across all pages. Resolved via
1528
+ * `table.getRowCount()`, so in server-side mode pass `rowCount` to
1529
+ * `useDataTable` — the same option `DataTablePagination` relies on.
1530
+ */
1531
+ totalCount: number;
1532
+ }
1533
+
1534
+ const DataTableBulkActionsContext =
1535
+ React.createContext<DataTableBulkActionsContextValue | null>(null);
1536
+
1537
+ /**
1538
+ * Read the selection counts from the surrounding `DataTableBulkActions`.
1539
+ *
1540
+ * Use it to build your own summary or action parts when the provided
1541
+ * sub-components don't fit.
1542
+ *
1543
+ * @example
1544
+ * function ClearSelectionHint() {
1545
+ * const { selectedCount } = useDataTableBulkActionsContext();
1546
+ * return <span>{selectedCount} selected</span>;
1547
+ * }
1548
+ */
1549
+ export function useDataTableBulkActionsContext() {
1550
+ const context = React.useContext(DataTableBulkActionsContext);
1551
+ if (!context) {
1552
+ throw new Error(
1553
+ "DataTableBulkActions components must be used within <DataTableBulkActions>"
1554
+ );
1555
+ }
1556
+ return context;
1557
+ }
1558
+
1559
+ /**
1560
+ * Props for `DataTableBulkActions` — the root of the bulk-actions bar.
1561
+ */
1562
+ export interface DataTableBulkActionsProps<TData> {
1563
+ /** TanStack Table instance. */
1564
+ table: TanStackTable<TData>;
1565
+ /** Data hook for automated testing (REQUIRED). */
1566
+ dataHook: string;
1567
+ /** Analytics element identifier. */
1568
+ trackingEl?: string;
1569
+ /** Analytics label. */
1570
+ trackingLabel?: string;
1571
+ /** Additional class name. */
1572
+ className?: string;
1573
+ /**
1574
+ * Bar contents — compose `DataTableBulkActionsSummary`,
1575
+ * `DataTableBulkActionsActions`, and any custom parts in any order.
1576
+ */
1577
+ children?: React.ReactNode;
1578
+ }
1579
+
1580
+ /**
1581
+ * Bulk-actions bar for a DataTable with row selection.
1582
+ *
1583
+ * Renders an unstyled inline row — muted summary text next to its actions —
1584
+ * while at least one row is selected, and nothing otherwise. No surface, no
1585
+ * border, no background: it sits inside whatever toolbar row you put it in.
1586
+ *
1587
+ * The root owns only the container, the visibility rule, and the selection
1588
+ * counts (shared via context). It makes no decision about the rest of the
1589
+ * toolbar: search inputs, filters, and add buttons stay mounted unless the
1590
+ * consumer chooses to hide them.
1591
+ *
1592
+ * @example
1593
+ * <DataTableToolbar dataHook="toolbar">
1594
+ * <DataTableToolbarLeft>
1595
+ * <DataTableSearch table={table} dataHook="search" />
1596
+ * </DataTableToolbarLeft>
1597
+ * <DataTableToolbarRight>
1598
+ * <DataTableBulkActions table={table} dataHook="bulk-actions">
1599
+ * <DataTableBulkActionsSummary />
1600
+ * <DataTableBulkActionsActions>
1601
+ * <Button dataHook="bulk-remove" size="sm" variant="outline" onClick={removeSelected}>
1602
+ * Remove Selected
1603
+ * </Button>
1604
+ * </DataTableBulkActionsActions>
1605
+ * </DataTableBulkActions>
1606
+ * </DataTableToolbarRight>
1607
+ * </DataTableToolbar>
1608
+ */
1609
+ export function DataTableBulkActions<TData>({
1610
+ table,
1611
+ dataHook,
1612
+ trackingEl,
1613
+ trackingLabel,
1614
+ className,
1615
+ children,
1616
+ }: DataTableBulkActionsProps<TData>) {
1617
+ const selectedCount = table.getFilteredSelectedRowModel().rows.length;
1618
+ // getRowCount() = the rowCount option in manual mode, the filtered row
1619
+ // count otherwise — the same total DataTablePagination shows.
1620
+ const totalCount = table.getRowCount();
1621
+
1622
+ const contextValue = React.useMemo<DataTableBulkActionsContextValue>(
1623
+ () => ({ selectedCount, totalCount }),
1624
+ [selectedCount, totalCount]
1625
+ );
1626
+
1627
+ if (selectedCount === 0) return null;
1628
+
1629
+ return (
1630
+ <DataTableBulkActionsContext.Provider value={contextValue}>
1631
+ <div
1632
+ className={cn("flex items-center gap-2.5", className)}
1633
+ data-hook={dataHook}
1634
+ data-slot="data-table-bulk-actions"
1635
+ data-tracking-el={trackingEl ?? "data-table-bulk-actions"}
1636
+ data-tracking-label={trackingLabel}
1637
+ >
1638
+ {children}
1639
+ </div>
1640
+ </DataTableBulkActionsContext.Provider>
1641
+ );
1642
+ }
1643
+
1644
+ DataTableBulkActions.displayName = "DataTableBulkActions";
1645
+
1646
+ /* -------------------------------------------------------------------------------------------------
1647
+ * DataTableBulkActionsSummary (selection summary text)
1648
+ * -----------------------------------------------------------------------------------------------*/
1649
+
1650
+ /**
1651
+ * Props for `DataTableBulkActionsSummary`.
1652
+ */
1653
+ export interface DataTableBulkActionsSummaryProps {
1654
+ /**
1655
+ * Data hook for automated testing.
1656
+ * @default "data-table-bulk-actions-summary"
1657
+ */
1658
+ dataHook?: string;
1659
+ /** Additional class name. */
1660
+ className?: string;
1661
+ /**
1662
+ * Summary content. Pass a node, or a function receiving the selection
1663
+ * counts so you control wording, pluralization, and order.
1664
+ * @default "{selectedCount} of {totalCount} row(s) selected."
1665
+ */
1666
+ children?:
1667
+ | React.ReactNode
1668
+ | ((info: DataTableBulkActionsContextValue) => React.ReactNode);
1669
+ }
1670
+
1671
+ /**
1672
+ * Selection summary text for the bulk-actions bar — muted, small, inline.
1673
+ *
1674
+ * Renders the default English summary when given no children. Pass a
1675
+ * function to build the string from the counts — the i18n-friendly form, and
1676
+ * the way to get shorter copy such as `"3 selected"`.
1677
+ * Must be used within `<DataTableBulkActions>`.
1678
+ *
1679
+ * Carries `role="status"` so screen readers hear the count change as rows are
1680
+ * selected. Custom summaries built on `useDataTableBulkActionsContext` should
1681
+ * do the same. Known limitation: the bar (and with it this live region)
1682
+ * mounts on the first selection, and some screen-reader/browser pairs do not
1683
+ * announce content already present when a live region is inserted — the 0→1
1684
+ * change may be silent, while every later change is announced. Keep your own
1685
+ * always-mounted `role="status"` node if announcing the first selection is
1686
+ * critical.
1687
+ *
1688
+ * @example
1689
+ * <DataTableBulkActionsSummary>
1690
+ * {({ selectedCount, totalCount }) =>
1691
+ * t("table.selected", { count: selectedCount, total: totalCount })
1692
+ * }
1693
+ * </DataTableBulkActionsSummary>
1694
+ */
1695
+ export function DataTableBulkActionsSummary({
1696
+ dataHook = "data-table-bulk-actions-summary",
1697
+ className,
1698
+ children,
1699
+ }: DataTableBulkActionsSummaryProps) {
1700
+ const { selectedCount, totalCount } = useDataTableBulkActionsContext();
1701
+
1702
+ let content: React.ReactNode;
1703
+ if (typeof children === "function") {
1704
+ content = children({ selectedCount, totalCount });
1705
+ } else if (children != null) {
1706
+ content = children;
1707
+ } else {
1708
+ content = `${selectedCount} of ${totalCount} row(s) selected.`;
1709
+ }
1710
+
1711
+ return (
1712
+ <TypographyMuted
1713
+ asChild
1714
+ className={cn("min-w-0", className)}
1715
+ dataHook={dataHook}
1716
+ >
1717
+ <span data-slot="data-table-bulk-actions-summary" role="status">
1718
+ {content}
1719
+ </span>
1720
+ </TypographyMuted>
1721
+ );
1722
+ }
1723
+
1724
+ DataTableBulkActionsSummary.displayName = "DataTableBulkActionsSummary";
1725
+
1726
+ /* -------------------------------------------------------------------------------------------------
1727
+ * DataTableBulkActionsActions (action button group)
1728
+ * -----------------------------------------------------------------------------------------------*/
1729
+
1730
+ /**
1731
+ * Props for `DataTableBulkActionsActions`.
1732
+ */
1733
+ export interface DataTableBulkActionsActionsProps {
1734
+ /**
1735
+ * Data hook for automated testing.
1736
+ * @default "data-table-bulk-actions-actions"
1737
+ */
1738
+ dataHook?: string;
1739
+ /** Additional class name. */
1740
+ className?: string;
1741
+ /** Action element(s) — typically one or more `Button`s. */
1742
+ children?: React.ReactNode;
1743
+ }
1744
+
1745
+ /**
1746
+ * Action slot for the bulk-actions bar — keeps its buttons at their
1747
+ * intrinsic width so a long summary can't squeeze them.
1748
+ *
1749
+ * Optional: a single action can sit directly inside
1750
+ * `DataTableBulkActions`. Use this when you have several, or need them
1751
+ * grouped and protected from shrinking.
1752
+ */
1753
+ export function DataTableBulkActionsActions({
1754
+ dataHook = "data-table-bulk-actions-actions",
1755
+ className,
1756
+ children,
1757
+ }: DataTableBulkActionsActionsProps) {
1758
+ return (
1759
+ <div
1760
+ className={cn("flex shrink-0 items-center gap-2", className)}
1761
+ data-hook={dataHook}
1762
+ data-slot="data-table-bulk-actions-actions"
1763
+ >
1764
+ {children}
1765
+ </div>
1766
+ );
1767
+ }
1768
+
1769
+ DataTableBulkActionsActions.displayName = "DataTableBulkActionsActions";
1770
+
1517
1771
  /* -------------------------------------------------------------------------------------------------
1518
1772
  * DataTableToolbar (layout container)
1519
1773
  * -----------------------------------------------------------------------------------------------*/
@@ -11,6 +11,9 @@ function FieldSet({ className, ...props }: React.ComponentProps<"fieldset">) {
11
11
  className={cn(
12
12
  "flex flex-col gap-6",
13
13
  "has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3",
14
+ // sr-only children (FieldLegend srOnly) are position:absolute — FieldSet
15
+ // must be their containing block (see components.md sr-only rule)
16
+ "has-[>.sr-only]:relative",
14
17
  className
15
18
  )}
16
19
  data-slot="field-set"
@@ -27,6 +30,12 @@ interface FieldLegendProps extends React.ComponentProps<"legend"> {
27
30
  * @default "legend"
28
31
  */
29
32
  variant?: "legend" | "label";
33
+ /**
34
+ * Visually hides the legend while keeping it in the accessibility tree,
35
+ * so the FieldSet group keeps its accessible name.
36
+ * @default false
37
+ */
38
+ srOnly?: boolean;
30
39
  }
31
40
 
32
41
  const fieldLegendVariants: FieldLegendProps["variant"][] = ["legend", "label"];
@@ -34,6 +43,7 @@ const fieldLegendVariants: FieldLegendProps["variant"][] = ["legend", "label"];
34
43
  function FieldLegend({
35
44
  className,
36
45
  variant = "legend",
46
+ srOnly = false,
37
47
  ...props
38
48
  }: FieldLegendProps) {
39
49
  return (
@@ -42,6 +52,7 @@ function FieldLegend({
42
52
  "mb-3 font-medium",
43
53
  "data-[variant=legend]:text-base",
44
54
  "data-[variant=label]:text-sm",
55
+ srOnly && "sr-only",
45
56
  className
46
57
  )}
47
58
  data-slot="field-legend"
@@ -75,6 +86,9 @@ const fieldVariants = cva(
75
86
  "has-[>[role=checkbox]]:gap-3",
76
87
  // Label leading overrides: use leading-normal for wrap-capable labels (checkbox)
77
88
  "has-[>[role=checkbox]]:[&_[data-slot=field-label]]:leading-normal",
89
+ // sr-only children are position:absolute — Field must be their containing
90
+ // block so they cannot escape scroll viewports (see components.md sr-only rule)
91
+ "has-[>.sr-only]:relative",
78
92
  ],
79
93
  {
80
94
  variants: {
@@ -84,11 +98,19 @@ const fieldVariants = cva(
84
98
  "grid grid-cols-[auto_1fr] items-center gap-x-2",
85
99
  "[&>[data-slot=field-description]]:col-start-2 [&>[data-slot=field-error]]:col-start-2",
86
100
  "has-[>[data-slot=field-content]]:items-start",
101
+ // sr-only label leaves grid flow — collapse to a single column
102
+ "has-[>.sr-only[data-slot=field-label]]:grid-cols-[1fr]",
103
+ "[&:has(>.sr-only[data-slot=field-label])>[data-slot=field-description]]:col-start-1",
104
+ "[&:has(>.sr-only[data-slot=field-label])>[data-slot=field-error]]:col-start-1",
87
105
  ],
88
106
  responsive: [
89
107
  "flex-col [&>*]:w-full [&>.sr-only]:w-auto @md/field-group:grid @md/field-group:grid-cols-[auto_1fr] @md/field-group:items-center @md/field-group:[&>*]:w-auto",
90
108
  "@md/field-group:[&>[data-slot=field-description]]:col-start-2 @md/field-group:[&>[data-slot=field-error]]:col-start-2",
91
109
  "@md/field-group:has-[>[data-slot=field-content]]:items-start",
110
+ // sr-only label leaves grid flow — collapse to a single column
111
+ "@md/field-group:has-[>.sr-only[data-slot=field-label]]:grid-cols-[1fr]",
112
+ "@md/field-group:[&:has(>.sr-only[data-slot=field-label])>[data-slot=field-description]]:col-start-1",
113
+ "@md/field-group:[&:has(>.sr-only[data-slot=field-label])>[data-slot=field-error]]:col-start-1",
92
114
  ],
93
115
  },
94
116
  variant: {
@@ -190,6 +212,15 @@ interface FieldLabelProps extends LabelProps {
190
212
  * Data hook for automated testing (REQUIRED)
191
213
  */
192
214
  dataHook: string;
215
+ /**
216
+ * Visually hides the label while keeping it in the accessibility tree,
217
+ * preserving the label/input association via `htmlFor`.
218
+ * Use for placeholder-only or visually-compact field designs.
219
+ * Do not combine with `variant="box"` or RadioGroup fields — there the
220
+ * visible label provides the full-row click target.
221
+ * @default false
222
+ */
223
+ srOnly?: boolean;
193
224
  }
194
225
 
195
226
  function FieldLabel({
@@ -1,8 +1,11 @@
1
1
  import * as React from "react";
2
2
 
3
+ import { ArrowLeft } from "@brightlocal/icons";
3
4
  import { cn } from "@brightlocal/ui-components/lib/utils";
4
5
  import { Header } from "./header";
6
+ import { Link } from "./link";
5
7
  import { ScrollArea } from "./scroll-area";
8
+ import { TypographyMuted } from "./typography";
6
9
 
7
10
  interface GlobalLayoutProps extends React.ComponentProps<"div"> {
8
11
  /**
@@ -167,6 +170,86 @@ const GlobalLayoutContent = React.forwardRef<
167
170
 
168
171
  GlobalLayoutContent.displayName = "GlobalLayoutContent";
169
172
 
173
+ interface GlobalLayoutBackLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
174
+ /**
175
+ * Data hook for automated testing
176
+ * @default "content-header-back-link"
177
+ */
178
+ dataHook?: string;
179
+ /**
180
+ * Accessible label for the icon-only back link.
181
+ * @default "Go back"
182
+ */
183
+ ariaLabel?: string;
184
+ }
185
+
186
+ /**
187
+ * Icon-only back link for the page header. Place it as a direct child of
188
+ * `GlobalLayoutContentHeader` — the header positions it before the title.
189
+ * Pass `href` for URL navigation or `onClick` for SPA router navigation.
190
+ */
191
+ const GlobalLayoutBackLink = React.forwardRef<
192
+ HTMLAnchorElement,
193
+ GlobalLayoutBackLinkProps
194
+ >(({ dataHook, ariaLabel, href, onClick, ...props }, ref) => {
195
+ // An anchor without href is not keyboard-focusable, so when only a click
196
+ // handler is given the link falls back to href="#" and cancels the hash
197
+ // navigation before delegating to the handler.
198
+ const handleClick: React.MouseEventHandler<HTMLAnchorElement> = (event) => {
199
+ if (href === undefined) {
200
+ event.preventDefault();
201
+ }
202
+ onClick?.(event);
203
+ };
204
+
205
+ return (
206
+ <Link
207
+ ref={ref}
208
+ // `||` rather than `??`: an icon-only link must never end up with an
209
+ // empty accessible name, so an empty string also falls back.
210
+ aria-label={ariaLabel || "Go back"}
211
+ data-slot="content-header-back-link"
212
+ dataHook={dataHook ?? "content-header-back-link"}
213
+ href={href ?? "#"}
214
+ variant="icon"
215
+ onClick={handleClick}
216
+ {...props}
217
+ >
218
+ <ArrowLeft aria-hidden="true" />
219
+ </Link>
220
+ );
221
+ });
222
+
223
+ GlobalLayoutBackLink.displayName = "GlobalLayoutBackLink";
224
+
225
+ interface GlobalLayoutSubtitleProps extends React.ComponentProps<"p"> {
226
+ /**
227
+ * Data hook for automated testing
228
+ * @default "content-header-subtitle"
229
+ */
230
+ dataHook?: string;
231
+ }
232
+
233
+ /**
234
+ * Muted description text for the page header. Place it as a direct child of
235
+ * `GlobalLayoutContentHeader` — the header positions it below the title row.
236
+ */
237
+ const GlobalLayoutSubtitle = React.forwardRef<
238
+ HTMLParagraphElement,
239
+ GlobalLayoutSubtitleProps
240
+ >(({ dataHook, ...props }, ref) => {
241
+ return (
242
+ <TypographyMuted
243
+ ref={ref}
244
+ data-slot="content-header-subtitle"
245
+ dataHook={dataHook ?? "content-header-subtitle"}
246
+ {...props}
247
+ />
248
+ );
249
+ });
250
+
251
+ GlobalLayoutSubtitle.displayName = "GlobalLayoutSubtitle";
252
+
170
253
  interface GlobalLayoutContentHeaderProps extends React.ComponentProps<"header"> {
171
254
  /**
172
255
  * Data hook for automated testing (required)
@@ -190,13 +273,53 @@ const GlobalLayoutContentHeader = React.forwardRef<
190
273
  { className, dataHook, trackingEl, trackingLabel, children, ...props },
191
274
  ref
192
275
  ) => {
276
+ // Slot the back link and subtitle out of the flat children so the
277
+ // header can lay them out per the design: back link before a column of
278
+ // title row + subtitle. Both must be direct children (not wrapped in
279
+ // fragments or other elements).
280
+ const backLinks: React.ReactNode[] = [];
281
+ const subtitles: React.ReactNode[] = [];
282
+ const titleChildren: React.ReactNode[] = [];
283
+
284
+ React.Children.forEach(children, (child) => {
285
+ if (React.isValidElement(child) && child.type === GlobalLayoutBackLink) {
286
+ backLinks.push(child);
287
+ } else if (
288
+ React.isValidElement(child) &&
289
+ child.type === GlobalLayoutSubtitle
290
+ ) {
291
+ subtitles.push(child);
292
+ } else {
293
+ titleChildren.push(child);
294
+ }
295
+ });
296
+
297
+ // Without a back link or subtitle the header keeps its original flat
298
+ // structure — children are laid out directly by the header row.
299
+ if (backLinks.length === 0 && subtitles.length === 0) {
300
+ return (
301
+ <Header
302
+ ref={ref}
303
+ className={cn(
304
+ "mx-auto w-full flex-wrap justify-between gap-4",
305
+ className
306
+ )}
307
+ data-slot="content-header"
308
+ dataHook={dataHook}
309
+ style={{ maxWidth: "var(--ds-breakpoint-lg)" }}
310
+ trackingEl={trackingEl}
311
+ trackingLabel={trackingLabel}
312
+ {...props}
313
+ >
314
+ {children}
315
+ </Header>
316
+ );
317
+ }
318
+
193
319
  return (
194
320
  <Header
195
321
  ref={ref}
196
- className={cn(
197
- "mx-auto w-full flex-wrap justify-between gap-4",
198
- className
199
- )}
322
+ className={cn("mx-auto w-full items-start", className)}
200
323
  data-slot="content-header"
201
324
  dataHook={dataHook}
202
325
  style={{ maxWidth: "var(--ds-breakpoint-lg)" }}
@@ -204,7 +327,19 @@ const GlobalLayoutContentHeader = React.forwardRef<
204
327
  trackingLabel={trackingLabel}
205
328
  {...props}
206
329
  >
207
- {children}
330
+ {backLinks}
331
+ <div
332
+ className="flex min-w-0 flex-1 flex-col gap-2"
333
+ data-slot="content-header-body"
334
+ >
335
+ <div
336
+ className="flex w-full flex-wrap items-center justify-between gap-4"
337
+ data-slot="content-header-title"
338
+ >
339
+ {titleChildren}
340
+ </div>
341
+ {subtitles}
342
+ </div>
208
343
  </Header>
209
344
  );
210
345
  }
@@ -364,6 +499,8 @@ export {
364
499
  GlobalLayoutContent,
365
500
  GlobalLayoutContentActions,
366
501
  GlobalLayoutContentHeader,
502
+ GlobalLayoutBackLink,
503
+ GlobalLayoutSubtitle,
367
504
  GlobalLayoutContentBody,
368
505
  GlobalLayoutMobileHeader,
369
506
  };
@@ -374,6 +511,8 @@ export type {
374
511
  GlobalLayoutContentProps,
375
512
  GlobalLayoutContentActionsProps,
376
513
  GlobalLayoutContentHeaderProps,
514
+ GlobalLayoutBackLinkProps,
515
+ GlobalLayoutSubtitleProps,
377
516
  GlobalLayoutContentBodyProps,
378
517
  GlobalLayoutMobileHeaderProps,
379
518
  };