[Feature] Combobox: match shadcn (Base UI + vega)

Merged
CI
19d ago
+2121-1218

Rewrites Combobox to follow shadcn's Base UI combobox with the vega style. This is a breaking change: the parts and their names change, and the old API has no aliases.

The audit on main found the old structure far from shadcn (radio buttons inside the list, a bordered popover with no animation, a search row with a magnifier icon). It also found focus that stayed on the trigger after opening, so the arrow keys did nothing until you clicked the search field, an invalid role="popover", and a role=combobox wrapper with no aria-expanded. ComboboxInputTrigger, ComboboxBadgeTrigger, ComboboxBadge and ComboboxClearButton shipped without the controller code they call, so they never worked.

Migration

BeforeAfter
Combobox(term:, placement:)Combobox(name:, multiple:, term:, disabled:, required:); placement moves to ComboboxContent(side:, align:, side_offset:, align_offset:)
ComboboxTrigger(placeholder: "...")ComboboxTrigger { ComboboxValue(placeholder: "...") }
ComboboxPopoverComboboxContent
ComboboxSearchInput(placeholder:)ComboboxInput(placeholder:, show_trigger: false) inside ComboboxContent
ComboboxEmptyStateComboboxEmpty
ComboboxListGroup(label: "Fruits")ComboboxGroup { ComboboxLabel { "Fruits" } ... }, plus ComboboxSeparator
ComboboxItem { ComboboxRadio(name:, value:); span { "Apple" } }ComboboxItem(value: "apple") { "Apple" } (name comes from the root)
ComboboxCheckboxCombobox(multiple: true) makes every item a checkbox
CheckboxGroup(required: true) around the itemsCombobox(multiple: true, required: true)
ComboboxToggleAllCheckboxComboboxToggleAll { "Select all" }
ComboboxInputTriggerComboboxInput(placeholder:, show_clear:) outside the content
ComboboxBadgeTrigger, ComboboxBadge, ComboboxClearButtonComboboxChips(max:) { ComboboxChipsInput }

Each item still holds a native radio or checkbox (visually hidden, out of the tab order), so forms submit the selection as before and required: and FormField keep working. FormField's aria-invalid and aria-describedby are copied onto the input or trigger people see. The hidden inputs are the one structural difference from Base UI.

Three extras have no shadcn counterpart: ComboboxToggleAll (works with chips and in a popup), term: ("4 fruits" instead of every name) and ComboboxChips(max:), which collapses the chips into one "100 frameworks" chip past the cap. All four differences are registered in audit/divergences/combobox.yml.

The controller follows the APG combobox pattern like Base UI: focus stays in the input, the active option goes through aria-activedescendant, the selected item is highlighted on open, Home and End jump to the ends, Escape and outside clicks return focus to the trigger, and the popup fades and zooms in and out over 100 ms. The popup is a popover="manual" element (top layer) positioned by Floating UI; with popover="auto", clicking the input that opens it would close it.

Combobox now depends on Button (dependencies.yml). The Form docs example and the MCP registry are updated. A Codex review raised nine issues (multiple required: ignored, errors only on the hidden inputs, Clear out of the tab order, chevron focus, Turbo morph state and ids, disabled items removed by Backspace, two listener/highlight leaks); all are fixed here.

Screenshots

Audit fixture: shadcn's "Combobox in Popup" example, 1280×800, same strings on both sides.

Closed (light)

Open (light)

Open (dark)

Option active (light)

Test steps

  1. cd gem && bundle exec rake (tests and standardrb).
  2. cd docs && bin/dev, open /docs/combobox:
    • Basic: click the input, type "re", press ArrowDown and Enter. The input shows "Remix" and the popup closes. The chevron opens it with focus in the input.
    • With clear button: the × clears the value; Tab from the input reaches it.
    • With groups: type "carr". The Fruits group hides; type more for the empty message.
    • Disabled items: ArrowDown skips SvelteKit and Remix.
    • In a popup: open, use the arrows, Home/End, Enter, Escape. Focus goes back to the button.
    • Multiple: pick items, remove chips with × and with Backspace.
    • Select all: select all, the chips collapse into "5 frameworks"; its × clears everything.
    • Multiple in a popup: "Select all", then deselect one; the trigger reads "3 fruits".
    • Form: submit empty. Both fields turn red with "Pick a framework" and "Pick at least one".
  3. /docs/form: the Combobox example validates as required.
  4. Optional: /shadcn-audit worktree/combobox reproduces the checklist below.
shadcn audit on main (before)
shadcn audit  ruby-ui/ruby_ui
  base 7e65e61f  head 7e65e61f  shadcn 4aaea19d
⚠️ Environment  font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (light)
⚠️ Environment  font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (dark)
✅ Theme  neutral tokens match shadcn
Combobox  (ref: bases/base/ui/combobox.tsx + style-vega.css @ 4aaea19d)
  ❌ Look       background-color: oklch(0.145 0 0); background-color: oklch(0.269 0 0); border-bottom-color: oklch(0.922 0 0); border-left-color: oklch(0.922 0 0); border-right-color: oklch(0.922 0 0); border-top-color: oklch(0.922 0 0); box-shadow: none; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklch(0.145 0 0) 0px 0px 0px 2px, oklch(0.556 0 0) 0px 0px 0px 4px, rgba(0, 0, 0, 0) 0px 0px 0px 0px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklch(1 0 0) 0px 0px 0px 2px, oklch(0.708 0 0) 0px 0px 0px 4px, rgba(0, 0, 0, 0) 0px 0px 0px 0px; color: oklch(0.205 0 0); column-gap: normal; display: flex; gap: normal; padding-bottom: 8px; padding-left: 16px; padding-right: 16px; padding-top: 8px; row-gap: normal
               vega: background-color: oklab(1 0 0 / 0.045); background-color: oklab(1 0 0 / 0.075); border-bottom-color: oklch(0.708 0 0); border-left-color: oklch(0.708 0 0); border-right-color: oklch(0.708 0 0); border-top-color: oklch(0.708 0 0); box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.556 0 0 / 0.5) 0px 0px 0px 3px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.708 0 0 / 0.5) 0px 0px 0px 3px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px; color: oklch(0.145 0 0); column-gap: 6px; display: inline-flex; gap: 6px; padding-bottom: 0px; padding-left: 10px; padding-right: 10px; padding-top: 0px; row-gap: 6px
               ComboboxTrigger — closed/light, open/light, focus/light, after-esc/light, closed/dark, open/dark, focus/dark, after-esc/dark — RubyUI: border border-input bg-background px-4 h-9 hover:bg-accent, focus ring-2 ring-offset-2. shadcn renders it as Button variant=outline (vega cn-button outline: border-border bg-background dark:bg-input/30 shadow-xs px-2.5, focus-visible:ring-3 ring-ring/50), w-64 justify-between font-normal. Requested: render via Button(variant: :outline) + justify-between font-normal.
               ↳ computed styles (shadcn-audit collect)
  ❌ Look       background-color: oklch(0.145 0 0); border-bottom-left-radius: 10px; border-bottom-right-radius: 10px; border-bottom-width: 1px; border-left-width: 1px; border-right-width: 1px; border-top-left-radius: 10px; border-top-right-radius: 10px; border-top-width: 1px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0.1) 0px 10px 15px -3px, rgba(0, 0, 0, 0.1) 0px 4p…; color: rgb(0, 0, 0)
               vega: background-color: oklch(0.205 0 0); border-bottom-left-radius: 8px; border-bottom-right-radius: 8px; border-bottom-width: 0px; border-left-width: 0px; border-right-width: 0px; border-top-left-radius: 8px; border-top-right-radius: 8px; border-top-width: 0px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.145 0 0 / 0.1) 0px 0px 0px 1px, rgba(0, 0, 0, 0.1) 0px 4px 6px -1px, rgba(0, 0, 0, 0.1) 0p…; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, oklab(0.985 0 0 / 0.1) 0px 0px 0px 1px, rgba(0, 0, 0, 0.1) 0px 4px 6px -1px, rgba(0, 0, 0, 0.1) 0p…; color: oklch(0.145 0 0); color: oklch(0.985 0 0)
               ComboboxPopover — open/light, open/dark — RubyUI: border bg-background shadow-lg rounded-lg, no padding. shadcn cn-combobox-content: bg-popover ring-1 ring-foreground/10 shadow-md rounded-md max-h-72 min-w-36, width = anchor + spacing(7) (style-vega.css:296). Requested: ComboboxContent with vega classes, data-open/closed fade+zoom animation, min-width trigger+28px.
               ↳ computed styles (shadcn-audit collect)
  ❌ Look       border-bottom-color: oklch(0.551 0.027 264.364); border-bottom-left-radius: 8px; border-bottom-right-radius: 8px; border-bottom-style: none; border-left-color: oklch(0.551 0.027 264.364); border-left-style: none; border-right-color: oklch(0.551 0.027 264.364); border-right-style: none; border-top-color: oklch(0.551 0.027 264.364); border-top-left-radius: 8px; border-top-right-radius: 8px; border-top-style: none; box-shadow: none; color: oklch(0.556 0 0); color: oklch(0.708 0 0); display: flex; outline-color: oklab(0.556 0 0 / 0.5); outline-color: oklab(0.708 0 0 / 0.5); outline-offset: 0px; outline-width: 3px; padding-bottom: 12px; padding-left: 12px; padding-right: 12px; padding-top: 12px
               vega: border-bottom-color: oklch(0.556 0 0); border-bottom-color: oklch(0.708 0 0); border-bottom-left-radius: 0px; border-bottom-right-radius: 0px; border-bottom-style: solid; border-left-color: oklch(0.556 0 0); border-left-color: oklch(0.708 0 0); border-left-style: solid; border-right-color: oklch(0.556 0 0); border-right-color: oklch(0.708 0 0); border-right-style: solid; border-top-color: oklch(0.556 0 0); border-top-color: oklch(0.708 0 0); border-top-left-radius: 0px; border-top-right-radius: 0px; border-top-style: solid; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgb(255, 255, 255) 0px 0px 0px 0px, oklab(0.556 0 0 / 0.5) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px; box-shadow: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgb(255, 255, 255) 0px 0px 0px 0px, oklab(0.708 0 0 / 0.5) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px; color: oklch(0.145 0 0); color: oklch(0.985 0 0); display: block; outline-color: rgba(0, 0, 0, 0); outline-offset: 2px; outline-width: 2px; padding-bottom: 4px; padding-left: 10px; padding-right: 6px; padding-top: 4px
               ComboboxSearchInput — open/light, open/dark — RubyUI: full-width row with border-b, magnifier icon, input h-9 px-0. shadcn: InputGroup inside the content, *:data-[slot=input-group]:m-1 mb-0 h-8 bg-input/30 border-input/30 shadow-none rounded-md, no icon (style-vega.css:297). Requested: ComboboxInput as an InputGroup (no icon), role=combobox, aria-controls, aria-activedescendant.
               ↳ computed styles (shadcn-audit collect)
  ❌ Look       column-gap: 4px; display: flex; gap: 4px; row-gap: 4px
               vega: column-gap: normal; display: block; gap: normal; row-gap: normal
               ComboboxList — open/light, open/dark — RubyUI: flex flex-col gap-1 p-1 max-h-72. shadcn cn-combobox-list: block, p-1 scroll-py-1 no-scrollbar max-h-[min(72-9 spacing, available-height)] (style-vega.css:325). Requested: ComboboxGroup + ComboboxLabel + ComboboxSeparator; list block p-1.
               ↳ computed styles (shadcn-audit collect)
  ⏸ Look       ComboboxEmptyState: no visible element in any reached state. Reached by hand (typed 'zzz', both sides render it): RubyUI py-6 text-center text-sm, no muted color; shadcn cn-combobox-empty py-2 text-muted-foreground (style-vega.css:321). Requested: ComboboxEmpty with vega classes.
  ❌ Look       border-bottom-width: 1px; column-gap: 4px; display: flex; gap: 4px; padding-bottom: 4px; padding-top: 4px; row-gap: 4px
               vega: border-bottom-width: 0px; column-gap: normal; display: block; gap: normal; padding-bottom: 0px; padding-top: 0px; row-gap: normal
               ComboboxListGroup — open/light, open/dark — RubyUI: flex flex-col py-1 gap-1 border-b, label drawn by ::before. shadcn cn-combobox-group has no classes; separation comes from ComboboxSeparator (bg-border -mx-1 my-1 h-px). Requested: ComboboxGroup + ComboboxLabel + ComboboxSeparator; list block p-1.
               ↳ computed styles (shadcn-audit collect)
  ❌ Look       color: oklch(0.145 0 0); padding-bottom: 8px; padding-right: 8px; padding-top: 8px
               vega: color: oklch(0.205 0 0); padding-bottom: 6px; padding-right: 32px; padding-top: 6px
               ComboboxItem — open/light, open/dark — RubyUI: label p-2 gap-2 rounded-sm cursor-pointer, has-[:checked]:bg-accent. shadcn cn-combobox-item: py-1.5 pr-8 pl-2 gap-2 rounded-sm cursor-default, data-highlighted:bg-accent, check indicator absolute right-2 (style-vega.css:309, 317). Requested: check indicator on the right, aria-selected; native radio/checkbox kept sr-only for the form.
               ↳ computed styles (shadcn-audit collect)
  ⏸ Look       properties: font-family, height, width
               ComboboxTrigger, ComboboxPopover, ComboboxSearchInput, ComboboxList, ComboboxListGroup, ComboboxItem — explained by environment diff: font. font-family is the environment font diff (Inter Variable stack); height/width come from the fixture wrapper (div.w-64 vs Button w-64) and from item padding. Requested: render via Button(variant: :outline) + justify-between font-normal.
  ⚠️ ARIA       aria-controls: (none); aria-haspopup: listbox; snapshot: only here: - button "Apple" [expanded]: |   - text: Apple |   - img; snapshot: only here: - button "Apple": |   - text: Apple |   - img
               shadcn: aria-controls: resolves; aria-haspopup: dialog; snapshot: only here: - combobox [expanded]: Apple; snapshot: only here: - combobox: Apple
               ComboboxTrigger — closed/light, open/light, focus/light, after-esc/light, closed/dark, open/dark, focus/dark, after-esc/dark Requested: render via Button(variant: :outline) + justify-between font-normal.
               ↳ accessibility tree (shadcn-audit collect)
  ⚠️ ARIA       snapshot: only here: - img | - searchbox "Search" | - listbox: |     - text: Fruits |     - option "Apple": |       - radio "Apple" [checked] |       - text: Apple |     - option "Banana": |       - radio "Bana…
               shadcn: snapshot: only here: - dialog: |     - combobox "Search" [expanded] |     - group |   - listbox: |     - group "Fruits": |       - option "Apple" [selected] |       - option "Banana" |       - option "Blueberry…
               ComboboxPopover — open/light, open/dark Requested: ComboboxContent with vega classes, data-open/closed fade+zoom animation, min-width trigger+28px.
               ↳ accessibility tree (shadcn-audit collect)
  ⚠️ ARIA       aria-controls: (none); aria-expanded: (none); aria-haspopup: (none); snapshot: only here: - searchbox "Search"
               shadcn: aria-controls: resolves; aria-expanded: true; aria-haspopup: listbox; snapshot: only here: - combobox "Search" [expanded]
               ComboboxSearchInput — open/light, open/dark Requested: ComboboxInput as an InputGroup (no icon), role=combobox, aria-controls, aria-activedescendant.
               ↳ accessibility tree (shadcn-audit collect)
  ⚠️ ARIA       snapshot: only here:   - group: |     - text: Fruits |     - option "Apple": |       - radio "Apple" [checked] |       - text: Apple |     - option "Banana": |       - radio "Banana" |       - text: Banana |   …
               shadcn: snapshot: only here:   - group "Fruits": |     - option "Apple" [selected] |     - option "Banana" |     - option "Blueberry" |     - option "Grapes" |     - option "Pineapple"
               ComboboxList — open/light, open/dark Requested: ComboboxGroup + ComboboxLabel + ComboboxSeparator; list block p-1.
               ↳ accessibility tree (shadcn-audit collect)
  ⏸ ARIA       ComboboxEmptyState: no visible element in any reached state. Reached by hand: both render the empty text; shadcn's is inside the dialog, outside the listbox. Requested: ComboboxEmpty with vega classes.
  ⚠️ ARIA       snapshot: only here: - group: |   - text: Fruits |   - option "Apple": |     - radio "Apple" [checked] |     - text: Apple |   - option "Banana": |     - radio "Banana" |     - text: Banana |   - option "Bluebe…
               shadcn: snapshot: only here: - group "Fruits": |   - option "Apple" [selected] |   - option "Banana" |   - option "Blueberry" |   - option "Grapes" |   - option "Pineapple"
               ComboboxListGroup — open/light, open/dark Requested: ComboboxGroup + ComboboxLabel + ComboboxSeparator; list block p-1.
               ↳ accessibility tree (shadcn-audit collect)
  ⚠️ ARIA       snapshot: only here: - option "Apple": |   - radio "Apple" [checked] |   - text: Apple; snapshot: only here: - option "Banana": |   - radio "Banana" |   - text: Banana; snapshot: only here: - option "Blueberry": |   - radio "Blueberry" |   - text: Blueberry; snapshot: only here: - option "Grapes": |   - radio "Grapes" |   - text: Grapes; snapshot: only here: - option "Pineapple": |   - radio "Pineapple" |   - text: Pineapple
               shadcn: snapshot: only here: - option "Apple" [selected]; snapshot: only here: - option "Banana"; snapshot: only here: - option "Blueberry"; snapshot: only here: - option "Grapes"; snapshot: only here: - option "Pineapple"
               ComboboxItem — open/light, open/dark Requested: check indicator on the right, aria-selected; native radio/checkbox kept sr-only for the form.
               ↳ accessibility tree (shadcn-audit collect)
  ❌ HTML       Combobox: div[role=combobox] wrapping trigger + popover
               shadcn: Combobox root renders no element; the trigger button carries role=combobox
               RubyUI puts the combobox role on a wrapper, not on the control that opens the list. Requested: root without role; role=combobox on the trigger/input; popup role=dialog.
               ↳ bases/base/ui/combobox.tsx:16
  ❌ HTML       ComboboxPopover: div[popover][role=popover], inline next to the trigger
               shadcn: Portal > Positioner > Popup[role=dialog][data-slot=combobox-content]
               Requested: ComboboxContent with vega classes, data-open/closed fade+zoom animation, min-width trigger+28px.
               ↳ bases/base/ui/combobox.tsx:101
  ❌ HTML       ComboboxSearchInput: div.border-b > svg(search) + input[type=search][role=searchbox]
               shadcn: InputGroup > input[role=combobox][data-slot=input-group-control] (ComboboxInput showTrigger={false})
               Requested: ComboboxInput as an InputGroup (no icon), role=combobox, aria-controls, aria-activedescendant.
               ↳ bases/base/ui/combobox.tsx:66
  ❌ HTML       ComboboxItem: label[role=option] > input[type=radio] (visible) + span
               shadcn: div[role=option][data-slot=combobox-item] > text + span.cn-combobox-item-indicator (check icon, right)
               RubyUI shows a radio/checkbox on the left; shadcn shows a check on the right only on the selected item. Requested: check indicator on the right, aria-selected; native radio/checkbox kept sr-only for the form.
               ↳ bases/base/ui/combobox.tsx:151
  ❌ HTML       ComboboxListGroup(label:) draws the label with ::before content: attr(label)
               shadcn: ComboboxGroup > ComboboxLabel (div[data-slot=combobox-label], text-muted-foreground px-2 py-1.5 text-xs)
               Pseudo-element text isn't a group name: the ARIA snapshot shows an unnamed group on RubyUI. Requested: ComboboxGroup + ComboboxLabel + ComboboxSeparator; list block p-1.
               ↳ bases/base/ui/combobox.tsx:192
  ❌ HTML       no part
               shadcn: ComboboxSeparator, ComboboxValue, ComboboxCollection, ComboboxInput (input as trigger), ComboboxChips/Chip/ChipsInput
               Missing parts. ComboboxInputTrigger / ComboboxBadgeTrigger / ComboboxBadge / ComboboxClearButton exist but are not wired (see Behavior). Requested: implement ComboboxInput + ComboboxChips/Chip/ChipsInput; delete InputTrigger/BadgeTrigger/Badge/ClearButton.
               ↳ bases/base/ui/combobox.tsx:221
  ❌ Props      Combobox(placement: 'bottom-start'), offset fixed at 4px
               shadcn: ComboboxContent side='bottom' sideOffset=6 align='start' alignOffset=0 anchor
               placement covers side+align on the root; no sideOffset/alignOffset/anchor. Requested: side/side_offset/align/align_offset on ComboboxContent.
               ↳ bases/base/ui/combobox.tsx:101
  ❌ Props      ComboboxInputTrigger(placeholder:), no disabled/show_trigger/show_clear
               shadcn: ComboboxInput showTrigger showClear disabled
               Requested: implement ComboboxInput + ComboboxChips/Chip/ChipsInput; delete InputTrigger/BadgeTrigger/Badge/ClearButton.
               ↳ bases/base/ui/combobox.tsx:66
  ❌ Props      ComboboxBadge: no remove control
               shadcn: ComboboxChip showRemove (ChipRemove button)
               Requested: implement ComboboxInput + ComboboxChips/Chip/ChipsInput; delete InputTrigger/BadgeTrigger/Badge/ClearButton.
               ↳ bases/base/ui/combobox.tsx:248
  ⚠️ Behavior   open: focus stays on the trigger button; ArrowDown/typing/Enter do nothing until the user clicks the search input
               shadcn: open: focus moves to the search input[role=combobox]; ArrowDown/typing/Enter work at once
               Browser run, 1280x800. ComboboxPopover has autofocus on a div, which doesn't move focus to the input. Requested: match shadcn (focus into input, aria-activedescendant, selected highlighted on open, focus back to trigger).
               ↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
  ⚠️ Behavior   open: no option active; active option = aria-current + ring on the label
               shadcn: open: selected item (Apple) highlighted; active option = data-highlighted + input aria-activedescendant
               Requested: match shadcn (focus into input, aria-activedescendant, selected highlighted on open, focus back to trigger).
               ↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#roles_states_properties
  ⚠️ Behavior   outside click closes; focus drops to body
               shadcn: outside click closes; focus returns to the trigger
               Requested: match shadcn (focus into input, aria-activedescendant, selected highlighted on open, focus back to trigger).
               ↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
  ✅ Behavior   typing filters (b → Banana, Blueberry), 'zzz' shows the empty state, ArrowDown+Enter selects Blueberry and closes, Esc closes and returns focus to the trigger
               Once focus is in the search input.
               ↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
  ⏸ Behavior   ComboboxInputTrigger, ComboboxBadgeTrigger, ComboboxClearButton
               shadcn: ComboboxInput, ComboboxChips, ComboboxClear
               Not in the fixture. Static read: they wire targets/actions the controller doesn't declare (inputTrigger, badgeInput, badgeContainer, clearButton, clearAll, handleBadgeInputBackspace) and filterItems reads only searchInputTarget, so they can't work as shipped. Requested: implement ComboboxInput + ComboboxChips/Chip/ChipsInput; delete InputTrigger/BadgeTrigger/Badge/ClearButton.
  ⚠️ Animation  none (animation-name: none)
               shadcn: fade-in-0 zoom-in-95 slide-in-from-top-2, 100ms (data-open/data-closed)
               Requested: ComboboxContent with vega classes, data-open/closed fade+zoom animation, min-width trigger+28px.
               ↳ style-vega.css:297
  ✅ Native     popover attribute: top layer, light dismiss, Esc, focus back to the trigger — native
               Positioning still uses Floating UI (native-html.md: popover doesn't position; anchor positioning is a separate follow-up).
               ↳ https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/popover
  ✅ Native     radio/checkbox inputs carry the form value — native
               ↳ https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/radio
  ❌ Spec       Combobox wrapper div[role=combobox] has no aria-expanded
               shadcn: trigger button[role=combobox][aria-expanded]
               aria-expanded is a required state of combobox in ARIA 1.2; RubyUI only sets it on the inner button. Requested: root without role; role=combobox on the trigger/input; popup role=dialog.
               ↳ https://www.w3.org/TR/wai-aria-1.2/#combobox
  ❌ Spec       ComboboxPopover role="popover"
               shadcn: Popup role=dialog
               "popover" is not a WAI-ARIA role, so the role is ignored. Requested: ComboboxContent with vega classes, data-open/closed fade+zoom animation, min-width trigger+28px.
               ↳ https://www.w3.org/TR/html-aria/#docconformance
  ✅ Spec       —
               shadcn side conforms to the APG combobox pattern.
               ↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#roles_states_properties
  ⏸ Props      ComboboxToggleAllCheckbox, Combobox(term:)
               shadcn: no counterpart
               RubyUI-only extras. Suggested divergence: keep Select all and term:, register in audit/divergences/combobox.yml.
shadcn audit on this branch (after)
shadcn audit  ruby-ui/ruby_ui
  base 7e65e61f  head 02758cd3  shadcn 4aaea19d
⚠️ Environment  font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (light)
⚠️ Environment  font: "Inter Variable", "system-ui", -apple-system, "system-ui", "Segoe UI", Roboto, "Helvetica Neue", Arial, "sans-serif" vs "Inter Variable", sans-serif (dark)
✅ Theme  neutral tokens match shadcn
Combobox  (ref: bases/base/ui/combobox.tsx + style-vega.css @ 4aaea19d)
  ⏸ Look       ComboboxEmpty: no visible element in any reached state. Reached by hand (typed 'zzz'): see the ComboboxEmpty Look/ARIA lines below.
  ⏸ Look       properties: font-family, height
               ComboboxTrigger, ComboboxInput, ComboboxContent, ComboboxList, ComboboxGroup, ComboboxLabel, ComboboxItem — explained by environment diff: font. font-family is the environment font diff; height follows from it and from the fixture wrapper.
  ⏸ ARIA       ComboboxEmpty: no visible element in any reached state. Reached by hand (typed 'zzz'): see the ComboboxEmpty Look/ARIA lines below.
  ✅ ARIA       ComboboxTrigger, ComboboxInput, ComboboxContent, ComboboxList, ComboboxGroup, ComboboxLabel, ComboboxItem: accessibility tree matches
               ↳ accessibility tree (shadcn-audit collect)
  ✅ Look       ComboboxEmpty (typed 'zzz'): flex, py-2 (8px 0), 14px, oklch(0.556 0 0), 284x36
               Computed styles compared by hand; collect doesn't type into the input.
               ↳ style-vega.css:321
  ✅ ARIA       ComboboxEmpty: role=status aria-live=polite aria-atomic=true
               Read from the DOM on both sides.
               ↳ bases/base/ui/combobox.tsx:211
  ✅ HTML       Combobox root: div without role; trigger button[role=combobox]; popup [popover] role=dialog > input group (role=group) + empty + listbox > group > options
               The wrapper div holds the Stimulus controller and has no role.
               ↳ bases/base/ui/combobox.tsx:101
  ✅ HTML       ComboboxItem: div[role=option][aria-selected] + check span (aria-hidden) on the right; ComboboxLabel div[aria-hidden] named through aria-labelledby; ComboboxSeparator div[role=separator]
               ↳ bases/base/ui/combobox.tsx:151
  ✅ HTML       Visually hidden native radio/checkbox inside each item — intentional
               Server-rendered component: the checked inputs are the selection, so the form submits it and required:/FormField validation work natively.
               ↳ audit/divergences/combobox.yml
  ✅ HTML       ComboboxInput (input as trigger, show_trigger/show_clear), ComboboxChips/Chip/ChipsInput
               Not in the fixture; exercised on /docs/combobox: open from the input and from the chevron, filter, Enter, clear by click and by Tab+Enter, chips, Backspace, chip remove.
               ↳ bases/base/ui/combobox.tsx:66
  ✅ Props      ComboboxContent(side:, side_offset:, align:, align_offset:); ComboboxInput(show_trigger:, show_clear:, disabled:)
               Side top checked on the docs page (opens above, flips when there is no room).
               ↳ bases/base/ui/combobox.tsx:101
  ✅ Props      show_remove: on ComboboxChips; no anchor: (chips anchor automatically) — intentional
               The controller builds chips from a template, so the option lives on the container.
               ↳ audit/divergences/combobox.yml
  ✅ Props      ComboboxToggleAll, Combobox(term:) — intentional
               RubyUI extras kept from the previous API; Select all checked with chips and in a popup.
               ↳ audit/divergences/combobox.yml
  ✅ Props      ComboboxChips(max:): past the cap, one "<count> <term>" chip that clears the selection — intentional
               RubyUI extra for large selections.
               ↳ audit/divergences/combobox.yml
  ✅ Behavior   open: focus to the search input, selected item highlighted, aria-activedescendant; ArrowDown, Home, End move; Enter selects and closes; focus back to the trigger
               Browser run, 1280x800, step by step on both sides.
               ↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
  ✅ Behavior   typing filters (ban → Banana), 'zzz' shows the empty state; Esc closes and returns focus; outside click closes and focus returns to the trigger
               ↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
  ✅ Behavior   input as trigger and multiple: chips, Backspace and × remove (disabled items stay), Select all, max: summary chip; required: (single and multiple) validated by the browser, FormField's aria-invalid/aria-describedby on the visible control
               Docs page run, no console errors.
               ↳ https://www.w3.org/WAI/ARIA/apg/patterns/combobox/#keyboard_interaction
  ✅ Animation  open: enter 0.1s (fade-in-0 zoom-in-95 slide-in-from-top-2); close: exit 0.1s, then hidePopover
               ↳ style-vega.css:297
  ⚠️ Native     popover="manual": top layer from the platform, Esc and outside click handled by the controller
               shadcn: Base UI JS popup
               popover="auto" would light-dismiss when the user clicks the input that triggers it (it sits outside the popup), and closes without the exit animation. Native radio/checkbox still carry the form value.
               ↳ https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes/popover
  ✅ Spec       trigger/input role=combobox with aria-expanded, aria-controls (trigger: only while open), aria-haspopup; no invalid roles
               The role="popover" and the role=combobox wrapper without aria-expanded from main are gone.
               ↳ https://www.w3.org/TR/wai-aria-1.2/#combobox

🤖 Generated with Claude Code


Summary by cubic

Rewrites Combobox to match shadcn's Base UI combobox with vega styling. Breaking change: part names and the root API change, with no aliases for the old API. This fixes the audit findings on main: focus stayed on the trigger after opening so arrow keys did nothing, an invalid role="popover", a role=combobox wrapper with no aria-expanded, and ComboboxInputTrigger, ComboboxBadgeTrigger, ComboboxBadge and ComboboxClearButton shipped pointing at controller code that doesn't exist.

Migration

BeforeAfter
Combobox(term:, placement:)Combobox(name:, multiple:, term:, disabled:, required:); placement moves to ComboboxContent(side:, align:, side_offset:, align_offset:)
ComboboxTrigger(placeholder: "...")ComboboxTrigger { ComboboxValue(placeholder: "...") }
ComboboxPopoverComboboxContent
ComboboxSearchInput(placeholder:)ComboboxInput(placeholder:, show_trigger: false) inside ComboboxContent
ComboboxEmptyStateComboboxEmpty
ComboboxListGroup(label: "Fruits")ComboboxGroup { ComboboxLabel { "Fruits" } ... }, plus ComboboxSeparator
ComboboxItem { ComboboxRadio(name:, value:); span { "Apple" } }ComboboxItem(value: "apple") { "Apple" } (name comes from the root)
ComboboxCheckboxCombobox(multiple: true) makes every item a checkbox
CheckboxGroup(required: true) around the itemsCombobox(multiple: true, required: true)
ComboboxToggleAllCheckboxComboboxToggleAll { "Select all" }
ComboboxInputTriggerComboboxInput(placeholder:, show_clear:) outside the content
ComboboxBadgeTrigger, ComboboxBadge, ComboboxClearButtonComboboxChips(max:) { ComboboxChipsInput }

Behavior changes

  • The controller follows the APG combobox pattern like Base UI: focus stays in the input, the active option goes through aria-activedescendant, the selected item is highlighted on open, Home and End jump to the ends, and Escape and outside clicks return focus to the trigger; the popup fades and zooms over 100 ms.
  • The popup is a popover="manual" top-layer element positioned by Floating UI; popover="auto" would close it when clicking the input that opens it.
  • Each item keeps a visually hidden native radio/checkbox so forms submit the selection, and FormField's aria-invalid and aria-describedby move onto the visible input or trigger; required: without a name: now raises an ArgumentError, and Form reset refreshes chips, value and required flags since the reset unchecks inputs without firing change.
  • Chip remove buttons label the item they remove and sit in the tab order; clicking the input group addon focuses the input. A group gets aria-labelledby only when a ComboboxLabel renders, and aria-controls follows a custom ComboboxList id.
  • ComboboxToggleAll, term: and ComboboxChips(max:) have no shadcn counterpart and are registered in audit/divergences/combobox.yml.
  • Combobox now depends on Button (dependencies.yml); the Form docs example, fixtures and MCP registry are updated.