@brightlocal/ui-components 3.0.0 → 3.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (235) hide show
  1. package/README.md +7 -1
  2. package/component-meta.json +749 -53
  3. package/deprecations.json +114 -4
  4. package/dist/accordion.cjs +1 -1
  5. package/dist/accordion.d.ts +36 -0
  6. package/dist/accordion.d.ts.map +1 -1
  7. package/dist/accordion.js +74 -61
  8. package/dist/alert-dialog.cjs +1 -1
  9. package/dist/alert-dialog.d.ts +32 -3
  10. package/dist/alert-dialog.d.ts.map +1 -1
  11. package/dist/alert-dialog.js +61 -58
  12. package/dist/alert.cjs +1 -1
  13. package/dist/alert.d.ts.map +1 -1
  14. package/dist/alert.js +58 -57
  15. package/dist/badge.cjs +1 -1
  16. package/dist/badge.d.ts +9 -0
  17. package/dist/badge.d.ts.map +1 -1
  18. package/dist/badge.js +50 -30
  19. package/dist/banner.cjs +1 -0
  20. package/dist/banner.d.ts +81 -0
  21. package/dist/banner.d.ts.map +1 -0
  22. package/dist/banner.js +176 -0
  23. package/dist/blocks/empty-state.cjs +1 -1
  24. package/dist/blocks/empty-state.d.ts +4 -3
  25. package/dist/blocks/empty-state.d.ts.map +1 -1
  26. package/dist/blocks/empty-state.js +50 -57
  27. package/dist/blocks/progress-state.d.ts +2 -2
  28. package/dist/blocks/sidebar.cjs +1 -1
  29. package/dist/blocks/sidebar.d.ts +17 -0
  30. package/dist/blocks/sidebar.d.ts.map +1 -1
  31. package/dist/blocks/sidebar.js +8 -2
  32. package/dist/brand-illustration-motif.d.ts +1 -1
  33. package/dist/button-group.cjs +1 -0
  34. package/dist/button-group.d.ts +36 -0
  35. package/dist/button-group.d.ts.map +1 -0
  36. package/dist/button-group.js +47 -0
  37. package/dist/button.cjs +1 -1
  38. package/dist/button.js +1 -1
  39. package/dist/card.cjs +1 -1
  40. package/dist/card.d.ts +105 -7
  41. package/dist/card.d.ts.map +1 -1
  42. package/dist/card.js +198 -101
  43. package/dist/chart.cjs +3 -3
  44. package/dist/chart.d.ts +270 -24
  45. package/dist/chart.d.ts.map +1 -1
  46. package/dist/chart.js +497 -322
  47. package/dist/checkbox.cjs +1 -1
  48. package/dist/checkbox.d.ts +1 -1
  49. package/dist/checkbox.d.ts.map +1 -1
  50. package/dist/checkbox.js +2 -1
  51. package/dist/chip.cjs +1 -1
  52. package/dist/chip.d.ts +38 -4
  53. package/dist/chip.d.ts.map +1 -1
  54. package/dist/chip.js +95 -81
  55. package/dist/combobox.cjs +1 -1
  56. package/dist/combobox.js +2 -2
  57. package/dist/command.cjs +1 -1
  58. package/dist/command.d.ts +23 -1
  59. package/dist/command.d.ts.map +1 -1
  60. package/dist/command.js +251 -225
  61. package/dist/data-table.cjs +1 -1
  62. package/dist/data-table.d.ts +201 -23
  63. package/dist/data-table.d.ts.map +1 -1
  64. package/dist/data-table.js +712 -568
  65. package/dist/date-picker.cjs +1 -1
  66. package/dist/date-picker.d.ts +13 -5
  67. package/dist/date-picker.d.ts.map +1 -1
  68. package/dist/date-picker.js +54 -53
  69. package/dist/field.cjs +1 -1
  70. package/dist/field.d.ts +8 -1
  71. package/dist/field.d.ts.map +1 -1
  72. package/dist/field.js +79 -52
  73. package/dist/global-layout.cjs +1 -1
  74. package/dist/global-layout.d.ts +105 -13
  75. package/dist/global-layout.d.ts.map +1 -1
  76. package/dist/global-layout.js +146 -129
  77. package/dist/grid.d.ts +26 -3
  78. package/dist/grid.d.ts.map +1 -1
  79. package/dist/hooks/use-breakpoint.cjs +1 -1
  80. package/dist/hooks/use-breakpoint.d.ts +1 -1
  81. package/dist/hooks/use-breakpoint.d.ts.map +1 -1
  82. package/dist/hooks/use-breakpoint.js +1 -0
  83. package/dist/hooks/use-mobile.cjs +1 -0
  84. package/dist/hooks/use-mobile.js +8 -0
  85. package/dist/index.cjs +1 -1
  86. package/dist/index.d.ts +6 -0
  87. package/dist/index.d.ts.map +1 -1
  88. package/dist/index.js +594 -553
  89. package/dist/info-tooltip.cjs +1 -0
  90. package/dist/info-tooltip.d.ts +39 -0
  91. package/dist/info-tooltip.d.ts.map +1 -0
  92. package/dist/info-tooltip.js +41 -0
  93. package/dist/input-chip.cjs +1 -1
  94. package/dist/input-chip.js +1 -1
  95. package/dist/input-group.cjs +1 -1
  96. package/dist/input-group.d.ts +33 -2
  97. package/dist/input-group.d.ts.map +1 -1
  98. package/dist/input-group.js +167 -54
  99. package/dist/input-otp.cjs +1 -1
  100. package/dist/input-otp.js +9 -9
  101. package/dist/input-password.cjs +1 -1
  102. package/dist/input-password.d.ts +45 -15
  103. package/dist/input-password.d.ts.map +1 -1
  104. package/dist/input-password.js +31 -30
  105. package/dist/input.cjs +1 -1
  106. package/dist/input.js +10 -10
  107. package/dist/lib/block-illustration.cjs +1 -1
  108. package/dist/lib/block-illustration.d.ts +4 -1
  109. package/dist/lib/block-illustration.d.ts.map +1 -1
  110. package/dist/lib/block-illustration.js +12 -11
  111. package/dist/lib/empty-chip.cjs +1 -0
  112. package/dist/lib/empty-chip.d.ts +4 -0
  113. package/dist/lib/empty-chip.d.ts.map +1 -0
  114. package/dist/lib/empty-chip.js +13 -0
  115. package/dist/lib/utils.cjs +1 -1
  116. package/dist/lib/utils.d.ts.map +1 -1
  117. package/dist/lib/utils.js +4 -3
  118. package/dist/list.cjs +1 -1
  119. package/dist/list.js +1 -1
  120. package/dist/multi-select-filter.cjs +1 -0
  121. package/dist/multi-select-filter.d.ts +178 -0
  122. package/dist/multi-select-filter.d.ts.map +1 -0
  123. package/dist/multi-select-filter.js +463 -0
  124. package/dist/pagination.cjs +1 -1
  125. package/dist/pagination.d.ts +3 -0
  126. package/dist/pagination.d.ts.map +1 -1
  127. package/dist/pagination.js +57 -57
  128. package/dist/progress.cjs +1 -1
  129. package/dist/progress.d.ts +123 -16
  130. package/dist/progress.d.ts.map +1 -1
  131. package/dist/progress.js +89 -75
  132. package/dist/rating.cjs +1 -1
  133. package/dist/rating.js +18 -18
  134. package/dist/relative-date.cjs +1 -0
  135. package/dist/relative-date.d.ts +65 -0
  136. package/dist/relative-date.d.ts.map +1 -0
  137. package/dist/relative-date.js +128 -0
  138. package/dist/scroll-area.cjs +1 -1
  139. package/dist/scroll-area.d.ts +15 -6
  140. package/dist/scroll-area.d.ts.map +1 -1
  141. package/dist/scroll-area.js +38 -36
  142. package/dist/select.cjs +2 -2
  143. package/dist/select.d.ts +24 -3
  144. package/dist/select.d.ts.map +1 -1
  145. package/dist/select.js +130 -110
  146. package/dist/sheet.cjs +1 -1
  147. package/dist/sheet.d.ts +78 -2
  148. package/dist/sheet.d.ts.map +1 -1
  149. package/dist/sheet.js +192 -85
  150. package/dist/single-select-filter.cjs +1 -0
  151. package/dist/single-select-filter.d.ts +81 -0
  152. package/dist/single-select-filter.d.ts.map +1 -0
  153. package/dist/single-select-filter.js +226 -0
  154. package/dist/sonner.cjs +1 -1
  155. package/dist/sonner.d.ts.map +1 -1
  156. package/dist/sonner.js +22 -22
  157. package/dist/split-layout.cjs +1 -1
  158. package/dist/split-layout.d.ts +1 -1
  159. package/dist/split-layout.js +13 -13
  160. package/dist/table.cjs +1 -1
  161. package/dist/table.d.ts +45 -4
  162. package/dist/table.d.ts.map +1 -1
  163. package/dist/table.js +90 -73
  164. package/dist/tabs.cjs +1 -1
  165. package/dist/tabs.d.ts +12 -1
  166. package/dist/tabs.d.ts.map +1 -1
  167. package/dist/tabs.js +148 -126
  168. package/dist/textarea.cjs +1 -1
  169. package/dist/textarea.js +1 -1
  170. package/dist/tooltip.cjs +1 -1
  171. package/dist/tooltip.d.ts +38 -36
  172. package/dist/tooltip.d.ts.map +1 -1
  173. package/dist/tooltip.js +262 -73
  174. package/dist/typography-heading.cjs +1 -1
  175. package/dist/typography-heading.d.ts +13 -0
  176. package/dist/typography-heading.d.ts.map +1 -1
  177. package/dist/typography-heading.js +32 -21
  178. package/dist/typography-text.cjs +1 -1
  179. package/dist/typography-text.d.ts +15 -2
  180. package/dist/typography-text.d.ts.map +1 -1
  181. package/dist/typography-text.js +35 -24
  182. package/dist/typography.d.ts +1 -1
  183. package/package.json +5 -6
  184. package/src/blocks/empty-state.tsx +17 -24
  185. package/src/blocks/progress-state.tsx +2 -2
  186. package/src/blocks/sidebar.tsx +26 -2
  187. package/src/components/accordion.tsx +82 -27
  188. package/src/components/alert-dialog.tsx +50 -5
  189. package/src/components/alert.tsx +16 -8
  190. package/src/components/badge.tsx +40 -3
  191. package/src/components/banner.tsx +288 -0
  192. package/src/components/brand-illustration-motif.tsx +1 -1
  193. package/src/components/button-group.tsx +112 -0
  194. package/src/components/button.tsx +1 -1
  195. package/src/components/card.tsx +249 -27
  196. package/src/components/chart.tsx +586 -53
  197. package/src/components/checkbox.tsx +1 -1
  198. package/src/components/chip.tsx +83 -10
  199. package/src/components/combobox.tsx +2 -2
  200. package/src/components/command.tsx +56 -4
  201. package/src/components/data-table.tsx +842 -199
  202. package/src/components/date-picker.tsx +18 -7
  203. package/src/components/field.tsx +81 -12
  204. package/src/components/global-layout.tsx +176 -38
  205. package/src/components/grid.tsx +34 -3
  206. package/src/components/info-tooltip.tsx +94 -0
  207. package/src/components/input-chip.tsx +1 -1
  208. package/src/components/input-group.tsx +246 -11
  209. package/src/components/input-otp.tsx +1 -1
  210. package/src/components/input-password.tsx +56 -22
  211. package/src/components/input.tsx +1 -1
  212. package/src/components/list.tsx +1 -1
  213. package/src/components/multi-select-filter.tsx +912 -0
  214. package/src/components/pagination.tsx +10 -3
  215. package/src/components/progress.tsx +190 -31
  216. package/src/components/rating.tsx +1 -1
  217. package/src/components/relative-date.tsx +230 -0
  218. package/src/components/scroll-area.tsx +23 -10
  219. package/src/components/select.tsx +65 -11
  220. package/src/components/sheet.tsx +240 -4
  221. package/src/components/single-select-filter.tsx +443 -0
  222. package/src/components/sonner.tsx +16 -5
  223. package/src/components/split-layout.tsx +2 -2
  224. package/src/components/table.tsx +71 -11
  225. package/src/components/tabs.tsx +93 -46
  226. package/src/components/textarea.tsx +1 -1
  227. package/src/components/tooltip.tsx +440 -68
  228. package/src/components/typography-heading.tsx +24 -0
  229. package/src/components/typography-text.tsx +27 -3
  230. package/src/components/typography.tsx +1 -1
  231. package/src/hooks/use-breakpoint.ts +2 -1
  232. package/src/index.ts +6 -0
  233. package/src/lib/block-illustration.tsx +5 -1
  234. package/src/lib/empty-chip.ts +24 -0
  235. package/src/lib/utils.ts +1 -0
@@ -14,7 +14,7 @@ type CardVariant = "filled" | "transparent" | "border" | "transparent-flush";
14
14
  /**
15
15
  * Card density type
16
16
  */
17
- type CardDensity = "default" | "condensed";
17
+ type CardDensity = "default" | "condensed" | "data";
18
18
 
19
19
  /**
20
20
  * Context to pass variant information to sub-components
@@ -22,10 +22,27 @@ type CardDensity = "default" | "condensed";
22
22
  const CardContext = React.createContext<{
23
23
  flush: boolean;
24
24
  density: CardDensity;
25
- }>({ flush: false, density: "default" });
25
+ variant: CardVariant;
26
+ }>({ flush: false, density: "default", variant: "filled" });
27
+
28
+ /**
29
+ * Opaque surface a sticky header paints so content never shows through it:
30
+ * the card's own fill, or the page background for unfilled variants.
31
+ */
32
+ const stickySurface: Record<CardVariant, string> = {
33
+ filled: "bg-muted",
34
+ border: "bg-card",
35
+ transparent: "bg-background",
36
+ "transparent-flush": "bg-background",
37
+ };
26
38
 
27
39
  function subPadding(flush: boolean, density: CardDensity): string | false {
28
- return !flush && (density === "condensed" ? "px-3" : "px-section-md");
40
+ if (flush) return false;
41
+ if (density === "condensed") return "px-3";
42
+ // Data cards use the fixed 24px content padding, not the responsive
43
+ // section scale — their content (tables, maps) sets its own rhythm.
44
+ if (density === "data") return "px-content";
45
+ return "px-section-md";
29
46
  }
30
47
 
31
48
  const cardVariants = cva(
@@ -35,29 +52,35 @@ const cardVariants = cva(
35
52
  "rounded-xl",
36
53
  "transition-colors duration-fast ease-out",
37
54
  "w-full",
38
- "max-w-[400px]",
39
55
  ],
40
56
  {
41
57
  variants: {
42
58
  variant: {
59
+ // The tinted fill: the muted surface, a step below the white card.
43
60
  filled: [
44
- "bg-card",
61
+ "bg-muted",
45
62
  "text-card-foreground",
46
63
  "border",
47
64
  "border-card-border",
48
65
  ],
49
66
  transparent: ["bg-transparent", "text-foreground"],
50
- border: [
51
- "bg-transparent",
52
- "text-foreground",
53
- "border",
54
- "border-border",
55
- ],
67
+ // The card surface: solid white on the off-white page, neutral-900 in dark.
68
+ border: ["bg-card", "text-foreground", "border", "border-border"],
56
69
  "transparent-flush": ["bg-transparent", "text-foreground"],
57
70
  },
58
71
  density: {
59
- default: ["gap-8", "py-section-md"],
60
- condensed: ["gap-3", "py-3"],
72
+ // Flush content right after a divider header cancels the root gap so
73
+ // it sits on the line, as it does in the data density.
74
+ default: [
75
+ "gap-8",
76
+ "py-section-md",
77
+ "[&>[data-divider]+[data-flush]]:-mt-8",
78
+ ],
79
+ condensed: ["gap-3", "py-3", "[&>[data-divider]+[data-flush]]:-mt-3"],
80
+ // Data cards space via the sub-components, not a root gap: the header
81
+ // owns the top padding and its divider; content/footer pad below it.
82
+ // This lets flush content sit directly against the header divider.
83
+ data: ["pb-6"],
61
84
  },
62
85
  },
63
86
  defaultVariants: {
@@ -77,7 +100,12 @@ type CardProps = React.ComponentProps<"div"> & {
77
100
  */
78
101
  variant?: CardVariant;
79
102
  /**
80
- * Spacing density of the card
103
+ * Spacing density of the card.
104
+ * - `"default"` — responsive section-scale padding for standalone cards.
105
+ * - `"condensed"` — tight 12px scale for dense sidebars and widgets.
106
+ * - `"data"` — the report-page scale (DS-989): fixed 24px horizontal
107
+ * padding and a tighter header, tuned for cards that carry a filter
108
+ * row and a data view (table, map, chart).
81
109
  * @default "default"
82
110
  */
83
111
  density?: CardDensity;
@@ -140,7 +168,7 @@ const Card = React.forwardRef<HTMLDivElement, CardProps>(
140
168
  : undefined;
141
169
 
142
170
  return (
143
- <CardContext.Provider value={{ flush, density }}>
171
+ <CardContext.Provider value={{ flush, density, variant }}>
144
172
  <div
145
173
  ref={ref}
146
174
  className={cn(cardVariants({ variant, density }), className)}
@@ -186,7 +214,7 @@ type CardSubComponentProps = React.ComponentProps<"div"> & {
186
214
  type CardHeaderAlign = "left" | "center" | "right";
187
215
 
188
216
  const cardHeaderVariants = cva(
189
- "@container/card-header grid auto-rows-min grid-rows-[auto_auto] gap-1.5 has-data-[slot=card-action]:grid-cols-[1fr_auto]",
217
+ "@container/card-header grid auto-rows-min grid-rows-[auto_auto] gap-1 has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-metric]:grid-cols-[1fr_auto]",
190
218
  {
191
219
  variants: {
192
220
  align: {
@@ -211,24 +239,65 @@ type CardHeaderProps = CardSubComponentProps & {
211
239
  * @default "left"
212
240
  */
213
241
  align?: CardHeaderAlign;
242
+ /**
243
+ * Closes the header with a full-width divider — the header's own bottom
244
+ * border, so it travels with a sticky header. Works in every density: the
245
+ * header pads its bottom by the density's section spacing so the line
246
+ * never touches the description, and flush content placed right after the
247
+ * header sits directly against the line (DS-989).
248
+ * @default false
249
+ */
250
+ divider?: boolean;
251
+ /**
252
+ * Keeps the header pinned while the card scrolls past (DS-989) — for tall
253
+ * report cards whose table scrolls under the title and filters. Sticks
254
+ * 16px from the top on mobile and 24px from xl up (the section spacing
255
+ * token), stays within the card, and paints the card's surface so rows
256
+ * never show through. Pair with `divider` so the stuck header keeps its edge.
257
+ * @default false
258
+ */
259
+ sticky?: boolean;
214
260
  };
215
261
 
216
262
  /**
217
263
  * Header section of the Card containing title and description.
218
264
  */
219
265
  const CardHeader = React.forwardRef<HTMLDivElement, CardHeaderProps>(
220
- ({ className, align = "left", dataHook, ...props }, ref) => {
221
- const { flush, density } = React.useContext(CardContext);
266
+ (
267
+ {
268
+ className,
269
+ align = "left",
270
+ divider = false,
271
+ sticky = false,
272
+ dataHook,
273
+ ...props
274
+ },
275
+ ref
276
+ ) => {
277
+ const { flush, density, variant } = React.useContext(CardContext);
222
278
  return (
223
279
  <div
224
280
  ref={ref}
225
281
  className={cn(
226
282
  cardHeaderVariants({ align }),
227
283
  subPadding(flush, density),
284
+ // Data cards: the header owns the card's top padding (DS-989).
285
+ density === "data" && "pt-4 pb-4",
286
+ // Other densities have no header padding of their own; with a
287
+ // divider the line gets the density's section spacing above it.
288
+ divider && density === "default" && "pb-8",
289
+ divider && density === "condensed" && "pb-3",
290
+ divider && "border-border border-b",
291
+ sticky && [
292
+ "sticky top-(--ds-section-padding-y-sm) z-10 rounded-t-xl",
293
+ stickySurface[variant],
294
+ ],
228
295
  className
229
296
  )}
297
+ data-divider={divider ? "" : undefined}
230
298
  data-hook={dataHook}
231
299
  data-slot="card-header"
300
+ data-sticky={sticky ? "" : undefined}
232
301
  {...props}
233
302
  />
234
303
  );
@@ -264,7 +333,8 @@ const cardTitleVariants = cva("", {
264
333
  */
265
334
  type CardTitleProps = CardSubComponentProps & {
266
335
  /**
267
- * Title text size.
336
+ * Title text size. Report cards (`density="data"`) use `"small"` —
337
+ * pass it explicitly per the report-card recipe.
268
338
  * @default "default"
269
339
  */
270
340
  size?: CardTitleSize;
@@ -316,14 +386,47 @@ const CardTitle = React.forwardRef<HTMLElement, CardTitleProps>(
316
386
  );
317
387
  CardTitle.displayName = "CardTitle";
318
388
 
389
+ /**
390
+ * Text alignment for the CardDescription.
391
+ */
392
+ type CardDescriptionAlign = "left" | "center" | "right";
393
+
394
+ // No defaultVariants on purpose: when `align` is omitted the description
395
+ // keeps inheriting alignment from its parent (e.g. `CardHeader align`),
396
+ // so existing cards render exactly as before.
397
+ const cardDescriptionVariants = cva("text-body-sm text-muted-foreground", {
398
+ variants: {
399
+ align: {
400
+ left: "text-left",
401
+ center: "text-center",
402
+ right: "text-right",
403
+ },
404
+ },
405
+ });
406
+
407
+ /**
408
+ * Props for the CardDescription component.
409
+ */
410
+ type CardDescriptionProps = CardSubComponentProps & {
411
+ /**
412
+ * Text alignment of the description itself. When omitted, the description
413
+ * inherits alignment from its parent — e.g. `CardHeader align`, or the
414
+ * centring a browser applies inside a `button`. Set it to pin the
415
+ * description's alignment regardless of context (matches `CardHeader`
416
+ * and Typography alignment values).
417
+ * @example <CardDescription align="left">…</CardDescription>
418
+ */
419
+ align?: CardDescriptionAlign;
420
+ };
421
+
319
422
  /**
320
423
  * Description text within the Card header.
321
424
  */
322
- const CardDescription = React.forwardRef<HTMLDivElement, CardSubComponentProps>(
323
- ({ className, dataHook, ...props }, ref) => (
425
+ const CardDescription = React.forwardRef<HTMLDivElement, CardDescriptionProps>(
426
+ ({ className, align, dataHook, ...props }, ref) => (
324
427
  <div
325
428
  ref={ref}
326
- className={cn("text-body-sm text-muted-foreground", className)}
429
+ className={cn(cardDescriptionVariants({ align }), className)}
327
430
  data-hook={dataHook}
328
431
  data-slot="card-description"
329
432
  {...props}
@@ -340,7 +443,9 @@ const CardAction = React.forwardRef<HTMLDivElement, CardSubComponentProps>(
340
443
  <div
341
444
  ref={ref}
342
445
  className={cn(
343
- "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
446
+ // Vertically centered against the title block, per the header spec
447
+ // (DS-989) — Figma's Title Row centers its slot on the cross axis.
448
+ "col-start-2 row-span-2 row-start-1 self-center justify-self-end",
344
449
  className
345
450
  )}
346
451
  data-hook={dataHook}
@@ -360,7 +465,11 @@ const CardMedia = React.forwardRef<HTMLDivElement, CardSubComponentProps>(
360
465
  return (
361
466
  <div
362
467
  ref={ref}
363
- className={cn(subPadding(flush, density), className)}
468
+ className={cn(
469
+ subPadding(flush, density),
470
+ density === "data" && "pt-6",
471
+ className
472
+ )}
364
473
  data-hook={dataHook}
365
474
  data-slot="card-media"
366
475
  {...props}
@@ -374,16 +483,38 @@ const CardMedia = React.forwardRef<HTMLDivElement, CardSubComponentProps>(
374
483
  );
375
484
  CardMedia.displayName = "CardMedia";
376
485
 
486
+ /**
487
+ * Props for the CardContent component.
488
+ */
489
+ type CardContentProps = CardSubComponentProps & {
490
+ /**
491
+ * Runs the content to the card edge (drops the horizontal padding) while
492
+ * the card keeps its surface and border. Use for tables, maps and charts
493
+ * inside a `filled` or `border` card — unlike `variant="transparent-flush"`,
494
+ * only this section goes edge-to-edge; the header and footer keep their
495
+ * padding, and other content sections can stay padded.
496
+ * @default false
497
+ */
498
+ flush?: boolean;
499
+ };
500
+
377
501
  /**
378
502
  * Main content area of the Card.
379
503
  */
380
- const CardContent = React.forwardRef<HTMLDivElement, CardSubComponentProps>(
381
- ({ className, dataHook, ...props }, ref) => {
504
+ const CardContent = React.forwardRef<HTMLDivElement, CardContentProps>(
505
+ ({ className, flush: flushProp = false, dataHook, ...props }, ref) => {
382
506
  const { flush, density } = React.useContext(CardContext);
383
507
  return (
384
508
  <div
385
509
  ref={ref}
386
- className={cn(subPadding(flush, density), className)}
510
+ className={cn(
511
+ flushProp ? false : subPadding(flush, density),
512
+ // Data cards space below the header divider per section; flush
513
+ // content instead sits directly against the divider.
514
+ density === "data" && !flushProp && "pt-6",
515
+ className
516
+ )}
517
+ data-flush={flushProp ? "" : undefined}
387
518
  data-hook={dataHook}
388
519
  data-slot="card-content"
389
520
  {...props}
@@ -393,6 +524,90 @@ const CardContent = React.forwardRef<HTMLDivElement, CardSubComponentProps>(
393
524
  );
394
525
  CardContent.displayName = "CardContent";
395
526
 
527
+ /**
528
+ * Toolbar row within the Card header (DS-989) — search, dimension filters
529
+ * and time/report-run pickers below the title and description (the Card
530
+ * counterpart of DataTableToolbar). Spans the full header width (under any
531
+ * CardAction/CardMetric), lays controls out left-to-right with an 8px gap,
532
+ * caps a search input (Input, InputGroup or DataTableSearch) at 360px so it
533
+ * doesn't dominate a sparse row, and lets select/combobox triggers hug their
534
+ * value. All of that styling reaches direct children only: wrap a control in
535
+ * any element to opt it out. Must be a direct child of CardHeader.
536
+ *
537
+ * Which toolbar: everything that narrows what the card shows, a table's
538
+ * `DataTableSearch` included, goes here in the header. `DataTableToolbar`
539
+ * holds the controls that page through the table (`DataTablePagination`)
540
+ * beside the table, and a table that stands without a card header. A report
541
+ * card uses both.
542
+ *
543
+ * Intentionally no `role="toolbar"`: the ARIA toolbar pattern requires a
544
+ * roving tabindex with arrow-key navigation, which is wrong for a row of
545
+ * inputs and selects. Don't add it.
546
+ */
547
+ const CardToolbar = React.forwardRef<HTMLDivElement, CardSubComponentProps>(
548
+ ({ className, dataHook, ...props }, ref) => (
549
+ <div
550
+ ref={ref}
551
+ className={cn(
552
+ // mt-2 + the header's gap-1 = the 12px title-block → filters gap.
553
+ // justify-self-stretch keeps the full width under align="center".
554
+ "col-span-full mt-2 flex flex-wrap items-center gap-2 justify-self-stretch",
555
+ "[&>[data-slot=data-table-search]]:max-w-90 [&>[data-slot=data-table-search]]:min-w-0 [&>[data-slot=input-group]]:max-w-90 [&>[data-slot=input-group]]:min-w-0 [&>[data-slot=input]]:max-w-90 [&>[data-slot=input]]:min-w-0",
556
+ // Select/combobox triggers are w-full for form layouts; in a filter
557
+ // row they hug their value instead.
558
+ "[&>[data-slot=combobox-trigger]]:w-fit [&>[data-slot=select-trigger]]:w-fit",
559
+ className
560
+ )}
561
+ data-hook={dataHook}
562
+ data-slot="card-toolbar"
563
+ {...props}
564
+ />
565
+ )
566
+ );
567
+ CardToolbar.displayName = "CardToolbar";
568
+
569
+ /**
570
+ * Props for the CardMetric component.
571
+ */
572
+ type CardMetricProps = Omit<CardSubComponentProps, "children"> & {
573
+ /**
574
+ * The metric value shown opposite the title, set in the `text-metric`
575
+ * type role.
576
+ */
577
+ value: React.ReactNode;
578
+ /**
579
+ * Trend indicator rendered after the value — typically a Badge.
580
+ */
581
+ trend?: React.ReactNode;
582
+ };
583
+
584
+ /**
585
+ * A headline metric in the Card header (DS-989) — a value and an optional
586
+ * trend badge sitting opposite the title, for cards whose own filters
587
+ * change the number. Occupies the same header area as CardAction, so use
588
+ * one or the other. Must be a direct child of CardHeader.
589
+ */
590
+ const CardMetric = React.forwardRef<HTMLDivElement, CardMetricProps>(
591
+ ({ className, value, trend, dataHook, ...props }, ref) => (
592
+ <div
593
+ ref={ref}
594
+ className={cn(
595
+ "col-start-2 row-span-2 row-start-1 flex items-baseline gap-2 self-center justify-self-end",
596
+ className
597
+ )}
598
+ data-hook={dataHook}
599
+ data-slot="card-metric"
600
+ {...props}
601
+ >
602
+ <span className="text-metric" data-slot="card-metric-value">
603
+ {value}
604
+ </span>
605
+ {trend}
606
+ </div>
607
+ )
608
+ );
609
+ CardMetric.displayName = "CardMetric";
610
+
396
611
  /**
397
612
  * Footer section of the Card for actions or metadata.
398
613
  */
@@ -405,6 +620,7 @@ const CardFooter = React.forwardRef<HTMLDivElement, CardSubComponentProps>(
405
620
  className={cn(
406
621
  "flex items-center",
407
622
  subPadding(flush, density),
623
+ density === "data" && "pt-6",
408
624
  className
409
625
  )}
410
626
  data-hook={dataHook}
@@ -423,7 +639,9 @@ export {
423
639
  CardTitle,
424
640
  CardAction,
425
641
  CardDescription,
642
+ CardToolbar,
426
643
  CardMedia,
644
+ CardMetric,
427
645
  CardContent,
428
646
  };
429
647
 
@@ -432,9 +650,13 @@ export type {
432
650
  CardSubComponentProps,
433
651
  CardHeaderProps,
434
652
  CardHeaderAlign,
653
+ CardDescriptionProps,
654
+ CardDescriptionAlign,
435
655
  CardTitleProps,
436
656
  CardTitleSize,
437
657
  CardTitleLevel,
658
+ CardContentProps,
659
+ CardMetricProps,
438
660
  CardVariant,
439
661
  CardDensity,
440
662
  };