@brightlocal/ui-components 3.3.0 → 3.4.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.
@@ -1,16 +1,25 @@
1
+ "use client";
2
+
1
3
  import * as React from "react";
2
4
  import { Slot } from "@radix-ui/react-slot";
3
5
  import { cva } from "class-variance-authority";
4
6
 
7
+ import { ChevronRight } from "@brightlocal/icons";
5
8
  import { cn } from "@brightlocal/ui-components/lib/utils";
6
9
  import { Skeleton } from "@brightlocal/ui-components/skeleton";
10
+ import {
11
+ Tooltip,
12
+ TooltipContent,
13
+ TooltipTrigger,
14
+ } from "@brightlocal/ui-components/tooltip";
7
15
 
8
16
  /* -------------------------------------------------------------------------------------------------
9
- * Item variants
17
+ * ListItem variants
10
18
  * -----------------------------------------------------------------------------------------------*/
11
19
 
12
- const itemVariants = cva(
20
+ const listItemVariants = cva(
13
21
  [
22
+ "group/item",
14
23
  "flex",
15
24
  "gap-4",
16
25
  "rounded-lg",
@@ -20,6 +29,10 @@ const itemVariants = cva(
20
29
  "transition-colors",
21
30
  "duration-fast",
22
31
  "ease-out",
32
+ // A row that holds an ListItemButton or ListItemLink hands its padding to it, so the
33
+ // whole row is the hit area and the padding never doubles (DS-1166).
34
+ "has-[>[data-slot=item-button]]:p-0",
35
+ "has-[>[data-slot=item-link]]:p-0",
23
36
  ],
24
37
  {
25
38
  variants: {
@@ -54,6 +67,19 @@ export type ListProps = React.ComponentProps<"ul"> & {
54
67
  * Data hook for automated testing (required).
55
68
  */
56
69
  dataHook: string;
70
+ /**
71
+ * Pulls the list out by the row's own inline padding, so the text of plain
72
+ * (`default`) rows lines up with the content edge of the card around it.
73
+ * @default false
74
+ */
75
+ inset?: boolean;
76
+ /**
77
+ * Draws a hairline between rows and drops the gap and the row radius, for
78
+ * plain (`default`) rows such as a drill-down list. For a single break
79
+ * between two groups, use `ListSeparator` instead.
80
+ * @default false
81
+ */
82
+ divided?: boolean;
57
83
  /**
58
84
  * Tracking element identifier for analytics.
59
85
  */
@@ -65,27 +91,58 @@ export type ListProps = React.ComponentProps<"ul"> & {
65
91
  };
66
92
 
67
93
  /**
68
- * Vertical list container for rendering a collection of Item rows.
94
+ * Vertical list container for rendering a collection of ListItem rows.
69
95
  *
70
96
  * @example
71
97
  * ```tsx
72
98
  * <List dataHook="keywords-list">
73
- * <Item variant="filled" dataHook="item-1">
74
- * <ItemContent>
75
- * <ItemTitle>Keyword</ItemTitle>
76
- * </ItemContent>
77
- * <ItemActions>
99
+ * <ListItem variant="filled" dataHook="item-1">
100
+ * <ListItemContent>
101
+ * <ListItemTitle>Keyword</ListItemTitle>
102
+ * </ListItemContent>
103
+ * <ListItemActions>
78
104
  * <Button variant="ghost" size="icon" dataHook="remove"><XIcon /></Button>
79
- * </ItemActions>
80
- * </Item>
105
+ * </ListItemActions>
106
+ * </ListItem>
81
107
  * </List>
82
108
  * ```
83
109
  */
110
+ const listVariants = cva(["flex", "flex-col"], {
111
+ variants: {
112
+ inset: {
113
+ true: ["-mr-2", "-ml-4"],
114
+ false: [],
115
+ },
116
+ divided: {
117
+ true: [
118
+ "gap-0",
119
+ "[&>[data-slot=item]]:rounded-none",
120
+ "[&>[data-slot=item]+[data-slot=item]]:border-t",
121
+ "[&>[data-slot=item]+[data-slot=item]]:border-border",
122
+ ],
123
+ false: ["gap-2"],
124
+ },
125
+ },
126
+ defaultVariants: { inset: false, divided: false },
127
+ });
128
+
84
129
  const List = React.forwardRef<HTMLUListElement, ListProps>(
85
- ({ className, dataHook, trackingEl, trackingLabel, ...props }, ref) => (
130
+ (
131
+ {
132
+ className,
133
+ dataHook,
134
+ trackingEl,
135
+ trackingLabel,
136
+ inset,
137
+ divided,
138
+ ...props
139
+ },
140
+ ref
141
+ ) => (
86
142
  <ul
87
143
  ref={ref}
88
- className={cn("flex flex-col gap-2", className)}
144
+ className={cn(listVariants({ inset, divided }), className)}
145
+ data-divided={divided ? "" : undefined}
89
146
  data-hook={dataHook}
90
147
  data-slot="list"
91
148
  data-tracking-el={trackingEl}
@@ -97,14 +154,14 @@ const List = React.forwardRef<HTMLUListElement, ListProps>(
97
154
  List.displayName = "List";
98
155
 
99
156
  /* -------------------------------------------------------------------------------------------------
100
- * Item
157
+ * ListItem
101
158
  * -----------------------------------------------------------------------------------------------*/
102
159
 
103
160
  /**
104
- * Props for an individual Item row within a List.
161
+ * Props for an individual ListItem row within a List.
105
162
  * Extends native `<li>` props with CVA variant styling and optional testing/analytics attributes.
106
163
  */
107
- export type ItemProps = React.ComponentProps<"li"> & {
164
+ export type ListItemProps = React.ComponentProps<"li"> & {
108
165
  /**
109
166
  * Render as the child element instead of `<li>`.
110
167
  * Useful when the item is wrapped by another element (e.g. `<motion.li>`).
@@ -121,7 +178,7 @@ export type ItemProps = React.ComponentProps<"li"> & {
121
178
  variant?: "default" | "filled" | "outline" | "loading";
122
179
  /**
123
180
  * Cross-axis alignment of the row's children (media, content, actions).
124
- * Use `"start"` when ItemMedia (icon, avatar, step number) should pin to the
181
+ * Use `"start"` when ListItemMedia (icon, avatar, step number) should pin to the
125
182
  * first line of multi-line content instead of centering vertically.
126
183
  * @default "center"
127
184
  */
@@ -142,9 +199,9 @@ export type ItemProps = React.ComponentProps<"li"> & {
142
199
 
143
200
  /**
144
201
  * Row component within a List. Supports `default`, `filled`, `outline`, and `loading` variants.
145
- * Compose with ItemMedia, ItemContent, ItemTitle, ItemDescription, and ItemActions.
202
+ * Compose with ListItemMedia, ListItemContent, ListItemTitle, ListItemDescription, and ListItemActions.
146
203
  */
147
- const Item = React.forwardRef<HTMLLIElement, ItemProps>(
204
+ const ListItem = React.forwardRef<HTMLLIElement, ListItemProps>(
148
205
  (
149
206
  {
150
207
  asChild = false,
@@ -164,7 +221,8 @@ const Item = React.forwardRef<HTMLLIElement, ItemProps>(
164
221
  return (
165
222
  <Comp
166
223
  ref={ref}
167
- className={cn(itemVariants({ variant, align }), className)}
224
+ className={cn(listItemVariants({ variant, align }), className)}
225
+ data-align={align ?? "center"}
168
226
  data-hook={dataHook}
169
227
  data-slot="item"
170
228
  data-tracking-el={trackingEl}
@@ -183,113 +241,354 @@ const Item = React.forwardRef<HTMLLIElement, ItemProps>(
183
241
  );
184
242
  }
185
243
  );
186
- Item.displayName = "Item";
244
+ ListItem.displayName = "ListItem";
187
245
 
188
246
  /* -------------------------------------------------------------------------------------------------
189
- * ItemMedia
247
+ * ListItemMedia
190
248
  * -----------------------------------------------------------------------------------------------*/
191
249
 
192
- /** Props for the ItemMedia sub-component — optional left-side media slot. */
193
- export type ItemMediaProps = React.ComponentProps<"div">;
250
+ const listItemMediaVariants = cva(["shrink-0"], {
251
+ variants: {
252
+ variant: {
253
+ default: [],
254
+ icon: [
255
+ "inline-flex",
256
+ "size-10",
257
+ "items-center",
258
+ "justify-center",
259
+ "rounded-lg",
260
+ "border",
261
+ "border-border",
262
+ "bg-background",
263
+ ],
264
+ image: [
265
+ "size-10",
266
+ "overflow-hidden",
267
+ "rounded-lg",
268
+ "[&_img]:size-full",
269
+ "[&_img]:object-cover",
270
+ ],
271
+ },
272
+ },
273
+ defaultVariants: { variant: "default" },
274
+ });
275
+
276
+ /** Props for the ListItemMedia sub-component — optional left-side media slot. */
277
+ export type ListItemMediaProps = React.ComponentProps<"div"> & {
278
+ /**
279
+ * How the media is framed.
280
+ * - `default` — the icon or avatar as it is
281
+ * - `icon` — a 40px bordered tile, for brand logos and icons
282
+ * - `image` — a 40px rounded crop, for thumbnails
283
+ * @default "default"
284
+ */
285
+ variant?: "default" | "icon" | "image";
286
+ };
194
287
 
195
288
  /**
196
- * Optional left-side media slot for icons or avatars.
289
+ * Optional left-side media slot for icons, avatars, logo tiles or thumbnails.
197
290
  */
198
- const ItemMedia = React.forwardRef<HTMLDivElement, ItemMediaProps>(
199
- ({ className, ...props }, ref) => (
291
+ const ListItemMedia = React.forwardRef<HTMLDivElement, ListItemMediaProps>(
292
+ ({ className, variant, ...props }, ref) => (
200
293
  <div
201
294
  ref={ref}
202
- className={cn("shrink-0", className)}
295
+ className={cn(listItemMediaVariants({ variant }), className)}
203
296
  data-slot="item-media"
297
+ data-variant={variant ?? "default"}
204
298
  {...props}
205
299
  />
206
300
  )
207
301
  );
208
- ItemMedia.displayName = "ItemMedia";
302
+ ListItemMedia.displayName = "ListItemMedia";
209
303
 
210
304
  /* -------------------------------------------------------------------------------------------------
211
- * ItemContent
305
+ * ListItemContent
212
306
  * -----------------------------------------------------------------------------------------------*/
213
307
 
214
- /** Props for the ItemContent sub-component — flexible content area within an Item. */
215
- export type ItemContentProps = React.ComponentProps<"div">;
308
+ /** Props for the ListItemContent sub-component — flexible content area within an ListItem. */
309
+ export type ListItemContentProps = React.ComponentProps<"div">;
216
310
 
217
311
  /**
218
312
  * Flexible content area that grows to fill available space.
219
- * Place ItemTitle and ItemDescription inside.
313
+ * Place ListItemTitle and ListItemDescription inside.
220
314
  */
221
- const ItemContent = React.forwardRef<HTMLDivElement, ItemContentProps>(
315
+ const ListItemContent = React.forwardRef<HTMLDivElement, ListItemContentProps>(
222
316
  ({ className, ...props }, ref) => (
223
317
  <div
224
318
  ref={ref}
225
- className={cn("flex flex-1 flex-col gap-1", className)}
319
+ className={cn("flex min-w-0 flex-1 flex-col gap-1", className)}
226
320
  data-slot="item-content"
227
321
  {...props}
228
322
  />
229
323
  )
230
324
  );
231
- ItemContent.displayName = "ItemContent";
325
+ ListItemContent.displayName = "ListItemContent";
232
326
 
233
327
  /* -------------------------------------------------------------------------------------------------
234
- * ItemTitle
328
+ * Truncated text (shared by ListItemTitle and ListItemDescription)
235
329
  * -----------------------------------------------------------------------------------------------*/
236
330
 
237
- /** Props for the ItemTitle sub-component — primary text label within an Item. */
238
- export type ItemTitleProps = React.ComponentProps<"div">;
331
+ /** The pressable row parts whose keyboard focus also reveals a cut-off text. */
332
+ const PRESSABLE_ROW_SELECTOR =
333
+ '[data-slot="item-button"], [data-slot="item-link"]';
239
334
 
240
335
  /**
241
- * Primary text label within an Item.
336
+ * Whether the element's text is clamped (cut off past its second line).
337
+ * Measured in a ResizeObserver callback, so it follows the element's width and
338
+ * runs again when the text changes (a MutationObserver re-observes).
242
339
  */
243
- const ItemTitle = React.forwardRef<HTMLDivElement, ItemTitleProps>(
244
- ({ className, ...props }, ref) => (
245
- <div
246
- ref={ref}
247
- className={cn("text-foreground text-body", className)}
248
- data-slot="item-title"
249
- {...props}
250
- />
251
- )
340
+ function useIsClamped(el: HTMLElement | null, enabled: boolean) {
341
+ const [clamped, setClamped] = React.useState(false);
342
+
343
+ React.useEffect(() => {
344
+ if (!enabled || !el) return;
345
+ const measure = () =>
346
+ setClamped(
347
+ el.scrollHeight > el.clientHeight + 1 ||
348
+ el.scrollWidth > el.clientWidth + 1
349
+ );
350
+ // ResizeObserver fires once on observe, so the first measure is async.
351
+ const resize = new ResizeObserver(measure);
352
+ resize.observe(el);
353
+ const mutation = new MutationObserver(measure);
354
+ mutation.observe(el, {
355
+ characterData: true,
356
+ childList: true,
357
+ subtree: true,
358
+ });
359
+ return () => {
360
+ resize.disconnect();
361
+ mutation.disconnect();
362
+ };
363
+ }, [enabled, el]);
364
+
365
+ return enabled && el !== null && clamped;
366
+ }
367
+
368
+ /**
369
+ * Keyboard focus on the row's ListItemButton / ListItemLink. The text itself is
370
+ * never a tab stop: the row stays one interactive target, and focusing it
371
+ * shows the full text of whatever is clamped inside it.
372
+ */
373
+ function useRowFocusVisible(el: HTMLElement | null, enabled: boolean) {
374
+ const [focusedRow, setFocusedRow] = React.useState<Element | null>(null);
375
+ const row = enabled ? (el?.closest(PRESSABLE_ROW_SELECTOR) ?? null) : null;
376
+
377
+ React.useEffect(() => {
378
+ if (!row) return;
379
+ const onFocus = () =>
380
+ setFocusedRow(
381
+ row === document.activeElement && row.matches(":focus-visible")
382
+ ? row
383
+ : null
384
+ );
385
+ const onBlur = () => setFocusedRow(null);
386
+ // The row may already hold focus when the listeners go in (it was
387
+ // focused before the text became clamped), so read the current state too.
388
+ onFocus();
389
+ row.addEventListener("focus", onFocus);
390
+ row.addEventListener("blur", onBlur);
391
+ return () => {
392
+ row.removeEventListener("focus", onFocus);
393
+ row.removeEventListener("blur", onBlur);
394
+ };
395
+ }, [row]);
396
+
397
+ return row !== null && focusedRow === row;
398
+ }
399
+
400
+ type TruncatableTextProps = React.ComponentProps<"div"> & {
401
+ asChild?: boolean;
402
+ truncate?: boolean;
403
+ partSlot: "item-title" | "item-description";
404
+ tooltipSide: "top" | "bottom";
405
+ };
406
+
407
+ /**
408
+ * Renders the text, and when `truncate` is on and the text runs past two
409
+ * lines (clamped with an ellipsis), wraps it in a Tooltip with the full text. Hover opens it with a
410
+ * mouse; keyboard focus on the row opens it; a tap opens it only when the
411
+ * text is not inside a button, link or label, so a tap on a pressable row
412
+ * still does what the row does. The full text stays in the DOM for screen
413
+ * readers, so nothing extra is announced.
414
+ */
415
+ const TruncatableText = React.forwardRef<HTMLDivElement, TruncatableTextProps>(
416
+ (
417
+ {
418
+ asChild = false,
419
+ truncate = false,
420
+ partSlot,
421
+ tooltipSide,
422
+ className,
423
+ children,
424
+ ...props
425
+ },
426
+ forwardedRef
427
+ ) => {
428
+ // The node lives in state, not a ref: wrapping the text in the Tooltip
429
+ // remounts it, and the observers must follow the new node.
430
+ const [node, setNode] = React.useState<HTMLDivElement | null>(null);
431
+ const setRefs = React.useCallback(
432
+ (el: HTMLDivElement | null) => {
433
+ setNode(el);
434
+ if (typeof forwardedRef === "function") forwardedRef(el);
435
+ else if (forwardedRef) forwardedRef.current = el;
436
+ },
437
+ [forwardedRef]
438
+ );
439
+ const truncated = useIsClamped(node, truncate);
440
+ const rowFocused = useRowFocusVisible(node, truncated);
441
+ const [hoverOpen, setHoverOpen] = React.useState(false);
442
+ // Escape closes the tooltip even while the row keeps focus; it stays
443
+ // closed until the next focus or hover asks for it again.
444
+ const [dismissed, setDismissed] = React.useState(false);
445
+ const [prevRowFocused, setPrevRowFocused] = React.useState(rowFocused);
446
+ if (rowFocused !== prevRowFocused) {
447
+ setPrevRowFocused(rowFocused);
448
+ if (rowFocused) setDismissed(false);
449
+ }
450
+
451
+ const Comp = asChild ? Slot : "div";
452
+ const text = (
453
+ <Comp
454
+ ref={setRefs}
455
+ className={cn(truncate && "line-clamp-2", className)}
456
+ data-slot={partSlot}
457
+ data-truncated={truncated ? "" : undefined}
458
+ {...props}
459
+ >
460
+ {children}
461
+ </Comp>
462
+ );
463
+
464
+ if (!truncated) return text;
465
+
466
+ return (
467
+ <Tooltip
468
+ open={!dismissed && (hoverOpen || rowFocused)}
469
+ onOpenChange={(open) => {
470
+ if (open) setDismissed(false);
471
+ setHoverOpen(open);
472
+ }}
473
+ >
474
+ <TooltipTrigger
475
+ asChild
476
+ onPointerDown={(event) => {
477
+ // Inside a button, link or label a tap belongs to that control:
478
+ // stop the tooltip from claiming it. The click still fires.
479
+ const target = event.currentTarget as HTMLElement;
480
+ if (
481
+ event.pointerType === "touch" &&
482
+ (target.closest("button, a, label") || target.tagName === "LABEL")
483
+ ) {
484
+ event.preventDefault();
485
+ }
486
+ }}
487
+ >
488
+ {text}
489
+ </TooltipTrigger>
490
+ <TooltipContent
491
+ dataHook={`list-${partSlot}-tooltip`}
492
+ side={tooltipSide}
493
+ sideOffset={4}
494
+ onEscapeKeyDown={() => setDismissed(true)}
495
+ >
496
+ {children}
497
+ </TooltipContent>
498
+ </Tooltip>
499
+ );
500
+ }
252
501
  );
253
- ItemTitle.displayName = "ItemTitle";
502
+ TruncatableText.displayName = "TruncatableText";
254
503
 
255
504
  /* -------------------------------------------------------------------------------------------------
256
- * ItemDescription
505
+ * ListItemTitle
257
506
  * -----------------------------------------------------------------------------------------------*/
258
507
 
259
- /** Props for the ItemDescription sub-component — supporting text beneath ItemTitle. */
260
- export type ItemDescriptionProps = React.ComponentProps<"div">;
508
+ /** Props for the ListItemTitle sub-component — primary text label within a ListItem. */
509
+ export type ListItemTitleProps = React.ComponentProps<"div"> & {
510
+ /**
511
+ * Render as the child element, e.g. a `<label>` that names the row's Switch.
512
+ * Works together with `truncate`.
513
+ */
514
+ asChild?: boolean;
515
+ /**
516
+ * Wrap the title to at most two lines and clamp the rest with an ellipsis.
517
+ * When it is clamped, hovering it (or focusing the row's ListItemButton /
518
+ * ListItemLink) shows the full title in a Tooltip. Two lines that fit get
519
+ * no tooltip.
520
+ * @default false
521
+ */
522
+ truncate?: boolean;
523
+ };
261
524
 
262
525
  /**
263
- * Supporting description text beneath ItemTitle.
526
+ * Primary text label within a ListItem.
264
527
  */
265
- const ItemDescription = React.forwardRef<HTMLDivElement, ItemDescriptionProps>(
528
+ const ListItemTitle = React.forwardRef<HTMLDivElement, ListItemTitleProps>(
266
529
  ({ className, ...props }, ref) => (
267
- <div
530
+ <TruncatableText
268
531
  ref={ref}
269
- className={cn("text-body-sm text-muted-foreground", className)}
270
- data-slot="item-description"
532
+ className={cn("text-foreground text-body", className)}
533
+ partSlot="item-title"
534
+ tooltipSide="top"
271
535
  {...props}
272
536
  />
273
537
  )
274
538
  );
275
- ItemDescription.displayName = "ItemDescription";
539
+ ListItemTitle.displayName = "ListItemTitle";
540
+
541
+ /* -------------------------------------------------------------------------------------------------
542
+ * ListItemDescription
543
+ * -----------------------------------------------------------------------------------------------*/
544
+
545
+ /** Props for the ListItemDescription sub-component — supporting text beneath ListItemTitle. */
546
+ export type ListItemDescriptionProps = React.ComponentProps<"div"> & {
547
+ /**
548
+ * Wrap the description to at most two lines and clamp the rest with an
549
+ * ellipsis. When it is clamped, hovering it (or focusing the row's
550
+ * ListItemButton / ListItemLink) shows the full text in a Tooltip. Two lines
551
+ * that fit get no tooltip.
552
+ * @default false
553
+ */
554
+ truncate?: boolean;
555
+ };
556
+
557
+ /**
558
+ * Supporting description text beneath ListItemTitle.
559
+ */
560
+ const ListItemDescription = React.forwardRef<
561
+ HTMLDivElement,
562
+ ListItemDescriptionProps
563
+ >(({ className, ...props }, ref) => (
564
+ <TruncatableText
565
+ ref={ref}
566
+ className={cn("text-body-sm text-muted-foreground", className)}
567
+ partSlot="item-description"
568
+ tooltipSide="bottom"
569
+ {...props}
570
+ />
571
+ ));
572
+ ListItemDescription.displayName = "ListItemDescription";
276
573
 
277
574
  /* -------------------------------------------------------------------------------------------------
278
- * ItemActions
575
+ * ListItemActions
279
576
  * -----------------------------------------------------------------------------------------------*/
280
577
 
281
- /** Props for the ItemActions sub-component — right-side slot for action controls. */
282
- export type ItemActionsProps = React.ComponentProps<"div">;
578
+ /** Props for the ListItemActions sub-component — right-side slot for action controls. */
579
+ export type ListItemActionsProps = React.ComponentProps<"div">;
283
580
 
284
581
  /**
285
- * Right-side slot for action controls such as remove buttons.
582
+ * Right-side slot for trailing content: an icon button, a menu, a Switch, a
583
+ * Badge or Status, a text Button, or several of them side by side. It is at
584
+ * least 36px square, so a single icon button keeps its place.
286
585
  */
287
- const ItemActions = React.forwardRef<HTMLDivElement, ItemActionsProps>(
586
+ const ListItemActions = React.forwardRef<HTMLDivElement, ListItemActionsProps>(
288
587
  ({ className, ...props }, ref) => (
289
588
  <div
290
589
  ref={ref}
291
590
  className={cn(
292
- "text-muted-foreground flex size-9 shrink-0 items-center justify-center rounded-full",
591
+ "text-muted-foreground flex min-h-9 min-w-9 shrink-0 items-center justify-center gap-2",
293
592
  className
294
593
  )}
295
594
  data-slot="item-actions"
@@ -297,14 +596,14 @@ const ItemActions = React.forwardRef<HTMLDivElement, ItemActionsProps>(
297
596
  />
298
597
  )
299
598
  );
300
- ItemActions.displayName = "ItemActions";
599
+ ListItemActions.displayName = "ListItemActions";
301
600
 
302
601
  /* -------------------------------------------------------------------------------------------------
303
- * ItemSubheader
602
+ * ListSubheader
304
603
  * -----------------------------------------------------------------------------------------------*/
305
604
 
306
- /** Props for the ItemSubheader sub-component — section heading within a List. */
307
- export type ItemSubheaderProps = React.ComponentProps<"li"> & {
605
+ /** Props for the ListSubheader sub-component — section heading within a List. */
606
+ export type ListSubheaderProps = React.ComponentProps<"li"> & {
308
607
  /**
309
608
  * Data hook for automated testing.
310
609
  */
@@ -318,12 +617,12 @@ export type ItemSubheaderProps = React.ComponentProps<"li"> & {
318
617
  * @example
319
618
  * ```tsx
320
619
  * <List dataHook="actions-list">
321
- * <ItemSubheader>Suggestions</ItemSubheader>
322
- * <Item variant="default" dataHook="item-1">...</Item>
620
+ * <ListSubheader>Suggestions</ListSubheader>
621
+ * <ListItem variant="default" dataHook="item-1">...</ListItem>
323
622
  * </List>
324
623
  * ```
325
624
  */
326
- const ItemSubheader = React.forwardRef<HTMLLIElement, ItemSubheaderProps>(
625
+ const ListSubheader = React.forwardRef<HTMLLIElement, ListSubheaderProps>(
327
626
  ({ className, dataHook, ...props }, ref) => (
328
627
  <li
329
628
  ref={ref}
@@ -347,7 +646,304 @@ const ItemSubheader = React.forwardRef<HTMLLIElement, ItemSubheaderProps>(
347
646
  />
348
647
  )
349
648
  );
350
- ItemSubheader.displayName = "ItemSubheader";
649
+ ListSubheader.displayName = "ListSubheader";
650
+
651
+ /* -------------------------------------------------------------------------------------------------
652
+ * ListItemButton / ListItemLink
653
+ * -----------------------------------------------------------------------------------------------*/
654
+
655
+ /* The pressable part of a row. The ListItem stays the <li>, so the list keeps its
656
+ semantics, and this fills it: it takes over the row's padding and gap
657
+ (ListItem drops its own padding while it holds one) and carries the hover and
658
+ focus states. Align follows the parent ListItem through data-align. */
659
+ const listItemPressableClasses = [
660
+ "flex",
661
+ "w-full",
662
+ "min-w-0",
663
+ "items-center",
664
+ "group-data-[align=start]/item:items-start",
665
+ "gap-4",
666
+ "rounded-[inherit]",
667
+ "py-2",
668
+ "pr-2",
669
+ "pl-4",
670
+ "text-left",
671
+ "cursor-pointer",
672
+ "outline-none",
673
+ "hover:bg-accent",
674
+ "focus-visible:shadow-default",
675
+ "transition-colors",
676
+ "duration-fast",
677
+ "ease-out",
678
+ "disabled:pointer-events-none",
679
+ "disabled:cursor-not-allowed",
680
+ "disabled:opacity-50",
681
+ "aria-disabled:pointer-events-none",
682
+ "aria-disabled:cursor-not-allowed",
683
+ "aria-disabled:opacity-50",
684
+ ];
685
+
686
+ /**
687
+ * A row marked `aria-disabled` stays focusable (so it is still announced), but
688
+ * must not activate. Enter on a button or link fires a click, so blocking the
689
+ * click covers keyboard and pointer. It runs in the capture phase, before any
690
+ * child handler (a router link under `asChild`), and router links skip
691
+ * navigation once the default is prevented.
692
+ */
693
+ function blockDisabledClick(
694
+ event: React.MouseEvent<HTMLElement>,
695
+ onClickCapture?: React.MouseEventHandler<HTMLElement>
696
+ ) {
697
+ const disabled = event.currentTarget.getAttribute("aria-disabled");
698
+ if (disabled === "true" || disabled === "") {
699
+ event.preventDefault();
700
+ event.stopPropagation();
701
+ return;
702
+ }
703
+ onClickCapture?.(event);
704
+ }
705
+
706
+ /** Props for ListItemButton — a row that runs an action (opens a sheet, a drill-down level). */
707
+ export type ListItemButtonProps = React.ComponentProps<"button"> & {
708
+ /**
709
+ * Data hook for automated testing.
710
+ */
711
+ dataHook?: string;
712
+ /**
713
+ * Tracking element identifier for analytics.
714
+ */
715
+ trackingEl?: string;
716
+ /**
717
+ * Tracking label for analytics context.
718
+ */
719
+ trackingLabel?: string;
720
+ };
721
+
722
+ /**
723
+ * Makes the whole row a button. Place it as the only child of an ListItem and put
724
+ * the row's parts (ListItemMedia, ListItemContent, ListItemValue, ListItemChevron) inside it.
725
+ *
726
+ * @example
727
+ * ```tsx
728
+ * <ListItem variant="default" dataHook="location">
729
+ * <ListItemButton dataHook="location-row" onClick={open}>
730
+ * <ListItemContent><ListItemTitle>Location</ListItemTitle></ListItemContent>
731
+ * <ListItemValue>London, UK</ListItemValue>
732
+ * <ListItemChevron />
733
+ * </ListItemButton>
734
+ * </ListItem>
735
+ * ```
736
+ */
737
+ const ListItemButton = React.forwardRef<HTMLButtonElement, ListItemButtonProps>(
738
+ (
739
+ {
740
+ className,
741
+ type = "button",
742
+ dataHook,
743
+ trackingEl,
744
+ trackingLabel,
745
+ onClickCapture,
746
+ ...props
747
+ },
748
+ ref
749
+ ) => (
750
+ <button
751
+ ref={ref}
752
+ className={cn(listItemPressableClasses, className)}
753
+ data-hook={dataHook}
754
+ data-slot="item-button"
755
+ data-tracking-el={trackingEl}
756
+ data-tracking-label={trackingLabel}
757
+ type={type}
758
+ onClickCapture={(event) => blockDisabledClick(event, onClickCapture)}
759
+ {...props}
760
+ />
761
+ )
762
+ );
763
+ ListItemButton.displayName = "ListItemButton";
764
+
765
+ /** Props for ListItemLink — a row that navigates. */
766
+ export type ListItemLinkProps = React.ComponentProps<"a"> & {
767
+ /**
768
+ * Render as the child element, e.g. a router `<Link>`.
769
+ */
770
+ asChild?: boolean;
771
+ /**
772
+ * Data hook for automated testing.
773
+ */
774
+ dataHook?: string;
775
+ /**
776
+ * Tracking element identifier for analytics.
777
+ */
778
+ trackingEl?: string;
779
+ /**
780
+ * Tracking label for analytics context.
781
+ */
782
+ trackingLabel?: string;
783
+ };
784
+
785
+ /**
786
+ * Makes the whole row a link. Place it as the only child of an ListItem; use
787
+ * `asChild` to render a router link.
788
+ *
789
+ * @example
790
+ * ```tsx
791
+ * <ListItem variant="outline" dataHook="billing">
792
+ * <ListItemLink asChild dataHook="billing-link">
793
+ * <NextLink href="/settings/billing">
794
+ * <ListItemContent><ListItemTitle>Billing</ListItemTitle></ListItemContent>
795
+ * <ListItemChevron />
796
+ * </NextLink>
797
+ * </ListItemLink>
798
+ * </ListItem>
799
+ * ```
800
+ */
801
+ const ListItemLink = React.forwardRef<HTMLAnchorElement, ListItemLinkProps>(
802
+ (
803
+ {
804
+ className,
805
+ asChild = false,
806
+ dataHook,
807
+ trackingEl,
808
+ trackingLabel,
809
+ onClickCapture,
810
+ ...props
811
+ },
812
+ ref
813
+ ) => {
814
+ const Comp = asChild ? Slot : "a";
815
+ return (
816
+ <Comp
817
+ ref={ref}
818
+ className={cn(listItemPressableClasses, className)}
819
+ data-hook={dataHook}
820
+ data-slot="item-link"
821
+ data-tracking-el={trackingEl}
822
+ data-tracking-label={trackingLabel}
823
+ onClickCapture={(event: React.MouseEvent<HTMLAnchorElement>) =>
824
+ blockDisabledClick(event, onClickCapture)
825
+ }
826
+ {...props}
827
+ />
828
+ );
829
+ }
830
+ );
831
+ ListItemLink.displayName = "ListItemLink";
832
+
833
+ /* -------------------------------------------------------------------------------------------------
834
+ * ListItemValue
835
+ * -----------------------------------------------------------------------------------------------*/
836
+
837
+ /** Props for ListItemValue — the current value shown at the end of a drill-down row. */
838
+ export type ListItemValueProps = React.ComponentProps<"span">;
839
+
840
+ /**
841
+ * The row's current value, before the chevron: muted, right-aligned, and cut
842
+ * off with an ellipsis past half the row so the title always keeps its room.
843
+ */
844
+ const ListItemValue = React.forwardRef<HTMLSpanElement, ListItemValueProps>(
845
+ ({ className, ...props }, ref) => (
846
+ <span
847
+ ref={ref}
848
+ className={cn(
849
+ "text-muted-foreground text-body-sm max-w-1/2 min-w-0 shrink truncate text-right",
850
+ className
851
+ )}
852
+ data-slot="item-value"
853
+ {...props}
854
+ />
855
+ )
856
+ );
857
+ ListItemValue.displayName = "ListItemValue";
858
+
859
+ /* -------------------------------------------------------------------------------------------------
860
+ * ListItemChevron
861
+ * -----------------------------------------------------------------------------------------------*/
862
+
863
+ /** Props for ListItemChevron — the trailing arrow of a row that opens something. */
864
+ export type ListItemChevronProps = React.ComponentProps<typeof ChevronRight>;
865
+
866
+ /**
867
+ * Trailing chevron for a row that navigates or drills down. Decorative: the
868
+ * row's button or link carries the meaning.
869
+ */
870
+ const ListItemChevron = React.forwardRef<SVGSVGElement, ListItemChevronProps>(
871
+ ({ className, ...props }, ref) => (
872
+ <ChevronRight
873
+ ref={ref}
874
+ aria-hidden
875
+ className={cn("text-muted-foreground shrink-0", className)}
876
+ data-slot="item-chevron"
877
+ {...props}
878
+ />
879
+ )
880
+ );
881
+ ListItemChevron.displayName = "ListItemChevron";
882
+
883
+ /* -------------------------------------------------------------------------------------------------
884
+ * ListSeparator
885
+ * -----------------------------------------------------------------------------------------------*/
886
+
887
+ /** Props for ListSeparator — a hairline between two rows or groups. */
888
+ export type ListSeparatorProps = React.ComponentProps<"li">;
889
+
890
+ /**
891
+ * A hairline between rows. Hidden from assistive tech so the list's item
892
+ * count stays the number of rows. For a line between every row, use
893
+ * `<List divided>` instead.
894
+ */
895
+ const ListSeparator = React.forwardRef<HTMLLIElement, ListSeparatorProps>(
896
+ ({ className, ...props }, ref) => (
897
+ <li
898
+ ref={ref}
899
+ aria-hidden
900
+ className={cn("bg-border h-px w-full shrink-0", className)}
901
+ data-slot="item-separator"
902
+ {...props}
903
+ />
904
+ )
905
+ );
906
+ ListSeparator.displayName = "ListSeparator";
907
+
908
+ /* -------------------------------------------------------------------------------------------------
909
+ * Exports
910
+ * -----------------------------------------------------------------------------------------------*/
911
+
912
+ /* -------------------------------------------------------------------------------------------------
913
+ * Deprecated names (removed in 4.0)
914
+ * -----------------------------------------------------------------------------------------------*/
915
+
916
+ /** @deprecated Use `ListItem`. Removed in 4.0. */
917
+ const Item = ListItem;
918
+ /** @deprecated Use `ListItemMedia`. Removed in 4.0. */
919
+ const ItemMedia = ListItemMedia;
920
+ /** @deprecated Use `ListItemContent`. Removed in 4.0. */
921
+ const ItemContent = ListItemContent;
922
+ /** @deprecated Use `ListItemTitle`. Removed in 4.0. */
923
+ const ItemTitle = ListItemTitle;
924
+ /** @deprecated Use `ListItemDescription`. Removed in 4.0. */
925
+ const ItemDescription = ListItemDescription;
926
+ /** @deprecated Use `ListItemActions`. Removed in 4.0. */
927
+ const ItemActions = ListItemActions;
928
+ /** @deprecated Use `ListSubheader`. Removed in 4.0. */
929
+ const ItemSubheader = ListSubheader;
930
+ /** @deprecated Use `listItemVariants`. Removed in 4.0. */
931
+ const itemVariants = listItemVariants;
932
+
933
+ /** @deprecated Use `ListItemProps`. Removed in 4.0. */
934
+ export type ItemProps = ListItemProps;
935
+ /** @deprecated Use `ListItemMediaProps`. Removed in 4.0. */
936
+ export type ItemMediaProps = ListItemMediaProps;
937
+ /** @deprecated Use `ListItemContentProps`. Removed in 4.0. */
938
+ export type ItemContentProps = ListItemContentProps;
939
+ /** @deprecated Use `ListItemTitleProps`. Removed in 4.0. */
940
+ export type ItemTitleProps = ListItemTitleProps;
941
+ /** @deprecated Use `ListItemDescriptionProps`. Removed in 4.0. */
942
+ export type ItemDescriptionProps = ListItemDescriptionProps;
943
+ /** @deprecated Use `ListItemActionsProps`. Removed in 4.0. */
944
+ export type ItemActionsProps = ListItemActionsProps;
945
+ /** @deprecated Use `ListSubheaderProps`. Removed in 4.0. */
946
+ export type ItemSubheaderProps = ListSubheaderProps;
351
947
 
352
948
  /* -------------------------------------------------------------------------------------------------
353
949
  * Exports
@@ -355,6 +951,21 @@ ItemSubheader.displayName = "ItemSubheader";
355
951
 
356
952
  export {
357
953
  List,
954
+ ListItem,
955
+ ListItemButton,
956
+ ListItemLink,
957
+ ListItemMedia,
958
+ ListItemContent,
959
+ ListItemTitle,
960
+ ListItemDescription,
961
+ ListItemValue,
962
+ ListItemChevron,
963
+ ListItemActions,
964
+ ListSubheader,
965
+ ListSeparator,
966
+ listVariants,
967
+ listItemVariants,
968
+ listItemMediaVariants,
358
969
  Item,
359
970
  ItemMedia,
360
971
  ItemContent,