@commercetools/nimbus-mcp 3.2.0 → 3.4.0

package/data/docs/routes/components-data-display-item.json

@@ -0,0 +1,611 @@
+{
+  "meta": {
+    "id": "Components-Item",
+    "title": "Item",
+    "exportName": "Item",
+    "description": "A horizontal content row with leading media, a title and description, and trailing actions — for settings, notification, and resource rows.",
+    "lifecycleState": "Beta",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/item/item.mdx",
+    "menu": [
+      "Components",
+      "Data Display",
+      "Item"
+    ],
+    "route": "components/data-display/item",
+    "tags": [
+      "component",
+      "item",
+      "row",
+      "list",
+      "content"
+    ],
+    "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": "Media",
+        "href": "#media",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variant",
+        "href": "#variant",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Header and footer",
+        "href": "#header-and-footer",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Link rows and actions",
+        "href": "#link-rows-and-actions",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          5
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\n`Item` lays out **one horizontal content row**: leading media, a title and\ndescription column, and trailing actions, with optional full-width bands above\nand below. It is the shape behind settings rows, notification entries,\nfile/resource rows, and summary rows — the pattern teams otherwise rebuild ad\nhoc with slightly different spacing every time.\n\n`Item` is deliberately restrained. It is presentational by default and only\nbecomes interactive in one way: passing `href` upgrades the entire row to an\naccessible link. There is no button mode and no built-in selection state — real\nactions live as `Button`/`IconButton` controls inside `Item.Actions`, and\nselectable, navigable collections stay the job of `Menu`. `Item` complements\n`Card`, which composes vertical containers, the same way it complements those\ninteractive collections: each owns a different shape.\n\nTo stack several rows into a list with dividers between them, pair `Item` with\nthe separate `ItemGroup` component.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Media\n\n`Item.Media` is a fixed, non-shrinking slot for an icon, avatar, or image. Its\n`variant` sizes and shapes the content independently of the row's own `variant`:\n`default` imposes no sizing (use it for a custom-sized avatar), `icon` sizes an\ninline glyph, and `image` constrains a thumbnail into a rounded box.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"400\">\n    <Item.Root variant=\"outline\">\n      <Item.Media variant=\"icon\">\n        <Icons.Person />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Icon media</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root variant=\"outline\">\n      <Item.Media variant=\"image\">\n        <img src=\"/images/card/card-discount-template.png\" alt=\"\" />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Image media</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </Stack>\n);\n```\n\n### Size\n\nThe `size` prop scales the row's padding and gap. Use `xs` and `sm` for dense\nlists of rows, and `md` (the default) for standalone or spacious layouts.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"400\">\n    <Item.Root size=\"xs\" variant=\"outline\">\n      <Item.Content>\n        <Item.Title>Extra small</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root size=\"sm\" variant=\"outline\">\n      <Item.Content>\n        <Item.Title>Small</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root size=\"md\" variant=\"outline\">\n      <Item.Content>\n        <Item.Title>Medium (default)</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </Stack>\n);\n```\n\n### Variant\n\nThe `variant` prop controls the row's visual treatment: `plain` (default) has no\nborder or fill, `outline` adds a token-based border, and `subtle` fills the row\nwith a muted surface color.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"400\">\n    <Item.Root variant=\"plain\">\n      <Item.Content>\n        <Item.Title>Plain</Item.Title>\n        <Item.Description>No border, no fill.</Item.Description>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root variant=\"outline\">\n      <Item.Content>\n        <Item.Title>Outline</Item.Title>\n        <Item.Description>A token-based border.</Item.Description>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root variant=\"subtle\">\n      <Item.Content>\n        <Item.Title>Subtle</Item.Title>\n        <Item.Description>A muted surface fill.</Item.Description>\n      </Item.Content>\n    </Item.Root>\n  </Stack>\n);\n```\n\n### Header and footer\n\n`Item.Header` and `Item.Footer` are optional full-width bands rendered above and\nbelow the media·content·actions row — useful for a category label or a timestamp\nthat shouldn't compete with the title for horizontal space.\n\n```jsx live\nconst App = () => (\n  <Item.Root variant=\"outline\">\n    <Item.Header>\n      <Text fontWeight=\"600\">This week</Text>\n    </Item.Header>\n    <Item.Media variant=\"icon\">\n      <Icons.Person />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Weekly digest</Item.Title>\n      <Item.Description>Summarizes activity across your team.</Item.Description>\n    </Item.Content>\n    <Item.Footer>\n      <Text textStyle=\"sm\" color=\"neutral.11\">\n        Sent Monday at 9:00am\n      </Text>\n    </Item.Footer>\n  </Item.Root>\n);\n```\n\n### Link rows and actions\n\nPassing `href` upgrades the row to an accessible link — the whole row is\nkeyboard focusable and navigable. Controls placed in `Item.Actions` stay\nindependently operable: pressing one fires its own handler without triggering\nthe row's navigation.\n\n```jsx live\nconst App = () => (\n  <Item.Root href=\"#settings\" variant=\"outline\">\n    <Item.Media variant=\"icon\">\n      <Icons.Settings />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Settings</Item.Title>\n      <Item.Description>Navigate to your account settings</Item.Description>\n    </Item.Content>\n    <Item.Actions>\n      <IconButton aria-label=\"Remove shortcut\" size=\"xs\" variant=\"ghost\">\n        <Icons.Delete />\n      </IconButton>\n    </Item.Actions>\n  </Item.Root>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\n`Item` lays out **one horizontal content row**: leading media, a title and\ndescription column, and trailing actions, with optional full-width bands above\nand below. It is the shape behind settings rows, notification entries,\nfile/resource rows, and summary rows — the pattern teams otherwise rebuild ad\nhoc with slightly different spacing every time.\n\n`Item` is deliberately restrained. It is presentational by default and only\nbecomes interactive in one way: passing `href` upgrades the entire row to an\naccessible link. There is no button mode and no built-in selection state — real\nactions live as `Button`/`IconButton` controls inside `Item.Actions`, and\nselectable, navigable collections stay the job of `Menu`. `Item` complements\n`Card`, which composes vertical containers, the same way it complements those\ninteractive collections: each owns a different shape.\n\nTo stack several rows into a list with dividers between them, pair `Item` with\nthe separate `ItemGroup` component.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Media\n\n`Item.Media` is a fixed, non-shrinking slot for an icon, avatar, or image. Its\n`variant` sizes and shapes the content independently of the row's own `variant`:\n`default` imposes no sizing (use it for a custom-sized avatar), `icon` sizes an\ninline glyph, and `image` constrains a thumbnail into a rounded box.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"400\">\n    <Item.Root variant=\"outline\">\n      <Item.Media variant=\"icon\">\n        <Icons.Person />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Icon media</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root variant=\"outline\">\n      <Item.Media variant=\"image\">\n        <img src=\"/images/card/card-discount-template.png\" alt=\"\" />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Image media</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </Stack>\n);\n```\n\n### Size\n\nThe `size` prop scales the row's padding and gap. Use `xs` and `sm` for dense\nlists of rows, and `md` (the default) for standalone or spacious layouts.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"400\">\n    <Item.Root size=\"xs\" variant=\"outline\">\n      <Item.Content>\n        <Item.Title>Extra small</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root size=\"sm\" variant=\"outline\">\n      <Item.Content>\n        <Item.Title>Small</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root size=\"md\" variant=\"outline\">\n      <Item.Content>\n        <Item.Title>Medium (default)</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </Stack>\n);\n```\n\n### Variant\n\nThe `variant` prop controls the row's visual treatment: `plain` (default) has no\nborder or fill, `outline` adds a token-based border, and `subtle` fills the row\nwith a muted surface color.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"400\">\n    <Item.Root variant=\"plain\">\n      <Item.Content>\n        <Item.Title>Plain</Item.Title>\n        <Item.Description>No border, no fill.</Item.Description>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root variant=\"outline\">\n      <Item.Content>\n        <Item.Title>Outline</Item.Title>\n        <Item.Description>A token-based border.</Item.Description>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root variant=\"subtle\">\n      <Item.Content>\n        <Item.Title>Subtle</Item.Title>\n        <Item.Description>A muted surface fill.</Item.Description>\n      </Item.Content>\n    </Item.Root>\n  </Stack>\n);\n```\n\n### Header and footer\n\n`Item.Header` and `Item.Footer` are optional full-width bands rendered above and\nbelow the media·content·actions row — useful for a category label or a timestamp\nthat shouldn't compete with the title for horizontal space.\n\n```jsx live\nconst App = () => (\n  <Item.Root variant=\"outline\">\n    <Item.Header>\n      <Text fontWeight=\"600\">This week</Text>\n    </Item.Header>\n    <Item.Media variant=\"icon\">\n      <Icons.Person />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Weekly digest</Item.Title>\n      <Item.Description>Summarizes activity across your team.</Item.Description>\n    </Item.Content>\n    <Item.Footer>\n      <Text textStyle=\"sm\" color=\"neutral.11\">\n        Sent Monday at 9:00am\n      </Text>\n    </Item.Footer>\n  </Item.Root>\n);\n```\n\n### Link rows and actions\n\nPassing `href` upgrades the row to an accessible link — the whole row is\nkeyboard focusable and navigable. Controls placed in `Item.Actions` stay\nindependently operable: pressing one fires its own handler without triggering\nthe row's navigation.\n\n```jsx live\nconst App = () => (\n  <Item.Root href=\"#settings\" variant=\"outline\">\n    <Item.Media variant=\"icon\">\n      <Icons.Settings />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Settings</Item.Title>\n      <Item.Description>Navigate to your account settings</Item.Description>\n    </Item.Content>\n    <Item.Actions>\n      <IconButton aria-label=\"Remove shortcut\" size=\"xs\" variant=\"ghost\">\n        <Icons.Delete />\n      </IconButton>\n    </Item.Actions>\n  </Item.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": "Media",
+          "href": "#media",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variant",
+          "href": "#variant",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Header and footer",
+          "href": "#header-and-footer",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Link rows and actions",
+          "href": "#link-rows-and-actions",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            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### Presentational by default\n\n`Item.Root` renders a plain `<div>` when no `href` is provided — no role, no\naccessible name, and no focus stop of its own. Nothing in the row is announced\nas interactive unless you either pass `href` or nest real interactive controls\nin `Item.Actions`.\n\n```jsx live\nconst App = () => (\n  <Item.Root variant=\"outline\" data-testid=\"static-row\">\n    <Item.Media variant=\"icon\" aria-hidden>\n      <Icons.Person />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Profile</Item.Title>\n      <Item.Description>Name, avatar, and contact details</Item.Description>\n    </Item.Content>\n  </Item.Root>\n);\n```\n\n### Link-mode accessible name\n\nWhen `href` upgrades `Item.Root` to an `<a>`, its accessible name is computed\nthe standard way for a link: from its visible text content — the title, the\ndescription, and anything else rendered inside the row. `Item` does not wire\nup `aria-labelledby`/`aria-describedby` slots the way `Card` does, so a long\ndescription becomes part of a long announced name. If that verbosity is\nundesirable, override it explicitly with `aria-label` or `aria-labelledby`.\n\n```jsx live\nconst App = () => (\n  <Item.Root\n    href=\"#settings\"\n    variant=\"outline\"\n    aria-label=\"Open account settings\"\n  >\n    <Item.Media variant=\"icon\" aria-hidden>\n      <Icons.Settings />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Settings</Item.Title>\n      <Item.Description>\n        Manage your profile, notifications, and connected accounts\n      </Item.Description>\n    </Item.Content>\n  </Item.Root>\n);\n```\n\n### Media is decorative unless you name it\n\n`Item.Media` injects no accessible name of its own — it is a layout slot, not\na labeling one. Mark purely decorative media `aria-hidden` (as in the examples\nabove) so it doesn't add an unlabeled node to the accessibility tree. Only give\nmedia its own name when it conveys information the title and description\ndon't already state.\n\n### Actions keep an independent focus order\n\nControls placed in `Item.Actions` are always their own focusable, operable\nstops — this holds whether `Item.Root` is a plain `<div>` or a link. When the\nrow is a link, activating a control inside `Item.Actions` (by click, `Enter`,\nor `Space`) does **not** also activate the row's navigation: a capture-phase\nguard on the link cancels the row's own navigation whenever the originating\nevent comes from inside `Item.Actions`, while the action's own handler still\nruns.\n\n```jsx live\nconst App = () => (\n  <Item.Root href=\"#item-target\" variant=\"outline\">\n    <Item.Content>\n      <Item.Title>Report Q3</Item.Title>\n      <Item.Description>Opens the report</Item.Description>\n    </Item.Content>\n    <Item.Actions>\n      <IconButton aria-label=\"Delete\" size=\"xs\" variant=\"ghost\">\n        <Icons.Delete />\n      </IconButton>\n    </Item.Actions>\n  </Item.Root>\n);\n```\n\n### Interactive controls in a link row are a content-model tradeoff\n\nCombining an `href` on `Item.Root` with an interactive control in\n`Item.Actions` nests that control inside the row's `<a>`. The HTML content\nmodel disallows interactive content inside an `<a>`, so this arrangement is\ntechnically invalid — the same reason a whole row can't be a single button\n(see below).\n\nNimbus supports it anyway as the way to pair navigation with a row action: it\nis a common, well-understood pattern, the capture-phase guard above keeps the\nclick behavior correct, and the nested control remains a first-class focus\nstop. Two things to keep in mind about the tradeoff:\n\n- **Automated a11y checks won't flag it, and that's expected.** `axe`'s\n  `nested-interactive` rule only applies to elements whose role makes their\n  children presentational (for example `button`); it does **not** apply to\n  links, so a control inside a link row passes the a11y test suite. The absence\n  of a violation here is not evidence that the markup is valid.\n- **If strict content-model validity matters** in your context, don't give a\n  single row both an `href` and interactive `Item.Actions`. Make the row\n  presentational (a `<div>`) and let its controls stand on their own, or let\n  the whole row navigate with no competing actions.\n\n### `Item.Actions` is for controls, not links\n\nPlace JS-activated controls — `Button`, `IconButton` — in `Item.Actions`. Do\n**not** put a navigating `<a href>` there inside a link row: the row's\ncapture-phase guard cancels navigation for anything originating in\n`Item.Actions`, so the inner link would silently do nothing. If a row needs a\nsecond destination, express it as a control the guard leaves alone (an\n`onPress` that routes), or restructure so the destinations aren't nested.\n\n### No row-as-button mode\n\n`Item.Root` intentionally offers no button/pressable-row mode. Rendering the\nwhole row as a single button would announce the entire title, description,\nand media subtree as one control and would make every nested `Item.Actions`\ncontrol an invalid button-inside-button. When a row needs to perform an\naction rather than navigate, put that action in `Item.Actions` as a\n`Button`/`IconButton` — don't attach a press handler to `Item.Root` itself.\n\n### Stacking rows\n\n`Item` lays out a single row and has no opinion about the list that contains\nit. To stack multiple rows, use the separate `ItemGroup` component — see its\nown accessibility documentation for how it composes rows into a group.\n\n### Accessibility standards\n\n- **Name, role, value:** A link-mode `Item.Root` is a genuine `<a>` with a\n  computed or explicit accessible name; a non-link `Item.Root` has none, which\n  is correct for presentational content.\n- **Info and relationships:** `Item.Media`, `Item.Title`, and\n  `Item.Description` are plain, unrelated `<div>`s — nothing but visible\n  layout ties them together, so don't depend on assistive technology inferring\n  a relationship beyond DOM order.\n- **Use of color:** `variant` (`plain`/`outline`/`subtle`) and `colorPalette`\n  are visual cues only; don't use color alone to signal that a row is\n  interactive or to distinguish one row's meaning from another's — pair it\n  with visible text.\n- **Non-text content:** Keep decorative media `aria-hidden`; give meaningful\n  media (an avatar that identifies a specific person, for example) its own\n  name.\n- **Focus order / no keyboard trap:** Controls in `Item.Actions` are always\n  independent focus stops, never captured by or hidden behind the row's link.\n- **Target size:** Size interactive controls placed in `Item.Actions` (for\n  example `IconButton`) per your target-size requirements — `Item` does not\n  enforce a minimum hit area on nested controls.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Presentational by default",
+          "href": "#presentational-by-default",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Link-mode accessible name",
+          "href": "#link-mode-accessible-name",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Media is decorative unless you name it",
+          "href": "#media-is-decorative-unless-you-name-it",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Actions keep an independent focus order",
+          "href": "#actions-keep-an-independent-focus-order",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interactive controls in a link row are a content-model tradeoff",
+          "href": "#interactive-controls-in-a-link-row-are-a-content-model-tradeoff",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Item.Actions is for controls, not links",
+          "href": "#itemactions-is-for-controls-not-links",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "No row-as-button mode",
+          "href": "#no-row-as-button-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Stacking rows",
+          "href": "#stacking-rows",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            9
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Item, type ItemRootProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\n`Item` is a compound component. Wrap `Item.Media`, `Item.Content` (itself\nwrapping `Item.Title` and `Item.Description`), and `Item.Actions` inside\n`Item.Root`. `Item.Root` renders a plain `<div>` unless you pass `href`.\n\n```jsx live-dev\nconst App = () => (\n  <Item.Root variant=\"outline\">\n    <Item.Media variant=\"icon\">\n      <Icons.Person />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Profile</Item.Title>\n      <Item.Description>Name, avatar, and contact details</Item.Description>\n    </Item.Content>\n    <Item.Actions>\n      <IconButton aria-label=\"Settings\" size=\"xs\" variant=\"ghost\">\n        <Icons.Settings />\n      </IconButton>\n    </Item.Actions>\n  </Item.Root>\n);\n```\n\n## Usage examples\n\n### Sizes\n\nThe `size` prop (`xs`, `sm`, `md`) scales the row's padding and gap via the\n`nimbusItem` recipe's density tokens. `md` is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack gap=\"400\">\n    <Item.Root size=\"xs\" variant=\"outline\">\n      <Item.Media variant=\"icon\"><Icons.Person /></Item.Media>\n      <Item.Content>\n        <Item.Title>Extra small</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root size=\"sm\" variant=\"outline\">\n      <Item.Media variant=\"icon\"><Icons.Person /></Item.Media>\n      <Item.Content>\n        <Item.Title>Small</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root size=\"md\" variant=\"outline\">\n      <Item.Media variant=\"icon\"><Icons.Person /></Item.Media>\n      <Item.Content>\n        <Item.Title>Medium (default)</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </Stack>\n);\n```\n\n### Variants\n\n`variant` (`plain`, `outline`, `subtle`) controls the row's border and fill.\n`plain` is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack gap=\"400\">\n    <Item.Root variant=\"plain\">\n      <Item.Content><Item.Title>Plain (default)</Item.Title></Item.Content>\n    </Item.Root>\n    <Item.Root variant=\"outline\">\n      <Item.Content><Item.Title>Outline</Item.Title></Item.Content>\n    </Item.Root>\n    <Item.Root variant=\"subtle\">\n      <Item.Content><Item.Title>Subtle</Item.Title></Item.Content>\n    </Item.Root>\n  </Stack>\n);\n```\n\n### Media variants\n\n`Item.Media` carries its own `variant` (`default`, `icon`, `image`), applied\nvia a `data-variant` attribute rather than the shared recipe context — this\nkeeps it independent of `Item.Root`'s `variant` prop. `default` applies no\nsizing, so use it when you need to size the media yourself (for example a\ncustom avatar component).\n\n```jsx live-dev\nconst App = () => (\n  <Stack gap=\"400\">\n    <Item.Root variant=\"outline\">\n      <Item.Media variant=\"icon\">\n        <Icons.Person />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Icon media</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root variant=\"outline\">\n      <Item.Media variant=\"image\">\n        <img\n          src=\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==\"\n          alt=\"Placeholder thumbnail\"\n        />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Image media</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </Stack>\n);\n```\n\n### Header and footer bands\n\n`Item.Header` and `Item.Footer` set `flex-basis: 100%` inside the row's\n`flex-wrap` layout, so they occupy their own full-width band above or below\nthe media·content·actions line.\n\n```jsx live-dev\nconst App = () => (\n  <Item.Root variant=\"outline\">\n    <Item.Header>\n      <Text fontWeight=\"600\">Header band</Text>\n    </Item.Header>\n    <Item.Media variant=\"icon\">\n      <Icons.Person />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>With header and footer</Item.Title>\n      <Item.Description>Both bands span the full row width.</Item.Description>\n    </Item.Content>\n    <Item.Footer>\n      <Text textStyle=\"sm\">Footer band</Text>\n    </Item.Footer>\n  </Item.Root>\n);\n```\n\n### Link-upgrade\n\nPassing `href` (plus optional `target`, `rel`, `download`, `ping`,\n`referrerPolicy`, `routerOptions`, `onPress`) switches `Item.Root`'s rendered\nelement from `<div>` to `<a>` and wires it up with React Aria's `useLink` —\nthe same hook Nimbus's own `Link` uses internally. `Item`'s recipe stays\nauthoritative on appearance; `useLink` only supplies keyboard, focus, and\npress behavior.\n\n```jsx live-dev\nconst App = () => (\n  <Item.Root href=\"#item-target\" variant=\"outline\">\n    <Item.Media variant=\"icon\">\n      <Icons.Settings />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Settings</Item.Title>\n      <Item.Description>Navigate to settings</Item.Description>\n    </Item.Content>\n  </Item.Root>\n);\n```\n\n### Actions inside a link row\n\n`Item.Actions` controls remain independently operable even when `Item.Root`\nis a link: an internal capture-phase guard on the link cancels the row's own\nnavigation whenever the originating click comes from inside `Item.Actions`,\nwhile the action's own handler still runs normally. There is no button mode\nfor `Item.Root` itself — a row rendered as a `<button>` would make every\nnested `Item.Actions` control an invalid button-inside-button, so real\nactions always live in `Item.Actions`.\n\n```jsx live-dev\nconst App = () => (\n  <Item.Root href=\"#item-target\" variant=\"outline\">\n    <Item.Content>\n      <Item.Title>Report Q3</Item.Title>\n      <Item.Description>Opens the report</Item.Description>\n    </Item.Content>\n    <Item.Actions>\n      <IconButton\n        aria-label=\"Delete\"\n        size=\"xs\"\n        variant=\"ghost\"\n        onPress={() => console.log(\"delete\")}\n      >\n        <Icons.Delete />\n      </IconButton>\n    </Item.Actions>\n  </Item.Root>\n);\n```\n\n### Color palette\n\nThe row inherits the `slate` color palette by default (media, title, and\ndescription colors, plus the `subtle`/`outline` variant surfaces all read from\n`colorPalette.*` tokens). Override `colorPalette` like any other Chakra style\nprop to tint a row semantically, for example a destructive row.\n\n```jsx live-dev\nconst App = () => (\n  <Item.Root variant=\"subtle\" colorPalette=\"critical\">\n    <Item.Media variant=\"icon\">\n      <Icons.Delete />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Delete account</Item.Title>\n      <Item.Description>This action cannot be undone.</Item.Description>\n    </Item.Content>\n  </Item.Root>\n);\n```\n\n### Stacking rows with ItemGroup\n\n`Item` only lays out a single row. To stack several rows into a list, with\noptional dividers between them, wrap `Item.Root` rows in the separate\n`ItemGroup` component rather than nesting them inside one `Item.Root`.\n\n```jsx live-dev\nconst App = () => (\n  <ItemGroup.Root>\n    <Item.Root href=\"#profile\">\n      <Item.Content><Item.Title>Profile</Item.Title></Item.Content>\n    </Item.Root>\n    <ItemGroup.Separator />\n    <Item.Root href=\"#billing\">\n      <Item.Content><Item.Title>Billing</Item.Title></Item.Content>\n    </Item.Root>\n  </ItemGroup.Root>\n);\n```\n\n## Component requirements\n\n- Nest `Item.Media`, `Item.Content`, and `Item.Actions` as direct children of\n  `Item.Root`; wrap `Item.Title` and `Item.Description` inside `Item.Content`.\n- `Item.Header` and `Item.Footer` are optional and render as full-width bands;\n  place them as direct children of `Item.Root` alongside the other parts.\n- Passing `href` is the only thing that changes `Item.Root`'s rendered\n  element and interaction model — every other prop behaves the same on the\n  `<div>` and `<a>` paths.\n- `Item.Root` does not accept `as`/`asChild`; it is not polymorphic.\n\n### Accessibility\n\n`Item.Root` renders a plain, unlabeled `<div>` by default — no role or\naccessible name is implied. When it upgrades to a link, its accessible name is\ncomputed the standard way, from its visible text content (title, description,\nand any other text inside the row), unless you override it with `aria-label`\nor `aria-labelledby`. `Item.Media` injects no accessible name of its own: mark\ndecorative media `aria-hidden` (as shown in the link-upgrade example above) or\ngive it an explicit name when the media conveys information the title doesn't\nalready state.\n\nIf your use case requires tracking and analytics for this component, it is\ngood practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"settings-item-row\";\n\nexport const Example = () => (\n  <Item.Root id={PERSISTENT_ID} href=\"/settings\">\n    <Item.Content>\n      <Item.Title>Settings</Item.Title>\n    </Item.Content>\n  </Item.Root>\n);\n```\n\n#### Keyboard navigation\n\n- `Tab`: When `href` is set, the row is one focusable stop, like any link;\n  controls inside `Item.Actions` are additional, independent focusable stops.\n  Without `href`, `Item.Root` introduces no focusable stop of its own.\n- `Enter`: Activates the row's link.\n- Activating a control inside `Item.Actions` (by click, `Enter`, or `Space`)\n  does not activate the row's link, even when the row is a link.\n\n## API reference\n\n<PropsTable id=\"Item\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Item\nwithin your application. As the component's internal functionality is already\ntested by Nimbus, these patterns help you verify your integration and\napplication-specific logic.\n\n### State Management\n\nDrive a list of Item rows from application state and toggle a row's state from its own action, without navigating the row\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { useState } from \"react\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Item, IconButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Person, Settings } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"Item - State management\", () => {\n  it(\"toggles a row's pinned state from its action while leaving the link intact\", async () => {\n    const user = userEvent.setup();\n\n    type Row = { id: string; title: string; pinned: boolean };\n\n    const PinnableList = () => {\n      const [rows, setRows] = useState<Row[]>([\n        { id: \"profile\", title: \"Profile\", pinned: false },\n        { id: \"billing\", title: \"Billing\", pinned: true },\n      ]);\n\n      const togglePinned = (id: string) =>\n        setRows((prev) =>\n          prev.map((row) =>\n            row.id === id ? { ...row, pinned: !row.pinned } : row\n          )\n        );\n\n      return (\n        <div>\n          {rows.map((row) => (\n            <Item.Root key={row.id} href={`#${row.id}`} variant=\"outline\">\n              <Item.Media variant=\"icon\">\n                <Person />\n              </Item.Media>\n              <Item.Content>\n                <Item.Title>{row.title}</Item.Title>\n                <Item.Description>\n                  {row.pinned ? \"Pinned\" : \"Not pinned\"}\n                </Item.Description>\n              </Item.Content>\n              <Item.Actions>\n                <IconButton\n                  aria-label={`${row.pinned ? \"Unpin\" : \"Pin\"} ${row.title}`}\n                  size=\"xs\"\n                  variant=\"ghost\"\n                  onPress={() => togglePinned(row.id)}\n                >\n                  <Settings />\n                </IconButton>\n              </Item.Actions>\n            </Item.Root>\n          ))}\n        </div>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <PinnableList />\n      </NimbusProvider>\n    );\n\n    // Each row is a link, and each row's action is a separate control.\n    expect(screen.getAllByRole(\"link\")).toHaveLength(2);\n\n    // Activating a row action updates state without navigating the row.\n    await user.click(screen.getByRole(\"button\", { name: \"Pin Profile\" }));\n    expect(\n      screen.getByRole(\"button\", { name: \"Unpin Profile\" })\n    ).toBeInTheDocument();\n    // The row link is still present — the action did not navigate away.\n    expect(screen.getByRole(\"link\", { name: /Profile/ })).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-item--docs)\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": "Sizes",
+          "href": "#sizes",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variants",
+          "href": "#variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Media variants",
+          "href": "#media-variants",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Header and footer bands",
+          "href": "#header-and-footer-bands",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Link-upgrade",
+          "href": "#link-upgrade",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Actions inside a link row",
+          "href": "#actions-inside-a-link-row",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Color palette",
+          "href": "#color-palette",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Stacking rows with ItemGroup",
+          "href": "#stacking-rows-with-itemgroup",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "State Management",
+          "href": "#state-management",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nItem guidelines focus on keeping a single content row scannable, restrained,\nand predictable, so a page built from many rows stays easy to read and use.\n\n### Best practices\n\n- **One row, one subject:** Keep each row focused on a single item — a\n  setting, a notification, a file. Don't merge two unrelated things into one\n  row's title and description.\n- **Concise title and description:** The title should read as a short label;\n  push supporting detail into the description rather than lengthening the\n  title itself.\n- **Limited, obvious actions:** Place only the actions a row actually needs in\n  `Item.Actions`. A row crowded with icon buttons is harder to scan and harder\n  to hit accurately.\n- **Consistent rows within a group:** When several rows sit together (via\n  `ItemGroup`), keep their structure consistent — if one row has media and\n  actions, give its siblings the same shape, even if a slot is empty.\n- **Choose one interaction model per row:** A row either navigates (`href`) or\n  hosts actions (`Item.Actions`), or both together — it never behaves like a\n  button in its own right. Don't design a row that expects a whole-row click\n  to trigger something other than navigation.\n- **Match density to context:** Use `size=\"xs\"` or `size=\"sm\"` for dense\n  lists with many rows, and `size=\"md\"` for standalone or spacious rows.\n\n### Usage\n\n`Item` is the shape behind the horizontal rows that make up settings screens,\nnotification lists, and resource/file browsers — content that is naturally a\nsequence of similar, scannable lines rather than a single detailed view.\n\n> [!TIP]\\\n> When to use\n\n- **Settings and preference rows:** A label, a short description, and a\n  control or a link to a detail page.\n- **Notifications and activity entries:** An icon or avatar, a short message,\n  and optional actions like dismiss or mark-as-read.\n- **File or resource rows:** A thumbnail or type icon, a name and metadata,\n  and actions like download or delete.\n- **Navigational rows:** A row that exists purely to link somewhere else, with\n  a leading icon and a trailing chevron as the visual cue.\n\n> [!CAUTION]\\\n> When not to use\n\n- **A single, detailed item:** When you need to present a lot of information\n  about one specific thing, use `Card` or a dedicated page instead of forcing\n  it into one row.\n- **Selectable or multi-select collections:** `Item` has no selection state.\n  If users need to select one or more rows, reach for `Menu` or a purpose-built\n  selectable list instead.\n- **A row that should act like a button:** If activating the whole row should\n  trigger an action rather than navigate, don't attach a press handler to\n  `Item.Root` — put a `Button`/`IconButton` in `Item.Actions` instead.\n- **Comparing structured data across many attributes:** When rows would need\n  many aligned columns to be useful, a table communicates that better than a\n  row layout.\n\n### Content\n\nKeep a row's text short enough to scan at a glance. The title carries the\nsubject; the description adds just enough context to disambiguate it from\nits neighbors.\n\n> [!TIP]\\\n> **Do**\n>\n> - Write titles as short, specific labels (\"Two-factor authentication\", not\n>   \"Settings related to your account security\").\n> - Use the description for one supporting detail, not a second paragraph.\n\n```jsx live\nconst App = () => (\n  <Item.Root variant=\"outline\" width=\"384px\">\n    <Item.Media variant=\"icon\">\n      <Icons.Security />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Two-factor authentication</Item.Title>\n      <Item.Description>Adds a second step when you sign in.</Item.Description>\n    </Item.Content>\n    <Item.Actions>\n      <Button size=\"xs\" variant=\"outline\">Enable</Button>\n    </Item.Actions>\n  </Item.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't stack multiple unrelated facts into the title.\n> - Don't let the description grow into a paragraph — a link-mode row's\n>   accessible name is built from that same text, so a long description makes\n>   for a long, awkward announcement.\n\n```jsx live\nconst App = () => (\n  <Item.Root variant=\"outline\" width=\"384px\">\n    <Item.Content>\n      <Item.Title>Two-factor authentication and password and email</Item.Title>\n      <Item.Description>\n        Adds a second step when you sign in, also lets you change your\n        password, and also shows your current recovery email address plus a\n        button to change it if you no longer have access to it.\n      </Item.Description>\n    </Item.Content>\n  </Item.Root>\n);\n```\n\n### Actions\n\nKeep the trailing actions short, obvious, and limited to what that specific\nrow needs — a row is meant to be scanned quickly, not studied.\n\n> [!TIP]\\\n> **Do**\n>\n> - Use one primary action per row, and reach for an icon button only when its\n>   meaning is unambiguous (a trash icon for delete).\n> - When a row also links somewhere, keep any action clearly separated from\n>   the row's own navigation — for example a trailing chevron for \"go to\n>   details\" versus a distinct trash icon for \"delete this\".\n\n```jsx live\nconst App = () => (\n  <Item.Root href=\"#report\" variant=\"outline\" width=\"384px\">\n    <Item.Media variant=\"icon\">\n      <Icons.Description />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Q3 report</Item.Title>\n      <Item.Description>Updated 2 days ago</Item.Description>\n    </Item.Content>\n    <Item.Actions>\n      <IconButton aria-label=\"Delete report\" size=\"xs\" variant=\"ghost\">\n        <Icons.Delete />\n      </IconButton>\n    </Item.Actions>\n  </Item.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't crowd a row with many actions — split them into a menu behind a\n>   single overflow control instead.\n> - Don't rely on a whole-row click to do something a visible action should do\n>   instead; nested actions must stay independently operable.\n\n```jsx live\nconst App = () => (\n  <Item.Root href=\"#report\" variant=\"outline\" width=\"384px\">\n    <Item.Media variant=\"icon\">\n      <Icons.Description />\n    </Item.Media>\n    <Item.Content>\n      <Item.Title>Q3 report</Item.Title>\n      <Item.Description>Updated 2 days ago</Item.Description>\n    </Item.Content>\n    <Item.Actions>\n      <IconButton aria-label=\"Share\" size=\"xs\" variant=\"ghost\">\n        <Icons.Share />\n      </IconButton>\n      <IconButton aria-label=\"Rename\" size=\"xs\" variant=\"ghost\">\n        <Icons.Edit />\n      </IconButton>\n      <IconButton aria-label=\"Archive\" size=\"xs\" variant=\"ghost\">\n        <Icons.Archive />\n      </IconButton>\n      <IconButton aria-label=\"Delete report\" size=\"xs\" variant=\"ghost\">\n        <Icons.Delete />\n      </IconButton>\n    </Item.Actions>\n  </Item.Root>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Content",
+          "href": "#content",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Actions",
+          "href": "#actions",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}