{
  "id": "combobox",
  "name": "Combobox",
  "level": "molecule",
  "status": "stable",
  "purpose": "A select you can type into to filter a long list.",
  "description": "**Purpose.** A searchable single-choice selector. Composes a Popover surface with the cmdk Command primitive — type-ahead filtering, arrow-key navigation, escape-to-close — behind a Trigger that mirrors `Select`'s chrome.\n\n**When to use.**\n- The list of options is long (~10 or more) so scanning is slow.\n- The user is likely to know the option's name and benefits from filtering as they type.\n- The options have grouping (frameworks by family, regions by continent) that filtering can collapse.\n\n**When NOT to use.**\n- ≤ 10 options where scanning is fast → use `Select`. Combobox adds keyboard ceremony for no gain.\n- Multi-select picker → use a tag-list pattern with `Combobox` + a chips region (or wait for a `MultiCombobox` molecule).\n- Free text where any value is acceptable → use `Input`. Combobox enforces a fixed list.\n\n**Composes with.**\n- `Field` to inherit label / description / error wiring.\n- `Combobox.Trigger / Content / Input / List / Group / Item / Separator / Empty` are the compound surface; consumers always render through them.\n- `Label` + `Description` for inline placements outside `Field`.\n\n**Accessibility.**\n- The Trigger is a `<button role=\"combobox\" aria-expanded>` with the listbox ID via `aria-controls`.\n- The Input inside the popover carries `aria-autocomplete=\"list\"`; the list is `role=\"listbox\"`; items are `role=\"option\"` with `aria-selected`.\n- Type-ahead and arrow keys are wired by cmdk. `Escape` closes the popover and returns focus to the Trigger.\n- `Empty` is announced inline (no toast) so the user knows their query produced no results.\n\n**Related patterns.**\n- `Patterns/Decision Matrix · ComponentChoice` — Combobox vs Select.\n- `Patterns/Overlays · OverlayChoice` — Popover-anchored vs Dialog-anchored selection.\n- `Patterns/Forms · ChoiceControls` — single-choice vs multi-choice ergonomics.",
  "role": "input",
  "import": "@rrios-forge/ui/molecules/combobox",
  "exports": [
    "Combobox",
    "ComboboxContent",
    "ComboboxEmpty",
    "ComboboxGroup",
    "ComboboxInput",
    "ComboboxItem",
    "ComboboxList",
    "ComboboxSeparator",
    "ComboboxTrigger",
    "comboboxInputRowVariants",
    "comboboxInputVariants",
    "comboboxItemVariants",
    "comboboxTriggerVariants",
    "COMBOBOX_TRIGGER_SIZES"
  ],
  "source": "packages/ui/src/molecules/combobox",
  "axes": [
    {
      "axis": "size",
      "part": null,
      "values": [
        "sm",
        "md",
        "lg"
      ],
      "default": "md",
      "meaning": "Ergonomic scale, in three families (control, text, container)."
    },
    {
      "axis": "invalid",
      "part": null,
      "values": [
        "true",
        "false"
      ],
      "default": "false",
      "meaning": "Fails validation: a danger edge, announced as invalid; pair it with an error message."
    }
  ],
  "needs": [
    {
      "need": "Tabs / select / autocomplete",
      "answer": "`Tabs` / `Select` / `Combobox` or `SearchField`"
    }
  ],
  "patterns": [
    "Patterns/Forms · ChoiceControls",
    "Patterns/Overlays · OverlayChoice",
    "Patterns/Decision Matrix · ComponentChoice"
  ],
  "a11yExceptions": [],
  "decisions": [
    {
      "id": "ADR-003",
      "title": "Storybook editorial convention and pattern↔component bidirectionality"
    },
    {
      "id": "ADR-005",
      "title": "Visual operational rules: surfaces, interaction, motion"
    },
    {
      "id": "ADR-006",
      "title": "Geometry and typography signature"
    },
    {
      "id": "ADR-024",
      "title": "`LocaleSelector` is a new molecule, not an extension of `Combobox`"
    }
  ],
  "stories": [
    {
      "name": "Playground",
      "id": "components-molecules-combobox--playground",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-combobox--playground",
      "frame": "/iframe.html?id=components-molecules-combobox--playground&viewMode=story"
    },
    {
      "name": "Many options",
      "id": "components-molecules-combobox--many-options",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-combobox--many-options",
      "frame": "/iframe.html?id=components-molecules-combobox--many-options&viewMode=story"
    },
    {
      "name": "Grouped",
      "id": "components-molecules-combobox--grouped",
      "interaction": false,
      "snapshots": [
        "dark",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-combobox--grouped",
      "frame": "/iframe.html?id=components-molecules-combobox--grouped&viewMode=story"
    },
    {
      "name": "In context",
      "id": "components-molecules-combobox--in-context",
      "interaction": false,
      "snapshots": [
        "dark",
        "high-contrast",
        "light"
      ],
      "skipsSnapshot": false,
      "docs": "/?path=/story/components-molecules-combobox--in-context",
      "frame": "/iframe.html?id=components-molecules-combobox--in-context&viewMode=story"
    },
    {
      "name": "Keyboard flow",
      "id": "components-molecules-combobox--keyboard-flow",
      "interaction": true,
      "snapshots": [],
      "skipsSnapshot": true,
      "docs": "/?path=/story/components-molecules-combobox--keyboard-flow",
      "frame": "/iframe.html?id=components-molecules-combobox--keyboard-flow&viewMode=story"
    },
    {
      "name": "Active descendant (interaction test, known bug)",
      "id": "components-molecules-combobox--active-descendant",
      "interaction": true,
      "snapshots": [],
      "skipsSnapshot": true,
      "docs": "/?path=/story/components-molecules-combobox--active-descendant",
      "frame": "/iframe.html?id=components-molecules-combobox--active-descendant&viewMode=story"
    }
  ],
  "storyFile": "tooling/storybook/stories/components/molecules/combobox.stories.tsx"
}