@brightlocal/ui-components 2.8.0 → 2.9.1

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 (46) hide show
  1. package/component-meta.json +1 -1
  2. package/dist/alert.cjs +1 -1
  3. package/dist/alert.js +1 -1
  4. package/dist/blocks/sidebar.cjs +1 -1
  5. package/dist/blocks/sidebar.d.ts +39 -21
  6. package/dist/blocks/sidebar.d.ts.map +1 -1
  7. package/dist/blocks/sidebar.js +379 -425
  8. package/dist/callout.cjs +1 -1
  9. package/dist/callout.js +1 -1
  10. package/dist/card.cjs +1 -1
  11. package/dist/card.js +11 -11
  12. package/dist/combobox.cjs +3 -3
  13. package/dist/combobox.d.ts +24 -3
  14. package/dist/combobox.d.ts.map +1 -1
  15. package/dist/combobox.js +327 -302
  16. package/dist/global-layout.cjs +1 -1
  17. package/dist/global-layout.d.ts +3 -7
  18. package/dist/global-layout.d.ts.map +1 -1
  19. package/dist/global-layout.js +85 -81
  20. package/dist/hooks/use-breakpoint.cjs +1 -0
  21. package/dist/hooks/use-breakpoint.d.ts +15 -0
  22. package/dist/hooks/use-breakpoint.d.ts.map +1 -0
  23. package/dist/hooks/use-breakpoint.js +30 -0
  24. package/dist/hooks/use-mobile.d.ts +13 -3
  25. package/dist/hooks/use-mobile.d.ts.map +1 -1
  26. package/dist/index.cjs +1 -1
  27. package/dist/index.d.ts +1 -0
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +124 -121
  30. package/dist/scroll-area.cjs +1 -1
  31. package/dist/scroll-area.d.ts +5 -0
  32. package/dist/scroll-area.d.ts.map +1 -1
  33. package/dist/scroll-area.js +34 -25
  34. package/package.json +1 -1
  35. package/src/blocks/sidebar.tsx +134 -148
  36. package/src/components/alert.tsx +1 -1
  37. package/src/components/callout.tsx +1 -1
  38. package/src/components/card.tsx +1 -1
  39. package/src/components/combobox.tsx +72 -11
  40. package/src/components/global-layout.tsx +46 -45
  41. package/src/components/scroll-area.tsx +15 -1
  42. package/src/hooks/use-breakpoint.ts +58 -0
  43. package/src/hooks/use-mobile.ts +20 -40
  44. package/src/index.ts +1 -0
  45. package/dist/hooks/use-mobile.cjs +0 -1
  46. package/dist/hooks/use-mobile.js +0 -26
@@ -18,14 +18,12 @@ import { cn } from "@brightlocal/ui-components/lib/utils";
18
18
  import { Button } from "../components/button";
19
19
  import { Input } from "../components/input";
20
20
  import { Separator } from "../components/separator";
21
- import { Sheet, SheetContent } from "../components/sheet";
22
21
  import {
23
- Drawer,
24
- DrawerContent,
25
- DrawerDescription,
26
- DrawerTitle,
27
- DrawerTrigger,
28
- } from "../components/drawer";
22
+ Sheet,
23
+ SheetContent,
24
+ SheetTitle,
25
+ SheetDescription,
26
+ } from "../components/sheet";
29
27
  import {
30
28
  Accordion,
31
29
  AccordionItem,
@@ -40,7 +38,7 @@ import {
40
38
  TooltipProvider,
41
39
  TooltipTrigger,
42
40
  } from "../components/tooltip";
43
- import { useIsMobile } from "../hooks/use-mobile";
41
+ import { useIsBelowBreakpoint } from "../hooks/use-breakpoint";
44
42
 
45
43
  /**
46
44
  * Sidebar position variants
@@ -168,8 +166,8 @@ export enum SidebarCollapseIconType {
168
166
 
169
167
  const SIDEBAR_COOKIE_NAME = "sidebar:state";
170
168
  const SIDEBAR_COOKIE_MAX_AGE = 60 * 60 * 24 * 7;
171
- const SIDEBAR_WIDTH = "256px";
172
- const SIDEBAR_WIDTH_MOBILE = "288px";
169
+ const SIDEBAR_WIDTH = "224px";
170
+ const SIDEBAR_WIDTH_MOBILE = "336px";
173
171
  const SIDEBAR_WIDTH_ICON = "48px";
174
172
  const SIDEBAR_KEYBOARD_SHORTCUT = "b";
175
173
 
@@ -243,7 +241,7 @@ const SidebarProvider = React.forwardRef<HTMLDivElement, SidebarProviderProps>(
243
241
  },
244
242
  ref
245
243
  ) => {
246
- const isMobile = useIsMobile();
244
+ const isMobile = useIsBelowBreakpoint("lg");
247
245
  const [openMobile, setOpenMobile] = React.useState(false);
248
246
 
249
247
  // Internal state for uncontrolled usage
@@ -368,11 +366,20 @@ interface SidebarProps extends React.ComponentProps<"div"> {
368
366
  */
369
367
  collapsible?: SidebarCollapsible;
370
368
  /**
371
- * Render in flow layout instead of fixed positioning.
372
- * Use when the Sidebar is placed inside a layout container (e.g. GlobalLayout).
373
- * Mobile rendering (Sheet) is skipped — handle mobile navigation separately with Drawer.
369
+ * @deprecated No longer needed. The Sidebar now always uses inline layout
370
+ * for desktop and Sheet overlay for mobile. Remove this prop.
374
371
  */
375
372
  embedded?: boolean;
373
+ /**
374
+ * Accessible title for the mobile sheet overlay
375
+ * @default "Navigation"
376
+ */
377
+ mobileTitle?: string;
378
+ /**
379
+ * Accessible description for the mobile sheet overlay
380
+ * @default "Main navigation menu"
381
+ */
382
+ mobileDescription?: string;
376
383
  }
377
384
 
378
385
  const Sidebar = React.forwardRef<HTMLDivElement, SidebarProps>(
@@ -384,7 +391,10 @@ const Sidebar = React.forwardRef<HTMLDivElement, SidebarProps>(
384
391
  side = SidebarSide.LEFT,
385
392
  variant = SidebarVariant.SIDEBAR,
386
393
  collapsible = SidebarCollapsible.OFFCANVAS,
387
- embedded = false,
394
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars -- accepted for backward compat
395
+ embedded,
396
+ mobileTitle = "Navigation",
397
+ mobileDescription = "Main navigation menu",
388
398
  className,
389
399
  children,
390
400
  ...props
@@ -398,7 +408,7 @@ const Sidebar = React.forwardRef<HTMLDivElement, SidebarProps>(
398
408
  <div
399
409
  ref={ref}
400
410
  className={cn(
401
- "bg-sidebar text-sidebar-foreground flex h-full w-[var(--sidebar-width)] flex-col",
411
+ "text-sidebar-foreground flex h-full w-[var(--sidebar-width)] flex-col",
402
412
  className
403
413
  )}
404
414
  data-hook={dataHook}
@@ -412,51 +422,25 @@ const Sidebar = React.forwardRef<HTMLDivElement, SidebarProps>(
412
422
  );
413
423
  }
414
424
 
415
- if (embedded) {
416
- return (
417
- <div
418
- ref={ref}
419
- className={cn(
420
- "group bg-sidebar text-sidebar-foreground flex h-full shrink-0 flex-col overflow-hidden transition-[width] duration-200 ease-linear",
421
- state === "expanded" && "w-[var(--sidebar-width)]",
422
- collapsible === SidebarCollapsible.ICON &&
423
- state === "collapsed" &&
424
- "w-[var(--sidebar-width-icon)]",
425
- collapsible === SidebarCollapsible.OFFCANVAS &&
426
- state === "collapsed" &&
427
- "w-0",
428
- className
429
- )}
430
- data-collapsible={state === "collapsed" ? collapsible : ""}
431
- data-hook={dataHook}
432
- data-side={side}
433
- data-slot="sidebar"
434
- data-state={state}
435
- data-tracking-el={trackingEl || "sidebar"}
436
- data-tracking-label={trackingLabel}
437
- data-variant={variant}
438
- {...props}
439
- >
440
- {children}
441
- </div>
442
- );
443
- }
444
-
445
425
  if (isMobile) {
446
426
  return (
447
427
  <Sheet open={openMobile} onOpenChange={setOpenMobile}>
448
428
  <SheetContent
449
- className="bg-sidebar text-sidebar-foreground w-[var(--sidebar-width)] p-0 [&>button]:hidden"
429
+ className="bg-sidebar-background text-sidebar-foreground w-[var(--sidebar-width)] p-6"
450
430
  data-hook={`${dataHook}-mobile-content`}
451
431
  data-mobile="true"
452
432
  data-sidebar="sidebar"
453
433
  side="left"
454
434
  style={
455
435
  {
456
- "--sidebar-width": SIDEBAR_WIDTH_MOBILE,
436
+ "--sidebar-width": `min(${SIDEBAR_WIDTH_MOBILE}, calc(100vw - 40px))`,
457
437
  } as React.CSSProperties
458
438
  }
459
439
  >
440
+ <SheetTitle className="sr-only">{mobileTitle}</SheetTitle>
441
+ <SheetDescription className="sr-only">
442
+ {mobileDescription}
443
+ </SheetDescription>
460
444
  <div className="flex h-full w-full flex-col">{children}</div>
461
445
  </SheetContent>
462
446
  </Sheet>
@@ -466,7 +450,17 @@ const Sidebar = React.forwardRef<HTMLDivElement, SidebarProps>(
466
450
  return (
467
451
  <div
468
452
  ref={ref}
469
- className="group peer text-sidebar-foreground hidden md:block"
453
+ className={cn(
454
+ "group text-sidebar-foreground flex h-full shrink-0 flex-col overflow-hidden transition-[width] duration-200 ease-linear",
455
+ state === "expanded" && "w-[var(--sidebar-width)]",
456
+ collapsible === SidebarCollapsible.ICON &&
457
+ state === "collapsed" &&
458
+ "w-[var(--sidebar-width-icon)]",
459
+ collapsible === SidebarCollapsible.OFFCANVAS &&
460
+ state === "collapsed" &&
461
+ "w-0",
462
+ className
463
+ )}
470
464
  data-collapsible={state === "collapsed" ? collapsible : ""}
471
465
  data-hook={dataHook}
472
466
  data-side={side}
@@ -475,31 +469,9 @@ const Sidebar = React.forwardRef<HTMLDivElement, SidebarProps>(
475
469
  data-tracking-el={trackingEl || "sidebar"}
476
470
  data-tracking-label={trackingLabel}
477
471
  data-variant={variant}
472
+ {...props}
478
473
  >
479
- {/* Desktop sidebar */}
480
- <div
481
- className={cn(
482
- "relative h-svh w-[var(--sidebar-width)] bg-transparent transition-[width] duration-200 ease-linear",
483
- "group-data-[collapsible=offcanvas]:w-0",
484
- "group-data-[collapsible=icon]:w-[var(--sidebar-width-icon)]"
485
- )}
486
- />
487
- <div
488
- className={cn(
489
- "fixed inset-y-0 z-10 hidden h-svh w-[var(--sidebar-width)] transition-[left,right,width] duration-200 ease-linear md:flex",
490
- "left-0 group-data-[collapsible=offcanvas]:left-[calc(var(--sidebar-width)*-1)]",
491
- "group-data-[collapsible=icon]:w-[var(--sidebar-width-icon)]",
492
- className
493
- )}
494
- {...props}
495
- >
496
- <div
497
- className="bg-sidebar flex h-full w-full flex-col"
498
- data-sidebar="sidebar"
499
- >
500
- {children}
501
- </div>
502
- </div>
474
+ {children}
503
475
  </div>
504
476
  );
505
477
  }
@@ -523,29 +495,35 @@ interface SidebarTriggerProps extends Omit<
523
495
  const SidebarTrigger = React.forwardRef<
524
496
  React.ElementRef<typeof Button>,
525
497
  SidebarTriggerProps
526
- >(({ className, onClick, dataHook = "sidebar-trigger", ...props }, ref) => {
527
- const { toggleSidebar } = useSidebar();
498
+ >(
499
+ (
500
+ { className, onClick, dataHook = "sidebar-trigger", children, ...props },
501
+ ref
502
+ ) => {
503
+ const { toggleSidebar } = useSidebar();
528
504
 
529
- return (
530
- <Button
531
- ref={ref}
532
- aria-label="Toggle Sidebar"
533
- className={cn("h-7 w-7", className)}
534
- data-slot="sidebar-trigger"
535
- dataHook={dataHook}
536
- size="sm"
537
- variant="ghost"
538
- onClick={(event) => {
539
- onClick?.(event);
540
- toggleSidebar();
541
- }}
542
- {...props}
543
- >
544
- <PanelLeft />
545
- <span className="sr-only">Toggle Sidebar</span>
546
- </Button>
547
- );
548
- });
505
+ return (
506
+ <Button
507
+ ref={ref}
508
+ iconOnly
509
+ aria-label="Toggle Sidebar"
510
+ className={cn("h-7 w-7", className)}
511
+ data-slot="sidebar-trigger"
512
+ dataHook={dataHook}
513
+ size="sm"
514
+ variant="ghost"
515
+ onClick={(event) => {
516
+ onClick?.(event);
517
+ toggleSidebar();
518
+ }}
519
+ {...props}
520
+ >
521
+ {children || <PanelLeft />}
522
+ <span className="sr-only">Toggle Sidebar</span>
523
+ </Button>
524
+ );
525
+ }
526
+ );
549
527
  SidebarTrigger.displayName = "SidebarTrigger";
550
528
 
551
529
  /**
@@ -565,7 +543,7 @@ const SidebarRail = React.forwardRef<HTMLButtonElement, SidebarRailProps>(
565
543
  "hover:after:bg-sidebar-border absolute inset-y-0 -right-4 z-20 hidden w-4 -translate-x-1/2 transition-transform ease-linear after:absolute after:inset-y-0 after:left-1/2 after:w-[2px] sm:flex",
566
544
  "cursor-w-resize",
567
545
  "[[data-state=collapsed]_&]:cursor-e-resize",
568
- "group-data-[collapsible=offcanvas]:hover:bg-sidebar group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full",
546
+ "group-data-[collapsible=offcanvas]:hover:bg-sidebar-background group-data-[collapsible=offcanvas]:translate-x-0 group-data-[collapsible=offcanvas]:after:left-full",
569
547
  "[[data-collapsible=offcanvas]_&]:-right-2",
570
548
  className
571
549
  )}
@@ -657,7 +635,10 @@ const SidebarHeader = React.forwardRef<HTMLDivElement, SidebarHeaderProps>(
657
635
  return (
658
636
  <div
659
637
  ref={ref}
660
- className={cn("px-section-xs flex flex-col gap-2 pt-2 pb-9", className)}
638
+ className={cn(
639
+ "pr-section-xs flex flex-col gap-2 pt-2 pb-9 pl-8",
640
+ className
641
+ )}
661
642
  data-hook={dataHook}
662
643
  data-slot="sidebar-header"
663
644
  {...props}
@@ -727,6 +708,7 @@ interface SidebarContentProps extends Omit<React.ComponentProps<"div">, "dir"> {
727
708
 
728
709
  const SidebarContent = React.forwardRef<HTMLDivElement, SidebarContentProps>(
729
710
  ({ className, dataHook, ariaLabel = "Sidebar", children, ...props }, ref) => {
711
+ const { isMobile } = useSidebar();
730
712
  return (
731
713
  <ScrollArea
732
714
  ref={ref}
@@ -735,6 +717,7 @@ const SidebarContent = React.forwardRef<HTMLDivElement, SidebarContentProps>(
735
717
  className
736
718
  )}
737
719
  dataHook={dataHook ?? "sidebar-content-scroll"}
720
+ scrollOrientation={isMobile ? "both" : "vertical"}
738
721
  {...props}
739
722
  >
740
723
  <nav
@@ -1083,7 +1066,7 @@ const sidebarMenuButtonVariants = cva(
1083
1066
  badge: "group-has-[[data-sidebar=menu-badge]]/menu-item:pr-16",
1084
1067
  // Big Icon - larger icon with title and subtitle
1085
1068
  bigIcon:
1086
- "h-auto flex-col items-start gap-1 rounded-lg p-3 [&>svg]:size-6 [&>svg]:rounded-md [&>svg]:bg-sidebar-foreground [&>svg]:p-1 [&>svg]:text-sidebar [&>svg]:opacity-100 hover:[&>svg]:bg-sidebar-foreground hover:[&>svg]:text-sidebar group-data-[collapsible=icon]:!size-10 group-data-[collapsible=icon]:!p-2 group-data-[collapsible=icon]:items-center group-data-[collapsible=icon]:[&>svg]:size-6",
1069
+ "h-auto flex-col items-start gap-1 rounded-lg p-3 [&>svg]:size-6 [&>svg]:rounded-md [&>svg]:bg-sidebar-foreground [&>svg]:p-1 [&>svg]:text-sidebar-background [&>svg]:opacity-100 hover:[&>svg]:bg-sidebar-foreground hover:[&>svg]:text-sidebar-background group-data-[collapsible=icon]:!size-10 group-data-[collapsible=icon]:!p-2 group-data-[collapsible=icon]:items-center group-data-[collapsible=icon]:[&>svg]:size-6",
1087
1070
  // Checkbox - has a checkbox indicator
1088
1071
  checkbox:
1089
1072
  "[&>[data-checkbox]]:size-4 [&>[data-checkbox]]:shrink-0 [&>[data-checkbox]]:rounded [&>[data-checkbox]]:border [&>[data-checkbox]]:border-sidebar-foreground/30 data-[checked=true]:[&>[data-checkbox]]:bg-primary data-[checked=true]:[&>[data-checkbox]]:border-primary data-[checked=true]:[&>[data-checkbox]]:text-primary-foreground",
@@ -1557,24 +1540,19 @@ const SidebarMenuCollapsibleContent = React.forwardRef<
1557
1540
  SidebarMenuCollapsibleContent.displayName = "SidebarMenuCollapsibleContent";
1558
1541
 
1559
1542
  /* -------------------------------------------------------------------------------------------------
1560
- * SidebarDrawer (Mobile navigation drawer with burger trigger)
1543
+ * SidebarDrawer (DEPRECATED — use SidebarTrigger instead)
1561
1544
  * -----------------------------------------------------------------------------------------------*/
1562
1545
 
1546
+ /**
1547
+ * Props for the SidebarDrawer component
1548
+ * @deprecated Use `SidebarTrigger` instead. SidebarDrawer will be removed in the next major version.
1549
+ */
1563
1550
  interface SidebarDrawerProps extends React.ComponentProps<"div"> {
1564
1551
  /**
1565
- * Data hook for automated testing (required)
1566
- */
1567
- dataHook: string;
1568
- /**
1569
- * Accessible label for the drawer
1570
- * @default "Navigation"
1571
- */
1572
- title?: string;
1573
- /**
1574
- * Accessible description for the drawer
1575
- * @default "Main navigation menu"
1552
+ * Data hook for automated testing
1553
+ * @default "sidebar-drawer"
1576
1554
  */
1577
- description?: string;
1555
+ dataHook?: string;
1578
1556
  /**
1579
1557
  * Tracking element identifier for analytics
1580
1558
  */
@@ -1585,51 +1563,58 @@ interface SidebarDrawerProps extends React.ComponentProps<"div"> {
1585
1563
  trackingLabel?: string;
1586
1564
  }
1587
1565
 
1588
- function SidebarDrawer({
1589
- dataHook,
1590
- title = "Navigation",
1591
- description = "Main navigation menu",
1592
- trackingEl,
1593
- trackingLabel,
1594
- children,
1595
- className,
1596
- ...props
1597
- }: SidebarDrawerProps) {
1598
- return (
1599
- <Drawer direction="left">
1600
- <DrawerTrigger asChild>
1601
- <Button
1602
- iconOnly
1603
- aria-label="Open menu"
1604
- dataHook={`${dataHook}-trigger`}
1605
- size="sm"
1606
- trackingEl={trackingEl}
1607
- trackingLabel={trackingLabel}
1608
- variant="ghost"
1609
- >
1610
- <Menu size={24} />
1611
- </Button>
1612
- </DrawerTrigger>
1613
- <DrawerContent
1614
- className={cn("max-w-96", className)}
1615
- dataHook={dataHook}
1566
+ /**
1567
+ * @deprecated Use `SidebarTrigger` with custom children instead.
1568
+ *
1569
+ * ```tsx
1570
+ * // Before
1571
+ * <SidebarDrawer dataHook="mobile-nav" />
1572
+ *
1573
+ * // After
1574
+ * <SidebarTrigger dataHook="mobile-nav">
1575
+ * <Menu size={24} />
1576
+ * </SidebarTrigger>
1577
+ * ```
1578
+ */
1579
+ const SidebarDrawer = React.forwardRef<HTMLDivElement, SidebarDrawerProps>(
1580
+ (
1581
+ {
1582
+ className,
1583
+ dataHook = "sidebar-drawer",
1584
+ trackingEl,
1585
+ trackingLabel,
1586
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars -- accepted for backward compat
1587
+ children,
1588
+ ...props
1589
+ },
1590
+ ref
1591
+ ) => {
1592
+ return (
1593
+ <div
1594
+ ref={ref}
1595
+ className={className}
1596
+ data-hook={dataHook}
1597
+ data-slot="sidebar-drawer"
1598
+ data-tracking-el={trackingEl}
1599
+ data-tracking-label={trackingLabel}
1616
1600
  {...props}
1617
1601
  >
1618
- <DrawerTitle className="sr-only">{title}</DrawerTitle>
1619
- <DrawerDescription className="sr-only">{description}</DrawerDescription>
1620
- <div className="flex h-full flex-col p-6">{children}</div>
1621
- </DrawerContent>
1622
- </Drawer>
1623
- );
1624
- }
1602
+ <SidebarTrigger dataHook={`${dataHook}-trigger`}>
1603
+ <Menu size={24} />
1604
+ </SidebarTrigger>
1605
+ </div>
1606
+ );
1607
+ }
1608
+ );
1625
1609
  SidebarDrawer.displayName = "SidebarDrawer";
1626
1610
 
1627
1611
  // Component exports
1628
1612
  export {
1629
1613
  Sidebar,
1630
1614
  SidebarCollapseIcon,
1631
- SidebarContent,
1615
+ /** @deprecated Use `SidebarTrigger` instead */
1632
1616
  SidebarDrawer,
1617
+ SidebarContent,
1633
1618
  SidebarFooter,
1634
1619
  SidebarGroup,
1635
1620
  SidebarGroupAction,
@@ -1661,6 +1646,8 @@ export {
1661
1646
  export type {
1662
1647
  SidebarProviderProps,
1663
1648
  SidebarProps,
1649
+ /** @deprecated Use `SidebarTriggerProps` instead */
1650
+ SidebarDrawerProps,
1664
1651
  SidebarTriggerProps,
1665
1652
  SidebarRailProps,
1666
1653
  SidebarInsetProps,
@@ -1669,7 +1656,6 @@ export type {
1669
1656
  SidebarFooterProps,
1670
1657
  SidebarSeparatorProps,
1671
1658
  SidebarContentProps,
1672
- SidebarDrawerProps,
1673
1659
  SidebarGroupProps,
1674
1660
  SidebarGroupLabelProps,
1675
1661
  SidebarGroupActionProps,
@@ -63,7 +63,7 @@ const AlertDescription = React.forwardRef<
63
63
  >(({ className, ...props }, ref) => (
64
64
  <div
65
65
  ref={ref}
66
- className={cn("text-sm leading-5 [&_p]:leading-5", className)}
66
+ className={cn("text-sm leading-5 font-normal [&_p]:leading-5", className)}
67
67
  data-slot="alert-description"
68
68
  {...props}
69
69
  />
@@ -133,7 +133,7 @@ const CalloutHeading = React.forwardRef<HTMLDivElement, CalloutHeadingProps>(
133
133
  ({ className, dataHook, ...props }, ref) => (
134
134
  <div
135
135
  ref={ref}
136
- className={cn("heading-lg font-semibold", className)}
136
+ className={cn("font-display text-4xl font-semibold", className)}
137
137
  data-hook={dataHook}
138
138
  data-slot="callout-heading"
139
139
  {...props}
@@ -168,7 +168,7 @@ const CardTitle = React.forwardRef<HTMLDivElement, CardSubComponentProps>(
168
168
  ({ className, ...props }, ref) => (
169
169
  <div
170
170
  ref={ref}
171
- className={cn("heading-sm", className)}
171
+ className={cn("font-display text-2xl font-medium", className)}
172
172
  data-slot="card-title"
173
173
  {...props}
174
174
  />
@@ -37,6 +37,8 @@ interface ComboboxContextValue {
37
37
  /** Map of value -> label for displaying selected value */
38
38
  itemLabels: Map<string, string>;
39
39
  registerItem: (value: string, label: string) => void;
40
+ /** Bulk-register items and flush state synchronously (no microtask). Use inside useLayoutEffect to avoid flash of unresolved labels. */
41
+ registerItemsSync: (entries: Iterable<[string, string]>) => void;
40
42
  /** Remove an item from the label map (called on unmount to prevent stale entries) */
41
43
  unregisterItem: (value: string) => void;
42
44
  /** Maps item value to a searchable string for filtering */
@@ -229,6 +231,16 @@ function Combobox({
229
231
  [scheduleMicrotaskFlush]
230
232
  );
231
233
 
234
+ const registerItemsSync = React.useCallback(
235
+ (entries: Iterable<[string, string]>) => {
236
+ for (const [itemValue, label] of entries) {
237
+ itemLabelsRef.current.set(itemValue, label);
238
+ }
239
+ setItemLabels(new Map(itemLabelsRef.current));
240
+ },
241
+ []
242
+ );
243
+
232
244
  // Track the current value in a ref so unregisterItem can read it without
233
245
  // adding `value` as a dependency (which would break callback identity).
234
246
  // useLayoutEffect runs before passive-effect cleanups, so the ref is
@@ -272,6 +284,7 @@ function Combobox({
272
284
  disabled,
273
285
  itemLabels,
274
286
  registerItem,
287
+ registerItemsSync,
275
288
  unregisterItem,
276
289
  itemToStringValue,
277
290
  filterFn,
@@ -289,6 +302,7 @@ function Combobox({
289
302
  disabled,
290
303
  itemLabels,
291
304
  registerItem,
305
+ registerItemsSync,
292
306
  unregisterItem,
293
307
  itemToStringValue,
294
308
  filterFn,
@@ -426,7 +440,7 @@ ComboboxTrigger.displayName = "ComboboxTrigger";
426
440
  * Combobox Value
427
441
  * -----------------------------------------------------------------------------------------------*/
428
442
 
429
- export interface ComboboxValueProps {
443
+ export interface ComboboxValueProps<T = unknown> {
430
444
  /** Placeholder text when no value is selected */
431
445
  placeholder?: string;
432
446
  /** Custom className */
@@ -445,16 +459,59 @@ export interface ComboboxValueProps {
445
459
  * ```
446
460
  */
447
461
  displayValue?: (value: string) => string | undefined;
462
+ /**
463
+ * Items array for auto-resolving display labels. When provided alongside
464
+ * `getItemValue` (and optionally `getItemLabel`), ComboboxValue builds an
465
+ * internal lookup map — eliminating the need for a manual `displayValue`
466
+ * callback. Typically the same array passed to `ComboboxVirtualList`.
467
+ *
468
+ * @example
469
+ * ```tsx
470
+ * <ComboboxValue
471
+ * placeholder="Select country..."
472
+ * items={countries}
473
+ * getItemValue={(c) => c.code}
474
+ * getItemLabel={(c) => c.name}
475
+ * />
476
+ * ```
477
+ */
478
+ items?: readonly T[];
479
+ /** Extract the value string from an item. Required when `items` is provided. */
480
+ getItemValue?: (item: T) => string;
481
+ /** Extract the display label from an item. Falls back to `getItemValue` when not provided. */
482
+ getItemLabel?: (item: T) => string;
448
483
  }
449
484
 
450
- function ComboboxValue({
485
+ function ComboboxValue<T>({
451
486
  placeholder,
452
487
  className,
453
488
  displayValue,
454
- }: ComboboxValueProps) {
489
+ items,
490
+ getItemValue,
491
+ getItemLabel,
492
+ }: ComboboxValueProps<T>) {
455
493
  const { value, itemLabels } = useComboboxContext();
494
+
495
+ useDevWarning(
496
+ () => !!items && !getItemValue,
497
+ "ComboboxValue: `items` was provided without `getItemValue`. " +
498
+ "Pass `getItemValue` (and optionally `getItemLabel`) to enable item-based label resolution.",
499
+ [items, getItemValue]
500
+ );
501
+
502
+ const itemsMap = React.useMemo(() => {
503
+ if (!items || !getItemValue) return null;
504
+ const resolveLabel = getItemLabel ?? getItemValue;
505
+ return new Map(
506
+ items.map((item) => [getItemValue(item), resolveLabel(item)])
507
+ );
508
+ }, [items, getItemValue, getItemLabel]);
509
+
456
510
  const displayText = value
457
- ? itemLabels.get(value) || displayValue?.(value) || value
511
+ ? itemsMap?.get(value) ||
512
+ itemLabels.get(value) ||
513
+ displayValue?.(value) ||
514
+ value
458
515
  : placeholder;
459
516
 
460
517
  return (
@@ -758,7 +815,7 @@ ComboboxList.displayName = "ComboboxList";
758
815
 
759
816
  export interface ComboboxVirtualListProps<T> {
760
817
  /** Array of items to virtualise. Memoize with useMemo to avoid re-registering labels on every render. */
761
- items: T[];
818
+ items: readonly T[];
762
819
  /** Extract the string value for each item (used for selection and keyboard navigation) */
763
820
  getItemValue: (item: T) => string;
764
821
  /**
@@ -823,7 +880,7 @@ function ComboboxVirtualListInner<T>(
823
880
  searchValue,
824
881
  filterFn,
825
882
  setActiveDescendantId,
826
- registerItem,
883
+ registerItemsSync,
827
884
  unregisterItem,
828
885
  } = useComboboxContext();
829
886
  const [activeIndex, setActiveIndex] = React.useState(0);
@@ -834,20 +891,24 @@ function ComboboxVirtualListInner<T>(
834
891
 
835
892
  // Bulk-register all item labels upfront so ComboboxValue can always resolve
836
893
  // the display label — even for items outside the virtualised viewport.
894
+ // Uses useLayoutEffect + synchronous flush so labels are available before
895
+ // the browser paints (no flash of raw values when a value is pre-selected).
837
896
  // Cleanup unregisters stale labels when `items` changes (e.g. server-driven
838
897
  // filtering/pagination). The selected value's label survives because
839
898
  // unregisterItem has a guard that preserves the currently selected value.
840
- React.useEffect(() => {
899
+ React.useLayoutEffect(() => {
841
900
  const resolveLabel = getItemLabel ?? getItemValue;
842
- for (const item of items) {
843
- registerItem(getItemValue(item), resolveLabel(item));
844
- }
901
+ const entries: [string, string][] = items.map((item) => [
902
+ getItemValue(item),
903
+ resolveLabel(item),
904
+ ]);
905
+ registerItemsSync(entries);
845
906
  return () => {
846
907
  for (const item of items) {
847
908
  unregisterItem(getItemValue(item));
848
909
  }
849
910
  };
850
- }, [items, getItemValue, getItemLabel, registerItem, unregisterItem]);
911
+ }, [items, getItemValue, getItemLabel, registerItemsSync, unregisterItem]);
851
912
 
852
913
  // Filter AND rank items by score — same behaviour as cmdk's scoring system.
853
914
  // Items with higher match scores appear first, so ordering is consistent