@brightlocal/ui-components 2.27.0 → 3.1.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 (289) hide show
  1. package/README.md +7 -1
  2. package/component-meta.json +568 -143
  3. package/deprecations.json +298 -1
  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.js +18 -18
  10. package/dist/alert.cjs +1 -1
  11. package/dist/alert.d.ts +11 -1
  12. package/dist/alert.d.ts.map +1 -1
  13. package/dist/alert.js +31 -28
  14. package/dist/avatar.cjs +1 -1
  15. package/dist/avatar.js +4 -4
  16. package/dist/badge.cjs +1 -1
  17. package/dist/badge.d.ts.map +1 -1
  18. package/dist/badge.js +15 -11
  19. package/dist/blocks/empty-state.cjs +1 -0
  20. package/dist/blocks/empty-state.d.ts +172 -0
  21. package/dist/blocks/empty-state.d.ts.map +1 -0
  22. package/dist/blocks/empty-state.js +147 -0
  23. package/dist/blocks/input-list.cjs +2 -2
  24. package/dist/blocks/input-list.d.ts.map +1 -1
  25. package/dist/blocks/input-list.js +124 -108
  26. package/dist/blocks/progress-state.cjs +1 -0
  27. package/dist/blocks/{progress-screen.d.ts → progress-state.d.ts} +30 -18
  28. package/dist/blocks/progress-state.d.ts.map +1 -0
  29. package/dist/blocks/{progress-screen.js → progress-state.js} +100 -71
  30. package/dist/blocks/sidebar.cjs +1 -1
  31. package/dist/blocks/sidebar.d.ts.map +1 -1
  32. package/dist/blocks/sidebar.js +160 -161
  33. package/dist/breadcrumb.cjs +1 -1
  34. package/dist/breadcrumb.js +1 -1
  35. package/dist/button-group.cjs +1 -0
  36. package/dist/button-group.d.ts +36 -0
  37. package/dist/button-group.d.ts.map +1 -0
  38. package/dist/button-group.js +47 -0
  39. package/dist/button.cjs +1 -1
  40. package/dist/button.js +12 -12
  41. package/dist/calendar.cjs +1 -1
  42. package/dist/calendar.d.ts.map +1 -1
  43. package/dist/calendar.js +37 -38
  44. package/dist/callout.cjs +1 -1
  45. package/dist/callout.d.ts +24 -2
  46. package/dist/callout.d.ts.map +1 -1
  47. package/dist/callout.js +57 -55
  48. package/dist/card.cjs +1 -1
  49. package/dist/card.d.ts +42 -3
  50. package/dist/card.d.ts.map +1 -1
  51. package/dist/card.js +102 -91
  52. package/dist/chart-empty.cjs +1 -0
  53. package/dist/chart-empty.d.ts +59 -0
  54. package/dist/chart-empty.d.ts.map +1 -0
  55. package/dist/chart-empty.js +29 -0
  56. package/dist/chart.cjs +6 -6
  57. package/dist/chart.d.ts +46 -13
  58. package/dist/chart.d.ts.map +1 -1
  59. package/dist/chart.js +172 -157
  60. package/dist/chip.cjs +1 -1
  61. package/dist/chip.d.ts +38 -4
  62. package/dist/chip.d.ts.map +1 -1
  63. package/dist/chip.js +100 -84
  64. package/dist/combobox.cjs +2 -2
  65. package/dist/combobox.d.ts.map +1 -1
  66. package/dist/combobox.js +81 -79
  67. package/dist/command.cjs +1 -1
  68. package/dist/command.d.ts +23 -1
  69. package/dist/command.d.ts.map +1 -1
  70. package/dist/command.js +248 -225
  71. package/dist/context-menu.cjs +1 -1
  72. package/dist/context-menu.d.ts.map +1 -1
  73. package/dist/context-menu.js +26 -29
  74. package/dist/data-table.cjs +1 -1
  75. package/dist/data-table.d.ts +75 -10
  76. package/dist/data-table.d.ts.map +1 -1
  77. package/dist/data-table.js +346 -334
  78. package/dist/date-picker.cjs +1 -1
  79. package/dist/date-picker.d.ts +13 -5
  80. package/dist/date-picker.d.ts.map +1 -1
  81. package/dist/date-picker.js +54 -53
  82. package/dist/description.cjs +1 -1
  83. package/dist/description.js +5 -5
  84. package/dist/dialog.cjs +1 -1
  85. package/dist/dialog.js +20 -20
  86. package/dist/drawer.cjs +1 -1
  87. package/dist/drawer.d.ts.map +1 -1
  88. package/dist/drawer.js +8 -11
  89. package/dist/dropdown-menu.cjs +1 -1
  90. package/dist/dropdown-menu.d.ts.map +1 -1
  91. package/dist/dropdown-menu.js +17 -20
  92. package/dist/field.cjs +1 -1
  93. package/dist/field.d.ts +8 -1
  94. package/dist/field.d.ts.map +1 -1
  95. package/dist/field.js +96 -65
  96. package/dist/global-layout.cjs +1 -1
  97. package/dist/global-layout.d.ts +130 -12
  98. package/dist/global-layout.d.ts.map +1 -1
  99. package/dist/global-layout.js +146 -127
  100. package/dist/grid.cjs +1 -0
  101. package/dist/grid.d.ts +56 -0
  102. package/dist/grid.d.ts.map +1 -0
  103. package/dist/grid.js +32 -0
  104. package/dist/header.d.ts +13 -0
  105. package/dist/header.d.ts.map +1 -1
  106. package/dist/hooks/use-delayed-pending.cjs +1 -0
  107. package/dist/hooks/use-delayed-pending.d.ts +34 -0
  108. package/dist/hooks/use-delayed-pending.d.ts.map +1 -0
  109. package/dist/hooks/use-delayed-pending.js +17 -0
  110. package/dist/hooks/use-mobile.cjs +1 -0
  111. package/dist/hooks/use-mobile.js +8 -0
  112. package/dist/hover-card.cjs +1 -1
  113. package/dist/hover-card.js +13 -13
  114. package/dist/index.cjs +1 -1
  115. package/dist/index.d.ts +9 -1
  116. package/dist/index.d.ts.map +1 -1
  117. package/dist/index.js +554 -527
  118. package/dist/input-chip.cjs +1 -1
  119. package/dist/input-chip.js +25 -25
  120. package/dist/input-group.cjs +1 -1
  121. package/dist/input-group.js +9 -9
  122. package/dist/input-otp.cjs +1 -1
  123. package/dist/input-otp.js +9 -9
  124. package/dist/input-password.cjs +1 -1
  125. package/dist/input-password.d.ts +17 -9
  126. package/dist/input-password.d.ts.map +1 -1
  127. package/dist/input-password.js +73 -72
  128. package/dist/input.cjs +1 -1
  129. package/dist/input.js +9 -9
  130. package/dist/label.cjs +1 -1
  131. package/dist/label.d.ts.map +1 -1
  132. package/dist/label.js +25 -28
  133. package/dist/lib/block-illustration.cjs +1 -0
  134. package/dist/lib/block-illustration.d.ts +28 -0
  135. package/dist/lib/block-illustration.d.ts.map +1 -0
  136. package/dist/lib/block-illustration.js +21 -0
  137. package/dist/lib/empty-canvas.cjs +1 -0
  138. package/dist/lib/empty-canvas.d.ts +27 -0
  139. package/dist/lib/empty-canvas.d.ts.map +1 -0
  140. package/dist/lib/empty-canvas.js +62 -0
  141. package/dist/lib/empty-chip.cjs +1 -0
  142. package/dist/lib/empty-chip.d.ts +4 -0
  143. package/dist/lib/empty-chip.d.ts.map +1 -0
  144. package/dist/lib/empty-chip.js +13 -0
  145. package/dist/lib/optical-center.cjs +1 -0
  146. package/dist/lib/optical-center.d.ts +12 -0
  147. package/dist/lib/optical-center.d.ts.map +1 -0
  148. package/dist/lib/optical-center.js +11 -0
  149. package/dist/lib/utils.cjs +1 -1
  150. package/dist/lib/utils.d.ts.map +1 -1
  151. package/dist/lib/utils.js +28 -5
  152. package/dist/list.cjs +1 -1
  153. package/dist/list.d.ts.map +1 -1
  154. package/dist/list.js +62 -58
  155. package/dist/map.cjs +1 -1
  156. package/dist/map.d.ts +60 -2
  157. package/dist/map.d.ts.map +1 -1
  158. package/dist/map.js +187 -164
  159. package/dist/media-empty.cjs +1 -0
  160. package/dist/media-empty.d.ts +72 -0
  161. package/dist/media-empty.d.ts.map +1 -0
  162. package/dist/media-empty.js +45 -0
  163. package/dist/menubar.cjs +1 -1
  164. package/dist/menubar.d.ts.map +1 -1
  165. package/dist/menubar.js +17 -20
  166. package/dist/navigation-menu.cjs +1 -1
  167. package/dist/navigation-menu.js +7 -7
  168. package/dist/pagination.cjs +1 -1
  169. package/dist/pagination.d.ts +130 -1
  170. package/dist/pagination.d.ts.map +1 -1
  171. package/dist/pagination.js +193 -102
  172. package/dist/progress.cjs +1 -1
  173. package/dist/progress.d.ts +2 -26
  174. package/dist/progress.d.ts.map +1 -1
  175. package/dist/progress.js +79 -118
  176. package/dist/scroll-area.cjs +1 -1
  177. package/dist/scroll-area.d.ts +15 -6
  178. package/dist/scroll-area.d.ts.map +1 -1
  179. package/dist/scroll-area.js +38 -36
  180. package/dist/select.cjs +2 -2
  181. package/dist/select.d.ts +13 -2
  182. package/dist/select.d.ts.map +1 -1
  183. package/dist/select.js +92 -87
  184. package/dist/separator.cjs +1 -1
  185. package/dist/separator.js +8 -8
  186. package/dist/sheet.cjs +1 -1
  187. package/dist/sheet.js +2 -2
  188. package/dist/skeleton.cjs +1 -1
  189. package/dist/skeleton.d.ts +38 -3
  190. package/dist/skeleton.d.ts.map +1 -1
  191. package/dist/skeleton.js +43 -20
  192. package/dist/sonner.cjs +1 -1
  193. package/dist/sonner.js +26 -26
  194. package/dist/stepper.cjs +1 -1
  195. package/dist/stepper.js +40 -40
  196. package/dist/table.cjs +1 -1
  197. package/dist/table.d.ts.map +1 -1
  198. package/dist/table.js +31 -28
  199. package/dist/tabs.cjs +1 -1
  200. package/dist/tabs.js +1 -1
  201. package/dist/text-reveal-motion.d.ts +10 -0
  202. package/dist/text-reveal-motion.d.ts.map +1 -1
  203. package/dist/textarea.cjs +1 -1
  204. package/dist/textarea.js +11 -11
  205. package/dist/toggle.cjs +1 -1
  206. package/dist/toggle.js +8 -8
  207. package/dist/tooltip.cjs +1 -1
  208. package/dist/tooltip.js +8 -8
  209. package/dist/typography-heading.cjs +1 -0
  210. package/dist/typography-heading.d.ts +129 -0
  211. package/dist/typography-heading.d.ts.map +1 -0
  212. package/dist/typography-heading.js +95 -0
  213. package/dist/typography-text.cjs +1 -0
  214. package/dist/typography-text.d.ts +127 -0
  215. package/dist/typography-text.d.ts.map +1 -0
  216. package/dist/typography-text.js +92 -0
  217. package/dist/typography.d.ts +13 -0
  218. package/dist/typography.d.ts.map +1 -1
  219. package/package.json +35 -7
  220. package/src/blocks/empty-state.tsx +412 -0
  221. package/src/blocks/input-list.tsx +66 -36
  222. package/src/blocks/{progress-screen.tsx → progress-state.tsx} +154 -93
  223. package/src/blocks/sidebar.tsx +25 -26
  224. package/src/components/accordion.tsx +82 -27
  225. package/src/components/alert-dialog.tsx +2 -2
  226. package/src/components/alert.tsx +27 -13
  227. package/src/components/avatar.tsx +1 -1
  228. package/src/components/badge.tsx +8 -4
  229. package/src/components/breadcrumb.tsx +1 -1
  230. package/src/components/button-group.tsx +112 -0
  231. package/src/components/button.tsx +4 -4
  232. package/src/components/calendar.tsx +5 -6
  233. package/src/components/callout.tsx +48 -15
  234. package/src/components/card.tsx +89 -19
  235. package/src/components/chart-empty.tsx +116 -0
  236. package/src/components/chart.tsx +103 -32
  237. package/src/components/chip.tsx +88 -13
  238. package/src/components/combobox.tsx +12 -10
  239. package/src/components/command.tsx +64 -13
  240. package/src/components/context-menu.tsx +6 -9
  241. package/src/components/data-table.tsx +135 -20
  242. package/src/components/date-picker.tsx +18 -7
  243. package/src/components/description.tsx +1 -1
  244. package/src/components/dialog.tsx +2 -2
  245. package/src/components/drawer.tsx +2 -5
  246. package/src/components/dropdown-menu.tsx +8 -11
  247. package/src/components/field.tsx +89 -16
  248. package/src/components/global-layout.tsx +210 -39
  249. package/src/components/grid.tsx +130 -0
  250. package/src/components/header.tsx +13 -0
  251. package/src/components/hover-card.tsx +1 -1
  252. package/src/components/input-chip.tsx +1 -1
  253. package/src/components/input-group.tsx +1 -1
  254. package/src/components/input-otp.tsx +1 -1
  255. package/src/components/input-password.tsx +24 -12
  256. package/src/components/input.tsx +1 -1
  257. package/src/components/label.tsx +10 -13
  258. package/src/components/list.tsx +13 -9
  259. package/src/components/map.tsx +101 -5
  260. package/src/components/media-empty.tsx +156 -0
  261. package/src/components/menubar.tsx +7 -10
  262. package/src/components/navigation-menu.tsx +1 -1
  263. package/src/components/pagination.tsx +286 -1
  264. package/src/components/progress.tsx +35 -113
  265. package/src/components/scroll-area.tsx +23 -10
  266. package/src/components/select.tsx +35 -10
  267. package/src/components/separator.tsx +1 -1
  268. package/src/components/sheet.tsx +2 -2
  269. package/src/components/skeleton.tsx +78 -7
  270. package/src/components/sonner.tsx +2 -2
  271. package/src/components/stepper.tsx +3 -3
  272. package/src/components/table.tsx +6 -3
  273. package/src/components/tabs.tsx +1 -1
  274. package/src/components/text-reveal-motion.tsx +10 -0
  275. package/src/components/textarea.tsx +1 -1
  276. package/src/components/toggle.tsx +1 -1
  277. package/src/components/tooltip.tsx +1 -1
  278. package/src/components/typography-heading.tsx +253 -0
  279. package/src/components/typography-text.tsx +250 -0
  280. package/src/components/typography.tsx +13 -0
  281. package/src/hooks/use-delayed-pending.ts +60 -0
  282. package/src/index.ts +11 -1
  283. package/src/lib/block-illustration.tsx +88 -0
  284. package/src/lib/empty-canvas.tsx +128 -0
  285. package/src/lib/empty-chip.ts +24 -0
  286. package/src/lib/optical-center.tsx +45 -0
  287. package/src/lib/utils.ts +26 -0
  288. package/dist/blocks/progress-screen.cjs +0 -1
  289. package/dist/blocks/progress-screen.d.ts.map +0 -1
@@ -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";
@@ -49,9 +52,9 @@ function FieldLegend({
49
52
  return (
50
53
  <legend
51
54
  className={cn(
52
- "mb-3 font-medium",
53
- "data-[variant=legend]:text-base",
54
- "data-[variant=label]:text-sm",
55
+ "mb-3",
56
+ "data-[variant=legend]:text-heading-subsection",
57
+ "data-[variant=label]:text-label",
55
58
  srOnly && "sr-only",
56
59
  className
57
60
  )}
@@ -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)
@@ -98,6 +105,9 @@ const fieldVariants = cva(
98
105
  "grid grid-cols-[auto_1fr] items-center gap-x-2",
99
106
  "[&>[data-slot=field-description]]:col-start-2 [&>[data-slot=field-error]]:col-start-2",
100
107
  "has-[>[data-slot=field-content]]:items-start",
108
+ // Top-aligned rows: a 16px control centres on the label's first line
109
+ // (text-label is 20px), never on the content box's top edge.
110
+ "has-[>[data-slot=field-content]]:[&>[role=radio]]:mt-0.5",
101
111
  // sr-only label leaves grid flow — collapse to a single column
102
112
  "has-[>.sr-only[data-slot=field-label]]:grid-cols-[1fr]",
103
113
  "[&:has(>.sr-only[data-slot=field-label])>[data-slot=field-description]]:col-start-1",
@@ -107,6 +117,7 @@ const fieldVariants = cva(
107
117
  "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",
108
118
  "@md/field-group:[&>[data-slot=field-description]]:col-start-2 @md/field-group:[&>[data-slot=field-error]]:col-start-2",
109
119
  "@md/field-group:has-[>[data-slot=field-content]]:items-start",
120
+ "@md/field-group:has-[>[data-slot=field-content]]:[&>[role=radio]]:mt-0.5",
110
121
  // sr-only label leaves grid flow — collapse to a single column
111
122
  "@md/field-group:has-[>.sr-only[data-slot=field-label]]:grid-cols-[1fr]",
112
123
  "@md/field-group:[&:has(>.sr-only[data-slot=field-label])>[data-slot=field-description]]:col-start-1",
@@ -120,6 +131,13 @@ const fieldVariants = cva(
120
131
  "rounded-lg border border-border bg-background p-3",
121
132
  "transition-colors duration-fast ease-out",
122
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",
123
141
  // Focus ring when a child control receives focus
124
142
  "has-[:focus-visible]:shadow-default has-[:focus-visible]:border-ring",
125
143
  // Checked-state for radio/checkbox (not switch)
@@ -306,6 +324,23 @@ interface FieldErrorProps extends Omit<
306
324
  errors?: Array<FieldErrorItem | undefined>;
307
325
  }
308
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
+
309
344
  interface FieldErrorIconProps extends Omit<LucideProps, "ref"> {
310
345
  /**
311
346
  * Custom icon component to render instead of the default AlertCircle.
@@ -356,7 +391,13 @@ function FieldErrorIcon({
356
391
  * FieldError displays validation error messages within a Field.
357
392
  *
358
393
  * Supports both direct children content and an errors array for form library integration.
359
- * 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.
360
401
  * No icon is displayed by default - use FieldErrorIcon for composition.
361
402
  *
362
403
  * @example
@@ -393,13 +434,42 @@ function FieldError({
393
434
  Boolean(e?.message)
394
435
  );
395
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
+
396
466
  // If no children and no valid errors, don't render anything
397
- if (!children && (!errorMessages || errorMessages.length === 0)) {
467
+ if (!hasMessage) {
398
468
  return null;
399
469
  }
400
470
 
401
471
  const baseStyles = cn(
402
- "text-destructive-foreground text-sm font-normal leading-5",
472
+ "text-body-sm text-destructive-foreground",
403
473
  "mt-2",
404
474
  "group-has-[[data-orientation=horizontal]]/field:text-balance",
405
475
  "last:mt-0 nth-last-2:-mt-1 [[data-variant=legend]+&]:-mt-1.5",
@@ -411,21 +481,24 @@ function FieldError({
411
481
 
412
482
  return (
413
483
  <div
484
+ aria-atomic="true"
485
+ aria-live="polite"
414
486
  className={baseStyles}
415
487
  data-hook={dataHook}
416
488
  data-slot="field-error"
417
- role="alert"
489
+ role="status"
418
490
  {...props}
419
491
  >
420
- {isMultiple ? (
421
- <ul className="list-disc space-y-1 pl-4">
422
- {errorMessages.map((error, index) => (
423
- <li key={index}>{error.message}</li>
424
- ))}
425
- </ul>
426
- ) : (
427
- <p className="m-0">{children || errorMessages?.[0]?.message}</p>
428
- )}
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
+ ))}
429
502
  </div>
430
503
  );
431
504
  }
@@ -3,10 +3,11 @@ 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";
9
- import { TypographyMuted } from "./typography";
10
+ import { TypographyText } from "./typography-text";
10
11
 
11
12
  interface GlobalLayoutProps extends React.ComponentProps<"div"> {
12
13
  /**
@@ -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
+
237
+ /**
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
+
209
287
  /**
210
- * Icon-only back link for the page header. Place it as a direct child of
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>
@@ -245,7 +336,12 @@ const GlobalLayoutBackLink = React.forwardRef<
245
336
 
246
337
  GlobalLayoutBackLink.displayName = "GlobalLayoutBackLink";
247
338
 
248
- interface GlobalLayoutSubtitleProps extends React.ComponentProps<"p"> {
339
+ // The deprecated native `color` presentation attribute is omitted: the
340
+ // subtitle's colour is the type scale's muted role, not a free-form value.
341
+ interface GlobalLayoutSubtitleProps extends Omit<
342
+ React.ComponentProps<"p">,
343
+ "color"
344
+ > {
249
345
  /**
250
346
  * Data hook for automated testing
251
347
  * @default "content-header-subtitle"
@@ -263,17 +359,23 @@ interface GlobalLayoutSubtitleProps extends React.ComponentProps<"p"> {
263
359
  * Muted description text for the page header. Place it as a direct child of
264
360
  * `GlobalLayoutContentHeader` — the header positions it below the title row.
265
361
  * For rich descriptions, pass `asChild` with your own flex row as the child.
362
+ *
363
+ * Sits on the semantic type scale's `text-body-sm` (Inter · Figma 500 · 14/20,
364
+ * rendering one CSS weight lighter per the DS-305 offset) with the muted
365
+ * colour role — de-emphasis is colour-only, never a lighter weight.
266
366
  */
267
367
  const GlobalLayoutSubtitle = React.forwardRef<
268
368
  HTMLParagraphElement,
269
369
  GlobalLayoutSubtitleProps
270
370
  >(({ dataHook, asChild, ...props }, ref) => {
271
371
  return (
272
- <TypographyMuted
372
+ <TypographyText
273
373
  ref={ref}
274
374
  asChild={asChild}
375
+ color="muted"
275
376
  data-slot="content-header-subtitle"
276
377
  dataHook={dataHook ?? "content-header-subtitle"}
378
+ variant="body-sm"
277
379
  {...props}
278
380
  />
279
381
  );
@@ -334,6 +436,28 @@ interface GlobalLayoutContentHeaderProps extends React.ComponentProps<"header">
334
436
  trackingLabel?: string;
335
437
  }
336
438
 
439
+ /**
440
+ * Page header for the content area. Slots direct children (back link, image,
441
+ * breadcrumb, subtitle, actions) around the title row per the Figma Page
442
+ * Header design.
443
+ *
444
+ * The consumer-supplied page title must be `TypographyHeading level={1}
445
+ * variant="page"` so it sits on the semantic type scale's
446
+ * `text-heading-page` (DS-714) — never a hand-styled heading. Exactly one
447
+ * page title per screen: a second title is a section (`variant="section"`,
448
+ * `text-heading-section`).
449
+ *
450
+ * @example
451
+ * <GlobalLayoutContentHeader dataHook="page-header">
452
+ * <TypographyHeading level={1} variant="page" dataHook="page-title">
453
+ * All Locations
454
+ * </TypographyHeading>
455
+ * <GlobalLayoutActions dataHook="header-actions">
456
+ * <Button dataHook="add-location">Add Location</Button>
457
+ * </GlobalLayoutActions>
458
+ * <GlobalLayoutSubtitle>Manage your business locations.</GlobalLayoutSubtitle>
459
+ * </GlobalLayoutContentHeader>
460
+ */
337
461
  const GlobalLayoutContentHeader = React.forwardRef<
338
462
  HTMLElement,
339
463
  GlobalLayoutContentHeaderProps
@@ -370,7 +494,7 @@ const GlobalLayoutContentHeader = React.forwardRef<
370
494
  subtitles.push(child);
371
495
  } else if (
372
496
  React.isValidElement(child) &&
373
- child.type === GlobalLayoutContentActions
497
+ child.type === GlobalLayoutActions
374
498
  ) {
375
499
  actions.push(child);
376
500
  } else {
@@ -437,7 +561,7 @@ const GlobalLayoutContentHeader = React.forwardRef<
437
561
  >
438
562
  {breadcrumbs}
439
563
  {actions.length > 0 ? (
440
- // With a slotted GlobalLayoutContentActions the header follows
564
+ // With a slotted GlobalLayoutActions the header follows
441
565
  // the Figma Page Header structure: a text block (title +
442
566
  // description) with the actions beside it — and below it on
443
567
  // mobile, so the action lands under the description.
@@ -477,11 +601,11 @@ const GlobalLayoutContentHeader = React.forwardRef<
477
601
  GlobalLayoutContentHeader.displayName = "GlobalLayoutContentHeader";
478
602
 
479
603
  // True while rendering inside GlobalLayoutContentHeader's actions slot —
480
- // GlobalLayoutContentActions switches from its standalone desktop-row
604
+ // GlobalLayoutActions switches from its standalone desktop-row
481
605
  // styling to an inline title-row group.
482
606
  const GlobalLayoutHeaderSlotContext = React.createContext(false);
483
607
 
484
- interface GlobalLayoutContentActionsProps extends React.ComponentProps<"div"> {
608
+ interface GlobalLayoutActionsProps extends React.ComponentProps<"div"> {
485
609
  /**
486
610
  * Data hook for automated testing (required)
487
611
  */
@@ -496,9 +620,15 @@ interface GlobalLayoutContentActionsProps extends React.ComponentProps<"div"> {
496
620
  trackingLabel?: string;
497
621
  }
498
622
 
499
- 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<
500
630
  HTMLDivElement,
501
- GlobalLayoutContentActionsProps
631
+ GlobalLayoutActionsProps
502
632
  >(
503
633
  (
504
634
  { className, dataHook, trackingEl, trackingLabel, children, ...props },
@@ -542,9 +672,17 @@ const GlobalLayoutContentActions = React.forwardRef<
542
672
  }
543
673
  );
544
674
 
545
- GlobalLayoutContentActions.displayName = "GlobalLayoutContentActions";
675
+ GlobalLayoutActions.displayName = "GlobalLayoutActions";
546
676
 
547
- 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"> {
548
686
  /**
549
687
  * Data hook for automated testing
550
688
  */
@@ -559,9 +697,14 @@ interface GlobalLayoutContentBodyProps extends React.ComponentProps<"div"> {
559
697
  trackingLabel?: string;
560
698
  }
561
699
 
562
- 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<
563
706
  HTMLDivElement,
564
- GlobalLayoutContentBodyProps
707
+ GlobalLayoutBodyProps
565
708
  >(
566
709
  (
567
710
  { className, dataHook, trackingEl, trackingLabel, children, ...props },
@@ -589,7 +732,15 @@ const GlobalLayoutContentBody = React.forwardRef<
589
732
  }
590
733
  );
591
734
 
592
- 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;
593
744
 
594
745
  interface GlobalLayoutMobileHeaderProps extends React.ComponentProps<"div"> {
595
746
  /**
@@ -661,24 +812,44 @@ export {
661
812
  GlobalLayout,
662
813
  GlobalLayoutSidebar,
663
814
  GlobalLayoutContent,
664
- GlobalLayoutContentActions,
815
+ GlobalLayoutActions,
665
816
  GlobalLayoutContentHeader,
666
817
  GlobalLayoutBackLink,
667
818
  GlobalLayoutSubtitle,
668
819
  GlobalLayoutImage,
669
- GlobalLayoutContentBody,
820
+ GlobalLayoutBody,
670
821
  GlobalLayoutMobileHeader,
822
+ GlobalLayoutContentActions,
823
+ GlobalLayoutContentBody,
671
824
  };
672
825
 
673
826
  export type {
674
827
  GlobalLayoutProps,
675
828
  GlobalLayoutSidebarProps,
676
829
  GlobalLayoutContentProps,
677
- GlobalLayoutContentActionsProps,
830
+ GlobalLayoutActionsProps,
678
831
  GlobalLayoutContentHeaderProps,
679
832
  GlobalLayoutBackLinkProps,
680
833
  GlobalLayoutSubtitleProps,
681
834
  GlobalLayoutImageProps,
682
- GlobalLayoutContentBodyProps,
835
+ GlobalLayoutBodyProps,
683
836
  GlobalLayoutMobileHeaderProps,
837
+ GlobalLayoutContentActionsProps,
838
+ GlobalLayoutContentBodyProps,
684
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;