@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/data/docs/routes/components-inputs-select-input.json

@@ -0,0 +1,960 @@
+{
+  "meta": {
+    "id": "Components-Select",
+    "title": "Select",
+    "exportName": "Select",
+    "description": "A select input is a form field that presents users with a dropdown menu of options to choose from.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/select/select.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Select input"
+    ],
+    "route": "components/inputs/select-input",
+    "tags": [
+      "component",
+      "select",
+      "dropdown",
+      "picker",
+      "options"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Height options",
+        "href": "#height-options",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Medium",
+        "href": "#medium",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Small",
+        "href": "#small",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Fixed width",
+        "href": "#fixed-width",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Solid-styled",
+        "href": "#solid-styled",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Ghost-styled",
+        "href": "#ghost-styled",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Text wrapping",
+        "href": "#text-wrapping",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Text wrapping within popover",
+        "href": "#text-wrapping-within-popover",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Truncate when long line item is selected",
+        "href": "#truncate-when-long-line-item-is-selected",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          3,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Validation",
+        "href": "#validation",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Default",
+        "href": "#default",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          4,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Invalid",
+        "href": "#invalid",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          4,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Disabled",
+        "href": "#disabled",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          4,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Placeholder",
+        "href": "#placeholder",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          4,
+          4
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=2304-22847&m=dev",
+    "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\nSelect inputs have two main appearances, two sizes, and several states that will\nrespond to validation status. **Currently, this is a single value selector, this\nwill be reworked to bring in multi-select in the future.**\n\n### Resources\n\n[ARIA APG: Listbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)\n[React ARIA: Select](https://react-spectrum.adobe.com/react-aria/Select.html)\n[Figma Library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=2304-22847&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Height options\n\n#### Medium\n\nThis is the default size for the select input.\n\n```jsx live\nconst App = () => (\n  <Select.Root size=\"md\" aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Small\n\nFor use in areas that require more condensed styling.\n\n```jsx live\nconst App = () => (\n  <Select.Root size=\"sm\" aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n### Fixed width\n\n#### Solid-styled\n\nMax width when not in a page wide form should be 268px. If the solid-styled\nselect input field is inline a page wide form match popover width to match the\nsize of the form fields.\n\n```jsx live\nconst App = () => (\n  <Select.Root aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Ghost-styled\n\nHug the select-input field, this styling needs closer placement to the drop down\nicon than a solid-styled version. The popover width has two options with this\nplacement based on content. Short content should match the hug width of the\nfield. Longer content should have a max width of 268px.\n\n```jsx live\nconst App = () => (\n  <Select.Root variant=\"ghost\" aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n### Text wrapping\n\n#### Text wrapping within popover\n\nPlease encourage short text when possible. When applicable, wrap text onto\nanother line when needed.\n\n```jsx live\nconst App = () => (\n  <Select.Root defaultSelectedKey=\"project-1\" w=\"6400\">\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"project-long\">\n        Project with a very long name\n      </Select.Option>\n      <Select.Option id=\"project-1\">Project 1</Select.Option>\n      <Select.Option id=\"abc\">ABC</Select.Option>\n      <Select.Option id=\"project-2lines\">\n        Project with an even longer name that breaks into 2 lines\n      </Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Truncate when long line item is selected\n\nIf selected, truncate text so it does not overlap over the icons in the select\ninput field.\n\n```jsx live\nconst App = () => (\n  <Select.Root defaultSelectedKey=\"project-2lines\" w=\"6400\">\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"project-long\">\n        Project with a very long name\n      </Select.Option>\n      <Select.Option id=\"project-1\">Project 1</Select.Option>\n      <Select.Option id=\"abc\">ABC</Select.Option>\n      <Select.Option id=\"project-2lines\">\n        Project with an even longer name that breaks into 2 lines\n      </Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n### Validation\n\n#### Default\n\nA select input's prompting the user to make a choice without implying a specific\nselection.\n\n```jsx live\nconst App = () => (\n  <Select.Root aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Invalid\n\nUse to immediately communicate the error to the user. Utilize error text when\nneeded.\n\n```jsx live\nconst App = () => (\n  <Select.Root aria-label=\"Select a fruit\" isInvalid>\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Disabled\n\nThis is the disabled state.\n\n```jsx live\nconst App = () => (\n  <Select.Root aria-label=\"Select a fruit\" isDisabled>\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Placeholder\n\nThe purpose of placeholder text is to provide a clear prompt or instruction,\nguiding the user on what action is expected.\n\n```jsx live\nconst App = () => (\n  <Select.Root placeholder=\"Select a fruit\" aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nSelect inputs have two main appearances, two sizes, and several states that will\nrespond to validation status. **Currently, this is a single value selector, this\nwill be reworked to bring in multi-select in the future.**\n\n### Resources\n\n[ARIA APG: Listbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)\n[React ARIA: Select](https://react-spectrum.adobe.com/react-aria/Select.html)\n[Figma Library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=2304-22847&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Height options\n\n#### Medium\n\nThis is the default size for the select input.\n\n```jsx live\nconst App = () => (\n  <Select.Root size=\"md\" aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Small\n\nFor use in areas that require more condensed styling.\n\n```jsx live\nconst App = () => (\n  <Select.Root size=\"sm\" aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n### Fixed width\n\n#### Solid-styled\n\nMax width when not in a page wide form should be 268px. If the solid-styled\nselect input field is inline a page wide form match popover width to match the\nsize of the form fields.\n\n```jsx live\nconst App = () => (\n  <Select.Root aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Ghost-styled\n\nHug the select-input field, this styling needs closer placement to the drop down\nicon than a solid-styled version. The popover width has two options with this\nplacement based on content. Short content should match the hug width of the\nfield. Longer content should have a max width of 268px.\n\n```jsx live\nconst App = () => (\n  <Select.Root variant=\"ghost\" aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n### Text wrapping\n\n#### Text wrapping within popover\n\nPlease encourage short text when possible. When applicable, wrap text onto\nanother line when needed.\n\n```jsx live\nconst App = () => (\n  <Select.Root defaultSelectedKey=\"project-1\" w=\"6400\">\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"project-long\">\n        Project with a very long name\n      </Select.Option>\n      <Select.Option id=\"project-1\">Project 1</Select.Option>\n      <Select.Option id=\"abc\">ABC</Select.Option>\n      <Select.Option id=\"project-2lines\">\n        Project with an even longer name that breaks into 2 lines\n      </Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Truncate when long line item is selected\n\nIf selected, truncate text so it does not overlap over the icons in the select\ninput field.\n\n```jsx live\nconst App = () => (\n  <Select.Root defaultSelectedKey=\"project-2lines\" w=\"6400\">\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"project-long\">\n        Project with a very long name\n      </Select.Option>\n      <Select.Option id=\"project-1\">Project 1</Select.Option>\n      <Select.Option id=\"abc\">ABC</Select.Option>\n      <Select.Option id=\"project-2lines\">\n        Project with an even longer name that breaks into 2 lines\n      </Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n### Validation\n\n#### Default\n\nA select input's prompting the user to make a choice without implying a specific\nselection.\n\n```jsx live\nconst App = () => (\n  <Select.Root aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Invalid\n\nUse to immediately communicate the error to the user. Utilize error text when\nneeded.\n\n```jsx live\nconst App = () => (\n  <Select.Root aria-label=\"Select a fruit\" isInvalid>\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Disabled\n\nThis is the disabled state.\n\n```jsx live\nconst App = () => (\n  <Select.Root aria-label=\"Select a fruit\" isDisabled>\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Placeholder\n\nThe purpose of placeholder text is to provide a clear prompt or instruction,\nguiding the user on what action is expected.\n\n```jsx live\nconst App = () => (\n  <Select.Root placeholder=\"Select a fruit\" aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Height options",
+          "href": "#height-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Medium",
+          "href": "#medium",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Small",
+          "href": "#small",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Fixed width",
+          "href": "#fixed-width",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Solid-styled",
+          "href": "#solid-styled",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Ghost-styled",
+          "href": "#ghost-styled",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Text wrapping",
+          "href": "#text-wrapping",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Text wrapping within popover",
+          "href": "#text-wrapping-within-popover",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Truncate when long line item is selected",
+          "href": "#truncate-when-long-line-item-is-selected",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Validation",
+          "href": "#validation",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Default",
+          "href": "#default",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Invalid",
+          "href": "#invalid",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            4,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled",
+          "href": "#disabled",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            4,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Placeholder",
+          "href": "#placeholder",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            4,
+            4
+          ],
+          "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  <Select.Root size=\"md\" aria-label=\"Select a fruit\">\n    <Select.Options>\n      <Select.Option>Apples</Select.Option>\n      <Select.Option>Bananas</Select.Option>\n      <Select.Option>Oranges</Select.Option>\n      <Select.Option>Cherries</Select.Option>\n    </Select.Options>\n  </Select.Root>\n)\n```\n\n### Accessibility standards\n\n- **Provide clear labels:** Use the `<label>` element to programmatically\n  associate a clear, descriptive label with the select input.\n- **Group related inputs:** Group related select inputs within a `<fieldset>`\n  and provide a `<legend>` to give context to the group.\n- **Don't rely on color alone:** Avoid relying solely on color to convey\n  information or the state of the select input. Ensure other visual cues convey\n  the necessary information.\n- **Ensure sufficient contrast:** Ensure sufficient color contrast exists\n  between the select input's text, background, and border. Use a contrast\n  checking tool to verify contrast ratios meet minimum requirements.\n- **Keyboard navigation:** Make the select input fully operable using the\n  keyboard. Allow users to navigate using Tab, open/close dropdown with Spacebar\n  or Enter, navigate options with arrow keys, and select with Enter.\n- **Focus visible:** Provide a clear and visible focus indicator for the select\n  input when it receives keyboard focus.\n- **No unexpected changes:** Prevent the select input from unexpectedly changing\n  the context of the page when it receives focus. Ensure changes are initiated\n  by user selection.\n- **Clear instructions:** Provide clear and concise labels or instructions for\n  the select input that accurately reflect its purpose.\n- **Error suggestions:** If an input error is automatically detected and\n  suggestions for correction are known, provide the suggestions to the user.\n- **Use semantic HTML:** Use semantic HTML elements (`<select>`, `<option>`) to\n  define the role, name, and value of the select input.\n- **ARIA attributes:** Use ARIA attributes when necessary to provide additional\n  information to assistive technologies, especially for complex or custom\n  implementations.\n\n### Resources\n\n- [W3C ARIA Authoring Practices Guide (APG) - Listbox](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)\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 { Select, type SelectProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses uncontrolled mode:\n\n```jsx live-dev\nconst App = () => (\n  <Select.Root aria-label=\"Select a fruit\">\n    <Select.Options placeholder=\"Select an option\">\n      <Select.Option id=\"apple\">Apple</Select.Option>\n      <Select.Option id=\"banana\">Banana</Select.Option>\n      <Select.Option id=\"orange\">Orange</Select.Option>\n    </Select.Options>\n  </Select.Root>\n)\n```\n\n## Working with selection values\n\nThe Select component uses React Aria's selection pattern, which uses keys (strings or numbers) to identify selected options.\n\n### Selection value types\n\nThe component accepts and returns selection keys:\n\n```tsx\n// String keys \n<Select.Option id=\"apple\">Apple</Select.Option>\n\n// Number keys\n<Select.Option id={1}>Option 1</Select.Option>\n```\n\n\n### Selection structure\n\n```tsx\n// Uncontrolled mode\n<Select.Root\n  defaultSelectedKey=\"apple\"\n  onSelectionChange={(key) => {}}\n>\n  <Select.Options>\n    <Select.Option id=\"apple\">Apple</Select.Option>\n  </Select.Options>\n</Select.Root>\n\n// Controlled mode\nconst [selectedKey, setSelectedKey] = useState<Key | null>(null);\n\n<Select.Root\n  selectedKey={selectedKey}\n  onSelectionChange={setSelectedKey}\n>\n  <Select.Options>\n    <Select.Option id=\"apple\">Apple</Select.Option>\n  </Select.Options>\n</Select.Root>\n```\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  <Stack direction=\"column\" gap=\"400\">\n    <Select.Root size=\"sm\" aria-label=\"Small select\">\n      <Select.Options placeholder=\"Select...\">\n        <Select.Option id=\"1\">Option 1</Select.Option>\n        <Select.Option id=\"2\">Option 2</Select.Option>\n      </Select.Options>\n    </Select.Root>\n    <Select.Root size=\"md\" aria-label=\"Medium select\">\n      <Select.Options placeholder=\"Select...\">\n        <Select.Option id=\"1\">Option 1</Select.Option>\n        <Select.Option id=\"2\">Option 2</Select.Option>\n      </Select.Options>\n    </Select.Root>\n  </Stack>\n)\n```\n\n### Disabled state\n\nUse `isDisabled` to disable the select:\n\n```jsx live-dev\nconst App = () => (\n  <Select.Root isDisabled aria-label=\"Disabled select\">\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"1\">Option 1</Select.Option>\n      <Select.Option id=\"2\">Option 2</Select.Option>\n    </Select.Options>\n  </Select.Root>\n)\n```\n\n### Visual variants\n\nChoose between `outline` and `ghost` variants to match your design context:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Select.Root variant=\"outline\" aria-label=\"Outline select\">\n      <Select.Options placeholder=\"Select...\">\n        <Select.Option id=\"1\">Option 1</Select.Option>\n        <Select.Option id=\"2\">Option 2</Select.Option>\n      </Select.Options>\n    </Select.Root>\n    <Select.Root variant=\"ghost\" aria-label=\"Ghost select\">\n      <Select.Options placeholder=\"Select...\">\n        <Select.Option id=\"1\">Option 1</Select.Option>\n        <Select.Option id=\"2\">Option 2</Select.Option>\n      </Select.Options>\n    </Select.Root>\n  </Stack>\n)\n```\n\n### Uncontrolled mode\n\nFor simpler use cases, use uncontrolled mode with `defaultSelectedKey` and `onSelectionChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedValue, setSelectedValue] = useState<string>('Selected: banana');\n\n  return (\n  <Stack direction=\"column\" gap=\"400\">\n      <Select.Root\n        defaultSelectedKey=\"banana\"\n        onSelectionChange={(key) => {\n          setSelectedValue(key ? `Selected: ${key}` : 'No selection');\n        }}\n        aria-label=\"Select a fruit\"\n      >\n        <Select.Options placeholder=\"Choose a fruit\">\n          <Select.Option id=\"apple\">Apple</Select.Option>\n          <Select.Option id=\"banana\">Banana</Select.Option>\n          <Select.Option id=\"orange\">Orange</Select.Option>\n        </Select.Options>\n      </Select.Root>\n      <Text fontSize=\"sm\">{selectedValue}</Text>\n    </Stack>\n  );\n}\n```\n\n\n### Controlled mode\n\n\nFor scenarios requiring programmatic control or coordination with other components, use controlled mode:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedKey, setSelectedKey] = useState<Key | null>(null);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Select.Root\n        selectedKey={selectedKey}\n        onSelectionChange={setSelectedKey}\n        aria-label=\"Select a fruit\"\n      >\n        <Select.Options placeholder=\"Choose a fruit\">\n          <Select.Option id=\"apple\">Apple</Select.Option>\n          <Select.Option id=\"banana\">Banana</Select.Option>\n          <Select.Option id=\"orange\">Orange</Select.Option>\n        </Select.Options>\n      </Select.Root>\n      <Text fontSize=\"sm\">\n        {selectedKey ? `Selected: ${selectedKey}` : 'No selection'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Option groups\n\nGroup related options with `Select.OptionGroup`:\n\n```jsx live-dev\nconst App = () => (\n  <Select.Root aria-label=\"Select a food\">\n    <Select.Options placeholder=\"Choose a food\">\n      <Select.OptionGroup label=\"Fruits\">\n        <Select.Option id=\"apple\">Apple</Select.Option>\n        <Select.Option id=\"banana\">Banana</Select.Option>\n        <Select.Option id=\"orange\">Orange</Select.Option>\n      </Select.OptionGroup>\n      <Select.OptionGroup label=\"Vegetables\">\n        <Select.Option id=\"carrot\">Carrot</Select.Option>\n        <Select.Option id=\"broccoli\">Broccoli</Select.Option>\n        <Select.Option id=\"spinach\">Spinach</Select.Option>\n      </Select.OptionGroup>\n    </Select.Options>\n  </Select.Root>\n)\n```\n\n### Dynamic options with items\n\n`Select.Options` supports the `items` prop, a pattern unique to React Aria Components (inherited from React Aria's `ListBox` component). This pattern provides 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 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  <Select.Root aria-label=\"Select a fruit\">\n    <Select.Options placeholder=\"Choose a fruit\">\n      <Select.Option id=\"apple\">Apple</Select.Option>\n      <Select.Option id=\"banana\">Banana</Select.Option>\n      <Select.Option id=\"orange\">Orange</Select.Option>\n    </Select.Options>\n  </Select.Root>\n)\n```\n\n**Dynamic items example:**\n\nWhen using `items`, children must be a render function that receives each item and returns a `Select.Option`. This example demonstrates using `items` with data 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 fruits = [\n    { id: 'apple', name: 'Apple' },\n    { id: 'banana', name: 'Banana' },\n    { id: 'orange', name: 'Orange' },\n  ];\n\n  return (\n    <Select.Root aria-label=\"Select a fruit\">\n      <Select.Options items={fruits} placeholder=\"Choose a fruit\">\n        {(item) => (\n          <Select.Option id={item.id}>{item.name}</Select.Option>\n        )}\n      </Select.Options>\n    </Select.Root>\n  );\n}\n```\n\nThe `items` pattern enables React Aria to optimize rendering and provides better support for features like virtualization, which can improve performance with large option lists.\n\n> [!TIP]\\\n> See [React Aria's ListBox documentation](https://react-spectrum.adobe.com/react-aria/ListBox.html#sections) for complete API reference and advanced usage, including static and dynamic items.\n\n### Clearable selection\n\nUse `isClearable` to show a clear button:\n\n```jsx live-dev\nconst App = () => (\n  <Select.Root\n    isClearable\n    defaultSelectedKey=\"banana\"\n    aria-label=\"Select a fruit\"\n  >\n    <Select.Options placeholder=\"Choose a fruit\">\n      <Select.Option id=\"apple\">Apple</Select.Option>\n      <Select.Option id=\"banana\">Banana</Select.Option>\n      <Select.Option id=\"orange\">Orange</Select.Option>\n    </Select.Options>\n  </Select.Root>\n)\n```\n\n\n### Leading element\n\nUse `leadingElement` to add an icon or element at the start of the trigger:\n\n```jsx live-dev\nconst App = () => (\n  <Select.Root\n    leadingElement={<Icon as={Icons.SentimentSatisfied} />}\n    aria-label=\"Select an option\"\n  >\n    <Select.Options placeholder=\"Choose...\">\n      <Select.Option id=\"1\">Option 1</Select.Option>\n      <Select.Option id=\"2\">Option 2</Select.Option>\n    </Select.Options>\n  </Select.Root>\n)\n```\n\n\n\n## Component requirements\n\n### Selection value types\n\nSelection values **must** be keys (strings or numbers) that match the `id` prop of `Select.Option` components.\n\n## Accessibility\n\nThe Select handles most accessibility requirements internally. However, you must always associate an internationalized label with the component. Visual labels are preferable, and can be set by:\n\n- Associating a `<label>` element with the `Select.Root` using `aria-labelledby`:\n\n```tsx\n<label id=\"label-id\">\n  {msg.format(labelMessage)}\n</label>\n<Select.Root aria-labelledby=\"label-id\">\n  <Select.Options>\n    <Select.Option id=\"1\">Option 1</Select.Option>\n  </Select.Options>\n</Select.Root>\n```\n\n- Associating a `<label>` element with the `Select.Root` using `htmlFor`:\n\n```tsx\n<label htmlFor=\"select-id\">\n  {msg.format(labelMessage)}\n</label>\n<Select.Root id=\"select-id\">\n  <Select.Options>\n    <Select.Option id=\"1\">Option 1</Select.Option>\n  </Select.Options>\n</Select.Root>\n```\n\nFor hidden labels, use `aria-label`:\n\n```tsx\n<Select.Root aria-label={msg.format(labelMessage)}>\n  <Select.Options>\n    <Select.Option id=\"1\">Option 1</Select.Option>\n  </Select.Options>\n</Select.Root>\n```\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-select\";\n\nexport const Example = () => (\n  <Select.Root id={PERSISTENT_ID} aria-label=\"Select an option\">\n    <Select.Options>\n      <Select.Option id=\"1\">Option 1</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Navigate to/from the select\n- `Enter` / `Space`: Open the dropdown\n- `Arrow keys`: Navigate through options when open\n- `Enter`: Select the focused option\n- `Escape`: Close the dropdown\n- `Home` / `End`: Jump to first/last option\n- Type to search: Type characters to jump to matching options\n\n## API reference\n\n<PropsTable id=\"Select\" />\n\n## Common patterns\n\n### Filtering data by selection\n\nA common use case is filtering lists or tables by a selected option:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedCategory, setSelectedCategory] = useState<Key | null>(null);\n\n  // Filter data based on selectedCategory\n  const appliedFilter = selectedCategory\n    ? `Showing items in category: ${selectedCategory}`\n    : 'No filter applied';\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Select.Root\n        selectedKey={selectedCategory}\n        onSelectionChange={setSelectedCategory}\n        aria-label=\"Filter by category\"\n      >\n        <Select.Options placeholder=\"All categories\">\n          <Select.Option id=\"electronics\">Electronics</Select.Option>\n          <Select.Option id=\"clothing\">Clothing</Select.Option>\n          <Select.Option id=\"books\">Books</Select.Option>\n        </Select.Options>\n      </Select.Root>\n      <Text fontSize=\"sm\">{appliedFilter}</Text>\n    </Stack>\n  );\n}\n```\n\n### Country/region selection\n\nExample for selecting a country, region, or category:\n\n```jsx live-dev\nconst App = () => {\n  const [country, setCountry] = useState<Key | null>(null);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Select.Root\n        selectedKey={country}\n        onSelectionChange={setCountry}\n        aria-label=\"Select country\"\n        isRequired\n      >\n        <Select.Options placeholder=\"Choose a country\">\n          <Select.Option id=\"us\">United States</Select.Option>\n          <Select.Option id=\"uk\">United Kingdom</Select.Option>\n          <Select.Option id=\"ca\">Canada</Select.Option>\n          <Select.Option id=\"de\">Germany</Select.Option>\n        </Select.Options>\n      </Select.Root>\n      {country && (\n        <Text fontSize=\"sm\">\n          Selected country: {country}\n        </Text>\n      )}\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Select within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-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 } from \"react\";\nimport type { Key } from \"react-aria-components\";\nimport { Select, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Select - Basic rendering\", () => {\n  it(\"renders select trigger button\", () => {\n    render(\n      <NimbusProvider>\n        <Select.Root aria-label=\"Select an option\">\n          <Select.Options>\n            <Select.Option id=\"1\">Option 1</Select.Option>\n          </Select.Options>\n        </Select.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /Select an option/ })\n    ).toBeInTheDocument();\n  });\n\n  it(\"displays default placeholder text\", () => {\n    render(\n      <NimbusProvider>\n        <Select.Root aria-label=\"Select an option\">\n          <Select.Options>\n            <Select.Option id=\"1\">Option 1</Select.Option>\n          </Select.Options>\n        </Select.Root>\n      </NimbusProvider>\n    );\n\n    // Default placeholder is \"Select an item\"\n    expect(screen.getByText(\"Select an item\")).toBeInTheDocument();\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 } from \"react\";\nimport type { Key } from \"react-aria-components\";\nimport { Select, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Select - Interactions\", () => {\n  it(\"opens dropdown when button is clicked\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Select.Root aria-label=\"Select an option\">\n          <Select.Options>\n            <Select.Option id=\"1\">Option 1</Select.Option>\n            <Select.Option id=\"2\">Option 2</Select.Option>\n          </Select.Options>\n        </Select.Root>\n      </NimbusProvider>\n    );\n\n    const select = screen.getByRole(\"button\", { name: /Select an option/ });\n    await user.click(select);\n\n    // The popover is rendered via a react portal outside of the select root\n    // and can only be found by querying the document directly\n    await waitFor(() => {\n      const listbox = document.querySelector('[role=\"listbox\"]');\n      expect(listbox).toBeInTheDocument();\n    });\n  });\n\n  it(\"selects an option when clicked\", async () => {\n    const user = userEvent.setup();\n    const handleSelectionChange = vi.fn();\n    render(\n      <NimbusProvider>\n        <Select.Root\n          aria-label=\"Select an option\"\n          onSelectionChange={handleSelectionChange}\n        >\n          <Select.Options>\n            <Select.Option id=\"1\">Option 1</Select.Option>\n            <Select.Option id=\"2\">Option 2</Select.Option>\n          </Select.Options>\n        </Select.Root>\n      </NimbusProvider>\n    );\n\n    const select = screen.getByRole(\"button\", { name: /Select an option/ });\n    await user.click(select);\n\n    // Options are in the portal, query the document directly\n    await waitFor(() => {\n      const options = document.querySelectorAll('[role=\"option\"]');\n      expect(options.length).toBeGreaterThan(0);\n    });\n    const options = document.querySelectorAll('[role=\"option\"]');\n    await user.click(options[1]);\n\n    expect(handleSelectionChange).toHaveBeenCalledWith(\"2\");\n  });\n});\n```\n\n### Controlled State Tests\n\nTest controlled selection state\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 } from \"react\";\nimport type { Key } from \"react-aria-components\";\nimport { Select, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Select - Controlled state\", () => {\n  it(\"displays selected value\", () => {\n    const TestComponent = () => {\n      const [selectedKey] = useState<Key | null>(\"2\");\n      return (\n        <NimbusProvider>\n          <Select.Root\n            selectedKey={selectedKey}\n            onSelectionChange={() => {}}\n            aria-label=\"Select an option\"\n          >\n            <Select.Options>\n              <Select.Option id=\"1\">Option 1</Select.Option>\n              <Select.Option id=\"2\">Option 2</Select.Option>\n            </Select.Options>\n          </Select.Root>\n        </NimbusProvider>\n      );\n    };\n\n    render(<TestComponent />);\n\n    // The selected value appears in the button label\n    const button = screen.getByRole(\"button\", { name: /Select an option/ });\n    expect(button).toHaveTextContent(\"Option 2\");\n  });\n});\n```\n\n### Option Group 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 } from \"react\";\nimport type { Key } from \"react-aria-components\";\nimport { Select, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Select - Option groups\", () => {\n  it(\"renders grouped options\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Select.Root aria-label=\"Select an option\">\n          <Select.Options>\n            <Select.OptionGroup label=\"Fruits\">\n              <Select.Option id=\"apple\">Apple</Select.Option>\n              <Select.Option id=\"banana\">Banana</Select.Option>\n            </Select.OptionGroup>\n            <Select.OptionGroup label=\"Vegetables\">\n              <Select.Option id=\"carrot\">Carrot</Select.Option>\n            </Select.OptionGroup>\n          </Select.Options>\n        </Select.Root>\n      </NimbusProvider>\n    );\n\n    const select = screen.getByRole(\"button\", { name: /Select an option/ });\n    await user.click(select);\n\n    await waitFor(() => {\n      expect(screen.getByText(\"Fruits\")).toBeInTheDocument();\n      expect(screen.getByText(\"Vegetables\")).toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Disabled State Tests\n\nTest that the select 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 } from \"react\";\nimport type { Key } from \"react-aria-components\";\nimport { Select, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Select - Disabled state\", () => {\n  it(\"renders disabled select\", () => {\n    render(\n      <NimbusProvider>\n        <Select.Root isDisabled aria-label=\"Select an option\">\n          <Select.Options>\n            <Select.Option id=\"1\">Option 1</Select.Option>\n          </Select.Options>\n        </Select.Root>\n      </NimbusProvider>\n    );\n\n    const select = screen.getByRole(\"button\", { name: /Select an option/ });\n    expect(select).toBeDisabled();\n  });\n});\n```\n\n### Invalid State Tests\n\nTest that the select 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 } from \"react\";\nimport type { Key } from \"react-aria-components\";\nimport { Select, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Select - Invalid state\", () => {\n  it(\"renders invalid select\", () => {\n    render(\n      <NimbusProvider>\n        <Select.Root isInvalid aria-label=\"Select an option\">\n          <Select.Options>\n            <Select.Option id=\"1\">Option 1</Select.Option>\n          </Select.Options>\n        </Select.Root>\n      </NimbusProvider>\n    );\n\n    // Invalid state is on the root element.\n    const button = screen.getByRole(\"button\", { name: /Select an option/ });\n    const selectRoot = button.closest('[data-invalid=\"true\"]');\n    expect(selectRoot).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-select--docs)\n- [React Aria Select](https://react-spectrum.adobe.com/react-aria/Select.html)\n- [ARIA Listbox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/)",
+      "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": "Working with selection values",
+          "href": "#working-with-selection-values",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Selection value types",
+          "href": "#selection-value-types",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Selection structure",
+          "href": "#selection-structure",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual variants",
+          "href": "#visual-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Option groups",
+          "href": "#option-groups",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Dynamic options with items",
+          "href": "#dynamic-options-with-items",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Clearable selection",
+          "href": "#clearable-selection",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Leading element",
+          "href": "#leading-element",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Selection value types",
+          "href": "#selection-value-types-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            5,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Filtering data by selection",
+          "href": "#filtering-data-by-selection",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Country/region selection",
+          "href": "#countryregion-selection",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled State Tests",
+          "href": "#controlled-state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Option Group Tests",
+          "href": "#option-group-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled State Tests",
+          "href": "#disabled-state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Invalid State Tests",
+          "href": "#invalid-state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            9
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nDesign guidelines offer a set of standardized rules and recommendations that\nensure consistency, usability, and accessibility across all design elements and\ninteractions.\n\n### Best practice\n\n- **Include a label:** Give the users context on what is being asked for when\n  making a selection. A picker without a label is ambiguous and not accessible.\n  Use \"Select\" or \"Search and select\" as a default placeholder label wording.\n  - In rare cases where context is sufficient to not need a label, these\n    placements should still be given an aria-label in HTML.\n  - **Placeholders:** Should function as a prompt not a value. Do not use a\n    placeholder as a label.\n- **Keep contents concise:** Long menu items that wrap to multiple lines should\n  be kept to a minimum. If this becomes a frequent concern, consider an\n  alternate UI component or pattern to allow for more breathing room for\n  content.\n- **Organize content:** The default organization is alphabetical, if a user\n  benefits from better organization please improve their experience with better\n  categories.\n- **Include help text when needed:** If more information is needed to provide\n  context, include helper text below the field for the user. Replace helper text\n  with error text if applicable and needed.\n- **Don't neglect ARIA attributes:** If you are building a custom select input,\n  ensure that you use proper ARIA attributes to make the select box accessible\n  to screen readers.\n\n#### When to use a solid vs. ghost styled select input\n\n| **Type**        | **Use this instead**                                                                                                                                                                                                                                                                                                                              |\n| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **Solid-style** | <ul><li>The default option to use in forms.</li><li>Typically the best experience to use with content created by a user.</li><li>When you want to include search for the content.</li></ul>                                                                                                                                                       |\n| **Ghost-style** | <ul><li>The default option to use to filter or build rules around content. Ex: filtering assets for the user.</li><li>Best used within rule building experiences such as discounts.</li><li>Ideal to be used in condensed areas, with condensed and familiar options for the user, as in simple filters or quick actions like \"delete\".</li></ul> |\n\n### Usage\n\nSelect inputs are common and users are familiar with their uses. Keeping\nconsistent with the guidelines will help our products intuitive and easy to\nunderstand, even through complicated areas.\n\n### Solid-styled widths\n\nThese placements are more regular, they have either a maximum width of 268px or\nform wide. The popover width should match the width of the field itself.\n\n> [!TIP]\\\n> **Do**\n>\n> - The form is at maximum size (when not in a pull page form) and the popover\n>   matches the width of the field.\n> - Longer options flow to the next lines, and when chosen, those longer texts\n>   are truncated so the user can still see the icons clearly.\n\n```jsx live\nconst App = () => (\n  <Select.Root defaultSelectedKey=\"project-1\" w=\"6400\">\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"project-long\">\n        Project with a very long name\n      </Select.Option>\n      <Select.Option id=\"project-1\">Project 1</Select.Option>\n      <Select.Option id=\"abc\">ABC</Select.Option>\n      <Select.Option id=\"project-2lines\">\n        Project with an even longer name that breaks into 2 lines\n      </Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not have different widths for select inputs.\n> - Do not change the width of the field to match the content once selected.\n\n```jsx live\nconst App = () => (\n  <Select.Root variant=\"ghost\" defaultSelectedKey=\"project-1\">\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"project-long\">\n        Project with a very long name\n      </Select.Option>\n      <Select.Option id=\"project-1\">Project 1</Select.Option>\n      <Select.Option id=\"abc\">ABC</Select.Option>\n      <Select.Option id=\"project-2lines\">\n        Project with an even longer name that breaks into 2 lines\n      </Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n### Ghost-styled widths\n\nThere are a few differences that ghost-styled select inputs have that aren't\nneeded with solid-style placements. Ghost-styled fields should hug width, with\npopovers having a min width matching the field, and max width being 268px unless\non a page wide form.\n\n> [!TIP]\\\n> **Do**\n>\n> - Select input field width set to \"hug\" with max width popover at 268px.\n> - Content flows to next line when needed.\n\n```jsx live\nconst App = () => (\n  <Select.Root variant=\"ghost\" defaultSelectedKey=\"project-1\">\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"project-long\">\n        Project with a very long name\n      </Select.Option>\n      <Select.Option id=\"project-1\">Project 1</Select.Option>\n      <Select.Option id=\"abc\">ABC</Select.Option>\n      <Select.Option id=\"project-2lines\">\n        Project with an even longer name that breaks into 2 lines\n      </Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - This drop down icon looks like it is not related to the select input field.\n> - Do not truncate options that should flow to the next line.\n\n```jsx live\nconst App = () => (\n  <Select.Root defaultSelectedKey=\"project-1\" w=\"6400\">\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"project-long\">\n        Project with a very long name\n      </Select.Option>\n      <Select.Option id=\"project-1\">Project 1</Select.Option>\n      <Select.Option id=\"abc\">ABC</Select.Option>\n      <Select.Option\n        id=\"project-2lines\"\n        overflow=\"hidden\"\n        textOverflow=\"ellipsis\"\n        whiteSpace=\"nowrap\"\n      >\n        Project with an even longer name that breaks into 2 lines\n      </Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n> [!TIP]\\\n> **Do**\n>\n> - With short selectable content, match content width to match the select input\n>   \"hug\" width.\n\n```jsx live\nconst App = () => (\n  <Select.Root variant=\"ghost\" defaultSelectedKey=\"1\">\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"0\">0</Select.Option>\n      <Select.Option id=\"1\">1</Select.Option>\n      <Select.Option id=\"2\">2</Select.Option>\n      <Select.Option id=\"3\">3</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not set the popover width to \"hug\", this content should match the width\n>   of the field.\n\n```jsx live\nconst App = () => (\n  <Select.Root variant=\"ghost\" defaultSelectedKey=\"1\" w=\"6400\">\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"0\">0</Select.Option>\n      <Select.Option id=\"1\">1</Select.Option>\n      <Select.Option id=\"2\">2</Select.Option>\n      <Select.Option id=\"3\">3</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n### Labels and preselection\n\nMake sure to place tooltips in areas where they will be seen easily.\n\n> [!TIP]\\\n> **Do**\n>\n> - Use a short and easily understandable label. Describe, do not use labels as\n>   instructions.\n> - Use placeholder if there isn't a most common or default choice.\n\n```jsx live\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Favorite color</FormField.Label>\n    <FormField.Input>\n      <Select.Root aria-label=\"Favorite color\">\n        <Select.Options placeholder=\"Select...\">\n          <Select.Option id=\"red\">Red</Select.Option>\n          <Select.Option id=\"blue\">Blue</Select.Option>\n          <Select.Option id=\"green\">Green</Select.Option>\n          <Select.Option id=\"teal\">Teal</Select.Option>\n        </Select.Options>\n      </Select.Root>\n    </FormField.Input>\n  </FormField.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not rely on placeholders instead of labels.\n> - Do not preselect a random option unless it's genuinely the most common or\n>   default choice.\n\n```jsx live\nconst App = () => (\n  <Select.Root\n    isClearable\n    defaultSelectedKey=\"green\"\n    aria-label=\"Favorite color\"\n  >\n    <Select.Options placeholder=\"Select...\">\n      <Select.Option id=\"red\">Red</Select.Option>\n      <Select.Option id=\"blue\">Blue</Select.Option>\n      <Select.Option id=\"green\">Green</Select.Option>\n      <Select.Option id=\"teal\">Teal</Select.Option>\n    </Select.Options>\n  </Select.Root>\n);\n```\n\n### Labels and layout exceptions\n\nWith the ghost styling for labels, there are some placements that can be used\nwithout labels and have varying widths based on placement. These are most\ncommonly found in filters and with rule builders.\n\n> [!TIP]\\\n> **Do**\n>\n> - Use a short and easily understandable label.\n> - Use placeholder if there isn't a most common or default choice.\n\n```jsx live\nconst App = () => (\n  <Flex alignItems=\"center\" gap=\"200\">\n    <Text>Color</Text>\n    <Text>is</Text>\n    <Select.Root variant=\"ghost\" aria-label=\"Color value\">\n      <Select.Options placeholder=\"Select...\">\n        <Select.Option id=\"red\">Red</Select.Option>\n        <Select.Option id=\"blue\">Blue</Select.Option>\n        <Select.Option id=\"green\">Green</Select.Option>\n        <Select.Option id=\"teal\">Teal</Select.Option>\n      </Select.Options>\n    </Select.Root>\n  </Flex>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Try not to overuse drop downs. Do not make it unclear what parts of a\n>   ghost-styled are interactive to the user.\n> - Make sure that if logic is being used that it goes through user testing and\n>   is understandable for the targeted user.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"200\">\n    <Flex alignItems=\"center\" gap=\"100\" flexWrap=\"wrap\">\n      <Text>item's location is</Text>\n      <Select.Root\n        variant=\"ghost\"\n        defaultSelectedKey=\"us\"\n        aria-label=\"Location\"\n        isClearable={false}\n      >\n        <Select.Options>\n          <Select.Option id=\"us\">United States</Select.Option>\n          <Select.Option id=\"uk\">United Kingdom</Select.Option>\n          <Select.Option id=\"ca\">Canada</Select.Option>\n        </Select.Options>\n      </Select.Root>\n      <Text>and color</Text>\n      <Select.Root\n        variant=\"ghost\"\n        defaultSelectedKey=\"is-blue\"\n        aria-label=\"Color condition\"\n        isClearable={false}\n      >\n        <Select.Options>\n          <Select.Option id=\"is-blue\">is blue</Select.Option>\n          <Select.Option id=\"is-red\">is red</Select.Option>\n          <Select.Option id=\"is-teal\">is teal</Select.Option>\n        </Select.Options>\n      </Select.Root>\n    </Flex>\n    <Flex alignItems=\"center\" gap=\"100\" flexWrap=\"wrap\">\n      <Text>apply discounts to</Text>\n      <Select.Root\n        variant=\"ghost\"\n        defaultSelectedKey=\"all\"\n        aria-label=\"Apply to\"\n        isClearable={false}\n      >\n        <Select.Options>\n          <Select.Option id=\"all\">all of matching items</Select.Option>\n          <Select.Option id=\"some\">some of matching items</Select.Option>\n        </Select.Options>\n      </Select.Root>\n    </Flex>\n    <Flex alignItems=\"center\" gap=\"100\" flexWrap=\"wrap\">\n      <Text>except</Text>\n      <Select.Root\n        variant=\"ghost\"\n        defaultSelectedKey=\"if-teal\"\n        aria-label=\"Exception\"\n        isClearable={false}\n      >\n        <Select.Options>\n          <Select.Option id=\"if-teal\">if item is teal</Select.Option>\n          <Select.Option id=\"if-blue\">if item is blue</Select.Option>\n        </Select.Options>\n      </Select.Root>\n    </Flex>\n  </Stack>\n);\n```\n\n### Keep menu items concise\n\nKeep menu items short and concise. Long menu items that cause text to wrap\nmultiple lines are discouraged. If text wrapping becomes a frequent concern,\nconsider revising the text or use alternative UI patterns that will give your\ncontent more space.\n\n> [!TIP]\\\n> **Do**\n>\n> - Use a short and easily understandable label. Describe, do not use labels as\n>   instructions.\n> - Text can flow to three lines, but truncate further text.\n\n```jsx live\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Discount templates</FormField.Label>\n    <FormField.Input>\n      <Select.Root aria-label=\"Discount templates\">\n        <Select.Options placeholder=\"Select...\">\n          <Select.OptionGroup label=\"Product discounts\">\n            <Select.Option id=\"pct-off-product\">\n              Percentage off product\n            </Select.Option>\n            <Select.Option id=\"amt-off-product\">\n              Amount off product\n            </Select.Option>\n          </Select.OptionGroup>\n          <Select.OptionGroup label=\"Cart discounts with line items\">\n            <Select.Option id=\"pct-off-cart\">\n              Percentage off item(s) on cart\n            </Select.Option>\n            <Select.Option id=\"amt-off-cart\">\n              Amount off item(s) in cart\n            </Select.Option>\n            <Select.Option id=\"buy-x-get-x\">\n              Buy x get x with percentage off\n            </Select.Option>\n            <Select.Option id=\"fixed-price\">Fixed-price in cart</Select.Option>\n            <Select.Option id=\"discounted-shipping\">\n              Discounted shipping\n            </Select.Option>\n            <Select.Option id=\"gift\">Gift with purchase</Select.Option>\n            <Select.Option id=\"amt-total-spend\">\n              Amount off based on total spend\n            </Select.Option>\n            <Select.Option id=\"pct-total-spend\">\n              Percentage off based on total spend\n            </Select.Option>\n          </Select.OptionGroup>\n          <Select.OptionGroup label=\"Cart discounts with custom line items\">\n            <Select.Option id=\"custom-pct\">\n              Percentage off item(s) in cart\n            </Select.Option>\n            <Select.Option id=\"custom-amt\">\n              Amount off item(s) in cart\n            </Select.Option>\n            <Select.Option id=\"custom-buy-x\">\n              Buy x get x with percentage off\n            </Select.Option>\n          </Select.OptionGroup>\n        </Select.Options>\n      </Select.Root>\n    </FormField.Input>\n  </FormField.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Keep content short or make sure that the location has enough room to display\n>   content with more space.\n> - Don't use additional labels or explainers when unneeded.\n> - Do not encourage lengthy text for drop down experiences. Text can flow to\n>   three lines, but truncate further text.\n\n```jsx live\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Discount templates</FormField.Label>\n    <FormField.Input>\n      <Select.Root aria-label=\"Discount templates\">\n        <Select.Options placeholder=\"Select...\">\n          <Select.OptionGroup label=\"Product discounts\">\n            <Select.Option\n              id=\"pct-off-product\"\n              textValue=\"Percentage off product\"\n            >\n              Discount the target item(s) relative to its price.\n              <Text slot=\"description\">Discount type: relative</Text>\n            </Select.Option>\n            <Select.Option id=\"amt-off-product\" textValue=\"Amount off product\">\n              Discount the target item(s) by an absolute amount.\n              <Text slot=\"description\">Discount type: absolute</Text>\n            </Select.Option>\n          </Select.OptionGroup>\n          <Select.OptionGroup label=\"Cart discounts with line items\">\n            <Select.Option id=\"pct-off-cart\" textValue=\"Percentage off cart\">\n              Discount the target item(s) relative to its price.\n              <Text slot=\"description\">Discount type: relative</Text>\n            </Select.Option>\n            <Select.Option id=\"amt-off-cart\" textValue=\"Amount off cart\">\n              Discount the target item(s) by an absolute amount.\n              <Text slot=\"description\">Discount type: absolute</Text>\n            </Select.Option>\n            <Select.Option id=\"buy-x-get-x\" textValue=\"Buy x get x\">\n              A relative (% off) discount is applied when the shopper buys a\n              specified quantity of an item.\n              <Text slot=\"description\">Discount type: multi-buy</Text>\n            </Select.Option>\n            <Select.Option id=\"fixed-price\" textValue=\"Fixed price\">\n              Discount the target item(s) by setting a fixed price.\n              <Text slot=\"description\">Discount type: fixed-price</Text>\n            </Select.Option>\n            <Select.Option\n              id=\"discounted-shipping\"\n              textValue=\"Discounted shipping\"\n            >\n              Discount the cart's shipping cost for the customer.\n              <Text slot=\"description\">Discount type: shipping</Text>\n            </Select.Option>\n            <Select.Option id=\"gift\" textValue=\"Gift with purchase\">\n              Discount adds a free line item(s) to the cart when the specified\n              conditions are met.\n              <Text slot=\"description\">Discount type: gift line item</Text>\n            </Select.Option>\n            <Select.Option\n              id=\"amt-total-spend\"\n              textValue=\"Amount off total spend\"\n            >\n              Discount an absolute amount based on cart total.\n              <Text slot=\"description\">Discount type: absolute</Text>\n            </Select.Option>\n            <Select.Option\n              id=\"pct-total-spend\"\n              textValue=\"Percentage off total spend\"\n            >\n              Discount an amount relative to the cart total.\n              <Text slot=\"description\">Discount type: relative</Text>\n            </Select.Option>\n          </Select.OptionGroup>\n          <Select.OptionGroup label=\"Cart discounts with custom line items\">\n            <Select.Option id=\"custom-pct\" textValue=\"Custom percentage off\">\n              Discount the target custom line item(s) relative to its price.\n              <Text slot=\"description\">Discount type: relative</Text>\n            </Select.Option>\n            <Select.Option id=\"custom-amt\" textValue=\"Custom amount off\">\n              Discount the target custom line item(s) by an absolute amount.\n              <Text slot=\"description\">Discount type: absolute</Text>\n            </Select.Option>\n            <Select.Option id=\"custom-buy-x\" textValue=\"Custom buy x get x\">\n              A relative (% off) discount is applied when the shopper buys a\n              specified quantity of an item defined as a custom line item.\n              <Text slot=\"description\">Discount type: multibuy</Text>\n            </Select.Option>\n          </Select.OptionGroup>\n        </Select.Options>\n      </Select.Root>\n    </FormField.Input>\n  </FormField.Root>\n);\n```\n\n### Organize dropdown content when possible\n\nUse grouping structures if all items in a list can be grouped for a better user\nexperience. By default, organize by alphabetical order.\n\n> [!TIP]\\\n> **Do**\n>\n> - Use labels within popover/drop downs to organize content.\n> - Allow if possible for the user to search for items with type ahead fuzzy\n>   search.\n> - If actions lists become bulky and hard to scan, consider another experience\n>   for the user.\n\n```jsx live\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Actions</FormField.Label>\n    <FormField.Input>\n      <Select.Root aria-label=\"Actions\">\n        <Select.Options placeholder=\"Select...\">\n          <Select.OptionGroup label=\"Common actions\">\n            <Select.Option id=\"publish\">Publish</Select.Option>\n            <Select.Option id=\"unpublish\">Unpublish</Select.Option>\n            <Select.Option id=\"delete\">Delete</Select.Option>\n          </Select.OptionGroup>\n          <Select.OptionGroup label=\"Import\">\n            <Select.Option id=\"import-csv\">Import via CSV</Select.Option>\n            <Select.Option id=\"bulk-unpublish-csv\">\n              Bulk unpublish via CSV\n            </Select.Option>\n            <Select.Option id=\"bulk-delete-csv\">\n              Bulk delete via CSV\n            </Select.Option>\n            <Select.Option id=\"import-inventories\">\n              Import inventories\n            </Select.Option>\n          </Select.OptionGroup>\n          <Select.OptionGroup label=\"Export\">\n            <Select.Option id=\"export-products\">Export products</Select.Option>\n            <Select.Option id=\"export-inventories\">\n              Export Inventories\n            </Select.Option>\n          </Select.OptionGroup>\n        </Select.Options>\n      </Select.Root>\n    </FormField.Input>\n  </FormField.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't bury frequently used actions within a dropdown or menu; instead,\n>   prioritize them at the top and group related actions together to facilitate\n>   quick user selection.\n\n```jsx live\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Actions</FormField.Label>\n    <FormField.Input>\n      <Select.Root defaultSelectedKey=\"bulk-unpublish-csv\" aria-label=\"Actions\">\n        <Select.Options placeholder=\"Select...\">\n          <Select.Option id=\"bulk-delete-csv\">\n            Bulk delete via CSV\n          </Select.Option>\n          <Select.Option id=\"bulk-unpublish-csv\">\n            Bulk unpublish via CSV\n          </Select.Option>\n          <Select.Option id=\"delete\">Delete</Select.Option>\n          <Select.Option id=\"export-inventories\">\n            Export Inventories\n          </Select.Option>\n          <Select.Option id=\"export-products\">Export products</Select.Option>\n          <Select.Option id=\"import-inventories\">\n            Import inventories\n          </Select.Option>\n          <Select.Option id=\"import-csv\">Import via CSV</Select.Option>\n          <Select.Option id=\"publish\">Publish</Select.Option>\n          <Select.Option id=\"unpublish\">Unpublish</Select.Option>\n        </Select.Options>\n      </Select.Root>\n    </FormField.Input>\n  </FormField.Root>\n);\n```\n\n### Help and error text inclusion\n\nUse helper text when needed, and replace helper text with error text if\ntriggered.\n\n> [!TIP]\\\n> **Do**\n>\n> - Use helper text to give more context to the select input when needed. Omit\n>   if self explanatory.\n> - Error and helper text should be short and easily understood.\n\n```jsx live\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Store restriction</FormField.Label>\n    <FormField.Input>\n      <Select.Root aria-label=\"Store restriction\">\n        <Select.Options placeholder=\"Select...\">\n          <Select.Option id=\"store-1\">Europe store</Select.Option>\n          <Select.Option id=\"store-2\">North America store</Select.Option>\n          <Select.Option id=\"store-3\">Asia Pacific store</Select.Option>\n        </Select.Options>\n      </Select.Root>\n    </FormField.Input>\n    <FormField.Description>\n      Restrict this account to only make future purchases to these stores.\n    </FormField.Description>\n  </FormField.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't show both helper text and information text simultaneously.\n\n```jsx live\nconst App = () => (\n  <FormField.Root isInvalid>\n    <FormField.Label>Store restriction</FormField.Label>\n    <FormField.Input>\n      <Select.Root\n        isClearable\n        defaultSelectedKey=\"valencia\"\n        aria-label=\"Store restriction\"\n      >\n        <Select.Options placeholder=\"Select...\">\n          <Select.Option id=\"valencia\">Valencia, Spain</Select.Option>\n          <Select.Option id=\"madrid\">Madrid, Spain</Select.Option>\n          <Select.Option id=\"barcelona\">Barcelona, Spain</Select.Option>\n        </Select.Options>\n      </Select.Root>\n    </FormField.Input>\n    <FormField.Description>\n      Restrict this account to only make future purchases to these stores.\n    </FormField.Description>\n    <FormField.Error>Cannot perform this action</FormField.Error>\n  </FormField.Root>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practice",
+          "href": "#best-practice",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use a solid vs. ghost styled select input",
+          "href": "#when-to-use-a-solid-vs-ghost-styled-select-input",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Solid-styled widths",
+          "href": "#solid-styled-widths",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Ghost-styled widths",
+          "href": "#ghost-styled-widths",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labels and preselection",
+          "href": "#labels-and-preselection",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labels and layout exceptions",
+          "href": "#labels-and-layout-exceptions",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keep menu items concise",
+          "href": "#keep-menu-items-concise",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Organize dropdown content when possible",
+          "href": "#organize-dropdown-content-when-possible",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Help and error text inclusion",
+          "href": "#help-and-error-text-inclusion",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            9
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}