@commercetools/nimbus-mcp 3.3.0 → 3.4.0

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

@@ -0,0 +1,565 @@
+{
+  "meta": {
+    "id": "Components-Breadcrumbs",
+    "title": "Breadcrumbs",
+    "exportName": "Breadcrumbs",
+    "description": "A navigation trail showing the path to the current page.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/breadcrumbs/breadcrumbs.mdx",
+    "menu": [
+      "Components",
+      "Navigation",
+      "Breadcrumbs"
+    ],
+    "route": "components/navigation/breadcrumbs",
+    "tags": [
+      "component",
+      "navigation",
+      "breadcrumbs"
+    ],
+    "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": "Guidelines",
+        "href": "#guidelines",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Sizes",
+        "href": "#sizes",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Current page",
+        "href": "#current-page",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Data-driven trail",
+        "href": "#data-driven-trail",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Custom separator",
+        "href": "#custom-separator",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Disabled item",
+        "href": "#disabled-item",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          5
+        ],
+        "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\nBreadcrumbs display the hierarchical path to the current page as an ordered list\nof links. They render a `<nav>` landmark containing an `<ol>` of `<a>` elements.\nEach item except the last navigates to an ancestor page; the last item is\ntreated as the current page automatically and is rendered as non-interactive\ntext with `aria-current=\"page\"`.\n\nUse breadcrumbs in pages that sit several levels deep in a hierarchy (e.g.\n`/products/apparel/shoes`) to help users understand where they are and to move\nback up the tree.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria Breadcrumbs](https://react-spectrum.adobe.com/react-aria/Breadcrumbs.html)\n\n## Guidelines\n\n> [!TIP]\\\n> **When to use**\n>\n> - The page sits **three or more levels deep** in a clear hierarchy.\n> - Every level in the trail is a real, navigable page.\n> - Users benefit from seeing where they are and stepping back up the tree.\n\n> [!CAUTION]\\\n> **When not to use**\n>\n> - As a substitute for a **back button** or the browser's history.\n> - On flat or two-level sites where the hierarchy adds no value.\n> - To represent a **multi-step flow or wizard** — use progress steps instead.\n> - Keep labels short and match them to the destination page titles.\n\n## Variables\n\nGet familiar with the features.\n\n### Sizes\n\n`Breadcrumbs` supports two size variants — `sm` and `md` (default) — that\ncontrol the font size and spacing between items.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    {[\"sm\", \"md\"].map((size) => (\n      <Stack key={size} direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"600\">{size}</Text>\n        <Breadcrumbs.Root aria-label={`Breadcrumb (${size})`} size={size}>\n          <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n          <Breadcrumbs.Item href=\"/orders\">Orders</Breadcrumbs.Item>\n          <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </Stack>\n    ))}\n  </Stack>\n);\n```\n\n### Current page\n\nThe **last** item is the current page automatically — there is no `isCurrent`\nprop. It renders as non-interactive text with `aria-current=\"page\"`, which\nscreen readers announce as \"current page\".\n\n```jsx live\nconst App = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n    <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/orders\">Orders</Breadcrumbs.Item>\n    <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n  </Breadcrumbs.Root>\n);\n```\n\n### Data-driven trail\n\nPass an `items` array to render a trail from data. The last entry is the current\npage.\n\n```jsx live\nconst App = () => (\n  <Breadcrumbs.Root\n    aria-label=\"Breadcrumb\"\n    items={[\n      { id: \"home\", label: \"Home\", href: \"/\" },\n      { id: \"catalog\", label: \"Catalog\", href: \"/catalog\" },\n      { id: \"shoes\", label: \"Shoes\" },\n    ]}\n  />\n);\n```\n\n### Custom separator\n\nSupply any React node via the `separator` prop on `Breadcrumbs.Root`. The\nseparator is decorative and hidden from assistive technologies.\n\n```jsx live\nconst App = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\" separator=\"/\">\n    <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/catalog\">Catalog</Breadcrumbs.Item>\n    <Breadcrumbs.Item>Shoes</Breadcrumbs.Item>\n  </Breadcrumbs.Root>\n);\n```\n\n### Disabled item\n\nUse `isDisabled` to render an item that is part of the trail but cannot be\nnavigated to. Disabled items are visually dimmed and excluded from the tab\nsequence.\n\n```jsx live\nconst App = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n    <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/orders\" isDisabled>\n      Orders\n    </Breadcrumbs.Item>\n    <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n  </Breadcrumbs.Root>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nBreadcrumbs display the hierarchical path to the current page as an ordered list\nof links. They render a `<nav>` landmark containing an `<ol>` of `<a>` elements.\nEach item except the last navigates to an ancestor page; the last item is\ntreated as the current page automatically and is rendered as non-interactive\ntext with `aria-current=\"page\"`.\n\nUse breadcrumbs in pages that sit several levels deep in a hierarchy (e.g.\n`/products/apparel/shoes`) to help users understand where they are and to move\nback up the tree.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria Breadcrumbs](https://react-spectrum.adobe.com/react-aria/Breadcrumbs.html)\n\n## Guidelines\n\n> [!TIP]\\\n> **When to use**\n>\n> - The page sits **three or more levels deep** in a clear hierarchy.\n> - Every level in the trail is a real, navigable page.\n> - Users benefit from seeing where they are and stepping back up the tree.\n\n> [!CAUTION]\\\n> **When not to use**\n>\n> - As a substitute for a **back button** or the browser's history.\n> - On flat or two-level sites where the hierarchy adds no value.\n> - To represent a **multi-step flow or wizard** — use progress steps instead.\n> - Keep labels short and match them to the destination page titles.\n\n## Variables\n\nGet familiar with the features.\n\n### Sizes\n\n`Breadcrumbs` supports two size variants — `sm` and `md` (default) — that\ncontrol the font size and spacing between items.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    {[\"sm\", \"md\"].map((size) => (\n      <Stack key={size} direction=\"column\" gap=\"200\">\n        <Text fontWeight=\"600\">{size}</Text>\n        <Breadcrumbs.Root aria-label={`Breadcrumb (${size})`} size={size}>\n          <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n          <Breadcrumbs.Item href=\"/orders\">Orders</Breadcrumbs.Item>\n          <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </Stack>\n    ))}\n  </Stack>\n);\n```\n\n### Current page\n\nThe **last** item is the current page automatically — there is no `isCurrent`\nprop. It renders as non-interactive text with `aria-current=\"page\"`, which\nscreen readers announce as \"current page\".\n\n```jsx live\nconst App = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n    <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/orders\">Orders</Breadcrumbs.Item>\n    <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n  </Breadcrumbs.Root>\n);\n```\n\n### Data-driven trail\n\nPass an `items` array to render a trail from data. The last entry is the current\npage.\n\n```jsx live\nconst App = () => (\n  <Breadcrumbs.Root\n    aria-label=\"Breadcrumb\"\n    items={[\n      { id: \"home\", label: \"Home\", href: \"/\" },\n      { id: \"catalog\", label: \"Catalog\", href: \"/catalog\" },\n      { id: \"shoes\", label: \"Shoes\" },\n    ]}\n  />\n);\n```\n\n### Custom separator\n\nSupply any React node via the `separator` prop on `Breadcrumbs.Root`. The\nseparator is decorative and hidden from assistive technologies.\n\n```jsx live\nconst App = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\" separator=\"/\">\n    <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/catalog\">Catalog</Breadcrumbs.Item>\n    <Breadcrumbs.Item>Shoes</Breadcrumbs.Item>\n  </Breadcrumbs.Root>\n);\n```\n\n### Disabled item\n\nUse `isDisabled` to render an item that is part of the trail but cannot be\nnavigated to. Disabled items are visually dimmed and excluded from the tab\nsequence.\n\n```jsx live\nconst App = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n    <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/orders\" isDisabled>\n      Orders\n    </Breadcrumbs.Item>\n    <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n  </Breadcrumbs.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": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Sizes",
+          "href": "#sizes",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Current page",
+          "href": "#current-page",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Data-driven trail",
+          "href": "#data-driven-trail",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom separator",
+          "href": "#custom-separator",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled item",
+          "href": "#disabled-item",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            5
+          ],
+          "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  <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n    <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/products\">Products</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/products/apparel\">Apparel</Breadcrumbs.Item>\n    <Breadcrumbs.Item>Shoes</Breadcrumbs.Item>\n  </Breadcrumbs.Root>\n);\n```\n\n### Accessibility standards\n\n- **Landmark role:** `Breadcrumbs.Root` renders a `<nav>` HTML element — a\n  navigation landmark. Always provide an `aria-label` (commonly `\"Breadcrumb\"`)\n  to identify the landmark, especially when a page contains multiple `<nav>`\n  elements.\n- **List semantics:** Items are rendered inside an ordered list (`<ol>` with\n  `<li>` children) carrying an explicit `role=\"list\"`, which communicates the\n  hierarchical, sequential nature of the trail to assistive technologies — and\n  keeps list semantics under `list-style: none`, which WebKit (Safari +\n  VoiceOver) otherwise strips.\n- **Link semantics:** Each navigable item renders an `<a>` element with the\n  implicit `link` role.\n- **Current page indication:** The current (last) item is derived automatically\n  (no `isCurrent` prop). It uses `aria-current=\"page\"` — **not** `aria-selected`\n  — which screen readers announce as \"current page\". It renders as a\n  non-focusable `<span role=\"link\">` and is removed from the tab sequence.\n- **Decorative separators:** Separators between items are decorative and carry\n  `aria-hidden=\"true\"`, so they are not announced by screen readers.\n- **Keyboard navigation:** Breadcrumbs use standard sequential keyboard\n  navigation. The `Tab` key moves focus to the next link and `Shift + Tab` moves\n  to the previous link. Arrow keys do **not** cycle focus between items.\n- **Disabled items:** Disabled items carry `aria-disabled=\"true\"` and are\n  excluded from the tab sequence, so keyboard users skip them naturally. Avoid\n  disabling the **last** item: it is already the non-interactive current page,\n  and because a disabled item renders as a plain `<span>` outside React Aria's\n  collection context, a disabled final item will not receive\n  `aria-current=\"page\"`.\n- **Contrast:** Ensure sufficient contrast between link text and the background\n  in all states (default, hover, current, focused, disabled). The focus\n  indicator 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 {\n  Breadcrumbs,\n  type BreadcrumbsProps,\n  type BreadcrumbsItemProps,\n} from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\n`Breadcrumbs` is a compound component for **hierarchical page navigation**. It\nrenders a `<nav>` landmark containing an ordered list of `<a>` elements. The\nlast item is treated as the current page automatically — there is no `isCurrent`\nprop.\n\n```jsx live-dev\nconst App = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n    <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/orders\">Orders</Breadcrumbs.Item>\n    <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n  </Breadcrumbs.Root>\n);\n```\n\n> [!NOTE]\\\n> Breadcrumbs is built on React Aria Components' `Breadcrumbs`/`Breadcrumb`\n> primitives. React Aria owns the collection semantics: it derives the current\n> page (the last item), applies `aria-current=\"page\"`, and removes that item\n> from the tab order automatically. This is why there is no `isCurrent` prop and\n> why the API mirrors other React-Aria-backed Nimbus components.\n\n## Usage examples\n\n### Current page\n\nThe final item is the current page automatically. React Aria strips its `href`,\nrenders it as non-interactive text, and sets `aria-current=\"page\"`.\n\n```jsx live-dev\nconst App = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n    <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/catalog\">Catalog</Breadcrumbs.Item>\n    <Breadcrumbs.Item>Shoes</Breadcrumbs.Item>\n  </Breadcrumbs.Root>\n);\n```\n\nWhen using a client-side router, derive the trail from the current route and\nrender the deepest segment last — it becomes current automatically:\n\n```tsx\nimport { useLocation } from \"react-router-dom\";\n\nconst ProductBreadcrumbs = ({ category }: { category: string }) => {\n  const { pathname } = useLocation();\n\n  return (\n    <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n      <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n      <Breadcrumbs.Item href=\"/products\">Products</Breadcrumbs.Item>\n      <Breadcrumbs.Item>{category}</Breadcrumbs.Item>\n    </Breadcrumbs.Root>\n  );\n};\n```\n\n### Data-driven trail (`items`)\n\nFor trails built from data, pass an `items` array instead of compound children.\nThe last entry is the current page, and `onAction` receives the activated\nentry's `id`.\n\n```jsx live-dev\nconst App = () => (\n  <Breadcrumbs.Root\n    aria-label=\"Breadcrumb\"\n    items={[\n      { id: \"home\", label: \"Home\", href: \"/\" },\n      { id: \"products\", label: \"Products\", href: \"/products\" },\n      { id: \"apparel\", label: \"Apparel\", href: \"/products/apparel\" },\n      { id: \"shoes\", label: \"Shoes\" },\n    ]}\n  />\n);\n```\n\n### Custom separator\n\nThe default separator is `›`. Pass any React node (string or icon) via the\n`separator` prop on `Breadcrumbs.Root`. Separators are decorative and hidden\nfrom assistive technologies.\n\n```jsx live-dev\nconst App = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\" separator=\"/\">\n    <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/products\">Products</Breadcrumbs.Item>\n    <Breadcrumbs.Item>Apparel</Breadcrumbs.Item>\n  </Breadcrumbs.Root>\n);\n```\n\n### Size variants\n\nThe `size` prop controls font size and spacing. Available sizes: `sm`, `md`\n(default).\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"500\">Small</Text>\n      <Breadcrumbs.Root aria-label=\"Breadcrumb (sm)\" size=\"sm\">\n        <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n        <Breadcrumbs.Item href=\"/orders\">Orders</Breadcrumbs.Item>\n        <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n      </Breadcrumbs.Root>\n    </Stack>\n    <Stack direction=\"column\" gap=\"200\">\n      <Text fontWeight=\"500\">Medium (default)</Text>\n      <Breadcrumbs.Root aria-label=\"Breadcrumb (md)\" size=\"md\">\n        <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n        <Breadcrumbs.Item href=\"/orders\">Orders</Breadcrumbs.Item>\n        <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n      </Breadcrumbs.Root>\n    </Stack>\n  </Stack>\n);\n```\n\n### Disabled items\n\nUse `isDisabled` to render an ancestor item that exists in the trail but cannot\ncurrently be navigated to. Disabled items are visually dimmed, removed from the\ntab sequence, and non-interactive.\n\n```jsx live-dev\nconst App = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n    <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n    <Breadcrumbs.Item href=\"/orders\" isDisabled>\n      Orders\n    </Breadcrumbs.Item>\n    <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n  </Breadcrumbs.Root>\n);\n```\n\n### External links\n\nUse `target` and `rel` to open a breadcrumb in a new browser tab. Always pair\n`target=\"_blank\"` with `rel=\"noopener noreferrer\"` for security.\n\n```jsx live-dev\nconst App = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n    <Breadcrumbs.Item\n      href=\"https://docs.example.com\"\n      target=\"_blank\"\n      rel=\"noopener noreferrer\"\n    >\n      Docs ↗\n    </Breadcrumbs.Item>\n    <Breadcrumbs.Item>Current page</Breadcrumbs.Item>\n  </Breadcrumbs.Root>\n);\n```\n\n## Component requirements\n\n### Accessibility\n\nThe Breadcrumbs component uses semantic HTML for navigation. Accessibility is\nhandled by the browser's `<nav>` landmark and ordered-list structure, combined\nwith React Aria's `Breadcrumbs`/`Breadcrumb`/`Link` primitives for current-page\nand interaction handling.\n\n#### Role\n\n- `Breadcrumbs.Root` renders a `<nav>` HTML element — a navigation landmark —\n  wrapping an `<ol>` (with an explicit `role=\"list\"`, which keeps list semantics\n  under `list-style: none` in Safari/VoiceOver).\n- Items are rendered inside an `<ol>`/`<li>` structure.\n- Each navigable item renders an `<a>` element with the implicit `link` role.\n- The current (last) item renders as a non-focusable `<span role=\"link\">` with\n  `aria-current=\"page\"` — **not** `aria-selected`.\n\n#### Labeling\n\nAlways provide an `aria-label` on `Breadcrumbs.Root` (commonly `\"Breadcrumb\"`)\nto describe the navigation region. A development-time warning is logged if it is\nomitted. In localized apps, translate the label.\n\n```tsx\n<Breadcrumbs.Root aria-label=\"Breadcrumb\">...</Breadcrumbs.Root>\n```\n\n#### Keyboard navigation\n\nBreadcrumbs use standard sequential keyboard navigation — no roving tabindex, no\narrow 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\nThe current (last) item and any disabled items are non-interactive and skipped\nin the tab sequence.\n\n## API reference\n\n<PropsTable id=\"Breadcrumbs\" />\n\n## Common patterns\n\n### Building a trail from data\n\nPrefer the declarative `items` API — it owns the last-is-current logic for you,\nso there is no index bookkeeping:\n\n```tsx\nconst trail = [\n  { id: \"home\", label: \"Home\", href: \"/\" },\n  { id: \"products\", label: \"Products\", href: \"/products\" },\n  { id: \"apparel\", label: \"Apparel\", href: \"/products/apparel\" },\n  { id: \"shoes\", label: \"Shoes\" }, // last entry is the current page\n];\n\nconst ProductTrail = () => (\n  <Breadcrumbs.Root aria-label=\"Breadcrumb\" items={trail} />\n);\n```\n\n## Out of scope\n\nThe following are intentionally **not** handled by this component today:\n\n- **Overflow / collapsing** long trails (e.g. `Home / … / Current`). Keep trails\n  short, or truncate labels in your own layout.\n- **RTL separator glyphs.** The layout mirrors in RTL, but a directional glyph\n  such as `›` does not flip — supply a direction-neutral separator (e.g. `/`)\n  for RTL locales.\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using\nBreadcrumbs within your application. As the component's internal functionality\nis already tested by Nimbus, these patterns help you verify your integration and\napplication-specific logic.\n\n### Basic Rendering Tests\n\nVerify the Breadcrumbs component renders a nav landmark with an ordered list of 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 { Breadcrumbs, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Breadcrumbs - Basic rendering\", () => {\n  it(\"renders a navigation landmark with an ordered list\", () => {\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n          <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n          <Breadcrumbs.Item href=\"/orders\">Orders</Breadcrumbs.Item>\n          <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"navigation\", { name: \"Breadcrumb\" })\n    ).toBeInTheDocument();\n    expect(screen.getByRole(\"list\").tagName).toBe(\"OL\");\n    expect(screen.getAllByRole(\"listitem\")).toHaveLength(3);\n  });\n\n  it(\"renders link items as anchors with the correct href\", () => {\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n          <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n          <Breadcrumbs.Item href=\"/orders\">Orders</Breadcrumbs.Item>\n          <Breadcrumbs.Item>Current</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"Home\" })).toHaveAttribute(\n      \"href\",\n      \"/\"\n    );\n    expect(screen.getByRole(\"link\", { name: \"Orders\" })).toHaveAttribute(\n      \"href\",\n      \"/orders\"\n    );\n  });\n\n  it(\"builds a trail from a data array via the items prop\", () => {\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root\n          aria-label=\"Breadcrumb\"\n          items={[\n            { id: \"home\", label: \"Home\", href: \"/\" },\n            { id: \"orders\", label: \"Orders\", href: \"/orders\" },\n            { id: \"detail\", label: \"Order #123\" },\n          ]}\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getAllByRole(\"listitem\")).toHaveLength(3);\n    expect(screen.getByRole(\"link\", { name: \"Home\" })).toHaveAttribute(\n      \"href\",\n      \"/\"\n    );\n    expect(screen.getByText(\"Order #123\")).toHaveAttribute(\n      \"aria-current\",\n      \"page\"\n    );\n  });\n});\n```\n\n### Current Page Tests\n\nVerify aria-current=\"page\" is applied to the last item automatically and not to ancestors\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 { Breadcrumbs, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Breadcrumbs - Current page\", () => {\n  it(\"sets aria-current='page' on the last item automatically\", () => {\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n          <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n          <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Order #123\")).toHaveAttribute(\n      \"aria-current\",\n      \"page\"\n    );\n  });\n\n  it(\"renders the current item as non-navigable (no href)\", () => {\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n          <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n          <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </NimbusProvider>\n    );\n\n    // React Aria renders the current item as a <span> (not an anchor) with no\n    // href, so it is not a navigable link.\n    const current = screen.getByText(\"Order #123\");\n    expect(current).not.toHaveAttribute(\"href\");\n    expect(current.tagName).toBe(\"SPAN\");\n  });\n\n  it(\"does not set aria-current on ancestor items\", () => {\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n          <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n          <Breadcrumbs.Item href=\"/orders\">Orders</Breadcrumbs.Item>\n          <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"link\", { name: \"Home\" })).not.toHaveAttribute(\n      \"aria-current\"\n    );\n    expect(screen.getByRole(\"link\", { name: \"Orders\" })).not.toHaveAttribute(\n      \"aria-current\"\n    );\n  });\n});\n```\n\n### Disabled Item Tests\n\nVerify disabled items are marked inaccessible and stripped of their href\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 { Breadcrumbs, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Breadcrumbs - Disabled items\", () => {\n  it(\"marks disabled items with aria-disabled='true' and strips href\", () => {\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n          <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n          <Breadcrumbs.Item href=\"/orders\" isDisabled>\n            Orders\n          </Breadcrumbs.Item>\n          <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </NimbusProvider>\n    );\n\n    const disabled = screen.getByText(\"Orders\");\n    expect(disabled).toHaveAttribute(\"aria-disabled\", \"true\");\n    expect(disabled).not.toHaveAttribute(\"href\");\n  });\n});\n```\n\n### External Link Tests\n\nVerify target and rel attributes for external breadcrumb 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 { Breadcrumbs, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Breadcrumbs - External links\", () => {\n  it(\"applies target and rel to external link items\", () => {\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n          <Breadcrumbs.Item\n            href=\"https://docs.example.com\"\n            target=\"_blank\"\n            rel=\"noopener noreferrer\"\n          >\n            Docs ↗\n          </Breadcrumbs.Item>\n          <Breadcrumbs.Item>Current page</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </NimbusProvider>\n    );\n\n    const external = screen.getByRole(\"link\", { name: \"Docs ↗\" });\n    expect(external).toHaveAttribute(\"target\", \"_blank\");\n    expect(external).toHaveAttribute(\"rel\", \"noopener noreferrer\");\n  });\n});\n```\n\n### Interaction Tests\n\nVerify onAction fires with the activated breadcrumb's id\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 { Breadcrumbs, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Breadcrumbs - Interactions\", () => {\n  it(\"calls onAction with the item id when a breadcrumb is activated\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root aria-label=\"Breadcrumb\" onAction={handleAction}>\n          <Breadcrumbs.Item id=\"home\" href=\"/\">\n            Home\n          </Breadcrumbs.Item>\n          <Breadcrumbs.Item id=\"orders\" href=\"/orders\">\n            Orders\n          </Breadcrumbs.Item>\n          <Breadcrumbs.Item id=\"detail\">Order #123</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"link\", { name: \"Orders\" }));\n    expect(handleAction).toHaveBeenCalledWith(\"orders\");\n  });\n\n  it(\"focuses link items with the Tab key\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n          <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n          <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </NimbusProvider>\n    );\n\n    await user.tab();\n    expect(screen.getByRole(\"link\", { name: \"Home\" })).toHaveFocus();\n  });\n});\n```\n\n### Accessibility Tests\n\nVerify accessible labels and that the widget does not use aria-selected\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 { Breadcrumbs, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Breadcrumbs - Accessibility\", () => {\n  it(\"supports aria-label on the root for landmark identification\", () => {\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n          <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n          <Breadcrumbs.Item>Current</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"navigation\", { name: \"Breadcrumb\" })\n    ).toBeInTheDocument();\n  });\n\n  it(\"does not use aria-selected (navigation, not a widget)\", () => {\n    render(\n      <NimbusProvider>\n        <Breadcrumbs.Root aria-label=\"Breadcrumb\">\n          <Breadcrumbs.Item href=\"/\">Home</Breadcrumbs.Item>\n          <Breadcrumbs.Item>Order #123</Breadcrumbs.Item>\n        </Breadcrumbs.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Order #123\")).not.toHaveAttribute(\"aria-selected\");\n  });\n});\n```\n\n\n## Resources\n\n- [React Aria Breadcrumbs](https://react-spectrum.adobe.com/react-aria/Breadcrumbs.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",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Current page",
+          "href": "#current-page",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Data-driven trail (items)",
+          "href": "#data-driven-trail-items",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom separator",
+          "href": "#custom-separator",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size variants",
+          "href": "#size-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled items",
+          "href": "#disabled-items",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "External links",
+          "href": "#external-links",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Role",
+          "href": "#role",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Labeling",
+          "href": "#labeling",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Building a trail from data",
+          "href": "#building-a-trail-from-data",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Out of scope",
+          "href": "#out-of-scope",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "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": "Current Page Tests",
+          "href": "#current-page-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"
+        }
+      ]
+    }
+  }
+}

package/data/docs/routes/icons.json

@@ -2,7 +2,7 @@
   "meta": {
     "id": "Icons",
     "title": "Icons",
-    "description": "display Icons",
+    "description": "Find and use icons from the Nimbus icon library.",
     "order": 5,
     "repoPath": "packages/nimbus-icons/README.mdx",
     "menu": [
@@ -22,10 +22,10 @@
       }
     ]
   },
-  "mdx": "\n# Icons\n\nIcons come from a separate package. Each Icon is a react component that can be\nused in any other component.\n\n> [!NOTE]  \n> If you can't find a fitting Icon, you may want to use the external\n> [material ui icon search](https://mui.com/material-ui/material-icons/?theme=Outlined&query=access#search-material-icons)\n> as the search below does not have access to Icon meta-data, only to\n> component-names.\n\nHere is the list of available icons:\n\n<IconSearch />\n",
+  "mdx": "\n<IconSearch />\n",
   "views": {
     "overview": {
-      "mdx": "\n# Icons\n\nIcons come from a separate package. Each Icon is a react component that can be\nused in any other component.\n\n> [!NOTE]  \n> If you can't find a fitting Icon, you may want to use the external\n> [material ui icon search](https://mui.com/material-ui/material-icons/?theme=Outlined&query=access#search-material-icons)\n> as the search below does not have access to Icon meta-data, only to\n> component-names.\n\nHere is the list of available icons:\n\n<IconSearch />\n",
+      "mdx": "\n<IconSearch />\n",
       "toc": []
     }
   }