@brightlocal/ui-components 2.27.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 (259) hide show
  1. package/README.md +6 -1
  2. package/component-meta.json +480 -126
  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-screen.d.ts → progress-state.d.ts} +30 -18
  26. package/dist/blocks/progress-state.d.ts.map +1 -0
  27. package/dist/blocks/{progress-screen.js → progress-state.js} +100 -71
  28. package/dist/blocks/sidebar.cjs +1 -1
  29. package/dist/blocks/sidebar.d.ts.map +1 -1
  30. package/dist/blocks/sidebar.js +160 -161
  31. package/dist/breadcrumb.cjs +1 -1
  32. package/dist/breadcrumb.js +1 -1
  33. package/dist/button.cjs +1 -1
  34. package/dist/button.js +11 -11
  35. package/dist/calendar.cjs +1 -1
  36. package/dist/calendar.d.ts.map +1 -1
  37. package/dist/calendar.js +37 -38
  38. package/dist/callout.cjs +1 -1
  39. package/dist/callout.d.ts +24 -2
  40. package/dist/callout.d.ts.map +1 -1
  41. package/dist/callout.js +57 -55
  42. package/dist/card.cjs +1 -1
  43. package/dist/card.d.ts +23 -2
  44. package/dist/card.d.ts.map +1 -1
  45. package/dist/card.js +94 -91
  46. package/dist/chart-empty.cjs +1 -0
  47. package/dist/chart-empty.d.ts +59 -0
  48. package/dist/chart-empty.d.ts.map +1 -0
  49. package/dist/chart-empty.js +29 -0
  50. package/dist/chart.cjs +6 -6
  51. package/dist/chart.d.ts +6 -1
  52. package/dist/chart.d.ts.map +1 -1
  53. package/dist/chart.js +183 -183
  54. package/dist/chip.cjs +1 -1
  55. package/dist/chip.d.ts.map +1 -1
  56. package/dist/chip.js +5 -3
  57. package/dist/combobox.cjs +2 -2
  58. package/dist/combobox.d.ts.map +1 -1
  59. package/dist/combobox.js +81 -79
  60. package/dist/command.cjs +1 -1
  61. package/dist/command.d.ts.map +1 -1
  62. package/dist/command.js +74 -77
  63. package/dist/context-menu.cjs +1 -1
  64. package/dist/context-menu.d.ts.map +1 -1
  65. package/dist/context-menu.js +26 -29
  66. package/dist/data-table.cjs +1 -1
  67. package/dist/data-table.d.ts +44 -10
  68. package/dist/data-table.d.ts.map +1 -1
  69. package/dist/data-table.js +13 -11
  70. package/dist/description.cjs +1 -1
  71. package/dist/description.js +5 -5
  72. package/dist/dialog.cjs +1 -1
  73. package/dist/dialog.js +20 -20
  74. package/dist/drawer.cjs +1 -1
  75. package/dist/drawer.d.ts.map +1 -1
  76. package/dist/drawer.js +8 -11
  77. package/dist/dropdown-menu.cjs +1 -1
  78. package/dist/dropdown-menu.d.ts.map +1 -1
  79. package/dist/dropdown-menu.js +17 -20
  80. package/dist/field.cjs +1 -1
  81. package/dist/field.d.ts.map +1 -1
  82. package/dist/field.js +29 -25
  83. package/dist/global-layout.cjs +1 -1
  84. package/dist/global-layout.d.ts +27 -1
  85. package/dist/global-layout.d.ts.map +1 -1
  86. package/dist/global-layout.js +18 -16
  87. package/dist/grid.cjs +1 -0
  88. package/dist/grid.d.ts +56 -0
  89. package/dist/grid.d.ts.map +1 -0
  90. package/dist/grid.js +32 -0
  91. package/dist/header.d.ts +13 -0
  92. package/dist/header.d.ts.map +1 -1
  93. package/dist/hooks/use-delayed-pending.cjs +1 -0
  94. package/dist/hooks/use-delayed-pending.d.ts +34 -0
  95. package/dist/hooks/use-delayed-pending.d.ts.map +1 -0
  96. package/dist/hooks/use-delayed-pending.js +17 -0
  97. package/dist/hover-card.cjs +1 -1
  98. package/dist/hover-card.js +13 -13
  99. package/dist/index.cjs +1 -1
  100. package/dist/index.d.ts +8 -1
  101. package/dist/index.d.ts.map +1 -1
  102. package/dist/index.js +512 -494
  103. package/dist/input-chip.cjs +1 -1
  104. package/dist/input-chip.js +25 -25
  105. package/dist/input-group.cjs +1 -1
  106. package/dist/input-group.js +9 -9
  107. package/dist/input-otp.cjs +1 -1
  108. package/dist/input-otp.js +9 -9
  109. package/dist/input-password.cjs +1 -1
  110. package/dist/input-password.js +51 -51
  111. package/dist/input.cjs +1 -1
  112. package/dist/input.js +9 -9
  113. package/dist/label.cjs +1 -1
  114. package/dist/label.d.ts.map +1 -1
  115. package/dist/label.js +25 -28
  116. package/dist/lib/block-illustration.cjs +1 -0
  117. package/dist/lib/block-illustration.d.ts +28 -0
  118. package/dist/lib/block-illustration.d.ts.map +1 -0
  119. package/dist/lib/block-illustration.js +21 -0
  120. package/dist/lib/empty-canvas.cjs +1 -0
  121. package/dist/lib/empty-canvas.d.ts +27 -0
  122. package/dist/lib/empty-canvas.d.ts.map +1 -0
  123. package/dist/lib/empty-canvas.js +62 -0
  124. package/dist/lib/optical-center.cjs +1 -0
  125. package/dist/lib/optical-center.d.ts +12 -0
  126. package/dist/lib/optical-center.d.ts.map +1 -0
  127. package/dist/lib/optical-center.js +11 -0
  128. package/dist/lib/utils.cjs +1 -1
  129. package/dist/lib/utils.d.ts.map +1 -1
  130. package/dist/lib/utils.js +28 -5
  131. package/dist/list.cjs +1 -1
  132. package/dist/list.d.ts.map +1 -1
  133. package/dist/list.js +62 -58
  134. package/dist/map.cjs +1 -1
  135. package/dist/map.d.ts +60 -2
  136. package/dist/map.d.ts.map +1 -1
  137. package/dist/map.js +187 -164
  138. package/dist/media-empty.cjs +1 -0
  139. package/dist/media-empty.d.ts +72 -0
  140. package/dist/media-empty.d.ts.map +1 -0
  141. package/dist/media-empty.js +45 -0
  142. package/dist/menubar.cjs +1 -1
  143. package/dist/menubar.d.ts.map +1 -1
  144. package/dist/menubar.js +17 -20
  145. package/dist/navigation-menu.cjs +1 -1
  146. package/dist/navigation-menu.js +7 -7
  147. package/dist/pagination.cjs +1 -1
  148. package/dist/pagination.d.ts +127 -1
  149. package/dist/pagination.d.ts.map +1 -1
  150. package/dist/pagination.js +189 -98
  151. package/dist/progress.cjs +1 -1
  152. package/dist/progress.d.ts +2 -26
  153. package/dist/progress.d.ts.map +1 -1
  154. package/dist/progress.js +79 -118
  155. package/dist/select.cjs +2 -2
  156. package/dist/select.d.ts.map +1 -1
  157. package/dist/select.js +19 -18
  158. package/dist/separator.cjs +1 -1
  159. package/dist/separator.js +8 -8
  160. package/dist/sheet.cjs +1 -1
  161. package/dist/sheet.js +2 -2
  162. package/dist/skeleton.cjs +1 -1
  163. package/dist/skeleton.d.ts +38 -3
  164. package/dist/skeleton.d.ts.map +1 -1
  165. package/dist/skeleton.js +43 -20
  166. package/dist/sonner.cjs +1 -1
  167. package/dist/sonner.js +26 -26
  168. package/dist/stepper.cjs +1 -1
  169. package/dist/stepper.js +40 -40
  170. package/dist/table.cjs +1 -1
  171. package/dist/table.d.ts.map +1 -1
  172. package/dist/table.js +31 -28
  173. package/dist/tabs.cjs +1 -1
  174. package/dist/tabs.js +1 -1
  175. package/dist/text-reveal-motion.d.ts +10 -0
  176. package/dist/text-reveal-motion.d.ts.map +1 -1
  177. package/dist/textarea.cjs +1 -1
  178. package/dist/textarea.js +11 -11
  179. package/dist/toggle.cjs +1 -1
  180. package/dist/toggle.js +8 -8
  181. package/dist/tooltip.cjs +1 -1
  182. package/dist/tooltip.js +8 -8
  183. package/dist/typography-heading.cjs +1 -0
  184. package/dist/typography-heading.d.ts +116 -0
  185. package/dist/typography-heading.d.ts.map +1 -0
  186. package/dist/typography-heading.js +84 -0
  187. package/dist/typography-text.cjs +1 -0
  188. package/dist/typography-text.d.ts +113 -0
  189. package/dist/typography-text.d.ts.map +1 -0
  190. package/dist/typography-text.js +81 -0
  191. package/dist/typography.d.ts +13 -0
  192. package/dist/typography.d.ts.map +1 -1
  193. package/package.json +35 -7
  194. package/src/blocks/empty-state.tsx +424 -0
  195. package/src/blocks/input-list.tsx +66 -36
  196. package/src/blocks/{progress-screen.tsx → progress-state.tsx} +154 -93
  197. package/src/blocks/sidebar.tsx +25 -26
  198. package/src/components/accordion.tsx +2 -2
  199. package/src/components/alert-dialog.tsx +2 -2
  200. package/src/components/alert.tsx +27 -13
  201. package/src/components/avatar.tsx +1 -1
  202. package/src/components/badge.tsx +8 -4
  203. package/src/components/breadcrumb.tsx +1 -1
  204. package/src/components/button.tsx +3 -3
  205. package/src/components/calendar.tsx +5 -6
  206. package/src/components/callout.tsx +48 -15
  207. package/src/components/card.tsx +52 -17
  208. package/src/components/chart-empty.tsx +116 -0
  209. package/src/components/chart.tsx +43 -17
  210. package/src/components/chip.tsx +5 -3
  211. package/src/components/combobox.tsx +12 -10
  212. package/src/components/command.tsx +9 -10
  213. package/src/components/context-menu.tsx +6 -9
  214. package/src/components/data-table.tsx +72 -17
  215. package/src/components/description.tsx +1 -1
  216. package/src/components/dialog.tsx +2 -2
  217. package/src/components/drawer.tsx +2 -5
  218. package/src/components/dropdown-menu.tsx +8 -11
  219. package/src/components/field.tsx +8 -4
  220. package/src/components/global-layout.tsx +36 -3
  221. package/src/components/grid.tsx +130 -0
  222. package/src/components/header.tsx +13 -0
  223. package/src/components/hover-card.tsx +1 -1
  224. package/src/components/input-chip.tsx +1 -1
  225. package/src/components/input-group.tsx +1 -1
  226. package/src/components/input-otp.tsx +1 -1
  227. package/src/components/input-password.tsx +1 -1
  228. package/src/components/input.tsx +1 -1
  229. package/src/components/label.tsx +10 -13
  230. package/src/components/list.tsx +13 -9
  231. package/src/components/map.tsx +101 -5
  232. package/src/components/media-empty.tsx +156 -0
  233. package/src/components/menubar.tsx +7 -10
  234. package/src/components/navigation-menu.tsx +1 -1
  235. package/src/components/pagination.tsx +279 -1
  236. package/src/components/progress.tsx +35 -113
  237. package/src/components/select.tsx +5 -4
  238. package/src/components/separator.tsx +1 -1
  239. package/src/components/sheet.tsx +2 -2
  240. package/src/components/skeleton.tsx +78 -7
  241. package/src/components/sonner.tsx +2 -2
  242. package/src/components/stepper.tsx +3 -3
  243. package/src/components/table.tsx +6 -3
  244. package/src/components/tabs.tsx +1 -1
  245. package/src/components/text-reveal-motion.tsx +10 -0
  246. package/src/components/textarea.tsx +1 -1
  247. package/src/components/toggle.tsx +1 -1
  248. package/src/components/tooltip.tsx +1 -1
  249. package/src/components/typography-heading.tsx +229 -0
  250. package/src/components/typography-text.tsx +225 -0
  251. package/src/components/typography.tsx +13 -0
  252. package/src/hooks/use-delayed-pending.ts +60 -0
  253. package/src/index.ts +10 -1
  254. package/src/lib/block-illustration.tsx +88 -0
  255. package/src/lib/empty-canvas.tsx +128 -0
  256. package/src/lib/optical-center.tsx +45 -0
  257. package/src/lib/utils.ts +26 -0
  258. package/dist/blocks/progress-screen.cjs +0 -1
  259. package/dist/blocks/progress-screen.d.ts.map +0 -1
@@ -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";
@@ -70,14 +75,18 @@ export * from "./components/toggle";
70
75
  export * from "./components/toggle-group";
71
76
  export * from "./components/tooltip";
72
77
  export * from "./components/typography";
78
+ export * from "./components/typography-heading";
79
+ export * from "./components/typography-text";
73
80
 
74
81
  // Blocks
75
- export * from "./blocks/progress-screen";
82
+ export * from "./blocks/empty-state";
83
+ export * from "./blocks/progress-state";
76
84
  export * from "./blocks/input-list";
77
85
  export * from "./blocks/sidebar";
78
86
 
79
87
  // Hooks
80
88
  export * from "./hooks/use-debounce";
89
+ export * from "./hooks/use-delayed-pending";
81
90
  export * from "./hooks/use-breakpoint";
82
91
  export * from "./hooks/use-mobile";
83
92
  export * from "./hooks/use-overlay-pointer-lock";
@@ -0,0 +1,88 @@
1
+ import * as React from "react";
2
+
3
+ /* -------------------------------------------------------------------------------------------------
4
+ * BlockIllustration (internal)
5
+ *
6
+ * The illustration slot shared by the blocks that draw one — ProgressState,
7
+ * and EmptyState at page scope. Both had the same problem and the same fix, so
8
+ * it lives once.
9
+ *
10
+ * The block owns the size, not the caller. Left to the consumer it was a number
11
+ * to get wrong on every call site, and forgetting it was as bad as mistyping
12
+ * it: the illustrations default to 250, so an unsized one arrives nearly twice
13
+ * the intended height and buries the title under it.
14
+ *
15
+ * The size is applied twice on purpose. As the element's own `size` prop,
16
+ * because clamping it only in the stylesheet means the artwork paints at 250
17
+ * and snaps down the moment the CSS lands — one visible jump on every mount.
18
+ * And as the wrapper's inline width/height, which is the whole mechanism for
19
+ * children that cannot take the prop.
20
+ *
21
+ * The box is square but the artwork is NOT stretched into it. The child keeps
22
+ * its own width — capped by the box — and takes its height from that, which is
23
+ * why `h-auto` is set and `w-auto` deliberately is not: an `<img>`'s `width`
24
+ * attribute is only a presentational hint, so a `w-auto` class beats it and
25
+ * collapses the element to nothing until the source has loaded. Most of the
26
+ * library's illustrations are square SVGs with a `size` prop, but a couple are
27
+ * `<img>`s with their own width and height (`GlobeyFixingFault` is 164×137),
28
+ * and forcing `size-full` on one of those squashed it. The child is capped by
29
+ * the box and keeps its own ratio instead, centred in whatever room is left, so
30
+ * the column's rhythm stays predictable whichever kind of artwork arrives.
31
+ * -----------------------------------------------------------------------------------------------*/
32
+
33
+ /**
34
+ * The size the design specifies for a page-scope illustration, shared by every
35
+ * block that draws one — `ProgressState` and `EmptyState` at page scope — so the
36
+ * artwork never resizes as one of those screens becomes the other.
37
+ *
38
+ * The artwork is the title's companion, not the subject of the screen: much
39
+ * larger and it outweighs the 24px heading under it, and the eye lands on the
40
+ * drawing instead of the words that say what to do next.
41
+ */
42
+ const BLOCK_ILLUSTRATION_SIZE = 130;
43
+
44
+ /**
45
+ * Props for the internal BlockIllustration wrapper.
46
+ */
47
+ interface BlockIllustrationProps {
48
+ /** The illustration element, exactly as the consumer passed it. */
49
+ children: React.ReactNode;
50
+ /** Rendered width and height in pixels. */
51
+ size: number;
52
+ /** The owning block's slot name, e.g. `"empty-screen-illustration"`. */
53
+ slot: string;
54
+ }
55
+
56
+ /**
57
+ * Renders a consumer-supplied illustration at the block's own size.
58
+ */
59
+ function BlockIllustration({ children, size, slot }: BlockIllustrationProps) {
60
+ /* Override whatever the caller set — including nothing, which is the
61
+ illustration's own 250. Merging leaves their other props (aria-hidden,
62
+ className) intact.
63
+
64
+ Only a plain function component gets the prop, and that is deliberately
65
+ narrow: those are the 109 SVG illustrations that declare `size`. A
66
+ `forwardRef` illustration (the two `<img>` ones) has an object type and so
67
+ falls through, which is what we want — `size` is not in its API and would
68
+ land on the `<img>` as an invalid attribute. A host element or a fragment
69
+ falls through for the same reason. Those are handled by the box below. */
70
+ const sized =
71
+ React.isValidElement(children) && typeof children.type === "function"
72
+ ? React.cloneElement(children as React.ReactElement<{ size?: number }>, {
73
+ size,
74
+ })
75
+ : children;
76
+
77
+ return (
78
+ <div
79
+ className="flex shrink-0 items-center justify-center [&>*]:h-auto [&>*]:max-h-full [&>*]:max-w-full"
80
+ data-slot={slot}
81
+ style={{ width: size, height: size }}
82
+ >
83
+ {sized}
84
+ </div>
85
+ );
86
+ }
87
+
88
+ export { BlockIllustration, BLOCK_ILLUSTRATION_SIZE };
@@ -0,0 +1,128 @@
1
+ import * as React from "react";
2
+
3
+ import { cn } from "@brightlocal/ui-components/lib/utils";
4
+ import { TypographyText } from "../components/typography-text";
5
+
6
+ /* -------------------------------------------------------------------------------------------------
7
+ * EmptyCanvas (internal)
8
+ *
9
+ * The shared body of the canvas-empty family — `ChartEmpty`, `MapEmpty` and
10
+ * `MediaEmpty`. A muted surface filling the box the consumer reserved, one bare
11
+ * glyph, one quiet line. No title, no CTA, and no circle chip, because a circle
12
+ * on a flat surface reads as a button.
13
+ *
14
+ * It is deliberately NOT `EmptyState` with most of its parts switched off. A
15
+ * canvas shares only the muted vocabulary with the standard block, not its
16
+ * anatomy — and `EmptyState` is a block that composes typography and actions,
17
+ * while these three are primitives. Borrowing the block here would point a
18
+ * primitive at a block and invert the layering.
19
+ *
20
+ * Internal, so it lives in `lib/` rather than `components/`: the package's
21
+ * `"./*"` export maps every file in `components/` to a public entry point, and
22
+ * this is not one.
23
+ * -----------------------------------------------------------------------------------------------*/
24
+
25
+ /**
26
+ * The glyph is one size, everywhere: 32.
27
+ *
28
+ * It does not scale with the box, and there is no size step either. A canvas
29
+ * empty is one treatment, so it reads the same on a metric card's plot, a map
30
+ * well and a photo slot — and every box these land in is a real content box,
31
+ * where 32 is right. A step existed briefly for a 1200px mockup-filler frame
32
+ * that no longer exists; three variants of one treatment were noise.
33
+ */
34
+ const CANVAS_ICON_SIZE = 32;
35
+
36
+ /**
37
+ * Props for the internal EmptyCanvas body.
38
+ */
39
+ interface EmptyCanvasProps extends Omit<
40
+ React.ComponentPropsWithoutRef<"div">,
41
+ "children" | "title"
42
+ > {
43
+ /** Required data-hook; the parts derive `-icon` and `-message` from it. */
44
+ dataHook: string;
45
+ /**
46
+ * The decorative glyph. This component owns its size — whatever the element
47
+ * carries is overridden — so no call site has a number to get wrong.
48
+ */
49
+ icon: React.ReactNode;
50
+ /** The one line under the glyph. */
51
+ message: string;
52
+ /** The calling component's slot name, e.g. `"chart-empty"`. */
53
+ slot: string;
54
+ /** Tracking element identifier for analytics. */
55
+ trackingEl?: string;
56
+ /** Tracking label for analytics context. */
57
+ trackingLabel?: string;
58
+ }
59
+
60
+ /**
61
+ * Renders the muted canvas surface with its glyph and line.
62
+ */
63
+ const EmptyCanvas = React.forwardRef<HTMLDivElement, EmptyCanvasProps>(
64
+ (
65
+ {
66
+ className,
67
+ dataHook,
68
+ icon,
69
+ message,
70
+ slot,
71
+ trackingEl,
72
+ trackingLabel,
73
+ ...props
74
+ },
75
+ ref
76
+ ) => {
77
+ /* Override whatever size the element carries, including none. Only
78
+ component elements get the prop — DS icons (forwardRef) and any icon
79
+ component take `size` — while a host element (`<svg>`, `<img>`) or a
80
+ fragment would receive it as an invalid attribute, so those fall
81
+ through; the span's CSS below sizes a raw svg instead. */
82
+ const sized =
83
+ React.isValidElement(icon) &&
84
+ typeof icon.type !== "string" &&
85
+ icon.type !== React.Fragment
86
+ ? React.cloneElement(icon as React.ReactElement<{ size?: number }>, {
87
+ size: CANVAS_ICON_SIZE,
88
+ })
89
+ : icon;
90
+
91
+ return (
92
+ <div
93
+ ref={ref}
94
+ className={cn(
95
+ "bg-muted flex flex-col items-center justify-center gap-2 text-center",
96
+ className
97
+ )}
98
+ data-hook={dataHook}
99
+ data-slot={slot}
100
+ data-tracking-el={trackingEl ?? slot}
101
+ data-tracking-label={trackingLabel}
102
+ {...props}
103
+ >
104
+ <span
105
+ aria-hidden="true"
106
+ className="text-muted-foreground flex items-center justify-center [&_svg:not([class*='size-'])]:size-8"
107
+ data-hook={`${dataHook}-icon`}
108
+ data-slot={`${slot}-icon`}
109
+ >
110
+ {sized}
111
+ </span>
112
+ <TypographyText
113
+ align="center"
114
+ color="muted"
115
+ data-slot={`${slot}-message`}
116
+ dataHook={`${dataHook}-message`}
117
+ variant="body-sm"
118
+ >
119
+ {message}
120
+ </TypographyText>
121
+ </div>
122
+ );
123
+ }
124
+ );
125
+
126
+ EmptyCanvas.displayName = "EmptyCanvas";
127
+
128
+ export { EmptyCanvas };