@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
@@ -66,8 +66,10 @@ const ScrollArea = React.forwardRef<
66
66
  >
67
67
  {children}
68
68
  </ScrollAreaPrimitive.Viewport>
69
- <ScrollBar />
70
- {scrollOrientation === "both" && <ScrollBar orientation="horizontal" />}
69
+ <ScrollAreaScrollbar />
70
+ {scrollOrientation === "both" && (
71
+ <ScrollAreaScrollbar orientation="horizontal" />
72
+ )}
71
73
  <ScrollAreaPrimitive.Corner />
72
74
  </ScrollAreaPrimitive.Root>
73
75
  );
@@ -77,9 +79,9 @@ const ScrollArea = React.forwardRef<
77
79
  ScrollArea.displayName = "ScrollArea";
78
80
 
79
81
  /**
80
- * Props for the ScrollBar component.
82
+ * Props for the ScrollAreaScrollbar component.
81
83
  */
82
- interface ScrollBarProps extends React.ComponentProps<
84
+ interface ScrollAreaScrollbarProps extends React.ComponentProps<
83
85
  typeof ScrollAreaPrimitive.ScrollAreaScrollbar
84
86
  > {
85
87
  /**
@@ -102,11 +104,11 @@ interface ScrollBarProps extends React.ComponentProps<
102
104
  }
103
105
 
104
106
  /**
105
- * ScrollBar provides a styled scrollbar for ScrollArea.
107
+ * ScrollAreaScrollbar provides a styled scrollbar for ScrollArea.
106
108
  */
107
- const ScrollBar = React.forwardRef<
109
+ const ScrollAreaScrollbar = React.forwardRef<
108
110
  React.ComponentRef<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>,
109
- ScrollBarProps
111
+ ScrollAreaScrollbarProps
110
112
  >(
111
113
  (
112
114
  {
@@ -146,8 +148,19 @@ const ScrollBar = React.forwardRef<
146
148
  }
147
149
  );
148
150
 
149
- ScrollBar.displayName = "ScrollBar";
151
+ ScrollAreaScrollbar.displayName = "ScrollAreaScrollbar";
152
+
153
+ /**
154
+ * @deprecated Use `ScrollAreaScrollbar` instead — family parts carry the
155
+ * `ScrollArea` family prefix (DS-853).
156
+ */
157
+ const ScrollBar = ScrollAreaScrollbar;
158
+
159
+ /**
160
+ * @deprecated Use `ScrollAreaScrollbarProps` instead (DS-853).
161
+ */
162
+ type ScrollBarProps = ScrollAreaScrollbarProps;
150
163
 
151
- export { ScrollArea, ScrollBar };
164
+ export { ScrollArea, ScrollAreaScrollbar, ScrollBar };
152
165
 
153
- export type { ScrollAreaProps, ScrollBarProps };
166
+ export type { ScrollAreaProps, ScrollAreaScrollbarProps, ScrollBarProps };
@@ -184,9 +184,9 @@ const selectTriggerVariants = cva([
184
184
  "bg-neutral-50 border-neutral-300",
185
185
  "dark:bg-white/5 dark:border-white/15",
186
186
 
187
- // Typography — text-body (16px) per the Figma form-field example: the select
188
- // sits beside inputs and both are values, so both are body (DS-921).
189
- "text-body text-foreground",
187
+ // Typography — text-field (DS-992): label-sized like every field value, with
188
+ // the built-in 16px touch bump that keeps iOS Safari from zooming on focus.
189
+ "text-field text-foreground",
190
190
 
191
191
  // Text truncation for long content (shadcn default behavior)
192
192
  "[&>span]:block [&>span]:truncate",
@@ -223,6 +223,16 @@ interface SelectTriggerProps extends React.ComponentProps<
223
223
  * @default "Select an option"
224
224
  */
225
225
  selectLabel?: string;
226
+ /**
227
+ * The visible labels this select can show, rendered invisibly inside the
228
+ * trigger so it always reserves the width of the widest one. Keeps the
229
+ * trigger — and the row around it, e.g. a CardToolbar filter row — from
230
+ * resizing and reflowing when the selection changes (DS-989). Include the
231
+ * placeholder if it can be the longest. For long option lists pass just a
232
+ * handful of the longest labels — every entry renders a hidden span.
233
+ * @example <SelectTrigger reserveValues={["All ratings", "4 stars and up"]}>
234
+ */
235
+ reserveValues?: React.ReactNode[];
226
236
  }
227
237
 
228
238
  // ============================================================================
@@ -239,6 +249,7 @@ function SelectTrigger({
239
249
  dataHook,
240
250
  error,
241
251
  selectLabel,
252
+ reserveValues,
242
253
  ...props
243
254
  }: SelectTriggerProps) {
244
255
  // Support both error prop and aria-invalid for backwards compatibility
@@ -267,8 +278,27 @@ function SelectTrigger({
267
278
  data-hook={dataHook}
268
279
  data-slot="select-trigger"
269
280
  >
270
- {/* Select value or placeholder */}
271
- {children}
281
+ {/* Select value or placeholder. With reserveValues, every possible
282
+ label is stacked invisibly in the same grid cell, so the trigger
283
+ keeps the width of the widest one and never reflows its row. */}
284
+ {reserveValues?.length ? (
285
+ // The base [&>span]:block would beat .grid on specificity, flowing the
286
+ // sizer spans inline and summing their widths — hence !grid.
287
+ <span className="!grid min-w-0 text-left" data-slot="select-reserve">
288
+ {reserveValues.map((value, i) => (
289
+ <span
290
+ key={i}
291
+ aria-hidden="true"
292
+ className="invisible col-start-1 row-start-1 truncate"
293
+ >
294
+ {value}
295
+ </span>
296
+ ))}
297
+ <span className="col-start-1 row-start-1 truncate">{children}</span>
298
+ </span>
299
+ ) : (
300
+ children
301
+ )}
272
302
 
273
303
  {/* Dropdown chevron (right side) */}
274
304
  <SelectPrimitive.Icon asChild>
@@ -403,11 +433,21 @@ SelectLabel.displayName = "SelectLabel";
403
433
  * </div>
404
434
  * </SelectItem>
405
435
  */
406
- function SelectItem({
407
- className,
408
- children,
409
- ...props
410
- }: React.ComponentProps<typeof SelectPrimitive.Item>) {
436
+ /**
437
+ * Props for the SelectItem component.
438
+ */
439
+ interface SelectItemProps extends React.ComponentProps<
440
+ typeof SelectPrimitive.Item
441
+ > {
442
+ /**
443
+ * Secondary hint rendered after the item label (e.g. "Latest").
444
+ * Rendered outside the item's text value, so it shows in the open list
445
+ * but never leaks into the trigger's selected-value rendering.
446
+ */
447
+ hint?: React.ReactNode;
448
+ }
449
+
450
+ function SelectItem({ className, children, hint, ...props }: SelectItemProps) {
411
451
  const itemStyles = cn(
412
452
  // Base layout
413
453
  "relative flex w-full cursor-default select-none items-center gap-2",
@@ -441,6 +481,15 @@ function SelectItem({
441
481
  </span>
442
482
 
443
483
  <SelectPrimitive.ItemText>{children}</SelectPrimitive.ItemText>
484
+
485
+ {hint != null && (
486
+ <span
487
+ className="text-label-sm text-muted-foreground ml-auto"
488
+ data-slot="select-item-hint"
489
+ >
490
+ {hint}
491
+ </span>
492
+ )}
444
493
  </SelectPrimitive.Item>
445
494
  );
446
495
  }
@@ -524,4 +573,9 @@ export {
524
573
  SelectValue,
525
574
  };
526
575
 
527
- export type { SelectContentProps, SelectProps, SelectTriggerProps };
576
+ export type {
577
+ SelectContentProps,
578
+ SelectItemProps,
579
+ SelectProps,
580
+ SelectTriggerProps,
581
+ };
@@ -3,9 +3,10 @@
3
3
  import * as React from "react";
4
4
  import * as SheetPrimitive from "@radix-ui/react-dialog";
5
5
  import { cva, type VariantProps } from "class-variance-authority";
6
- import { X } from "@brightlocal/icons";
6
+ import { ChevronDown, ChevronUp, X } from "@brightlocal/icons";
7
7
 
8
8
  import { cn } from "@brightlocal/ui-components/lib/utils";
9
+ import { Button } from "@brightlocal/ui-components/button";
9
10
  import { ScrollArea } from "@brightlocal/ui-components/scroll-area";
10
11
  import { useOverlayPointerLock } from "@brightlocal/ui-components/hooks/use-overlay-pointer-lock";
11
12
 
@@ -273,9 +274,18 @@ const SheetContent = React.forwardRef<
273
274
  {...props}
274
275
  >
275
276
  {children}
276
- <SheetPrimitive.Close className="ring-offset-background focus-visible:ring-ring data-[state=open]:bg-accent data-[state=open]:text-muted-foreground duration-fast absolute top-4 right-4 rounded-xs opacity-70 outline-hidden transition-opacity ease-out hover:opacity-100 focus-visible:ring-2 focus-visible:ring-offset-2 disabled:pointer-events-none [&_svg]:pointer-events-none [&_svg]:shrink-0">
277
- <X />
278
- <span className="sr-only">{closeLabel ?? "Close"}</span>
277
+ {/* Ghost icon button (DS-1035) — standard hover/focus states, and its
278
+ 36px box at top-6 lines up with a SheetPagination row. */}
279
+ <SheetPrimitive.Close asChild>
280
+ <Button
281
+ iconOnly
282
+ className="absolute top-6 right-4"
283
+ dataHook="sheet-close"
284
+ variant="ghost"
285
+ >
286
+ <X />
287
+ <span className="sr-only">{closeLabel ?? "Close"}</span>
288
+ </Button>
279
289
  </SheetPrimitive.Close>
280
290
  </SheetPrimitive.Content>
281
291
  </SheetPortal>
@@ -301,6 +311,229 @@ const SheetHeader = React.forwardRef<
301
311
  ));
302
312
  SheetHeader.displayName = "SheetHeader";
303
313
 
314
+ /**
315
+ * Numbers a `SheetPagination` position indicator is built from.
316
+ */
317
+ interface SheetPaginationPositionInfo {
318
+ /** 1-based position of the item shown in the sheet. */
319
+ current: number;
320
+ /** Total number of items in the list being stepped through. */
321
+ total: number;
322
+ }
323
+
324
+ /**
325
+ * Props for the SheetPagination component
326
+ */
327
+ interface SheetPaginationProps extends Omit<
328
+ React.ComponentProps<"div">,
329
+ "children"
330
+ > {
331
+ /** Called when the user steps to the previous item. */
332
+ onPrevious: () => void;
333
+ /** Called when the user steps to the next item. */
334
+ onNext: () => void;
335
+ /**
336
+ * 1-based position of the item shown in the sheet. Together with `total`,
337
+ * drives the position indicator and the default boundary state.
338
+ */
339
+ current?: number;
340
+ /** Total number of items in the list being stepped through. */
341
+ total?: number;
342
+ /**
343
+ * Whether a previous item exists. Disables the previous button when false.
344
+ * @default current > 1 (true when `current` is not set)
345
+ */
346
+ hasPrevious?: boolean;
347
+ /**
348
+ * Whether a next item exists. Disables the next button when false.
349
+ * @default current < total (true when either is not set)
350
+ */
351
+ hasNext?: boolean;
352
+ /**
353
+ * Render the position indicator. Receives the current position and total;
354
+ * you own the wording. Return `null` to hide it.
355
+ * @default Renders "{current} of {total}", or nothing when either is unset.
356
+ */
357
+ renderPosition?:
358
+ | ((info: SheetPaginationPositionInfo) => React.ReactNode)
359
+ | null;
360
+ /**
361
+ * Accessible label for the item navigation group.
362
+ * @default "Item navigation"
363
+ */
364
+ ariaLabel?: string;
365
+ /**
366
+ * Accessible label for the previous button.
367
+ * @default "Previous item"
368
+ */
369
+ prevAriaLabel?: string;
370
+ /**
371
+ * Accessible label for the next button.
372
+ * @default "Next item"
373
+ */
374
+ nextAriaLabel?: string;
375
+ /**
376
+ * Data hook for automated testing. The buttons get `{dataHook}-previous`
377
+ * and `{dataHook}-next`.
378
+ */
379
+ dataHook: string;
380
+ /**
381
+ * Tracking element identifier for analytics
382
+ */
383
+ trackingEl?: string;
384
+ /**
385
+ * Tracking label for analytics context
386
+ */
387
+ trackingLabel?: string;
388
+ }
389
+
390
+ /**
391
+ * Previous/next controls for stepping through a list of items without
392
+ * closing the sheet — e.g. a detail sheet drilled into from a table row.
393
+ * Place it as the first child of SheetContent, above SheetHeader; it shares
394
+ * the close button's row. The arrow keys step while focus is on the controls.
395
+ */
396
+ const SheetPagination = React.forwardRef<HTMLDivElement, SheetPaginationProps>(
397
+ (
398
+ {
399
+ className,
400
+ onPrevious,
401
+ onNext,
402
+ current,
403
+ total,
404
+ hasPrevious,
405
+ hasNext,
406
+ renderPosition,
407
+ ariaLabel,
408
+ prevAriaLabel,
409
+ nextAriaLabel,
410
+ dataHook,
411
+ trackingEl,
412
+ trackingLabel,
413
+ ...props
414
+ },
415
+ ref
416
+ ) => {
417
+ const canPrevious = hasPrevious ?? (current == null || current > 1);
418
+ const canNext =
419
+ hasNext ?? (current == null || total == null || current < total);
420
+
421
+ const prevRef = React.useRef<HTMLButtonElement>(null);
422
+ const nextRef = React.useRef<HTMLButtonElement>(null);
423
+ // The button that just triggered a step. Set only by our own
424
+ // navigation, consumed on the next commit.
425
+ const pendingRef = React.useRef<HTMLButtonElement | null>(null);
426
+
427
+ // Reaching a boundary disables the button that was just pressed, which
428
+ // drops focus to <body>. Hand it to the sibling instead so keyboard users
429
+ // stay in the control.
430
+ React.useEffect(() => {
431
+ const pending = pendingRef.current;
432
+ pendingRef.current = null;
433
+ if (!pending) return;
434
+ const active = document.activeElement;
435
+ if (active !== pending && active !== document.body) return;
436
+ if (!canPrevious && pending === prevRef.current && canNext) {
437
+ nextRef.current?.focus();
438
+ } else if (!canNext && pending === nextRef.current && canPrevious) {
439
+ prevRef.current?.focus();
440
+ }
441
+ });
442
+
443
+ const handleBlur = (event: React.FocusEvent<HTMLButtonElement>) => {
444
+ // Focus left on purpose (to anything but the sibling) — drop any
445
+ // pending hand-off. A disabled button blurs with a null relatedTarget.
446
+ const next = event.relatedTarget;
447
+ if (next && next !== prevRef.current && next !== nextRef.current) {
448
+ pendingRef.current = null;
449
+ }
450
+ };
451
+
452
+ const step = (
453
+ direction: "previous" | "next",
454
+ trigger: HTMLButtonElement
455
+ ) => {
456
+ if (direction === "previous") {
457
+ if (!canPrevious) return;
458
+ pendingRef.current = trigger;
459
+ onPrevious();
460
+ } else {
461
+ if (!canNext) return;
462
+ pendingRef.current = trigger;
463
+ onNext();
464
+ }
465
+ };
466
+
467
+ const handleKeyDown = (event: React.KeyboardEvent<HTMLButtonElement>) => {
468
+ if (event.key === "ArrowUp" || event.key === "ArrowLeft") {
469
+ event.preventDefault();
470
+ step("previous", event.currentTarget);
471
+ } else if (event.key === "ArrowDown" || event.key === "ArrowRight") {
472
+ event.preventDefault();
473
+ step("next", event.currentTarget);
474
+ }
475
+ };
476
+
477
+ let position: React.ReactNode = null;
478
+ if (renderPosition !== null && current != null && total != null) {
479
+ position = renderPosition
480
+ ? renderPosition({ current, total })
481
+ : `${current} of ${total}`;
482
+ }
483
+
484
+ return (
485
+ <div
486
+ ref={ref}
487
+ aria-label={ariaLabel ?? "Item navigation"}
488
+ // mb-2 on top of SheetContent's gap-4 gives the 24px Figma gap to
489
+ // the header below.
490
+ className={cn("mb-2 flex items-center gap-1", className)}
491
+ data-hook={dataHook}
492
+ data-slot="sheet-pagination"
493
+ data-tracking-el={trackingEl}
494
+ data-tracking-label={trackingLabel}
495
+ role="group"
496
+ {...props}
497
+ >
498
+ <Button
499
+ ref={prevRef}
500
+ ariaLabel={prevAriaLabel ?? "Previous item"}
501
+ dataHook={`${dataHook}-previous`}
502
+ disabled={!canPrevious}
503
+ variant="ghost"
504
+ onBlur={handleBlur}
505
+ onClick={(event) => step("previous", event.currentTarget)}
506
+ onKeyDown={handleKeyDown}
507
+ >
508
+ <ChevronUp />
509
+ </Button>
510
+ <Button
511
+ ref={nextRef}
512
+ ariaLabel={nextAriaLabel ?? "Next item"}
513
+ dataHook={`${dataHook}-next`}
514
+ disabled={!canNext}
515
+ variant="ghost"
516
+ onBlur={handleBlur}
517
+ onClick={(event) => step("next", event.currentTarget)}
518
+ onKeyDown={handleKeyDown}
519
+ >
520
+ <ChevronDown />
521
+ </Button>
522
+ {position != null && (
523
+ <span
524
+ aria-live="polite"
525
+ className="text-body-sm text-muted-foreground"
526
+ data-slot="sheet-pagination-position"
527
+ >
528
+ {position}
529
+ </span>
530
+ )}
531
+ </div>
532
+ );
533
+ }
534
+ );
535
+ SheetPagination.displayName = "SheetPagination";
536
+
304
537
  /**
305
538
  * Props for the SheetBody component
306
539
  */
@@ -450,6 +683,7 @@ export {
450
683
  SheetFooter,
451
684
  SheetHeader,
452
685
  SheetOverlay,
686
+ SheetPagination,
453
687
  SheetPortal,
454
688
  SheetTitle,
455
689
  SheetTrigger,
@@ -459,6 +693,8 @@ export type {
459
693
  SheetBodyProps,
460
694
  SheetContentProps,
461
695
  SheetDescriptionProps,
696
+ SheetPaginationPositionInfo,
697
+ SheetPaginationProps,
462
698
  SheetTitleProps,
463
699
  SheetTriggerProps,
464
700
  };