@brightlocal/ui-components 3.3.0 → 3.5.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 (207) hide show
  1. package/AI_USAGE.md +22 -3
  2. package/README.md +177 -109
  3. package/component-meta.json +1307 -113
  4. package/dist/alert-dialog.cjs +1 -1
  5. package/dist/alert-dialog.d.ts +13 -2
  6. package/dist/alert-dialog.d.ts.map +1 -1
  7. package/dist/alert-dialog.js +4 -3
  8. package/dist/banner.cjs +1 -1
  9. package/dist/banner.d.ts +47 -11
  10. package/dist/banner.d.ts.map +1 -1
  11. package/dist/banner.js +156 -79
  12. package/dist/blocks/empty-state.cjs +1 -1
  13. package/dist/blocks/empty-state.d.ts +40 -5
  14. package/dist/blocks/empty-state.d.ts.map +1 -1
  15. package/dist/blocks/empty-state.js +59 -52
  16. package/dist/blocks/input-list.cjs +1 -1
  17. package/dist/blocks/input-list.d.ts +1 -0
  18. package/dist/blocks/input-list.d.ts.map +1 -1
  19. package/dist/blocks/input-list.js +39 -39
  20. package/dist/blocks/sidebar.cjs +1 -1
  21. package/dist/blocks/sidebar.d.ts +12 -6
  22. package/dist/blocks/sidebar.d.ts.map +1 -1
  23. package/dist/blocks/sidebar.js +64 -63
  24. package/dist/button.cjs +1 -1
  25. package/dist/button.d.ts.map +1 -1
  26. package/dist/button.js +47 -43
  27. package/dist/card.cjs +1 -1
  28. package/dist/card.d.ts +12 -0
  29. package/dist/card.d.ts.map +1 -1
  30. package/dist/card.js +115 -97
  31. package/dist/chart.cjs +6 -6
  32. package/dist/chart.d.ts +6 -10
  33. package/dist/chart.d.ts.map +1 -1
  34. package/dist/chart.js +281 -296
  35. package/dist/combobox.cjs +3 -3
  36. package/dist/combobox.d.ts.map +1 -1
  37. package/dist/combobox.js +430 -343
  38. package/dist/command.cjs +1 -1
  39. package/dist/command.d.ts +23 -2
  40. package/dist/command.d.ts.map +1 -1
  41. package/dist/command.js +212 -207
  42. package/dist/count-indicator.cjs +1 -0
  43. package/dist/count-indicator.d.ts +85 -0
  44. package/dist/count-indicator.d.ts.map +1 -0
  45. package/dist/count-indicator.js +72 -0
  46. package/dist/data-table.cjs +1 -1
  47. package/dist/data-table.d.ts +101 -11
  48. package/dist/data-table.d.ts.map +1 -1
  49. package/dist/data-table.js +593 -523
  50. package/dist/description-list.cjs +1 -0
  51. package/dist/description-list.d.ts +142 -0
  52. package/dist/description-list.d.ts.map +1 -0
  53. package/dist/description-list.js +173 -0
  54. package/dist/dialog.cjs +1 -1
  55. package/dist/dialog.d.ts +26 -3
  56. package/dist/dialog.d.ts.map +1 -1
  57. package/dist/dialog.js +62 -47
  58. package/dist/drawer.cjs +1 -1
  59. package/dist/drawer.d.ts +8 -4
  60. package/dist/drawer.d.ts.map +1 -1
  61. package/dist/drawer.js +37 -38
  62. package/dist/file-upload.cjs +1 -0
  63. package/dist/file-upload.d.ts +546 -0
  64. package/dist/file-upload.d.ts.map +1 -0
  65. package/dist/file-upload.js +1103 -0
  66. package/dist/global-layout.cjs +1 -1
  67. package/dist/global-layout.d.ts +7 -2
  68. package/dist/global-layout.d.ts.map +1 -1
  69. package/dist/global-layout.js +52 -52
  70. package/dist/hooks/use-file-dropzone.cjs +1 -0
  71. package/dist/hooks/use-file-dropzone.d.ts +75 -0
  72. package/dist/hooks/use-file-dropzone.d.ts.map +1 -0
  73. package/dist/hooks/use-file-dropzone.js +133 -0
  74. package/dist/hover-card.cjs +1 -1
  75. package/dist/hover-card.d.ts +29 -16
  76. package/dist/hover-card.d.ts.map +1 -1
  77. package/dist/hover-card.js +153 -36
  78. package/dist/index.cjs +1 -1
  79. package/dist/index.d.ts +4 -0
  80. package/dist/index.d.ts.map +1 -1
  81. package/dist/index.js +681 -623
  82. package/dist/input-chip.cjs +1 -1
  83. package/dist/input-chip.d.ts +30 -1
  84. package/dist/input-chip.d.ts.map +1 -1
  85. package/dist/input-chip.js +131 -115
  86. package/dist/input-group.cjs +1 -1
  87. package/dist/input-group.d.ts +37 -2
  88. package/dist/input-group.d.ts.map +1 -1
  89. package/dist/input-group.js +131 -114
  90. package/dist/input-password.cjs +1 -1
  91. package/dist/input-password.js +6 -6
  92. package/dist/lib/empty-canvas.cjs +1 -1
  93. package/dist/lib/empty-canvas.d.ts +27 -1
  94. package/dist/lib/empty-canvas.d.ts.map +1 -1
  95. package/dist/lib/empty-canvas.js +27 -23
  96. package/dist/lib/empty-chip.cjs +1 -1
  97. package/dist/lib/empty-chip.d.ts +19 -2
  98. package/dist/lib/empty-chip.d.ts.map +1 -1
  99. package/dist/lib/empty-chip.js +14 -9
  100. package/dist/lib/field-aria.cjs +1 -1
  101. package/dist/lib/field-aria.d.ts +4 -4
  102. package/dist/lib/field-aria.d.ts.map +1 -1
  103. package/dist/lib/field-aria.js +7 -5
  104. package/dist/lib/media-viewer-content.cjs +1 -1
  105. package/dist/lib/media-viewer-content.js +1 -1
  106. package/dist/lib/motion.cjs +1 -1
  107. package/dist/lib/motion.js +15 -10
  108. package/dist/lib/table-internal.cjs +1 -1
  109. package/dist/lib/table-internal.d.ts +19 -0
  110. package/dist/lib/table-internal.d.ts.map +1 -1
  111. package/dist/lib/table-internal.js +22 -7
  112. package/dist/list.cjs +1 -1
  113. package/dist/list.d.ts +230 -40
  114. package/dist/list.d.ts.map +1 -1
  115. package/dist/list.js +301 -66
  116. package/dist/logo-mark.cjs +1 -1
  117. package/dist/logo-mark.d.ts +18 -2
  118. package/dist/logo-mark.d.ts.map +1 -1
  119. package/dist/logo-mark.js +159 -79
  120. package/dist/media-empty.cjs +1 -1
  121. package/dist/media-empty.d.ts +50 -7
  122. package/dist/media-empty.d.ts.map +1 -1
  123. package/dist/media-empty.js +14 -13
  124. package/dist/media-viewer.cjs +1 -1
  125. package/dist/media-viewer.js +6 -6
  126. package/dist/multi-select-filter.cjs +1 -1
  127. package/dist/multi-select-filter.d.ts.map +1 -1
  128. package/dist/multi-select-filter.js +92 -101
  129. package/dist/pagination.cjs +1 -1
  130. package/dist/pagination.d.ts +11 -0
  131. package/dist/pagination.d.ts.map +1 -1
  132. package/dist/pagination.js +17 -17
  133. package/dist/relative-date.d.ts +6 -0
  134. package/dist/relative-date.d.ts.map +1 -1
  135. package/dist/resizable.d.ts +1 -1
  136. package/dist/result-count.cjs +1 -1
  137. package/dist/result-count.d.ts +13 -16
  138. package/dist/result-count.d.ts.map +1 -1
  139. package/dist/result-count.js +24 -33
  140. package/dist/route-progress.cjs +1 -1
  141. package/dist/route-progress.js +24 -23
  142. package/dist/sheet.cjs +1 -1
  143. package/dist/sheet.d.ts +22 -3
  144. package/dist/sheet.d.ts.map +1 -1
  145. package/dist/sheet.js +152 -125
  146. package/dist/single-select-filter.cjs +1 -1
  147. package/dist/single-select-filter.d.ts.map +1 -1
  148. package/dist/single-select-filter.js +67 -76
  149. package/dist/table.cjs +1 -1
  150. package/dist/table.d.ts.map +1 -1
  151. package/dist/table.js +77 -76
  152. package/dist/tabs.cjs +1 -1
  153. package/dist/tabs.d.ts +39 -3
  154. package/dist/tabs.d.ts.map +1 -1
  155. package/dist/tabs.js +127 -76
  156. package/dist/textarea.cjs +1 -1
  157. package/dist/textarea.d.ts +34 -0
  158. package/dist/textarea.d.ts.map +1 -1
  159. package/dist/textarea.js +115 -19
  160. package/dist/tooltip.cjs +1 -1
  161. package/dist/tooltip.d.ts.map +1 -1
  162. package/dist/tooltip.js +137 -131
  163. package/dist/typography-text.cjs +1 -1
  164. package/dist/typography-text.d.ts +6 -2
  165. package/dist/typography-text.d.ts.map +1 -1
  166. package/dist/typography-text.js +14 -13
  167. package/package.json +2 -3
  168. package/src/blocks/empty-state.tsx +108 -48
  169. package/src/blocks/input-list.tsx +15 -9
  170. package/src/blocks/sidebar.tsx +39 -16
  171. package/src/components/alert-dialog.tsx +18 -2
  172. package/src/components/banner.tsx +247 -68
  173. package/src/components/button.tsx +27 -10
  174. package/src/components/card.tsx +89 -7
  175. package/src/components/chart.tsx +47 -67
  176. package/src/components/combobox.tsx +221 -12
  177. package/src/components/command.tsx +83 -37
  178. package/src/components/count-indicator.tsx +188 -0
  179. package/src/components/data-table.tsx +506 -159
  180. package/src/components/description-list.tsx +445 -0
  181. package/src/components/dialog.tsx +74 -5
  182. package/src/components/drawer.tsx +52 -32
  183. package/src/components/file-upload.tsx +2574 -0
  184. package/src/components/global-layout.tsx +18 -5
  185. package/src/components/hover-card.tsx +395 -65
  186. package/src/components/input-chip.tsx +67 -2
  187. package/src/components/input-group.tsx +89 -6
  188. package/src/components/list.tsx +720 -72
  189. package/src/components/logo-mark.tsx +109 -25
  190. package/src/components/media-empty.tsx +62 -7
  191. package/src/components/multi-select-filter.tsx +9 -16
  192. package/src/components/pagination.tsx +15 -2
  193. package/src/components/relative-date.tsx +6 -0
  194. package/src/components/result-count.tsx +27 -54
  195. package/src/components/sheet.tsx +86 -8
  196. package/src/components/single-select-filter.tsx +9 -16
  197. package/src/components/table.tsx +16 -1
  198. package/src/components/tabs.tsx +223 -41
  199. package/src/components/textarea.tsx +271 -4
  200. package/src/components/tooltip.tsx +29 -2
  201. package/src/components/typography-text.tsx +7 -2
  202. package/src/hooks/use-file-dropzone.ts +325 -0
  203. package/src/index.ts +4 -0
  204. package/src/lib/empty-canvas.tsx +47 -20
  205. package/src/lib/empty-chip.tsx +38 -3
  206. package/src/lib/field-aria.tsx +11 -6
  207. package/src/lib/table-internal.ts +38 -0
@@ -272,9 +272,7 @@ function isRenderableValue(
272
272
  /**
273
273
  * Props for the ChartTooltip component.
274
274
  *
275
- * Inherits all Recharts Tooltip props. Notable defaults changed by the DS:
276
- * - `portal` — renders to `document.body`; pass `null` for inline (Recharts default)
277
- * - `allowEscapeViewBox` — `{ x: true, y: true }` so the tooltip is never clipped
275
+ * Inherits all Recharts Tooltip props. Notable default changed by the DS:
278
276
  * - `wrapperStyle` — includes `zIndex: 50`; consumer values are merged on top
279
277
  */
280
278
  interface ChartTooltipProps extends React.ComponentProps<
@@ -293,74 +291,48 @@ interface ChartTooltipProps extends React.ComponentProps<
293
291
  }
294
292
 
295
293
  const TOOLTIP_Z_INDEX = 50;
296
-
297
294
  /**
298
- * Creates and manages a body-appended div for portalling the chart tooltip
299
- * outside the chart container, so it is never clipped by overflow or
300
- * stacking-context boundaries.
301
- */
302
- function useChartTooltipPortal(enabled: boolean): HTMLDivElement | null {
303
- const [portalEl, setPortalEl] = React.useState<HTMLDivElement | null>(null);
304
-
305
- /* eslint-disable react-hooks/set-state-in-effect -- portal div must be created in an effect (DOM side-effect) and stored in state so the component re-renders with it */
306
- React.useEffect(() => {
307
- if (!enabled) {
308
- setPortalEl(null);
309
- return;
310
- }
311
- const div = document.createElement("div");
312
- div.setAttribute("data-slot", "chart-tooltip-portal");
313
- document.body.appendChild(div);
314
- setPortalEl(div);
315
- return () => {
316
- document.body.removeChild(div);
317
- };
318
- }, [enabled]);
319
- /* eslint-enable react-hooks/set-state-in-effect */
320
-
321
- return portalEl;
322
- }
323
-
324
- /**
325
- * Dismisses the chart tooltip on touch-outside and scroll. On touch devices
326
- * Recharts keeps the tooltip visible after a tap (no pointerleave fires), so
327
- * this hook hides the Recharts tooltip wrapper when the user taps elsewhere or
328
- * scrolls. Recharts naturally restores `visibility: visible` when a new data
329
- * point is tapped.
295
+ * Closes the chart tooltip on touch devices, where no pointerleave fires
296
+ * after a tap: on a tap outside the chart, and on a scroll after a tap.
297
+ * Returns whether the tooltip is closed; a tap inside the chart, or a mouse,
298
+ * pen or keyboard on it, opens it again. The state goes to Recharts through `active`, so Recharts shows the
299
+ * tooltip again itself on the next tap.
330
300
  */
331
301
  function useChartTouchDismiss(
332
302
  containerRef: React.RefObject<HTMLDivElement | null> | undefined,
333
- portalEl: HTMLDivElement | null
334
- ) {
303
+ portalEl: HTMLElement | null
304
+ ): boolean {
305
+ const [dismissed, setDismissed] = React.useState(false);
306
+
335
307
  React.useEffect(() => {
336
308
  const container = containerRef?.current;
337
309
  if (!container) return;
338
310
 
339
- const tooltipHost = portalEl ?? container;
340
311
  let touchActive = false;
341
312
 
342
- function dismiss() {
343
- const wrapper = tooltipHost.querySelector(
344
- ".recharts-tooltip-wrapper"
345
- ) as HTMLElement | null;
346
- if (wrapper) {
347
- wrapper.style.visibility = "hidden";
348
- }
349
- }
350
-
351
313
  function handleTouchStart(e: TouchEvent) {
352
- touchActive = true;
353
314
  const target = e.target as Node;
354
- if (!container!.contains(target) && !tooltipHost.contains(target)) {
355
- dismiss();
356
- touchActive = false;
357
- }
315
+ const inside =
316
+ container!.contains(target) || !!portalEl?.contains(target);
317
+ touchActive = inside;
318
+ setDismissed(!inside);
358
319
  }
359
320
 
360
321
  function handleScroll() {
361
322
  if (!touchActive) return;
362
- dismiss();
363
323
  touchActive = false;
324
+ setDismissed(true);
325
+ }
326
+
327
+ // A mouse, pen or keyboard back on the chart (a touch laptop, a tablet
328
+ // with a trackpad) brings the tooltip back: a touch close must not
329
+ // outlive the touch.
330
+ function handlePointer(e: PointerEvent) {
331
+ if (e.pointerType !== "touch") setDismissed(false);
332
+ }
333
+
334
+ function handleKeyboard() {
335
+ setDismissed(false);
364
336
  }
365
337
 
366
338
  document.addEventListener("touchstart", handleTouchStart, {
@@ -370,38 +342,46 @@ function useChartTouchDismiss(
370
342
  passive: true,
371
343
  capture: true,
372
344
  });
345
+ container.addEventListener("pointermove", handlePointer);
346
+ container.addEventListener("pointerdown", handlePointer);
347
+ container.addEventListener("keydown", handleKeyboard);
348
+ container.addEventListener("focusin", handleKeyboard);
373
349
 
374
350
  return () => {
375
351
  document.removeEventListener("touchstart", handleTouchStart);
376
352
  window.removeEventListener("scroll", handleScroll, { capture: true });
353
+ container.removeEventListener("pointermove", handlePointer);
354
+ container.removeEventListener("pointerdown", handlePointer);
355
+ container.removeEventListener("keydown", handleKeyboard);
356
+ container.removeEventListener("focusin", handleKeyboard);
377
357
  };
378
358
  }, [containerRef, portalEl]);
359
+
360
+ return dismissed;
379
361
  }
380
362
 
381
363
  /**
382
- * ChartTooltip displays data values on hover/tap. Portals to `document.body`
383
- * by default so the tooltip escapes chart overflow clipping and sits above
384
- * page-level widgets (z-index 50). On touch devices, dismisses on tap-outside
385
- * and scroll.
386
- *
387
- * Pass `portal={null}` to render inline (pre-portal Recharts default).
364
+ * ChartTooltip displays data values on hover/tap. Renders inline, as in
365
+ * shadcn/Recharts: Recharts keeps it inside the chart and slides it after the
366
+ * cursor. It sits above page-level widgets (z-index 50). On touch devices,
367
+ * it closes on a tap outside the chart and on scroll.
388
368
  */
389
369
  function ChartTooltip({
390
370
  portal,
391
371
  wrapperStyle,
392
- allowEscapeViewBox,
372
+ active,
393
373
  ...props
394
374
  }: ChartTooltipProps) {
395
375
  const chartContext = useChartOptional();
396
- const usePortal = portal !== null;
397
- const portalEl = useChartTooltipPortal(usePortal);
398
-
399
- useChartTouchDismiss(chartContext?.containerRef, portalEl);
376
+ const dismissed = useChartTouchDismiss(
377
+ chartContext?.containerRef,
378
+ portal ?? null
379
+ );
400
380
 
401
381
  return (
402
382
  <RechartsPrimitive.Tooltip
403
- allowEscapeViewBox={allowEscapeViewBox ?? { x: true, y: true }}
404
- portal={portal !== undefined ? portal : portalEl}
383
+ active={active ?? (dismissed ? false : undefined)}
384
+ portal={portal}
405
385
  wrapperStyle={{ zIndex: TOOLTIP_Z_INDEX, ...wrapperStyle }}
406
386
  {...props}
407
387
  />
@@ -61,6 +61,10 @@ interface ComboboxContextValue {
61
61
  setActiveDescendantId: React.Dispatch<
62
62
  React.SetStateAction<string | undefined>
63
63
  >;
64
+ /** ID of the virtual listbox (set by virtual list for the input's aria-controls) */
65
+ listboxId: string | undefined;
66
+ /** Update the virtual listbox ID */
67
+ setListboxId: React.Dispatch<React.SetStateAction<string | undefined>>;
64
68
  }
65
69
 
66
70
  /* -------------------------------------------------------------------------------------------------
@@ -187,6 +191,9 @@ function Combobox({
187
191
  const [activeDescendantId, setActiveDescendantId] = React.useState<
188
192
  string | undefined
189
193
  >(undefined);
194
+ const [listboxId, setListboxId] = React.useState<string | undefined>(
195
+ undefined
196
+ );
190
197
 
191
198
  const isValueControlled = controlledValue !== undefined;
192
199
  const isOpenControlled = controlledOpen !== undefined;
@@ -340,6 +347,8 @@ function Combobox({
340
347
  setSearchValue,
341
348
  activeDescendantId,
342
349
  setActiveDescendantId,
350
+ listboxId,
351
+ setListboxId,
343
352
  }),
344
353
  [
345
354
  open,
@@ -357,6 +366,7 @@ function Combobox({
357
366
  searchValue,
358
367
  activeDescendantId,
359
368
  setActiveDescendantId,
369
+ listboxId,
360
370
  ]
361
371
  );
362
372
 
@@ -829,23 +839,149 @@ function ComboboxContent({
829
839
  side={lockedSide ?? side}
830
840
  sideOffset={sideOffset}
831
841
  >
832
- <Command
842
+ <ComboboxCommand
833
843
  className={cn(
834
844
  "min-h-0 flex-1 border-0 shadow-none",
835
845
  "[&_[data-slot='command-input-wrapper']]:shrink-0",
836
846
  hideList && "[&_[data-slot='command-input-wrapper']]:border-b-0"
837
847
  )}
838
- data-slot="combobox-command"
839
848
  dataHook={dataHook || "combobox-command"}
840
849
  filter={cmdkFilter}
841
850
  shouldFilter={shouldFilter}
842
851
  >
843
852
  {children}
844
- </Command>
853
+ </ComboboxCommand>
845
854
  </PopoverContent>
846
855
  );
847
856
  }
848
857
 
858
+ /** Escapes a value for use inside a double-quoted CSS attribute selector. */
859
+ function cssAttributeValue(value: string) {
860
+ return typeof CSS !== "undefined" && CSS.escape
861
+ ? CSS.escape(value)
862
+ : value.replace(/["\\]/g, "\\$&");
863
+ }
864
+
865
+ /**
866
+ * Scrolls `item` to the vertical centre of its `[cmdk-list]` scroll
867
+ * container, without scrolling any other ancestor (scrollIntoView would also
868
+ * move the page). Measured from rects divided by the list's rendered scale,
869
+ * so the popover's zoom-in entrance does not skew the offset.
870
+ */
871
+ function centerItemInList(item: HTMLElement) {
872
+ const list = item.closest<HTMLElement>("[cmdk-list]");
873
+ if (!list || list.offsetHeight === 0) return;
874
+ const listRect = list.getBoundingClientRect();
875
+ const itemRect = item.getBoundingClientRect();
876
+ const scale = listRect.height / list.offsetHeight || 1;
877
+ const itemTop = (itemRect.top - listRect.top) / scale + list.scrollTop;
878
+ const itemHeight = itemRect.height / scale;
879
+ list.scrollTop = itemTop - (list.clientHeight - itemHeight) / 2;
880
+ }
881
+
882
+ function isItemInView(item: HTMLElement) {
883
+ const list = item.closest<HTMLElement>("[cmdk-list]");
884
+ if (!list) return true;
885
+ const listRect = list.getBoundingClientRect();
886
+ const itemRect = item.getBoundingClientRect();
887
+ return itemRect.top >= listRect.top && itemRect.bottom <= listRect.bottom;
888
+ }
889
+
890
+ /**
891
+ * The cmdk root of a ComboboxContent. Mounts with the popover content, so
892
+ * every open starts here: it opens the list at the selected value — that
893
+ * item is cmdk's active item (arrow keys and Enter start from it) and is
894
+ * centred in the list. With no value, or a value the list does not contain,
895
+ * cmdk's default stands: the first item is active.
896
+ *
897
+ * cmdk's `value` prop is controlled only for the opening render and handed
898
+ * back right after. Kept controlled, cmdk reads the active item's id and
899
+ * scroll target from the DOM before its items re-render, so both would lag
900
+ * one key press behind. cmdk also only publishes `aria-activedescendant` once
901
+ * it moves the active item itself, so the seeded item's id is written to the
902
+ * input and list here; cmdk overwrites it on the next move.
903
+ */
904
+ function ComboboxCommand({
905
+ children,
906
+ ...props
907
+ }: React.ComponentProps<typeof Command>) {
908
+ const { open, value } = useComboboxContext();
909
+ const commandRef = React.useRef<HTMLDivElement>(null);
910
+ // `undefined` = uncontrolled (cmdk owns the active item); "" = clear it
911
+ const [seed, setSeed] = React.useState<string | undefined>(
912
+ () => value || undefined
913
+ );
914
+ const recheckFrame = React.useRef(0);
915
+
916
+ // Reopened before the exit animation unmounted this tree: nothing remounts,
917
+ // so seed again — the selected value, or the first item when there is none.
918
+ const closedWhileMounted = React.useRef(false);
919
+ /* eslint-disable react-hooks/set-state-in-effect -- the seed is read from cmdk's rendered items, which exist only after commit; a layout effect re-renders before paint */
920
+ React.useLayoutEffect(() => {
921
+ if (!open) {
922
+ closedWhileMounted.current = true;
923
+ return;
924
+ }
925
+ if (!closedWhileMounted.current) return;
926
+ closedWhileMounted.current = false;
927
+ setSeed(
928
+ value ||
929
+ commandRef.current
930
+ ?.querySelector('[cmdk-item]:not([aria-disabled="true"])')
931
+ ?.getAttribute("data-value") ||
932
+ undefined
933
+ );
934
+ }, [open, value]);
935
+
936
+ // Child layout effects (cmdk registering its items) have run by now.
937
+ React.useLayoutEffect(() => {
938
+ const root = commandRef.current;
939
+ if (seed === undefined || !root) return;
940
+ if (seed === "") {
941
+ setSeed(undefined);
942
+ return;
943
+ }
944
+
945
+ const item = root.querySelector<HTMLElement>(
946
+ `[cmdk-item][data-value="${cssAttributeValue(seed)}"]:not([aria-disabled="true"])`
947
+ );
948
+ if (!item) {
949
+ // Not in the list: fall back to cmdk's default, the first item — or
950
+ // no active item, so items that load later still get their first one
951
+ const first = root
952
+ .querySelector<HTMLElement>('[cmdk-item]:not([aria-disabled="true"])')
953
+ ?.getAttribute("data-value");
954
+ setSeed(first ?? "");
955
+ return;
956
+ }
957
+
958
+ for (const owner of root.querySelectorAll("[cmdk-input], [cmdk-list]")) {
959
+ owner.setAttribute("aria-activedescendant", item.id);
960
+ }
961
+ centerItemInList(item);
962
+ setSeed(undefined);
963
+
964
+ // The popover can still resize as it settles (collision padding caps its
965
+ // height a frame later); keep the item in view if it moved out.
966
+ recheckFrame.current = requestAnimationFrame(() => {
967
+ if (item.isConnected && !isItemInView(item)) centerItemInList(item);
968
+ });
969
+ }, [seed]);
970
+ /* eslint-enable react-hooks/set-state-in-effect */
971
+ React.useEffect(() => () => cancelAnimationFrame(recheckFrame.current), []);
972
+
973
+ return (
974
+ <Command
975
+ {...props}
976
+ ref={commandRef}
977
+ data-slot="combobox-command"
978
+ value={seed}
979
+ >
980
+ {children}
981
+ </Command>
982
+ );
983
+ }
984
+
849
985
  /* -------------------------------------------------------------------------------------------------
850
986
  * Combobox Input
851
987
  * -----------------------------------------------------------------------------------------------*/
@@ -870,7 +1006,7 @@ const ComboboxInput = React.forwardRef<
870
1006
  React.ComponentRef<typeof CommandInput>,
871
1007
  ComboboxInputProps
872
1008
  >(({ debounceMs, onValueChange, ...props }, ref) => {
873
- const { setSearchValue, shouldFilter, activeDescendantId } =
1009
+ const { setSearchValue, shouldFilter, activeDescendantId, listboxId } =
874
1010
  useComboboxContext();
875
1011
  const timerRef = React.useRef<ReturnType<typeof setTimeout> | undefined>(
876
1012
  undefined
@@ -918,9 +1054,50 @@ const ComboboxInput = React.forwardRef<
918
1054
  [debounceMs, onValueChange, setSearchValue]
919
1055
  );
920
1056
 
1057
+ // cmdk's input writes its own `aria-activedescendant` and `aria-controls`
1058
+ // after spreading our props, so the props never reach the DOM.
1059
+ // ComboboxVirtualList renders its own listbox of plain options cmdk does not
1060
+ // know about, so while it is mounted both attributes are set on the element
1061
+ // directly. Otherwise cmdk owns them and both IDs stay undefined.
1062
+ const inputRef = React.useRef<HTMLInputElement | null>(null);
1063
+ const setInputRef = React.useCallback(
1064
+ (node: HTMLInputElement | null) => {
1065
+ inputRef.current = node;
1066
+ if (typeof ref !== "function") {
1067
+ if (ref) ref.current = node;
1068
+ return undefined;
1069
+ }
1070
+ // Hand a React 19 cleanup-returning ref its cleanup back, so React
1071
+ // calls it instead of ref(null)
1072
+ const cleanup: unknown = ref(node);
1073
+ if (typeof cleanup !== "function") return undefined;
1074
+ return () => {
1075
+ inputRef.current = null;
1076
+ cleanup();
1077
+ };
1078
+ },
1079
+ [ref]
1080
+ );
1081
+ React.useLayoutEffect(() => {
1082
+ const input = inputRef.current;
1083
+ if (!input || activeDescendantId === undefined) return undefined;
1084
+ input.setAttribute("aria-activedescendant", activeDescendantId);
1085
+ return () => input.removeAttribute("aria-activedescendant");
1086
+ }, [activeDescendantId]);
1087
+ React.useLayoutEffect(() => {
1088
+ const input = inputRef.current;
1089
+ if (!input || listboxId === undefined) return undefined;
1090
+ const cmdkListId = input.getAttribute("aria-controls");
1091
+ input.setAttribute("aria-controls", listboxId);
1092
+ return () => {
1093
+ if (cmdkListId) input.setAttribute("aria-controls", cmdkListId);
1094
+ else input.removeAttribute("aria-controls");
1095
+ };
1096
+ }, [listboxId]);
1097
+
921
1098
  return (
922
1099
  <CommandInput
923
- ref={ref}
1100
+ ref={setInputRef}
924
1101
  aria-activedescendant={activeDescendantId}
925
1102
  data-slot="combobox-input"
926
1103
  onValueChange={handleValueChange}
@@ -1044,6 +1221,7 @@ function ComboboxVirtualListInner<T>(
1044
1221
 
1045
1222
  const parentRef = React.useRef<HTMLDivElement>(null);
1046
1223
  const {
1224
+ open,
1047
1225
  value,
1048
1226
  onValueChange,
1049
1227
  setOpen,
@@ -1051,6 +1229,7 @@ function ComboboxVirtualListInner<T>(
1051
1229
  searchValue,
1052
1230
  filterFn,
1053
1231
  setActiveDescendantId,
1232
+ setListboxId,
1054
1233
  registerItemsSync,
1055
1234
  unregisterItem,
1056
1235
  } = useComboboxContext();
@@ -1132,20 +1311,41 @@ function ComboboxVirtualListInner<T>(
1132
1311
  setActiveIndex(0);
1133
1312
  }, [searchValue, filteredItems.length]);
1134
1313
 
1135
- // Scroll to selected value once it becomes available (when popover opens).
1136
- // Runs when value/filteredItems change but only fires once via guard ref,
1137
- // so async-loaded items that arrive after mount are still handled.
1138
- const initialScrollDone = React.useRef(false);
1314
+ // Open at the selected value: make it the active item and centre it.
1315
+ // Pending from every open until it lands, so async items that arrive after
1316
+ // mount are still handled; typing hands control to the search instead.
1317
+ //
1318
+ // The pending flag is re-armed by an unmount cleanup. Under React
1319
+ // StrictMode the virtualizer's own layout-effect cleanup cancels an
1320
+ // in-flight scrollToIndex, and its re-mount writes back the offset it last
1321
+ // saw (0) — so a one-shot scroll guarded by a ref is undone and never
1322
+ // retried (DS-1266). It is also re-armed on close, for a popover reopened
1323
+ // before its exit animation unmounted this list.
1324
+ const initialScrollPending = React.useRef(true);
1325
+ React.useEffect(
1326
+ () => () => {
1327
+ initialScrollPending.current = true;
1328
+ },
1329
+ []
1330
+ );
1139
1331
  React.useEffect(() => {
1140
- if (initialScrollDone.current || !value) return;
1332
+ if (!open) {
1333
+ initialScrollPending.current = true;
1334
+ return;
1335
+ }
1336
+ if (!initialScrollPending.current || !value) return;
1337
+ if (searchValue) {
1338
+ initialScrollPending.current = false;
1339
+ return;
1340
+ }
1141
1341
 
1142
1342
  const idx = filteredItems.findIndex((item) => getItemValue(item) === value);
1143
1343
  if (idx >= 0) {
1344
+ initialScrollPending.current = false;
1144
1345
  setActiveIndex(idx);
1145
1346
  virtualizer.scrollToIndex(idx, { align: "center" });
1146
- initialScrollDone.current = true;
1147
1347
  }
1148
- }, [value, filteredItems, getItemValue, virtualizer]);
1348
+ }, [open, value, searchValue, filteredItems, getItemValue, virtualizer]);
1149
1349
 
1150
1350
  // Only auto-scroll when the active index changed from keyboard navigation,
1151
1351
  // not from pointer hover (the user's mouse is already at the item they see).
@@ -1262,6 +1462,13 @@ function ComboboxVirtualListInner<T>(
1262
1462
  return () => setActiveDescendantId(undefined);
1263
1463
  }, [activeItemId, setActiveDescendantId]);
1264
1464
 
1465
+ // The input must control the listbox its active descendant lives in
1466
+ const listboxId = `${idPrefix}listbox`;
1467
+ React.useEffect(() => {
1468
+ setListboxId(listboxId);
1469
+ return () => setListboxId(undefined);
1470
+ }, [listboxId, setListboxId]);
1471
+
1265
1472
  // Always render the listbox container so empty state stays within the
1266
1473
  // correct ARIA structure (role="listbox" wraps renderEmpty).
1267
1474
  if (filteredItems.length === 0) {
@@ -1274,6 +1481,7 @@ function ComboboxVirtualListInner<T>(
1274
1481
  )}
1275
1482
  data-hook={dataHook}
1276
1483
  data-slot="combobox-virtual-list"
1484
+ id={listboxId}
1277
1485
  role="listbox"
1278
1486
  >
1279
1487
  {renderEmpty}
@@ -1291,6 +1499,7 @@ function ComboboxVirtualListInner<T>(
1291
1499
  )}
1292
1500
  data-hook={dataHook}
1293
1501
  data-slot="combobox-virtual-list"
1502
+ id={listboxId}
1294
1503
  role="listbox"
1295
1504
  >
1296
1505
  <div