@brightlocal/ui-components 3.0.0 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (235) hide show
  1. package/README.md +7 -1
  2. package/component-meta.json +749 -53
  3. package/deprecations.json +114 -4
  4. package/dist/accordion.cjs +1 -1
  5. package/dist/accordion.d.ts +36 -0
  6. package/dist/accordion.d.ts.map +1 -1
  7. package/dist/accordion.js +74 -61
  8. package/dist/alert-dialog.cjs +1 -1
  9. package/dist/alert-dialog.d.ts +32 -3
  10. package/dist/alert-dialog.d.ts.map +1 -1
  11. package/dist/alert-dialog.js +61 -58
  12. package/dist/alert.cjs +1 -1
  13. package/dist/alert.d.ts.map +1 -1
  14. package/dist/alert.js +58 -57
  15. package/dist/badge.cjs +1 -1
  16. package/dist/badge.d.ts +9 -0
  17. package/dist/badge.d.ts.map +1 -1
  18. package/dist/badge.js +50 -30
  19. package/dist/banner.cjs +1 -0
  20. package/dist/banner.d.ts +81 -0
  21. package/dist/banner.d.ts.map +1 -0
  22. package/dist/banner.js +176 -0
  23. package/dist/blocks/empty-state.cjs +1 -1
  24. package/dist/blocks/empty-state.d.ts +4 -3
  25. package/dist/blocks/empty-state.d.ts.map +1 -1
  26. package/dist/blocks/empty-state.js +50 -57
  27. package/dist/blocks/progress-state.d.ts +2 -2
  28. package/dist/blocks/sidebar.cjs +1 -1
  29. package/dist/blocks/sidebar.d.ts +17 -0
  30. package/dist/blocks/sidebar.d.ts.map +1 -1
  31. package/dist/blocks/sidebar.js +8 -2
  32. package/dist/brand-illustration-motif.d.ts +1 -1
  33. package/dist/button-group.cjs +1 -0
  34. package/dist/button-group.d.ts +36 -0
  35. package/dist/button-group.d.ts.map +1 -0
  36. package/dist/button-group.js +47 -0
  37. package/dist/button.cjs +1 -1
  38. package/dist/button.js +1 -1
  39. package/dist/card.cjs +1 -1
  40. package/dist/card.d.ts +105 -7
  41. package/dist/card.d.ts.map +1 -1
  42. package/dist/card.js +198 -101
  43. package/dist/chart.cjs +3 -3
  44. package/dist/chart.d.ts +270 -24
  45. package/dist/chart.d.ts.map +1 -1
  46. package/dist/chart.js +497 -322
  47. package/dist/checkbox.cjs +1 -1
  48. package/dist/checkbox.d.ts +1 -1
  49. package/dist/checkbox.d.ts.map +1 -1
  50. package/dist/checkbox.js +2 -1
  51. package/dist/chip.cjs +1 -1
  52. package/dist/chip.d.ts +38 -4
  53. package/dist/chip.d.ts.map +1 -1
  54. package/dist/chip.js +95 -81
  55. package/dist/combobox.cjs +1 -1
  56. package/dist/combobox.js +2 -2
  57. package/dist/command.cjs +1 -1
  58. package/dist/command.d.ts +23 -1
  59. package/dist/command.d.ts.map +1 -1
  60. package/dist/command.js +251 -225
  61. package/dist/data-table.cjs +1 -1
  62. package/dist/data-table.d.ts +201 -23
  63. package/dist/data-table.d.ts.map +1 -1
  64. package/dist/data-table.js +712 -568
  65. package/dist/date-picker.cjs +1 -1
  66. package/dist/date-picker.d.ts +13 -5
  67. package/dist/date-picker.d.ts.map +1 -1
  68. package/dist/date-picker.js +54 -53
  69. package/dist/field.cjs +1 -1
  70. package/dist/field.d.ts +8 -1
  71. package/dist/field.d.ts.map +1 -1
  72. package/dist/field.js +79 -52
  73. package/dist/global-layout.cjs +1 -1
  74. package/dist/global-layout.d.ts +105 -13
  75. package/dist/global-layout.d.ts.map +1 -1
  76. package/dist/global-layout.js +146 -129
  77. package/dist/grid.d.ts +26 -3
  78. package/dist/grid.d.ts.map +1 -1
  79. package/dist/hooks/use-breakpoint.cjs +1 -1
  80. package/dist/hooks/use-breakpoint.d.ts +1 -1
  81. package/dist/hooks/use-breakpoint.d.ts.map +1 -1
  82. package/dist/hooks/use-breakpoint.js +1 -0
  83. package/dist/hooks/use-mobile.cjs +1 -0
  84. package/dist/hooks/use-mobile.js +8 -0
  85. package/dist/index.cjs +1 -1
  86. package/dist/index.d.ts +6 -0
  87. package/dist/index.d.ts.map +1 -1
  88. package/dist/index.js +594 -553
  89. package/dist/info-tooltip.cjs +1 -0
  90. package/dist/info-tooltip.d.ts +39 -0
  91. package/dist/info-tooltip.d.ts.map +1 -0
  92. package/dist/info-tooltip.js +41 -0
  93. package/dist/input-chip.cjs +1 -1
  94. package/dist/input-chip.js +1 -1
  95. package/dist/input-group.cjs +1 -1
  96. package/dist/input-group.d.ts +33 -2
  97. package/dist/input-group.d.ts.map +1 -1
  98. package/dist/input-group.js +167 -54
  99. package/dist/input-otp.cjs +1 -1
  100. package/dist/input-otp.js +9 -9
  101. package/dist/input-password.cjs +1 -1
  102. package/dist/input-password.d.ts +45 -15
  103. package/dist/input-password.d.ts.map +1 -1
  104. package/dist/input-password.js +31 -30
  105. package/dist/input.cjs +1 -1
  106. package/dist/input.js +10 -10
  107. package/dist/lib/block-illustration.cjs +1 -1
  108. package/dist/lib/block-illustration.d.ts +4 -1
  109. package/dist/lib/block-illustration.d.ts.map +1 -1
  110. package/dist/lib/block-illustration.js +12 -11
  111. package/dist/lib/empty-chip.cjs +1 -0
  112. package/dist/lib/empty-chip.d.ts +4 -0
  113. package/dist/lib/empty-chip.d.ts.map +1 -0
  114. package/dist/lib/empty-chip.js +13 -0
  115. package/dist/lib/utils.cjs +1 -1
  116. package/dist/lib/utils.d.ts.map +1 -1
  117. package/dist/lib/utils.js +4 -3
  118. package/dist/list.cjs +1 -1
  119. package/dist/list.js +1 -1
  120. package/dist/multi-select-filter.cjs +1 -0
  121. package/dist/multi-select-filter.d.ts +178 -0
  122. package/dist/multi-select-filter.d.ts.map +1 -0
  123. package/dist/multi-select-filter.js +463 -0
  124. package/dist/pagination.cjs +1 -1
  125. package/dist/pagination.d.ts +3 -0
  126. package/dist/pagination.d.ts.map +1 -1
  127. package/dist/pagination.js +57 -57
  128. package/dist/progress.cjs +1 -1
  129. package/dist/progress.d.ts +123 -16
  130. package/dist/progress.d.ts.map +1 -1
  131. package/dist/progress.js +89 -75
  132. package/dist/rating.cjs +1 -1
  133. package/dist/rating.js +18 -18
  134. package/dist/relative-date.cjs +1 -0
  135. package/dist/relative-date.d.ts +65 -0
  136. package/dist/relative-date.d.ts.map +1 -0
  137. package/dist/relative-date.js +128 -0
  138. package/dist/scroll-area.cjs +1 -1
  139. package/dist/scroll-area.d.ts +15 -6
  140. package/dist/scroll-area.d.ts.map +1 -1
  141. package/dist/scroll-area.js +38 -36
  142. package/dist/select.cjs +2 -2
  143. package/dist/select.d.ts +24 -3
  144. package/dist/select.d.ts.map +1 -1
  145. package/dist/select.js +130 -110
  146. package/dist/sheet.cjs +1 -1
  147. package/dist/sheet.d.ts +78 -2
  148. package/dist/sheet.d.ts.map +1 -1
  149. package/dist/sheet.js +192 -85
  150. package/dist/single-select-filter.cjs +1 -0
  151. package/dist/single-select-filter.d.ts +81 -0
  152. package/dist/single-select-filter.d.ts.map +1 -0
  153. package/dist/single-select-filter.js +226 -0
  154. package/dist/sonner.cjs +1 -1
  155. package/dist/sonner.d.ts.map +1 -1
  156. package/dist/sonner.js +22 -22
  157. package/dist/split-layout.cjs +1 -1
  158. package/dist/split-layout.d.ts +1 -1
  159. package/dist/split-layout.js +13 -13
  160. package/dist/table.cjs +1 -1
  161. package/dist/table.d.ts +45 -4
  162. package/dist/table.d.ts.map +1 -1
  163. package/dist/table.js +90 -73
  164. package/dist/tabs.cjs +1 -1
  165. package/dist/tabs.d.ts +12 -1
  166. package/dist/tabs.d.ts.map +1 -1
  167. package/dist/tabs.js +148 -126
  168. package/dist/textarea.cjs +1 -1
  169. package/dist/textarea.js +1 -1
  170. package/dist/tooltip.cjs +1 -1
  171. package/dist/tooltip.d.ts +38 -36
  172. package/dist/tooltip.d.ts.map +1 -1
  173. package/dist/tooltip.js +262 -73
  174. package/dist/typography-heading.cjs +1 -1
  175. package/dist/typography-heading.d.ts +13 -0
  176. package/dist/typography-heading.d.ts.map +1 -1
  177. package/dist/typography-heading.js +32 -21
  178. package/dist/typography-text.cjs +1 -1
  179. package/dist/typography-text.d.ts +15 -2
  180. package/dist/typography-text.d.ts.map +1 -1
  181. package/dist/typography-text.js +35 -24
  182. package/dist/typography.d.ts +1 -1
  183. package/package.json +5 -6
  184. package/src/blocks/empty-state.tsx +17 -24
  185. package/src/blocks/progress-state.tsx +2 -2
  186. package/src/blocks/sidebar.tsx +26 -2
  187. package/src/components/accordion.tsx +82 -27
  188. package/src/components/alert-dialog.tsx +50 -5
  189. package/src/components/alert.tsx +16 -8
  190. package/src/components/badge.tsx +40 -3
  191. package/src/components/banner.tsx +288 -0
  192. package/src/components/brand-illustration-motif.tsx +1 -1
  193. package/src/components/button-group.tsx +112 -0
  194. package/src/components/button.tsx +1 -1
  195. package/src/components/card.tsx +249 -27
  196. package/src/components/chart.tsx +586 -53
  197. package/src/components/checkbox.tsx +1 -1
  198. package/src/components/chip.tsx +83 -10
  199. package/src/components/combobox.tsx +2 -2
  200. package/src/components/command.tsx +56 -4
  201. package/src/components/data-table.tsx +842 -199
  202. package/src/components/date-picker.tsx +18 -7
  203. package/src/components/field.tsx +81 -12
  204. package/src/components/global-layout.tsx +176 -38
  205. package/src/components/grid.tsx +34 -3
  206. package/src/components/info-tooltip.tsx +94 -0
  207. package/src/components/input-chip.tsx +1 -1
  208. package/src/components/input-group.tsx +246 -11
  209. package/src/components/input-otp.tsx +1 -1
  210. package/src/components/input-password.tsx +56 -22
  211. package/src/components/input.tsx +1 -1
  212. package/src/components/list.tsx +1 -1
  213. package/src/components/multi-select-filter.tsx +912 -0
  214. package/src/components/pagination.tsx +10 -3
  215. package/src/components/progress.tsx +190 -31
  216. package/src/components/rating.tsx +1 -1
  217. package/src/components/relative-date.tsx +230 -0
  218. package/src/components/scroll-area.tsx +23 -10
  219. package/src/components/select.tsx +65 -11
  220. package/src/components/sheet.tsx +240 -4
  221. package/src/components/single-select-filter.tsx +443 -0
  222. package/src/components/sonner.tsx +16 -5
  223. package/src/components/split-layout.tsx +2 -2
  224. package/src/components/table.tsx +71 -11
  225. package/src/components/tabs.tsx +93 -46
  226. package/src/components/textarea.tsx +1 -1
  227. package/src/components/tooltip.tsx +440 -68
  228. package/src/components/typography-heading.tsx +24 -0
  229. package/src/components/typography-text.tsx +27 -3
  230. package/src/components/typography.tsx +1 -1
  231. package/src/hooks/use-breakpoint.ts +2 -1
  232. package/src/index.ts +6 -0
  233. package/src/lib/block-illustration.tsx +5 -1
  234. package/src/lib/empty-chip.ts +24 -0
  235. package/src/lib/utils.ts +1 -0
@@ -77,17 +77,17 @@ function useDatePickerContext() {
77
77
  const context = React.useContext(DatePickerContext);
78
78
  if (!context) {
79
79
  throw new Error(
80
- "DatePicker compound components must be used within DatePickerRoot"
80
+ "DatePicker compound components must be used within DatePicker"
81
81
  );
82
82
  }
83
83
  return context;
84
84
  }
85
85
 
86
86
  // ============================================================================
87
- // DatePickerRoot
87
+ // DatePicker (root)
88
88
  // ============================================================================
89
89
 
90
- export interface DatePickerRootProps {
90
+ export interface DatePickerProps {
91
91
  /**
92
92
  * Data hook for automated testing (REQUIRED)
93
93
  */
@@ -155,9 +155,9 @@ export interface DatePickerRootProps {
155
155
  }
156
156
 
157
157
  /**
158
- * DatePickerRoot - Root component that provides context for all DatePicker parts
158
+ * DatePicker - Root component that provides context for all DatePicker parts
159
159
  */
160
- function DatePickerRoot({
160
+ function DatePicker({
161
161
  children,
162
162
  dataHook,
163
163
  trackingEl,
@@ -173,7 +173,7 @@ function DatePickerRoot({
173
173
  open: controlledOpen,
174
174
  onOpenChange,
175
175
  defaultOpen = false,
176
- }: DatePickerRootProps) {
176
+ }: DatePickerProps) {
177
177
  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(defaultOpen);
178
178
 
179
179
  const isControlled = controlledOpen !== undefined;
@@ -235,7 +235,17 @@ function DatePickerRoot({
235
235
  );
236
236
  }
237
237
 
238
- DatePickerRoot.displayName = "DatePickerRoot";
238
+ DatePicker.displayName = "DatePicker";
239
+
240
+ /**
241
+ * @deprecated Use `DatePicker` instead — family roots are bare names (DS-853).
242
+ */
243
+ const DatePickerRoot = DatePicker;
244
+
245
+ /**
246
+ * @deprecated Use `DatePickerProps` instead — family roots are bare names (DS-853).
247
+ */
248
+ export type DatePickerRootProps = DatePickerProps;
239
249
 
240
250
  // ============================================================================
241
251
  // DatePickerTrigger
@@ -594,6 +604,7 @@ DatePickerPresets.displayName = "DatePickerPresets";
594
604
  // ============================================================================
595
605
 
596
606
  export {
607
+ DatePicker,
597
608
  DatePickerRoot,
598
609
  DatePickerTrigger,
599
610
  DatePickerContent,
@@ -1,3 +1,6 @@
1
+ "use client";
2
+
3
+ import * as React from "react";
1
4
  import { cva, type VariantProps } from "class-variance-authority";
2
5
 
3
6
  import { AlertCircle, type LucideProps } from "@brightlocal/icons";
@@ -82,6 +85,10 @@ const fieldVariants = cva(
82
85
  "[[data-slot=radio-group]_&]:relative [[data-slot=radio-group]_&]:cursor-pointer [[data-slot=radio-group]_&]:gap-3 [[data-slot=radio-group]_&]:has-[[data-disabled]]:cursor-not-allowed",
83
86
  // RadioGroup context: label overlay spans the full Field for clickable row
84
87
  "[[data-slot=radio-group]_&_[data-slot=field-label]]:after:absolute [[data-slot=radio-group]_&_[data-slot=field-label]]:after:inset-0 [[data-slot=radio-group]_&_[data-slot=field-label]]:after:cursor-pointer [[data-slot=radio-group]_&:has([data-disabled])_[data-slot=field-label]]:after:cursor-not-allowed",
88
+ // DS-772: lift the control above the label overlay so a direct click on the
89
+ // control passes pointer hit-testing (Playwright check()/click() without
90
+ // force). Row/label clicks still delegate via the label's htmlFor.
91
+ "[[data-slot=radio-group]_&_[data-slot=radio-group-item]]:z-10",
85
92
  // Checkbox context: match RadioGroup gap-3 spacing
86
93
  "has-[>[role=checkbox]]:gap-3",
87
94
  // Label leading overrides: use leading-normal for wrap-capable labels (checkbox)
@@ -124,6 +131,13 @@ const fieldVariants = cva(
124
131
  "rounded-lg border border-border bg-background p-3",
125
132
  "transition-colors duration-fast ease-out",
126
133
  "[&_[data-slot=field-label]]:after:absolute [&_[data-slot=field-label]]:after:inset-0 [&_[data-slot=field-label]]:after:cursor-pointer",
134
+ // DS-772: lift controls above the label's full-card overlay so a
135
+ // direct click on the control passes pointer hit-testing (Playwright
136
+ // check()/click() without force). Card clicks still delegate via the
137
+ // label's htmlFor.
138
+ "[&_[data-slot=checkbox]]:relative [&_[data-slot=checkbox]]:z-10",
139
+ "[&_[data-slot=radio-group-item]]:z-10",
140
+ "[&_[data-slot=switch]]:relative [&_[data-slot=switch]]:z-10",
127
141
  // Focus ring when a child control receives focus
128
142
  "has-[:focus-visible]:shadow-default has-[:focus-visible]:border-ring",
129
143
  // Checked-state for radio/checkbox (not switch)
@@ -310,6 +324,23 @@ interface FieldErrorProps extends Omit<
310
324
  errors?: Array<FieldErrorItem | undefined>;
311
325
  }
312
326
 
327
+ const emptySubscribe = () => () => {};
328
+
329
+ /**
330
+ * True for renders driven by the client after hydration; false on the server
331
+ * and during hydration of server-rendered HTML (getServerSnapshot is used for
332
+ * both). Lets FieldError keep server-rendered messages in the initial HTML
333
+ * while deferring only client-side appearances for the live-region
334
+ * announcement — without hydration mismatches.
335
+ */
336
+ function useIsClientRender() {
337
+ return React.useSyncExternalStore(
338
+ emptySubscribe,
339
+ () => true,
340
+ () => false
341
+ );
342
+ }
343
+
313
344
  interface FieldErrorIconProps extends Omit<LucideProps, "ref"> {
314
345
  /**
315
346
  * Custom icon component to render instead of the default AlertCircle.
@@ -360,7 +391,13 @@ function FieldErrorIcon({
360
391
  * FieldError displays validation error messages within a Field.
361
392
  *
362
393
  * Supports both direct children content and an errors array for form library integration.
363
- * Uses role="alert" for accessibility, ensuring screen readers announce error messages.
394
+ * Renders a polite live region (role="status" / aria-live="polite") so screen readers
395
+ * announce the message when it appears and again whenever it changes (DS-964).
396
+ * A message that appears client-side is committed one tick after the region mounts —
397
+ * a live region is only announced reliably when it exists in the accessibility tree
398
+ * before its content does, and consumers mount FieldError conditionally, together with
399
+ * the message. Server-rendered messages stay in the initial HTML (no deferral): they
400
+ * are part of the page screen readers read on load, so they need no announcement.
364
401
  * No icon is displayed by default - use FieldErrorIcon for composition.
365
402
  *
366
403
  * @example
@@ -397,8 +434,37 @@ function FieldError({
397
434
  Boolean(e?.message)
398
435
  );
399
436
 
437
+ const hasMessage = Boolean(children) || Boolean(errorMessages?.length);
438
+
439
+ // Screen readers only announce live-region content that arrives *after* the
440
+ // region is in the accessibility tree. Consumers typically mount FieldError
441
+ // together with the message, so when a message appears client-side the
442
+ // region renders empty for the first paint and the message is committed
443
+ // right after — the resulting content mutation is what gets announced
444
+ // (DS-964). A FieldError whose first render happens on the server or during
445
+ // hydration keeps its message synchronous instead: the message must be in
446
+ // the server-rendered HTML, and content present at page load is read with
447
+ // the page, so it needs no announcement. The distinction is captured as the
448
+ // initial state of `defer` (a post-hydration re-render must not blank a
449
+ // server-rendered message) and latches to "defer" once the message clears
450
+ // client-side, because any later message is a client-side appearance.
451
+ const isClientRender = useIsClientRender();
452
+ const [defer, setDefer] = React.useState(isClientRender);
453
+ const [announced, setAnnounced] = React.useState(false);
454
+
455
+ React.useEffect(() => {
456
+ if (!hasMessage) {
457
+ setDefer(true);
458
+ setAnnounced(false);
459
+ } else if (defer) {
460
+ setAnnounced(true);
461
+ }
462
+ }, [defer, hasMessage]);
463
+
464
+ const showMessage = hasMessage && (!defer || announced);
465
+
400
466
  // If no children and no valid errors, don't render anything
401
- if (!children && (!errorMessages || errorMessages.length === 0)) {
467
+ if (!hasMessage) {
402
468
  return null;
403
469
  }
404
470
 
@@ -415,21 +481,24 @@ function FieldError({
415
481
 
416
482
  return (
417
483
  <div
484
+ aria-atomic="true"
485
+ aria-live="polite"
418
486
  className={baseStyles}
419
487
  data-hook={dataHook}
420
488
  data-slot="field-error"
421
- role="alert"
489
+ role="status"
422
490
  {...props}
423
491
  >
424
- {isMultiple ? (
425
- <ul className="list-disc space-y-1 pl-4">
426
- {errorMessages.map((error, index) => (
427
- <li key={index}>{error.message}</li>
428
- ))}
429
- </ul>
430
- ) : (
431
- <p className="m-0">{children || errorMessages?.[0]?.message}</p>
432
- )}
492
+ {showMessage &&
493
+ (isMultiple ? (
494
+ <ul className="list-disc space-y-1 pl-4">
495
+ {errorMessages.map((error, index) => (
496
+ <li key={index}>{error.message}</li>
497
+ ))}
498
+ </ul>
499
+ ) : (
500
+ <p className="m-0">{children || errorMessages?.[0]?.message}</p>
501
+ ))}
433
502
  </div>
434
503
  );
435
504
  }
@@ -3,6 +3,7 @@ import * as React from "react";
3
3
  import { ArrowLeft } from "@brightlocal/icons";
4
4
  import { cn } from "@brightlocal/ui-components/lib/utils";
5
5
  import { Breadcrumb } from "./breadcrumb";
6
+ import { Button } from "./button";
6
7
  import { Header } from "./header";
7
8
  import { Link } from "./link";
8
9
  import { ScrollArea } from "./scroll-area";
@@ -193,50 +194,140 @@ GlobalLayoutContent.displayName = "GlobalLayoutContent";
193
194
  // the full width.
194
195
  const CONTENT_REGION_PX = "px-4 md:px-6 lg:px-section-xs";
195
196
 
196
- interface GlobalLayoutBackLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
197
+ interface GlobalLayoutBackLinkCommonProps {
197
198
  /**
198
199
  * Data hook for automated testing
199
200
  * @default "content-header-back-link"
200
201
  */
201
202
  dataHook?: string;
202
203
  /**
203
- * Accessible label for the icon-only back link.
204
+ * Accessible label for the icon-only back control.
204
205
  * @default "Go back"
205
206
  */
206
207
  ariaLabel?: string;
207
208
  }
208
209
 
210
+ // Attributes that exist on only one of the two rendered elements. Each mode
211
+ // explicitly rejects the other's (`?: never`, mirroring EmptyState's
212
+ // size-exclusive props) so a cross-mode attribute — `disabled` on the anchor,
213
+ // `target` on the button — fails to compile instead of silently landing on
214
+ // the wrong element.
215
+ type AnchorOnlyAttributes = Omit<
216
+ React.AnchorHTMLAttributes<HTMLAnchorElement>,
217
+ keyof React.ButtonHTMLAttributes<HTMLButtonElement>
218
+ >;
219
+ type ButtonOnlyAttributes = Omit<
220
+ React.ButtonHTMLAttributes<HTMLButtonElement>,
221
+ keyof React.AnchorHTMLAttributes<HTMLAnchorElement>
222
+ >;
223
+ type ForbiddenAttributes<T> = { [K in keyof T]?: never };
224
+
225
+ /**
226
+ * Anchor mode: a real destination, rendered as `Link variant="icon"`.
227
+ */
228
+ interface GlobalLayoutBackLinkAnchorProps
229
+ extends
230
+ GlobalLayoutBackLinkCommonProps,
231
+ React.AnchorHTMLAttributes<HTMLAnchorElement>,
232
+ ForbiddenAttributes<ButtonOnlyAttributes> {
233
+ /** Destination URL — renders a real link (`<a>`). */
234
+ href: string;
235
+ }
236
+
209
237
  /**
210
- * Icon-only back link for the page header. Place it as a direct child of
238
+ * Button mode: no destination, rendered as an icon `<button>` for SPA
239
+ * router navigation via `onClick`.
240
+ */
241
+ interface GlobalLayoutBackLinkButtonProps
242
+ extends
243
+ GlobalLayoutBackLinkCommonProps,
244
+ Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "type">,
245
+ ForbiddenAttributes<AnchorOnlyAttributes> {
246
+ /** Omit `href` to render a `<button>` for SPA router navigation. */
247
+ href?: undefined;
248
+ /**
249
+ * Button type attribute (button mode only).
250
+ * @default "button"
251
+ */
252
+ type?: "button" | "submit";
253
+ }
254
+
255
+ /**
256
+ * Discriminated on `href` so the impossible combinations don't compile:
257
+ * anchor-only attributes (target, rel, download, …) require an `href`, and
258
+ * button-only attributes (disabled, form*, …) apply only without one. DS-847
259
+ * removed the old `href="#"` + preventDefault fallback — an action that
260
+ * doesn't navigate now has real button semantics.
261
+ *
262
+ * The leading inline block restates the shared props (plus `href`, the
263
+ * discriminant) so the registry's props extractor, which reads the first
264
+ * braced block after this declaration, documents them; the mode interfaces
265
+ * remain the source of the per-mode constraints.
266
+ */
267
+ type GlobalLayoutBackLinkProps = {
268
+ /**
269
+ * Data hook for automated testing
270
+ * @default "content-header-back-link"
271
+ */
272
+ dataHook?: string;
273
+ /**
274
+ * Accessible label for the icon-only back control.
275
+ * @default "Go back"
276
+ */
277
+ ariaLabel?: string;
278
+ /**
279
+ * Destination URL. Set, the control renders a real link
280
+ * (`Link variant="icon"`); omitted, it renders an identically styled
281
+ * `<button>` for SPA router navigation via `onClick` — there is no
282
+ * `href="#"` fallback.
283
+ */
284
+ href?: string;
285
+ } & (GlobalLayoutBackLinkAnchorProps | GlobalLayoutBackLinkButtonProps);
286
+
287
+ /**
288
+ * Icon-only back control for the page header. Place it as a direct child of
211
289
  * `GlobalLayoutContentHeader` — the header positions it before the title.
212
- * Pass `href` for URL navigation or `onClick` for SPA router navigation.
290
+ * Pass `href` for URL navigation (renders a `Link variant="icon"` anchor);
291
+ * omit it and pass `onClick` for SPA router navigation (renders an
292
+ * identically styled icon `<button>`). Both modes are keyboard-focusable and
293
+ * carry the "Go back" accessible name by default.
213
294
  */
214
295
  const GlobalLayoutBackLink = React.forwardRef<
215
- HTMLAnchorElement,
296
+ HTMLAnchorElement | HTMLButtonElement,
216
297
  GlobalLayoutBackLinkProps
217
- >(({ dataHook, ariaLabel, href, onClick, ...props }, ref) => {
218
- // An anchor without href is not keyboard-focusable, so when only a click
219
- // handler is given the link falls back to href="#" and cancels the hash
220
- // navigation before delegating to the handler.
221
- const handleClick: React.MouseEventHandler<HTMLAnchorElement> = (event) => {
222
- if (href === undefined) {
223
- event.preventDefault();
224
- }
225
- onClick?.(event);
226
- };
298
+ >((props, ref) => {
299
+ if (props.href === undefined) {
300
+ // `buttonProps` still carries `href: undefined` — Button doesn't declare
301
+ // it, and React drops undefined-valued attributes, so nothing renders.
302
+ const { dataHook, ariaLabel, ...buttonProps } = props;
303
+ return (
304
+ <Button
305
+ ref={ref as React.Ref<HTMLButtonElement>}
306
+ // Button's ghost variant is the treatment Link variant="icon" derives
307
+ // from, and a single icon child triggers Button's icon-only footprint
308
+ // (size-9 p-0) — so both modes render identically. `||` rather than
309
+ // `??`: an icon-only control must never end up with an empty
310
+ // accessible name, so an empty string also falls back.
311
+ ariaLabel={ariaLabel || "Go back"}
312
+ data-slot="content-header-back-link"
313
+ dataHook={dataHook ?? "content-header-back-link"}
314
+ variant="ghost"
315
+ {...buttonProps}
316
+ >
317
+ <ArrowLeft aria-hidden="true" />
318
+ </Button>
319
+ );
320
+ }
227
321
 
322
+ const { dataHook, ariaLabel, ...anchorProps } = props;
228
323
  return (
229
324
  <Link
230
- ref={ref}
231
- // `||` rather than `??`: an icon-only link must never end up with an
232
- // empty accessible name, so an empty string also falls back.
325
+ ref={ref as React.Ref<HTMLAnchorElement>}
233
326
  aria-label={ariaLabel || "Go back"}
234
327
  data-slot="content-header-back-link"
235
328
  dataHook={dataHook ?? "content-header-back-link"}
236
- href={href ?? "#"}
237
329
  variant="icon"
238
- onClick={handleClick}
239
- {...props}
330
+ {...anchorProps}
240
331
  >
241
332
  <ArrowLeft aria-hidden="true" />
242
333
  </Link>
@@ -361,9 +452,9 @@ interface GlobalLayoutContentHeaderProps extends React.ComponentProps<"header">
361
452
  * <TypographyHeading level={1} variant="page" dataHook="page-title">
362
453
  * All Locations
363
454
  * </TypographyHeading>
364
- * <GlobalLayoutContentActions dataHook="header-actions">
455
+ * <GlobalLayoutActions dataHook="header-actions">
365
456
  * <Button dataHook="add-location">Add Location</Button>
366
- * </GlobalLayoutContentActions>
457
+ * </GlobalLayoutActions>
367
458
  * <GlobalLayoutSubtitle>Manage your business locations.</GlobalLayoutSubtitle>
368
459
  * </GlobalLayoutContentHeader>
369
460
  */
@@ -403,7 +494,7 @@ const GlobalLayoutContentHeader = React.forwardRef<
403
494
  subtitles.push(child);
404
495
  } else if (
405
496
  React.isValidElement(child) &&
406
- child.type === GlobalLayoutContentActions
497
+ child.type === GlobalLayoutActions
407
498
  ) {
408
499
  actions.push(child);
409
500
  } else {
@@ -470,7 +561,7 @@ const GlobalLayoutContentHeader = React.forwardRef<
470
561
  >
471
562
  {breadcrumbs}
472
563
  {actions.length > 0 ? (
473
- // With a slotted GlobalLayoutContentActions the header follows
564
+ // With a slotted GlobalLayoutActions the header follows
474
565
  // the Figma Page Header structure: a text block (title +
475
566
  // description) with the actions beside it — and below it on
476
567
  // mobile, so the action lands under the description.
@@ -510,11 +601,11 @@ const GlobalLayoutContentHeader = React.forwardRef<
510
601
  GlobalLayoutContentHeader.displayName = "GlobalLayoutContentHeader";
511
602
 
512
603
  // True while rendering inside GlobalLayoutContentHeader's actions slot —
513
- // GlobalLayoutContentActions switches from its standalone desktop-row
604
+ // GlobalLayoutActions switches from its standalone desktop-row
514
605
  // styling to an inline title-row group.
515
606
  const GlobalLayoutHeaderSlotContext = React.createContext(false);
516
607
 
517
- interface GlobalLayoutContentActionsProps extends React.ComponentProps<"div"> {
608
+ interface GlobalLayoutActionsProps extends React.ComponentProps<"div"> {
518
609
  /**
519
610
  * Data hook for automated testing (required)
520
611
  */
@@ -529,9 +620,15 @@ interface GlobalLayoutContentActionsProps extends React.ComponentProps<"div"> {
529
620
  trackingLabel?: string;
530
621
  }
531
622
 
532
- const GlobalLayoutContentActions = React.forwardRef<
623
+ /**
624
+ * Action row for the page header. Place it as a direct child of
625
+ * `GlobalLayoutContentHeader` — the header positions it beside the title row
626
+ * (below it on mobile). Standalone it keeps the legacy desktop-only
627
+ * full-width row.
628
+ */
629
+ const GlobalLayoutActions = React.forwardRef<
533
630
  HTMLDivElement,
534
- GlobalLayoutContentActionsProps
631
+ GlobalLayoutActionsProps
535
632
  >(
536
633
  (
537
634
  { className, dataHook, trackingEl, trackingLabel, children, ...props },
@@ -575,9 +672,17 @@ const GlobalLayoutContentActions = React.forwardRef<
575
672
  }
576
673
  );
577
674
 
578
- GlobalLayoutContentActions.displayName = "GlobalLayoutContentActions";
675
+ GlobalLayoutActions.displayName = "GlobalLayoutActions";
579
676
 
580
- interface GlobalLayoutContentBodyProps extends React.ComponentProps<"div"> {
677
+ /**
678
+ * @deprecated Renamed `GlobalLayoutActions` (DS-855) — the `Content`
679
+ * discriminator was unearned: no sibling actions row exists to discriminate
680
+ * against (DS-809: discriminate siblings only). This alias will be removed in
681
+ * the next major.
682
+ */
683
+ const GlobalLayoutContentActions = GlobalLayoutActions;
684
+
685
+ interface GlobalLayoutBodyProps extends React.ComponentProps<"div"> {
581
686
  /**
582
687
  * Data hook for automated testing
583
688
  */
@@ -592,9 +697,14 @@ interface GlobalLayoutContentBodyProps extends React.ComponentProps<"div"> {
592
697
  trackingLabel?: string;
593
698
  }
594
699
 
595
- const GlobalLayoutContentBody = React.forwardRef<
700
+ /**
701
+ * Main content region below the page header. Carries the content max-width
702
+ * set by `GlobalLayoutContent` and the shared region padding, so full-width
703
+ * treatments on sibling regions (header border, sticky header) stay possible.
704
+ */
705
+ const GlobalLayoutBody = React.forwardRef<
596
706
  HTMLDivElement,
597
- GlobalLayoutContentBodyProps
707
+ GlobalLayoutBodyProps
598
708
  >(
599
709
  (
600
710
  { className, dataHook, trackingEl, trackingLabel, children, ...props },
@@ -622,7 +732,15 @@ const GlobalLayoutContentBody = React.forwardRef<
622
732
  }
623
733
  );
624
734
 
625
- GlobalLayoutContentBody.displayName = "GlobalLayoutContentBody";
735
+ GlobalLayoutBody.displayName = "GlobalLayoutBody";
736
+
737
+ /**
738
+ * @deprecated Renamed `GlobalLayoutBody` (DS-855) — the `Content`
739
+ * discriminator was unearned: no sibling body region exists to discriminate
740
+ * against (DS-809: discriminate siblings only). This alias will be removed in
741
+ * the next major.
742
+ */
743
+ const GlobalLayoutContentBody = GlobalLayoutBody;
626
744
 
627
745
  interface GlobalLayoutMobileHeaderProps extends React.ComponentProps<"div"> {
628
746
  /**
@@ -694,24 +812,44 @@ export {
694
812
  GlobalLayout,
695
813
  GlobalLayoutSidebar,
696
814
  GlobalLayoutContent,
697
- GlobalLayoutContentActions,
815
+ GlobalLayoutActions,
698
816
  GlobalLayoutContentHeader,
699
817
  GlobalLayoutBackLink,
700
818
  GlobalLayoutSubtitle,
701
819
  GlobalLayoutImage,
702
- GlobalLayoutContentBody,
820
+ GlobalLayoutBody,
703
821
  GlobalLayoutMobileHeader,
822
+ GlobalLayoutContentActions,
823
+ GlobalLayoutContentBody,
704
824
  };
705
825
 
706
826
  export type {
707
827
  GlobalLayoutProps,
708
828
  GlobalLayoutSidebarProps,
709
829
  GlobalLayoutContentProps,
710
- GlobalLayoutContentActionsProps,
830
+ GlobalLayoutActionsProps,
711
831
  GlobalLayoutContentHeaderProps,
712
832
  GlobalLayoutBackLinkProps,
713
833
  GlobalLayoutSubtitleProps,
714
834
  GlobalLayoutImageProps,
715
- GlobalLayoutContentBodyProps,
835
+ GlobalLayoutBodyProps,
716
836
  GlobalLayoutMobileHeaderProps,
837
+ GlobalLayoutContentActionsProps,
838
+ GlobalLayoutContentBodyProps,
717
839
  };
840
+
841
+ // Deprecated prop-type aliases (DS-855), declared after the export blocks on
842
+ // purpose: the registry's props extractor scrapes the first braced block that
843
+ // follows a `type <Name>Props` declaration, so a bare alias sitting mid-file
844
+ // would document the *next* interface's props under the deprecated name.
845
+ // Down here nothing follows, and only the canonical names carry props.
846
+
847
+ /**
848
+ * @deprecated Renamed `GlobalLayoutActionsProps` (DS-855).
849
+ */
850
+ type GlobalLayoutContentActionsProps = GlobalLayoutActionsProps;
851
+
852
+ /**
853
+ * @deprecated Renamed `GlobalLayoutBodyProps` (DS-855).
854
+ */
855
+ type GlobalLayoutContentBodyProps = GlobalLayoutBodyProps;
@@ -31,6 +31,14 @@ import { OpticalCenter } from "../lib/optical-center";
31
31
  * padding) for pages outside the app shell — auth, invites. Grid owns nothing
32
32
  * but the position inside whatever box it is given.
33
33
  *
34
+ * The flex chain (DS-1058): `centered` stretches with `flex-1`, and `flex-1`
35
+ * only means something inside a flex column that itself has height. Every box
36
+ * between the page body and the Grid must continue that chain (`flex flex-1
37
+ * flex-col`). A plain `<div>` in between breaks it silently: the Grid shrinks to
38
+ * its content, both spacers collapse to zero, and the message is centred
39
+ * horizontally only — it hugs the top of the body. The fix is the chain, never
40
+ * a top margin on the call site.
41
+ *
34
42
  * The single-message blocks are deliberately NOT wired to this internally:
35
43
  * `EmptyState size="lg"` is a pure visual block, and the page recipe is the
36
44
  * composition `<Grid variant="centered"><EmptyState size="lg" /></Grid>` — so
@@ -64,6 +72,10 @@ interface GridBaseProps extends React.ComponentPropsWithoutRef<"div"> {
64
72
  /**
65
73
  * One message at the page body's optical centre (38/62). Give it a page body
66
74
  * to fill — it stretches with `flex-1` — and one message to hold.
75
+ *
76
+ * Requires an unbroken flex chain: the Grid's parent, and every wrapper up to
77
+ * the page body, must be a `flex flex-1 flex-col` box. Behind a non-flex
78
+ * wrapper it centres horizontally only — fix the wrapper, do not add a margin.
67
79
  */
68
80
  interface GridCenteredProps extends GridBaseProps {
69
81
  variant: "centered";
@@ -81,16 +93,35 @@ export type GridProps = GridCenteredProps;
81
93
  *
82
94
  * @example
83
95
  * ```tsx
84
- * <GlobalLayoutContentBody dataHook="locations-body">
96
+ * <GlobalLayoutBody dataHook="locations-body">
85
97
  * <Grid dataHook="locations-empty-center" variant="centered">
86
98
  * <EmptyState
87
99
  * dataHook="locations-empty"
88
- * illustration={<BusinessLocation aria-hidden />}
100
+ * illustration={<SmallBusiness aria-hidden />}
89
101
  * size="lg"
90
102
  * title={t("locations.empty.title")}
91
103
  * />
92
104
  * </Grid>
93
- * </GlobalLayoutContentBody>
105
+ * </GlobalLayoutBody>
106
+ * ```
107
+ *
108
+ * @example
109
+ * Wrappers between the page body and the Grid must continue the flex chain:
110
+ * ```tsx
111
+ * // Broken — the plain <div> has no height to give, so the Grid collapses to
112
+ * // its content and the message hugs the top (horizontal centring only).
113
+ * <GlobalLayoutBody dataHook="search-body">
114
+ * <div>
115
+ * <Grid dataHook="search-empty-center" variant="centered">…</Grid>
116
+ * </div>
117
+ * </GlobalLayoutBody>
118
+ *
119
+ * // Fixed — the wrapper passes the height down.
120
+ * <GlobalLayoutBody dataHook="search-body">
121
+ * <div className="flex flex-1 flex-col">
122
+ * <Grid dataHook="search-empty-center" variant="centered">…</Grid>
123
+ * </div>
124
+ * </GlobalLayoutBody>
94
125
  * ```
95
126
  */
96
127
  const Grid = React.forwardRef<HTMLDivElement, GridProps>(