@commercetools/nimbus-mcp 3.3.0 → 3.5.0

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

@@ -0,0 +1,413 @@
+{
+  "meta": {
+    "id": "Components-ItemGroup",
+    "title": "Item group",
+    "exportName": "ItemGroup",
+    "description": "A container that groups a set of Item rows into a vertical stack, with optional dividers between them.",
+    "lifecycleState": "Beta",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/item-group/item-group.mdx",
+    "menu": [
+      "Components",
+      "Data Display",
+      "Item group"
+    ],
+    "route": "components/data-display/item-group",
+    "tags": [
+      "component",
+      "item-group",
+      "group",
+      "list",
+      "container",
+      "rows",
+      "separator"
+    ],
+    "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": "Rows with separators",
+        "href": "#rows-with-separators",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Grouped navigation rows",
+        "href": "#grouped-navigation-rows",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "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`ItemGroup` visually groups a set of `Item` rows into a single vertical stack,\nwith an optional divider between rows. It is a **peer** of `Item` — it wraps\n`Item.Root` rows from the outside rather than nesting inside one — so it ships\nas its own component instead of an `Item.*` part.\n\n- `ItemGroup.Root` — the container. Lays its children out as a vertical stack;\n  it does not add spacing or a border of its own beyond the rows placed inside\n  it.\n- `ItemGroup.Separator` — a horizontal divider placed between rows.\n\nGrouping is purely visual: `ItemGroup.Root` does not impose a list semantic on\nits children, so any mix of presentational and linked `Item.Root` rows — divided\nby as many or as few separators as needed — is valid. See the **Accessibility\ntab** for why no `role=\"list\"` is applied.\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### Rows with separators\n\nPlace `ItemGroup.Separator` between rows to divide related but distinct pieces\nof information within the group.\n\n```jsx live\nconst App = () => (\n  <ItemGroup.Root>\n    <Item.Root>\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.Root>\n    <ItemGroup.Separator />\n    <Item.Root>\n      <Item.Media variant=\"icon\">\n        <Icons.Notifications />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Notifications</Item.Title>\n        <Item.Description>Email and push preferences</Item.Description>\n      </Item.Content>\n    </Item.Root>\n    <ItemGroup.Separator />\n    <Item.Root>\n      <Item.Media variant=\"icon\">\n        <Icons.Settings />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Settings</Item.Title>\n        <Item.Description>Workspace configuration</Item.Description>\n      </Item.Content>\n    </Item.Root>\n  </ItemGroup.Root>\n);\n```\n\n### Grouped navigation rows\n\nRows can be links (`Item.Root href=\"...\"`) just as easily as static rows; the\ngroup divides them the same way either way.\n\n```jsx live\nconst App = () => (\n  <ItemGroup.Root>\n    <Item.Root href=\"#profile\">\n      <Item.Content>\n        <Item.Title>Profile</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <ItemGroup.Separator />\n    <Item.Root href=\"#settings\">\n      <Item.Content>\n        <Item.Title>Settings</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </ItemGroup.Root>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\n`ItemGroup` visually groups a set of `Item` rows into a single vertical stack,\nwith an optional divider between rows. It is a **peer** of `Item` — it wraps\n`Item.Root` rows from the outside rather than nesting inside one — so it ships\nas its own component instead of an `Item.*` part.\n\n- `ItemGroup.Root` — the container. Lays its children out as a vertical stack;\n  it does not add spacing or a border of its own beyond the rows placed inside\n  it.\n- `ItemGroup.Separator` — a horizontal divider placed between rows.\n\nGrouping is purely visual: `ItemGroup.Root` does not impose a list semantic on\nits children, so any mix of presentational and linked `Item.Root` rows — divided\nby as many or as few separators as needed — is valid. See the **Accessibility\ntab** for why no `role=\"list\"` is applied.\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### Rows with separators\n\nPlace `ItemGroup.Separator` between rows to divide related but distinct pieces\nof information within the group.\n\n```jsx live\nconst App = () => (\n  <ItemGroup.Root>\n    <Item.Root>\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.Root>\n    <ItemGroup.Separator />\n    <Item.Root>\n      <Item.Media variant=\"icon\">\n        <Icons.Notifications />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Notifications</Item.Title>\n        <Item.Description>Email and push preferences</Item.Description>\n      </Item.Content>\n    </Item.Root>\n    <ItemGroup.Separator />\n    <Item.Root>\n      <Item.Media variant=\"icon\">\n        <Icons.Settings />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Settings</Item.Title>\n        <Item.Description>Workspace configuration</Item.Description>\n      </Item.Content>\n    </Item.Root>\n  </ItemGroup.Root>\n);\n```\n\n### Grouped navigation rows\n\nRows can be links (`Item.Root href=\"...\"`) just as easily as static rows; the\ngroup divides them the same way either way.\n\n```jsx live\nconst App = () => (\n  <ItemGroup.Root>\n    <Item.Root href=\"#profile\">\n      <Item.Content>\n        <Item.Title>Profile</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <ItemGroup.Separator />\n    <Item.Root href=\"#settings\">\n      <Item.Content>\n        <Item.Title>Settings</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </ItemGroup.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": "Rows with separators",
+          "href": "#rows-with-separators",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Grouped navigation rows",
+          "href": "#grouped-navigation-rows",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "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### Grouping role: `group`, not `list`\n\n`ItemGroup.Root` exposes its contents to assistive technology with\n`role=\"group\"`, which signals that the rows belong together. It deliberately\ndoes **not** use `role=\"list\"`: the ARIA `list` role carries an\n`aria-required-children` constraint — every child must be a `listitem`, and no\nother content is permitted — which `ItemGroup.Root` cannot guarantee, because\nit composes freely with any mix of `Item.Root` rows and `ItemGroup.Separator`\ndividers. `role=\"list\"` would produce an invalid accessibility tree the moment\na separator (or anything else) sits between rows; `role=\"group\"` carries no\nsuch constraint, so each `Item.Root` keeps its own semantics (a plain row, or a\nlink when given `href`) unaffected by the wrapper.\n\nGive the group an accessible name with `aria-label` or `aria-labelledby` when\nthe grouping isn't clear from surrounding context. The role is an overridable\ndefault — pass your own `role` to replace it.\n\n```jsx live\nconst App = () => (\n  <ItemGroup.Root aria-label=\"Account\">\n    <Item.Root href=\"#profile\">\n      <Item.Content>\n        <Item.Title>Profile</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <ItemGroup.Separator />\n    <Item.Root href=\"#settings\">\n      <Item.Content>\n        <Item.Title>Settings</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </ItemGroup.Root>\n);\n```\n\n### The separator is not a focus stop\n\n`ItemGroup.Separator` sets `role=\"separator\"` and\n`aria-orientation=\"horizontal\"`. It is a purely visual, static divider — it\ndoes not receive `tabIndex` and is not part of the focus order. This matches\nthe [WAI-ARIA `separator` role](https://www.w3.org/TR/wai-aria-1.2/#separator):\na separator is only focusable when it is also used to resize adjacent panes,\nwhich `ItemGroup.Separator` does not do here.\n\n### If you need a listbox instead\n\nIf the rows are actually selectable options rather than a purely visual\ngrouping, `ItemGroup` is not the right primitive — reach for a\nselection-aware component (e.g. `List`, `Menu`) that manages\n`listitem`/`option` semantics and keyboard navigation for you.\n\n### Accessibility standards\n\n- **Info and relationships:** `ItemGroup.Root` exposes `role=\"group\"` to tie\n  its rows together without an `aria-required-children` constraint, so a mix of\n  rows and separators stays a valid accessibility tree.\n- **Name, role, value:** `ItemGroup.Root` is a `group`; give it an accessible\n  name with `aria-label`/`aria-labelledby` when the grouping isn't clear from\n  context. `ItemGroup.Separator` exposes `role=\"separator\"` with\n  `aria-orientation=\"horizontal\"` and carries no accessible name, because it\n  conveys no information beyond the visual divide.\n- **Focus order:** neither `ItemGroup.Root` nor `ItemGroup.Separator` is a\n  focus stop; keyboard focus moves directly between the interactive content\n  inside each `Item.Root` (or the row itself, when it is a link).\n- **Semantic HTML:** each `Item.Root` keeps its own role — a plain container,\n  or an `<a>` when given `href` — unaffected by the group.\n\n### Resources\n\n- [WAI-ARIA: `group` role](https://www.w3.org/TR/wai-aria-1.2/#group)\n- [WAI-ARIA: `list` role](https://www.w3.org/TR/wai-aria-1.2/#list)\n- [WAI-ARIA: `separator` role](https://www.w3.org/TR/wai-aria-1.2/#separator)\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Grouping role: group, not list",
+          "href": "#grouping-role-group-not-list",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "The separator is not a focus stop",
+          "href": "#the-separator-is-not-a-focus-stop",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "If you need a listbox instead",
+          "href": "#if-you-need-a-listbox-instead",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            5
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Item, ItemGroup } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\n`ItemGroup` is a compound component: wrap `Item.Root` rows in\n`ItemGroup.Root`, and place `ItemGroup.Separator` between the rows that should\nbe visually divided.\n\n```jsx live-dev\nconst App = () => (\n  <ItemGroup.Root>\n    <Item.Root>\n      <Item.Content>\n        <Item.Title>Profile</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <ItemGroup.Separator />\n    <Item.Root>\n      <Item.Content>\n        <Item.Title>Settings</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </ItemGroup.Root>\n)\n```\n\n## Usage examples\n\n### Rows with media and separators\n\n`ItemGroup.Root` does not restyle the rows it wraps — each `Item.Root` keeps\nits own `variant`/`size`. Use `ItemGroup.Separator` only between rows, never\nbefore the first or after the last.\n\n```jsx live-dev\nconst App = () => (\n  <ItemGroup.Root>\n    <Item.Root>\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.Root>\n    <ItemGroup.Separator />\n    <Item.Root>\n      <Item.Media variant=\"icon\">\n        <Icons.Notifications />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Notifications</Item.Title>\n        <Item.Description>Email and push preferences</Item.Description>\n      </Item.Content>\n    </Item.Root>\n    <ItemGroup.Separator />\n    <Item.Root>\n      <Item.Media variant=\"icon\">\n        <Icons.Settings />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Settings</Item.Title>\n        <Item.Description>Workspace configuration</Item.Description>\n      </Item.Content>\n    </Item.Root>\n  </ItemGroup.Root>\n)\n```\n\n### Grouped link rows\n\nGive `Item.Root` an `href` to upgrade a row to an accessible link;\n`ItemGroup` composes with link rows the same way it composes with\npresentational ones.\n\n```jsx live-dev\nconst App = () => (\n  <ItemGroup.Root>\n    <Item.Root href=\"#profile\">\n      <Item.Content>\n        <Item.Title>Profile</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <ItemGroup.Separator />\n    <Item.Root href=\"#settings\">\n      <Item.Content>\n        <Item.Title>Settings</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </ItemGroup.Root>\n)\n```\n\n## Component requirements\n\n- Place `ItemGroup.Separator` only _between_ `Item.Root` rows — never before\n  the first row or after the last.\n- `ItemGroup.Root` exposes its rows as a `role=\"group\"` (an overridable\n  default). It does not set `role=\"list\"` — see Accessibility for why — so it\n  never constrains what you place inside it.\n- `ItemGroup.Root` only affects layout (a vertical stack); it does not read or\n  override each row's own `variant`/`size`.\n\n## Accessibility\n\n`ItemGroup.Root` exposes `role=\"group\"` so assistive tech announces the rows as\nbelonging together; give it a name with `aria-label`/`aria-labelledby` when the\ngrouping isn't clear from context. It deliberately does not use `role=\"list\"`:\nthat role requires every child to be a `listitem` and forbids other content,\nsuch as a separator, which the free-composition API here can't guarantee.\n`ItemGroup.Separator` sets `role=\"separator\"` and `aria-orientation=\"horizontal\"`;\nit is a static, non-focusable divider. See the **Accessibility tab** for the\nfull rationale.\n\n## API reference\n\n<PropsTable id=\"ItemGroup\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using\nItemGroup within your application. As the component's internal functionality\nis already tested by Nimbus, these patterns help you verify your integration\nand application-specific logic.\n\n### Async Data & State Management\n\nPopulate a group from data fetched after mount, interleave separators between rows, and update the group from a row action\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { Fragment, useEffect, useState } from \"react\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  Item,\n  ItemGroup,\n  IconButton,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\nimport { Delete } from \"@commercetools/nimbus-icons\";\n\ndescribe(\"ItemGroup - Async data and state management\", () => {\n  it(\"renders rows once data resolves and removes one via a row action\", async () => {\n    const user = userEvent.setup();\n\n    type Resource = { id: string; title: string; description: string };\n\n    const fetchResources = (): Promise<Resource[]> =>\n      Promise.resolve([\n        { id: \"spec\", title: \"Design spec\", description: \"PDF · 2.4 MB\" },\n        { id: \"assets\", title: \"Brand assets\", description: \"ZIP · 18 MB\" },\n      ]);\n\n    const FileGroup = () => {\n      const [resources, setResources] = useState<Resource[] | null>(null);\n\n      useEffect(() => {\n        let active = true;\n        void fetchResources().then((data) => {\n          if (active) setResources(data);\n        });\n        return () => {\n          active = false;\n        };\n      }, []);\n\n      if (!resources) return <span>Loading files…</span>;\n\n      return (\n        <ItemGroup.Root aria-label=\"Files\">\n          {resources.map((resource, index) => (\n            <Fragment key={resource.id}>\n              {index > 0 && <ItemGroup.Separator />}\n              <Item.Root>\n                <Item.Content>\n                  <Item.Title>{resource.title}</Item.Title>\n                  <Item.Description>{resource.description}</Item.Description>\n                </Item.Content>\n                <Item.Actions>\n                  <IconButton\n                    aria-label={`Remove ${resource.title}`}\n                    size=\"xs\"\n                    variant=\"ghost\"\n                    onPress={() =>\n                      setResources((prev) =>\n                        (prev ?? []).filter((item) => item.id !== resource.id)\n                      )\n                    }\n                  >\n                    <Delete />\n                  </IconButton>\n                </Item.Actions>\n              </Item.Root>\n            </Fragment>\n          ))}\n        </ItemGroup.Root>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <FileGroup />\n      </NimbusProvider>\n    );\n\n    // Rows appear only after the async fetch resolves.\n    expect(await screen.findByText(\"Design spec\")).toBeInTheDocument();\n    expect(screen.getByText(\"Brand assets\")).toBeInTheDocument();\n\n    // A per-row action updates the group's state.\n    await user.click(\n      screen.getByRole(\"button\", { name: \"Remove Design spec\" })\n    );\n\n    expect(screen.queryByText(\"Design spec\")).not.toBeInTheDocument();\n    expect(screen.getByText(\"Brand assets\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-itemgroup--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": "Rows with media and separators",
+          "href": "#rows-with-media-and-separators",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Grouped link rows",
+          "href": "#grouped-link-rows",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Async Data & State Management",
+          "href": "#async-data--state-management",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\n`ItemGroup` guidelines focus on using visual grouping and separators to signal\nthat a set of `Item` rows belong to the same category, without changing how\neach row behaves on its own.\n\n### Best practices\n\n- **Group related rows only:** Put rows in the same `ItemGroup.Root` because\n  they belong to the same category or section — not simply because they sit\n  next to each other on the page.\n- **Use separators sparingly:** A separator signals a boundary between\n  subsections within the group. Don't add one between every row if the whole\n  group is already a single category.\n- **Don't restyle individual rows to compensate:** `ItemGroup.Root` only\n  stacks rows vertically; each `Item.Root` keeps its own `variant` and `size`.\n  Pick a consistent `variant`/`size` across the rows in a group rather than\n  varying it row-by-row.\n- **Keep rows self-contained:** Each `Item.Root` should make sense read on its\n  own — a group is a visual convenience, not a shared sentence split across\n  rows.\n\n### Usage\n\n> [!TIP]\\\n> When to use\n\n- **A settings or preferences list:** A vertical stack of related,\n  individually navigable rows (Profile, Notifications, Settings…).\n- **A short list of linked resources:** Rows that each navigate elsewhere,\n  optionally divided into sections by separators.\n- **A summary list of key-value rows:** Presentational rows (no interaction)\n  that belong together, such as an order's line items.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Selectable options:** If a user needs to select one or more rows (a\n  listbox, a menu), use a selection-aware component instead — `ItemGroup` has\n  no selection state or keyboard navigation of its own.\n- **A single row:** If there's only one row, skip the group — it adds a\n  wrapper with no visual benefit.\n- **Unrelated content:** Don't reach for `ItemGroup` just to stack arbitrary\n  content vertically; use `Stack` for that and reserve `ItemGroup` for a set\n  of `Item` rows.\n\n```jsx live\nconst App = () => (\n  <ItemGroup.Root>\n    <Item.Root>\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.Root>\n    <ItemGroup.Separator />\n    <Item.Root>\n      <Item.Media variant=\"icon\">\n        <Icons.Notifications />\n      </Item.Media>\n      <Item.Content>\n        <Item.Title>Notifications</Item.Title>\n        <Item.Description>Email and push preferences</Item.Description>\n      </Item.Content>\n    </Item.Root>\n  </ItemGroup.Root>\n);\n```\n\n### Composition\n\nSeparators divide rows from each other — they don't set the group apart from\nits surroundings.\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't lead or trail the group with a separator.\n> - Don't place two separators back-to-back — there's no row between them to\n>   divide.\n\n```jsx live\nconst App = () => (\n  <ItemGroup.Root>\n    <ItemGroup.Separator />\n    <Item.Root>\n      <Item.Content>\n        <Item.Title>Profile</Item.Title>\n      </Item.Content>\n    </Item.Root>\n    <Item.Root>\n      <Item.Content>\n        <Item.Title>Settings</Item.Title>\n      </Item.Content>\n    </Item.Root>\n  </ItemGroup.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": "Composition",
+          "href": "#composition",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}