@commercetools/nimbus-mcp 3.2.0 → 3.4.0

package/data/docs/routes/components-navigation-menu.json

@@ -123,7 +123,7 @@
       ]
     },
     "dev": {
-      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Menu, type MenuRootProps, type MenuItemProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation creates an action menu with items:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root onAction={(key) => alert(`Action: ${key}`)}>\n    <Menu.Trigger>Actions</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"edit\">Edit</Menu.Item>\n      <Menu.Item id=\"duplicate\">Duplicate</Menu.Item>\n      <Menu.Item id=\"delete\">Delete</Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n## Usage examples\n\n### Custom triggers\n\nUse `asChild` to render custom trigger elements like Button or IconButton:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Menu.Root>\n      <Menu.Trigger asChild>\n        <Button variant=\"solid\" colorPalette=\"primary\">\n          <Icons.KeyboardArrowDown />\n          Button Trigger\n        </Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"option1\">Option 1</Menu.Item>\n        <Menu.Item id=\"option2\">Option 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n\n    <Menu.Root>\n      <Menu.Trigger asChild>\n        <IconButton\n          variant=\"ghost\"\n          colorPalette=\"neutral\"\n          aria-label=\"More options\"\n        >\n          <Icons.MoreVert />\n        </IconButton>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"edit\">Edit</Menu.Item>\n        <Menu.Item id=\"delete\">Delete</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n  </Stack>\n)\n```\n\n### Menu placement\n\nControl where the menu appears relative to the trigger with the `placement` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Menu.Root placement=\"bottom start\">\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">Bottom Start</Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"1\">Item 1</Menu.Item>\n        <Menu.Item id=\"2\">Item 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n\n    <Menu.Root placement=\"bottom end\">\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">Bottom End</Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"1\">Item 1</Menu.Item>\n        <Menu.Item id=\"2\">Item 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n\n    <Menu.Root placement=\"right\">\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">Right</Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"1\">Item 1</Menu.Item>\n        <Menu.Item id=\"2\">Item 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n  </Stack>\n)\n```\n\n### Rich item content\n\nMenu items support icons, labels, descriptions, and keyboard shortcuts using slots:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Edit Menu</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"copy\">\n        <Icon slot=\"icon\"><Icons.ContentCopy /></Icon>\n        <Text slot=\"label\">Copy</Text>\n        <Text slot=\"description\">Copy to clipboard</Text>\n        <Kbd slot=\"keyboard\">⌘C</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"paste\">\n        <Icon slot=\"icon\"><Icons.ContentPaste /></Icon>\n        <Text slot=\"label\">Paste</Text>\n        <Text slot=\"description\">Paste from clipboard</Text>\n        <Kbd slot=\"keyboard\">⌘V</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"cut\">\n        <Icon slot=\"icon\"><Icons.ContentCut /></Icon>\n        <Text slot=\"label\">Cut</Text>\n        <Kbd slot=\"keyboard\">⌘X</Kbd>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Critical items\n\nUse `isCritical` to highlight destructive actions:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>File Actions</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"rename\">\n        <Icon slot=\"icon\"><Icons.Edit /></Icon>\n        <Text slot=\"label\">Rename</Text>\n      </Menu.Item>\n      <Menu.Item id=\"archive\">\n        <Icon slot=\"icon\"><Icons.Archive /></Icon>\n        <Text slot=\"label\">Archive</Text>\n      </Menu.Item>\n      <Separator />\n      <Menu.Item id=\"delete\" isCritical>\n        <Icon slot=\"icon\"><Icons.Delete /></Icon>\n        <Text slot=\"label\">Delete</Text>\n        <Text slot=\"description\">This action cannot be undone</Text>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Disabled items\n\nUse `isDisabled` on individual items to prevent interaction:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Edit</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"undo\">\n        <Text slot=\"label\">Undo</Text>\n        <Kbd slot=\"keyboard\">⌘Z</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"redo\" isDisabled>\n        <Text slot=\"label\">Redo</Text>\n        <Text slot=\"description\">Nothing to redo</Text>\n        <Kbd slot=\"keyboard\">⌘⇧Z</Kbd>\n      </Menu.Item>\n      <Separator />\n      <Menu.Item id=\"paste\" isDisabled>\n        <Text slot=\"label\">Paste</Text>\n        <Text slot=\"description\">Clipboard is empty</Text>\n        <Kbd slot=\"keyboard\">⌘V</Kbd>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Sections with labels\n\nGroup related items using `Menu.Section` with a label:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Application Menu</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Section label=\"File\">\n        <Menu.Item id=\"new\">New Document</Menu.Item>\n        <Menu.Item id=\"open\">Open</Menu.Item>\n        <Menu.Item id=\"save\">Save</Menu.Item>\n      </Menu.Section>\n      <Separator />\n      <Menu.Section label=\"Edit\">\n        <Menu.Item id=\"undo\">Undo</Menu.Item>\n        <Menu.Item id=\"redo\">Redo</Menu.Item>\n      </Menu.Section>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Single selection mode\n\nUse `selectionMode=\"single\"` for radio-button-like behavior within a section:\n\n```jsx live-dev\nconst App = () => {\n  const [selected, setSelected] = useState<string>(\"medium\");\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Menu.Root\n        selectionMode=\"single\"\n        selectedKeys={new Set([selected])}\n        onSelectionChange={(keys) => {\n          if (keys !== \"all\") {\n            const newKey = Array.from(keys)[0] as string;\n            setSelected(newKey);\n          }\n        }}\n      >\n        <Menu.Trigger asChild>\n          <Button variant=\"outline\">Text Size: {selected}</Button>\n        </Menu.Trigger>\n        <Menu.Content>\n          <Menu.Section label=\"Choose Size\">\n            <Menu.Item id=\"small\">\n              <Text slot=\"label\">Small</Text>\n            </Menu.Item>\n            <Menu.Item id=\"medium\">\n              <Text slot=\"label\">Medium</Text>\n            </Menu.Item>\n            <Menu.Item id=\"large\">\n              <Text slot=\"label\">Large</Text>\n            </Menu.Item>\n          </Menu.Section>\n        </Menu.Content>\n      </Menu.Root>\n      <Text fontSize=\"sm\">Selected: {selected}</Text>\n    </Stack>\n  );\n}\n```\n\n### Multiple selection mode\n\nUse `selectionMode=\"multiple\"` for checkbox-like behavior:\n\n```jsx live-dev\nconst App = () => {\n  const [selected, setSelected] = useState<Set<string>>(new Set([\"bold\"]));\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Menu.Root\n        selectionMode=\"multiple\"\n        selectedKeys={selected}\n        onSelectionChange={(keys) => {\n          if (keys !== \"all\") {\n            setSelected(new Set(Array.from(keys) as string[]));\n          }\n        }}\n      >\n        <Menu.Trigger asChild>\n          <Button variant=\"outline\">Text Formatting</Button>\n        </Menu.Trigger>\n        <Menu.Content>\n          <Menu.Section label=\"Style Options\">\n            <Menu.Item id=\"bold\">\n              <Text slot=\"label\">Bold</Text>\n              <Kbd slot=\"keyboard\">⌘B</Kbd>\n            </Menu.Item>\n            <Menu.Item id=\"italic\">\n              <Text slot=\"label\">Italic</Text>\n              <Kbd slot=\"keyboard\">⌘I</Kbd>\n            </Menu.Item>\n            <Menu.Item id=\"underline\">\n              <Text slot=\"label\">Underline</Text>\n              <Kbd slot=\"keyboard\">⌘U</Kbd>\n            </Menu.Item>\n          </Menu.Section>\n        </Menu.Content>\n      </Menu.Root>\n      <Text fontSize=\"sm\">\n        Selected: {Array.from(selected).join(\", \") || \"None\"}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Submenus\n\nCreate nested menus using `Menu.SubmenuTrigger` and `Menu.Submenu`:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Settings</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"general\">\n        <Icon slot=\"icon\"><Icons.Settings /></Icon>\n        <Text slot=\"label\">General</Text>\n      </Menu.Item>\n      <Menu.SubmenuTrigger>\n        <Menu.Item>\n          <Icon slot=\"icon\"><Icons.AccountCircle /></Icon>\n          <Text slot=\"label\">Account</Text>\n          <Text slot=\"description\">Manage your account</Text>\n        </Menu.Item>\n        <Menu.Submenu>\n          <Menu.Item id=\"profile\">Profile</Menu.Item>\n          <Menu.Item id=\"security\">Security</Menu.Item>\n          <Menu.Item id=\"notifications\">Notifications</Menu.Item>\n        </Menu.Submenu>\n      </Menu.SubmenuTrigger>\n      <Menu.SubmenuTrigger>\n        <Menu.Item>\n          <Icon slot=\"icon\"><Icons.Palette /></Icon>\n          <Text slot=\"label\">Appearance</Text>\n        </Menu.Item>\n        <Menu.Submenu>\n          <Menu.Item id=\"theme\">Theme</Menu.Item>\n          <Menu.Item id=\"language\">Language</Menu.Item>\n        </Menu.Submenu>\n      </Menu.SubmenuTrigger>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Uncontrolled mode\n\nFor simpler use cases, use `defaultOpen` and `onOpenChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [lastAction, setLastAction] = useState<string>(\"None\");\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Menu.Root\n        onAction={(key) => setLastAction(key as string)}\n        onOpenChange={(isOpen) => console.log(\"Menu open:\", isOpen)}\n        placement=\"bottom end\"\n      >\n        <Menu.Trigger>Quick Actions</Menu.Trigger>\n        <Menu.Content>\n          <Menu.Item id=\"new\">New File</Menu.Item>\n          <Menu.Item id=\"open\">Open</Menu.Item>\n          <Menu.Item id=\"save\">Save</Menu.Item>\n        </Menu.Content>\n      </Menu.Root>\n      <Text fontSize=\"sm\">Last action: {lastAction}</Text>\n    </Stack>\n  );\n}\n```\n\n### Controlled mode\n\nFor programmatic control, use `isOpen` and `onOpenChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState<boolean>(false);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Menu.Root isOpen={isOpen} onOpenChange={setIsOpen}>\n        <Menu.Trigger>Controlled Menu</Menu.Trigger>\n        <Menu.Content>\n          <Menu.Item id=\"item1\">Item 1</Menu.Item>\n          <Menu.Item id=\"item2\">Item 2</Menu.Item>\n          <Menu.Item id=\"item3\">Item 3</Menu.Item>\n        </Menu.Content>\n      </Menu.Root>\n      <Button onClick={() => setIsOpen(!isOpen)}>\n        {isOpen ? \"Close\" : \"Open\"} Menu\n      </Button>\n      <Text fontSize=\"sm\">Menu is {isOpen ? \"open\" : \"closed\"}</Text>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Menu handles most accessibility requirements internally through React Aria. However, you must ensure proper labeling:\n\n- **For default triggers**: The trigger text serves as the accessible name\n- **For icon-only triggers**: Always provide `aria-label`:\n\n```tsx\n<Menu.Trigger asChild>\n  <IconButton aria-label=\"More options\">\n    <Icons.MoreVert />\n  </IconButton>\n</Menu.Trigger>\n```\n\n- **For custom triggers**: Ensure the trigger element has an accessible name\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-menu\";\n\nexport const Example = () => (\n  <Menu.Root id={PERSISTENT_ID}>\n    <Menu.Trigger>Actions</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"edit\">Edit</Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n\n- `Tab` / `Shift+Tab`: Navigate to/from the menu trigger\n- `Enter` / `Space`: Open the menu when trigger is focused\n- `Arrow Down` / `Arrow Up`: Navigate through menu items\n- `Arrow Right`: Open submenu (when focused on submenu trigger)\n- `Arrow Left`: Close submenu and return to parent menu\n- `Enter`: Select the focused item\n- `Space`: Toggle selection in selection modes\n- `Escape`: Close the menu\n- `Home` / `End`: Jump to first/last item\n- Type to search: Type characters to jump to matching items\n\n## API reference\n\n<PropsTable id=\"Menu\" />\n\n## Common patterns\n\n### Context menu for list items\n\nA common pattern for providing actions on list items:\n\n```jsx live-dev\nconst App = () => {\n  const items = [\n    { id: \"1\", name: \"Document A.pdf\" },\n    { id: \"2\", name: \"Spreadsheet B.xlsx\" },\n    { id: \"3\", name: \"Presentation C.pptx\" },\n  ];\n\n  const handleAction = (itemId, action) => {\n    alert(`${action} on ${itemId}`);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"200\">\n      {items.map((item) => (\n        <Box\n          key={item.id}\n          display=\"flex\"\n          justifyContent=\"space-between\"\n          alignItems=\"center\"\n          padding=\"300\"\n          borderRadius=\"200\"\n          bg=\"neutral.2\"\n        >\n          <Text>{item.name}</Text>\n          <Menu.Root onAction={(action) => handleAction(item.id, action)}>\n            <Menu.Trigger asChild>\n              <IconButton\n                variant=\"ghost\"\n                aria-label={`Actions for ${item.name}`}\n              >\n                <Icons.MoreVert />\n              </IconButton>\n            </Menu.Trigger>\n            <Menu.Content>\n              <Menu.Item id=\"open\">\n                <Icon slot=\"icon\"><Icons.FolderOpen /></Icon>\n                <Text slot=\"label\">Open</Text>\n              </Menu.Item>\n              <Menu.Item id=\"rename\">\n                <Icon slot=\"icon\"><Icons.Edit /></Icon>\n                <Text slot=\"label\">Rename</Text>\n              </Menu.Item>\n              <Menu.Item id=\"download\">\n                <Icon slot=\"icon\"><Icons.Download /></Icon>\n                <Text slot=\"label\">Download</Text>\n              </Menu.Item>\n              <Separator />\n              <Menu.Item id=\"delete\" isCritical>\n                <Icon slot=\"icon\"><Icons.Delete /></Icon>\n                <Text slot=\"label\">Delete</Text>\n              </Menu.Item>\n            </Menu.Content>\n          </Menu.Root>\n        </Box>\n      ))}\n    </Stack>\n  );\n}\n```\n\n### Dynamic menu items\n\nBuild menus from data arrays:\n\n```jsx live-dev\nconst App = () => {\n  const menuItems = [\n    { id: \"new\", label: \"New File\", icon: Icons.InsertDriveFile, kbd: \"⌘N\" },\n    { id: \"open\", label: \"Open\", icon: Icons.FolderOpen, kbd: \"⌘O\" },\n    { id: \"save\", label: \"Save\", icon: Icons.Save, kbd: \"⌘S\" },\n    { id: \"divider\" },\n    { id: \"delete\", label: \"Delete\", icon: Icons.Delete, critical: true },\n  ];\n\n  return (\n    <Menu.Root onAction={(key) => alert(`Action: ${key}`)}>\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">\n          <Icons.MoreVert />\n          File Menu\n        </Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        {menuItems.map((item) => {\n          if (item.id === \"divider\") {\n            return <Separator key={Math.random()} />;\n          }\n          return (\n            <Menu.Item key={item.id} id={item.id} isCritical={item.critical}>\n              {item.icon && (\n                <Icon slot=\"icon\"><item.icon /></Icon>\n              )}\n              <Text slot=\"label\">{item.label}</Text>\n              {item.kbd && <Kbd slot=\"keyboard\">{item.kbd}</Kbd>}\n            </Menu.Item>\n          );\n        })}\n      </Menu.Content>\n    </Menu.Root>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Menu 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 menu renders with expected elements\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Basic rendering\", () => {\n  it(\"renders menu trigger\", () => {\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\", { name: \"Actions\" })).toBeInTheDocument();\n  });\n\n  it(\"renders menu items when opened\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n            <Menu.Item id=\"delete\">Delete</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    expect(screen.getByRole(\"menuitem\", { name: \"Edit\" })).toBeInTheDocument();\n    expect(\n      screen.getByRole(\"menuitem\", { name: \"Delete\" })\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the menu\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Interactions\", () => {\n  it(\"opens menu on trigger click\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n  });\n\n  it(\"closes menu when item is selected\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"menuitem\", { name: \"Edit\" }));\n\n    expect(handleAction).toHaveBeenCalledWith(\"edit\");\n    await waitFor(() => {\n      expect(screen.queryByRole(\"menu\")).not.toBeInTheDocument();\n    });\n  });\n\n  it(\"closes menu on Escape key\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.keyboard(\"{Escape}\");\n\n    await waitFor(() => {\n      expect(screen.queryByRole(\"menu\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Action Callback Tests\n\nTest the onAction callback behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Action callback\", () => {\n  it(\"calls onAction with item id when clicked\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"copy\">Copy</Menu.Item>\n            <Menu.Item id=\"paste\">Paste</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"menuitem\", { name: \"Copy\" }));\n\n    expect(handleAction).toHaveBeenCalledWith(\"copy\");\n  });\n\n  it(\"calls onAction with Enter key\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"save\">Save</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // First item should have focus\n    await waitFor(() => {\n      expect(screen.getByRole(\"menuitem\", { name: \"Save\" })).toHaveFocus();\n    });\n\n    await user.keyboard(\"{Enter}\");\n\n    expect(handleAction).toHaveBeenCalledWith(\"save\");\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled open/close behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Controlled mode\", () => {\n  it(\"opens when isOpen is true\", async () => {\n    render(\n      <NimbusProvider>\n        <Menu.Root isOpen={true} onOpenChange={() => {}}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n  });\n\n  it(\"calls onOpenChange when menu is opened\", async () => {\n    const user = userEvent.setup();\n    const handleOpenChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root isOpen={false} onOpenChange={handleOpenChange}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    expect(handleOpenChange).toHaveBeenCalledWith(true);\n  });\n});\n```\n\n### Disabled Items Tests\n\nTest disabled item behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Disabled items\", () => {\n  it(\"renders disabled item with aria-disabled\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n            <Menu.Item id=\"paste\" isDisabled>\n              Paste\n            </Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    const disabledItem = screen.getByRole(\"menuitem\", { name: \"Paste\" });\n    expect(disabledItem).toHaveAttribute(\"aria-disabled\", \"true\");\n  });\n\n  it(\"does not call onAction for disabled items\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"paste\" isDisabled>\n              Paste\n            </Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // Disabled items have pointer-events: none, so click won't fire\n    // We verify the item is disabled\n    const disabledItem = screen.getByRole(\"menuitem\", { name: \"Paste\" });\n    expect(disabledItem).toHaveAttribute(\"aria-disabled\", \"true\");\n\n    // onAction should not have been called\n    expect(handleAction).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Selection Mode Tests\n\nTest single and multiple selection modes\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Selection mode\", () => {\n  it(\"renders radio items in single selection mode\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root selectionMode=\"single\" selectedKeys={new Set([\"medium\"])}>\n          <Menu.Trigger>Size</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"small\">Small</Menu.Item>\n            <Menu.Item id=\"medium\">Medium</Menu.Item>\n            <Menu.Item id=\"large\">Large</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Size\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // Items should be radio items in single selection mode\n    expect(\n      screen.getByRole(\"menuitemradio\", { name: \"Medium\" })\n    ).toHaveAttribute(\"data-selected\");\n  });\n\n  it(\"renders checkbox items in multiple selection mode\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root\n          selectionMode=\"multiple\"\n          selectedKeys={new Set([\"bold\", \"italic\"])}\n        >\n          <Menu.Trigger>Formatting</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"bold\">Bold</Menu.Item>\n            <Menu.Item id=\"italic\">Italic</Menu.Item>\n            <Menu.Item id=\"underline\">Underline</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Formatting\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // Items should be checkbox items in multiple selection mode\n    expect(\n      screen.getByRole(\"menuitemcheckbox\", { name: \"Bold\" })\n    ).toHaveAttribute(\"data-selected\");\n    expect(\n      screen.getByRole(\"menuitemcheckbox\", { name: \"Italic\" })\n    ).toHaveAttribute(\"data-selected\");\n    expect(\n      screen.getByRole(\"menuitemcheckbox\", { name: \"Underline\" })\n    ).not.toHaveAttribute(\"data-selected\");\n  });\n\n  it(\"calls onSelectionChange when selection changes\", async () => {\n    const user = userEvent.setup();\n    const handleSelectionChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root\n          selectionMode=\"single\"\n          selectedKeys={new Set([\"small\"])}\n          onSelectionChange={handleSelectionChange}\n        >\n          <Menu.Trigger>Size</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"small\">Small</Menu.Item>\n            <Menu.Item id=\"medium\">Medium</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Size\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"menuitemradio\", { name: \"Medium\" }));\n\n    expect(handleSelectionChange).toHaveBeenCalled();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-menu--docs)\n- [React Aria Menu](https://react-spectrum.adobe.com/react-aria/Menu.html)\n- [ARIA Menu Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/)\n",
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Menu, type MenuRootProps, type MenuItemProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation creates an action menu with items:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root onAction={(key) => alert(`Action: ${key}`)}>\n    <Menu.Trigger>Actions</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"edit\">Edit</Menu.Item>\n      <Menu.Item id=\"duplicate\">Duplicate</Menu.Item>\n      <Menu.Item id=\"delete\">Delete</Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n## Usage examples\n\n### Custom triggers\n\nUse `asChild` to render custom trigger elements like Button or IconButton:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Menu.Root>\n      <Menu.Trigger asChild>\n        <Button variant=\"solid\" colorPalette=\"primary\">\n          <Icons.KeyboardArrowDown />\n          Button Trigger\n        </Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"option1\">Option 1</Menu.Item>\n        <Menu.Item id=\"option2\">Option 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n\n    <Menu.Root>\n      <Menu.Trigger asChild>\n        <IconButton\n          variant=\"ghost\"\n          colorPalette=\"neutral\"\n          aria-label=\"More options\"\n        >\n          <Icons.MoreVert />\n        </IconButton>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"edit\">Edit</Menu.Item>\n        <Menu.Item id=\"delete\">Delete</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n  </Stack>\n)\n```\n\n### Menu placement\n\nControl where the menu appears relative to the trigger with the `placement` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Menu.Root placement=\"bottom start\">\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">Bottom Start</Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"1\">Item 1</Menu.Item>\n        <Menu.Item id=\"2\">Item 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n\n    <Menu.Root placement=\"bottom end\">\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">Bottom End</Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"1\">Item 1</Menu.Item>\n        <Menu.Item id=\"2\">Item 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n\n    <Menu.Root placement=\"right\">\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">Right</Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"1\">Item 1</Menu.Item>\n        <Menu.Item id=\"2\">Item 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n  </Stack>\n)\n```\n\n### Rich item content\n\nMenu items support icons, labels, descriptions, and keyboard shortcuts using slots:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Edit Menu</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"copy\">\n        <Icon slot=\"icon\"><Icons.ContentCopy /></Icon>\n        <Text slot=\"label\">Copy</Text>\n        <Text slot=\"description\">Copy to clipboard</Text>\n        <Kbd slot=\"keyboard\">⌘C</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"paste\">\n        <Icon slot=\"icon\"><Icons.ContentPaste /></Icon>\n        <Text slot=\"label\">Paste</Text>\n        <Text slot=\"description\">Paste from clipboard</Text>\n        <Kbd slot=\"keyboard\">⌘V</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"cut\">\n        <Icon slot=\"icon\"><Icons.ContentCut /></Icon>\n        <Text slot=\"label\">Cut</Text>\n        <Kbd slot=\"keyboard\">⌘X</Kbd>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Critical items\n\nUse `isCritical` to highlight destructive actions:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>File Actions</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"rename\">\n        <Icon slot=\"icon\"><Icons.Edit /></Icon>\n        <Text slot=\"label\">Rename</Text>\n      </Menu.Item>\n      <Menu.Item id=\"archive\">\n        <Icon slot=\"icon\"><Icons.Archive /></Icon>\n        <Text slot=\"label\">Archive</Text>\n      </Menu.Item>\n      <Separator />\n      <Menu.Item id=\"delete\" isCritical>\n        <Icon slot=\"icon\"><Icons.Delete /></Icon>\n        <Text slot=\"label\">Delete</Text>\n        <Text slot=\"description\">This action cannot be undone</Text>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Disabled items\n\nUse `isDisabled` on individual items to prevent interaction:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Edit</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"undo\">\n        <Text slot=\"label\">Undo</Text>\n        <Kbd slot=\"keyboard\">⌘Z</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"redo\" isDisabled>\n        <Text slot=\"label\">Redo</Text>\n        <Text slot=\"description\">Nothing to redo</Text>\n        <Kbd slot=\"keyboard\">⌘⇧Z</Kbd>\n      </Menu.Item>\n      <Separator />\n      <Menu.Item id=\"paste\" isDisabled>\n        <Text slot=\"label\">Paste</Text>\n        <Text slot=\"description\">Clipboard is empty</Text>\n        <Kbd slot=\"keyboard\">⌘V</Kbd>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Sections with labels\n\nGroup related items using `Menu.Section` with a label:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Application Menu</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Section label=\"File\">\n        <Menu.Item id=\"new\">New Document</Menu.Item>\n        <Menu.Item id=\"open\">Open</Menu.Item>\n        <Menu.Item id=\"save\">Save</Menu.Item>\n      </Menu.Section>\n      <Separator />\n      <Menu.Section label=\"Edit\">\n        <Menu.Item id=\"undo\">Undo</Menu.Item>\n        <Menu.Item id=\"redo\">Redo</Menu.Item>\n      </Menu.Section>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Single selection mode\n\nUse `selectionMode=\"single\"` for radio-button-like behavior within a section:\n\n```jsx live-dev\nconst App = () => {\n  const [selected, setSelected] = useState<string>(\"medium\");\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Menu.Root\n        selectionMode=\"single\"\n        selectedKeys={new Set([selected])}\n        onSelectionChange={(keys) => {\n          if (keys !== \"all\") {\n            const newKey = Array.from(keys)[0] as string;\n            setSelected(newKey);\n          }\n        }}\n      >\n        <Menu.Trigger asChild>\n          <Button variant=\"outline\">Text Size: {selected}</Button>\n        </Menu.Trigger>\n        <Menu.Content>\n          <Menu.Section label=\"Choose Size\">\n            <Menu.Item id=\"small\">\n              <Text slot=\"label\">Small</Text>\n            </Menu.Item>\n            <Menu.Item id=\"medium\">\n              <Text slot=\"label\">Medium</Text>\n            </Menu.Item>\n            <Menu.Item id=\"large\">\n              <Text slot=\"label\">Large</Text>\n            </Menu.Item>\n          </Menu.Section>\n        </Menu.Content>\n      </Menu.Root>\n      <Text fontSize=\"sm\">Selected: {selected}</Text>\n    </Stack>\n  );\n}\n```\n\n### Multiple selection mode\n\nUse `selectionMode=\"multiple\"` for checkbox-like behavior:\n\n```jsx live-dev\nconst App = () => {\n  const [selected, setSelected] = useState<Set<string>>(new Set([\"bold\"]));\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Menu.Root\n        selectionMode=\"multiple\"\n        selectedKeys={selected}\n        onSelectionChange={(keys) => {\n          if (keys !== \"all\") {\n            setSelected(new Set(Array.from(keys) as string[]));\n          }\n        }}\n      >\n        <Menu.Trigger asChild>\n          <Button variant=\"outline\">Text Formatting</Button>\n        </Menu.Trigger>\n        <Menu.Content>\n          <Menu.Section label=\"Style Options\">\n            <Menu.Item id=\"bold\">\n              <Text slot=\"label\">Bold</Text>\n              <Kbd slot=\"keyboard\">⌘B</Kbd>\n            </Menu.Item>\n            <Menu.Item id=\"italic\">\n              <Text slot=\"label\">Italic</Text>\n              <Kbd slot=\"keyboard\">⌘I</Kbd>\n            </Menu.Item>\n            <Menu.Item id=\"underline\">\n              <Text slot=\"label\">Underline</Text>\n              <Kbd slot=\"keyboard\">⌘U</Kbd>\n            </Menu.Item>\n          </Menu.Section>\n        </Menu.Content>\n      </Menu.Root>\n      <Text fontSize=\"sm\">\n        Selected: {Array.from(selected).join(\", \") || \"None\"}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Submenus\n\nCreate nested menus using `Menu.SubmenuTrigger` and `Menu.Submenu`:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Settings</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"general\">\n        <Icon slot=\"icon\"><Icons.Settings /></Icon>\n        <Text slot=\"label\">General</Text>\n      </Menu.Item>\n      <Menu.SubmenuTrigger>\n        <Menu.Item>\n          <Icon slot=\"icon\"><Icons.AccountCircle /></Icon>\n          <Text slot=\"label\">Account</Text>\n          <Text slot=\"description\">Manage your account</Text>\n        </Menu.Item>\n        <Menu.Submenu>\n          <Menu.Item id=\"profile\">Profile</Menu.Item>\n          <Menu.Item id=\"security\">Security</Menu.Item>\n          <Menu.Item id=\"notifications\">Notifications</Menu.Item>\n        </Menu.Submenu>\n      </Menu.SubmenuTrigger>\n      <Menu.SubmenuTrigger>\n        <Menu.Item>\n          <Icon slot=\"icon\"><Icons.Palette /></Icon>\n          <Text slot=\"label\">Appearance</Text>\n        </Menu.Item>\n        <Menu.Submenu>\n          <Menu.Item id=\"theme\">Theme</Menu.Item>\n          <Menu.Item id=\"language\">Language</Menu.Item>\n        </Menu.Submenu>\n      </Menu.SubmenuTrigger>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Uncontrolled mode\n\nFor simpler use cases, use `defaultOpen` and `onOpenChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [lastAction, setLastAction] = useState<string>(\"None\");\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Menu.Root\n        onAction={(key) => setLastAction(key as string)}\n        onOpenChange={(isOpen) => console.log(\"Menu open:\", isOpen)}\n        placement=\"bottom end\"\n      >\n        <Menu.Trigger>Quick Actions</Menu.Trigger>\n        <Menu.Content>\n          <Menu.Item id=\"new\">New File</Menu.Item>\n          <Menu.Item id=\"open\">Open</Menu.Item>\n          <Menu.Item id=\"save\">Save</Menu.Item>\n        </Menu.Content>\n      </Menu.Root>\n      <Text fontSize=\"sm\">Last action: {lastAction}</Text>\n    </Stack>\n  );\n}\n```\n\n### Controlled mode\n\nFor programmatic control, use `isOpen` and `onOpenChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState<boolean>(false);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Menu.Root isOpen={isOpen} onOpenChange={setIsOpen}>\n        <Menu.Trigger>Controlled Menu</Menu.Trigger>\n        <Menu.Content>\n          <Menu.Item id=\"item1\">Item 1</Menu.Item>\n          <Menu.Item id=\"item2\">Item 2</Menu.Item>\n          <Menu.Item id=\"item3\">Item 3</Menu.Item>\n        </Menu.Content>\n      </Menu.Root>\n      <Button onClick={() => setIsOpen(!isOpen)}>\n        {isOpen ? \"Close\" : \"Open\"} Menu\n      </Button>\n      <Text fontSize=\"sm\">Menu is {isOpen ? \"open\" : \"closed\"}</Text>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Menu handles most accessibility requirements internally through React Aria. However, you must ensure proper labeling:\n\n- **For default triggers**: The trigger text serves as the accessible name\n- **For icon-only triggers**: Always provide `aria-label`:\n\n```tsx\n<Menu.Trigger asChild>\n  <IconButton aria-label=\"More options\">\n    <Icons.MoreVert />\n  </IconButton>\n</Menu.Trigger>\n```\n\n- **For custom triggers**: Ensure the trigger element has an accessible name\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-menu\";\n\nexport const Example = () => (\n  <Menu.Root id={PERSISTENT_ID}>\n    <Menu.Trigger>Actions</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"edit\">Edit</Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n\n- `Tab` / `Shift+Tab`: Navigate to/from the menu trigger\n- `Enter` / `Space`: Open the menu when trigger is focused\n- `Arrow Down` / `Arrow Up`: Navigate through menu items\n- `Arrow Right`: Open submenu (when focused on submenu trigger)\n- `Arrow Left`: Close submenu and return to parent menu\n- `Enter`: Select the focused item\n- `Space`: Toggle selection in selection modes\n- `Escape`: Close the menu\n- `Home` / `End`: Jump to first/last item\n- Type to search: Type characters to jump to matching items\n\n## API reference\n\n<PropsTable id=\"Menu\" />\n\n## Common patterns\n\n### Context menu for list items\n\nA common pattern for providing actions on list items:\n\n```jsx live-dev\nconst App = () => {\n  const items = [\n    { id: \"1\", name: \"Document A.pdf\" },\n    { id: \"2\", name: \"Spreadsheet B.xlsx\" },\n    { id: \"3\", name: \"Presentation C.pptx\" },\n  ];\n\n  const handleAction = (itemId, action) => {\n    alert(`${action} on ${itemId}`);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"200\">\n      {items.map((item) => (\n        <Box\n          key={item.id}\n          display=\"flex\"\n          justifyContent=\"space-between\"\n          alignItems=\"center\"\n          padding=\"300\"\n          borderRadius=\"200\"\n          bg=\"neutral.2\"\n        >\n          <Text>{item.name}</Text>\n          <Menu.Root onAction={(action) => handleAction(item.id, action)}>\n            <Menu.Trigger asChild>\n              <IconButton\n                variant=\"ghost\"\n                aria-label={`Actions for ${item.name}`}\n              >\n                <Icons.MoreVert />\n              </IconButton>\n            </Menu.Trigger>\n            <Menu.Content>\n              <Menu.Item id=\"open\">\n                <Icon slot=\"icon\"><Icons.FolderOpen /></Icon>\n                <Text slot=\"label\">Open</Text>\n              </Menu.Item>\n              <Menu.Item id=\"rename\">\n                <Icon slot=\"icon\"><Icons.Edit /></Icon>\n                <Text slot=\"label\">Rename</Text>\n              </Menu.Item>\n              <Menu.Item id=\"download\">\n                <Icon slot=\"icon\"><Icons.Download /></Icon>\n                <Text slot=\"label\">Download</Text>\n              </Menu.Item>\n              <Separator />\n              <Menu.Item id=\"delete\" isCritical>\n                <Icon slot=\"icon\"><Icons.Delete /></Icon>\n                <Text slot=\"label\">Delete</Text>\n              </Menu.Item>\n            </Menu.Content>\n          </Menu.Root>\n        </Box>\n      ))}\n    </Stack>\n  );\n}\n```\n\n### Dynamic menu items\n\nBuild menus from data arrays:\n\n```jsx live-dev\nconst App = () => {\n  const menuItems = [\n    { id: \"new\", label: \"New File\", icon: Icons.InsertDriveFile, kbd: \"⌘N\" },\n    { id: \"open\", label: \"Open\", icon: Icons.FolderOpen, kbd: \"⌘O\" },\n    { id: \"save\", label: \"Save\", icon: Icons.Save, kbd: \"⌘S\" },\n    { id: \"divider\" },\n    { id: \"delete\", label: \"Delete\", icon: Icons.Delete, critical: true },\n  ];\n\n  return (\n    <Menu.Root onAction={(key) => alert(`Action: ${key}`)}>\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">\n          <Icons.MoreVert />\n          File Menu\n        </Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        {menuItems.map((item) => {\n          if (item.id === \"divider\") {\n            return <Separator key={Math.random()} />;\n          }\n          return (\n            <Menu.Item key={item.id} id={item.id} isCritical={item.critical}>\n              {item.icon && (\n                <Icon slot=\"icon\"><item.icon /></Icon>\n              )}\n              <Text slot=\"label\">{item.label}</Text>\n              {item.kbd && <Kbd slot=\"keyboard\">{item.kbd}</Kbd>}\n            </Menu.Item>\n          );\n        })}\n      </Menu.Content>\n    </Menu.Root>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Menu 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 menu renders with expected elements\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Basic rendering\", () => {\n  it(\"renders menu trigger\", () => {\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\", { name: \"Actions\" })).toBeInTheDocument();\n  });\n\n  it(\"renders menu items when opened\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n            <Menu.Item id=\"delete\">Delete</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    expect(screen.getByRole(\"menuitem\", { name: \"Edit\" })).toBeInTheDocument();\n    expect(\n      screen.getByRole(\"menuitem\", { name: \"Delete\" })\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the menu\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Interactions\", () => {\n  it(\"opens menu on trigger click\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n  });\n\n  it(\"closes menu when item is selected\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"menuitem\", { name: \"Edit\" }));\n\n    expect(handleAction).toHaveBeenCalledWith(\"edit\", undefined);\n    await waitFor(() => {\n      expect(screen.queryByRole(\"menu\")).not.toBeInTheDocument();\n    });\n  });\n\n  it(\"closes menu on Escape key\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.keyboard(\"{Escape}\");\n\n    await waitFor(() => {\n      expect(screen.queryByRole(\"menu\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Action Callback Tests\n\nTest the onAction callback behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Action callback\", () => {\n  it(\"calls onAction with item id when clicked\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"copy\">Copy</Menu.Item>\n            <Menu.Item id=\"paste\">Paste</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"menuitem\", { name: \"Copy\" }));\n\n    expect(handleAction).toHaveBeenCalledWith(\"copy\", undefined);\n  });\n\n  it(\"calls onAction with Enter key\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"save\">Save</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // First item should have focus\n    await waitFor(() => {\n      expect(screen.getByRole(\"menuitem\", { name: \"Save\" })).toHaveFocus();\n    });\n\n    await user.keyboard(\"{Enter}\");\n\n    expect(handleAction).toHaveBeenCalledWith(\"save\", undefined);\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled open/close behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Controlled mode\", () => {\n  it(\"opens when isOpen is true\", async () => {\n    render(\n      <NimbusProvider>\n        <Menu.Root isOpen={true} onOpenChange={() => {}}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n  });\n\n  it(\"calls onOpenChange when menu is opened\", async () => {\n    const user = userEvent.setup();\n    const handleOpenChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root isOpen={false} onOpenChange={handleOpenChange}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    expect(handleOpenChange).toHaveBeenCalledWith(true);\n  });\n});\n```\n\n### Disabled Items Tests\n\nTest disabled item behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Disabled items\", () => {\n  it(\"renders disabled item with aria-disabled\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n            <Menu.Item id=\"paste\" isDisabled>\n              Paste\n            </Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    const disabledItem = screen.getByRole(\"menuitem\", { name: \"Paste\" });\n    expect(disabledItem).toHaveAttribute(\"aria-disabled\", \"true\");\n  });\n\n  it(\"does not call onAction for disabled items\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"paste\" isDisabled>\n              Paste\n            </Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // Disabled items have pointer-events: none, so click won't fire\n    // We verify the item is disabled\n    const disabledItem = screen.getByRole(\"menuitem\", { name: \"Paste\" });\n    expect(disabledItem).toHaveAttribute(\"aria-disabled\", \"true\");\n\n    // onAction should not have been called\n    expect(handleAction).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Selection Mode Tests\n\nTest single and multiple selection modes\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Selection mode\", () => {\n  it(\"renders radio items in single selection mode\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root selectionMode=\"single\" selectedKeys={new Set([\"medium\"])}>\n          <Menu.Trigger>Size</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"small\">Small</Menu.Item>\n            <Menu.Item id=\"medium\">Medium</Menu.Item>\n            <Menu.Item id=\"large\">Large</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Size\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // Items should be radio items in single selection mode\n    expect(\n      screen.getByRole(\"menuitemradio\", { name: \"Medium\" })\n    ).toHaveAttribute(\"data-selected\");\n  });\n\n  it(\"renders checkbox items in multiple selection mode\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root\n          selectionMode=\"multiple\"\n          selectedKeys={new Set([\"bold\", \"italic\"])}\n        >\n          <Menu.Trigger>Formatting</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"bold\">Bold</Menu.Item>\n            <Menu.Item id=\"italic\">Italic</Menu.Item>\n            <Menu.Item id=\"underline\">Underline</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Formatting\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // Items should be checkbox items in multiple selection mode\n    expect(\n      screen.getByRole(\"menuitemcheckbox\", { name: \"Bold\" })\n    ).toHaveAttribute(\"data-selected\");\n    expect(\n      screen.getByRole(\"menuitemcheckbox\", { name: \"Italic\" })\n    ).toHaveAttribute(\"data-selected\");\n    expect(\n      screen.getByRole(\"menuitemcheckbox\", { name: \"Underline\" })\n    ).not.toHaveAttribute(\"data-selected\");\n  });\n\n  it(\"calls onSelectionChange when selection changes\", async () => {\n    const user = userEvent.setup();\n    const handleSelectionChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root\n          selectionMode=\"single\"\n          selectedKeys={new Set([\"small\"])}\n          onSelectionChange={handleSelectionChange}\n        >\n          <Menu.Trigger>Size</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"small\">Small</Menu.Item>\n            <Menu.Item id=\"medium\">Medium</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Size\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"menuitemradio\", { name: \"Medium\" }));\n\n    expect(handleSelectionChange).toHaveBeenCalled();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-menu--docs)\n- [React Aria Menu](https://react-spectrum.adobe.com/react-aria/Menu.html)\n- [ARIA Menu Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/)\n",
       "toc": [
         {
           "value": "Getting started",

package/data/docs/routes/components-navigation-tabnav.json

@@ -61,6 +61,28 @@
         ],
         "parent": "root"
       },
+      {
+        "value": "Variants",
+        "href": "#variants",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Animated highlight",
+        "href": "#animated-highlight",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
       {
         "value": "Active item",
         "href": "#active-item",
@@ -68,7 +90,7 @@
         "numbering": [
           1,
           2,
-          2
+          4
         ],
         "parent": "root"
       },
@@ -79,7 +101,7 @@
         "numbering": [
           1,
           2,
-          3
+          5
         ],
         "parent": "root"
       },
@@ -90,7 +112,7 @@
         "numbering": [
           1,
           2,
-          4
+          6
         ],
         "parent": "root"
       }
@@ -114,10 +136,10 @@
       }
     ]
   },
-  "mdx": "\n## Overview\n\nTabNav provides tab-styled navigation links for route-based page navigation.\nUnlike `Tabs`, which switch content panels within the same page, `TabNav` renders\na `<nav>` landmark containing `<a>` anchor elements that link to distinct routes.\nEach item behaves as a standard link, and the active item is identified with\n`aria-current=\"page\"`.\n\nUse `TabNav` in page headers where each item links to a different URL (e.g.,\n`/orders/123/general`, `/orders/123/items`).\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Sizes\n\n`TabNav` supports three size variants — `sm`, `md` (default), and `lg` — that\ncontrol font size and padding on each item.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    {[\"sm\", \"md\", \"lg\"].map((size) => (\n      <Stack key={size} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{size}</Text>\n        <TabNav.Root aria-label={`Order navigation (${size})`} size={size}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This renders `aria-current=\"page\"`\non the anchor, which screen readers announce as \"current page\" and which applies\nthe active underline style.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### Disabled item\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible.\nDisabled items are visually dimmed and excluded from the tab sequence.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### With icons\n\nTab items support inline icons alongside text via the built-in flex gap layout.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n",
+  "mdx": "\n## Overview\n\nTabNav provides tab-styled navigation links for route-based page navigation.\nUnlike `Tabs`, which switch content panels within the same page, `TabNav` renders\na `<nav>` landmark containing `<a>` anchor elements that link to distinct routes.\nEach item behaves as a standard link, and the active item is identified with\n`aria-current=\"page\"`.\n\nUse `TabNav` in page headers where each item links to a different URL (e.g.,\n`/orders/123/general`, `/orders/123/items`).\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Sizes\n\n`TabNav` supports three size variants — `sm`, `md` (default), and `lg` — that\ncontrol font size and padding on each item.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    {[\"sm\", \"md\", \"lg\"].map((size) => (\n      <Stack key={size} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{size}</Text>\n        <TabNav.Root aria-label={`Order navigation (${size})`} size={size}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Variants\n\n`TabNav` ships with three visual variants:\n\n- **`line`** (default) — an underline strip beneath the active item.\n- **`rounded`** — a soft rounded-rect highlight behind the active item.\n- **`pill`** — a fully-rounded capsule highlight behind the active item.\n\nThe `rounded` and `pill` variants drop the baseline and add a small gap\nbetween items. Their active highlight is themeable via `colorPalette` (it\ndefaults to `primary`).\n\nThe active highlight always slides smoothly between items as the active item\nchanges — a single sliding indicator rather than a static per-item highlight.\nThe motion automatically respects `prefers-reduced-motion: reduce`: when reduced\nmotion is requested, the highlight snaps into place instead of sliding.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    {[\"line\", \"rounded\", \"pill\"].map((variant) => (\n      <Stack key={variant} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{variant}</Text>\n        <TabNav.Root aria-label={`Order navigation (${variant})`} variant={variant}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Animated highlight\n\nThe active highlight slides between items whenever the active item changes (an\nunderline bar for `line`, a filled highlight for `rounded`/`pill`) — no prop\nrequired. The slide respects `prefers-reduced-motion: reduce` (the highlight\nsnaps into place), and `aria-current`, focus, and keyboard order are unaffected.\n\n```jsx live\nconst App = () => {\n  const items = [\n    { href: \"/orders/123/general\", label: \"General\" },\n    { href: \"/orders/123/items\", label: \"Items\" },\n    { href: \"/orders/123/shipping\", label: \"Shipping\" },\n  ];\n  const [activePath, setActivePath] = React.useState(items[0].href);\n  return (\n    <TabNav.Root aria-label=\"Order navigation\" variant=\"rounded\">\n      {items.map((item) => (\n        <TabNav.Item\n          key={item.href}\n          href={item.href}\n          isCurrent={activePath === item.href}\n          onClick={(e) => {\n            e.preventDefault();\n            setActivePath(item.href);\n          }}\n        >\n          {item.label}\n        </TabNav.Item>\n      ))}\n    </TabNav.Root>\n  );\n}\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This renders `aria-current=\"page\"`\non the anchor, which screen readers announce as \"current page\" and which applies\nthe active underline style.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### Disabled item\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible.\nDisabled items are visually dimmed and excluded from the tab sequence.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### With icons\n\nTab items support inline icons alongside text via the built-in flex gap layout.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n",
   "views": {
     "overview": {
-      "mdx": "\n## Overview\n\nTabNav provides tab-styled navigation links for route-based page navigation.\nUnlike `Tabs`, which switch content panels within the same page, `TabNav` renders\na `<nav>` landmark containing `<a>` anchor elements that link to distinct routes.\nEach item behaves as a standard link, and the active item is identified with\n`aria-current=\"page\"`.\n\nUse `TabNav` in page headers where each item links to a different URL (e.g.,\n`/orders/123/general`, `/orders/123/items`).\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Sizes\n\n`TabNav` supports three size variants — `sm`, `md` (default), and `lg` — that\ncontrol font size and padding on each item.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    {[\"sm\", \"md\", \"lg\"].map((size) => (\n      <Stack key={size} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{size}</Text>\n        <TabNav.Root aria-label={`Order navigation (${size})`} size={size}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This renders `aria-current=\"page\"`\non the anchor, which screen readers announce as \"current page\" and which applies\nthe active underline style.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### Disabled item\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible.\nDisabled items are visually dimmed and excluded from the tab sequence.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### With icons\n\nTab items support inline icons alongside text via the built-in flex gap layout.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n",
+      "mdx": "\n## Overview\n\nTabNav provides tab-styled navigation links for route-based page navigation.\nUnlike `Tabs`, which switch content panels within the same page, `TabNav` renders\na `<nav>` landmark containing `<a>` anchor elements that link to distinct routes.\nEach item behaves as a standard link, and the active item is identified with\n`aria-current=\"page\"`.\n\nUse `TabNav` in page headers where each item links to a different URL (e.g.,\n`/orders/123/general`, `/orders/123/items`).\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n\n## Variables\n\nGet familiar with the features.\n\n### Sizes\n\n`TabNav` supports three size variants — `sm`, `md` (default), and `lg` — that\ncontrol font size and padding on each item.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    {[\"sm\", \"md\", \"lg\"].map((size) => (\n      <Stack key={size} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{size}</Text>\n        <TabNav.Root aria-label={`Order navigation (${size})`} size={size}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Variants\n\n`TabNav` ships with three visual variants:\n\n- **`line`** (default) — an underline strip beneath the active item.\n- **`rounded`** — a soft rounded-rect highlight behind the active item.\n- **`pill`** — a fully-rounded capsule highlight behind the active item.\n\nThe `rounded` and `pill` variants drop the baseline and add a small gap\nbetween items. Their active highlight is themeable via `colorPalette` (it\ndefaults to `primary`).\n\nThe active highlight always slides smoothly between items as the active item\nchanges — a single sliding indicator rather than a static per-item highlight.\nThe motion automatically respects `prefers-reduced-motion: reduce`: when reduced\nmotion is requested, the highlight snaps into place instead of sliding.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    {[\"line\", \"rounded\", \"pill\"].map((variant) => (\n      <Stack key={variant} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"600\">{variant}</Text>\n        <TabNav.Root aria-label={`Order navigation (${variant})`} variant={variant}>\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n)\n```\n\n### Animated highlight\n\nThe active highlight slides between items whenever the active item changes (an\nunderline bar for `line`, a filled highlight for `rounded`/`pill`) — no prop\nrequired. The slide respects `prefers-reduced-motion: reduce` (the highlight\nsnaps into place), and `aria-current`, focus, and keyboard order are unaffected.\n\n```jsx live\nconst App = () => {\n  const items = [\n    { href: \"/orders/123/general\", label: \"General\" },\n    { href: \"/orders/123/items\", label: \"Items\" },\n    { href: \"/orders/123/shipping\", label: \"Shipping\" },\n  ];\n  const [activePath, setActivePath] = React.useState(items[0].href);\n  return (\n    <TabNav.Root aria-label=\"Order navigation\" variant=\"rounded\">\n      {items.map((item) => (\n        <TabNav.Item\n          key={item.href}\n          href={item.href}\n          isCurrent={activePath === item.href}\n          onClick={(e) => {\n            e.preventDefault();\n            setActivePath(item.href);\n          }}\n        >\n          {item.label}\n        </TabNav.Item>\n      ))}\n    </TabNav.Root>\n  );\n}\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This renders `aria-current=\"page\"`\non the anchor, which screen readers announce as \"current page\" and which applies\nthe active underline style.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### Disabled item\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible.\nDisabled items are visually dimmed and excluded from the tab sequence.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### With icons\n\nTab items support inline icons alongside text via the built-in flex gap layout.\n\n```jsx live\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n)\n```\n",
       "toc": [
         {
           "value": "Overview",
@@ -161,6 +183,28 @@
           ],
           "parent": "root"
         },
+        {
+          "value": "Variants",
+          "href": "#variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Animated highlight",
+          "href": "#animated-highlight",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
         {
           "value": "Active item",
           "href": "#active-item",
@@ -168,7 +212,7 @@
           "numbering": [
             1,
             2,
-            2
+            4
           ],
           "parent": "root"
         },
@@ -179,7 +223,7 @@
           "numbering": [
             1,
             2,
-            3
+            5
           ],
           "parent": "root"
         },
@@ -190,7 +234,7 @@
           "numbering": [
             1,
             2,
-            4
+            6
           ],
           "parent": "root"
         }
@@ -223,7 +267,7 @@
       ]
     },
     "dev": {
-      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { TabNav, type TabNavProps, type TabNavItemProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\n`TabNav` is a compound component for **page-level route-based navigation** that renders a `<nav>` landmark containing `<a>` anchor elements. The active item is identified with `aria-current=\"page\"`.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## TabNav vs Tabs\n\n`TabNav` and `Tabs` look similar but serve fundamentally different purposes:\n\n| | `TabNav` | `Tabs` |\n|---|---|---|\n| **Use case** | Page-level navigation between routes | Switching content panels within a page |\n| **HTML semantics** | `<nav>` + `<a>` | `role=\"tablist\"` + `role=\"tab\"` |\n| **Active state** | `aria-current=\"page\"` | `aria-selected=\"true\"` |\n| **Keyboard** | Sequential Tab key | Arrow keys (roving tabindex) |\n| **Content** | No panel — content managed by router | Owns associated `TabPanel` |\n| **URL** | Always (`href` required) | Optional (`href` prop) |\n\nBoth `TabNav` and `Tabs` support client-side routing — the deciding factor is whether the component owns its content panels or delegates to the router. Use `TabNav` when each item navigates to a different route and the router manages what's rendered. Use `Tabs` when the content lives alongside the tab list.\n\n## Usage examples\n\n### Client-side view switching\n\nThe most common TabNav pattern: a persistent nav bar where clicking an item swaps the visible content without a full page reload. In a real app, `isCurrent` is derived from the router and the `href` triggers a route change. The example below simulates this with local state to show the interaction.\n\n```jsx live-dev\nconst items = [\n  { href: '/orders/123/general', label: 'General' },\n  { href: '/orders/123/items', label: 'Items' },\n  { href: '/orders/123/shipping', label: 'Shipping' },\n];\n\nconst content = {\n  '/orders/123/general': 'General settings and order details.',\n  '/orders/123/items': 'Line items and quantities.',\n  '/orders/123/shipping': 'Shipping address and carrier information.',\n};\n\nconst App = () => {\n  const [activePath, setActivePath] = React.useState(items[0].href);\n\n  return (\n    <Stack gap=\"400\">\n      <TabNav.Root aria-label=\"Order navigation\">\n        {items.map((item) => (\n          <TabNav.Item\n            key={item.href}\n            href={item.href}\n            isCurrent={activePath === item.href}\n            onClick={(e) => { e.preventDefault(); setActivePath(item.href); }}\n          >\n            {item.label}\n          </TabNav.Item>\n        ))}\n      </TabNav.Root>\n      <Box padding=\"400\">{content[activePath]}</Box>\n    </Stack>\n  );\n};\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This sets `aria-current=\"page\"` on the anchor element, which screen readers announce as \"current page\".\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n);\n```\n\nWhen using a client-side router, set `isCurrent` based on the active route:\n\n```tsx\nimport { useLocation } from 'react-router-dom';\n\nconst OrderNav = ({ orderId }: { orderId: string }) => {\n  const { pathname } = useLocation();\n\n  return (\n    <TabNav.Root aria-label=\"Order navigation\">\n      <TabNav.Item\n        href={`/orders/${orderId}/general`}\n        isCurrent={pathname.endsWith('/general')}\n      >\n        General\n      </TabNav.Item>\n      <TabNav.Item\n        href={`/orders/${orderId}/items`}\n        isCurrent={pathname.endsWith('/items')}\n      >\n        Items\n      </TabNav.Item>\n    </TabNav.Root>\n  );\n};\n```\n\n### Size variants\n\nThe `size` prop controls font size and padding. Available sizes: `sm`, `md` (default), `lg`.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Small</Text>\n      <TabNav.Root aria-label=\"Navigation (sm)\" size=\"sm\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Medium (default)</Text>\n      <TabNav.Root aria-label=\"Navigation (md)\" size=\"md\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Large</Text>\n      <TabNav.Root aria-label=\"Navigation (lg)\" size=\"lg\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n  </Stack>\n);\n```\n\n### Disabled items\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible. Disabled items are visually dimmed, removed from the tab sequence, and their `href` is stripped.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### External links\n\nUse `target` and `rel` to open a navigation item in a new browser tab. Always pair `target=\"_blank\"` with `rel=\"noopener noreferrer\"` for security.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item\n      href=\"https://docs.example.com/orders\"\n      target=\"_blank\"\n      rel=\"noopener noreferrer\"\n    >\n      Docs ↗\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### With icons\n\nTab items support inline icons alongside text via the `gap` built into the item layout.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## Component requirements\n\n### Accessibility\n\nThe TabNav component uses semantic HTML for navigation — it does not use ARIA roles for the tablist pattern. Accessibility is handled natively by the browser's `<nav>` landmark and `<a>` anchor semantics. `TabNav.Item` uses `useLink` from React Aria for consistent interaction handling.\n\n#### Role\n\n- `TabNav.Root` renders a `<nav>` HTML element — a navigation landmark, **not** `role=\"tablist\"`\n- `TabNav.Item` renders an `<a>` HTML element with the implicit `link` role — **not** `role=\"tab\"`\n- The active item uses `aria-current=\"page\"` — **not** `aria-selected`\n\n#### Labeling\n\nAlways provide an `aria-label` on `TabNav.Root` to describe the navigation region. This is especially important when a page contains multiple `<nav>` landmarks.\n\n```tsx\n<TabNav.Root aria-label=\"Order navigation\">\n  ...\n</TabNav.Root>\n```\n\n#### Keyboard navigation\n\nTabNav uses standard sequential keyboard navigation — no roving tabindex, no arrow key cycling.\n\n| Key | Action |\n|-----|--------|\n| `Tab` | Move focus to the next link |\n| `Shift + Tab` | Move focus to the previous link |\n| `Enter` | Activate the focused link |\n\nArrow keys (`ArrowRight`, `ArrowLeft`) do **not** move focus between items. This is intentional — TabNav is a `<nav>` with standard anchor links, not a `role=\"tablist\"` widget.\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:\n\n```tsx\nconst PERSISTENT_ID = \"order-detail-tab-nav\";\n\nexport const OrderTabNav = ({ orderId }: { orderId: string }) => (\n  <TabNav.Root id={PERSISTENT_ID} aria-label=\"Order navigation\">\n    <TabNav.Item href={`/orders/${orderId}/general`} isCurrent>\n      General\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## API reference\n\n<PropsTable id=\"TabNav\" />\n\n## Common patterns\n\n### Syncing active item with router\n\nIn most routing setups you derive `isCurrent` from the current URL rather than managing it in state.\n\n```tsx\n// React Router v6\nimport { useMatch } from 'react-router-dom';\n\nconst OrderNav = ({ orderId }: { orderId: string }) => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item\n      href={`/orders/${orderId}/general`}\n      isCurrent={!!useMatch(`/orders/${orderId}/general`)}\n    >\n      General\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/items`}\n      isCurrent={!!useMatch(`/orders/${orderId}/items`)}\n    >\n      Items\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/shipping`}\n      isCurrent={!!useMatch(`/orders/${orderId}/shipping`)}\n    >\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### Conditionally disabling items\n\nDisable items based on permissions or loading state rather than hiding them — this preserves the layout and communicates to users that the section exists.\n\n```tsx\nconst OrderNav = ({ orderId, canViewShipping }: { orderId: string; canViewShipping: boolean }) => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href={`/orders/${orderId}/general`} isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/shipping`}\n      isDisabled={!canViewShipping}\n    >\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using TabNav 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 TabNav component renders a nav landmark with anchor links\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Basic rendering\", () => {\n  it(\"renders a navigation landmark with links\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"navigation\", { name: \"Order navigation\" })\n    ).toBeInTheDocument();\n    expect(screen.getAllByRole(\"link\")).toHaveLength(3);\n  });\n\n  it(\"renders items as anchor elements with correct href\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveAttribute(\n      \"href\",\n      \"/orders/123/general\"\n    );\n    expect(screen.getByRole(\"link\", { name: \"Items\" })).toHaveAttribute(\n      \"href\",\n      \"/orders/123/items\"\n    );\n  });\n});\n```\n\n### Active Item Tests\n\nVerify aria-current=\"page\" is applied correctly to the active navigation item\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Active item\", () => {\n  it(\"sets aria-current='page' on the active item\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveAttribute(\n      \"aria-current\",\n      \"page\"\n    );\n  });\n\n  it(\"does not set aria-current on inactive items\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"Items\" })).not.toHaveAttribute(\n      \"aria-current\"\n    );\n    expect(screen.getByRole(\"link\", { name: \"Shipping\" })).not.toHaveAttribute(\n      \"aria-current\"\n    );\n  });\n\n  it(\"does not use aria-selected (navigation, not widget)\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).not.toHaveAttribute(\n      \"aria-selected\"\n    );\n  });\n});\n```\n\n### Disabled Item Tests\n\nVerify disabled items are marked inaccessible and removed from tab order\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Disabled items\", () => {\n  it(\"marks disabled items with aria-disabled='true'\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n            Shipping\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    const disabledItem = screen.getByRole(\"link\", { name: \"Shipping\" });\n    expect(disabledItem).toHaveAttribute(\"aria-disabled\", \"true\");\n  });\n\n  it(\"disabled items have no tabIndex (excluded from tab sequence by browser)\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n            Shipping\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    // React Aria sets no tabIndex on the disabled anchor — the browser excludes it\n    const disabledItem = screen.getByRole(\"link\", { name: \"Shipping\" });\n    expect(disabledItem).not.toHaveAttribute(\"tabindex\");\n  });\n});\n```\n\n### External Link Tests\n\nVerify target and rel attributes for external navigation items\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - External links\", () => {\n  it(\"applies target and rel to external link items\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item\n            href=\"https://docs.example.com\"\n            target=\"_blank\"\n            rel=\"noopener noreferrer\"\n          >\n            Docs ↗\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    const externalLink = screen.getByRole(\"link\", { name: \"Docs ↗\" });\n    expect(externalLink).toHaveAttribute(\"target\", \"_blank\");\n    expect(externalLink).toHaveAttribute(\"rel\", \"noopener noreferrer\");\n  });\n});\n```\n\n### Interaction Tests\n\nVerify click handling and keyboard activation\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Interactions\", () => {\n  it(\"calls onClick handler when a link is clicked\", async () => {\n    const user = userEvent.setup();\n    const handleClick = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" onClick={handleClick}>\n            General\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"link\", { name: \"General\" }));\n    expect(handleClick).toHaveBeenCalled();\n  });\n\n  it(\"is focusable with Tab key\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    await user.tab();\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveFocus();\n  });\n});\n```\n\n### Accessibility Tests\n\nVerify accessible labels and ID support\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Accessibility\", () => {\n  it(\"supports aria-label on the root for landmark identification\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"navigation\", { name: \"Order navigation\" })\n    ).toBeInTheDocument();\n  });\n\n  it(\"supports a persistent id on the root for tracking\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root id=\"order-tab-nav\" aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"navigation\")).toHaveAttribute(\n      \"id\",\n      \"order-tab-nav\"\n    );\n  });\n});\n```\n\n\n## Resources\n\n- [React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n- [ARIA: navigation landmark](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role)\n- [aria-current attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)\n- [Tabs](/components/navigation/tabs) — use when switching content panels on the same page\n",
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { TabNav, type TabNavProps, type TabNavItemProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\n`TabNav` is a compound component for **page-level route-based navigation** that renders a `<nav>` landmark containing `<a>` anchor elements. The active item is identified with `aria-current=\"page\"`.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## TabNav vs Tabs\n\n`TabNav` and `Tabs` look similar but serve fundamentally different purposes:\n\n| | `TabNav` | `Tabs` |\n|---|---|---|\n| **Use case** | Page-level navigation between routes | Switching content panels within a page |\n| **HTML semantics** | `<nav>` + `<a>` | `role=\"tablist\"` + `role=\"tab\"` |\n| **Active state** | `aria-current=\"page\"` | `aria-selected=\"true\"` |\n| **Keyboard** | Sequential Tab key | Arrow keys (roving tabindex) |\n| **Content** | No panel — content managed by router | Owns associated `TabPanel` |\n| **URL** | Always (`href` required) | Optional (`href` prop) |\n\nBoth `TabNav` and `Tabs` support client-side routing — the deciding factor is whether the component owns its content panels or delegates to the router. Use `TabNav` when each item navigates to a different route and the router manages what's rendered. Use `Tabs` when the content lives alongside the tab list.\n\n## Usage examples\n\n### Client-side view switching\n\nThe most common TabNav pattern: a persistent nav bar where clicking an item swaps the visible content without a full page reload. In a real app, `isCurrent` is derived from the router and the `href` triggers a route change. The example below simulates this with local state to show the interaction.\n\n```jsx live-dev\nconst items = [\n  { href: '/orders/123/general', label: 'General' },\n  { href: '/orders/123/items', label: 'Items' },\n  { href: '/orders/123/shipping', label: 'Shipping' },\n];\n\nconst content = {\n  '/orders/123/general': 'General settings and order details.',\n  '/orders/123/items': 'Line items and quantities.',\n  '/orders/123/shipping': 'Shipping address and carrier information.',\n};\n\nconst App = () => {\n  const [activePath, setActivePath] = React.useState(items[0].href);\n\n  return (\n    <Stack gap=\"400\">\n      <TabNav.Root aria-label=\"Order navigation\">\n        {items.map((item) => (\n          <TabNav.Item\n            key={item.href}\n            href={item.href}\n            isCurrent={activePath === item.href}\n            onClick={(e) => { e.preventDefault(); setActivePath(item.href); }}\n          >\n            {item.label}\n          </TabNav.Item>\n        ))}\n      </TabNav.Root>\n      <Box padding=\"400\">{content[activePath]}</Box>\n    </Stack>\n  );\n};\n```\n\n### Variants\n\nThe `variant` prop controls the visual style. Available variants: `line` (default), `rounded`, `pill`. (`Tabs` exposes the same three variants.)\n\n- **`line`** — an underline strip beneath the active item (visually twinned with the `Tabs` `line` variant).\n- **`rounded`** — a soft rounded-rect highlight behind the active item.\n- **`pill`** — a fully-rounded capsule highlight behind the active item.\n\nThe `rounded` and `pill` variants drop the baseline, add a small gap between items, and drive their active highlight off `colorPalette` (defaulting to `primary`), so they theme with the surrounding palette.\n\nThe legacy `tabs` variant name is accepted as a deprecated alias for `line`.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    {['line', 'rounded', 'pill'].map((variant) => (\n      <Stack key={variant} direction=\"column\" gap=\"300\">\n        <Text fontWeight=\"500\">{variant}</Text>\n        <TabNav.Root aria-label={`Navigation (${variant})`} variant={variant}>\n          <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n          <TabNav.Item href=\"/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </Stack>\n    ))}\n  </Stack>\n);\n```\n\n### Animated highlight\n\nThe active highlight always slides between items as the active item changes — a single indicator instead of a static per-item highlight. It adapts to the variant: a sliding underline bar for `line`, and a sliding filled highlight for `rounded`/`pill`. No prop is required.\n\nThe indicator is an `aria-hidden`, non-focusable element, so `aria-current`, focus rings, and keyboard order are unaffected. Its position is measured from the live DOM (`aria-current=\"page\"`) and kept in sync as the active item changes or the layout resizes. The recipe's static marker is the SSR / no-JS fallback.\n\nThe slide transition is automatically disabled under `prefers-reduced-motion: reduce` — the highlight snaps into place. (To disable the motion, the user sets the OS-level reduced-motion preference; there is no per-instance prop.)\n\n```jsx live-dev\nconst items = [\n  { href: '/orders/123/general', label: 'General' },\n  { href: '/orders/123/items', label: 'Items' },\n  { href: '/orders/123/shipping', label: 'Shipping' },\n];\n\nconst App = () => {\n  const [activePath, setActivePath] = React.useState(items[0].href);\n\n  return (\n    <TabNav.Root aria-label=\"Order navigation\" variant=\"rounded\">\n      {items.map((item) => (\n        <TabNav.Item\n          key={item.href}\n          href={item.href}\n          isCurrent={activePath === item.href}\n          onClick={(e) => { e.preventDefault(); setActivePath(item.href); }}\n        >\n          {item.label}\n        </TabNav.Item>\n      ))}\n    </TabNav.Root>\n  );\n};\n```\n\n### Active item\n\nMark the currently viewed page with `isCurrent`. This sets `aria-current=\"page\"` on the anchor element, which screen readers announce as \"current page\".\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n  </TabNav.Root>\n);\n```\n\nWhen using a client-side router, set `isCurrent` based on the active route:\n\n```tsx\nimport { useLocation } from 'react-router-dom';\n\nconst OrderNav = ({ orderId }: { orderId: string }) => {\n  const { pathname } = useLocation();\n\n  return (\n    <TabNav.Root aria-label=\"Order navigation\">\n      <TabNav.Item\n        href={`/orders/${orderId}/general`}\n        isCurrent={pathname.endsWith('/general')}\n      >\n        General\n      </TabNav.Item>\n      <TabNav.Item\n        href={`/orders/${orderId}/items`}\n        isCurrent={pathname.endsWith('/items')}\n      >\n        Items\n      </TabNav.Item>\n    </TabNav.Root>\n  );\n};\n```\n\n### Size variants\n\nThe `size` prop controls font size and padding. Available sizes: `sm`, `md` (default), `lg`.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"800\">\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Small</Text>\n      <TabNav.Root aria-label=\"Navigation (sm)\" size=\"sm\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Medium (default)</Text>\n      <TabNav.Root aria-label=\"Navigation (md)\" size=\"md\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n    <Stack direction=\"column\" gap=\"300\">\n      <Text fontWeight=\"500\">Large</Text>\n      <TabNav.Root aria-label=\"Navigation (lg)\" size=\"lg\">\n        <TabNav.Item href=\"/general\" isCurrent>General</TabNav.Item>\n        <TabNav.Item href=\"/items\">Items</TabNav.Item>\n        <TabNav.Item href=\"/shipping\">Shipping</TabNav.Item>\n      </TabNav.Root>\n    </Stack>\n  </Stack>\n);\n```\n\n### Disabled items\n\nUse `isDisabled` to prevent navigation to items that are not yet accessible. Disabled items are visually dimmed, removed from the tab sequence, and their `href` is stripped.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### External links\n\nUse `target` and `rel` to open a navigation item in a new browser tab. Always pair `target=\"_blank\"` with `rel=\"noopener noreferrer\"` for security.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n    <TabNav.Item\n      href=\"https://docs.example.com/orders\"\n      target=\"_blank\"\n      rel=\"noopener noreferrer\"\n    >\n      Docs ↗\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### With icons\n\nTab items support inline icons alongside text via the `gap` built into the item layout.\n\n```jsx live-dev\nconst App = () => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href=\"/orders/123/general\" isCurrent>\n      <Icons.Info />\n      General\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/items\">\n      <Icons.List />\n      Items\n    </TabNav.Item>\n    <TabNav.Item href=\"/orders/123/shipping\">\n      <Icons.LocalShipping />\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## Component requirements\n\n### Accessibility\n\nThe TabNav component uses semantic HTML for navigation — it does not use ARIA roles for the tablist pattern. Accessibility is handled natively by the browser's `<nav>` landmark and `<a>` anchor semantics. `TabNav.Item` uses `useLink` from React Aria for consistent interaction handling.\n\n#### Role\n\n- `TabNav.Root` renders a `<nav>` HTML element — a navigation landmark, **not** `role=\"tablist\"`\n- `TabNav.Item` renders an `<a>` HTML element with the implicit `link` role — **not** `role=\"tab\"`\n- The active item uses `aria-current=\"page\"` — **not** `aria-selected`\n\n#### Labeling\n\nAlways provide an `aria-label` on `TabNav.Root` to describe the navigation region. This is especially important when a page contains multiple `<nav>` landmarks.\n\n```tsx\n<TabNav.Root aria-label=\"Order navigation\">\n  ...\n</TabNav.Root>\n```\n\n#### Keyboard navigation\n\nTabNav uses standard sequential keyboard navigation — no roving tabindex, no arrow key cycling.\n\n| Key | Action |\n|-----|--------|\n| `Tab` | Move focus to the next link |\n| `Shift + Tab` | Move focus to the previous link |\n| `Enter` | Activate the focused link |\n\nArrow keys (`ArrowRight`, `ArrowLeft`) do **not** move focus between items. This is intentional — TabNav is a `<nav>` with standard anchor links, not a `role=\"tablist\"` widget.\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:\n\n```tsx\nconst PERSISTENT_ID = \"order-detail-tab-nav\";\n\nexport const OrderTabNav = ({ orderId }: { orderId: string }) => (\n  <TabNav.Root id={PERSISTENT_ID} aria-label=\"Order navigation\">\n    <TabNav.Item href={`/orders/${orderId}/general`} isCurrent>\n      General\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## API reference\n\n<PropsTable id=\"TabNav\" />\n\n## Common patterns\n\n### Syncing active item with router\n\nIn most routing setups you derive `isCurrent` from the current URL rather than managing it in state.\n\n```tsx\n// React Router v6\nimport { useMatch } from 'react-router-dom';\n\nconst OrderNav = ({ orderId }: { orderId: string }) => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item\n      href={`/orders/${orderId}/general`}\n      isCurrent={!!useMatch(`/orders/${orderId}/general`)}\n    >\n      General\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/items`}\n      isCurrent={!!useMatch(`/orders/${orderId}/items`)}\n    >\n      Items\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/shipping`}\n      isCurrent={!!useMatch(`/orders/${orderId}/shipping`)}\n    >\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n### Conditionally disabling items\n\nDisable items based on permissions or loading state rather than hiding them — this preserves the layout and communicates to users that the section exists.\n\n```tsx\nconst OrderNav = ({ orderId, canViewShipping }: { orderId: string; canViewShipping: boolean }) => (\n  <TabNav.Root aria-label=\"Order navigation\">\n    <TabNav.Item href={`/orders/${orderId}/general`} isCurrent>\n      General\n    </TabNav.Item>\n    <TabNav.Item\n      href={`/orders/${orderId}/shipping`}\n      isDisabled={!canViewShipping}\n    >\n      Shipping\n    </TabNav.Item>\n  </TabNav.Root>\n);\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using TabNav 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 TabNav component renders a nav landmark with anchor links\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Basic rendering\", () => {\n  it(\"renders a navigation landmark with links\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"navigation\", { name: \"Order navigation\" })\n    ).toBeInTheDocument();\n    expect(screen.getAllByRole(\"link\")).toHaveLength(3);\n  });\n\n  it(\"renders items as anchor elements with correct href\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveAttribute(\n      \"href\",\n      \"/orders/123/general\"\n    );\n    expect(screen.getByRole(\"link\", { name: \"Items\" })).toHaveAttribute(\n      \"href\",\n      \"/orders/123/items\"\n    );\n  });\n});\n```\n\n### Active Item Tests\n\nVerify aria-current=\"page\" is applied correctly to the active navigation item\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Active item\", () => {\n  it(\"sets aria-current='page' on the active item\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveAttribute(\n      \"aria-current\",\n      \"page\"\n    );\n  });\n\n  it(\"does not set aria-current on inactive items\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item href=\"/orders/123/items\">Items</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\">Shipping</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"Items\" })).not.toHaveAttribute(\n      \"aria-current\"\n    );\n    expect(screen.getByRole(\"link\", { name: \"Shipping\" })).not.toHaveAttribute(\n      \"aria-current\"\n    );\n  });\n\n  it(\"does not use aria-selected (navigation, not widget)\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"General\" })).not.toHaveAttribute(\n      \"aria-selected\"\n    );\n  });\n});\n```\n\n### Disabled Item Tests\n\nVerify disabled items are marked inaccessible and removed from tab order\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Disabled items\", () => {\n  it(\"marks disabled items with aria-disabled='true'\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n            Shipping\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    const disabledItem = screen.getByRole(\"link\", { name: \"Shipping\" });\n    expect(disabledItem).toHaveAttribute(\"aria-disabled\", \"true\");\n  });\n\n  it(\"disabled items have no tabIndex (excluded from tab sequence by browser)\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n          <TabNav.Item href=\"/orders/123/shipping\" isDisabled>\n            Shipping\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    // React Aria sets no tabIndex on the disabled anchor — the browser excludes it\n    const disabledItem = screen.getByRole(\"link\", { name: \"Shipping\" });\n    expect(disabledItem).not.toHaveAttribute(\"tabindex\");\n  });\n});\n```\n\n### External Link Tests\n\nVerify target and rel attributes for external navigation items\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - External links\", () => {\n  it(\"applies target and rel to external link items\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" isCurrent>\n            General\n          </TabNav.Item>\n          <TabNav.Item\n            href=\"https://docs.example.com\"\n            target=\"_blank\"\n            rel=\"noopener noreferrer\"\n          >\n            Docs ↗\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    const externalLink = screen.getByRole(\"link\", { name: \"Docs ↗\" });\n    expect(externalLink).toHaveAttribute(\"target\", \"_blank\");\n    expect(externalLink).toHaveAttribute(\"rel\", \"noopener noreferrer\");\n  });\n});\n```\n\n### Interaction Tests\n\nVerify click handling and keyboard activation\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Interactions\", () => {\n  it(\"calls onClick handler when a link is clicked\", async () => {\n    const user = userEvent.setup();\n    const handleClick = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\" onClick={handleClick}>\n            General\n          </TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"link\", { name: \"General\" }));\n    expect(handleClick).toHaveBeenCalled();\n  });\n\n  it(\"is focusable with Tab key\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    await user.tab();\n    expect(screen.getByRole(\"link\", { name: \"General\" })).toHaveFocus();\n  });\n});\n```\n\n### Accessibility Tests\n\nVerify accessible labels and ID support\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 { TabNav, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"TabNav - Accessibility\", () => {\n  it(\"supports aria-label on the root for landmark identification\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"navigation\", { name: \"Order navigation\" })\n    ).toBeInTheDocument();\n  });\n\n  it(\"supports a persistent id on the root for tracking\", () => {\n    render(\n      <NimbusProvider>\n        <TabNav.Root id=\"order-tab-nav\" aria-label=\"Order navigation\">\n          <TabNav.Item href=\"/orders/123/general\">General</TabNav.Item>\n        </TabNav.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"navigation\")).toHaveAttribute(\n      \"id\",\n      \"order-tab-nav\"\n    );\n  });\n});\n```\n\n\n## Resources\n\n- [React Aria useLink](https://react-spectrum.adobe.com/react-aria/useLink.html)\n- [ARIA: navigation landmark](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/navigation_role)\n- [aria-current attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-current)\n- [Tabs](/components/navigation/tabs) — use when switching content panels on the same page\n",
       "toc": [
         {
           "value": "Getting started",
@@ -288,6 +332,28 @@
           ],
           "parent": "root"
         },
+        {
+          "value": "Variants",
+          "href": "#variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Animated highlight",
+          "href": "#animated-highlight",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
         {
           "value": "Active item",
           "href": "#active-item",
@@ -295,7 +361,7 @@
           "numbering": [
             1,
             3,
-            2
+            4
           ],
           "parent": "root"
         },
@@ -306,7 +372,7 @@
           "numbering": [
             1,
             3,
-            3
+            5
           ],
           "parent": "root"
         },
@@ -317,7 +383,7 @@
           "numbering": [
             1,
             3,
-            4
+            6
           ],
           "parent": "root"
         },
@@ -328,7 +394,7 @@
           "numbering": [
             1,
             3,
-            5
+            7
           ],
           "parent": "root"
         },
@@ -339,7 +405,7 @@
           "numbering": [
             1,
             3,
-            6
+            8
           ],
           "parent": "root"
         },