@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/data/docs/routes/components-buttons-toggle-button-group.json

@@ -0,0 +1,722 @@
+{
+  "meta": {
+    "id": "Components-ToggleButtonGroup",
+    "title": "Toggle button group",
+    "exportName": "ToggleButtonGroup",
+    "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/toggle-button-group/toggle-button-group.mdx",
+    "menu": [
+      "Components",
+      "Buttons",
+      "Toggle button group"
+    ],
+    "route": "components/buttons/toggle-button-group",
+    "tags": [
+      "component",
+      "buttons",
+      "toggle",
+      "group",
+      "controls"
+    ],
+    "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",
+        "href": "#medium",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "X-Small",
+        "href": "#x-small",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Visual options",
+        "href": "#visual-options",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Labels and icons",
+        "href": "#labels-and-icons",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Just labels",
+        "href": "#just-labels",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Just icons",
+        "href": "#just-icons",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          2,
+          3
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=2693-2416&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\nButton groups can be used several ways, with and without icons, and spanning\nfrom two selections to several.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=2693-2416&m=dev)\n\n[`ToggleButtonGroup` on `react-aria`](https://react-spectrum.adobe.com/react-aria/ToggleButtonGroup.html#togglebuttongroup)\n\n[Relevant W3C Aria pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/)\n\n## Variables\n\nGet familiar with the features.\n\n### Size\n\nToggle Button Groups come in different sizes to fit various layout needs.\n\n#### Medium\n\nThis is the default size.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Medium size example (default)\" selectedKeys={[\"md-day\"]} colorPalette=\"primary\">\n    <ToggleButtonGroup.Button id=\"md-day\"><Icons.ViewDay />Day</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"md-week\"><Icons.CalendarViewWeek />Week</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"md-month\"><Icons.CalendarViewMonth />Month</ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n);\n```\n\n#### X-Small\n\nThis size is for compact placements.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root size=\"xs\" aria-label=\"X-Small size example\" selectedKeys={[\"xs-day\"]} colorPalette=\"primary\">\n    <ToggleButtonGroup.Button id=\"xs-day\"><Icons.ViewDay />Day</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"xs-week\"><Icons.CalendarViewWeek />Week</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"xs-month\"><Icons.CalendarViewMonth />Month</ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n);\n```\n\n### Visual options\n\nToggle Button Groups can be configured with labels, icons, or both.\n\n#### Labels and icons\n\nButton groups with icons and labels are used to present a set of related actions\nin a compact and visually clear way, where icons provide quick recognition and\nlabels offer explicit understanding of each option. This combination enhances\nuser efficiency by making common choices readily available and easily\nidentifiable.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Labels and icons example\" selectedKeys={[\"li-shipped\"]} colorPalette=\"primary\">\n    <ToggleButtonGroup.Button id=\"li-processing\">\n      <Icons.RotateRight /> Processing\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"li-shipped\">\n      <Icons.LocalShipping /> Shipped\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"li-cancelled\">\n      <Icons.Dangerous /> Cancelled\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"li-refunded\">\n      <Icons.CurrencyExchange /> Refunded\n    </ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n);\n```\n\n#### Just labels\n\nButton groups with just labels provide explicit understanding of each option.\nThis approach prioritizes readability and ease of comprehension, making it\nsuitable for scenarios where icons might be ambiguous or when the actions are\nbest described through text.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Just labels example\" selectedKeys={[\"label-inactive\"]} colorPalette=\"primary\">\n    <ToggleButtonGroup.Button id=\"label-active\">\n      Active promotions\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"label-inactive\">\n      Inactive promotions\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"label-draft\">\n      Draft promotions\n    </ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n);\n```\n\n#### Just icons\n\nMessages potential problems or situations that require user attention to prevent\nissues. They require the user to take action to make needed corrections or\nconfirmation. Use tooltips for accessibility.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Just icons example\" selectedKeys={[\"icon-copy\"]} colorPalette=\"primary\">\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"icon-edit\" aria-label=\"Edit view\">\n        <Icons.Edit />\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Edit</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"icon-copy\" aria-label=\"Copy view\">\n        <Icons.ContentCopy />\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Copy</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"icon-delete\" aria-label=\"Delete view\">\n        <Icons.Delete />\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Delete</Tooltip.Content>\n    </Tooltip.Root>\n  </ToggleButtonGroup.Root>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nButton groups can be used several ways, with and without icons, and spanning\nfrom two selections to several.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=2693-2416&m=dev)\n\n[`ToggleButtonGroup` on `react-aria`](https://react-spectrum.adobe.com/react-aria/ToggleButtonGroup.html#togglebuttongroup)\n\n[Relevant W3C Aria pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/)\n\n## Variables\n\nGet familiar with the features.\n\n### Size\n\nToggle Button Groups come in different sizes to fit various layout needs.\n\n#### Medium\n\nThis is the default size.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Medium size example (default)\" selectedKeys={[\"md-day\"]} colorPalette=\"primary\">\n    <ToggleButtonGroup.Button id=\"md-day\"><Icons.ViewDay />Day</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"md-week\"><Icons.CalendarViewWeek />Week</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"md-month\"><Icons.CalendarViewMonth />Month</ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n);\n```\n\n#### X-Small\n\nThis size is for compact placements.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root size=\"xs\" aria-label=\"X-Small size example\" selectedKeys={[\"xs-day\"]} colorPalette=\"primary\">\n    <ToggleButtonGroup.Button id=\"xs-day\"><Icons.ViewDay />Day</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"xs-week\"><Icons.CalendarViewWeek />Week</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"xs-month\"><Icons.CalendarViewMonth />Month</ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n);\n```\n\n### Visual options\n\nToggle Button Groups can be configured with labels, icons, or both.\n\n#### Labels and icons\n\nButton groups with icons and labels are used to present a set of related actions\nin a compact and visually clear way, where icons provide quick recognition and\nlabels offer explicit understanding of each option. This combination enhances\nuser efficiency by making common choices readily available and easily\nidentifiable.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Labels and icons example\" selectedKeys={[\"li-shipped\"]} colorPalette=\"primary\">\n    <ToggleButtonGroup.Button id=\"li-processing\">\n      <Icons.RotateRight /> Processing\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"li-shipped\">\n      <Icons.LocalShipping /> Shipped\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"li-cancelled\">\n      <Icons.Dangerous /> Cancelled\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"li-refunded\">\n      <Icons.CurrencyExchange /> Refunded\n    </ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n);\n```\n\n#### Just labels\n\nButton groups with just labels provide explicit understanding of each option.\nThis approach prioritizes readability and ease of comprehension, making it\nsuitable for scenarios where icons might be ambiguous or when the actions are\nbest described through text.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Just labels example\" selectedKeys={[\"label-inactive\"]} colorPalette=\"primary\">\n    <ToggleButtonGroup.Button id=\"label-active\">\n      Active promotions\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"label-inactive\">\n      Inactive promotions\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"label-draft\">\n      Draft promotions\n    </ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n);\n```\n\n#### Just icons\n\nMessages potential problems or situations that require user attention to prevent\nissues. They require the user to take action to make needed corrections or\nconfirmation. Use tooltips for accessibility.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Just icons example\" selectedKeys={[\"icon-copy\"]} colorPalette=\"primary\">\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"icon-edit\" aria-label=\"Edit view\">\n        <Icons.Edit />\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Edit</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"icon-copy\" aria-label=\"Copy view\">\n        <Icons.ContentCopy />\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Copy</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"icon-delete\" aria-label=\"Delete view\">\n        <Icons.Delete />\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Delete</Tooltip.Content>\n    </Tooltip.Root>\n  </ToggleButtonGroup.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": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Medium",
+          "href": "#medium",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "X-Small",
+          "href": "#x-small",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual options",
+          "href": "#visual-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labels and icons",
+          "href": "#labels-and-icons",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Just labels",
+          "href": "#just-labels",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Just icons",
+          "href": "#just-icons",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            2,
+            3
+          ],
+          "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  <ToggleButtonGroup.Root aria-label=\"Labels and icons example\" selectedKeys={[\"li-shipped\"]} colorPalette=\"primary\">\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"li-processing\">\n        <Icons.RotateRight /> Processing\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Processing Status</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"li-shipped\">\n        <Icons.LocalShipping /> Shipped\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Shipped Status</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"li-cancelled\">\n        <Icons.Dangerous /> Cancelled\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Cancelled Status</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"li-refunded\">\n        <Icons.CurrencyExchange /> Refunded\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Refunded Status</Tooltip.Content>\n    </Tooltip.Root>\n  </ToggleButtonGroup.Root>\n);\n```\n\n### Accessibility standards\n\n- **Provide text alternatives for non-text content:** Provide text alternatives\n  for any non-text content (e.g., icons within buttons) via `aria-label` on the\n  button or surrounding `Tooltip`. Ensure icons have sufficient visual clarity.\n- **Don't rely on color alone:** Avoid relying solely on color to indicate the\n  selected state. Default styles typically use background color and potentially\n  borders or font weight changes.\n- **Ensure sufficient contrast:** Ensure sufficient color contrast between\n  button text/icons and their background, in both selected and unselected\n  states. Ensure sufficient contrast between adjacent buttons.\n- **Keyboard navigation:** Make the entire group focusable using the Tab key.\n  Allow navigation between buttons within the group using arrow keys (Left/Right\n  or Up/Down depending on orientation). Allow selection using the Enter or Space\n  key.\n- **Clear button labels:** Button labels (text or `aria-label` for icons) should\n  clearly describe the action or choice.\n- **Focus visible:** Provide a clear and visible focus indicator for the\n  currently focused button within the group.\n- **No unexpected focus changes:** Ensure that moving focus between buttons does\n  not trigger unexpected actions.\n- **Provide group label:** Provide a clear `aria-label` for the\n  `ToggleButtonGroup.Root` element to describe the purpose of the group to\n  assistive technologies.\n- **Use appropriate ARIA roles:** Use appropriate ARIA roles (e.g., `radiogroup`\n  for single selection, `group` for multiple selection, `radio` or `checkbox`\n  for items depending on mode) to ensure compatibility with assistive\n  technologies. Nimbus components built on React Aria generally handle this\n  automatically.\n\n### Resources\n\n- [W3C ARIA Authoring Practices Guide (APG) - Radio Group](https://www.w3.org/WAI/ARIA/apg/patterns/radio/)\n- [W3C ARIA Authoring Practices Guide (APG) - Toolbar](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/)\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 { ToggleButtonGroup, type ToggleButtonGroupProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe ToggleButtonGroup component groups multiple toggle buttons together, allowing users to select one or more options from a set of related choices. It uses a compound component structure with `Root` and `Button` sub-components:\n\n```jsx live-dev\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Text alignment\">\n    <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"center\">Center</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n)\n```\n\nBy default, the group operates in single-selection mode where only one button can be selected at a time. Each button must have a unique `id` prop that identifies it within the group.\n\n## Usage examples\n\n### Size options\n\nThe component supports two size variants to match your interface density:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <ToggleButtonGroup.Root size=\"md\" aria-label=\"Medium text alignment\">\n      <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"center\">Center</ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n    </ToggleButtonGroup.Root>\n\n    <ToggleButtonGroup.Root size=\"xs\" aria-label=\"Small text alignment\">\n      <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"center\">Center</ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n    </ToggleButtonGroup.Root>\n  </Stack>\n)\n```\n\n### Color palettes\n\nChoose from semantic color palettes to match your design context:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <ToggleButtonGroup.Root colorPalette=\"primary\" aria-label=\"Primary alignment\">\n      <ToggleButtonGroup.Button id=\"left\">\n        <Icons.FormatAlignLeft />\n      </ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"center\">\n        <Icons.FormatAlignCenter />\n      </ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"right\">\n        <Icons.FormatAlignRight />\n      </ToggleButtonGroup.Button>\n    </ToggleButtonGroup.Root>\n\n    <ToggleButtonGroup.Root colorPalette=\"critical\" aria-label=\"Critical actions\">\n      <ToggleButtonGroup.Button id=\"delete\">\n        <Icons.Delete />\n      </ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"warning\">\n        <Icons.Warning />\n      </ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"block\">\n        <Icons.Block />\n      </ToggleButtonGroup.Button>\n    </ToggleButtonGroup.Root>\n\n    <ToggleButtonGroup.Root colorPalette=\"neutral\" aria-label=\"Neutral formatting\">\n      <ToggleButtonGroup.Button id=\"bold\">\n        <Icons.FormatBold />\n      </ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"italic\">\n        <Icons.FormatItalic />\n      </ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"underline\">\n        <Icons.FormatUnderlined />\n      </ToggleButtonGroup.Button>\n    </ToggleButtonGroup.Root>\n  </Stack>\n)\n```\n\n### With icons\n\nIcons can be used alone or combined with text labels:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <ToggleButtonGroup.Root aria-label=\"Icon-only formatting\">\n      <ToggleButtonGroup.Button id=\"bold\" aria-label=\"Bold\">\n        <Icons.FormatBold />\n      </ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"italic\" aria-label=\"Italic\">\n        <Icons.FormatItalic />\n      </ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"underline\" aria-label=\"Underline\">\n        <Icons.FormatUnderlined />\n      </ToggleButtonGroup.Button>\n    </ToggleButtonGroup.Root>\n\n    <ToggleButtonGroup.Root aria-label=\"Text alignment with labels\">\n      <ToggleButtonGroup.Button id=\"left\">\n        <Icons.FormatAlignLeft /> Left\n      </ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"center\">\n        <Icons.FormatAlignCenter /> Center\n      </ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"right\">\n        <Icons.FormatAlignRight /> Right\n      </ToggleButtonGroup.Button>\n    </ToggleButtonGroup.Root>\n  </Stack>\n)\n```\n\nWhen using icon-only buttons, always provide an `aria-label` on each button for screen reader accessibility.\n\n### Selection modes\n\nThe group supports both single-selection (default) and multi-selection modes:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"350\" fontWeight=\"600\">Single selection (default)</Text>\n      <ToggleButtonGroup.Root aria-label=\"Text alignment\">\n        <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"center\">Center</ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n      </ToggleButtonGroup.Root>\n    </Stack>\n\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"350\" fontWeight=\"600\">Multiple selection</Text>\n      <ToggleButtonGroup.Root selectionMode=\"multiple\" aria-label=\"Text formatting\">\n        <ToggleButtonGroup.Button id=\"bold\" aria-label=\"Bold\">\n          <Icons.FormatBold />\n        </ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"italic\" aria-label=\"Italic\">\n          <Icons.FormatItalic />\n        </ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"underline\" aria-label=\"Underline\">\n          <Icons.FormatUnderlined />\n        </ToggleButtonGroup.Button>\n      </ToggleButtonGroup.Root>\n    </Stack>\n  </Stack>\n)\n```\n\nIn single-selection mode, selecting a button automatically deselects any previously selected button. In multi-selection mode, users can select multiple buttons independently.\n\n### Disabled state\n\nDisable the entire group or individual buttons:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"350\" fontWeight=\"600\">Disabled group</Text>\n      <ToggleButtonGroup.Root isDisabled aria-label=\"Disabled alignment\">\n        <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"center\">Center</ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n      </ToggleButtonGroup.Root>\n    </Stack>\n\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontSize=\"350\" fontWeight=\"600\">Individual disabled buttons</Text>\n      <ToggleButtonGroup.Root aria-label=\"Partial alignment\">\n        <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"center\" isDisabled>Center</ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n      </ToggleButtonGroup.Root>\n    </Stack>\n  </Stack>\n)\n```\n\n### Uncontrolled mode\n\nUse `defaultSelectedKeys` to set initial selection without managing state:\n\n```jsx live-dev\nconst App = () => {\n  const handleSelectionChange = (keys) => {\n    console.log('Selection changed:', Array.from(keys));\n  };\n\n  return (\n    <ToggleButtonGroup.Root\n      defaultSelectedKeys={['center']}\n      onSelectionChange={handleSelectionChange}\n      aria-label=\"Text alignment\"\n    >\n      <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"center\">Center</ToggleButtonGroup.Button>\n      <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n    </ToggleButtonGroup.Root>\n  );\n}\n```\n\n### Controlled mode\n\nFor full control over selection state, use `selectedKeys` with `onSelectionChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedKeys, setSelectedKeys] = React.useState(new Set(['left']));\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <ToggleButtonGroup.Root\n        selectedKeys={selectedKeys}\n        onSelectionChange={setSelectedKeys}\n        aria-label=\"Text alignment\"\n      >\n        <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"center\">Center</ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n      </ToggleButtonGroup.Root>\n\n      <Text fontSize=\"350\">\n        Selected: {Array.from(selectedKeys).join(', ') || 'none'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\nIn controlled mode, the component's selection state is fully managed by your application. The `selectedKeys` prop accepts a `Set` containing the IDs of selected buttons.\n\n### Multi-selection with controlled state\n\nCombine `selectionMode=\"multiple\"` with controlled state for complex selection logic:\n\n```jsx live-dev\nconst App = () => {\n  const [selectedFormats, setSelectedFormats] = React.useState(new Set([]));\n\n  const formatNames = {\n    bold: 'Bold',\n    italic: 'Italic',\n    underline: 'Underline'\n  };\n\n  const selectedList = Array.from(selectedFormats)\n    .map(key => formatNames[key])\n    .join(', ');\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <ToggleButtonGroup.Root\n        selectionMode=\"multiple\"\n        selectedKeys={selectedFormats}\n        onSelectionChange={setSelectedFormats}\n        aria-label=\"Text formatting\"\n      >\n        <ToggleButtonGroup.Button id=\"bold\" aria-label=\"Bold\">\n          <Icons.FormatBold />\n        </ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"italic\" aria-label=\"Italic\">\n          <Icons.FormatItalic />\n        </ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"underline\" aria-label=\"Underline\">\n          <Icons.FormatUnderlined />\n        </ToggleButtonGroup.Button>\n      </ToggleButtonGroup.Root>\n\n      <Text fontSize=\"350\">\n        Active formats: {selectedList || 'none'}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nThe ToggleButtonGroup component follows WCAG 2.1 AA guidelines and uses React Aria for robust accessibility support.\n\n#### Role\n\n- **Single-selection mode (default)**:\n  - Root element has `role=\"radiogroup\"`\n  - Each button has `role=\"radio\"`\n- **Multi-selection mode**:\n  - Root element has `role=\"toolbar\"`\n  - Each button has `role=\"button\"` with `aria-pressed` attribute\n\n#### Labeling\n\n- **Group label required**: Always provide an `aria-label` or `aria-labelledby` on the Root component\n- **Button labels**: Each button must have accessible text content or an `aria-label`\n- **Icon-only buttons**: Must include an `aria-label` on each button\n\n```jsx live-dev\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Text formatting options\">\n    <ToggleButtonGroup.Button id=\"bold\" aria-label=\"Toggle bold\">\n      <Icons.FormatBold />\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"italic\" aria-label=\"Toggle italic\">\n      <Icons.FormatItalic />\n    </ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n)\n```\n\n#### Keyboard navigation\n\n| Key | Action |\n|-----|--------|\n| `Tab` | Move focus into/out of the button group |\n| `Arrow Left/Up` | Move focus to the previous button |\n| `Arrow Right/Down` | Move focus to the next button |\n| `Space` | Toggle the focused button's selection state |\n| `Home` | Move focus to the first button |\n| `End` | Move focus to the last button |\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\nconst PERSISTENT_ID = \"text-alignment-toggle-group\";\n\nexport const Example = () => (\n  <ToggleButtonGroup.Root id={PERSISTENT_ID} aria-label=\"Text alignment\">\n    <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"center\">Center</ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n);\n```\n\n## API reference\n\n<PropsTable id=\"ToggleButtonGroup\" />\n\n## Common patterns\n\n### Text editor toolbar\n\nCombine multiple toggle button groups to create a rich text formatting toolbar:\n\n```jsx live-dev\nconst App = () => {\n  const [alignment, setAlignment] = React.useState(new Set(['left']));\n  const [formats, setFormats] = React.useState(new Set([]));\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <ToggleButtonGroup.Root\n        selectionMode=\"multiple\"\n        selectedKeys={formats}\n        onSelectionChange={setFormats}\n        size=\"xs\"\n        aria-label=\"Text formatting\"\n      >\n        <ToggleButtonGroup.Button id=\"bold\" aria-label=\"Bold\">\n          <Icons.FormatBold />\n        </ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"italic\" aria-label=\"Italic\">\n          <Icons.FormatItalic />\n        </ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"underline\" aria-label=\"Underline\">\n          <Icons.FormatUnderlined />\n        </ToggleButtonGroup.Button>\n      </ToggleButtonGroup.Root>\n\n      <Separator orientation=\"vertical\" height=\"6\" />\n\n      <ToggleButtonGroup.Root\n        selectedKeys={alignment}\n        onSelectionChange={setAlignment}\n        size=\"xs\"\n        aria-label=\"Text alignment\"\n      >\n        <ToggleButtonGroup.Button id=\"left\" aria-label=\"Align left\">\n          <Icons.FormatAlignLeft />\n        </ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"center\" aria-label=\"Align center\">\n          <Icons.FormatAlignCenter />\n        </ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"right\" aria-label=\"Align right\">\n          <Icons.FormatAlignRight />\n        </ToggleButtonGroup.Button>\n      </ToggleButtonGroup.Root>\n    </Stack>\n  );\n}\n```\n\n### View mode selector\n\nUse toggle button groups to switch between different view modes:\n\n```jsx live-dev\nconst App = () => {\n  const [viewMode, setViewMode] = React.useState(new Set(['grid']));\n\n  const selectedMode = Array.from(viewMode)[0] || 'grid';\n\n  return (\n    <Stack direction=\"column\" gap=\"300\">\n      <ToggleButtonGroup.Root\n        selectedKeys={viewMode}\n        onSelectionChange={setViewMode}\n        aria-label=\"View mode\"\n      >\n        <ToggleButtonGroup.Button id=\"grid\" aria-label=\"Grid view\">\n          <Icons.GridView />\n        </ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"list\" aria-label=\"List view\">\n          <Icons.ViewList />\n        </ToggleButtonGroup.Button>\n        <ToggleButtonGroup.Button id=\"column\" aria-label=\"Column view\">\n          <Icons.ViewColumn />\n        </ToggleButtonGroup.Button>\n      </ToggleButtonGroup.Root>\n\n      <Text fontSize=\"350\">Current view: {selectedMode}</Text>\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using ToggleButtonGroup 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 toggle button group renders with expected structure and accessibility attributes\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { ToggleButtonGroup, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ToggleButtonGroup - Basic rendering\", () => {\n  it(\"renders toggle button group with buttons\", () => {\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root aria-label=\"Text alignment\">\n          <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"center\">\n            Center\n          </ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"radiogroup\", { name: /text alignment/i });\n    expect(group).toBeInTheDocument();\n\n    const buttons = within(group).getAllByRole(\"radio\");\n    expect(buttons).toHaveLength(3);\n    expect(buttons[0]).toHaveTextContent(\"Left\");\n    expect(buttons[1]).toHaveTextContent(\"Center\");\n    expect(buttons[2]).toHaveTextContent(\"Right\");\n  });\n\n  it(\"renders with correct accessibility attributes\", () => {\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root aria-label=\"Formatting options\">\n          <ToggleButtonGroup.Button id=\"bold\">Bold</ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"italic\">\n            Italic\n          </ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const group = screen.getByRole(\"radiogroup\", {\n      name: /formatting options/i,\n    });\n    expect(group).toHaveAttribute(\"aria-label\", \"Formatting options\");\n  });\n});\n```\n\n### Single Selection Tests\n\nTest single-selection mode behavior (default mode)\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { ToggleButtonGroup, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ToggleButtonGroup - Single selection mode\", () => {\n  it(\"allows selecting one button at a time\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root\n          onSelectionChange={handleChange}\n          aria-label=\"Text alignment\"\n        >\n          <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"center\">\n            Center\n          </ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const buttons = screen.getAllByRole(\"radio\");\n    const [leftButton, centerButton] = buttons;\n\n    // Initially no buttons selected\n    expect(leftButton).toHaveAttribute(\"aria-checked\", \"false\");\n    expect(centerButton).toHaveAttribute(\"aria-checked\", \"false\");\n\n    // Click first button\n    await user.click(leftButton);\n    expect(handleChange).toHaveBeenCalledWith(new Set([\"left\"]));\n\n    // Click second button - should deselect first\n    await user.click(centerButton);\n    expect(handleChange).toHaveBeenCalledWith(new Set([\"center\"]));\n  });\n\n  it(\"supports toggling selection by clicking same button\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root\n          onSelectionChange={handleChange}\n          aria-label=\"Options\"\n        >\n          <ToggleButtonGroup.Button id=\"option1\">\n            Option 1\n          </ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"radio\");\n\n    // Select\n    await user.click(button);\n    expect(handleChange).toHaveBeenCalledWith(new Set([\"option1\"]));\n\n    // Deselect\n    await user.click(button);\n    expect(handleChange).toHaveBeenCalledWith(new Set());\n  });\n});\n```\n\n### Multiple Selection Tests\n\nTest multi-selection mode behavior with selectionMode=\"multiple\"\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { ToggleButtonGroup, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ToggleButtonGroup - Multiple selection mode\", () => {\n  it(\"allows selecting multiple buttons independently\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root\n          selectionMode=\"multiple\"\n          onSelectionChange={handleChange}\n          aria-label=\"Text formatting\"\n        >\n          <ToggleButtonGroup.Button id=\"bold\">Bold</ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"italic\">\n            Italic\n          </ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"underline\">\n            Underline\n          </ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const toolbar = screen.getByRole(\"toolbar\", { name: /text formatting/i });\n    const buttons = within(toolbar).getAllByRole(\"button\");\n    const [boldButton, italicButton] = buttons;\n\n    // Select first button\n    await user.click(boldButton);\n    expect(handleChange).toHaveBeenCalledWith(new Set([\"bold\"]));\n\n    handleChange.mockClear();\n\n    // Select second button - first should remain selected\n    await user.click(italicButton);\n    expect(handleChange).toHaveBeenCalledWith(new Set([\"bold\", \"italic\"]));\n  });\n});\n```\n\n### Keyboard Navigation Tests\n\nTest keyboard interactions and focus management\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { ToggleButtonGroup, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ToggleButtonGroup - Keyboard navigation\", () => {\n  it(\"supports arrow key navigation between buttons\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root aria-label=\"Navigation\">\n          <ToggleButtonGroup.Button id=\"first\">First</ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"second\">\n            Second\n          </ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"third\">Third</ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const buttons = screen.getAllByRole(\"radio\");\n    const [firstButton, secondButton, thirdButton] = buttons;\n\n    // Tab to focus first button\n    await user.tab();\n    expect(firstButton).toHaveFocus();\n\n    // Arrow right to second button\n    await user.keyboard(\"{ArrowRight}\");\n    expect(secondButton).toHaveFocus();\n\n    // Arrow right to third button\n    await user.keyboard(\"{ArrowRight}\");\n    expect(thirdButton).toHaveFocus();\n\n    // Arrow left back to second button\n    await user.keyboard(\"{ArrowLeft}\");\n    expect(secondButton).toHaveFocus();\n  });\n\n  it(\"supports Space key for toggling selection\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root\n          onSelectionChange={handleChange}\n          aria-label=\"Options\"\n        >\n          <ToggleButtonGroup.Button id=\"option1\">\n            Option 1\n          </ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"option2\">\n            Option 2\n          </ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    // Tab to focus first button\n    await user.tab();\n\n    // Press Space to select\n    await user.keyboard(\" \");\n    expect(handleChange).toHaveBeenCalledWith(new Set([\"option1\"]));\n\n    handleChange.mockClear();\n\n    // Navigate to second button\n    await user.keyboard(\"{ArrowRight}\");\n\n    // Press Space to select second\n    await user.keyboard(\" \");\n    expect(handleChange).toHaveBeenCalledWith(new Set([\"option2\"]));\n  });\n});\n```\n\n### Disabled State Tests\n\nTest behavior when group or individual buttons are disabled\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { ToggleButtonGroup, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ToggleButtonGroup - Disabled state\", () => {\n  it(\"disables entire group when isDisabled is true\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root\n          isDisabled\n          onSelectionChange={handleChange}\n          aria-label=\"Disabled group\"\n        >\n          <ToggleButtonGroup.Button id=\"option1\">\n            Option 1\n          </ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"option2\">\n            Option 2\n          </ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const buttons = screen.getAllByRole(\"radio\");\n\n    // All buttons should be disabled\n    buttons.forEach((button) => {\n      expect(button).toBeDisabled();\n    });\n\n    // Clicking disabled button should not trigger change\n    await user.click(buttons[0]);\n    expect(handleChange).not.toHaveBeenCalled();\n  });\n\n  it(\"disables individual buttons\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root\n          onSelectionChange={handleChange}\n          aria-label=\"Partial disabled\"\n        >\n          <ToggleButtonGroup.Button id=\"enabled\">\n            Enabled\n          </ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"disabled\" isDisabled>\n            Disabled\n          </ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const buttons = screen.getAllByRole(\"radio\");\n    const [enabledButton, disabledButton] = buttons;\n\n    expect(enabledButton).not.toBeDisabled();\n    expect(disabledButton).toBeDisabled();\n\n    // Click enabled button works\n    await user.click(enabledButton);\n    expect(handleChange).toHaveBeenCalledWith(new Set([\"enabled\"]));\n\n    handleChange.mockClear();\n\n    // Click disabled button does not work\n    await user.click(disabledButton);\n    expect(handleChange).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled selection state with selectedKeys prop\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { ToggleButtonGroup, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ToggleButtonGroup - Controlled mode\", () => {\n  it(\"respects controlled selectedKeys prop\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root\n          selectedKeys={new Set([\"center\"])}\n          aria-label=\"Controlled\"\n        >\n          <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"center\">\n            Center\n          </ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const buttons = screen.getAllByRole(\"radio\");\n    const [leftButton, centerButton, rightButton] = buttons;\n\n    // Center button should be selected\n    expect(leftButton).toHaveAttribute(\"aria-checked\", \"false\");\n    expect(centerButton).toHaveAttribute(\"aria-checked\", \"true\");\n    expect(rightButton).toHaveAttribute(\"aria-checked\", \"false\");\n\n    // Update selection externally\n    rerender(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root\n          selectedKeys={new Set([\"right\"])}\n          aria-label=\"Controlled\"\n        >\n          <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"center\">\n            Center\n          </ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    // Right button should now be selected\n    expect(leftButton).toHaveAttribute(\"aria-checked\", \"false\");\n    expect(centerButton).toHaveAttribute(\"aria-checked\", \"false\");\n    expect(rightButton).toHaveAttribute(\"aria-checked\", \"true\");\n  });\n\n  it(\"calls onSelectionChange with updated selection\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root\n          selectedKeys={new Set([\"left\"])}\n          onSelectionChange={handleChange}\n          aria-label=\"Controlled with callback\"\n        >\n          <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"center\">\n            Center\n          </ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const buttons = screen.getAllByRole(\"radio\");\n    const centerButton = buttons[1];\n\n    await user.click(centerButton);\n    expect(handleChange).toHaveBeenCalledWith(new Set([\"center\"]));\n  });\n});\n```\n\n### Uncontrolled Mode Tests\n\nTest uncontrolled selection with defaultSelectedKeys prop\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, within } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { ToggleButtonGroup, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ToggleButtonGroup - Uncontrolled mode\", () => {\n  it(\"respects defaultSelectedKeys for initial selection\", () => {\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root\n          defaultSelectedKeys={[\"center\"]}\n          aria-label=\"Uncontrolled\"\n        >\n          <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"center\">\n            Center\n          </ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"right\">Right</ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const buttons = screen.getAllByRole(\"radio\");\n    const [leftButton, centerButton, rightButton] = buttons;\n\n    expect(leftButton).toHaveAttribute(\"aria-checked\", \"false\");\n    expect(centerButton).toHaveAttribute(\"aria-checked\", \"true\");\n    expect(rightButton).toHaveAttribute(\"aria-checked\", \"false\");\n  });\n\n  it(\"manages selection state internally\", async () => {\n    const user = userEvent.setup();\n    const handleChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ToggleButtonGroup.Root\n          defaultSelectedKeys={[\"left\"]}\n          onSelectionChange={handleChange}\n          aria-label=\"Uncontrolled internal\"\n        >\n          <ToggleButtonGroup.Button id=\"left\">Left</ToggleButtonGroup.Button>\n          <ToggleButtonGroup.Button id=\"center\">\n            Center\n          </ToggleButtonGroup.Button>\n        </ToggleButtonGroup.Root>\n      </NimbusProvider>\n    );\n\n    const buttons = screen.getAllByRole(\"radio\");\n    const centerButton = buttons[1];\n\n    // Click center button\n    await user.click(centerButton);\n\n    // Callback should be called with new selection\n    expect(handleChange).toHaveBeenCalledWith(new Set([\"center\"]));\n\n    // Component should update its own internal state\n    expect(centerButton).toHaveAttribute(\"aria-checked\", \"true\");\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-buttons-togglebuttongroup--docs)\n- [React Aria ToggleButton](https://react-spectrum.adobe.com/react-aria/ToggleButton.html)\n- [ARIA: radio role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/radio_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": "Color palettes",
+          "href": "#color-palettes",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With icons",
+          "href": "#with-icons",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Selection modes",
+          "href": "#selection-modes",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-selection with controlled state",
+          "href": "#multi-selection-with-controlled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "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": "Text editor toolbar",
+          "href": "#text-editor-toolbar",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "View mode selector",
+          "href": "#view-mode-selector",
+          "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": "Single Selection Tests",
+          "href": "#single-selection-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multiple Selection Tests",
+          "href": "#multiple-selection-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard Navigation Tests",
+          "href": "#keyboard-navigation-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled State Tests",
+          "href": "#disabled-state-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled Mode Tests",
+          "href": "#controlled-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled Mode Tests",
+          "href": "#uncontrolled-mode-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\nButton group guidelines focus on presenting sets of related actions in a clear,\norganized, and accessible manner, enabling users to easily understand and choose\nbetween the available options, often emphasizing visual connection and logical\narrangement.\n\n### Best practices\n\n- **Order logically:** Arrange buttons by importance or user flow.\n- **Use clear labels:** Keep button text concise and understandable, if using\n  icons, utilize tooltip labels.\n- **Limit button count:** Avoid overwhelming users with too many options.\n- **Space appropriately:** Place button groups close to controlled content.\n- **Ensure accessibility:** Make them navigable and understandable by everyone.\n\n### Usage\n\nA button group is best used when you need to present users with a set of closely\nrelated, mutually exclusive (e.g., a user selecting data table views), or\ncomplementary actions that are important enough to be displayed directly in the\ninterface for quick access. Think of scenarios where users need to make a choice\nbetween a few options or perform a series of connected tasks within a specific\ncontext.\n\n> [!TIP]\\\n> When to use\n\n- **Grouping related actions:** Organize similar tasks together. Use button\n  groups to cluster actions that are logically connected, like order processing\n  steps or product editing options.\n- **Providing mutually exclusive choices:** Offer clear alternatives. When users\n  need to select only one option from a set, like filtering by order status or\n  choosing a report timeframe.\n- **Streamlining workflows:** Enable quick task completion. For frequently\n  performed actions on a single item or within a specific context, like managing\n  inventory or editing customer details.\n- **Conserving screen space:** Present options compactly. When screen real\n  estate is limited, button groups offer a space-efficient way to display\n  multiple relevant actions.\n- **Enhancing visual clarity:** Improve comprehension of options. Visually\n  connecting related buttons helps users understand the available choices and\n  their relationships.\n- **Facilitating efficient navigation:** Offer quick jumps within a section. For\n  navigating between closely related views or steps within a specific management\n  area.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Do not use a button group as a tab navigation:** There is a specific\n  [tab component](#), please use this component instead. There is better\n  accessibility support, and consistency with other designs and uses.\n- **Unrelated actions:** Don't group unrelated actions together. If buttons\n  perform completely different tasks, a button group can be confusing.\n- **Overcrowding the UI:** Avoid too many buttons within a group. Too much\n  choice confuses users and makes decision making more difficult.\n- **Do not use for multi-stepped processes:** Button groups are for single click\n  actions, not for guiding users through complex sequences.\n- **Avoid if actions aren't logically linked:** If there is no clear\n  relationship between the buttons, grouping them may be misleading.\n\n### Selecting views\n\nTo allow users to switch between different display views (e.g., grid view, list\nview, map view). Make sure that users can easily recognize icons and pair with\nhover tooltips.\n\n> [!TIP]\\\n> **Do**\n>\n> - Do use clear differentiated, and familiar icons for users to be able to\n>   toggle options.\n> - Do use tooltips to easily explain what a tool is to a user.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Select view\" selectedKeys={[\"view-list\"]} colorPalette=\"primary\">\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"view-grid\" aria-label=\"Grid View\">\n        <Icons.Apps />\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Grid View</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"view-list\" aria-label=\"List View\">\n        <Icons.List />\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>List View</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <ToggleButtonGroup.Button id=\"view-map\" aria-label=\"Map View\">\n        <Icons.ViewWeek />\n      </ToggleButtonGroup.Button>\n      <Tooltip.Content>Week View</Tooltip.Content>\n    </Tooltip.Root>\n  </ToggleButtonGroup.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not use icons that users will not easily recognize or pairings of icons\n>   that seem too visually similar.\n> - Always pair icon buttons with tooltip labels for all users.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Select view (Bad Example)\" selectedKeys={[\"view-confusing2\"]} colorPalette=\"primary\">\n    <ToggleButtonGroup.Button id=\"view-confusing1\" aria-label=\"Confusing Icon 1\">\n      <Icons.Apartment />\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"view-confusing2\" aria-label=\"Confusing Icon 2\">\n      <Icons.ProductionQuantityLimits />\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"view-confusing3\" aria-label=\"Confusing Icon 3\">\n      <Icons.Tour />\n    </ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n);\n```\n\n### Filter information\n\nIn data tables or lists, button groups can be used to filter or sort content.\n\n> [!TIP]\\\n> **Do**\n>\n> - When using button groups to show filtered lists, pair closely with\n>   information to make sure that users know that this interaction shows tagged\n>   information instead of changing the state of any selected data. This can\n>   sometimes look like an item count included with the button group items.\n> - It is not good practice to mix styles in button groupings.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Filter status\" selectedKeys={[\"filter-accepted\"]} colorPalette=\"primary\">\n    <ToggleButtonGroup.Button id=\"filter-drafts\">\n      Drafts (6)\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"filter-accepted\">\n      Accepted (2)\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"filter-rejected\">\n      Rejected (10)\n    </ToggleButtonGroup.Button>\n  </ToggleButtonGroup.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not confuse the user with unclear options.\n> - Do not use unfamiliar and lengthly labels.\n\n```jsx live\nconst App = () => (\n  <ToggleButtonGroup.Root aria-label=\"Filter status (Bad Example)\" selectedKeys={[\"filter-granted\"]} colorPalette=\"primary\">\n    <ToggleButtonGroup.Button id=\"filter-compositions\">\n      Compositions\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"filter-granted\">\n      Granted\n    </ToggleButtonGroup.Button>\n    <ToggleButtonGroup.Button id=\"filter-veto\">\n      Veto\n    </ToggleButtonGroup.Button>\n  </ToggleButtonGroup.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": "Selecting views",
+          "href": "#selecting-views",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Filter information",
+          "href": "#filter-information",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}