@brightlocal/ui-components 2.26.0 → 3.0.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 (284) hide show
  1. package/README.md +9 -2
  2. package/component-meta.json +4010 -255
  3. package/deprecations.json +189 -2
  4. package/dist/accordion.cjs +1 -1
  5. package/dist/accordion.js +2 -2
  6. package/dist/alert-dialog.cjs +1 -1
  7. package/dist/alert-dialog.js +18 -18
  8. package/dist/alert.cjs +1 -1
  9. package/dist/alert.d.ts +11 -1
  10. package/dist/alert.d.ts.map +1 -1
  11. package/dist/alert.js +31 -28
  12. package/dist/avatar.cjs +1 -1
  13. package/dist/avatar.js +4 -4
  14. package/dist/badge.cjs +1 -1
  15. package/dist/badge.d.ts.map +1 -1
  16. package/dist/badge.js +15 -11
  17. package/dist/blocks/empty-state.cjs +1 -0
  18. package/dist/blocks/empty-state.d.ts +172 -0
  19. package/dist/blocks/empty-state.d.ts.map +1 -0
  20. package/dist/blocks/empty-state.js +155 -0
  21. package/dist/blocks/input-list.cjs +2 -2
  22. package/dist/blocks/input-list.d.ts.map +1 -1
  23. package/dist/blocks/input-list.js +124 -108
  24. package/dist/blocks/progress-state.cjs +1 -0
  25. package/dist/blocks/progress-state.d.ts +121 -0
  26. package/dist/blocks/progress-state.d.ts.map +1 -0
  27. package/dist/blocks/progress-state.js +368 -0
  28. package/dist/blocks/sidebar.cjs +1 -1
  29. package/dist/blocks/sidebar.d.ts.map +1 -1
  30. package/dist/blocks/sidebar.js +297 -296
  31. package/dist/brand-illustration-motif.d.ts +1 -1
  32. package/dist/breadcrumb.cjs +1 -1
  33. package/dist/breadcrumb.d.ts.map +1 -1
  34. package/dist/breadcrumb.js +44 -40
  35. package/dist/button.cjs +1 -1
  36. package/dist/button.d.ts.map +1 -1
  37. package/dist/button.js +23 -23
  38. package/dist/calendar.cjs +1 -1
  39. package/dist/calendar.d.ts.map +1 -1
  40. package/dist/calendar.js +37 -38
  41. package/dist/callout.cjs +1 -1
  42. package/dist/callout.d.ts +24 -2
  43. package/dist/callout.d.ts.map +1 -1
  44. package/dist/callout.js +57 -55
  45. package/dist/card.cjs +1 -1
  46. package/dist/card.d.ts +23 -2
  47. package/dist/card.d.ts.map +1 -1
  48. package/dist/card.js +94 -91
  49. package/dist/chart-empty.cjs +1 -0
  50. package/dist/chart-empty.d.ts +59 -0
  51. package/dist/chart-empty.d.ts.map +1 -0
  52. package/dist/chart-empty.js +29 -0
  53. package/dist/chart.cjs +6 -6
  54. package/dist/chart.d.ts +6 -1
  55. package/dist/chart.d.ts.map +1 -1
  56. package/dist/chart.js +183 -183
  57. package/dist/chip.cjs +1 -1
  58. package/dist/chip.d.ts +1 -1
  59. package/dist/chip.d.ts.map +1 -1
  60. package/dist/chip.js +47 -44
  61. package/dist/combobox.cjs +3 -3
  62. package/dist/combobox.d.ts +4 -2
  63. package/dist/combobox.d.ts.map +1 -1
  64. package/dist/combobox.js +143 -141
  65. package/dist/command.cjs +1 -1
  66. package/dist/command.d.ts.map +1 -1
  67. package/dist/command.js +74 -77
  68. package/dist/context-menu.cjs +1 -1
  69. package/dist/context-menu.d.ts.map +1 -1
  70. package/dist/context-menu.js +26 -29
  71. package/dist/data-table.cjs +1 -1
  72. package/dist/data-table.d.ts +182 -13
  73. package/dist/data-table.d.ts.map +1 -1
  74. package/dist/data-table.js +462 -314
  75. package/dist/description.cjs +1 -1
  76. package/dist/description.js +5 -5
  77. package/dist/dialog.cjs +1 -1
  78. package/dist/dialog.js +20 -20
  79. package/dist/drawer.cjs +1 -1
  80. package/dist/drawer.d.ts.map +1 -1
  81. package/dist/drawer.js +8 -11
  82. package/dist/dropdown-menu.cjs +1 -1
  83. package/dist/dropdown-menu.d.ts.map +1 -1
  84. package/dist/dropdown-menu.js +17 -20
  85. package/dist/field.cjs +1 -1
  86. package/dist/field.d.ts.map +1 -1
  87. package/dist/field.js +29 -25
  88. package/dist/global-layout.cjs +1 -1
  89. package/dist/global-layout.d.ts +58 -6
  90. package/dist/global-layout.d.ts.map +1 -1
  91. package/dist/global-layout.js +278 -194
  92. package/dist/grid.cjs +1 -0
  93. package/dist/grid.d.ts +56 -0
  94. package/dist/grid.d.ts.map +1 -0
  95. package/dist/grid.js +32 -0
  96. package/dist/header.d.ts +13 -0
  97. package/dist/header.d.ts.map +1 -1
  98. package/dist/hooks/use-delayed-pending.cjs +1 -0
  99. package/dist/hooks/use-delayed-pending.d.ts +34 -0
  100. package/dist/hooks/use-delayed-pending.d.ts.map +1 -0
  101. package/dist/hooks/use-delayed-pending.js +17 -0
  102. package/dist/hover-card.cjs +1 -1
  103. package/dist/hover-card.js +13 -13
  104. package/dist/index.cjs +1 -1
  105. package/dist/index.d.ts +10 -0
  106. package/dist/index.d.ts.map +1 -1
  107. package/dist/index.js +523 -494
  108. package/dist/input-chip.cjs +1 -1
  109. package/dist/input-chip.js +25 -25
  110. package/dist/input-group.cjs +1 -1
  111. package/dist/input-group.js +9 -9
  112. package/dist/input-otp.cjs +1 -1
  113. package/dist/input-otp.js +9 -9
  114. package/dist/input-password.cjs +1 -1
  115. package/dist/input-password.js +51 -51
  116. package/dist/input.cjs +1 -1
  117. package/dist/input.js +9 -9
  118. package/dist/label.cjs +1 -1
  119. package/dist/label.d.ts.map +1 -1
  120. package/dist/label.js +25 -28
  121. package/dist/lib/block-illustration.cjs +1 -0
  122. package/dist/lib/block-illustration.d.ts +28 -0
  123. package/dist/lib/block-illustration.d.ts.map +1 -0
  124. package/dist/lib/block-illustration.js +21 -0
  125. package/dist/lib/empty-canvas.cjs +1 -0
  126. package/dist/lib/empty-canvas.d.ts +27 -0
  127. package/dist/lib/empty-canvas.d.ts.map +1 -0
  128. package/dist/lib/empty-canvas.js +62 -0
  129. package/dist/lib/motion.cjs +1 -1
  130. package/dist/lib/motion.js +10 -8
  131. package/dist/lib/optical-center.cjs +1 -0
  132. package/dist/lib/optical-center.d.ts +12 -0
  133. package/dist/lib/optical-center.d.ts.map +1 -0
  134. package/dist/lib/optical-center.js +11 -0
  135. package/dist/lib/utils.cjs +1 -1
  136. package/dist/lib/utils.d.ts.map +1 -1
  137. package/dist/lib/utils.js +28 -5
  138. package/dist/link.cjs +1 -1
  139. package/dist/link.d.ts +8 -6
  140. package/dist/link.d.ts.map +1 -1
  141. package/dist/link.js +52 -20
  142. package/dist/list.cjs +1 -1
  143. package/dist/list.d.ts.map +1 -1
  144. package/dist/list.js +87 -81
  145. package/dist/map.cjs +1 -1
  146. package/dist/map.d.ts +60 -2
  147. package/dist/map.d.ts.map +1 -1
  148. package/dist/map.js +187 -164
  149. package/dist/media-empty.cjs +1 -0
  150. package/dist/media-empty.d.ts +72 -0
  151. package/dist/media-empty.d.ts.map +1 -0
  152. package/dist/media-empty.js +45 -0
  153. package/dist/menubar.cjs +1 -1
  154. package/dist/menubar.d.ts.map +1 -1
  155. package/dist/menubar.js +17 -20
  156. package/dist/navigation-menu.cjs +1 -1
  157. package/dist/navigation-menu.js +7 -7
  158. package/dist/pagination.cjs +1 -1
  159. package/dist/pagination.d.ts +127 -1
  160. package/dist/pagination.d.ts.map +1 -1
  161. package/dist/pagination.js +189 -98
  162. package/dist/progress.cjs +1 -1
  163. package/dist/progress.d.ts +37 -3
  164. package/dist/progress.d.ts.map +1 -1
  165. package/dist/progress.js +102 -64
  166. package/dist/route-progress.cjs +1 -0
  167. package/dist/route-progress.d.ts +103 -0
  168. package/dist/route-progress.d.ts.map +1 -0
  169. package/dist/route-progress.js +106 -0
  170. package/dist/select.cjs +2 -2
  171. package/dist/select.d.ts.map +1 -1
  172. package/dist/select.js +19 -18
  173. package/dist/separator.cjs +1 -1
  174. package/dist/separator.js +8 -8
  175. package/dist/sheet.cjs +1 -1
  176. package/dist/sheet.d.ts +35 -2
  177. package/dist/sheet.d.ts.map +1 -1
  178. package/dist/sheet.js +103 -66
  179. package/dist/skeleton.cjs +1 -1
  180. package/dist/skeleton.d.ts +38 -3
  181. package/dist/skeleton.d.ts.map +1 -1
  182. package/dist/skeleton.js +43 -20
  183. package/dist/sonner.cjs +1 -1
  184. package/dist/sonner.d.ts.map +1 -1
  185. package/dist/sonner.js +32 -36
  186. package/dist/spinner.cjs +1 -0
  187. package/dist/spinner.d.ts +57 -0
  188. package/dist/spinner.d.ts.map +1 -0
  189. package/dist/spinner.js +35 -0
  190. package/dist/stepper.cjs +1 -1
  191. package/dist/stepper.d.ts.map +1 -1
  192. package/dist/stepper.js +23 -22
  193. package/dist/table.cjs +1 -1
  194. package/dist/table.d.ts +1 -1
  195. package/dist/table.d.ts.map +1 -1
  196. package/dist/table.js +36 -29
  197. package/dist/tabs.cjs +1 -1
  198. package/dist/tabs.js +1 -1
  199. package/dist/text-reveal-motion.d.ts +10 -0
  200. package/dist/text-reveal-motion.d.ts.map +1 -1
  201. package/dist/textarea.cjs +1 -1
  202. package/dist/textarea.js +11 -11
  203. package/dist/toggle.cjs +1 -1
  204. package/dist/toggle.js +8 -8
  205. package/dist/tooltip.cjs +1 -1
  206. package/dist/tooltip.js +8 -8
  207. package/dist/typography-heading.cjs +1 -0
  208. package/dist/typography-heading.d.ts +116 -0
  209. package/dist/typography-heading.d.ts.map +1 -0
  210. package/dist/typography-heading.js +84 -0
  211. package/dist/typography-text.cjs +1 -0
  212. package/dist/typography-text.d.ts +113 -0
  213. package/dist/typography-text.d.ts.map +1 -0
  214. package/dist/typography-text.js +81 -0
  215. package/dist/typography.d.ts +13 -0
  216. package/dist/typography.d.ts.map +1 -1
  217. package/package.json +42 -2
  218. package/src/blocks/empty-state.tsx +424 -0
  219. package/src/blocks/input-list.tsx +66 -36
  220. package/src/blocks/progress-state.tsx +542 -0
  221. package/src/blocks/sidebar.tsx +46 -40
  222. package/src/components/accordion.tsx +2 -2
  223. package/src/components/alert-dialog.tsx +2 -2
  224. package/src/components/alert.tsx +27 -13
  225. package/src/components/avatar.tsx +1 -1
  226. package/src/components/badge.tsx +8 -4
  227. package/src/components/breadcrumb.tsx +9 -4
  228. package/src/components/button.tsx +5 -8
  229. package/src/components/calendar.tsx +5 -6
  230. package/src/components/callout.tsx +48 -15
  231. package/src/components/card.tsx +52 -17
  232. package/src/components/chart-empty.tsx +116 -0
  233. package/src/components/chart.tsx +43 -17
  234. package/src/components/chip.tsx +9 -6
  235. package/src/components/combobox.tsx +21 -12
  236. package/src/components/command.tsx +9 -10
  237. package/src/components/context-menu.tsx +6 -9
  238. package/src/components/data-table.tsx +405 -31
  239. package/src/components/description.tsx +1 -1
  240. package/src/components/dialog.tsx +2 -2
  241. package/src/components/drawer.tsx +2 -5
  242. package/src/components/dropdown-menu.tsx +8 -11
  243. package/src/components/field.tsx +8 -4
  244. package/src/components/global-layout.tsx +264 -65
  245. package/src/components/grid.tsx +130 -0
  246. package/src/components/header.tsx +13 -0
  247. package/src/components/hover-card.tsx +1 -1
  248. package/src/components/input-chip.tsx +1 -1
  249. package/src/components/input-group.tsx +1 -1
  250. package/src/components/input-otp.tsx +1 -1
  251. package/src/components/input-password.tsx +1 -1
  252. package/src/components/input.tsx +1 -1
  253. package/src/components/label.tsx +10 -13
  254. package/src/components/link.tsx +39 -5
  255. package/src/components/list.tsx +18 -14
  256. package/src/components/map.tsx +101 -5
  257. package/src/components/media-empty.tsx +156 -0
  258. package/src/components/menubar.tsx +7 -10
  259. package/src/components/navigation-menu.tsx +1 -1
  260. package/src/components/pagination.tsx +279 -1
  261. package/src/components/progress.tsx +120 -11
  262. package/src/components/route-progress.tsx +354 -0
  263. package/src/components/select.tsx +5 -4
  264. package/src/components/separator.tsx +1 -1
  265. package/src/components/sheet.tsx +89 -7
  266. package/src/components/skeleton.tsx +78 -7
  267. package/src/components/sonner.tsx +5 -14
  268. package/src/components/spinner.tsx +94 -0
  269. package/src/components/stepper.tsx +6 -7
  270. package/src/components/table.tsx +11 -4
  271. package/src/components/tabs.tsx +1 -1
  272. package/src/components/text-reveal-motion.tsx +10 -0
  273. package/src/components/textarea.tsx +1 -1
  274. package/src/components/toggle.tsx +1 -1
  275. package/src/components/tooltip.tsx +1 -1
  276. package/src/components/typography-heading.tsx +229 -0
  277. package/src/components/typography-text.tsx +225 -0
  278. package/src/components/typography.tsx +13 -0
  279. package/src/hooks/use-delayed-pending.ts +60 -0
  280. package/src/index.ts +12 -0
  281. package/src/lib/block-illustration.tsx +88 -0
  282. package/src/lib/empty-canvas.tsx +128 -0
  283. package/src/lib/optical-center.tsx +45 -0
  284. package/src/lib/utils.ts +26 -0
@@ -0,0 +1,229 @@
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
+ },
78
+ defaultVariants: {
79
+ color: "default",
80
+ },
81
+ });
82
+
83
+ /**
84
+ * Default visual style for each heading level, used when `variant` is
85
+ * omitted. `display` is never a default — it must be requested explicitly.
86
+ */
87
+ const defaultVariantForLevel: Record<
88
+ TypographyHeadingLevel,
89
+ TypographyHeadingVariant
90
+ > = {
91
+ 1: "page",
92
+ 2: "section",
93
+ 3: "subsection",
94
+ 4: "subsection",
95
+ 5: "subsection",
96
+ 6: "subsection",
97
+ };
98
+
99
+ /**
100
+ * Props for the TypographyHeading component.
101
+ * Extends native heading props with design system tracking attributes.
102
+ */
103
+ interface TypographyHeadingProps extends React.ComponentProps<"h1"> {
104
+ /**
105
+ * Document outline level — renders the corresponding h1–h6 tag.
106
+ * Pick it as if CSS didn't exist (one h1 per page, no skipped levels);
107
+ * the visual size is controlled separately via `variant`.
108
+ */
109
+ level: TypographyHeadingLevel;
110
+ /**
111
+ * Visual style from the semantic type scale, independent of `level`.
112
+ * When omitted, derived from the level: 1 → "page", 2 → "section",
113
+ * 3–6 → "subsection". "display" is always explicit.
114
+ */
115
+ variant?: TypographyHeadingVariant;
116
+ /**
117
+ * Color role: `muted` de-emphasises with color only (text-muted-foreground) —
118
+ * the scale never de-emphasises via lighter weight or smaller size. There is
119
+ * no destructive heading — error/critical text uses TypographyText
120
+ * `color="destructive"`.
121
+ * @default "default"
122
+ */
123
+ color?: TypographyHeadingColor;
124
+ /**
125
+ * Text alignment. When omitted, no alignment class is applied and
126
+ * text keeps the default (left) or inherited alignment.
127
+ * @example "center"
128
+ */
129
+ align?: TypographyHeadingAlign;
130
+ /**
131
+ * Tabular figures (fixed-width numerals) so live values don't jitter —
132
+ * for headings that contain a changing number. Inside Table/DataTable cells
133
+ * figures are already tabular (inherited from the Table root, DS-926);
134
+ * an explicit `false` restores proportional figures there. When omitted,
135
+ * figures follow the surrounding context. Numbers only: never enable
136
+ * it on regular text/prose — it only affects digits, and digits inside
137
+ * prose should stay proportional.
138
+ * No effect on `display`/`page`: Poppins ships no tabular figures, so the
139
+ * request is a harmless no-op there — and a large standalone number is a
140
+ * TypographyText `metric` (plus `tabular` if it must align), not a heading.
141
+ */
142
+ tabular?: boolean;
143
+ /**
144
+ * Render as a different element using Radix Slot pattern.
145
+ * When true, merges props onto the child element.
146
+ * @default false
147
+ */
148
+ asChild?: boolean;
149
+ /**
150
+ * Data hook for automated testing (REQUIRED).
151
+ * Used to identify component in tests and E2E automation.
152
+ * @example "page-title", "card-heading"
153
+ */
154
+ dataHook: string;
155
+ /**
156
+ * Tracking element identifier for analytics.
157
+ * @default "typography-heading-{variant}"
158
+ */
159
+ trackingEl?: string;
160
+ /**
161
+ * Tracking label for analytics context.
162
+ */
163
+ trackingLabel?: string;
164
+ }
165
+
166
+ /**
167
+ * Semantic heading with decoupled axes: `level` sets the HTML tag (document
168
+ * outline), `variant` sets the visual style (semantic type scale, DS-714).
169
+ * This makes "an h3 that looks like a section title" a first-class, correct
170
+ * combination — markup encodes meaning, the variant encodes appearance.
171
+ *
172
+ * @example
173
+ * <TypographyHeading level={2} variant="section" dataHook="card-title">
174
+ * Ranking performance
175
+ * </TypographyHeading>
176
+ */
177
+ const TypographyHeading = React.forwardRef<
178
+ HTMLHeadingElement,
179
+ TypographyHeadingProps
180
+ >(
181
+ (
182
+ {
183
+ className,
184
+ level,
185
+ variant,
186
+ color = "default",
187
+ align,
188
+ tabular,
189
+ asChild = false,
190
+ dataHook,
191
+ trackingEl,
192
+ trackingLabel,
193
+ ...props
194
+ },
195
+ ref
196
+ ) => {
197
+ const resolvedVariant = variant ?? defaultVariantForLevel[level];
198
+ const Comp = asChild ? Slot : (`h${level}` as const);
199
+ return (
200
+ <Comp
201
+ ref={ref}
202
+ className={cn(
203
+ typographyHeadingVariants({
204
+ variant: resolvedVariant,
205
+ color,
206
+ align,
207
+ tabular,
208
+ }),
209
+ className
210
+ )}
211
+ data-hook={dataHook}
212
+ data-slot="typography-heading"
213
+ data-tracking-el={trackingEl || `typography-heading-${resolvedVariant}`}
214
+ data-tracking-label={trackingLabel}
215
+ {...props}
216
+ />
217
+ );
218
+ }
219
+ );
220
+ TypographyHeading.displayName = "TypographyHeading";
221
+
222
+ export { TypographyHeading };
223
+ export type {
224
+ TypographyHeadingProps,
225
+ TypographyHeadingLevel,
226
+ TypographyHeadingVariant,
227
+ TypographyHeadingAlign,
228
+ TypographyHeadingColor,
229
+ };
@@ -0,0 +1,225 @@
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
+ },
71
+ defaultVariants: {
72
+ variant: "body",
73
+ color: "default",
74
+ },
75
+ });
76
+
77
+ /**
78
+ * Default rendered element per variant: flowing text is a paragraph,
79
+ * metrics are inline, code is a code element.
80
+ */
81
+ const defaultElementForVariant: Record<
82
+ TypographyTextVariant,
83
+ "p" | "span" | "code"
84
+ > = {
85
+ body: "p",
86
+ "body-sm": "p",
87
+ "body-xs": "p",
88
+ metric: "span",
89
+ code: "code",
90
+ };
91
+
92
+ /**
93
+ * Props for the TypographyText component.
94
+ * Extends native element props with design system tracking attributes.
95
+ */
96
+ interface TypographyTextProps extends React.HTMLAttributes<HTMLElement> {
97
+ /**
98
+ * Visual style from the semantic type scale. Pick the name that matches
99
+ * what the text is doing — never pick a size. When in doubt, it's "body".
100
+ * @default "body"
101
+ */
102
+ variant?: TypographyTextVariant;
103
+ /**
104
+ * Color role: `muted` de-emphasises with color only (text-muted-foreground) —
105
+ * the scale never de-emphasises via lighter weight or smaller size;
106
+ * `destructive` is for error/critical text and must be paired with an icon
107
+ * or wording (color is never the only indicator).
108
+ * @default "default"
109
+ */
110
+ color?: TypographyTextColor;
111
+ /**
112
+ * Tabular figures (fixed-width numerals) so columns align and live values
113
+ * don't jitter. Opt in with `true` for numbers outside a Table — timestamps,
114
+ * counters, metric columns. Inside Table/DataTable cells figures are already
115
+ * tabular (inherited from the Table root, DS-926) — no prop needed; pass an
116
+ * explicit `false` there to restore proportional figures for a prose-heavy
117
+ * column. When omitted, figures follow the surrounding context. Numbers
118
+ * only: never enable it on regular text/prose — it only affects digits, and
119
+ * digits inside prose should stay proportional.
120
+ */
121
+ tabular?: boolean;
122
+ /**
123
+ * Text alignment. When omitted, no alignment class is applied and
124
+ * text keeps the default (left) or inherited alignment.
125
+ * @example "center"
126
+ */
127
+ align?: TypographyTextAlign;
128
+ /**
129
+ * Render as a different element using Radix Slot pattern.
130
+ * When true, merges props onto the child element.
131
+ * @default false
132
+ */
133
+ asChild?: boolean;
134
+ /**
135
+ * Data hook for automated testing (REQUIRED).
136
+ * Used to identify component in tests and E2E automation.
137
+ * @example "card-description", "kpi-value"
138
+ */
139
+ dataHook: string;
140
+ /**
141
+ * Tracking element identifier for analytics.
142
+ * @default "typography-text-{variant}"
143
+ */
144
+ trackingEl?: string;
145
+ /**
146
+ * Tracking label for analytics context.
147
+ */
148
+ trackingLabel?: string;
149
+ }
150
+
151
+ /**
152
+ * Semantic text styled by the type scale (DS-714). The variant chooses
153
+ * family, size, line-height, weight and tracking together; the rendered
154
+ * element defaults per variant (p / span / code) and can be changed with
155
+ * `asChild` when a different tag carries the right meaning.
156
+ *
157
+ * @example
158
+ * <TypographyText variant="body-sm" color="muted" dataHook="card-hint">
159
+ * Biggest rank changes this week
160
+ * </TypographyText>
161
+ *
162
+ * @example
163
+ * // Inline emphasis is Figma 700 — a few words inside a paragraph, never a
164
+ * // heading or a whole block. The `text-emphasis` utility encodes the weight
165
+ * // (and the Figma→Web parity offset) so nothing inline ever needs a raw
166
+ * // font-* class.
167
+ * <TypographyText dataHook="alert-body">
168
+ * Two locations are <strong className="text-emphasis">missing</strong> a primary category
169
+ * </TypographyText>
170
+ */
171
+ const TypographyText = React.forwardRef<HTMLElement, TypographyTextProps>(
172
+ (
173
+ {
174
+ className,
175
+ variant = "body",
176
+ color = "default",
177
+ tabular,
178
+ align,
179
+ asChild = false,
180
+ dataHook,
181
+ trackingEl,
182
+ trackingLabel,
183
+ ...props
184
+ },
185
+ ref
186
+ ) => {
187
+ // p/span/code declare different element refs, which JSX cannot unify
188
+ // across the tag union. Widen the resolved tag to a single
189
+ // HTMLElement-level component signature that every text element satisfies
190
+ // at runtime, so the forwarded HTMLElement ref passes through without
191
+ // mislabelling it as one specific element. (React.ElementType<P> is
192
+ // deliberately avoided here: it distributes over every intrinsic tag and
193
+ // the resulting union exceeds TS's complexity limit — TS2590.)
194
+ const Comp = asChild
195
+ ? Slot
196
+ : (defaultElementForVariant[
197
+ variant
198
+ ] as unknown as React.ForwardRefExoticComponent<
199
+ React.HTMLAttributes<HTMLElement> & React.RefAttributes<HTMLElement>
200
+ >);
201
+ return (
202
+ <Comp
203
+ ref={ref}
204
+ className={cn(
205
+ typographyTextVariants({ variant, color, tabular, align }),
206
+ className
207
+ )}
208
+ data-hook={dataHook}
209
+ data-slot="typography-text"
210
+ data-tracking-el={trackingEl || `typography-text-${variant}`}
211
+ data-tracking-label={trackingLabel}
212
+ {...props}
213
+ />
214
+ );
215
+ }
216
+ );
217
+ TypographyText.displayName = "TypographyText";
218
+
219
+ export { TypographyText };
220
+ export type {
221
+ TypographyTextProps,
222
+ TypographyTextVariant,
223
+ TypographyTextAlign,
224
+ TypographyTextColor,
225
+ };
@@ -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
+ }
package/src/index.ts CHANGED
@@ -13,6 +13,9 @@ export * from "./components/callout";
13
13
  export * from "./components/card";
14
14
  export * from "./components/carousel";
15
15
  export * from "./components/chart";
16
+ // Also re-exported through ./components/chart, which is the documented path;
17
+ // both resolve to the same binding, so the duplicate star export is not ambiguous.
18
+ export * from "./components/chart-empty";
16
19
  export * from "./components/centred-layout";
17
20
  export * from "./components/checkbox";
18
21
  export * from "./components/chip";
@@ -28,6 +31,7 @@ export * from "./components/drawer";
28
31
  export * from "./components/dropdown-menu";
29
32
  export * from "./components/field";
30
33
  export * from "./components/global-layout";
34
+ export * from "./components/grid";
31
35
  export * from "./components/header";
32
36
  export * from "./components/height-transition";
33
37
  export * from "./components/hover-card";
@@ -41,6 +45,7 @@ export * from "./components/list";
41
45
  export * from "./components/loading";
42
46
  export * from "./components/logo";
43
47
  export * from "./components/map";
48
+ export * from "./components/media-empty";
44
49
  export * from "./components/menubar";
45
50
  export * from "./components/navigation-menu";
46
51
  export * from "./components/pagination";
@@ -50,6 +55,7 @@ export * from "./components/progress";
50
55
  export * from "./components/radio-group";
51
56
  export * from "./components/rating";
52
57
  export * from "./components/resizable";
58
+ export * from "./components/route-progress";
53
59
  export * from "./components/scroll-area";
54
60
  export * from "./components/select";
55
61
  export * from "./components/separator";
@@ -57,6 +63,7 @@ export * from "./components/sheet";
57
63
  export * from "./components/skeleton";
58
64
  export * from "./components/slider";
59
65
  export * from "./components/sonner";
66
+ export * from "./components/spinner";
60
67
  export * from "./components/split-layout";
61
68
  export * from "./components/stepper";
62
69
  export * from "./components/switch";
@@ -68,13 +75,18 @@ export * from "./components/toggle";
68
75
  export * from "./components/toggle-group";
69
76
  export * from "./components/tooltip";
70
77
  export * from "./components/typography";
78
+ export * from "./components/typography-heading";
79
+ export * from "./components/typography-text";
71
80
 
72
81
  // Blocks
82
+ export * from "./blocks/empty-state";
83
+ export * from "./blocks/progress-state";
73
84
  export * from "./blocks/input-list";
74
85
  export * from "./blocks/sidebar";
75
86
 
76
87
  // Hooks
77
88
  export * from "./hooks/use-debounce";
89
+ export * from "./hooks/use-delayed-pending";
78
90
  export * from "./hooks/use-breakpoint";
79
91
  export * from "./hooks/use-mobile";
80
92
  export * from "./hooks/use-overlay-pointer-lock";