@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/components-inputs-combo-box.json

@@ -0,0 +1,761 @@
+{
+  "meta": {
+    "id": "Components-ComboBox",
+    "title": "Combo box",
+    "exportName": "ComboBox",
+    "description": "A combobox is an input that combines a text field with a pop-up list of options. It allows users to select a value from a predefined list or enter their own custom value.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/combobox/combobox.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Combo box"
+    ],
+    "route": "components/inputs/combo-box",
+    "tags": [
+      "component",
+      "combobox",
+      "autocomplete",
+      "dropdown",
+      "typeahead"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Key features",
+        "href": "#key-features",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Visual options",
+        "href": "#visual-options",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Appearances",
+        "href": "#appearances",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Selection types",
+        "href": "#selection-types",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Async Loading",
+        "href": "#async-loading",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nThe combobox component provides both selection and text input capabilities. It\ndisplays a list of options that users can choose from, while also allowing them\nto type directly into the text field. This functionality improves user\nexperience by assisting with value selection and, in some cases, prevents\ninvalid entries.\n\n### Key features\n\n- **External State Management:** Full control over async logic using React Stately's `useAsyncList`\n- **Debouncing:** Use `useDebouncedCallback` from `use-debounce` to reduce API calls while typing\n- **Minimum Search Length:** Implement custom validation in the `load` function\n- **Automatic Cancellation:** `useAsyncList` cancels previous requests via AbortSignal\n- **Loading States:** Access `list.loadingState` to display loading indicators\n- **Error Handling:** Manage errors in your `load` function with full control\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?node-id=1852-4333&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\n#### Size\n\nThe medium size of the combobox is default, the small sizes are meant for more\ncompact uses.\n\n```jsx live\nconst App = () => {\n  const options = [\n    { id: \"seasonal\", name: \"Seasonal\", description: \"Grower's choice\" },\n    { id: \"greens\", name: \"Greens\", description: \"Leafy and nutritious\" },\n    { id: \"fruit\", name: \"Fruit\", description: \"Sweet and tart\" },\n    { id: \"root-vegetables\", name: \"Root Vegetables\", description: \"Firm and hearty\" }\n  ];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"400\" alignItems=\"flex-start\">\n      <ComboBox.Root size=\"md\" items={options} placeholder=\"Search...\">\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id} textValue={item.name}>\n                <Stack gap=\"100\">\n                  <Text textStyle=\"sm\">{item.name}</Text>\n                  <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n                </Stack>\n              </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n\n      <ComboBox.Root size=\"sm\" items={options} placeholder=\"Search...\">\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id} textValue={item.name}>\n                <Stack gap=\"100\">\n                  <Text textStyle=\"sm\">{item.name}</Text>\n                  <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n                </Stack>\n              </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n    </Stack>\n  )\n}\n```\n\n#### Appearances\n\nCombobox supports solid and ghost styles.\n\n```jsx live\nconst App = () => {\n  const options = [\n    { id: \"seasonal\", name: \"Seasonal\", description: \"Grower's choice\" },\n    { id: \"greens\", name: \"Greens\", description: \"Leafy and nutritious\" },\n    { id: \"fruit\", name: \"Fruit\", description: \"Sweet and tart\" },\n    { id: \"root-vegetables\", name: \"Root Vegetables\", description: \"Firm and hearty\" }\n  ];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"400\" alignItems=\"flex-start\">\n      <ComboBox.Root variant=\"solid\" items={options} placeholder=\"Search...\">\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id} textValue={item.name}>\n                <Stack gap=\"100\">\n                  <Text textStyle=\"sm\">{item.name}</Text>\n                  <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n                </Stack>\n              </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n\n      <ComboBox.Root variant=\"ghost\" items={options} placeholder=\"Search...\">\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id} textValue={item.name}>\n                <Stack gap=\"100\">\n                  <Text textStyle=\"sm\">{item.name}</Text>\n                  <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n                </Stack>\n              </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n    </Stack>\n  )\n}\n```\n\n#### Selection types\n\nSingle and multi-select is supported by comboboxes.\n\n```jsx live\nconst App = () => {\n  const options = [\n    { id: \"surprise-me\", name: \"Surprise me\", description: \"A mix of delights\" },\n    { id: \"toys-only\", name: \"Toys only\", description: \"Balls, stuffies, and tug toys\" },\n    { id: \"treats-only\", name: \"Treats only\", description: \"Chews, bites, and crunchy snacks\" },\n    { id: \"heavy-chewers\", name: \"Heavy chewers\", description: \"Only difficult to destroy toys\" }\n  ];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"400\" alignItems=\"flex-start\">\n      <ComboBox.Root items={options} placeholder=\"Search...\">\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option id={item.id} textValue={item.name}>\n              <Stack gap=\"100\">\n                <Text textStyle=\"sm\">{item.name}</Text>\n                <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n              </Stack>\n            </ComboBox.Option>\n              )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n\n      <ComboBox.Root\n        selectionMode=\"multiple\"\n        items={options}\n        placeholder=\"Search...\"\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n        {(item) => (\n          <ComboBox.Option id={item.id} textValue={item.name}>\n            <Stack gap=\"100\">\n              <Text textStyle=\"sm\">{item.name}</Text>\n              <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n            </Stack>\n          </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n    </Stack>\n  )\n}\n```\n\n### Async Loading\n\nComboBox supports async data loading by managing the async state externally\nusing React Stately's `useAsyncList` hook. This pattern gives you full control\nover data fetching and works seamlessly with ComboBox's filtering and selection\nfeatures.\n\n**Use cases:**\n\n- Loading large datasets on demand\n- Providing search suggestions from a server\n- Fetching filtered results based on user input\n\n```jsx live\nconst App = () => {\n  const [error, setError] = useState(null);\n  const [inputValue, setInputValue] = useState(\"\");\n  const [isPending, setIsPending] = useState(false);\n  const minSearchLength = 2;\n\n  // Manage async data loading with useAsyncList\n  const list = useAsyncList({\n    async load({ signal, filterText }) {\n      setError(null);\n\n      // Don't load if below minimum search length\n      if (!filterText || filterText.length < minSearchLength) {\n        return { items: [] };\n      }\n\n      try {\n        const response = await fetch(\n          `https://swapi.py4e.com/api/people/?search=${encodeURIComponent(filterText)}`,\n          { signal }\n        );\n\n        if (!response.ok) {\n          throw new Error(`HTTP error! status: ${response.status}`);\n        }\n\n        const data = await response.json();\n        return { items: data.results || [] };\n      } catch (err) {\n        if (err.name === \"AbortError\") {\n          throw err;\n        }\n        setError(err.message);\n        return { items: [] };\n      }\n    }\n  });\n\n  // Debounce only the API call, not the input update\n  const debouncedSetFilterText = useDebouncedCallback(\n    (value) => {\n      setIsPending(false);\n      list.setFilterText(value);\n    },\n    300\n  );\n\n  // Handle input changes: update immediately for responsive typing, debounce API calls\n  const handleInputChange = (value) => {\n    setInputValue(value);\n    setIsPending(true);\n    debouncedSetFilterText(value);\n  };\n\n  // Compute combined loading state\n  // Check all loading states from useAsyncList: \"loading\", \"loadingMore\", \"filtering\"\n  const isLoading = isPending ||\n    list.loadingState === \"loading\" ||\n    list.loadingState === \"loadingMore\" ||\n    list.loadingState === \"filtering\";\n\n  return (\n    <FormField.Root invalid={!!error}>\n      <ComboBox.Root\n        label=\"Search Star Wars Characters\"\n        placeholder=\"Type to search (min 2 characters)...\"\n        items={list.items}\n        inputValue={inputValue}\n        onInputChange={handleInputChange}\n        isLoading={isLoading}\n        getKey={(character) => character.name}\n        // Disable client-side filtering since server already filters results\n        filter={(nodes) => nodes}\n        // Keep menu open during async loading to show loading/empty states\n        allowsEmptyMenu={true}\n        renderEmptyState={({ isLoading }) => {\n          if (isLoading) {\n            return <Text padding=\"300\">Loading...</Text>;\n          }\n          if (!inputValue || inputValue.length < minSearchLength) {\n            return <Text padding=\"300\">Type at least {minSearchLength} characters to search</Text>;\n          }\n          return <Text padding=\"300\">No results found</Text>;\n        }}\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(character) => (\n              <ComboBox.Option textValue={character.name}>\n                <Stack gap=\"100\">\n                  <Text textStyle=\"sm\">{character.name}</Text>\n                  <Text textStyle=\"xs\" color=\"neutral.11\">\n                    {character.gender} • Born {character.birth_year}\n                  </Text>\n                </Stack>\n              </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n      {error && <FormField.ErrorMessage>{error}</FormField.ErrorMessage>}\n    </FormField.Root>\n  );\n};\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThe combobox component provides both selection and text input capabilities. It\ndisplays a list of options that users can choose from, while also allowing them\nto type directly into the text field. This functionality improves user\nexperience by assisting with value selection and, in some cases, prevents\ninvalid entries.\n\n### Key features\n\n- **External State Management:** Full control over async logic using React Stately's `useAsyncList`\n- **Debouncing:** Use `useDebouncedCallback` from `use-debounce` to reduce API calls while typing\n- **Minimum Search Length:** Implement custom validation in the `load` function\n- **Automatic Cancellation:** `useAsyncList` cancels previous requests via AbortSignal\n- **Loading States:** Access `list.loadingState` to display loading indicators\n- **Error Handling:** Manage errors in your `load` function with full control\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?node-id=1852-4333&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visual options\n\n#### Size\n\nThe medium size of the combobox is default, the small sizes are meant for more\ncompact uses.\n\n```jsx live\nconst App = () => {\n  const options = [\n    { id: \"seasonal\", name: \"Seasonal\", description: \"Grower's choice\" },\n    { id: \"greens\", name: \"Greens\", description: \"Leafy and nutritious\" },\n    { id: \"fruit\", name: \"Fruit\", description: \"Sweet and tart\" },\n    { id: \"root-vegetables\", name: \"Root Vegetables\", description: \"Firm and hearty\" }\n  ];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"400\" alignItems=\"flex-start\">\n      <ComboBox.Root size=\"md\" items={options} placeholder=\"Search...\">\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id} textValue={item.name}>\n                <Stack gap=\"100\">\n                  <Text textStyle=\"sm\">{item.name}</Text>\n                  <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n                </Stack>\n              </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n\n      <ComboBox.Root size=\"sm\" items={options} placeholder=\"Search...\">\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id} textValue={item.name}>\n                <Stack gap=\"100\">\n                  <Text textStyle=\"sm\">{item.name}</Text>\n                  <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n                </Stack>\n              </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n    </Stack>\n  )\n}\n```\n\n#### Appearances\n\nCombobox supports solid and ghost styles.\n\n```jsx live\nconst App = () => {\n  const options = [\n    { id: \"seasonal\", name: \"Seasonal\", description: \"Grower's choice\" },\n    { id: \"greens\", name: \"Greens\", description: \"Leafy and nutritious\" },\n    { id: \"fruit\", name: \"Fruit\", description: \"Sweet and tart\" },\n    { id: \"root-vegetables\", name: \"Root Vegetables\", description: \"Firm and hearty\" }\n  ];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"400\" alignItems=\"flex-start\">\n      <ComboBox.Root variant=\"solid\" items={options} placeholder=\"Search...\">\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id} textValue={item.name}>\n                <Stack gap=\"100\">\n                  <Text textStyle=\"sm\">{item.name}</Text>\n                  <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n                </Stack>\n              </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n\n      <ComboBox.Root variant=\"ghost\" items={options} placeholder=\"Search...\">\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id} textValue={item.name}>\n                <Stack gap=\"100\">\n                  <Text textStyle=\"sm\">{item.name}</Text>\n                  <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n                </Stack>\n              </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n    </Stack>\n  )\n}\n```\n\n#### Selection types\n\nSingle and multi-select is supported by comboboxes.\n\n```jsx live\nconst App = () => {\n  const options = [\n    { id: \"surprise-me\", name: \"Surprise me\", description: \"A mix of delights\" },\n    { id: \"toys-only\", name: \"Toys only\", description: \"Balls, stuffies, and tug toys\" },\n    { id: \"treats-only\", name: \"Treats only\", description: \"Chews, bites, and crunchy snacks\" },\n    { id: \"heavy-chewers\", name: \"Heavy chewers\", description: \"Only difficult to destroy toys\" }\n  ];\n\n  return (\n    <Stack direction=\"horizontal\" gap=\"400\" alignItems=\"flex-start\">\n      <ComboBox.Root items={options} placeholder=\"Search...\">\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option id={item.id} textValue={item.name}>\n              <Stack gap=\"100\">\n                <Text textStyle=\"sm\">{item.name}</Text>\n                <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n              </Stack>\n            </ComboBox.Option>\n              )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n\n      <ComboBox.Root\n        selectionMode=\"multiple\"\n        items={options}\n        placeholder=\"Search...\"\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n        {(item) => (\n          <ComboBox.Option id={item.id} textValue={item.name}>\n            <Stack gap=\"100\">\n              <Text textStyle=\"sm\">{item.name}</Text>\n              <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n            </Stack>\n          </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n    </Stack>\n  )\n}\n```\n\n### Async Loading\n\nComboBox supports async data loading by managing the async state externally\nusing React Stately's `useAsyncList` hook. This pattern gives you full control\nover data fetching and works seamlessly with ComboBox's filtering and selection\nfeatures.\n\n**Use cases:**\n\n- Loading large datasets on demand\n- Providing search suggestions from a server\n- Fetching filtered results based on user input\n\n```jsx live\nconst App = () => {\n  const [error, setError] = useState(null);\n  const [inputValue, setInputValue] = useState(\"\");\n  const [isPending, setIsPending] = useState(false);\n  const minSearchLength = 2;\n\n  // Manage async data loading with useAsyncList\n  const list = useAsyncList({\n    async load({ signal, filterText }) {\n      setError(null);\n\n      // Don't load if below minimum search length\n      if (!filterText || filterText.length < minSearchLength) {\n        return { items: [] };\n      }\n\n      try {\n        const response = await fetch(\n          `https://swapi.py4e.com/api/people/?search=${encodeURIComponent(filterText)}`,\n          { signal }\n        );\n\n        if (!response.ok) {\n          throw new Error(`HTTP error! status: ${response.status}`);\n        }\n\n        const data = await response.json();\n        return { items: data.results || [] };\n      } catch (err) {\n        if (err.name === \"AbortError\") {\n          throw err;\n        }\n        setError(err.message);\n        return { items: [] };\n      }\n    }\n  });\n\n  // Debounce only the API call, not the input update\n  const debouncedSetFilterText = useDebouncedCallback(\n    (value) => {\n      setIsPending(false);\n      list.setFilterText(value);\n    },\n    300\n  );\n\n  // Handle input changes: update immediately for responsive typing, debounce API calls\n  const handleInputChange = (value) => {\n    setInputValue(value);\n    setIsPending(true);\n    debouncedSetFilterText(value);\n  };\n\n  // Compute combined loading state\n  // Check all loading states from useAsyncList: \"loading\", \"loadingMore\", \"filtering\"\n  const isLoading = isPending ||\n    list.loadingState === \"loading\" ||\n    list.loadingState === \"loadingMore\" ||\n    list.loadingState === \"filtering\";\n\n  return (\n    <FormField.Root invalid={!!error}>\n      <ComboBox.Root\n        label=\"Search Star Wars Characters\"\n        placeholder=\"Type to search (min 2 characters)...\"\n        items={list.items}\n        inputValue={inputValue}\n        onInputChange={handleInputChange}\n        isLoading={isLoading}\n        getKey={(character) => character.name}\n        // Disable client-side filtering since server already filters results\n        filter={(nodes) => nodes}\n        // Keep menu open during async loading to show loading/empty states\n        allowsEmptyMenu={true}\n        renderEmptyState={({ isLoading }) => {\n          if (isLoading) {\n            return <Text padding=\"300\">Loading...</Text>;\n          }\n          if (!inputValue || inputValue.length < minSearchLength) {\n            return <Text padding=\"300\">Type at least {minSearchLength} characters to search</Text>;\n          }\n          return <Text padding=\"300\">No results found</Text>;\n        }}\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(character) => (\n              <ComboBox.Option textValue={character.name}>\n                <Stack gap=\"100\">\n                  <Text textStyle=\"sm\">{character.name}</Text>\n                  <Text textStyle=\"xs\" color=\"neutral.11\">\n                    {character.gender} • Born {character.birth_year}\n                  </Text>\n                </Stack>\n              </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n      {error && <FormField.ErrorMessage>{error}</FormField.ErrorMessage>}\n    </FormField.Root>\n  );\n};\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Key features",
+          "href": "#key-features",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual options",
+          "href": "#visual-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Appearances",
+          "href": "#appearances",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Selection types",
+          "href": "#selection-types",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Async Loading",
+          "href": "#async-loading",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => {\n  const options = [\n    { id: \"seasonal\", name: \"Seasonal\", description: \"Grower's choice\" },\n    { id: \"greens\", name: \"Greens\", description: \"Leafy and nutritious\" },\n    { id: \"fruit\", name: \"Fruit\", description: \"Sweet and tart\" },\n    { id: \"root-vegetables\", name: \"Root Vegetables\", description: \"Firm and hearty\" }\n  ];\n\n  return (\n    <ComboBox.Root size=\"md\" items={options} placeholder=\"Search...\">\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option id={item.id} textValue={item.name}>\n              <Stack gap=\"100\">\n                <Text textStyle=\"sm\">{item.name}</Text>\n                <Text textStyle=\"xs\" color=\"neutral.11\">{item.description}</Text>\n              </Stack>\n            </ComboBox.Option>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  )\n}\n```\n\n### Accessibility standards\n\n- Always provide a visible label for the input.\n- If a visible label is not used, provide an `aria-label` or `aria-labelledby`\n  for screen readers.\n- Ensure proper ARIA roles (`combobox`, `listbox`, `option`) and attributes\n  (`aria-expanded`, `aria-autocomplete`, `aria-activedescendant`) are used.\n- Ensure sufficient color contrast for all elements (text, borders, icons).\n- Communicate errors clearly, using both visual cues (e.g., color) and\n  descriptive error messages.\n- Clearly indicate the focused and selected states.\n\n### Resources\n\n- [Adobe Spectrum ComboBox](https://spectrum.adobe.com/page/combo-box/)\n- [React Spectrum ComboBox](https://react-spectrum.adobe.com/react-spectrum/ComboBox.html)\n- [W3C ARIA Authoring Practices Guide (APG) - Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { ComboBox, type ComboBoxRootProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\nComboBox supports two patterns for defining options:\n\n#### With items prop (recommended for dynamic data)\n\nUse the `items` prop when working with data from APIs, state, or dynamic\nsources:\n\n```jsx live-dev\nconst App = () => {\n  const animals = [\n    { id: \"koala\", name: \"Koala\" },\n    { id: \"panda\", name: \"Panda\" },\n    { id: \"giraffe\", name: \"Giraffe\" },\n  ];\n\n  return (\n    <ComboBox.Root\n      items={animals}\n      placeholder=\"Select an animal...\"\n      aria-label=\"Select an animal\"\n    >\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  );\n};\n```\n\n#### With static children (requires textValue)\n\nFor static lists, you **must** include the `textValue` prop on each option for\nselections to display correctly:\n\n```jsx live-dev\nconst App = () => (\n  <ComboBox.Root\n    placeholder=\"Select an animal...\"\n    aria-label=\"Select an animal\"\n  >\n    <ComboBox.Trigger />\n    <ComboBox.Popover>\n      <ComboBox.ListBox>\n        <ComboBox.Option id=\"koala\" textValue=\"Koala\">\n          Koala\n        </ComboBox.Option>\n        <ComboBox.Option id=\"panda\" textValue=\"Panda\">\n          Panda\n        </ComboBox.Option>\n        <ComboBox.Option id=\"giraffe\" textValue=\"Giraffe\">\n          Giraffe\n        </ComboBox.Option>\n      </ComboBox.ListBox>\n    </ComboBox.Popover>\n  </ComboBox.Root>\n);\n```\n\n> [!WARNING]\\\n> Without `textValue` on static children, selected values will not display in\n> the input field or as tags. Always include `textValue` when not using the\n> `items` prop.\n\n## Usage examples\n\n### Size options\n\nThe `sm` and `md` size variants are available to match your interface density:\n\n```jsx live-dev\nconst App = () => {\n  const options = [\n    { id: \"1\", name: \"Option 1\" },\n    { id: \"2\", name: \"Option 2\" },\n  ];\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <ComboBox.Root\n        size=\"sm\"\n        items={options}\n        placeholder=\"Small size...\"\n        aria-label=\"Small combobox\"\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n      <ComboBox.Root\n        size=\"md\"\n        items={options}\n        placeholder=\"Medium size...\"\n        aria-label=\"Medium combobox\"\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n    </Stack>\n  );\n};\n```\n\n### Visual variants\n\nChoose between `solid` and `ghost` variants to match your design context:\n\n```jsx live-dev\nconst App = () => {\n  const options = [\n    { id: \"1\", name: \"Option 1\" },\n    { id: \"2\", name: \"Option 2\" },\n  ];\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <ComboBox.Root\n        variant=\"solid\"\n        items={options}\n        placeholder=\"Solid variant...\"\n        aria-label=\"Solid combobox\"\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n      <ComboBox.Root\n        variant=\"ghost\"\n        items={options}\n        placeholder=\"Ghost variant...\"\n        aria-label=\"Ghost combobox\"\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n    </Stack>\n  );\n};\n```\n\n### Single-select mode\n\nBy default, ComboBox operates in single-select mode where users can select one\noption at a time:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedKeys, setSelectedKeys] = useState([]);\n\n  const fruits = [\n    { id: \"apple\", name: \"Apple\" },\n    { id: \"banana\", name: \"Banana\" },\n    { id: \"orange\", name: \"Orange\" },\n  ];\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <ComboBox.Root\n        items={fruits}\n        selectedKeys={selectedKeys}\n        onSelectionChange={setSelectedKeys}\n        selectionMode=\"single\"\n        placeholder=\"Select a fruit...\"\n        aria-label=\"Select a fruit\"\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n      <Text fontSize=\"sm\">\n        {selectedKeys.length > 0\n          ? `Selected: ${selectedKeys[0]}`\n          : \"No selection\"}\n      </Text>\n    </Stack>\n  );\n};\n```\n\n### Multi-select mode\n\nEnable multi-select to allow users to choose multiple options displayed as tags:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedKeys, setSelectedKeys] = useState([]);\n\n  const animals = [\n    { id: \"koala\", name: \"Koala\" },\n    { id: \"panda\", name: \"Panda\" },\n    { id: \"giraffe\", name: \"Giraffe\" },\n    { id: \"elephant\", name: \"Elephant\" },\n  ];\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <ComboBox.Root\n        items={animals}\n        selectedKeys={selectedKeys}\n        onSelectionChange={setSelectedKeys}\n        selectionMode=\"multiple\"\n        placeholder=\"Select animals...\"\n        aria-label=\"Select animals\"\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n      <Text fontSize=\"sm\">\n        Selected: {selectedKeys.length} item\n        {selectedKeys.length !== 1 ? \"s\" : \"\"}\n      </Text>\n    </Stack>\n  );\n};\n```\n\n### Leading element\n\nAdd a leading icon to enhance the visual context:\n\n```jsx live-dev\nconst App = () => {\n  const animals = [\n    { id: \"koala\", name: \"Koala\" },\n    { id: \"panda\", name: \"Panda\" },\n    { id: \"giraffe\", name: \"Giraffe\" },\n  ];\n\n  return (\n    <ComboBox.Root\n      items={animals}\n      leadingElement={<Icons.Search aria-hidden=\"true\" />}\n      placeholder=\"Search...\"\n      aria-label=\"Search for an animal\"\n    >\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  );\n};\n```\n\n### Disabled state\n\nUse `isDisabled` to disable the combobox:\n\n```jsx live-dev\nconst App = () => {\n  const options = [\n    { id: \"1\", name: \"Option 1\" },\n    { id: \"2\", name: \"Option 2\" },\n  ];\n\n  return (\n    <ComboBox.Root\n      items={options}\n      isDisabled\n      placeholder=\"Disabled...\"\n      aria-label=\"Disabled combobox\"\n    >\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  );\n};\n```\n\n### Invalid state\n\nMark the combobox as invalid for form validation:\n\n```jsx live-dev\nconst App = () => {\n  const options = [\n    { id: \"1\", name: \"Option 1\" },\n    { id: \"2\", name: \"Option 2\" },\n  ];\n\n  return (\n    <ComboBox.Root\n      items={options}\n      isInvalid\n      placeholder=\"Select an option...\"\n      aria-label=\"Invalid combobox\"\n    >\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  );\n};\n```\n\n### Read-only state\n\nUse `isReadOnly` for display-only scenarios:\n\n```jsx live-dev\nconst App = () => {\n  const fruits = [\n    { id: \"apple\", name: \"Apple\" },\n    { id: \"banana\", name: \"Banana\" },\n  ];\n\n  return (\n    <ComboBox.Root\n      items={fruits}\n      isReadOnly\n      selectedKeys={[\"apple\"]}\n      aria-label=\"Read-only combobox\"\n    >\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  );\n};\n```\n\n### Option groups\n\nOrganize options into sections with headers:\n\n```jsx live-dev\nconst App = () => {\n  const foodCategories = [\n    {\n      id: \"fruits\",\n      name: \"Fruits\",\n      children: [\n        { id: \"apple\", name: \"Apple\" },\n        { id: \"banana\", name: \"Banana\" },\n        { id: \"orange\", name: \"Orange\" },\n      ],\n    },\n    {\n      id: \"vegetables\",\n      name: \"Vegetables\",\n      children: [\n        { id: \"carrot\", name: \"Carrot\" },\n        { id: \"broccoli\", name: \"Broccoli\" },\n        { id: \"spinach\", name: \"Spinach\" },\n      ],\n    },\n  ];\n\n  return (\n    <ComboBox.Root\n      items={foodCategories}\n      placeholder=\"Select a food...\"\n      aria-label=\"Select a food\"\n    >\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(category) => (\n            <ComboBox.Section\n              id={category.id}\n              label={category.name}\n              items={category.children}\n            >\n              {(item) => (\n                <ComboBox.Option id={item.id} textValue={item.name}>\n                  {item.name}\n                </ComboBox.Option>\n              )}\n            </ComboBox.Section>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  );\n};\n```\n\n### Dynamic options with items\n\n`ComboBox.ListBox` supports the `items` prop, a pattern unique to React Aria\nComponents (inherited from React Aria's `ListBox` component). This pattern\nprovides an efficient way to render dynamic or large lists of options.\n\n**When to use `items` vs static children:**\n\n- **Use `items` when:**\n  - Rendering options from dynamic data (API responses, filtered lists, computed\n    arrays)\n  - Working with large lists (better performance through virtualization support)\n  - Options change frequently based on user input or state\n  - You need to map over data structures\n\n- **Use static children when:**\n  - Options are known at compile time\n  - You have a small, fixed set of options\n  - You prefer the simpler JSX syntax for readability\n\n**Static children example:**\n\n```jsx live-dev\nconst App = () => (\n  <ComboBox.Root\n    placeholder=\"Select an animal...\"\n    aria-label=\"Select an animal\"\n  >\n    <ComboBox.Trigger />\n    <ComboBox.Popover>\n      <ComboBox.ListBox>\n        <ComboBox.Option id=\"koala\" textValue=\"Koala\">\n          Koala\n        </ComboBox.Option>\n        <ComboBox.Option id=\"panda\" textValue=\"Panda\">\n          Panda\n        </ComboBox.Option>\n        <ComboBox.Option id=\"giraffe\" textValue=\"Giraffe\">\n          Giraffe\n        </ComboBox.Option>\n      </ComboBox.ListBox>\n    </ComboBox.Popover>\n  </ComboBox.Root>\n);\n```\n\n**Dynamic items example:**\n\nWhen using `items`, children must be a render function that receives each item\nand returns a `ComboBox.Option`. This example demonstrates using `items` with\ndata that could come from an API, state, or computed values:\n\n```jsx live-dev\nconst App = () => {\n  // In a real app, this data might come from an API, props, or state.\n  const animals = [\n    { id: \"koala\", name: \"Koala\" },\n    { id: \"panda\", name: \"Panda\" },\n    { id: \"giraffe\", name: \"Giraffe\" },\n    { id: \"elephant\", name: \"Elephant\" },\n  ];\n\n  return (\n    <ComboBox.Root\n      items={animals}\n      placeholder=\"Select an animal...\"\n      aria-label=\"Select an animal\"\n    >\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  );\n};\n```\n\nThe `items` pattern enables React Aria to optimize rendering and provides better\nsupport for features like virtualization, which can improve performance with\nlarge option lists.\n\n> [!TIP]\\\n> See [React Aria's ComboBox documentation](https://react-spectrum.adobe.com/react-aria/ComboBox.html#sections)\n> for complete API reference and advanced usage, including static and dynamic\n> items.\n\n### Custom filtering\n\nCustomize how options are filtered using the `filter` prop:\n\n```jsx live-dev\nconst App = () => {\n  const animals = [\n    { id: 1, name: \"Koala\", category: \"Marsupial\" },\n    { id: 2, name: \"Panda\", category: \"Bear\" },\n    { id: 3, name: \"Giraffe\", category: \"Mammal\" },\n    { id: 4, name: \"Elephant\", category: \"Mammal\" },\n  ];\n\n  // Use the built-in multi-property filter\n  const multiPropertyFilter = useCallback(\n    ComboBox.filters.createMultiPropertyFilter([\"name\", \"category\"]),\n    []\n  );\n\n  return (\n    <ComboBox.Root\n      items={animals}\n      filter={multiPropertyFilter}\n      aria-label=\"Search animals\"\n      placeholder=\"Search by name or category...\"\n    >\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option key={item.id} id={item.id}>\n              {item.name} ({item.category})\n            </ComboBox.Option>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  );\n};\n```\n\n### Custom options creation\n\nAllow users to create new options by typing and pressing Enter:\n\n```jsx live-dev\nconst App = () => {\n  const [items, setItems] = useState([\n    { id: 1, name: \"Apple\" },\n    { id: 2, name: \"Banana\" },\n    { id: 3, name: \"Orange\" },\n  ]);\n  const [selectedKeys, setSelectedKeys] = useState([]);\n\n  const handleCreateOption = useCallback((newItem) => {\n    console.log(\"Created:\", newItem.name);\n  }, []);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <ComboBox.Root\n        items={items}\n        selectedKeys={selectedKeys}\n        onSelectionChange={setSelectedKeys}\n        selectionMode=\"multiple\"\n        allowsCustomOptions\n        getNewOptionData={(inputValue) => ({\n          id: Date.now(),\n          name: inputValue,\n        })}\n        onCreateOption={handleCreateOption}\n        aria-label=\"Select or create fruits\"\n        placeholder=\"Type to search or create...\"\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option key={item.id} id={item.id}>\n                {item.name}\n              </ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n      <Text fontSize=\"sm\">\n        Type a custom fruit and press Enter to create it!\n      </Text>\n    </Stack>\n  );\n};\n```\n\n### Async data loading\n\nLoad options asynchronously with built-in debouncing and loading states:\n\n```jsx live-dev\nconst App = () => {\n  // Simulated API call\n  const loadPokemon = useCallback(async (filterText, signal) => {\n    await new Promise((resolve) => setTimeout(resolve, 500));\n\n    const allPokemon = [\n      { id: 1, name: \"Bulbasaur\" },\n      { id: 2, name: \"Charmander\" },\n      { id: 3, name: \"Squirtle\" },\n      { id: 4, name: \"Pikachu\" },\n      { id: 5, name: \"Jigglypuff\" },\n    ];\n\n    return allPokemon.filter((p) =>\n      p.name.toLowerCase().includes(filterText.toLowerCase())\n    );\n  }, []);\n\n  return (\n    <ComboBox.Root\n      async={{\n        load: loadPokemon,\n        minSearchLength: 2,\n        debounce: 300,\n      }}\n      aria-label=\"Search Pokemon\"\n      placeholder=\"Type to search...\"\n    >\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option key={item.id} id={item.id}>\n              {item.name}\n            </ComboBox.Option>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  );\n};\n```\n\n### Controlled input value\n\nControl the input text for advanced scenarios:\n\n```jsx live-dev\nconst App = () => {\n  const [inputValue, setInputValue] = useState(\"\");\n  const [selectedKeys, setSelectedKeys] = useState([]);\n\n  const fruits = [\n    { id: \"apple\", name: \"Apple\" },\n    { id: \"banana\", name: \"Banana\" },\n    { id: \"orange\", name: \"Orange\" },\n  ];\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <ComboBox.Root\n        items={fruits}\n        inputValue={inputValue}\n        onInputChange={setInputValue}\n        selectedKeys={selectedKeys}\n        onSelectionChange={setSelectedKeys}\n        selectionMode=\"single\"\n        placeholder=\"Select a fruit...\"\n        aria-label=\"Controlled combobox\"\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {(item) => (\n              <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n            )}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n      <Text fontSize=\"sm\">Input: {inputValue || \"(empty)\"}</Text>\n    </Stack>\n  );\n};\n```\n\n### Menu trigger behavior\n\nControl when the dropdown menu opens using `menuTrigger`:\n\n```jsx live-dev\nconst App = () => {\n  const options = [\n    { id: \"1\", name: \"Option 1\" },\n    { id: \"2\", name: \"Option 2\" },\n  ];\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Box>\n        <Text fontSize=\"sm\" fontWeight=\"medium\" mb=\"200\">\n          menuTrigger=\"focus\" (default) - Opens when clicking input or toggle\n          button\n        </Text>\n        <ComboBox.Root\n          items={options}\n          menuTrigger=\"focus\"\n          placeholder=\"Click to open...\"\n          aria-label=\"Focus trigger\"\n        >\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              {(item) => (\n                <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n              )}\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </Box>\n      <Box>\n        <Text fontSize=\"sm\" fontWeight=\"medium\" mb=\"200\">\n          menuTrigger=\"input\" - Opens only when typing (try typing in the input)\n        </Text>\n        <ComboBox.Root\n          items={options}\n          menuTrigger=\"input\"\n          placeholder=\"Type to open...\"\n          aria-label=\"Input trigger\"\n        >\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              {(item) => (\n                <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n              )}\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </Box>\n      <Box>\n        <Text fontSize=\"sm\" fontWeight=\"medium\" mb=\"200\">\n          menuTrigger=\"manual\" - Opens only via toggle button (input click does\n          nothing)\n        </Text>\n        <ComboBox.Root\n          items={options}\n          menuTrigger=\"manual\"\n          placeholder=\"Use button to open...\"\n          aria-label=\"Manual trigger\"\n        >\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              {(item) => (\n                <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>\n              )}\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </Box>\n    </Stack>\n  );\n};\n```\n\n## Component requirements\n\n### Accessibility\n\nThe ComboBox handles most accessibility requirements internally via React Aria.\n\nIf your use case requires tracking and analytics for this component, it is good\npractice to add a **persistent**, **unique** id:\n\n```tsx\nconst PERSISTENT_ID = \"example-combobox\";\n\nexport const Example = () => (\n  <ComboBox.Root id={PERSISTENT_ID} aria-label=\"Select an option\">\n    <ComboBox.Trigger />\n    <ComboBox.Popover>\n      <ComboBox.ListBox>\n        <ComboBox.Option id=\"1\">Option 1</ComboBox.Option>\n      </ComboBox.ListBox>\n    </ComboBox.Popover>\n  </ComboBox.Root>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n\n- `Tab` / `Shift+Tab`: Navigate to/from the combobox\n- `Arrow Down`: Opens the menu and moves focus to the next option\n- `Arrow Up`: Opens the menu and moves focus to the previous option\n- `Enter`: Selects the focused option (or creates custom option if\n  `allowsCustomOptions` is enabled)\n- `Escape`: Closes the menu\n- `Home` / `End`: Jump to first/last option\n- Type to filter: Type characters to filter options in real-time\n\n## API reference\n\n<PropsTable id=\"ComboBox\" />\n\n## Common patterns\n\n### Product search with categories\n\nA common e-commerce pattern combining filtering, grouping, and multi-select:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedKeys, setSelectedKeys] = useState([]);\n\n  const products = [\n    { id: 1, name: \"MacBook Pro\", category: \"Electronics\" },\n    { id: 2, name: \"iPhone\", category: \"Electronics\" },\n    { id: 3, name: \"Desk Chair\", category: \"Furniture\" },\n    { id: 4, name: \"Standing Desk\", category: \"Furniture\" },\n    { id: 5, name: \"Coffee Maker\", category: \"Appliances\" },\n  ];\n\n  // Group products by category\n  const groupedByCategory = products.reduce((acc, product) => {\n    if (!acc[product.category]) {\n      acc[product.category] = [];\n    }\n    acc[product.category].push(product);\n    return acc;\n  }, {});\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <ComboBox.Root\n        selectedKeys={selectedKeys}\n        onSelectionChange={setSelectedKeys}\n        selectionMode=\"multiple\"\n        placeholder=\"Search products...\"\n        aria-label=\"Select products\"\n      >\n        <ComboBox.Trigger />\n        <ComboBox.Popover>\n          <ComboBox.ListBox>\n            {Object.entries(groupedByCategory).map(([category, items]) => (\n              <ComboBox.Section key={category} label={category}>\n                {items.map((item) => (\n                  <ComboBox.Option key={item.id} id={item.id}>\n                    {item.name}\n                  </ComboBox.Option>\n                ))}\n              </ComboBox.Section>\n            ))}\n          </ComboBox.ListBox>\n        </ComboBox.Popover>\n      </ComboBox.Root>\n      <Text fontSize=\"sm\">\n        {selectedKeys.length} product{selectedKeys.length !== 1 ? \"s\" : \"\"}{\" \"}\n        selected\n      </Text>\n    </Stack>\n  );\n};\n```\n\n### Tag selection with creation\n\nEnable users to select from existing tags or create new ones:\n\n```jsx live-dev\nconst App = () => {\n  const [tags, setTags] = useState([\n    { id: 1, label: \"React\" },\n    { id: 2, label: \"TypeScript\" },\n    { id: 3, label: \"JavaScript\" },\n  ]);\n  const [selectedKeys, setSelectedKeys] = useState([]);\n\n  const handleCreateTag = useCallback((newTag) => {\n    setTags((prev) => [...prev, newTag]);\n  }, []);\n\n  return (\n    <ComboBox.Root\n      items={tags}\n      selectedKeys={selectedKeys}\n      onSelectionChange={setSelectedKeys}\n      selectionMode=\"multiple\"\n      allowsCustomOptions\n      getNewOptionData={(inputValue) => ({\n        id: Date.now(),\n        label: inputValue,\n      })}\n      onCreateOption={handleCreateTag}\n      getTextValue={(item) => item.label}\n      placeholder=\"Add tags...\"\n      aria-label=\"Select or create tags\"\n    >\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option key={item.id} id={item.id}>\n              {item.label}\n            </ComboBox.Option>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  );\n};\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using ComboBox\nwithin your application. As the component's internal functionality is already\ntested by Nimbus, these patterns help you verify your integration and\napplication-specific logic.\n\n### Basic Rendering Tests\n\nVerify the component renders with expected elements\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { useState, useCallback } from \"react\";\nimport { ComboBox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ComboBox - Basic rendering\", () => {\n  it(\"renders combobox input\", async () => {\n    render(\n      <NimbusProvider>\n        <ComboBox.Root aria-label=\"Select an animal\">\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              <ComboBox.Option id=\"koala\">Koala</ComboBox.Option>\n              <ComboBox.Option id=\"panda\">Panda</ComboBox.Option>\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </NimbusProvider>\n    );\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"combobox\")).toBeInTheDocument();\n    });\n  });\n\n  it(\"renders with placeholder text\", async () => {\n    render(\n      <NimbusProvider>\n        <ComboBox.Root\n          placeholder=\"Search animals...\"\n          aria-label=\"Select an animal\"\n        >\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              <ComboBox.Option id=\"koala\">Koala</ComboBox.Option>\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </NimbusProvider>\n    );\n\n    await waitFor(() => {\n      expect(\n        screen.getByPlaceholderText(\"Search animals...\")\n      ).toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the component\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { useState, useCallback } from \"react\";\nimport { ComboBox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ComboBox - Interactions\", () => {\n  it(\"opens dropdown when input is clicked\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <ComboBox.Root aria-label=\"Select an animal\" menuTrigger=\"focus\">\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              <ComboBox.Option id=\"koala\">Koala</ComboBox.Option>\n              <ComboBox.Option id=\"panda\">Panda</ComboBox.Option>\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </NimbusProvider>\n    );\n\n    const combobox = screen.getByRole(\"combobox\");\n    await user.click(combobox);\n\n    // The listbox is rendered in a portal outside the component tree\n    // Query document directly and wait for it to appear\n    await waitFor(() => {\n      expect(document.querySelector('[role=\"listbox\"]')).toBeInTheDocument();\n    });\n  });\n\n  it(\"calls onInputChange when typing\", async () => {\n    const user = userEvent.setup();\n    const handleInputChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ComboBox.Root\n          onInputChange={handleInputChange}\n          aria-label=\"Select an animal\"\n        >\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              <ComboBox.Option id=\"koala\">Koala</ComboBox.Option>\n              <ComboBox.Option id=\"panda\">Panda</ComboBox.Option>\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </NimbusProvider>\n    );\n\n    const combobox = screen.getByRole(\"combobox\");\n    await user.type(combobox, \"test\");\n\n    expect(handleInputChange).toHaveBeenCalled();\n  });\n\n  it(\"selects option when clicked\", async () => {\n    const user = userEvent.setup();\n    const handleSelectionChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <ComboBox.Root\n          onSelectionChange={handleSelectionChange}\n          menuTrigger=\"focus\"\n          aria-label=\"Select an animal\"\n        >\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              <ComboBox.Option id=\"koala\">Koala</ComboBox.Option>\n              <ComboBox.Option id=\"panda\">Panda</ComboBox.Option>\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </NimbusProvider>\n    );\n\n    const combobox = screen.getByRole(\"combobox\");\n    await user.click(combobox);\n\n    // Wait for options to appear in the portal\n    await waitFor(() => {\n      expect(\n        document.querySelectorAll('[role=\"option\"]').length\n      ).toBeGreaterThan(0);\n    });\n\n    // Get options after they've rendered\n    const options = document.querySelectorAll('[role=\"option\"]');\n    await user.click(options[0]);\n\n    expect(handleSelectionChange).toHaveBeenCalledWith([\"koala\"]);\n  });\n});\n```\n\n### Single-Select Mode Tests\n\nTest single-select behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { useState, useCallback } from \"react\";\nimport { ComboBox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ComboBox - Single-select mode\", () => {\n  it(\"supports single selection mode\", async () => {\n    const handleSelectionChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ComboBox.Root\n          selectionMode=\"single\"\n          onSelectionChange={handleSelectionChange}\n          aria-label=\"Select a fruit\"\n        >\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              <ComboBox.Option id=\"apple\">Apple</ComboBox.Option>\n              <ComboBox.Option id=\"banana\">Banana</ComboBox.Option>\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </NimbusProvider>\n    );\n\n    // Verify single-select mode renders correctly\n    await waitFor(() => {\n      expect(screen.getByRole(\"combobox\")).toBeInTheDocument();\n    });\n    expect(handleSelectionChange).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Multi-Select Mode Tests\n\nTest multi-select behavior with tags\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { useState, useCallback } from \"react\";\nimport { ComboBox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ComboBox - Multi-select mode\", () => {\n  it(\"supports multiple selection mode\", async () => {\n    const handleSelectionChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ComboBox.Root\n          selectionMode=\"multiple\"\n          onSelectionChange={handleSelectionChange}\n          aria-label=\"Select animals\"\n        >\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              <ComboBox.Option id=\"koala\">Koala</ComboBox.Option>\n              <ComboBox.Option id=\"panda\">Panda</ComboBox.Option>\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </NimbusProvider>\n    );\n\n    // Verify multi-select mode renders correctly\n    await waitFor(() => {\n      expect(screen.getByRole(\"combobox\")).toBeInTheDocument();\n    });\n    expect(handleSelectionChange).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Disabled State Tests\n\nTest that the combobox is properly disabled\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { useState, useCallback } from \"react\";\nimport { ComboBox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ComboBox - Disabled state\", () => {\n  it(\"renders disabled combobox\", async () => {\n    render(\n      <NimbusProvider>\n        <ComboBox.Root isDisabled aria-label=\"Select an animal\">\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              <ComboBox.Option id=\"koala\">Koala</ComboBox.Option>\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </NimbusProvider>\n    );\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"combobox\")).toBeDisabled();\n    });\n  });\n});\n```\n\n### Invalid State Tests\n\nTest that the combobox is properly marked as invalid\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { useState, useCallback } from \"react\";\nimport { ComboBox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ComboBox - Invalid state\", () => {\n  it(\"renders invalid combobox\", async () => {\n    render(\n      <NimbusProvider>\n        <ComboBox.Root isInvalid aria-label=\"Select an animal\">\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              <ComboBox.Option id=\"koala\">Koala</ComboBox.Option>\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </NimbusProvider>\n    );\n\n    // Invalid state is on the root element\n    await waitFor(() => {\n      const combobox = screen.getByRole(\"combobox\");\n      const comboboxRoot = combobox.closest('[data-invalid=\"true\"]');\n      expect(comboboxRoot).toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Custom Options Creation Tests\n\nTest creating custom options with allowsCustomOptions\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { useState, useCallback } from \"react\";\nimport { ComboBox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ComboBox - Custom options\", () => {\n  it(\"creates new option when Enter is pressed\", async () => {\n    const user = userEvent.setup();\n\n    type FruitItem = {\n      id: number;\n      name: string;\n    };\n\n    const handleCreateOption = vi.fn();\n\n    const TestComponent = () => {\n      const [items, setItems] = useState<FruitItem[]>([\n        { id: 1, name: \"Apple\" },\n        { id: 2, name: \"Banana\" },\n      ]);\n\n      const getNewOptionData = useCallback(\n        (inputValue: string): FruitItem => ({\n          id: Date.now(),\n          name: inputValue,\n        }),\n        []\n      );\n\n      const onCreateOption = useCallback((newItem: FruitItem) => {\n        setItems((prev) => [...prev, newItem]);\n        handleCreateOption(newItem);\n      }, []);\n\n      return (\n        <NimbusProvider>\n          <ComboBox.Root\n            items={items}\n            selectionMode=\"multiple\"\n            allowsCustomOptions\n            getNewOptionData={getNewOptionData}\n            onCreateOption={onCreateOption}\n            aria-label=\"Select or create fruits\"\n          >\n            <ComboBox.Trigger />\n            <ComboBox.Popover>\n              <ComboBox.ListBox>\n                {(item: FruitItem) => (\n                  <ComboBox.Option key={item.id} id={item.id}>\n                    {item.name}\n                  </ComboBox.Option>\n                )}\n              </ComboBox.ListBox>\n            </ComboBox.Popover>\n          </ComboBox.Root>\n        </NimbusProvider>\n      );\n    };\n\n    render(<TestComponent />);\n\n    const combobox = screen.getByRole(\"combobox\");\n    await user.click(combobox);\n    await user.type(combobox, \"Orange\");\n    await user.keyboard(\"{Enter}\");\n\n    expect(handleCreateOption).toHaveBeenCalled();\n    // TypeScript knows the mock call argument type from the implementation\n    const createdItem = handleCreateOption.mock.calls[0][0] as FruitItem;\n    expect(createdItem.name).toBe(\"Orange\");\n  });\n});\n```\n\n### Option Groups Tests\n\nTest rendering with option groups\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { useState, useCallback } from \"react\";\nimport { ComboBox, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ComboBox - Option groups\", () => {\n  it(\"renders grouped options\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <ComboBox.Root menuTrigger=\"focus\" aria-label=\"Select a food\">\n          <ComboBox.Trigger />\n          <ComboBox.Popover>\n            <ComboBox.ListBox>\n              <ComboBox.Section label=\"Fruits\">\n                <ComboBox.Option id=\"apple\">Apple</ComboBox.Option>\n                <ComboBox.Option id=\"banana\">Banana</ComboBox.Option>\n              </ComboBox.Section>\n              <ComboBox.Section label=\"Vegetables\">\n                <ComboBox.Option id=\"carrot\">Carrot</ComboBox.Option>\n              </ComboBox.Section>\n            </ComboBox.ListBox>\n          </ComboBox.Popover>\n        </ComboBox.Root>\n      </NimbusProvider>\n    );\n\n    const combobox = screen.getByRole(\"combobox\");\n    await user.click(combobox);\n\n    // Wait for listbox to appear in portal, then check for section labels\n    await waitFor(() => {\n      expect(document.querySelector('[role=\"listbox\"]')).toBeInTheDocument();\n    });\n\n    // Section labels should be visible in the document\n    await waitFor(() => {\n      expect(screen.getByText(\"Fruits\")).toBeInTheDocument();\n      expect(screen.getByText(\"Vegetables\")).toBeInTheDocument();\n    });\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-combobox--docs)\n- [React Aria ComboBox](https://react-spectrum.adobe.com/react-aria/ComboBox.html)\n- [ARIA Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With items prop (recommended for dynamic data)",
+          "href": "#with-items-prop-recommended-for-dynamic-data",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With static children (requires textValue)",
+          "href": "#with-static-children-requires-textvalue",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual variants",
+          "href": "#visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Single-select mode",
+          "href": "#single-select-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-select mode",
+          "href": "#multi-select-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Leading element",
+          "href": "#leading-element",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Invalid state",
+          "href": "#invalid-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Read-only state",
+          "href": "#read-only-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Option groups",
+          "href": "#option-groups",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Dynamic options with items",
+          "href": "#dynamic-options-with-items",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            10
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom filtering",
+          "href": "#custom-filtering",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            11
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom options creation",
+          "href": "#custom-options-creation",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            12
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Async data loading",
+          "href": "#async-data-loading",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            13
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled input value",
+          "href": "#controlled-input-value",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            14
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Menu trigger behavior",
+          "href": "#menu-trigger-behavior",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            15
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Product search with categories",
+          "href": "#product-search-with-categories",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tag selection with creation",
+          "href": "#tag-selection-with-creation",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Single-Select Mode Tests",
+          "href": "#single-select-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-Select Mode Tests",
+          "href": "#multi-select-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled State Tests",
+          "href": "#disabled-state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Invalid State Tests",
+          "href": "#invalid-state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom Options Creation Tests",
+          "href": "#custom-options-creation-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Option Groups Tests",
+          "href": "#option-groups-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nA combobox combines a text input with a dropdown list, allowing users to type a\nvalue or select from predefined options.\n\n### Best practices\n\n- **Provide Instant Feedback:** Filter results in real-time as users type.\n- **Handle No Results Graciously:** Display a clear message when no matching\n  options are found.\n- **Optimize for Keyboard Navigation:** Ensure full functionality using only the\n  keyboard.\n- **Consider Performance:** For very long lists, implement virtualization or\n  lazy loading to prevent performance issues.\n- **Offer Clear/Reset Option:** Provide a way for users to clear their selection\n  if needed.\n- **Match Input to Options:** If the user types a value that exactly matches an\n  option, automatically select it.\n\n### Usage\n\nUsers interact with a combobox by typing to filter options or by selecting from\nthe dropdown list, expecting the component to dynamically narrow choices and\nallow either a selection or custom entry.\n\n> [!TIP]\\\n> When to use\n\n- Allowing custom input alongside predefined options.\n- Filtering long lists.\n- Providing suggestions as a user types.\n\n> [!CAUTION]\\\n> When not to use\n\n- Only predefined options are allowed.\n- The list of options is very short (e.g., 2-5 options).\n- Multi-selection is the primary goal without typing.\n- Real-time validation of complex custom input is difficult.\n\n### Intuitive interactions\n\nA well-designed combobox enhances user efficiency and accuracy by offering\nflexible input methods with clear, dynamic feedback.\n\n> [!TIP]\\\n> **Do**\n>\n> - Provide a clear and concise label.\n> - Filter options dynamically as the user types.\n> - Support both keyboard and mouse interactions.\n> - Offer clear feedback for all states (focus, hover, active, disabled,\n>   invalid).\n> - Ensure accessibility with appropriate ARIA attributes.\n> - Pre-populate with common values if applicable.\n\n```jsx live\nconst App = () => {\n  const [selectedKeys, setSelectedKeys] = useState([\"yellow\", \"blue\"]);\n\n  const colors = [\n    { id: \"red\", name: \"Red\" },\n    { id: \"yellow\", name: \"Yellow\" },\n    { id: \"blue\", name: \"Blue\" },\n    { id: \"pink\", name: \"Pink\" },\n  ];\n\n  return (\n    <ComboBox.Root\n      items={colors}\n      selectedKeys={selectedKeys}\n      onSelectionChange={setSelectedKeys}\n      selectionMode=\"multiple\"\n      placeholder=\"Select colors...\"\n      aria-label=\"Select colors\"\n    >\n      <ComboBox.Trigger />\n      <ComboBox.Popover>\n        <ComboBox.ListBox>\n          {(item) => (\n            <ComboBox.Option id={item.id}>\n              <Stack gap=\"100\">\n                <Text textStyle=\"sm\">{item.name}</Text>\n                <Text textStyle=\"xs\" color=\"neutral.11\">\n                  key: {item.id}\n                </Text>\n              </Stack>\n            </ComboBox.Option>\n          )}\n        </ComboBox.ListBox>\n      </ComboBox.Popover>\n    </ComboBox.Root>\n  );\n};\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Use for simple dropdowns where no custom input is needed (use a select\n>   component instead).\n> - Neglect to provide feedback when no options match the input.\n> - Force users to type an exact match if a selection from the list is expected.\n> - Rely solely on visual cues; provide ARIA attributes for screen readers.\n> - Display an overwhelming number of options without filtering or pagination.\n\n<img\n  src=\"/images/combobox/combobox-dont.png\"\n  alt=\"combobox do guideline\"\n  width=\"316px\"\n/>\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Intuitive interactions",
+          "href": "#intuitive-interactions",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}