@brightlocal/ui-components 2.10.0 → 2.12.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 (163) hide show
  1. package/README.md +3 -1
  2. package/component-meta.json +200 -17
  3. package/dist/badge.cjs +1 -1
  4. package/dist/badge.d.ts.map +1 -1
  5. package/dist/badge.js +42 -25
  6. package/dist/blocks/data-table.cjs +1 -1
  7. package/dist/blocks/data-table.d.ts +16 -4
  8. package/dist/blocks/data-table.d.ts.map +1 -1
  9. package/dist/blocks/data-table.js +57 -53
  10. package/dist/blocks/input-list.cjs +2 -2
  11. package/dist/blocks/input-list.d.ts +7 -1
  12. package/dist/blocks/input-list.d.ts.map +1 -1
  13. package/dist/blocks/input-list.js +82 -81
  14. package/dist/blocks/sidebar.cjs +1 -1
  15. package/dist/blocks/sidebar.d.ts +19 -10
  16. package/dist/blocks/sidebar.d.ts.map +1 -1
  17. package/dist/blocks/sidebar.js +173 -169
  18. package/dist/breadcrumb.cjs +1 -1
  19. package/dist/breadcrumb.d.ts +14 -2
  20. package/dist/breadcrumb.d.ts.map +1 -1
  21. package/dist/breadcrumb.js +37 -37
  22. package/dist/button.cjs +1 -1
  23. package/dist/button.js +25 -25
  24. package/dist/callout.cjs +1 -1
  25. package/dist/callout.d.ts +3 -3
  26. package/dist/callout.d.ts.map +1 -1
  27. package/dist/callout.js +2 -1
  28. package/dist/card.cjs +1 -1
  29. package/dist/card.d.ts +10 -1
  30. package/dist/card.d.ts.map +1 -1
  31. package/dist/card.js +85 -82
  32. package/dist/carousel.cjs +1 -1
  33. package/dist/carousel.d.ts +37 -4
  34. package/dist/carousel.d.ts.map +1 -1
  35. package/dist/carousel.js +213 -163
  36. package/dist/chip.cjs +1 -1
  37. package/dist/chip.d.ts +11 -0
  38. package/dist/chip.d.ts.map +1 -1
  39. package/dist/chip.js +43 -38
  40. package/dist/combobox.cjs +3 -3
  41. package/dist/combobox.d.ts +12 -2
  42. package/dist/combobox.d.ts.map +1 -1
  43. package/dist/combobox.js +235 -230
  44. package/dist/command.cjs +1 -1
  45. package/dist/command.d.ts +106 -1
  46. package/dist/command.d.ts.map +1 -1
  47. package/dist/command.js +385 -120
  48. package/dist/date-picker.cjs +1 -1
  49. package/dist/date-picker.d.ts +10 -0
  50. package/dist/date-picker.d.ts.map +1 -1
  51. package/dist/date-picker.js +96 -96
  52. package/dist/dialog.cjs +1 -1
  53. package/dist/dialog.d.ts +7 -2
  54. package/dist/dialog.d.ts.map +1 -1
  55. package/dist/dialog.js +38 -30
  56. package/dist/drawer.d.ts +2 -2
  57. package/dist/global-layout.cjs +1 -1
  58. package/dist/global-layout.d.ts +5 -0
  59. package/dist/global-layout.d.ts.map +1 -1
  60. package/dist/global-layout.js +15 -7
  61. package/dist/hooks/use-breakpoint.cjs +1 -1
  62. package/dist/hooks/use-breakpoint.d.ts.map +1 -1
  63. package/dist/hooks/use-breakpoint.js +10 -10
  64. package/dist/index.cjs +1 -1
  65. package/dist/index.d.ts +1 -0
  66. package/dist/index.d.ts.map +1 -1
  67. package/dist/index.js +406 -395
  68. package/dist/input-chip.cjs +1 -1
  69. package/dist/input-chip.d.ts +8 -5
  70. package/dist/input-chip.d.ts.map +1 -1
  71. package/dist/input-chip.js +164 -170
  72. package/dist/input-group.d.ts +1 -1
  73. package/dist/input-password.cjs +1 -1
  74. package/dist/input-password.d.ts +10 -0
  75. package/dist/input-password.d.ts.map +1 -1
  76. package/dist/input-password.js +108 -106
  77. package/dist/link.cjs +1 -1
  78. package/dist/link.d.ts +1 -1
  79. package/dist/link.d.ts.map +1 -1
  80. package/dist/link.js +36 -37
  81. package/dist/list.d.ts +1 -1
  82. package/dist/logo.cjs +1 -1
  83. package/dist/logo.d.ts +6 -1
  84. package/dist/logo.d.ts.map +1 -1
  85. package/dist/logo.js +25 -22
  86. package/dist/map.cjs +1 -0
  87. package/dist/map.d.ts +207 -0
  88. package/dist/map.d.ts.map +1 -0
  89. package/dist/map.js +256 -0
  90. package/dist/pagination.cjs +1 -1
  91. package/dist/pagination.d.ts +29 -3
  92. package/dist/pagination.d.ts.map +1 -1
  93. package/dist/pagination.js +26 -25
  94. package/dist/rating.cjs +1 -1
  95. package/dist/rating.d.ts +6 -0
  96. package/dist/rating.d.ts.map +1 -1
  97. package/dist/rating.js +27 -19
  98. package/dist/resizable.d.ts +1 -1
  99. package/dist/select.cjs +2 -2
  100. package/dist/select.d.ts +7 -1
  101. package/dist/select.d.ts.map +1 -1
  102. package/dist/select.js +52 -51
  103. package/dist/separator.cjs +1 -1
  104. package/dist/separator.d.ts +16 -4
  105. package/dist/separator.d.ts.map +1 -1
  106. package/dist/separator.js +38 -35
  107. package/dist/sheet.cjs +1 -1
  108. package/dist/sheet.d.ts +6 -1
  109. package/dist/sheet.d.ts.map +1 -1
  110. package/dist/sheet.js +42 -41
  111. package/dist/skeleton.cjs +1 -1
  112. package/dist/skeleton.d.ts +5 -0
  113. package/dist/skeleton.d.ts.map +1 -1
  114. package/dist/skeleton.js +13 -11
  115. package/dist/sonner.cjs +1 -1
  116. package/dist/sonner.d.ts.map +1 -1
  117. package/dist/sonner.js +32 -30
  118. package/dist/tabs.cjs +1 -1
  119. package/dist/tabs.d.ts +4 -0
  120. package/dist/tabs.d.ts.map +1 -1
  121. package/dist/tabs.js +101 -52
  122. package/dist/text-reveal-motion.cjs +1 -1
  123. package/dist/text-reveal-motion.d.ts +5 -0
  124. package/dist/text-reveal-motion.d.ts.map +1 -1
  125. package/dist/text-reveal-motion.js +111 -110
  126. package/dist/typography.cjs +1 -1
  127. package/dist/typography.d.ts +1 -2
  128. package/dist/typography.d.ts.map +1 -1
  129. package/dist/typography.js +49 -50
  130. package/package.json +4 -5
  131. package/src/blocks/data-table.tsx +26 -9
  132. package/src/blocks/input-list.tsx +12 -1
  133. package/src/blocks/sidebar.tsx +61 -44
  134. package/src/components/badge.tsx +22 -5
  135. package/src/components/breadcrumb.tsx +43 -26
  136. package/src/components/button.tsx +13 -13
  137. package/src/components/callout.tsx +5 -4
  138. package/src/components/card.tsx +35 -19
  139. package/src/components/carousel.tsx +134 -13
  140. package/src/components/chip.tsx +22 -2
  141. package/src/components/combobox.tsx +18 -3
  142. package/src/components/command.tsx +644 -17
  143. package/src/components/date-picker.tsx +17 -3
  144. package/src/components/dialog.tsx +17 -4
  145. package/src/components/drawer.tsx +2 -2
  146. package/src/components/global-layout.tsx +15 -2
  147. package/src/components/input-chip.tsx +114 -66
  148. package/src/components/input-password.tsx +73 -49
  149. package/src/components/link.tsx +29 -17
  150. package/src/components/logo.tsx +10 -2
  151. package/src/components/map.tsx +597 -0
  152. package/src/components/pagination.tsx +44 -11
  153. package/src/components/rating.tsx +20 -2
  154. package/src/components/select.tsx +9 -1
  155. package/src/components/separator.tsx +40 -25
  156. package/src/components/sheet.tsx +28 -20
  157. package/src/components/skeleton.tsx +13 -2
  158. package/src/components/sonner.tsx +9 -3
  159. package/src/components/tabs.tsx +118 -22
  160. package/src/components/text-reveal-motion.tsx +7 -1
  161. package/src/components/typography.tsx +6 -7
  162. package/src/hooks/use-breakpoint.ts +2 -3
  163. package/src/index.ts +1 -0
@@ -2,10 +2,41 @@
2
2
 
3
3
  import * as React from "react";
4
4
  import { Command as CommandPrimitive } from "cmdk";
5
+ import { defaultFilter } from "cmdk";
6
+ import { useVirtualizer } from "@tanstack/react-virtual";
5
7
  import { Check, Search, X } from "@brightlocal/icons";
6
8
 
7
9
  import { Button } from "@brightlocal/ui-components/button";
8
10
  import { cn } from "@brightlocal/ui-components/lib/utils";
11
+ import { useDevWarning } from "@brightlocal/ui-components/lib/use-dev-warning";
12
+
13
+ /* -------------------------------------------------------------------------------------------------
14
+ * Command Context — shared state between CommandInput and CommandVirtualList
15
+ * -----------------------------------------------------------------------------------------------*/
16
+
17
+ interface CommandContextValue {
18
+ searchValue: string;
19
+ setSearchValue: (value: string) => void;
20
+ activeDescendantId: string | undefined;
21
+ setActiveDescendantId: React.Dispatch<
22
+ React.SetStateAction<string | undefined>
23
+ >;
24
+ listboxId: string | undefined;
25
+ setListboxId: React.Dispatch<React.SetStateAction<string | undefined>>;
26
+ }
27
+
28
+ const CommandContext = React.createContext<CommandContextValue>({
29
+ searchValue: "",
30
+ setSearchValue: () => {},
31
+ activeDescendantId: undefined,
32
+ setActiveDescendantId: () => {},
33
+ listboxId: undefined,
34
+ setListboxId: () => {},
35
+ });
36
+
37
+ /* -------------------------------------------------------------------------------------------------
38
+ * Command
39
+ * -----------------------------------------------------------------------------------------------*/
9
40
 
10
41
  /**
11
42
  * Props for the Command component
@@ -34,22 +65,49 @@ export interface CommandProps extends React.ComponentProps<
34
65
  const Command = React.forwardRef<
35
66
  React.ComponentRef<typeof CommandPrimitive>,
36
67
  CommandProps
37
- >(({ className, dataHook, trackingEl, trackingLabel, ...props }, ref) => (
38
- <CommandPrimitive
39
- ref={ref}
40
- className={cn(
41
- "bg-popover text-popover-foreground flex w-full flex-col overflow-hidden rounded-lg border shadow-md",
42
- className
43
- )}
44
- data-hook={dataHook}
45
- data-slot="command"
46
- data-tracking-el={trackingEl}
47
- data-tracking-label={trackingLabel}
48
- {...props}
49
- />
50
- ));
68
+ >(({ className, dataHook, trackingEl, trackingLabel, ...props }, ref) => {
69
+ const [searchValue, setSearchValue] = React.useState("");
70
+ const [activeDescendantId, setActiveDescendantId] = React.useState<
71
+ string | undefined
72
+ >(undefined);
73
+ const [listboxId, setListboxId] = React.useState<string | undefined>(
74
+ undefined
75
+ );
76
+ const contextValue = React.useMemo(
77
+ () => ({
78
+ searchValue,
79
+ setSearchValue,
80
+ activeDescendantId,
81
+ setActiveDescendantId,
82
+ listboxId,
83
+ setListboxId,
84
+ }),
85
+ [searchValue, activeDescendantId, listboxId]
86
+ );
87
+
88
+ return (
89
+ <CommandContext.Provider value={contextValue}>
90
+ <CommandPrimitive
91
+ ref={ref}
92
+ className={cn(
93
+ "bg-popover text-popover-foreground flex w-full flex-col overflow-hidden rounded-lg border shadow-md",
94
+ className
95
+ )}
96
+ data-hook={dataHook}
97
+ data-slot="command"
98
+ data-tracking-el={trackingEl}
99
+ data-tracking-label={trackingLabel}
100
+ {...props}
101
+ />
102
+ </CommandContext.Provider>
103
+ );
104
+ });
51
105
  Command.displayName = "Command";
52
106
 
107
+ /* -------------------------------------------------------------------------------------------------
108
+ * Command Input
109
+ * -----------------------------------------------------------------------------------------------*/
110
+
53
111
  /**
54
112
  * Props for the CommandInput component
55
113
  */
@@ -72,6 +130,18 @@ export interface CommandInputProps extends React.ComponentProps<
72
130
  * Callback when clear button is clicked
73
131
  */
74
132
  onClear?: () => void;
133
+ /**
134
+ * Debounce delay in milliseconds for the `onValueChange` callback.
135
+ * The input display updates immediately; only the callback is debounced.
136
+ * Useful for async filtering to avoid firing on every keystroke.
137
+ * @example 300
138
+ */
139
+ debounceMs?: number;
140
+ /**
141
+ * Accessible label for the clear button.
142
+ * @default "Clear search"
143
+ */
144
+ clearSearchAriaLabel?: string;
75
145
  }
76
146
 
77
147
  /**
@@ -91,16 +161,53 @@ const CommandInput = React.forwardRef<
91
161
  value: controlledValue,
92
162
  onValueChange,
93
163
  onClear,
164
+ debounceMs,
165
+ clearSearchAriaLabel,
94
166
  ...props
95
167
  },
96
168
  ref
97
169
  ) => {
98
170
  const inputRef = React.useRef<HTMLInputElement>(null);
99
171
  const [internalValue, setInternalValue] = React.useState("");
172
+ const timerRef = React.useRef<ReturnType<typeof setTimeout> | undefined>(
173
+ undefined
174
+ );
175
+ const { setSearchValue, activeDescendantId, listboxId } =
176
+ React.useContext(CommandContext);
100
177
 
101
- // Merge refs
102
178
  React.useImperativeHandle(ref, () => inputRef.current!, []);
103
179
 
180
+ useDevWarning(
181
+ () => !!(debounceMs && debounceMs > 0 && controlledValue !== undefined),
182
+ "debounceMs is set on <CommandInput> together with a controlled `value` prop.\n" +
183
+ "The debounced onValueChange callback cannot update the controlled value " +
184
+ "synchronously, so the input will appear to lag behind typing.\n" +
185
+ "Remove `value` to let the input manage its own display, or remove " +
186
+ "debounceMs if you need a controlled input.",
187
+ [debounceMs, controlledValue]
188
+ );
189
+
190
+ React.useEffect(() => {
191
+ return () => {
192
+ if (timerRef.current) clearTimeout(timerRef.current);
193
+ };
194
+ }, []);
195
+
196
+ // cmdk sets aria-controls/aria-activedescendant internally after
197
+ // spreading props, so we override via DOM to point at our virtual listbox.
198
+ React.useEffect(() => {
199
+ const el = inputRef.current;
200
+ if (!el) return;
201
+ if (listboxId) {
202
+ el.setAttribute("aria-controls", listboxId);
203
+ }
204
+ if (activeDescendantId) {
205
+ el.setAttribute("aria-activedescendant", activeDescendantId);
206
+ } else {
207
+ el.removeAttribute("aria-activedescendant");
208
+ }
209
+ });
210
+
104
211
  const isControlled = controlledValue !== undefined;
105
212
  const value = isControlled ? controlledValue : internalValue;
106
213
  const showClearButton = String(value).length > 0;
@@ -109,13 +216,24 @@ const CommandInput = React.forwardRef<
109
216
  if (!isControlled) {
110
217
  setInternalValue(newValue);
111
218
  }
112
- onValueChange?.(newValue);
219
+ setSearchValue(newValue);
220
+
221
+ if (debounceMs && debounceMs > 0) {
222
+ clearTimeout(timerRef.current);
223
+ timerRef.current = setTimeout(() => {
224
+ onValueChange?.(newValue);
225
+ }, debounceMs);
226
+ } else {
227
+ onValueChange?.(newValue);
228
+ }
113
229
  };
114
230
 
115
231
  const handleClear = () => {
116
232
  if (!isControlled) {
117
233
  setInternalValue("");
118
234
  }
235
+ setSearchValue("");
236
+ clearTimeout(timerRef.current);
119
237
  onValueChange?.("");
120
238
  onClear?.();
121
239
  inputRef.current?.focus();
@@ -143,7 +261,7 @@ const CommandInput = React.forwardRef<
143
261
  />
144
262
  {showClearButton && (
145
263
  <Button
146
- aria-label="Clear search"
264
+ aria-label={clearSearchAriaLabel ?? "Clear search"}
147
265
  className="text-muted-foreground hover:text-foreground"
148
266
  dataHook="command-input-clear"
149
267
  variant="ghost"
@@ -158,6 +276,10 @@ const CommandInput = React.forwardRef<
158
276
  );
159
277
  CommandInput.displayName = "CommandInput";
160
278
 
279
+ /* -------------------------------------------------------------------------------------------------
280
+ * Command List
281
+ * -----------------------------------------------------------------------------------------------*/
282
+
161
283
  /**
162
284
  * Props for the CommandList component
163
285
  */
@@ -190,6 +312,10 @@ const CommandList = React.forwardRef<
190
312
  ));
191
313
  CommandList.displayName = "CommandList";
192
314
 
315
+ /* -------------------------------------------------------------------------------------------------
316
+ * Command Empty
317
+ * -----------------------------------------------------------------------------------------------*/
318
+
193
319
  /**
194
320
  * Props for the CommandEmpty component
195
321
  */
@@ -235,6 +361,10 @@ const CommandEmpty = React.forwardRef<
235
361
  });
236
362
  CommandEmpty.displayName = "CommandEmpty";
237
363
 
364
+ /* -------------------------------------------------------------------------------------------------
365
+ * Command Group
366
+ * -----------------------------------------------------------------------------------------------*/
367
+
238
368
  /**
239
369
  * Props for the CommandGroup component
240
370
  */
@@ -267,6 +397,10 @@ const CommandGroup = React.forwardRef<
267
397
  ));
268
398
  CommandGroup.displayName = "CommandGroup";
269
399
 
400
+ /* -------------------------------------------------------------------------------------------------
401
+ * Command Separator
402
+ * -----------------------------------------------------------------------------------------------*/
403
+
270
404
  /**
271
405
  * Props for the CommandSeparator component
272
406
  */
@@ -296,6 +430,10 @@ const CommandSeparator = React.forwardRef<
296
430
  ));
297
431
  CommandSeparator.displayName = "CommandSeparator";
298
432
 
433
+ /* -------------------------------------------------------------------------------------------------
434
+ * Command Item
435
+ * -----------------------------------------------------------------------------------------------*/
436
+
299
437
  /**
300
438
  * Props for the CommandItem component
301
439
  */
@@ -359,6 +497,10 @@ const CommandItem = React.forwardRef<
359
497
  );
360
498
  CommandItem.displayName = "CommandItem";
361
499
 
500
+ /* -------------------------------------------------------------------------------------------------
501
+ * Command Shortcut
502
+ * -----------------------------------------------------------------------------------------------*/
503
+
362
504
  /**
363
505
  * Props for the CommandShortcut component
364
506
  */
@@ -398,6 +540,489 @@ const CommandShortcut = React.forwardRef<HTMLSpanElement, CommandShortcutProps>(
398
540
  );
399
541
  CommandShortcut.displayName = "CommandShortcut";
400
542
 
543
+ /* -------------------------------------------------------------------------------------------------
544
+ * Command Virtual List Context
545
+ * -----------------------------------------------------------------------------------------------*/
546
+
547
+ interface CommandVirtualListContextValue {
548
+ activeValue: string | null;
549
+ onItemPointerMove: (itemValue: string) => void;
550
+ idPrefix: string;
551
+ filteredCount: number;
552
+ getItemPosition: (itemValue: string) => number;
553
+ onSelectCallbacks: React.RefObject<Map<string, (() => void) | undefined>>;
554
+ }
555
+
556
+ const CommandVirtualListContext =
557
+ React.createContext<CommandVirtualListContextValue | null>(null);
558
+
559
+ /* -------------------------------------------------------------------------------------------------
560
+ * Command Virtual List
561
+ * -----------------------------------------------------------------------------------------------*/
562
+
563
+ /**
564
+ * Props for the CommandVirtualList component
565
+ */
566
+ export interface CommandVirtualListProps<T> {
567
+ /**
568
+ * Array of items to render. Memoize to avoid re-registration on every render.
569
+ */
570
+ items: T[];
571
+ /**
572
+ * Extract a unique string value from each item.
573
+ */
574
+ getItemValue: (item: T) => string;
575
+ /**
576
+ * Extract a display label for filtering. Defaults to `getItemValue`.
577
+ */
578
+ getItemLabel?: (item: T) => string;
579
+ /**
580
+ * Extra searchable keywords per item.
581
+ */
582
+ getItemKeywords?: (item: T) => string[];
583
+ /**
584
+ * Estimated item height in px for the virtualiser.
585
+ * @default 44
586
+ */
587
+ estimateSize?: number;
588
+ /**
589
+ * Number of items to render outside the visible viewport.
590
+ * @default 5
591
+ */
592
+ overscan?: number;
593
+ /**
594
+ * Render function called for each visible item.
595
+ */
596
+ children: (item: T, index: number, searchValue: string) => React.ReactNode;
597
+ /**
598
+ * Content rendered when the filtered list is empty.
599
+ */
600
+ renderEmpty?: React.ReactNode;
601
+ /**
602
+ * Accessible label for the listbox.
603
+ * Required for a11y — describes the list's purpose to screen readers.
604
+ */
605
+ "aria-label": string;
606
+ /**
607
+ * Additional CSS classes for the scroll container.
608
+ */
609
+ className?: string;
610
+ /**
611
+ * Data hook for automated testing.
612
+ */
613
+ dataHook?: string;
614
+ }
615
+
616
+ /**
617
+ * Virtualised list for Command that renders only visible items.
618
+ * Use with `shouldFilter={false}` on the parent Command component.
619
+ *
620
+ * @example
621
+ * ```tsx
622
+ * <Command dataHook="cmd" shouldFilter={false}>
623
+ * <CommandInput placeholder="Search..." />
624
+ * <CommandVirtualList
625
+ * items={items}
626
+ * getItemValue={(item) => item.value}
627
+ * getItemLabel={(item) => item.label}
628
+ * dataHook="virtual-list"
629
+ * >
630
+ * {(item) => (
631
+ * <CommandVirtualItem value={item.value}>{item.label}</CommandVirtualItem>
632
+ * )}
633
+ * </CommandVirtualList>
634
+ * </Command>
635
+ * ```
636
+ */
637
+ function CommandVirtualListInner<T>(
638
+ {
639
+ items,
640
+ getItemValue,
641
+ getItemLabel: getItemLabelProp,
642
+ getItemKeywords,
643
+ estimateSize = 44,
644
+ overscan = 5,
645
+ children,
646
+ renderEmpty,
647
+ "aria-label": ariaLabel,
648
+ className,
649
+ dataHook,
650
+ }: CommandVirtualListProps<T>,
651
+ ref: React.ForwardedRef<HTMLDivElement>
652
+ ): React.ReactElement | null {
653
+ const parentRef = React.useRef<HTMLDivElement>(null);
654
+ const { searchValue, setActiveDescendantId, setListboxId } =
655
+ React.useContext(CommandContext);
656
+ const [activeIndex, setActiveIndex] = React.useState(0);
657
+ const idPrefix = React.useId();
658
+ const listboxId = React.useId();
659
+ const onSelectCallbacksRef = React.useRef<
660
+ Map<string, (() => void) | undefined>
661
+ >(new Map());
662
+
663
+ React.useImperativeHandle(ref, () => parentRef.current!, []);
664
+
665
+ const getItemLabel = React.useMemo(
666
+ () => getItemLabelProp ?? getItemValue,
667
+ [getItemLabelProp, getItemValue]
668
+ );
669
+
670
+ const filteredItems = React.useMemo(() => {
671
+ if (!searchValue.trim()) return items;
672
+
673
+ const scored: { item: T; score: number }[] = [];
674
+ for (const item of items) {
675
+ let score = defaultFilter(getItemLabel(item), searchValue);
676
+
677
+ if (getItemKeywords) {
678
+ for (const kw of getItemKeywords(item)) {
679
+ score = Math.max(score, defaultFilter(kw, searchValue));
680
+ }
681
+ }
682
+
683
+ if (score > 0) scored.push({ item, score });
684
+ }
685
+
686
+ scored.sort((a, b) => b.score - a.score);
687
+ return scored.map((s) => s.item);
688
+ }, [items, searchValue, getItemLabel, getItemKeywords]);
689
+
690
+ // eslint-disable-next-line react-hooks/incompatible-library -- compiler already skips this component; virtualizer is not passed to memoized consumers
691
+ const virtualizer = useVirtualizer({
692
+ count: filteredItems.length,
693
+ getScrollElement: () => parentRef.current,
694
+ estimateSize: () => estimateSize,
695
+ overscan,
696
+ });
697
+
698
+ const activeValue =
699
+ activeIndex >= 0 && activeIndex < filteredItems.length
700
+ ? getItemValue(filteredItems[activeIndex]!)
701
+ : null;
702
+
703
+ React.useEffect(() => {
704
+ setActiveIndex(0);
705
+ }, [searchValue, filteredItems.length]);
706
+
707
+ const scrollOnNextIndexChange = React.useRef(false);
708
+
709
+ React.useEffect(() => {
710
+ if (
711
+ scrollOnNextIndexChange.current &&
712
+ activeIndex >= 0 &&
713
+ activeIndex < filteredItems.length
714
+ ) {
715
+ virtualizer.scrollToIndex(activeIndex, { align: "auto" });
716
+ }
717
+ scrollOnNextIndexChange.current = false;
718
+ }, [activeIndex, filteredItems.length, virtualizer]);
719
+
720
+ React.useEffect(() => {
721
+ const el = parentRef.current?.closest(
722
+ '[data-slot="command"]'
723
+ ) as HTMLElement | null;
724
+ if (!el) return;
725
+
726
+ const handleKeyDown = (e: KeyboardEvent) => {
727
+ switch (e.key) {
728
+ case "ArrowDown":
729
+ e.preventDefault();
730
+ e.stopPropagation();
731
+ scrollOnNextIndexChange.current = true;
732
+ setActiveIndex((prev) =>
733
+ prev < filteredItems.length - 1 ? prev + 1 : prev
734
+ );
735
+ break;
736
+ case "ArrowUp":
737
+ e.preventDefault();
738
+ e.stopPropagation();
739
+ scrollOnNextIndexChange.current = true;
740
+ setActiveIndex((prev) => (prev > 0 ? prev - 1 : prev));
741
+ break;
742
+ case "Enter": {
743
+ e.preventDefault();
744
+ e.stopPropagation();
745
+ if (activeValue != null) {
746
+ const callback = onSelectCallbacksRef.current.get(activeValue);
747
+ callback?.();
748
+ }
749
+ break;
750
+ }
751
+ case "Home":
752
+ e.preventDefault();
753
+ e.stopPropagation();
754
+ scrollOnNextIndexChange.current = true;
755
+ setActiveIndex(0);
756
+ break;
757
+ case "End":
758
+ e.preventDefault();
759
+ e.stopPropagation();
760
+ scrollOnNextIndexChange.current = true;
761
+ setActiveIndex(filteredItems.length - 1);
762
+ break;
763
+ }
764
+ };
765
+
766
+ el.addEventListener("keydown", handleKeyDown, { capture: true });
767
+ return () =>
768
+ el.removeEventListener("keydown", handleKeyDown, { capture: true });
769
+ }, [filteredItems, activeValue]);
770
+
771
+ const itemIndexMap = React.useMemo(() => {
772
+ const map = new Map<string, number>();
773
+ filteredItems.forEach((item, i) => {
774
+ map.set(getItemValue(item), i);
775
+ });
776
+ return map;
777
+ }, [filteredItems, getItemValue]);
778
+
779
+ const onItemPointerMove = React.useCallback(
780
+ (itemValue: string) => {
781
+ const index = itemIndexMap.get(itemValue);
782
+ if (index !== undefined) setActiveIndex(index);
783
+ },
784
+ [itemIndexMap]
785
+ );
786
+
787
+ const getItemPosition = React.useCallback(
788
+ (itemValue: string) => (itemIndexMap.get(itemValue) ?? 0) + 1,
789
+ [itemIndexMap]
790
+ );
791
+
792
+ const filteredCount = filteredItems.length;
793
+
794
+ const contextValue = React.useMemo<CommandVirtualListContextValue>(
795
+ () => ({
796
+ activeValue,
797
+ onItemPointerMove,
798
+ idPrefix,
799
+ filteredCount,
800
+ getItemPosition,
801
+ onSelectCallbacks: onSelectCallbacksRef,
802
+ }),
803
+ [activeValue, onItemPointerMove, idPrefix, filteredCount, getItemPosition]
804
+ );
805
+
806
+ // Push active descendant ID into CommandContext for CommandInput's aria-activedescendant
807
+ const activeItemId =
808
+ activeValue != null ? `${idPrefix}item-${activeValue}` : undefined;
809
+
810
+ React.useEffect(() => {
811
+ setActiveDescendantId(activeItemId);
812
+ return () => setActiveDescendantId(undefined);
813
+ }, [activeItemId, setActiveDescendantId]);
814
+
815
+ // Push listbox ID into CommandContext for CommandInput's aria-controls
816
+ React.useEffect(() => {
817
+ setListboxId(listboxId);
818
+ return () => setListboxId(undefined);
819
+ }, [listboxId, setListboxId]);
820
+
821
+ const scrollContainerClass = cn(
822
+ "scrollbar max-h-[300px] min-h-0 flex-1 scroll-py-1 overflow-x-hidden overflow-y-auto py-1",
823
+ className
824
+ );
825
+
826
+ if (filteredItems.length === 0) {
827
+ return (
828
+ <div
829
+ ref={parentRef}
830
+ aria-label={ariaLabel}
831
+ className={scrollContainerClass}
832
+ data-hook={dataHook}
833
+ data-slot="command-virtual-list"
834
+ id={listboxId}
835
+ role="listbox"
836
+ tabIndex={-1}
837
+ >
838
+ {renderEmpty}
839
+ </div>
840
+ );
841
+ }
842
+
843
+ return (
844
+ <CommandVirtualListContext.Provider value={contextValue}>
845
+ <div
846
+ ref={parentRef}
847
+ aria-label={ariaLabel}
848
+ className={scrollContainerClass}
849
+ data-hook={dataHook}
850
+ data-slot="command-virtual-list"
851
+ id={listboxId}
852
+ role="listbox"
853
+ tabIndex={-1}
854
+ >
855
+ <div
856
+ className="relative w-full"
857
+ style={{ height: `${virtualizer.getTotalSize()}px` }}
858
+ >
859
+ {virtualizer.getVirtualItems().map((virtualItem) => (
860
+ <div
861
+ key={virtualItem.key}
862
+ ref={virtualizer.measureElement}
863
+ className="absolute top-0 left-0 w-full px-2"
864
+ data-index={virtualItem.index}
865
+ style={{
866
+ transform: `translateY(${virtualItem.start}px)`,
867
+ }}
868
+ >
869
+ {children(
870
+ filteredItems[virtualItem.index]!,
871
+ virtualItem.index,
872
+ searchValue
873
+ )}
874
+ </div>
875
+ ))}
876
+ </div>
877
+ </div>
878
+ </CommandVirtualListContext.Provider>
879
+ );
880
+ }
881
+
882
+ const CommandVirtualList = React.forwardRef(CommandVirtualListInner) as <T>(
883
+ props: CommandVirtualListProps<T> & { ref?: React.Ref<HTMLDivElement> }
884
+ ) => React.ReactElement | null;
885
+
886
+ /* -------------------------------------------------------------------------------------------------
887
+ * Command Virtual Item
888
+ * -----------------------------------------------------------------------------------------------*/
889
+
890
+ /**
891
+ * Props for the CommandVirtualItem component
892
+ */
893
+ export interface CommandVirtualItemProps extends React.ComponentPropsWithoutRef<"div"> {
894
+ /**
895
+ * Unique value identifying this item.
896
+ */
897
+ value: string;
898
+ /**
899
+ * Data hook for automated testing.
900
+ */
901
+ dataHook?: string;
902
+ /**
903
+ * Tracking element identifier for analytics.
904
+ */
905
+ trackingEl?: string;
906
+ /**
907
+ * Tracking label for analytics context.
908
+ */
909
+ trackingLabel?: string;
910
+ /**
911
+ * Whether this item is selected (shows checkmark).
912
+ */
913
+ selected?: boolean;
914
+ /**
915
+ * Whether this item is disabled.
916
+ */
917
+ disabled?: boolean;
918
+ /**
919
+ * Callback when the item is activated (click or Enter).
920
+ */
921
+ onSelect?: () => void;
922
+ }
923
+
924
+ /**
925
+ * Item within a CommandVirtualList. Renders as a plain div with proper
926
+ * ARIA attributes, bypassing cmdk item registration for performance.
927
+ */
928
+ const CommandVirtualItem = React.forwardRef<
929
+ HTMLDivElement,
930
+ CommandVirtualItemProps
931
+ >(
932
+ (
933
+ {
934
+ value,
935
+ dataHook,
936
+ trackingEl,
937
+ trackingLabel,
938
+ selected,
939
+ disabled,
940
+ onSelect,
941
+ children,
942
+ className,
943
+ onClick: consumerOnClick,
944
+ onKeyDown: consumerOnKeyDown,
945
+ onPointerMove: consumerOnPointerMove,
946
+ ...props
947
+ },
948
+ ref
949
+ ) => {
950
+ const virtualCtx = React.useContext(CommandVirtualListContext);
951
+ const isHighlighted = virtualCtx?.activeValue === value;
952
+
953
+ // Register onSelect callback so the virtual list's Enter handler
954
+ // can invoke it via state instead of DOM querying.
955
+ const onSelectRef = React.useRef(onSelect);
956
+ React.useEffect(() => {
957
+ onSelectRef.current = onSelect;
958
+ });
959
+
960
+ React.useEffect(() => {
961
+ if (!virtualCtx) return;
962
+ virtualCtx.onSelectCallbacks.current.set(value, () =>
963
+ onSelectRef.current?.()
964
+ );
965
+ return () => {
966
+ virtualCtx.onSelectCallbacks.current.delete(value);
967
+ };
968
+ }, [value, virtualCtx]);
969
+
970
+ return (
971
+ <div
972
+ ref={ref}
973
+ {...props}
974
+ aria-disabled={disabled || undefined}
975
+ aria-posinset={virtualCtx?.getItemPosition(value)}
976
+ aria-selected={selected || undefined}
977
+ aria-setsize={virtualCtx?.filteredCount}
978
+ className={cn(
979
+ "data-[highlighted=true]:bg-accent data-[highlighted=true]:text-accent-foreground relative flex cursor-default items-center gap-2 rounded-sm px-2 py-3 text-sm outline-hidden select-none",
980
+ "[&_svg]:pointer-events-none [&_svg]:shrink-0",
981
+ disabled && "pointer-events-none opacity-50",
982
+ className
983
+ )}
984
+ data-highlighted={isHighlighted || undefined}
985
+ data-hook={dataHook}
986
+ data-selected-item={selected || undefined}
987
+ data-slot="command-virtual-item"
988
+ data-tracking-el={trackingEl}
989
+ data-tracking-label={trackingLabel}
990
+ id={virtualCtx ? `${virtualCtx.idPrefix}item-${value}` : undefined}
991
+ role="option"
992
+ tabIndex={-1}
993
+ onClick={
994
+ disabled
995
+ ? undefined
996
+ : (e) => {
997
+ onSelect?.();
998
+ consumerOnClick?.(e);
999
+ }
1000
+ }
1001
+ onKeyDown={
1002
+ disabled
1003
+ ? undefined
1004
+ : (e) => {
1005
+ if (e.key === "Enter" || e.key === " ") onSelect?.();
1006
+ consumerOnKeyDown?.(e);
1007
+ }
1008
+ }
1009
+ onPointerMove={
1010
+ disabled
1011
+ ? undefined
1012
+ : (e) => {
1013
+ virtualCtx?.onItemPointerMove(value);
1014
+ consumerOnPointerMove?.(e);
1015
+ }
1016
+ }
1017
+ >
1018
+ {children}
1019
+ {selected && <Check className="text-foreground ml-auto" />}
1020
+ </div>
1021
+ );
1022
+ }
1023
+ );
1024
+ CommandVirtualItem.displayName = "CommandVirtualItem";
1025
+
401
1026
  export {
402
1027
  Command,
403
1028
  CommandEmpty,
@@ -407,4 +1032,6 @@ export {
407
1032
  CommandList,
408
1033
  CommandSeparator,
409
1034
  CommandShortcut,
1035
+ CommandVirtualItem,
1036
+ CommandVirtualList,
410
1037
  };