@commercetools/nimbus-mcp 0.1.0 → 2.10.0

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

@@ -0,0 +1,583 @@
+{
+  "meta": {
+    "id": "Components-RadioInput",
+    "title": "Radio input",
+    "exportName": "RadioInput",
+    "description": "A set of closely related, mutually exclusive or complementary actions that are important enough to be displayed directly in the interface for quick access.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/radio-input/radio-input.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Radio input"
+    ],
+    "route": "components/inputs/radio-input",
+    "tags": [
+      "component",
+      "radio",
+      "input",
+      "selection",
+      "option"
+    ],
+    "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": "Visual options",
+        "href": "#visual-options",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Default",
+        "href": "#default",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Active",
+        "href": "#active",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Disabled",
+        "href": "#disabled",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Invalid toned",
+        "href": "#invalid-toned",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          4
+        ],
+        "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\nRadio inputs ensure users can easily select one option from a small, visible set\nof mutually exclusive choices with clear labels and visual feedback.\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#### Default\n\n```jsx live\nconst App = () => (\n  <RadioInput.Root orientation=\"horizontal\" name=\"default-example\">\n    <RadioInput.Option value=\"option1\">Select me</RadioInput.Option>\n    <RadioInput.Option value=\"option2\">Select me instead</RadioInput.Option>\n  </RadioInput.Root>\n)\n```\n\n#### Active\n\n```jsx live\nconst App = () => (\n  <RadioInput.Root orientation=\"horizontal\" name=\"active-example\" defaultValue=\"option1\">\n    <RadioInput.Option value=\"option1\">Selected option</RadioInput.Option>\n    <RadioInput.Option value=\"option2\">Unselected option</RadioInput.Option>\n  </RadioInput.Root>\n)\n```\n\n#### Disabled\n\n```jsx live\nconst App = () => (\n  <RadioInput.Root orientation=\"horizontal\" name=\"disabled-example\" isDisabled>\n    <RadioInput.Option value=\"option1\">Disabled option</RadioInput.Option>\n    <RadioInput.Option value=\"option2\">Also disabled</RadioInput.Option>\n  </RadioInput.Root>\n)\n```\n\n#### Invalid toned\n\n```jsx live\nconst App = () => (\n  <RadioInput.Root orientation=\"horizontal\" name=\"invalid-example\" isInvalid>\n    <RadioInput.Option value=\"option1\">Invalid option</RadioInput.Option>\n    <RadioInput.Option value=\"option2\">Another invalid option</RadioInput.Option>\n  </RadioInput.Root>\n)\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nRadio inputs ensure users can easily select one option from a small, visible set\nof mutually exclusive choices with clear labels and visual feedback.\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#### Default\n\n```jsx live\nconst App = () => (\n  <RadioInput.Root orientation=\"horizontal\" name=\"default-example\">\n    <RadioInput.Option value=\"option1\">Select me</RadioInput.Option>\n    <RadioInput.Option value=\"option2\">Select me instead</RadioInput.Option>\n  </RadioInput.Root>\n)\n```\n\n#### Active\n\n```jsx live\nconst App = () => (\n  <RadioInput.Root orientation=\"horizontal\" name=\"active-example\" defaultValue=\"option1\">\n    <RadioInput.Option value=\"option1\">Selected option</RadioInput.Option>\n    <RadioInput.Option value=\"option2\">Unselected option</RadioInput.Option>\n  </RadioInput.Root>\n)\n```\n\n#### Disabled\n\n```jsx live\nconst App = () => (\n  <RadioInput.Root orientation=\"horizontal\" name=\"disabled-example\" isDisabled>\n    <RadioInput.Option value=\"option1\">Disabled option</RadioInput.Option>\n    <RadioInput.Option value=\"option2\">Also disabled</RadioInput.Option>\n  </RadioInput.Root>\n)\n```\n\n#### Invalid toned\n\n```jsx live\nconst App = () => (\n  <RadioInput.Root orientation=\"horizontal\" name=\"invalid-example\" isInvalid>\n    <RadioInput.Option value=\"option1\">Invalid option</RadioInput.Option>\n    <RadioInput.Option value=\"option2\">Another invalid option</RadioInput.Option>\n  </RadioInput.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": "Visual options",
+          "href": "#visual-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Default",
+          "href": "#default",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Active",
+          "href": "#active",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled",
+          "href": "#disabled",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Invalid toned",
+          "href": "#invalid-toned",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            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  <RadioInput.Root\n    orientation=\"horizontal\"\n    name=\"accessibility-example\"\n    id=\"accessibility-example-group\"\n    aria-label=\"Select an option\"\n    isRequired={true}\n  >\n    <RadioInput.Option\n      value=\"option1\"\n      id=\"option1\"\n      aria-label=\"Select me option\"\n    >\n      Select me\n    </RadioInput.Option>\n    <RadioInput.Option\n      value=\"option2\"\n      id=\"option2\"\n      aria-label=\"Select me instead option\"\n    >\n      Select me instead\n    </RadioInput.Option>\n  </RadioInput.Root>\n)\n```\n\n### Accessibility standards\n\n- Always provide a visible label for the radio input.\n- Clearly associate the label with the input using the `for` attribute on the\n  `<label>` and a matching `id` on the `<input type=\"radio\">`.\n- Group related radio inputs within a `<fieldset>` with a `<legend>` to provide\n  a clear group label for screen readers.\n- Ensure sufficient color contrast for all elements (text, borders, icons, focus\n  indicators).\n- Clearly indicate the focused state.\n- Support keyboard navigation:\n- Use Tab to navigate into and out of the radio group.\n- Use arrow keys (left/right or up/down) to navigate between radio inputs within\n  the group.\n- Selected state should be clearly indicated.\n- Communicate errors clearly, using both visual cues (e.g., color) and\n  descriptive error messages.\n\n## Resources\n\n- [Adobe Spectrum Design System](https://spectrum.adobe.com/)\n- [React Spectrum](https://react-spectrum.adobe.com/)\n- [W3C ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/)\n  (Search for \"Radio Button\" pattern)\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": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { RadioInput, type RadioInputRootProps, type RadioInputOptionProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe RadioInput is a compound component that requires both `RadioInput.Root` and `RadioInput.Option` sub-components. The simplest implementation uses uncontrolled mode:\n\n```jsx live-dev\nconst App = () => (\n  <RadioInput.Root name=\"choice\">\n    <RadioInput.Option value=\"yes\">Yes</RadioInput.Option>\n    <RadioInput.Option value=\"no\">No</RadioInput.Option>\n  </RadioInput.Root>\n)\n```\n\n## Usage examples\n\n### Orientation options\n\nThe `orientation` prop controls the layout direction of radio options. The default is `vertical`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <RadioInput.Root name=\"vertical-example\" orientation=\"vertical\">\n      <RadioInput.Option value=\"option1\">First Option</RadioInput.Option>\n      <RadioInput.Option value=\"option2\">Second Option</RadioInput.Option>\n      <RadioInput.Option value=\"option3\">Third Option</RadioInput.Option>\n    </RadioInput.Root>\n    <hr />\n    <RadioInput.Root name=\"horizontal-example\" orientation=\"horizontal\">\n      <RadioInput.Option value=\"option1\">First Option</RadioInput.Option>\n      <RadioInput.Option value=\"option2\">Second Option</RadioInput.Option>\n      <RadioInput.Option value=\"option3\">Third Option</RadioInput.Option>\n    </RadioInput.Root>\n  </Stack>\n)\n```\n\n**Behavioral differences:**\n- `orientation=\"vertical\"`: Options are stacked vertically with consistent spacing (default)\n- `orientation=\"horizontal\"`: Options are arranged in a row, useful for compact layouts with few options\n\n### Uncontrolled mode\n\nFor simpler use cases, use uncontrolled mode with `defaultValue` and `onChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedValue, setSelectedValue] = useState<string | undefined>(undefined);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <RadioInput.Root\n        name=\"uncontrolled-example\"\n        defaultValue=\"option2\"\n        onChange={(value) => {\n          setSelectedValue(value);\n        }}\n      >\n        <RadioInput.Option value=\"option1\">First Choice</RadioInput.Option>\n        <RadioInput.Option value=\"option2\">Second Choice</RadioInput.Option>\n        <RadioInput.Option value=\"option3\">Third Choice</RadioInput.Option>\n      </RadioInput.Root>\n      <Text fontSize=\"sm\">\n        Selected: {selectedValue || 'None'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\nUse uncontrolled mode when you need to capture the selected value without managing state yourself.\n\n### Controlled mode\n\nFor scenarios requiring programmatic control or coordination with other components, use controlled mode:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<RadioInputRootProps[\"value\"]>(\"option1\");\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <RadioInput.Root\n        name=\"controlled-example\"\n        value={value}\n        onChange={setValue}\n      >\n        <RadioInput.Option value=\"option1\">First Choice</RadioInput.Option>\n        <RadioInput.Option value=\"option2\">Second Choice</RadioInput.Option>\n        <RadioInput.Option value=\"option3\">Third Choice</RadioInput.Option>\n      </RadioInput.Root>\n      <Text fontSize=\"sm\">\n        Selected: {value || 'None'}\n      </Text>\n      <Button size=\"xs\" onPress={() => setValue(\"option2\")}>\n        Select Second Option\n      </Button>\n    </Stack>\n  );\n}\n```\n\nUse controlled mode when you need to:\n- Synchronize the value with external state\n- Validate or transform selections\n- Clear or programmatically set the value\n- Coordinate with other form fields\n\n### Disabled state\n\nUse the `isDisabled` prop to disable the entire radio group, or apply it to individual options:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <RadioInput.Root name=\"disabled-example\" isDisabled>\n      <RadioInput.Option value=\"option1\">Disabled Option 1</RadioInput.Option>\n      <RadioInput.Option value=\"option2\">Disabled Option 2</RadioInput.Option>\n    </RadioInput.Root>\n    \n    <RadioInput.Root name=\"disabled-selected-example\" isDisabled defaultValue=\"option1\">\n      <RadioInput.Option value=\"option1\">Selected but Disabled</RadioInput.Option>\n      <RadioInput.Option value=\"option2\">Also Disabled</RadioInput.Option>\n    </RadioInput.Root>\n    \n    <hr />\n    \n    <RadioInput.Root name=\"partially-disabled-example\" defaultValue=\"option1\">\n      <RadioInput.Option value=\"option1\">Available Option</RadioInput.Option>\n      <RadioInput.Option value=\"option2\" isDisabled>Disabled Option</RadioInput.Option>\n      <RadioInput.Option value=\"option3\">Another Available Option</RadioInput.Option>\n    </RadioInput.Root>\n  </Stack>\n)\n```\n\n### Invalid state\n\nUse the `isInvalid` prop to indicate validation errors:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <RadioInput.Root name=\"invalid-example\" isInvalid>\n      <RadioInput.Option value=\"option1\">Invalid Option 1</RadioInput.Option>\n      <RadioInput.Option value=\"option2\">Invalid Option 2</RadioInput.Option>\n    </RadioInput.Root>\n    \n    <RadioInput.Root name=\"invalid-selected-example\" isInvalid defaultValue=\"option1\">\n      <RadioInput.Option value=\"option1\">Selected Invalid Option</RadioInput.Option>\n      <RadioInput.Option value=\"option2\">Another Invalid Option</RadioInput.Option>\n    </RadioInput.Root>\n  </Stack>\n)\n```\n\n### With FormField\n\nRadioInput integrates seamlessly with the FormField pattern for consistent form layouts:\n\n```jsx live-dev\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Select your preference:</FormField.Label>\n    <FormField.Input mt=\"300\">\n      <RadioInput.Root name=\"formfield-example\" aria-label=\"Preference selection\">\n        <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n        <RadioInput.Option value=\"option2\">Option 2</RadioInput.Option>\n        <RadioInput.Option value=\"option3\">Option 3</RadioInput.Option>\n      </RadioInput.Root>\n    </FormField.Input>\n    <FormField.Description mt=\"300\">\n      Choose one option from the list above.\n    </FormField.Description>\n  </FormField.Root>\n)\n```\n\n### Required state\n\nUse the `isRequired` prop to indicate that a selection is mandatory. When used with `FormField`, it displays a visual indicator (asterisk) in the label and sets `aria-required=\"true\"` for accessibility:\n\n```jsx live-dev\nconst App = () => (\n    <FormField.Root isRequired>\n      <FormField.Label>Select your preference</FormField.Label>\n      <FormField.Input mt=\"300\">\n        <RadioInput.Root name=\"required-example\" isRequired aria-label=\"Preference selection\">\n          <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n          <RadioInput.Option value=\"option2\">Option 2</RadioInput.Option>\n          <RadioInput.Option value=\"option3\">Option 3</RadioInput.Option>\n        </RadioInput.Root>\n      </FormField.Input>\n      <FormField.Description mt=\"300\">\n        You must select one of the options above.\n      </FormField.Description>\n    </FormField.Root>\n)\n```\n\n**Note:** The `isRequired` prop sets the `aria-required` attribute on the radio group for screen readers. For visual indication, use it within a `FormField.Root` that also has `isRequired`, which will display an asterisk (*) in the label.\n\n## Component requirements\n\n## Accessibility\n\nThe RadioInput handles most accessibility requirements internally via React Aria Components. However, you must always associate an internationalized label with the component. Visual labels are preferable, and can be set by:\n\n- Using the `FormField` pattern component (recommended):\n```tsx\n<FormField.Root>\n  <FormField.Label>\n    {msg.format(labelMessage)}\n  </FormField.Label>\n  <FormField.Input>\n    <RadioInput.Root name=\"example\" aria-label={msg.format(labelMessage)}>\n      <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n    </RadioInput.Root>\n  </FormField.Input>\n</FormField.Root>\n```\n\n- Associating a `<label>` element with the `RadioInput.Root` using `aria-labelledby`:\n```tsx\n<label id=\"radio-label-id\">\n  {msg.format(labelMessage)}\n</label>\n<RadioInput.Root name=\"example\" aria-labelledby=\"radio-label-id\">\n  <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n</RadioInput.Root>\n```\n\nIf your design requires that the label should not be visible, the label should be set using the `aria-label` prop:\n```tsx\n<RadioInput.Root \n  name=\"example\" \n  aria-label={msg.format(labelMessage)}\n>\n  <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n</RadioInput.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-radio-input\";\n\nexport const Example = () => (\n  <RadioInput.Root id={PERSISTENT_ID} name=\"example\">\n    <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n  </RadioInput.Root>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab` / `Shift+Tab`: Navigate into and out of the radio group\n- `Arrow keys` (Up/Down or Left/Right): Navigate between radio options within the group\n- `Space`: Select the focused radio option\n- `Enter`: Does not trigger selection (use Space instead)\n\n## API reference\n\n<PropsTable id=\"RadioInput\" />\n\n## Common patterns\n\n### Form validation\n\nValidate radio input selection and display error messages:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string | undefined>(undefined);\n  const [error, setError] = useState<string | undefined>(undefined);\n  const [touched, setTouched] = useState(false);\n\n  const handleChange = (newValue: string) => {\n    setValue(newValue);\n    setError(undefined);\n  };\n\n  const handleBlur = () => {\n    setTouched(true);\n    if (!value) {\n      setError('Please select an option');\n    }\n  };\n\n  const handleSubmit = () => {\n    if (!value) {\n      setError('Please select an option');\n      setTouched(true);\n    }\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <FormField.Root isInvalid={!!(error && touched)}>\n        <FormField.Label>Select an option</FormField.Label>\n        <FormField.Input>\n          <RadioInput.Root\n            name=\"validation-example\"\n            value={value}\n            onChange={handleChange}\n            onBlur={handleBlur}\n            isInvalid={!!(error && touched)}\n            aria-label=\"Option selection\"\n          >\n            <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n            <RadioInput.Option value=\"option2\">Option 2</RadioInput.Option>\n            <RadioInput.Option value=\"option3\">Option 3</RadioInput.Option>\n          </RadioInput.Root>\n        </FormField.Input>\n        {touched && error && (\n          <FormField.Error>{error}</FormField.Error>\n        )}\n      </FormField.Root>\n      <Button onPress={handleSubmit}>Submit</Button>\n      {value && !error && (\n        <Text fontSize=\"sm\" color=\"positive.9\">\n          Successfully selected: {value}\n        </Text>\n      )}\n    </Stack>\n  );\n}\n```\n\n### Conditional rendering based on selection\n\nShow or hide content based on the selected radio option:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState<string | undefined>(undefined);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <RadioInput.Root\n        name=\"conditional-example\"\n        value={value}\n        onChange={setValue}\n      >\n        <RadioInput.Option value=\"yes\">Yes, I agree</RadioInput.Option>\n        <RadioInput.Option value=\"no\">No, I disagree</RadioInput.Option>\n      </RadioInput.Root>\n      \n      {value === 'yes' && (\n        <Text fontSize=\"sm\" color=\"positive.9\">\n          Thank you for agreeing!\n        </Text>\n      )}\n      \n      {value === 'no' && (\n        <Text fontSize=\"sm\" color=\"critical.9\">\n          Please let us know why you disagree.\n        </Text>\n      )}\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using RadioInput in 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 { RadioInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"RadioInput - Basic rendering\", () => {\n  it(\"renders radio group with options\", () => {\n    render(\n      <NimbusProvider>\n        <RadioInput.Root name=\"test-radio\" aria-label=\"Test selection\">\n          <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n          <RadioInput.Option value=\"option2\">Option 2</RadioInput.Option>\n        </RadioInput.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"radiogroup\")).toBeInTheDocument();\n    expect(\n      screen.getByRole(\"radio\", { name: /option 1/i })\n    ).toBeInTheDocument();\n    expect(\n      screen.getByRole(\"radio\", { name: /option 2/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders with default value selected\", () => {\n    render(\n      <NimbusProvider>\n        <RadioInput.Root\n          name=\"test-radio\"\n          defaultValue=\"option1\"\n          aria-label=\"Test selection\"\n        >\n          <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n          <RadioInput.Option value=\"option2\">Option 2</RadioInput.Option>\n        </RadioInput.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"radio\", { name: /option 1/i })).toBeChecked();\n    expect(screen.getByRole(\"radio\", { name: /option 2/i })).not.toBeChecked();\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 { RadioInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"RadioInput - Interactions\", () => {\n  it(\"calls onChange when option is selected\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <RadioInput.Root\n          name=\"test-radio\"\n          onChange={handleChange}\n          aria-label=\"Test selection\"\n        >\n          <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n          <RadioInput.Option value=\"option2\">Option 2</RadioInput.Option>\n        </RadioInput.Root>\n      </NimbusProvider>\n    );\n\n    const option2 = screen.getByRole(\"radio\", { name: /option 2/i });\n    await user.click(option2);\n\n    expect(handleChange).toHaveBeenCalledWith(\"option2\");\n  });\n\n  it(\"allows only one option to be selected at a time\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <RadioInput.Root\n          name=\"test-radio\"\n          defaultValue=\"option1\"\n          aria-label=\"Test selection\"\n        >\n          <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n          <RadioInput.Option value=\"option2\">Option 2</RadioInput.Option>\n          <RadioInput.Option value=\"option3\">Option 3</RadioInput.Option>\n        </RadioInput.Root>\n      </NimbusProvider>\n    );\n\n    const option1 = screen.getByRole(\"radio\", { name: /option 1/i });\n    const option2 = screen.getByRole(\"radio\", { name: /option 2/i });\n    const option3 = screen.getByRole(\"radio\", { name: /option 3/i });\n\n    expect(option1).toBeChecked();\n    expect(option2).not.toBeChecked();\n    expect(option3).not.toBeChecked();\n\n    await user.click(option2);\n\n    await waitFor(() => {\n      expect(option1).not.toBeChecked();\n      expect(option2).toBeChecked();\n      expect(option3).not.toBeChecked();\n    });\n  });\n\n  it(\"supports keyboard navigation with arrow keys\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <RadioInput.Root name=\"test-radio\" aria-label=\"Test selection\">\n          <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n          <RadioInput.Option value=\"option2\">Option 2</RadioInput.Option>\n        </RadioInput.Root>\n      </NimbusProvider>\n    );\n\n    const option1 = screen.getByRole(\"radio\", { name: /option 1/i });\n    const option2 = screen.getByRole(\"radio\", { name: /option 2/i });\n\n    // Tab to focus the first option\n    await user.tab();\n    expect(option1).toHaveFocus();\n\n    // Use arrow key to navigate to next option\n    await user.keyboard(\"{ArrowDown}\");\n    expect(option2).toHaveFocus();\n\n    // Select with Space\n    await user.keyboard(\" \");\n    expect(option2).toBeChecked();\n  });\n});\n```\n\n### Testing Disabled State\n\nTest disabled state 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 { RadioInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"RadioInput - Disabled state\", () => {\n  it(\"prevents interaction when disabled\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <RadioInput.Root\n          name=\"test-radio\"\n          isDisabled\n          onChange={handleChange}\n          aria-label=\"Test selection\"\n        >\n          <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n          <RadioInput.Option value=\"option2\">Option 2</RadioInput.Option>\n        </RadioInput.Root>\n      </NimbusProvider>\n    );\n\n    const radioGroup = screen.getByRole(\"radiogroup\");\n    expect(radioGroup).toHaveAttribute(\"aria-disabled\", \"true\");\n\n    const option1 = screen.getByRole(\"radio\", { name: /option 1/i });\n    await user.click(option1);\n\n    expect(handleChange).not.toHaveBeenCalled();\n  });\n\n  it(\"does not receive focus when disabled\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <RadioInput.Root\n          name=\"test-radio\"\n          isDisabled\n          aria-label=\"Test selection\"\n        >\n          <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n        </RadioInput.Root>\n      </NimbusProvider>\n    );\n\n    await user.tab();\n    const option1 = screen.getByRole(\"radio\", { name: /option 1/i });\n    expect(option1).not.toHaveFocus();\n  });\n});\n```\n\n### Testing Invalid State\n\nTest invalid state 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 { RadioInput, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"RadioInput - Invalid state\", () => {\n  it(\"applies invalid styling and attributes\", () => {\n    render(\n      <NimbusProvider>\n        <RadioInput.Root\n          name=\"test-radio\"\n          isInvalid\n          aria-label=\"Test selection\"\n        >\n          <RadioInput.Option value=\"option1\">Option 1</RadioInput.Option>\n          <RadioInput.Option value=\"option2\">Option 2</RadioInput.Option>\n        </RadioInput.Root>\n      </NimbusProvider>\n    );\n\n    const radioGroup = screen.getByRole(\"radiogroup\");\n    expect(radioGroup).toHaveAttribute(\"aria-invalid\", \"true\");\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-radioinput--docs)\n- [React Aria RadioGroup](https://react-spectrum.adobe.com/react-aria/RadioGroup.html)\n- [ARIA Radio Group Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)\n\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": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Orientation options",
+          "href": "#orientation-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Invalid state",
+          "href": "#invalid-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With FormField",
+          "href": "#with-formfield",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Required state",
+          "href": "#required-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form validation",
+          "href": "#form-validation",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Conditional rendering based on selection",
+          "href": "#conditional-rendering-based-on-selection",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Disabled State",
+          "href": "#testing-disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Invalid State",
+          "href": "#testing-invalid-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nRadio input guidelines focus on providing a clear, accessible, and mutually\nexclusive set of options, ensuring users can easily understand the available\nchoices and select only one, with clear visual indication of the selected state\nand proper labeling for accessibility.\n\n### Best practices\n\n- **Clear and concise labels:** Ensure each radio input has a descriptive label\n  placed consistently (usually to the right).\n- **Logical grouping:** Enclose related radio inputs within a `<fieldset>`\n  element and provide a clear `<legend>` to describe the group's purpose.\n- **Visual distinction:** Clearly indicate the selected state (e.g., filled\n  circle) and the non-selected state (e.g., empty circle).\n- **Sufficient spacing:** Provide enough spacing between radio inputs and their\n  labels for easy selection.\n- **Keyboard accessibility:** Ensure users can navigate through radio inputs\n  using the Tab key and select an option using the arrow keys and Spacebar.\n- **Clear default selection (use sparingly):** Only pre-select a radio input if\n  there's a genuinely logical default option. Avoid forcing a choice\n  unnecessarily.\n- **Avoid too many options:** If you have a long list of mutually exclusive\n  choices, consider a dropdown select instead.\n\n### Usage\n\nRadio inputs are used when you need users to pick a single choice from a limited\nnumber of options, presenting all possibilities upfront for easy comparison and\nselection of just one.\n\n> [!TIP]\\\n> When to use\n\n- **Single selection required:** When users must choose only one option from a\n  predefined list.\n- **Limited number of options:** When the number of choices is relatively small\n  (typically 2-5) and all options can be displayed clearly.\n- **Equal importance of options:** When all choices are presented as equally\n  valid and the user needs to make a deliberate selection.\n- **Visual comparison is beneficial:** When seeing all available options at once\n  helps users understand and compare them before choosing.\n- **Clear and mutually exclusive choices:** When the options are distinct and\n  there's no possibility of selecting more than one.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Multiple selections allowed:** If users can select more than one option, use\n  checkboxes instead.\n- **Large number of options:** For long lists of choices, a dropdown select is\n  more space-efficient.\n- **Obscure or infrequently used options:** If many options are rarely chosen, a\n  dropdown can hide them until needed, reducing visual clutter.\n- **Saving screen space is critical:** Radio inputs display all options, which\n  can take up significant space, especially on smaller screens.\n- **Default selection is strongly preferred:** If one option is almost always\n  the correct choice, a pre-selected checkbox might be more efficient (with\n  clear indication that it can be unchecked).\n- **Complex or dynamic options:** When the available choices change frequently\n  or depend on other user inputs, a dynamic select or autocomplete field might\n  be better.\n\n### Limited options\n\nRadio inputs work best when there are a limited number of options for a user.\n\n> [!TIP]\\\n> **Do**\n>\n> - Use when there are a few options available for the user.\n\n```jsx live\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Shipping priority</FormField.Label>\n    <FormField.Input mt=\"200\">\n      <RadioInput.Root orientation=\"vertical\" name=\"shipping-speed\">\n        <RadioInput.Option value=\"standard\">Standard</RadioInput.Option>\n        <RadioInput.Option value=\"express\">Express</RadioInput.Option>\n        <RadioInput.Option value=\"priority\">Priority</RadioInput.Option>\n        <RadioInput.Option value=\"same-day\">Same-day</RadioInput.Option>\n        <RadioInput.Option value=\"instore-pickup\">\n          In-store pick up\n        </RadioInput.Option>\n      </RadioInput.Root>\n    </FormField.Input>\n  </FormField.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not use radio inputs when there are an excessive amount of options. Radio\n>   input options on default will show every option to a user so it can be\n>   overwhelming for a user when there is a lot of information to digest in a\n>   small area. Instead, use a dropdown selector to simplify the UI and make it\n>   easier to search quickly to find the right option.\n\n```jsx live\nconst App = () => (\n  <FormField.Root>\n    <FormField.Label>Shipping priority</FormField.Label>\n    <FormField.Input mt=\"200\">\n      <RadioInput.Root name=\"shipping-dont\">\n        <Grid\n          templateColumns=\"repeat(3, auto)\"\n          gap=\"400\"\n          rowGap=\"400\"\n          justifyItems=\"start\"\n        >\n          <RadioInput.Option value=\"standard\">Standard</RadioInput.Option>\n          <RadioInput.Option value=\"next-business\">\n            Next business day\n          </RadioInput.Option>\n          <RadioInput.Option value=\"local-pickup\">\n            Local pickup\n          </RadioInput.Option>\n          <RadioInput.Option value=\"express\">Express</RadioInput.Option>\n          <RadioInput.Option value=\"express-2\">Express</RadioInput.Option>\n          <RadioInput.Option value=\"rural\">\n            Rural/remote area shipping\n          </RadioInput.Option>\n          <RadioInput.Option value=\"priority\">Priority</RadioInput.Option>\n          <RadioInput.Option value=\"two-day\">\n            Two-day shipping\n          </RadioInput.Option>\n          <RadioInput.Option value=\"temp-controlled\">\n            Temperature-controlled shipping\n          </RadioInput.Option>\n          <RadioInput.Option value=\"sameday\">Same-day</RadioInput.Option>\n          <RadioInput.Option value=\"freight\">\n            Freight shipping\n          </RadioInput.Option>\n          <RadioInput.Option value=\"white-glove\">\n            White glove delivery\n          </RadioInput.Option>\n          <RadioInput.Option value=\"pickup\">In-store pick up</RadioInput.Option>\n          <RadioInput.Option value=\"intl-economy\">\n            International economy\n          </RadioInput.Option>\n          <RadioInput.Option value=\"carbon-neutral\">\n            Carbon-neutral shipping\n          </RadioInput.Option>\n        </Grid>\n      </RadioInput.Root>\n    </FormField.Input>\n  </FormField.Root>\n);\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": "Limited options",
+          "href": "#limited-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}