refactor(playground-ui): migrate Combobox to @base-ui/react (#12377)

mfrachet · claude · web-flow · commit 95df5c1fbab9 · 2026-01-27T21:18:12.000+01:00
Refactored the Combobox component to use `@base-ui/react` instead of a
custom implementation built on Radix UI Popover.

This removes ~70 lines of manual keyboard navigation and state
management code since Base UI handles it automatically. The props
interface and styling remain identical.

**Before (custom Popover implementation):**
```tsx
const [open, setOpen] = useState(false);
const [search, setSearch] = useState('');
const [highlightedIndex, setHighlightedIndex] = useState(0);
// ...keyboard handlers, scroll management, etc.
```

**After (Base UI):**
```tsx
&lt;BaseCombobox.Root items={options} value={selectedOption} onValueChange={handleSelect}&gt;
  &lt;BaseCombobox.Trigger&gt;...&lt;/BaseCombobox.Trigger&gt;
  &lt;BaseCombobox.Portal&gt;
    &lt;BaseCombobox.Popup&gt;
      &lt;BaseCombobox.Input /&gt;
      &lt;BaseCombobox.List&gt;{(option) =&gt; &lt;BaseCombobox.Item /&gt;}&lt;/BaseCombobox.List&gt;
    &lt;/BaseCombobox.Popup&gt;
  &lt;/BaseCombobox.Portal&gt;
&lt;/BaseCombobox.Root&gt;
```

Tested all 8 Storybook stories - dropdown, search filtering, selection
with checkmark, and disabled state all work correctly.

&lt;!-- This is an auto-generated comment: release notes by coderabbit.ai
--&gt;
## Summary by CodeRabbit

* **Refactor**
* The Combobox component has been internally refactored to simplify
implementation while preserving the same appearance, props, and
keyboard/accessibility behavior. Existing integrations remain fully
compatible and no user-facing changes are expected.

&lt;sub&gt;✏️ Tip: You can customize this high-level summary in your review
settings.&lt;/sub&gt;
&lt;!-- end of auto-generated comment: release notes by coderabbit.ai --&gt;

---------

Co-authored-by: Claude Opus 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/.changeset/combobox-base-ui-refactor.md b/.changeset/combobox-base-ui-refactor.md
@@ -0,0 +1,5 @@
+---
+"@mastra/playground-ui": minor
+---
+
+Refactored Combobox component to use @base-ui/react instead of custom Radix UI Popover implementation. This removes ~70 lines of manual keyboard navigation code while preserving the same props interface and styling.
diff --git a/packages/playground-ui/package.json b/packages/playground-ui/package.json
@@ -57,13 +57,13 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@assistant-ui/react": "^0.11.47",
-    "cmdk": "^1.1.1",
     "@assistant-ui/react-markdown": "^0.11.6",
     "@assistant-ui/react-syntax-highlighter": "^0.11.6",
     "@assistant-ui/react-ui": "^0.2.1",
     "@autoform/core": "^3.0.0",
     "@autoform/react": "^4.0.0",
     "@autoform/zod": "^4.0.0",
+    "@base-ui/react": "^1.1.0",
     "@codemirror/lang-javascript": "^6.2.2",
     "@codemirror/lang-json": "^6.0.2",
     "@codemirror/lang-markdown": "^6.5.0",
@@ -97,6 +97,7 @@
     "@uiw/codemirror-theme-github": "^4.25.3",
     "@uiw/react-codemirror": "^4.23.14",
     "@xyflow/react": "^12.9.3",
+    "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "prettier": "^3.6.2",
     "prism-react-renderer": "^2.4.1",
diff --git a/packages/playground-ui/src/ds/components/Combobox/combobox.tsx b/packages/playground-ui/src/ds/components/Combobox/combobox.tsx
@@ -1,9 +1,9 @@
-import { Button as DSButton } from '@/ds/components/Button/Button';
-import { Popover, PopoverContent, PopoverTrigger } from '@/ds/components/Popover';
+import { Combobox as BaseCombobox } from '@base-ui/react/combobox';
+import { buttonVariants } from '@/ds/components/Button/Button';
 import { cn } from '@/lib/utils';
 import { Check, ChevronsUpDown, Search } from 'lucide-react';
 import * as React from 'react';
-import { type FormElementSize, formElementFocus } from '@/ds/primitives/form-element';
+import { type FormElementSize } from '@/ds/primitives/form-element';
 import { transitions } from '@/ds/primitives/transitions';
 
 export type ComboboxOption = {
@@ -36,173 +36,74 @@ export function Combobox({
   variant = 'default',
   size = 'md',
 }: ComboboxProps) {
-  const [open, setOpen] = React.useState(false);
-  const [search, setSearch] = React.useState('');
-  const [highlightedIndex, setHighlightedIndex] = React.useState(0);
-  const triggerRef = React.useRef<HTMLButtonElement>(null);
-  const [triggerWidth, setTriggerWidth] = React.useState<number | undefined>(undefined);
-  const inputRef = React.useRef<HTMLInputElement>(null);
-  const listRef = React.useRef<HTMLDivElement>(null);
+  const selectedOption = options.find(option => option.value === value) ?? null;
 
-  const selectedOption = options.find(option => option.value === value);
-
-  const handleSelect = (optionValue: string) => {
-    onValueChange?.(optionValue);
-    setOpen(false);
-    setSearch('');
-    setHighlightedIndex(0);
-  };
-
-  React.useEffect(() => {
-    if (triggerRef.current) {
-      setTriggerWidth(triggerRef.current.offsetWidth);
-    }
-  }, [open]);
-
-  React.useEffect(() => {
-    if (open && inputRef.current) {
-      inputRef.current.focus();
-    }
-  }, [open]);
-
-  const filteredOptions = React.useMemo(() => {
-    if (!search) return options;
-    return options.filter(option => option.label.toLowerCase().includes(search.toLowerCase()));
-  }, [options, search]);
-
-  React.useEffect(() => {
-    setHighlightedIndex(0);
-  }, [filteredOptions]);
-
-  const handleKeyDown = (e: React.KeyboardEvent) => {
-    if (!open) return;
-
-    switch (e.key) {
-      case 'ArrowDown':
-        e.preventDefault();
-        setHighlightedIndex(prev => (prev < filteredOptions.length - 1 ? prev + 1 : prev));
-        break;
-      case 'ArrowUp':
-        e.preventDefault();
-        setHighlightedIndex(prev => (prev > 0 ? prev - 1 : prev));
-        break;
-      case 'Enter':
-        e.preventDefault();
-        if (filteredOptions[highlightedIndex]) {
-          handleSelect(filteredOptions[highlightedIndex].value);
-        }
-        break;
-      case 'Escape':
-        e.preventDefault();
-        setOpen(false);
-        setSearch('');
-        break;
-      case 'Home':
-        e.preventDefault();
-        setHighlightedIndex(0);
-        break;
-      case 'End':
-        e.preventDefault();
-        setHighlightedIndex(filteredOptions.length - 1);
-        break;
+  const handleSelect = (item: ComboboxOption | null) => {
+    if (item) {
+      onValueChange?.(item.value);
     }
   };
 
-  React.useEffect(() => {
-    if (listRef.current && highlightedIndex >= 0) {
-      const highlightedElement = listRef.current.children[highlightedIndex] as HTMLElement;
-      if (highlightedElement) {
-        highlightedElement.scrollIntoView({ block: 'nearest' });
-      }
-    }
-  }, [highlightedIndex]);
-
   return (
-    <Popover open={open} onOpenChange={setOpen}>
-      <PopoverTrigger asChild>
-        <DSButton
-          ref={triggerRef}
-          role="combobox"
-          aria-expanded={open}
-          variant={variant}
-          size={size}
-          className={cn('w-full justify-between', className)}
-          disabled={disabled}
-        >
-          <span className="truncate">{selectedOption ? selectedOption.label : placeholder}</span>
-          <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
-        </DSButton>
-      </PopoverTrigger>
-      <PopoverContent className="p-0 w-fit" align="start">
-        <div
-          className={cn(
-            'flex h-full w-full flex-col overflow-hidden rounded-md bg-surface3 text-neutral5',
-            'shadow-elevated',
-            'animate-in fade-in-0 zoom-in-95 duration-150',
-          )}
-        >
-          <div className={cn('flex items-center border-b border-border1 px-3 py-2', transitions.colors)}>
-            <Search className={cn('mr-2 h-4 w-4 shrink-0 text-neutral3', transitions.colors)} />
-            <input
-              ref={inputRef}
-              className={cn(
-                'flex h-8 w-full rounded-md bg-transparent py-1 text-sm',
-                'placeholder:text-neutral3 disabled:cursor-not-allowed disabled:opacity-50',
-                'outline-none',
-                transitions.colors,
-              )}
-              placeholder={searchPlaceholder}
-              value={search}
-              onChange={e => setSearch(e.target.value)}
-              onKeyDown={handleKeyDown}
-              role="combobox"
-              aria-autocomplete="list"
-              aria-controls="combobox-options"
-              aria-expanded={open}
-            />
-          </div>
-          <div
-            ref={listRef}
-            id="combobox-options"
-            role="listbox"
-            className="max-h-dropdown-max-height overflow-y-auto overflow-x-hidden p-1"
-          >
-            {filteredOptions.length === 0 ? (
-              <div className="py-6 text-center text-sm text-neutral3">{emptyText}</div>
-            ) : (
-              filteredOptions.map((option, index) => {
-                const isSelected = value === option.value;
-                const isHighlighted = index === highlightedIndex;
-                return (
-                  <div
-                    key={option.value}
-                    role="option"
-                    aria-selected={isSelected}
-                    className={cn(
-                      'relative flex cursor-pointer select-none items-center rounded-sm px-2 py-1.5 text-sm',
-                      transitions.colors,
-                      'hover:bg-surface5 hover:text-neutral5',
-                      isHighlighted && 'bg-surface5 text-neutral5',
-                      isSelected && !isHighlighted && 'bg-accent1Dark text-accent1',
-                    )}
-                    onClick={() => handleSelect(option.value)}
-                    onMouseEnter={() => setHighlightedIndex(index)}
-                  >
-                    <Check
-                      className={cn(
-                        'mr-2 h-4 w-4',
-                        transitions.opacity,
-                        isSelected ? 'opacity-100 text-accent1' : 'opacity-0',
-                      )}
-                    />
-                    {option.label}
-                  </div>
-                );
-              })
+    <BaseCombobox.Root items={options} value={selectedOption} onValueChange={handleSelect} disabled={disabled}>
+      <BaseCombobox.Trigger className={cn(buttonVariants({ variant, size }), 'w-full justify-between', className)}>
+        <span className="truncate">
+          <BaseCombobox.Value placeholder={placeholder} />
+        </span>
+        <ChevronsUpDown className="ml-2 h-4 w-4 shrink-0 opacity-50" />
+      </BaseCombobox.Trigger>
+
+      <BaseCombobox.Portal>
+        <BaseCombobox.Positioner align="start" sideOffset={4}>
+          <BaseCombobox.Popup
+            className={cn(
+              'min-w-[var(--anchor-width)] w-max rounded-md bg-surface3 text-neutral5',
+              'shadow-elevated',
+              'origin-[var(--transform-origin)]',
+              'transition-[transform,scale,opacity] duration-150 ease-out',
+              'data-[starting-style]:scale-95 data-[starting-style]:opacity-0',
+              'data-[ending-style]:scale-95 data-[ending-style]:opacity-0',
             )}
-          </div>
-        </div>
-      </PopoverContent>
-    </Popover>
+          >
+            <div className={cn('flex items-center border-b border-border1 px-3 py-2', transitions.colors)}>
+              <Search className={cn('mr-2 h-4 w-4 shrink-0 text-neutral3', transitions.colors)} />
+              <BaseCombobox.Input
+                className={cn(
+                  'flex h-8 w-full rounded-md bg-transparent py-1 text-sm',
+                  'placeholder:text-neutral3 disabled:cursor-not-allowed disabled:opacity-50',
+                  'outline-none',
+                  transitions.colors,
+                )}
+                placeholder={searchPlaceholder}
+              />
+            </div>
+            <BaseCombobox.Empty className="[&:not(:empty)]:block hidden py-6 text-center text-sm text-neutral3">
+              {emptyText}
+            </BaseCombobox.Empty>
+            <BaseCombobox.List className="max-h-dropdown-max-height overflow-y-auto overflow-x-hidden p-1">
+              {(option: ComboboxOption) => (
+                <BaseCombobox.Item
+                  key={option.value}
+                  value={option}
+                  className={cn(
+                    'relative flex cursor-pointer select-none items-center rounded-sm px-2 py-1.5 text-sm',
+                    transitions.colors,
+                    'data-[highlighted]:bg-surface5 data-[highlighted]:text-neutral5',
+                    'data-[selected]:bg-accent1Dark data-[selected]:text-accent1',
+                  )}
+                >
+                  <span className="mr-2 flex h-4 w-4 shrink-0 items-center justify-center">
+                    <BaseCombobox.ItemIndicator>
+                      <Check className={cn('h-4 w-4 text-accent1', transitions.opacity)} />
+                    </BaseCombobox.ItemIndicator>
+                  </span>
+                  <span className="whitespace-nowrap">{option.label}</span>
+                </BaseCombobox.Item>
+              )}
+            </BaseCombobox.List>
+          </BaseCombobox.Popup>
+        </BaseCombobox.Positioner>
+      </BaseCombobox.Portal>
+    </BaseCombobox.Root>
   );
 }
diff --git a/packages/playground/src/App.tsx b/packages/playground/src/App.tsx
@@ -76,7 +76,7 @@ const paths: LinkComponentProviderProps['paths'] = {
 
 const RootLayout = () => {
   const navigate = useNavigate();
-  const frameworkNavigate = (path: string) => navigate(path);
+  const frameworkNavigate = (path: string) => navigate(path, { viewTransition: true });
 
   return (
     <LinkComponentProvider Link={Link} navigate={frameworkNavigate} paths={paths}>
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@mastra/playground-ui": minor
 +---
++
 +Refactored Combobox component to use @base-ui/react instead of custom Radix UI Popover implementation. This removes ~70 lines of manual keyboard navigation code while preserving the same props interface and styling.