@commercetools/nimbus-mcp 0.1.0 → 2.11.0

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

@@ -0,0 +1,546 @@
+{
+  "meta": {
+    "id": "Components-TabNav",
+    "title": "TabNav",
+    "exportName": "TabNav",
+    "description": "Tab-styled navigation links for route-based page navigation.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/tab-nav/tab-nav.mdx",
+    "menu": [
+      "Components",
+      "Navigation",
+      "TabNav"
+    ],
+    "route": "components/navigation/tabnav",
+    "tags": [
+      "component",
+      "navigation",
+      "tab-nav"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Sizes",
+        "href": "#sizes",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Active item",
+        "href": "#active-item",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Disabled item",
+        "href": "#disabled-item",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "With icons",
+        "href": "#with-icons",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          4
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "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",
+  "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",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Sizes",
+          "href": "#sizes",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Active item",
+          "href": "#active-item",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled item",
+          "href": "#disabled-item",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With icons",
+          "href": "#with-icons",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => (\n  <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.Item href=\"/orders/123/history\">History</TabNav.Item>\n  </TabNav.Root>\n)\n```\n\n### Accessibility standards\n\n- **Landmark role:** `TabNav.Root` renders a `<nav>` HTML element — a navigation\n  landmark. Always provide an `aria-label` to identify the landmark, especially\n  when a page contains multiple `<nav>` elements.\n- **Link semantics:** `TabNav.Item` renders an `<a>` element with the implicit\n  `link` role. Do **not** use `role=\"tab\"` — this component is not a tablist\n  widget.\n- **Active page indication:** The active item uses `aria-current=\"page\"` — **not**\n  `aria-selected`. Screen readers announce this as \"current page\" to users.\n- **Keyboard navigation:** `TabNav` uses standard sequential keyboard navigation.\n  The `Tab` key moves focus to the next link and `Shift + Tab` moves to the\n  previous link. Arrow keys do **not** cycle focus between items — this is\n  intentional and differs from the `Tabs` widget pattern.\n- **Disabled items:** Disabled items carry `aria-disabled=\"true\"` and are\n  excluded from the tab sequence, so keyboard users skip them naturally.\n- **Contrast:** Ensure sufficient contrast between link text and the background\n  in all states (default, hover, active, focused, disabled). The focus indicator\n  must be clearly visible.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { 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",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "TabNav vs Tabs",
+          "href": "#tabnav-vs-tabs",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Client-side view switching",
+          "href": "#client-side-view-switching",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Active item",
+          "href": "#active-item",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size variants",
+          "href": "#size-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled items",
+          "href": "#disabled-items",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "External links",
+          "href": "#external-links",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With icons",
+          "href": "#with-icons",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Role",
+          "href": "#role",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labeling",
+          "href": "#labeling",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Persistent ID",
+          "href": "#persistent-id",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Syncing active item with router",
+          "href": "#syncing-active-item-with-router",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Conditionally disabling items",
+          "href": "#conditionally-disabling-items",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Active Item Tests",
+          "href": "#active-item-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled Item Tests",
+          "href": "#disabled-item-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "External Link Tests",
+          "href": "#external-link-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility Tests",
+          "href": "#accessibility-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}