@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
@@ -153,7 +153,7 @@ const TooltipContent = React.forwardRef<
153
153
  <TooltipPrimitive.Content
154
154
  ref={ref}
155
155
  className={cn(
156
- "bg-secondary text-secondary-foreground z-50 w-max max-w-sm rounded-md px-3 py-1.5 text-xs leading-4 font-normal",
156
+ "bg-secondary text-secondary-foreground text-body-xs z-50 w-max max-w-sm rounded-md px-3 py-1.5",
157
157
  FLOATING_CONTENT_ANIMATION,
158
158
  "**:data-[slot=tooltip-arrow]:-translate-y-px",
159
159
  className
@@ -0,0 +1,253 @@
1
+ import * as React from "react";
2
+ import { Slot } from "@radix-ui/react-slot";
3
+ import { cva } from "class-variance-authority";
4
+
5
+ import { cn } from "@brightlocal/ui-components/lib/utils";
6
+
7
+ /**
8
+ * Heading levels — the rendered HTML tag (h1–h6).
9
+ * The level encodes the document outline position only; it is fully
10
+ * independent of the visual style, which is chosen via `variant`.
11
+ */
12
+ type TypographyHeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
13
+
14
+ /**
15
+ * Visual styles from the semantic type scale (DS-714). Weights below are the
16
+ * Figma spec values; each utility renders one step lighter in CSS — the
17
+ * Figma→Web parity offset (DS-305).
18
+ * Every heading is Figma 600 (renders 500) — Figma 700 (the `text-emphasis`
19
+ * utility) is inline emphasis only, never a heading.
20
+ * - `display` — Poppins 600 · 36/40. Brand moments only; never a default.
21
+ * Callout is the one component that uses it.
22
+ * - `page` — Poppins 600 · 24/32. The page title; exactly one per screen.
23
+ * - `section` — Inter 600 · 20/28. Card, dialog and sheet titles.
24
+ * - `subsection` — Inter 600 · 16/24. Sections inside a card, panel headers.
25
+ * - `compact` — Inter 600 · 14/20. Titles inside dense surfaces — alert and
26
+ * toast titles, step titles; the smallest heading. Table column headers are
27
+ * not headings — style the `th` as label-size text at 600 instead.
28
+ */
29
+ type TypographyHeadingVariant =
30
+ | "display"
31
+ | "page"
32
+ | "section"
33
+ | "subsection"
34
+ | "compact";
35
+
36
+ /**
37
+ * Text alignment options.
38
+ */
39
+ type TypographyHeadingAlign = "left" | "center" | "right";
40
+
41
+ /**
42
+ * Color role from the scale.
43
+ * - `default` — regular foreground.
44
+ * - `muted` — de-emphasis by color only; same size and weight.
45
+ * Headings have no destructive role — error/critical text is TypographyText
46
+ * `color="destructive"`, never a heading.
47
+ */
48
+ type TypographyHeadingColor = "default" | "muted";
49
+
50
+ const typographyHeadingVariants = cva("", {
51
+ variants: {
52
+ variant: {
53
+ display: "text-display",
54
+ page: "text-heading-page",
55
+ section: "text-heading-section",
56
+ subsection: "text-heading-subsection",
57
+ compact: "text-heading-compact",
58
+ },
59
+ color: {
60
+ default: "text-foreground",
61
+ muted: "text-muted-foreground",
62
+ },
63
+ align: {
64
+ left: "text-left",
65
+ center: "text-center",
66
+ right: "text-right",
67
+ },
68
+ // Tri-state on purpose: `undefined` (the default) emits no class so the
69
+ // heading inherits its context — proportional everywhere except inside a
70
+ // Table root, which sets `tabular-nums` (DS-926). Explicit `false` must
71
+ // therefore emit `proportional-nums`, or opting out inside a Table would
72
+ // be a silent no-op.
73
+ tabular: {
74
+ true: "tabular-nums",
75
+ false: "proportional-nums",
76
+ },
77
+ // Boolean on purpose (no `false` class): unlike tabular there is no
78
+ // inherited context to undo — either the element clips or it doesn't.
79
+ // `block` is load-bearing: an inline asChild child (e.g. a `span`) cannot
80
+ // clip — overflow does not apply to non-replaced inlines — so the variant
81
+ // forces a block container. A no-op on the default h1–h6 (already block)
82
+ // and on flex/grid items (blockified by the layout).
83
+ truncate: {
84
+ true: "block truncate",
85
+ },
86
+ },
87
+ defaultVariants: {
88
+ color: "default",
89
+ },
90
+ });
91
+
92
+ /**
93
+ * Default visual style for each heading level, used when `variant` is
94
+ * omitted. `display` is never a default — it must be requested explicitly.
95
+ */
96
+ const defaultVariantForLevel: Record<
97
+ TypographyHeadingLevel,
98
+ TypographyHeadingVariant
99
+ > = {
100
+ 1: "page",
101
+ 2: "section",
102
+ 3: "subsection",
103
+ 4: "subsection",
104
+ 5: "subsection",
105
+ 6: "subsection",
106
+ };
107
+
108
+ /**
109
+ * Props for the TypographyHeading component.
110
+ * Extends native heading props with design system tracking attributes.
111
+ */
112
+ interface TypographyHeadingProps extends React.ComponentProps<"h1"> {
113
+ /**
114
+ * Document outline level — renders the corresponding h1–h6 tag.
115
+ * Pick it as if CSS didn't exist (one h1 per page, no skipped levels);
116
+ * the visual size is controlled separately via `variant`.
117
+ */
118
+ level: TypographyHeadingLevel;
119
+ /**
120
+ * Visual style from the semantic type scale, independent of `level`.
121
+ * When omitted, derived from the level: 1 → "page", 2 → "section",
122
+ * 3–6 → "subsection". "display" is always explicit.
123
+ */
124
+ variant?: TypographyHeadingVariant;
125
+ /**
126
+ * Color role: `muted` de-emphasises with color only (text-muted-foreground) —
127
+ * the scale never de-emphasises via lighter weight or smaller size. There is
128
+ * no destructive heading — error/critical text uses TypographyText
129
+ * `color="destructive"`.
130
+ * @default "default"
131
+ */
132
+ color?: TypographyHeadingColor;
133
+ /**
134
+ * Text alignment. When omitted, no alignment class is applied and
135
+ * text keeps the default (left) or inherited alignment.
136
+ * @example "center"
137
+ */
138
+ align?: TypographyHeadingAlign;
139
+ /**
140
+ * Tabular figures (fixed-width numerals) so live values don't jitter —
141
+ * for headings that contain a changing number. Inside Table/DataTable cells
142
+ * figures are already tabular (inherited from the Table root, DS-926);
143
+ * an explicit `false` restores proportional figures there. When omitted,
144
+ * figures follow the surrounding context. Numbers only: never enable
145
+ * it on regular text/prose — it only affects digits, and digits inside
146
+ * prose should stay proportional.
147
+ * No effect on `display`/`page`: Poppins ships no tabular figures, so the
148
+ * request is a harmless no-op there — and a large standalone number is a
149
+ * TypographyText `metric` (plus `tabular` if it must align), not a heading.
150
+ */
151
+ tabular?: boolean;
152
+ /**
153
+ * Clip overflowing text to a single line with an ellipsis — card titles in
154
+ * a fixed-width grid, panel headers beside actions; anywhere a title can
155
+ * outgrow its container. The surrounding layout must still allow the
156
+ * element to shrink: inside a flex row the element (or its wrapper) needs
157
+ * `min-w-0`, and in a grid column `minmax(0, …)` — otherwise the box grows
158
+ * instead of clipping. Forces `display: block` (an inline box cannot
159
+ * clip), so an inline `asChild` child becomes a block while truncating —
160
+ * a no-op on the default h1–h6. Single-line only by design; a multi-line
161
+ * clamp can follow if demand appears.
162
+ * @default false
163
+ */
164
+ truncate?: boolean;
165
+ /**
166
+ * Render as a different element using Radix Slot pattern.
167
+ * When true, merges props onto the child element.
168
+ * @default false
169
+ */
170
+ asChild?: boolean;
171
+ /**
172
+ * Data hook for automated testing (REQUIRED).
173
+ * Used to identify component in tests and E2E automation.
174
+ * @example "page-title", "card-heading"
175
+ */
176
+ dataHook: string;
177
+ /**
178
+ * Tracking element identifier for analytics.
179
+ * @default "typography-heading-{variant}"
180
+ */
181
+ trackingEl?: string;
182
+ /**
183
+ * Tracking label for analytics context.
184
+ */
185
+ trackingLabel?: string;
186
+ }
187
+
188
+ /**
189
+ * Semantic heading with decoupled axes: `level` sets the HTML tag (document
190
+ * outline), `variant` sets the visual style (semantic type scale, DS-714).
191
+ * This makes "an h3 that looks like a section title" a first-class, correct
192
+ * combination — markup encodes meaning, the variant encodes appearance.
193
+ *
194
+ * @example
195
+ * <TypographyHeading level={2} variant="section" dataHook="card-title">
196
+ * Ranking performance
197
+ * </TypographyHeading>
198
+ */
199
+ const TypographyHeading = React.forwardRef<
200
+ HTMLHeadingElement,
201
+ TypographyHeadingProps
202
+ >(
203
+ (
204
+ {
205
+ className,
206
+ level,
207
+ variant,
208
+ color = "default",
209
+ align,
210
+ tabular,
211
+ truncate = false,
212
+ asChild = false,
213
+ dataHook,
214
+ trackingEl,
215
+ trackingLabel,
216
+ ...props
217
+ },
218
+ ref
219
+ ) => {
220
+ const resolvedVariant = variant ?? defaultVariantForLevel[level];
221
+ const Comp = asChild ? Slot : (`h${level}` as const);
222
+ return (
223
+ <Comp
224
+ ref={ref}
225
+ className={cn(
226
+ typographyHeadingVariants({
227
+ variant: resolvedVariant,
228
+ color,
229
+ align,
230
+ tabular,
231
+ truncate,
232
+ }),
233
+ className
234
+ )}
235
+ data-hook={dataHook}
236
+ data-slot="typography-heading"
237
+ data-tracking-el={trackingEl || `typography-heading-${resolvedVariant}`}
238
+ data-tracking-label={trackingLabel}
239
+ {...props}
240
+ />
241
+ );
242
+ }
243
+ );
244
+ TypographyHeading.displayName = "TypographyHeading";
245
+
246
+ export { TypographyHeading };
247
+ export type {
248
+ TypographyHeadingProps,
249
+ TypographyHeadingLevel,
250
+ TypographyHeadingVariant,
251
+ TypographyHeadingAlign,
252
+ TypographyHeadingColor,
253
+ };
@@ -0,0 +1,250 @@
1
+ import * as React from "react";
2
+ import { Slot } from "@radix-ui/react-slot";
3
+ import { cva } from "class-variance-authority";
4
+
5
+ import { cn } from "@brightlocal/ui-components/lib/utils";
6
+
7
+ /**
8
+ * Visual styles from the semantic type scale (DS-714).
9
+ * - `body` — Inter 500 · 16/24. The default; card copy, descriptions, input values.
10
+ * - `body-sm` — Inter 500 · 14/20. Table cells, dense lists, app chrome. Density, never hierarchy.
11
+ * - `body-xs` — Inter 500 · 12/16. Helper text, captions, timestamps; the 12px floor.
12
+ * - `metric` — Inter 600 · 24/28. Large numbers only: KPIs, stat cards,
13
+ * scores — a metric presented as the point of its card. Figures are
14
+ * proportional; add `tabular` where metrics sit in a column or the value
15
+ * updates in place.
16
+ * - `code` — Geist Mono 400 · 16/24. IDs, keys, coordinates a user copies verbatim.
17
+ * Inside a sentence use the `text-code-inline` utility on a `code` element instead
18
+ * (0.9em, inherits the line's height).
19
+ *
20
+ * There are no standalone label variants on purpose: the `text-label` /
21
+ * `text-label-sm` tokens are reserved for control-owning components
22
+ * (Label/Field, tabs, nav, badges, chips) to adopt in follow-up work.
23
+ */
24
+ type TypographyTextVariant = "body" | "body-sm" | "body-xs" | "metric" | "code";
25
+
26
+ /**
27
+ * Text alignment options.
28
+ */
29
+ type TypographyTextAlign = "left" | "center" | "right";
30
+
31
+ /**
32
+ * Color role from the scale.
33
+ * - `default` — regular foreground.
34
+ * - `muted` — de-emphasis by color only; same size and weight.
35
+ * - `destructive` — error/critical text; pair with an icon or wording, never
36
+ * color alone.
37
+ */
38
+ type TypographyTextColor = "default" | "muted" | "destructive";
39
+
40
+ const typographyTextVariants = cva("", {
41
+ variants: {
42
+ variant: {
43
+ body: "text-body",
44
+ "body-sm": "text-body-sm",
45
+ "body-xs": "text-body-xs",
46
+ metric: "text-metric",
47
+ code: "text-code",
48
+ },
49
+ color: {
50
+ default: "text-foreground",
51
+ muted: "text-muted-foreground",
52
+ // destructive-foreground is the legible error-text color in both modes
53
+ // (text-destructive is the surface red used behind destructive fills)
54
+ destructive: "text-destructive-foreground",
55
+ },
56
+ // Tri-state on purpose: `undefined` (the default) emits no class so the
57
+ // text inherits its context — proportional everywhere except inside a
58
+ // Table root, which sets `tabular-nums` (DS-926). Explicit `false` must
59
+ // therefore emit `proportional-nums`, or opting out inside a Table would
60
+ // be a silent no-op.
61
+ tabular: {
62
+ true: "tabular-nums",
63
+ false: "proportional-nums",
64
+ },
65
+ align: {
66
+ left: "text-left",
67
+ center: "text-center",
68
+ right: "text-right",
69
+ },
70
+ // Boolean on purpose (no `false` class): unlike tabular there is no
71
+ // inherited context to undo — either the element clips or it doesn't.
72
+ // `block` is load-bearing: an inline box (the default `span` for metric,
73
+ // `code` for code, or an inline asChild child) cannot clip — overflow
74
+ // does not apply to non-replaced inlines — so the variant forces a block
75
+ // container. A no-op on the body variants (`p` is already block) and on
76
+ // flex/grid items (blockified by the layout).
77
+ truncate: {
78
+ true: "block truncate",
79
+ },
80
+ },
81
+ defaultVariants: {
82
+ variant: "body",
83
+ color: "default",
84
+ },
85
+ });
86
+
87
+ /**
88
+ * Default rendered element per variant: flowing text is a paragraph,
89
+ * metrics are inline, code is a code element.
90
+ */
91
+ const defaultElementForVariant: Record<
92
+ TypographyTextVariant,
93
+ "p" | "span" | "code"
94
+ > = {
95
+ body: "p",
96
+ "body-sm": "p",
97
+ "body-xs": "p",
98
+ metric: "span",
99
+ code: "code",
100
+ };
101
+
102
+ /**
103
+ * Props for the TypographyText component.
104
+ * Extends native element props with design system tracking attributes.
105
+ */
106
+ interface TypographyTextProps extends React.HTMLAttributes<HTMLElement> {
107
+ /**
108
+ * Visual style from the semantic type scale. Pick the name that matches
109
+ * what the text is doing — never pick a size. When in doubt, it's "body".
110
+ * @default "body"
111
+ */
112
+ variant?: TypographyTextVariant;
113
+ /**
114
+ * Color role: `muted` de-emphasises with color only (text-muted-foreground) —
115
+ * the scale never de-emphasises via lighter weight or smaller size;
116
+ * `destructive` is for error/critical text and must be paired with an icon
117
+ * or wording (color is never the only indicator).
118
+ * @default "default"
119
+ */
120
+ color?: TypographyTextColor;
121
+ /**
122
+ * Tabular figures (fixed-width numerals) so columns align and live values
123
+ * don't jitter. Opt in with `true` for numbers outside a Table — timestamps,
124
+ * counters, metric columns. Inside Table/DataTable cells figures are already
125
+ * tabular (inherited from the Table root, DS-926) — no prop needed; pass an
126
+ * explicit `false` there to restore proportional figures for a prose-heavy
127
+ * column. When omitted, figures follow the surrounding context. Numbers
128
+ * only: never enable it on regular text/prose — it only affects digits, and
129
+ * digits inside prose should stay proportional.
130
+ */
131
+ tabular?: boolean;
132
+ /**
133
+ * Text alignment. When omitted, no alignment class is applied and
134
+ * text keeps the default (left) or inherited alignment.
135
+ * @example "center"
136
+ */
137
+ align?: TypographyTextAlign;
138
+ /**
139
+ * Clip overflowing text to a single line with an ellipsis — table cells,
140
+ * list rows, dropdown options; anywhere text can outgrow its container.
141
+ * The surrounding layout must still allow the element to shrink: inside a
142
+ * flex row the element (or its wrapper) needs `min-w-0`, and in a grid
143
+ * column `minmax(0, …)` — otherwise the box grows instead of clipping.
144
+ * Forces `display: block` (an inline box cannot clip), so an inline
145
+ * default element (`metric`'s span, `code`'s code) or an inline `asChild`
146
+ * child becomes a block while truncating.
147
+ * Single-line only by design; a multi-line clamp can follow if demand
148
+ * appears.
149
+ * @default false
150
+ */
151
+ truncate?: boolean;
152
+ /**
153
+ * Render as a different element using Radix Slot pattern.
154
+ * When true, merges props onto the child element.
155
+ * @default false
156
+ */
157
+ asChild?: boolean;
158
+ /**
159
+ * Data hook for automated testing (REQUIRED).
160
+ * Used to identify component in tests and E2E automation.
161
+ * @example "card-description", "kpi-value"
162
+ */
163
+ dataHook: string;
164
+ /**
165
+ * Tracking element identifier for analytics.
166
+ * @default "typography-text-{variant}"
167
+ */
168
+ trackingEl?: string;
169
+ /**
170
+ * Tracking label for analytics context.
171
+ */
172
+ trackingLabel?: string;
173
+ }
174
+
175
+ /**
176
+ * Semantic text styled by the type scale (DS-714). The variant chooses
177
+ * family, size, line-height, weight and tracking together; the rendered
178
+ * element defaults per variant (p / span / code) and can be changed with
179
+ * `asChild` when a different tag carries the right meaning.
180
+ *
181
+ * @example
182
+ * <TypographyText variant="body-sm" color="muted" dataHook="card-hint">
183
+ * Biggest rank changes this week
184
+ * </TypographyText>
185
+ *
186
+ * @example
187
+ * // Inline emphasis is Figma 700 — a few words inside a paragraph, never a
188
+ * // heading or a whole block. The `text-emphasis` utility encodes the weight
189
+ * // (and the Figma→Web parity offset) so nothing inline ever needs a raw
190
+ * // font-* class.
191
+ * <TypographyText dataHook="alert-body">
192
+ * Two locations are <strong className="text-emphasis">missing</strong> a primary category
193
+ * </TypographyText>
194
+ */
195
+ const TypographyText = React.forwardRef<HTMLElement, TypographyTextProps>(
196
+ (
197
+ {
198
+ className,
199
+ variant = "body",
200
+ color = "default",
201
+ tabular,
202
+ align,
203
+ truncate = false,
204
+ asChild = false,
205
+ dataHook,
206
+ trackingEl,
207
+ trackingLabel,
208
+ ...props
209
+ },
210
+ ref
211
+ ) => {
212
+ // p/span/code declare different element refs, which JSX cannot unify
213
+ // across the tag union. Widen the resolved tag to a single
214
+ // HTMLElement-level component signature that every text element satisfies
215
+ // at runtime, so the forwarded HTMLElement ref passes through without
216
+ // mislabelling it as one specific element. (React.ElementType<P> is
217
+ // deliberately avoided here: it distributes over every intrinsic tag and
218
+ // the resulting union exceeds TS's complexity limit — TS2590.)
219
+ const Comp = asChild
220
+ ? Slot
221
+ : (defaultElementForVariant[
222
+ variant
223
+ ] as unknown as React.ForwardRefExoticComponent<
224
+ React.HTMLAttributes<HTMLElement> & React.RefAttributes<HTMLElement>
225
+ >);
226
+ return (
227
+ <Comp
228
+ ref={ref}
229
+ className={cn(
230
+ typographyTextVariants({ variant, color, tabular, align, truncate }),
231
+ className
232
+ )}
233
+ data-hook={dataHook}
234
+ data-slot="typography-text"
235
+ data-tracking-el={trackingEl || `typography-text-${variant}`}
236
+ data-tracking-label={trackingLabel}
237
+ {...props}
238
+ />
239
+ );
240
+ }
241
+ );
242
+ TypographyText.displayName = "TypographyText";
243
+
244
+ export { TypographyText };
245
+ export type {
246
+ TypographyTextProps,
247
+ TypographyTextVariant,
248
+ TypographyTextAlign,
249
+ TypographyTextColor,
250
+ };
@@ -78,6 +78,7 @@ interface TypographyH1Props
78
78
  * Main page heading component (h1).
79
79
  * Used for the primary title on a page. Uses the display font (Poppins) with
80
80
  * responsive sizing — 36px on mobile, 48px from the `md` breakpoint.
81
+ * @deprecated Use `<TypographyHeading level={1} variant="page">` (semantic type scale, DS-714). Note the scale's page title is 24px — the 48px look is `variant="display"`, reserved for brand moments.
81
82
  */
82
83
  const TypographyH1 = React.forwardRef<HTMLHeadingElement, TypographyH1Props>(
83
84
  (
@@ -126,6 +127,7 @@ interface TypographyH2Props
126
127
  /**
127
128
  * Section heading component (h2).
128
129
  * Used for major section titles within a page.
130
+ * @deprecated Use `<TypographyHeading level={2} variant="section">` (semantic type scale, DS-714).
129
131
  */
130
132
  const TypographyH2 = React.forwardRef<HTMLHeadingElement, TypographyH2Props>(
131
133
  (
@@ -174,6 +176,7 @@ interface TypographyH3Props
174
176
  /**
175
177
  * Subsection heading component (h3).
176
178
  * Used for subsections within a major section.
179
+ * @deprecated Use `<TypographyHeading level={3} variant="subsection">` (semantic type scale, DS-714).
177
180
  */
178
181
  const TypographyH3 = React.forwardRef<HTMLHeadingElement, TypographyH3Props>(
179
182
  (
@@ -222,6 +225,7 @@ interface TypographyH4Props
222
225
  /**
223
226
  * Minor heading component (h4).
224
227
  * Used for smaller section headings and card titles.
228
+ * @deprecated Use `<TypographyHeading level={4} variant="subsection">` (semantic type scale, DS-714).
225
229
  */
226
230
  const TypographyH4 = React.forwardRef<HTMLHeadingElement, TypographyH4Props>(
227
231
  (
@@ -267,6 +271,7 @@ interface TypographyPProps
267
271
  /**
268
272
  * Paragraph text component (p).
269
273
  * Used for body text and general content.
274
+ * @deprecated Use `<TypographyText>` (variant "body", semantic type scale, DS-714).
270
275
  */
271
276
  const TypographyP = React.forwardRef<HTMLParagraphElement, TypographyPProps>(
272
277
  (
@@ -314,6 +319,7 @@ interface TypographyBlockquoteProps
314
319
  /**
315
320
  * Blockquote component for quoted content.
316
321
  * Displays with a left border accent for visual distinction.
322
+ * @deprecated Use `<TypographyText asChild>` with a `blockquote` child (semantic type scale, DS-714); the border/quote treatment is consumer layout.
317
323
  */
318
324
  const TypographyBlockquote = React.forwardRef<
319
325
  HTMLQuoteElement,
@@ -368,6 +374,7 @@ interface TypographyListProps
368
374
  /**
369
375
  * Unordered list component (ul).
370
376
  * Used for bullet-point lists with consistent styling.
377
+ * @deprecated Use `<TypographyText asChild>` with a `ul` child (semantic type scale, DS-714); list markers and spacing are consumer layout.
371
378
  */
372
379
  const TypographyList = React.forwardRef<HTMLUListElement, TypographyListProps>(
373
380
  (
@@ -424,6 +431,7 @@ interface TypographyInlineCodeProps
424
431
  /**
425
432
  * Inline code component for code snippets within text.
426
433
  * Displays with monospace font and muted background.
434
+ * @deprecated Use `<code className="text-code-inline">` inside a sentence (0.9em, inherits the line's height — semantic type scale, DS-714).
427
435
  */
428
436
  const TypographyInlineCode = React.forwardRef<
429
437
  HTMLElement,
@@ -473,6 +481,7 @@ interface TypographyCodeProps
473
481
  /**
474
482
  * Code block component for multi-line code snippets.
475
483
  * Displays with dark background, monospace font, and horizontal scroll.
484
+ * @deprecated Use `<TypographyText variant="code">` for copyable identifiers, or a `pre` styled with `text-code` for multi-line snippets (semantic type scale, DS-714).
476
485
  */
477
486
  const TypographyCode = React.forwardRef<HTMLPreElement, TypographyCodeProps>(
478
487
  (
@@ -521,6 +530,7 @@ interface TypographyLeadProps
521
530
  /**
522
531
  * Lead paragraph component for introductory text.
523
532
  * Displays larger, muted text for page introductions and summaries.
533
+ * @deprecated Use `<TypographyText color="muted">` for an intro line (semantic type scale, DS-714).
524
534
  */
525
535
  const TypographyLead = React.forwardRef<
526
536
  HTMLParagraphElement,
@@ -571,6 +581,7 @@ interface TypographyLargeProps
571
581
  /**
572
582
  * Large text component for emphasized content.
573
583
  * Displays larger, semibold text for callouts and highlights.
584
+ * @deprecated Use `<TypographyHeading level={n} variant="subsection">` for a small heading or `<TypographyText>` for emphasised copy (DS-714).
574
585
  */
575
586
  const TypographyLarge = React.forwardRef<HTMLDivElement, TypographyLargeProps>(
576
587
  (
@@ -618,6 +629,7 @@ interface TypographySmallProps
618
629
  /**
619
630
  * Small text component for compact content.
620
631
  * Used for captions, labels, and supplementary information.
632
+ * @deprecated Use `<TypographyText variant="body-sm">` (semantic type scale, DS-714).
621
633
  */
622
634
  const TypographySmall = React.forwardRef<HTMLElement, TypographySmallProps>(
623
635
  (
@@ -664,6 +676,7 @@ interface TypographyMutedProps
664
676
  /**
665
677
  * Muted text component for de-emphasized content.
666
678
  * Displays with reduced visual prominence for secondary information.
679
+ * @deprecated Use `<TypographyText variant="body-sm" color="muted">` (semantic type scale, DS-714).
667
680
  */
668
681
  const TypographyMuted = React.forwardRef<
669
682
  HTMLParagraphElement,
@@ -0,0 +1,60 @@
1
+ import { useEffect, useState } from "react";
2
+
3
+ /**
4
+ * The flash threshold — the delay before a pending state becomes visible.
5
+ * Below it an indicator registers as a flicker rather than as information.
6
+ * One shared constant so every surface flickers (or rather, doesn't) the
7
+ * same way. See the Loading pattern, "Timing".
8
+ *
9
+ * This is the JS mirror of the `--ds-motion-flash-threshold` motion token
10
+ * (the `flash-delay` CSS utility), which drives CSS-only appearance delays
11
+ * such as ComboboxLoading's — when one changes, change the other.
12
+ */
13
+ export const FLASH_THRESHOLD_MS = 150;
14
+
15
+ /**
16
+ * Delays entering a visible pending state by the flash threshold, and leaves
17
+ * it immediately.
18
+ *
19
+ * The two rules are deliberately asymmetric ("delay, don't hold" — see the
20
+ * Loading pattern):
21
+ * - On the way in, the returned flag turns on only after `delay` ms, so a
22
+ * wait that resolves inside the flash zone never shows an indicator at all.
23
+ * - On the way out, the flag turns off the moment `pending` does — there is
24
+ * no timer on the exit path, so a minimum display time is impossible by
25
+ * construction. Never re-add one: flicker is fixed by this entry delay,
26
+ * not by holding skeletons over content the user could already be reading.
27
+ *
28
+ * The flag gates only what is rendered. It must never gate the request or
29
+ * the content swap — data renders the moment it lands.
30
+ *
31
+ * @param pending - The raw pending state (e.g. a query's `isFetching`).
32
+ * @param delay - Delay before the pending state shows, in milliseconds
33
+ * (default `FLASH_THRESHOLD_MS`).
34
+ * @returns Whether the pending indicator should be visible.
35
+ */
36
+ export function useDelayedPending(
37
+ pending: boolean,
38
+ delay: number = FLASH_THRESHOLD_MS
39
+ ): boolean {
40
+ /* Only the entry is stateful. The exit is derived below rather than
41
+ written, so it needs no render of its own and cannot be delayed even by
42
+ accident — `pending` going false is already enough to hide the
43
+ indicator, whatever the timer did. The cleanup's reset is what keeps a
44
+ second wait honest: without it a stale `true` would survive into the
45
+ next wait and show instantly. */
46
+ const [elapsed, setElapsed] = useState(false);
47
+
48
+ useEffect(() => {
49
+ if (!pending) {
50
+ return;
51
+ }
52
+ const timer = setTimeout(() => setElapsed(true), delay);
53
+ return () => {
54
+ clearTimeout(timer);
55
+ setElapsed(false);
56
+ };
57
+ }, [pending, delay]);
58
+
59
+ return pending && elapsed;
60
+ }