@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/components-inputs-switch.json

@@ -0,0 +1,720 @@
+{
+  "meta": {
+    "id": "Components-Switch",
+    "title": "Switch",
+    "exportName": "Switch",
+    "description": "A clear, visual toggle, allowing users to activate or deactivate a setting quickly.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/switch/switch.mdx",
+    "menu": [
+      "Components",
+      "Inputs",
+      "Switch"
+    ],
+    "route": "components/inputs/switch",
+    "tags": [
+      "component",
+      "input",
+      "toggle"
+    ],
+    "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": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Medium (md)",
+        "href": "#medium-md",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Small (sm)",
+        "href": "#small-sm",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Labels",
+        "href": "#labels",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "With label",
+        "href": "#with-label",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Without visible label",
+        "href": "#without-visible-label",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?m=auto&node-id=346-2572&t=0Gug4G6TEF60mpzZ-1",
+    "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\nThis switch is an interactive element that provides instant visual feedback\nallowing users to toggle binary options.\n\n### Resources\n\n- [Figma](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?m=auto&node-id=346-2572&t=0Gug4G6TEF60mpzZ-1)\n\n## Variables\n\nGet familiar with the features.\n\n### Size\n\n#### Medium (md)\n\n```jsx live\nconst App = () => <Switch size=\"md\">Label</Switch>;\n```\n\n#### Small (sm)\n\n```jsx live\nconst App = () => <Switch size=\"sm\">Label</Switch>;\n```\n\n### Labels\n\n#### With label\n\nIt is always good practice to have a label paired with a switch so a user knows\nwhat is being toggled. The label responds to both switch sizes to match use\ncases.\n\n```jsx live\nconst App = () => <Switch>Label</Switch>;\n```\n\n#### Without visible label\n\nYou can use switch without visible label if the use is clear enough to not need\na label for the user.\n\n```jsx live\nconst App = () => <Switch aria-label=\"I still need an aria-label for a11y purposes\" />;\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThis switch is an interactive element that provides instant visual feedback\nallowing users to toggle binary options.\n\n### Resources\n\n- [Figma](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?m=auto&node-id=346-2572&t=0Gug4G6TEF60mpzZ-1)\n\n## Variables\n\nGet familiar with the features.\n\n### Size\n\n#### Medium (md)\n\n```jsx live\nconst App = () => <Switch size=\"md\">Label</Switch>;\n```\n\n#### Small (sm)\n\n```jsx live\nconst App = () => <Switch size=\"sm\">Label</Switch>;\n```\n\n### Labels\n\n#### With label\n\nIt is always good practice to have a label paired with a switch so a user knows\nwhat is being toggled. The label responds to both switch sizes to match use\ncases.\n\n```jsx live\nconst App = () => <Switch>Label</Switch>;\n```\n\n#### Without visible label\n\nYou can use switch without visible label if the use is clear enough to not need\na label for the user.\n\n```jsx live\nconst App = () => <Switch aria-label=\"I still need an aria-label for a11y purposes\" />;\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": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Medium (md)",
+          "href": "#medium-md",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Small (sm)",
+          "href": "#small-sm",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labels",
+          "href": "#labels",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With label",
+          "href": "#with-label",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Without visible label",
+          "href": "#without-visible-label",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => <Switch size=\"md\">Label</Switch>;\n```\n\n### Accessibility standards\n\n- **Info and relationships:** Ensure the switch's state and purpose are\n  programmatically determinable. Use ARIA attributes like `aria-checked` to\n  convey the on/off state to assistive technologies. Associate a clear label\n  with the switch using the `<label>` element or `aria-label`.\n- **Use of color:** Don't rely solely on color to indicate the switch's state.\n  Use other visual cues like position or icons.\n- **Color contrast:** Ensure sufficient color contrast between the switch's\n  elements (background, toggle, label) and surrounding content.\n- **Keyboard accessibility:** Make the switch fully operable via keyboard. Users\n  should be able to focus on the switch using the Tab key and toggle it using\n  the Spacebar or Enter key.\n- **Focus visible:** Provide a clear visual focus indicator when the switch\n  receives keyboard focus.\n- **On focus:** Ensure that focusing on the switch doesn't trigger unexpected\n  changes or actions.\n- **Labels or instructions:** Provide clear and concise labels that accurately\n  describe the switch's function.\n- **Name, role, value:** Use appropriate semantic HTML and ARIA attributes to\n  define the switch's role, name, and value. This ensures compatibility with\n  assistive technologies. `aria-checked` must accurately reflect the on/off\n  state.\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"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Switch, type SwitchProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\n```jsx live-dev\nconst App = () => {\n  return <Switch>Enable notifications</Switch>;\n};\n```\n\n## Usage examples\n\n### Size options\n\nSwitch supports two size variants: `sm` (small) and `md` (medium, default).\n\n#### Small size\n\n```jsx live-dev\nconst App = () => {\n  return <Switch size=\"sm\">Small switch</Switch>;\n};\n```\n\n#### Medium size\n\n```jsx live-dev\nconst App = () => {\n  return <Switch size=\"md\">Medium switch</Switch>;\n};\n```\n\n### With label\n\nIt's best practice to provide a visible label that describes what the switch controls.\n\n```jsx live-dev\nconst App = () => {\n  return (\n    <Stack gap=\"400\">\n      <Switch>Dark mode</Switch>\n      <Switch>Email notifications</Switch>\n      <Switch>Auto-save drafts</Switch>\n    </Stack>\n  );\n};\n```\n\n### Without visible label\n\nWhen the context makes the switch's purpose clear, you can omit the visible label. However, you must still provide an accessible label using `aria-label`.\n\n```jsx live-dev\nconst App = () => {\n  return (\n    <Stack gap=\"400\">\n      <Text>Notifications</Text>\n      <Switch aria-label=\"Enable notifications\" />\n    </Stack>\n  );\n};\n```\n\n### Disabled state\n\nUse `isDisabled` to prevent user interaction with the switch.\n\n```jsx live-dev\nconst App = () => {\n  return (\n    <Stack gap=\"400\">\n      <Switch isDisabled>Disabled switch (off)</Switch>\n      <Switch isDisabled defaultSelected>\n        Disabled switch (on)\n      </Switch>\n    </Stack>\n  );\n};\n```\n\n### Invalid state\n\nUse `isInvalid` to indicate that the switch's current state is not valid, such as when a required setting must be enabled.\n\n```jsx live-dev\nconst App = () => {\n  return (\n    <Stack gap=\"400\">\n      <Switch isInvalid>Accept terms and conditions</Switch>\n      <Text fontSize=\"350\" color=\"danger.11\">\n        You must accept the terms to continue\n      </Text>\n    </Stack>\n  );\n};\n```\n\n### Default selected\n\nUse `defaultSelected` to set the initial state in uncontrolled mode.\n\n```jsx live-dev\nconst App = () => {\n  return (\n    <Stack gap=\"400\">\n      <Switch defaultSelected={false}>Default off</Switch>\n      <Switch defaultSelected={true}>Default on</Switch>\n    </Stack>\n  );\n};\n```\n\n### Uncontrolled mode\n\nIn uncontrolled mode, the Switch manages its own state internally. Use `defaultSelected` to set the initial value and `onChange` to be notified of changes.\n\n```jsx live-dev\nconst App = () => {\n  const [lastChanged, setLastChanged] = React.useState('');\n\n  return (\n    <Stack gap=\"400\">\n      <Switch\n        defaultSelected={false}\n        onChange={(isSelected) => {\n          setLastChanged(`Switch is now ${isSelected ? 'on' : 'off'}`);\n        }}\n      >\n        Enable feature\n      </Switch>\n      {lastChanged && <Text fontSize=\"350\">{lastChanged}</Text>}\n    </Stack>\n  );\n};\n```\n\n### Controlled mode\n\nIn controlled mode, you manage the switch state externally using the `isSelected` prop.\n\n```jsx live-dev\nconst App = () => {\n  const [isEnabled, setIsEnabled] = React.useState<\n    SwitchProps['isSelected']\n  >(false);\n\n  return (\n    <Stack gap=\"400\">\n      <Switch isSelected={isEnabled} onChange={setIsEnabled}>\n        Notifications enabled\n      </Switch>\n      <Text fontSize=\"350\">\n        Current state: <strong>{isEnabled ? 'On' : 'Off'}</strong>\n      </Text>\n      <Button onClick={() => setIsEnabled(!isEnabled)}>\n        Toggle programmatically\n      </Button>\n    </Stack>\n  );\n};\n```\n\n### Read-only state\n\nUse `isReadOnly` to display a switch that cannot be toggled by the user but shows a specific state.\n\n```jsx live-dev\nconst App = () => {\n  return (\n    <Stack gap=\"400\">\n      <Switch isReadOnly isSelected={false}>\n        Read-only off\n      </Switch>\n      <Switch isReadOnly isSelected={true}>\n        Read-only on\n      </Switch>\n    </Stack>\n  );\n};\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Switch component follows the [WAI-ARIA Switch pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/) and meets accessibility standards:\n\n#### Role\n\n- The switch uses a checkbox input with `type=\"checkbox\"` and `role=\"switch\"` semantics\n- The component properly communicates its state through ARIA attributes\n\n#### Labeling\n\n**With visible label:**\n```tsx\n<Switch>Enable dark mode</Switch>\n```\n\n**Without visible label (using aria-label):**\n```tsx\n<Switch aria-label=\"Enable dark mode\" />\n```\n\n**With external label (using aria-labelledby):**\n```tsx\n<>\n  <span id=\"dark-mode-label\">Enable dark mode</span>\n  <Switch aria-labelledby=\"dark-mode-label\" />\n</>\n```\n\n#### Keyboard navigation\n\n| Key | Action |\n|-----|--------|\n| <kbd>Tab</kbd> | Moves focus to/from the switch |\n| <kbd>Space</kbd> | Toggles the switch between on and off states |\n\n#### Persistent ID\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\n<Switch id=\"notification-toggle\">Enable notifications</Switch>\n```\n\n## API reference\n\n<PropsTable id=\"Switch\" />\n\n## Common patterns\n\n### Settings toggle\n\nUse switches for user preference settings that can be turned on or off.\n\n```jsx live-dev\nconst App = () => {\n  const [settings, setSettings] = React.useState({\n    emailNotifications: true,\n    pushNotifications: false,\n    weeklyDigest: true,\n  });\n\n  return (\n    <Stack gap=\"400\">\n      <Text fontSize=\"450\" fontWeight=\"medium\">\n        Notification Settings\n      </Text>\n      <Switch\n        isSelected={settings.emailNotifications}\n        onChange={(value) =>\n          setSettings({ ...settings, emailNotifications: value })\n        }\n      >\n        Email notifications\n      </Switch>\n      <Switch\n        isSelected={settings.pushNotifications}\n        onChange={(value) =>\n          setSettings({ ...settings, pushNotifications: value })\n        }\n      >\n        Push notifications\n      </Switch>\n      <Switch\n        isSelected={settings.weeklyDigest}\n        onChange={(value) =>\n          setSettings({ ...settings, weeklyDigest: value })\n        }\n      >\n        Weekly digest emails\n      </Switch>\n    </Stack>\n  );\n};\n```\n\n### Feature enable/disable\n\nUse switches to enable or disable application features.\n\n```jsx live-dev\nconst App = () => {\n  const [darkMode, setDarkMode] = React.useState(false);\n  const [autoSave, setAutoSave] = React.useState(true);\n\n  return (\n    <Stack gap=\"400\">\n      <Text fontSize=\"450\" fontWeight=\"medium\">\n        Editor Settings\n      </Text>\n      <Switch isSelected={darkMode} onChange={setDarkMode}>\n        Dark mode\n      </Switch>\n      <Switch isSelected={autoSave} onChange={setAutoSave}>\n        Auto-save\n      </Switch>\n      {autoSave && (\n        <Text fontSize=\"350\" color=\"neutral.11\">\n          Changes will be saved automatically every 30 seconds\n        </Text>\n      )}\n    </Stack>\n  );\n};\n```\n\n### Conditional content display\n\nShow or hide content based on switch state.\n\n```jsx live-dev\nconst App = () => {\n  const [showAdvanced, setShowAdvanced] = React.useState(false);\n\n  return (\n    <Stack gap=\"400\">\n      <Switch isSelected={showAdvanced} onChange={setShowAdvanced}>\n        Show advanced options\n      </Switch>\n      {showAdvanced && (\n        <Stack gap=\"300\" p=\"400\" bg=\"neutral.3\" borderRadius=\"200\">\n          <Text fontSize=\"400\" fontWeight=\"medium\">\n            Advanced Options\n          </Text>\n          <Text fontSize=\"350\">\n            Additional configuration options appear here\n          </Text>\n        </Stack>\n      )}\n    </Stack>\n  );\n};\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Switch 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 Switch renders with expected elements and attributes\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Switch, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Switch - Basic rendering\", () => {\n  it(\"renders with label\", () => {\n    render(\n      <NimbusProvider>\n        <Switch>Enable notifications</Switch>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Enable notifications\")).toBeInTheDocument();\n    expect(screen.getByRole(\"switch\")).toBeInTheDocument();\n  });\n\n  it(\"renders without visible label using aria-label\", () => {\n    render(\n      <NimbusProvider>\n        <Switch aria-label=\"Toggle feature\" />\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).toHaveAccessibleName(\"Toggle feature\");\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the Switch\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Switch, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Switch - Interactions\", () => {\n  it(\"toggles when clicked\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Switch onChange={handleChange}>Toggle me</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).not.toBeChecked();\n\n    await user.click(switchElement);\n    expect(handleChange).toHaveBeenCalledWith(true);\n  });\n\n  it(\"toggles with keyboard (Space)\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Switch onChange={handleChange}>Keyboard toggle</Switch>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n    await user.keyboard(\" \");\n    expect(handleChange).toHaveBeenCalledWith(true);\n  });\n\n  it(\"maintains state through multiple toggles\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Switch defaultSelected={false}>Multi-toggle</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).not.toBeChecked();\n\n    await user.click(switchElement);\n    expect(switchElement).toBeChecked();\n\n    await user.click(switchElement);\n    expect(switchElement).not.toBeChecked();\n  });\n\n  it(\"can be focused with Tab key\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Switch>Focusable switch</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n\n    await user.tab();\n    expect(switchElement).toHaveFocus();\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled state management\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Switch, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Switch - Controlled mode\", () => {\n  it(\"respects controlled isSelected prop\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Switch isSelected={false}>Controlled switch</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).not.toBeChecked();\n\n    rerender(\n      <NimbusProvider>\n        <Switch isSelected={true}>Controlled switch</Switch>\n      </NimbusProvider>\n    );\n\n    expect(switchElement).toBeChecked();\n  });\n\n  it(\"calls onChange with new value\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Switch isSelected={false} onChange={handleChange}>\n          Controlled switch\n        </Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    await user.click(switchElement);\n\n    expect(handleChange).toHaveBeenCalledWith(true);\n  });\n\n  it(\"updates when isSelected prop changes\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Switch isSelected={false}>Toggle</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).not.toBeChecked();\n\n    rerender(\n      <NimbusProvider>\n        <Switch isSelected={true}>Toggle</Switch>\n      </NimbusProvider>\n    );\n\n    expect(switchElement).toBeChecked();\n  });\n});\n```\n\n### Uncontrolled Mode Tests\n\nTest uncontrolled state management with defaultSelected\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Switch, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Switch - Uncontrolled mode\", () => {\n  it(\"uses defaultSelected for initial state\", () => {\n    render(\n      <NimbusProvider>\n        <Switch defaultSelected={true}>Default on</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).toBeChecked();\n  });\n\n  it(\"manages its own state after initial render\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Switch defaultSelected={false}>Uncontrolled</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).not.toBeChecked();\n\n    await user.click(switchElement);\n    expect(switchElement).toBeChecked();\n\n    await user.click(switchElement);\n    expect(switchElement).not.toBeChecked();\n  });\n});\n```\n\n### State Tests\n\nTest different component states (disabled, invalid, readonly)\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Switch, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Switch - States\", () => {\n  it(\"renders in disabled state\", () => {\n    render(\n      <NimbusProvider>\n        <Switch isDisabled>Disabled switch</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).toBeDisabled();\n  });\n\n  it(\"does not respond to clicks when disabled\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Switch isDisabled onChange={handleChange}>\n          Disabled\n        </Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    await user.click(switchElement);\n\n    expect(handleChange).not.toHaveBeenCalled();\n  });\n\n  it(\"renders in invalid state\", () => {\n    render(\n      <NimbusProvider>\n        <Switch isInvalid>Invalid switch</Switch>\n      </NimbusProvider>\n    );\n\n    const switchRoot = screen\n      .getByText(\"Invalid switch\")\n      .closest(\"[data-slot='root']\");\n    expect(switchRoot).toHaveAttribute(\"data-invalid\", \"true\");\n  });\n\n  it(\"renders in readonly state\", () => {\n    render(\n      <NimbusProvider>\n        <Switch isReadOnly isSelected={true}>\n          Read-only switch\n        </Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).toHaveAttribute(\"aria-readonly\", \"true\");\n  });\n\n  it(\"does not toggle when readonly\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Switch isReadOnly isSelected={false} onChange={handleChange}>\n          Read-only\n        </Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    await user.click(switchElement);\n\n    expect(handleChange).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Accessibility Tests\n\nVerify accessibility attributes and keyboard navigation\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Switch, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Switch - Accessibility\", () => {\n  it(\"has proper switch role\", () => {\n    render(\n      <NimbusProvider>\n        <Switch>Accessible switch</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).toBeInTheDocument();\n  });\n\n  it(\"has accessible name from label\", () => {\n    render(\n      <NimbusProvider>\n        <Switch>Enable feature</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).toHaveAccessibleName(\"Enable feature\");\n  });\n\n  it(\"has accessible name from aria-label\", () => {\n    render(\n      <NimbusProvider>\n        <Switch aria-label=\"Toggle notifications\" />\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).toHaveAccessibleName(\"Toggle notifications\");\n  });\n\n  it(\"supports aria-labelledby\", () => {\n    render(\n      <NimbusProvider>\n        <div>\n          <span id=\"switch-label\">Custom label</span>\n          <Switch aria-labelledby=\"switch-label\" />\n        </div>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).toHaveAccessibleName(\"Custom label\");\n  });\n});\n```\n\n### Form Integration Tests\n\nTest form-related functionality\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Switch, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Switch - Form integration\", () => {\n  it(\"supports name attribute for form submission\", () => {\n    render(\n      <NimbusProvider>\n        <Switch name=\"notifications\">Enable notifications</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).toHaveAttribute(\"name\", \"notifications\");\n  });\n\n  it(\"supports value attribute\", () => {\n    render(\n      <NimbusProvider>\n        <Switch value=\"enabled\">Enable feature</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).toHaveAttribute(\"value\", \"enabled\");\n  });\n\n  it(\"accepts isRequired prop\", () => {\n    render(\n      <NimbusProvider>\n        <Switch isRequired>Accept terms</Switch>\n      </NimbusProvider>\n    );\n\n    const switchElement = screen.getByRole(\"switch\");\n    expect(switchElement).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-switch--docs)\n- [React Aria Switch](https://react-spectrum.adobe.com/react-aria/useSwitch.html)\n- [WAI-ARIA Switch Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/switch/)\n- [ARIA: switch role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/switch_role)\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": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Small size",
+          "href": "#small-size",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Medium size",
+          "href": "#medium-size",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With label",
+          "href": "#with-label",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Without visible label",
+          "href": "#without-visible-label",
+          "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": "Default selected",
+          "href": "#default-selected",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Read-only state",
+          "href": "#read-only-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            9
+          ],
+          "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": "Role",
+          "href": "#role",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labeling",
+          "href": "#labeling",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Persistent ID",
+          "href": "#persistent-id",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            4
+          ],
+          "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": "Settings toggle",
+          "href": "#settings-toggle",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Feature enable/disable",
+          "href": "#feature-enabledisable",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Conditional content display",
+          "href": "#conditional-content-display",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "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": "Controlled Mode Tests",
+          "href": "#controlled-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled Mode Tests",
+          "href": "#uncontrolled-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State Tests",
+          "href": "#state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility Tests",
+          "href": "#accessibility-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form Integration Tests",
+          "href": "#form-integration-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nSwitch guidelines focus on providing a clear, accessible, and visually\nconsistent binary toggle for on/off states, ensuring discoverability, ease of\ninteraction, and proper communication of the current setting.\n\n### Best practices\n\n- **Labels & feedback**: Use clear labels and provide instant visual feedback on\n  state changes.\n- **Functionality**: Employ switches solely for binary on/off actions, avoiding\n  overuse.\n- **Accessibility**: Ensure keyboard navigation and proper ARIA for screen\n  readers.\n\n### Usage\n\n- **Simple on/off settings**: When users need to toggle a single feature or\n  preference between two states (e.g., \"Notifications: On/Off,\" \"Dark Mode:\n  On/Off\").\n- **Immediate, direct control**: When users want to quickly and directly change\n  a setting without navigating through menus or dialogs.\n- **Visual clarity of state**: When it's important to visually represent the\n  current state of a setting at a glance.\n- **User preferences**: When users are setting personal preferences that are\n  binary.\n- **Feature toggles**: When users want to enable or disable features of an\n  application.\n\n### Mixed interaction states\n\nSwitches should represent binary options, without mixing states. Avoid use cases\nthat will need to represent summaries when options are mixed. Try using\ncheckboxes if you have many settings that are selectable.\n\n> [!TIP]\\\n> **Do**\n>\n> - Keep switches to binary options, simplifying for the user.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"200\" alignItems=\"flex-start\">\n    <Text fontWeight=\"700\">Notifications</Text>\n    <Separator />\n    <Switch>Email notifications</Switch>\n    <Switch>Text notifications</Switch>\n  </Stack>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - There is not an indeterminate state for switches. Do not design experiences\n>   where a switch is being used to summarize mixed settings.\n> - Do not excessively use switches, other options like checkboxes are\n>   available.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"200\" alignItems=\"flex-start\">\n    <Switch>Notifications</Switch>\n    <Separator />\n    <Switch defaultSelected>Email notifications</Switch>\n    <Switch>Text notifications</Switch>\n  </Stack>\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": "Mixed interaction states",
+          "href": "#mixed-interaction-states",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}