@commercetools/nimbus-mcp 2.11.0 → 3.1.0

package/data/docs/routes/components-media-avatar.json

@@ -180,7 +180,7 @@
       ]
     },
     "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  <Avatar firstName=\"Adam\" lastName=\"Vadam\" src=\"https://thispersondoesnotexist.com/ \" />\n)\n```\n\n### Accessibility standards\n\n- **Non-text content:** Avatars must have a text alternative. Use the `alt`\n  attribute on the `<img>` tag (if the avatar is an image) or through `ARIA` if\n  the avatar is more complex. The alt text should describe the avatar's purpose\n  or what it represents (e.g., \"User profile picture,\" \"John Doe's avatar,\"\n  \"Company logo\"). If the avatar is purely decorative and doesn't convey any\n  meaningful information, the alt attribute should be empty (`alt=\"\"`).\n- **Info and relationships:** If the avatar is associated with other information\n  (e.g., a username, profile link), the relationship should be programmatically\n  determinable. This can be achieved using semantic `HTML` (e.g., placing the\n  avatar and username within a single element) or ARIA attributes (e.g.,\n  `aria-labelledby` or `aria-describedby`).\n- **Use of color:** Don't rely on color alone to convey information about the\n  avatar (e.g., using a colored border to indicate status). Any information\n  conveyed by color must also be available through other means.\n- **Color contrast:** If the avatar contains any text (which is less common),\n  that text must meet minimum contrast ratio requirements.\n- **Keyboard accessibility:** If the avatar is interactive (e.g., clicking it\n  opens a profile), it must be operable using the keyboard. Users should be able\n  to navigate to the avatar using the Tab key and activate it using the Enter or\n  Space key.\n- **Link purpose:** If the avatar is a link, its purpose should be clear from\n  the surrounding context or from the avatar's alt text. Avoid generic link text\n  like \"Click here.\"\n- **Focus visible:** If the avatar is interactive, it should have a visible\n  focus indicator when it receives keyboard focus.\n- **On focus:** If the avatar is interactive and its appearance changes on\n  focus, the change should not be disorienting or unexpected.\n- **Name, role, value:** Assistive technologies should be able to correctly\n  interpret the role of the avatar (e.g., `image`, `link`) and its name (from\n  the alt text).\n",
+      "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  <Avatar firstName=\"Adam\" lastName=\"Vadam\" src=\"https://thispersondoesnotexist.com/ \" />\n)\n```\n\n### Accessibility standards\n\n- **Non-text content:** Avatars must have a text alternative. Use the `alt`\n  attribute on the `<img>` tag (if the avatar is an image) or through `ARIA` if\n  the avatar is more complex. The alt text should describe the avatar's purpose\n  or what it represents (e.g., \"User profile picture,\" \"John Doe's avatar,\"\n  \"Company logo\"). If the avatar is purely decorative and doesn't convey any\n  meaningful information, the alt attribute should be empty (`alt=\"\"`).\n- **Generic label fallback:** When `firstName` and `lastName` are both\n  missing, empty, or whitespace-only, the Avatar renders a generic\n  `Person` icon and applies a localized generic `aria-label`\n  (`\"User avatar\"` in English, with translations for all supported\n  locales). This guarantees screen readers always announce a meaningful\n  label even when user identity data is incomplete. Consumers can still\n  override with an explicit `aria-label` prop when more specific context\n  is available.\n- **Info and relationships:** If the avatar is associated with other information\n  (e.g., a username, profile link), the relationship should be programmatically\n  determinable. This can be achieved using semantic `HTML` (e.g., placing the\n  avatar and username within a single element) or ARIA attributes (e.g.,\n  `aria-labelledby` or `aria-describedby`).\n- **Use of color:** Don't rely on color alone to convey information about the\n  avatar (e.g., using a colored border to indicate status). Any information\n  conveyed by color must also be available through other means.\n- **Color contrast:** If the avatar contains any text (which is less common),\n  that text must meet minimum contrast ratio requirements.\n- **Keyboard accessibility:** If the avatar is interactive (e.g., clicking it\n  opens a profile), it must be operable using the keyboard. Users should be able\n  to navigate to the avatar using the Tab key and activate it using the Enter or\n  Space key.\n- **Link purpose:** If the avatar is a link, its purpose should be clear from\n  the surrounding context or from the avatar's alt text. Avoid generic link text\n  like \"Click here.\"\n- **Focus visible:** If the avatar is interactive, it should have a visible\n  focus indicator when it receives keyboard focus.\n- **On focus:** If the avatar is interactive and its appearance changes on\n  focus, the change should not be disorienting or unexpected.\n- **Name, role, value:** Assistive technologies should be able to correctly\n  interpret the role of the avatar (e.g., `image`, `link`) and its name (from\n  the alt text).\n",
       "toc": [
         {
           "value": "Accessibility",
@@ -206,7 +206,7 @@
       ]
     },
     "dev": {
-      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Avatar, type AvatarProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\nThe simplest implementation displays an avatar with initials derived from first\nand last names:\n\n```jsx live-dev\nconst App = () => (\n  <Avatar firstName=\"John\" lastName=\"Doe\" />\n)\n```\n\n## Usage examples\n\n### Size options\n\nThe `2xs`, `xs`, and `md` size variants are available to match your interface\ndensity:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"2xs\" />\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"xs\" />\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"md\" />\n  </Stack>\n)\n```\n\n### Color palettes\n\nAvatars support different color palettes to convey semantic meaning or match\nyour design theme:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" lastName=\"Doe\" colorPalette=\"primary\" />\n    <Avatar firstName=\"Jane\" lastName=\"Smith\" colorPalette=\"positive\" />\n    <Avatar firstName=\"Alex\" lastName=\"Chen\" colorPalette=\"info\" />\n    <Avatar firstName=\"Maria\" lastName=\"Garcia\" colorPalette=\"critical\" />\n    <Avatar firstName=\"Sam\" lastName=\"Wilson\" colorPalette=\"cyan\" />\n  </Stack>\n)\n```\n\n### With image\n\nWhen a `src` prop is provided, the Avatar displays the image. If the image fails\nto load, it automatically falls back to initials:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar\n      firstName=\"Jane\"\n      lastName=\"Smith\"\n      src=\"https://i.pravatar.cc/150?img=1\"\n      alt=\"Jane Smith's profile picture\"\n    />\n    <Avatar\n      firstName=\"Alex\"\n      lastName=\"Johnson\"\n      src=\"https://i.pravatar.cc/150?img=2\"\n      alt=\"Alex Johnson's profile picture\"\n    />\n  </Stack>\n)\n```\n\n### Initials fallback\n\nThe Avatar automatically extracts and displays initials from the provided first\nand last names. This serves as a fallback when no image is available or when the\nimage fails to load:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Avatar\n      firstName=\"Maria\"\n      lastName=\"Garcia\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n    <Avatar\n      firstName=\"Chen\"\n      lastName=\"Wei\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n    <Avatar\n      firstName=\"Aisha\"\n      lastName=\"Patel\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n  </Stack>\n)\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Avatar component handles most accessibility requirements internally,\nincluding automatic labeling with the user's full name.\n\n- **Labeling**: The component automatically generates an internationalized\n  accessible label from the `firstName` and `lastName` props. When providing an\n  image via the `src` prop, always include an `alt` attribute for screen\n  readers.\n- **Role**: Renders as a `<figure>` element with an `aria-label` that includes\n  the full name (e.g., \"Avatar image for John Doe\").\n\nIf your use case requires tracking and analytics for this component, it is good\npractice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-avatar\";\n\nexport const Example = () => (\n  <Avatar id={PERSISTENT_ID} firstName=\"John\" lastName=\"Doe\" />\n);\n```\n\n#### Keyboard navigation\n\nAvatars are non-interactive elements and do not receive focus or support\nkeyboard interaction by default. If you need to make an avatar interactive\n(e.g., clickable), wrap it in a button or interactive element:\n\n```tsx\n<button onClick={handleClick} aria-label=\"View profile\">\n  <Avatar firstName=\"John\" lastName=\"Doe\" />\n</button>\n```\n\n## API reference\n\n<PropsTable id=\"Avatar\" />\n\n## Common patterns\n\n### User profile header\n\nCombine Avatar with text components to create a user profile header:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar\n      firstName=\"Sarah\"\n      lastName=\"Johnson\"\n      src=\"https://i.pravatar.cc/150?img=5\"\n      size=\"md\"\n    />\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"md\" fontWeight=\"600\">Sarah Johnson</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">Product Manager</Text>\n    </Stack>\n  </Stack>\n)\n```\n\n### Comment or message list\n\nDisplay avatars alongside user content in comments or messages:\n\n```jsx live-dev\nconst App = () => {\n  const comments = [\n    { id: 1, author: { firstName: \"Alex\", lastName: \"Chen\" }, text: \"Great work on this feature!\", time: \"2 hours ago\" },\n    { id: 2, author: { firstName: \"Maria\", lastName: \"Garcia\" }, text: \"I agree, this is really helpful.\", time: \"1 hour ago\" },\n    { id: 3, author: { firstName: \"James\", lastName: \"Wilson\" }, text: \"Looking forward to the next update.\", time: \"30 minutes ago\" },\n  ];\n\n  return (\n    <Stack direction=\"column\" gap=\"600\">\n      {comments.map((comment) => (\n        <Stack key={comment.id} direction=\"row\" gap=\"400\">\n          <Avatar\n            firstName={comment.author.firstName}\n            lastName={comment.author.lastName}\n            size=\"xs\"\n          />\n          <Stack direction=\"column\" gap=\"100\" flex=\"1\">\n            <Stack direction=\"row\" gap=\"200\" alignItems=\"baseline\">\n              <Text fontSize=\"sm\" fontWeight=\"600\">\n                {comment.author.firstName} {comment.author.lastName}\n              </Text>\n              <Text fontSize=\"xs\" color=\"neutral.11\">{comment.time}</Text>\n            </Stack>\n            <Text fontSize=\"sm\">{comment.text}</Text>\n          </Stack>\n        </Stack>\n      ))}\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Avatar\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### Basic rendering tests\n\nVerify the Avatar renders with expected elements and labels\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Basic rendering\", () => {\n  it(\"renders avatar with initials\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"figure\")).toBeInTheDocument();\n    expect(screen.getByLabelText(/John Doe/i)).toBeInTheDocument();\n    expect(screen.getByText(\"JD\")).toBeInTheDocument();\n  });\n\n  it(\"renders avatar with image\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar\n          firstName=\"Jane\"\n          lastName=\"Smith\"\n          src=\"https://example.com/avatar.jpg\"\n          alt=\"Jane Smith profile\"\n        />\n      </NimbusProvider>\n    );\n\n    const image = screen.getByAltText(\"Jane Smith profile\");\n    expect(image).toBeInTheDocument();\n    expect(image).toHaveAttribute(\"src\", \"https://example.com/avatar.jpg\");\n  });\n});\n```\n\n### Size variant tests\n\nTest different size options\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Size variants\", () => {\n  it(\"renders different sizes correctly\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"2xs\" />\n      </NimbusProvider>\n    );\n\n    let avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"xs\" />\n      </NimbusProvider>\n    );\n\n    avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"md\" />\n      </NimbusProvider>\n    );\n\n    avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n  });\n});\n```\n\n### Accessibility tests\n\nVerify accessibility attributes and labeling\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Accessibility\", () => {\n  it(\"has correct aria-label with full name\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar firstName=\"Maria\" lastName=\"Garcia\" />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByLabelText(/Maria Garcia/i);\n    expect(avatar).toBeInTheDocument();\n    expect(avatar.tagName).toBe(\"FIGURE\");\n  });\n\n  it(\"applies custom id for tracking\", () => {\n    const PERSISTENT_ID = \"test-avatar-id\";\n\n    render(\n      <NimbusProvider>\n        <Avatar id={PERSISTENT_ID} firstName=\"John\" lastName=\"Doe\" />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByRole(\"figure\");\n    expect(avatar).toHaveAttribute(\"id\", PERSISTENT_ID);\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-avatar--docs)\n",
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Avatar, type AvatarProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\nThe simplest implementation displays an avatar with initials derived from first\nand last names:\n\n```jsx live-dev\nconst App = () => (\n  <Avatar firstName=\"John\" lastName=\"Doe\" />\n)\n```\n\n## Usage examples\n\n### Size options\n\nThe `2xs`, `xs`, and `md` size variants are available to match your interface\ndensity:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"2xs\" />\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"xs\" />\n    <Avatar firstName=\"John\" lastName=\"Doe\" size=\"md\" />\n  </Stack>\n)\n```\n\n### Color palettes\n\nAvatars support different color palettes to convey semantic meaning or match\nyour design theme:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" lastName=\"Doe\" colorPalette=\"primary\" />\n    <Avatar firstName=\"Jane\" lastName=\"Smith\" colorPalette=\"positive\" />\n    <Avatar firstName=\"Alex\" lastName=\"Chen\" colorPalette=\"info\" />\n    <Avatar firstName=\"Maria\" lastName=\"Garcia\" colorPalette=\"critical\" />\n    <Avatar firstName=\"Sam\" lastName=\"Wilson\" colorPalette=\"cyan\" />\n  </Stack>\n)\n```\n\n### With image\n\nWhen a `src` prop is provided, the Avatar displays the image. If the image fails\nto load, it automatically falls back to initials:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar\n      firstName=\"Jane\"\n      lastName=\"Smith\"\n      src=\"https://i.pravatar.cc/150?img=1\"\n      alt=\"Jane Smith's profile picture\"\n    />\n    <Avatar\n      firstName=\"Alex\"\n      lastName=\"Johnson\"\n      src=\"https://i.pravatar.cc/150?img=2\"\n      alt=\"Alex Johnson's profile picture\"\n    />\n  </Stack>\n)\n```\n\n### Initials fallback\n\nThe Avatar automatically extracts and displays initials from the provided first\nand last names. This serves as a fallback when no image is available or when the\nimage fails to load:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Avatar\n      firstName=\"Maria\"\n      lastName=\"Garcia\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n    <Avatar\n      firstName=\"Chen\"\n      lastName=\"Wei\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n    <Avatar\n      firstName=\"Aisha\"\n      lastName=\"Patel\"\n      src=\"https://www.gravatar.com/avatar/thisWill404?s=200&d=404\" />\n  </Stack>\n)\n```\n\n### Missing or partial names\n\n`firstName` and `lastName` are both **optional**. The Avatar handles missing,\nempty, and whitespace-only values defensively:\n\n- If only one name is usable (after trimming whitespace), a single initial\n  is rendered.\n- If neither name yields a usable character, a generic `Person` icon is\n  rendered as the fallback and a localized generic `aria-label`\n  (`\"User avatar\"`) is applied.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar firstName=\"John\" />            {/* renders \"J\" */}\n    <Avatar lastName=\"Doe\" />              {/* renders \"D\" */}\n    <Avatar firstName=\"\" lastName=\"\" />    {/* renders the Person icon */}\n    <Avatar />                             {/* renders the Person icon */}\n  </Stack>\n)\n```\n\nThis is intended for cases where user records have incomplete name data —\ncommon in legacy systems and partial profiles. The component's TypeScript\ncontract permits `undefined` so call sites do not need non-null assertions\nor empty-string fallbacks.\n\nInitials extraction is also Unicode codepoint-safe (emoji and astral-plane\ncharacters are not split mid-surrogate) and trim-aware (leading/trailing\nwhitespace is discarded before extracting the first character).\n\n## Component requirements\n\n## Accessibility\n\nThe Avatar component handles most accessibility requirements internally,\nincluding automatic labeling with the user's full name.\n\n- **Labeling**: The component automatically generates an internationalized\n  accessible label from the `firstName` and `lastName` props. When providing an\n  image via the `src` prop, always include an `alt` attribute for screen\n  readers.\n- **Role**: Renders as a `<figure>` element with an `aria-label` that includes\n  the full name (e.g., \"Avatar image for John Doe\").\n\nIf your use case requires tracking and analytics for this component, it is good\npractice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-avatar\";\n\nexport const Example = () => (\n  <Avatar id={PERSISTENT_ID} firstName=\"John\" lastName=\"Doe\" />\n);\n```\n\n#### Keyboard navigation\n\nAvatars are non-interactive elements and do not receive focus or support\nkeyboard interaction by default. If you need to make an avatar interactive\n(e.g., clickable), wrap it in a button or interactive element:\n\n```tsx\n<button onClick={handleClick} aria-label=\"View profile\">\n  <Avatar firstName=\"John\" lastName=\"Doe\" />\n</button>\n```\n\n## API reference\n\n<PropsTable id=\"Avatar\" />\n\n## Common patterns\n\n### User profile header\n\nCombine Avatar with text components to create a user profile header:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Avatar\n      firstName=\"Sarah\"\n      lastName=\"Johnson\"\n      src=\"https://i.pravatar.cc/150?img=5\"\n      size=\"md\"\n    />\n    <Stack direction=\"column\" gap=\"100\">\n      <Text fontSize=\"md\" fontWeight=\"600\">Sarah Johnson</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">Product Manager</Text>\n    </Stack>\n  </Stack>\n)\n```\n\n### Comment or message list\n\nDisplay avatars alongside user content in comments or messages:\n\n```jsx live-dev\nconst App = () => {\n  const comments = [\n    { id: 1, author: { firstName: \"Alex\", lastName: \"Chen\" }, text: \"Great work on this feature!\", time: \"2 hours ago\" },\n    { id: 2, author: { firstName: \"Maria\", lastName: \"Garcia\" }, text: \"I agree, this is really helpful.\", time: \"1 hour ago\" },\n    { id: 3, author: { firstName: \"James\", lastName: \"Wilson\" }, text: \"Looking forward to the next update.\", time: \"30 minutes ago\" },\n  ];\n\n  return (\n    <Stack direction=\"column\" gap=\"600\">\n      {comments.map((comment) => (\n        <Stack key={comment.id} direction=\"row\" gap=\"400\">\n          <Avatar\n            firstName={comment.author.firstName}\n            lastName={comment.author.lastName}\n            size=\"xs\"\n          />\n          <Stack direction=\"column\" gap=\"100\" flex=\"1\">\n            <Stack direction=\"row\" gap=\"200\" alignItems=\"baseline\">\n              <Text fontSize=\"sm\" fontWeight=\"600\">\n                {comment.author.firstName} {comment.author.lastName}\n              </Text>\n              <Text fontSize=\"xs\" color=\"neutral.11\">{comment.time}</Text>\n            </Stack>\n            <Text fontSize=\"sm\">{comment.text}</Text>\n          </Stack>\n        </Stack>\n      ))}\n    </Stack>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Avatar\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### Basic rendering tests\n\nVerify the Avatar renders with expected elements and labels\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Basic rendering\", () => {\n  it(\"renders avatar with initials\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"figure\")).toBeInTheDocument();\n    expect(screen.getByLabelText(/John Doe/i)).toBeInTheDocument();\n    expect(screen.getByText(\"JD\")).toBeInTheDocument();\n  });\n\n  it(\"renders avatar with image\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar\n          firstName=\"Jane\"\n          lastName=\"Smith\"\n          src=\"https://example.com/avatar.jpg\"\n          alt=\"Jane Smith profile\"\n        />\n      </NimbusProvider>\n    );\n\n    const image = screen.getByAltText(\"Jane Smith profile\");\n    expect(image).toBeInTheDocument();\n    expect(image).toHaveAttribute(\"src\", \"https://example.com/avatar.jpg\");\n  });\n});\n```\n\n### Size variant tests\n\nTest different size options\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Size variants\", () => {\n  it(\"renders different sizes correctly\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"2xs\" />\n      </NimbusProvider>\n    );\n\n    let avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"xs\" />\n      </NimbusProvider>\n    );\n\n    avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" lastName=\"Doe\" size=\"md\" />\n      </NimbusProvider>\n    );\n\n    avatar = screen.getByRole(\"figure\");\n    expect(avatar).toBeInTheDocument();\n  });\n});\n```\n\n### Accessibility tests\n\nVerify accessibility attributes and labeling\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Accessibility\", () => {\n  it(\"has correct aria-label with full name\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar firstName=\"Maria\" lastName=\"Garcia\" />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByLabelText(/Maria Garcia/i);\n    expect(avatar).toBeInTheDocument();\n    expect(avatar.tagName).toBe(\"FIGURE\");\n  });\n\n  it(\"applies custom id for tracking\", () => {\n    const PERSISTENT_ID = \"test-avatar-id\";\n\n    render(\n      <NimbusProvider>\n        <Avatar id={PERSISTENT_ID} firstName=\"John\" lastName=\"Doe\" />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByRole(\"figure\");\n    expect(avatar).toHaveAttribute(\"id\", PERSISTENT_ID);\n  });\n});\n```\n\n### Missing-name fallback tests\n\nVerify the Avatar renders a generic icon and label when\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Avatar, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Avatar - Missing names\", () => {\n  it(\"renders the Person icon and generic aria-label when both names are missing\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByRole(\"figure\");\n    // Generic localized aria-label (\"Generic user avatar\" in English)\n    expect(avatar).toHaveAttribute(\"aria-label\", \"Generic user avatar\");\n    // Person icon is rendered as the visual fallback\n    expect(avatar.querySelector(\"svg\")).not.toBeNull();\n    // No initials text is rendered\n    expect(avatar.textContent?.trim()).toBe(\"\");\n  });\n\n  it(\"renders a single initial when only firstName is provided\", () => {\n    render(\n      <NimbusProvider>\n        <Avatar firstName=\"John\" />\n      </NimbusProvider>\n    );\n\n    const avatar = screen.getByRole(\"figure\");\n    expect(avatar.textContent?.trim()).toBe(\"J\");\n    expect(avatar.querySelector(\"svg\")).toBeNull();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-avatar--docs)\n",
       "toc": [
         {
           "value": "Getting started",
@@ -294,6 +294,17 @@
           ],
           "parent": "root"
         },
+        {
+          "value": "Missing or partial names",
+          "href": "#missing-or-partial-names",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
         {
           "value": "Component requirements",
           "href": "#component-requirements",
@@ -411,6 +422,17 @@
           ],
           "parent": "root"
         },
+        {
+          "value": "Missing-name fallback tests",
+          "href": "#missing-name-fallback-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
         {
           "value": "Resources",
           "href": "#resources",

package/data/docs/routes/components-utilities-region.json

@@ -0,0 +1,265 @@
+{
+  "meta": {
+    "id": "Components-Region",
+    "title": "Region",
+    "exportName": "Region",
+    "description": "A headless primitive for named content projection — render content into a named region elsewhere in the layout while it stays in your React tree.",
+    "lifecycleState": "Beta",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/region/region.mdx",
+    "menu": [
+      "Components",
+      "Utilities",
+      "Region"
+    ],
+    "route": "components/utilities/region",
+    "tags": [
+      "component",
+      "utility",
+      "portal",
+      "layout",
+      "provider"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "When to use",
+        "href": "#when-to-use",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "When not to use",
+        "href": "#when-not-to-use",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Anatomy",
+        "href": "#anatomy",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Example",
+        "href": "#example",
+        "depth": 2,
+        "numbering": [
+          1,
+          5
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nRegion is a headless primitive for **named content projection**: render content\ninto a slot somewhere else in the layout — an aside, a toolbar, a detail pane —\nfrom a component that lives somewhere else entirely, even a different package.\n\nIt is the structured form of `createPortal`. You **place a target** with\n`<Region name=\"…\" />` to mark where a region renders, and **fill it** from\nanywhere with `useRegion(name)`. Projected content paints at the target but stays\na child of its author in the React tree, so all ancestor context — routing, intl,\ndata clients, permissions — is preserved. A target can also publish a **value**\n(typically control callbacks plus state), so its host can hand consumers a way to\ndrive it.\n\nThe scope, `Region.Provider`, is mounted **ambiently inside `NimbusProvider`**, so\nin a Nimbus app you place targets and call `useRegion` without ever wrapping a\nprovider yourself.\n\nRegion renders no visual chrome of its own; it is a coordination primitive, not\na styled component.\n\n## When to use\n\n- A shell or layout owns a slot (a side panel, a header action area) that a\n  feature elsewhere needs to fill.\n- Content must be **authored** deep in the tree (to keep its context) but\n  **rendered** at a fixed location.\n- A target's host wants to expose controls (open/close, select) to whoever fills\n  it, without prop-drilling.\n\nFor a user-resizable two-pane layout, compose Region with\n[Splitter](/components/layout/splitter): mount the splitter, put a\n`<Region name=\"…\" />` in the aside, and let a consumer fill it and toggle it — see\nthe implementation tab.\n\n## When not to use\n\n- You own both the content and its location and they're in the same place — just\n  render it directly.\n- You need overlay portalling (modals, tooltips, popovers) — those are handled\n  by the overlay components, not Region.\n\n## Anatomy\n\n- **`<Region name=\"…\" />`** — the **target**: marks where a named region renders\n  and registers its DOM node. It is layout-transparent (`display: contents`), so\n  projected content lays out as a direct child of the target's parent — no extra\n  wrapper box. Backed by a `chakra.div`, so it accepts style props; pass\n  `display=\"block\"` (etc.) if you want it to be a real box. Can publish a `value`.\n- **`useRegion(name)`** — returns a stable `Region` portal component to fill the\n  named region, plus the `value` its target published. Resolves safely (`null`\n  value, portal renders nothing) before a target mounts.\n- **`Region.Provider`** — the scope. Mounted ambiently by `NimbusProvider`;\n  reuses an ancestor's scope when nested, so you rarely write it directly.\n\nNote the two sides share the name `Region`: the top-level `<Region name>` is the\n**target**, while the `Region` you get from `useRegion` is the **filler**. Place\nwith the former, fill with the latter.\n\n## Example\n\n```jsx live-dev\nconst Sidebar = () => {\n  // fill the region — `Region` here is the filler from the hook\n  const { Region: Filler } = useRegion(\"docs-sidebar\");\n  return (\n    <Filler>\n      <Box p=\"300\" bg=\"teal.3\">\n        Authored over here, painted in the target over there.\n      </Box>\n    </Filler>\n  );\n};\n\nconst App = () => (\n  // No Region.Provider needed — NimbusProvider supplies the scope ambiently.\n  <Stack direction=\"row\" gap=\"400\">\n    <Box flexGrow=\"1\" p=\"300\" bg=\"amber.3\">\n      <Text>Content area</Text>\n      <Sidebar />\n    </Box>\n    <Box width=\"240px\" minHeight=\"120px\" bg=\"neutral.3\" p=\"200\">\n      <Region name=\"docs-sidebar\" />\n    </Box>\n  </Stack>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nRegion is a headless primitive for **named content projection**: render content\ninto a slot somewhere else in the layout — an aside, a toolbar, a detail pane —\nfrom a component that lives somewhere else entirely, even a different package.\n\nIt is the structured form of `createPortal`. You **place a target** with\n`<Region name=\"…\" />` to mark where a region renders, and **fill it** from\nanywhere with `useRegion(name)`. Projected content paints at the target but stays\na child of its author in the React tree, so all ancestor context — routing, intl,\ndata clients, permissions — is preserved. A target can also publish a **value**\n(typically control callbacks plus state), so its host can hand consumers a way to\ndrive it.\n\nThe scope, `Region.Provider`, is mounted **ambiently inside `NimbusProvider`**, so\nin a Nimbus app you place targets and call `useRegion` without ever wrapping a\nprovider yourself.\n\nRegion renders no visual chrome of its own; it is a coordination primitive, not\na styled component.\n\n## When to use\n\n- A shell or layout owns a slot (a side panel, a header action area) that a\n  feature elsewhere needs to fill.\n- Content must be **authored** deep in the tree (to keep its context) but\n  **rendered** at a fixed location.\n- A target's host wants to expose controls (open/close, select) to whoever fills\n  it, without prop-drilling.\n\nFor a user-resizable two-pane layout, compose Region with\n[Splitter](/components/layout/splitter): mount the splitter, put a\n`<Region name=\"…\" />` in the aside, and let a consumer fill it and toggle it — see\nthe implementation tab.\n\n## When not to use\n\n- You own both the content and its location and they're in the same place — just\n  render it directly.\n- You need overlay portalling (modals, tooltips, popovers) — those are handled\n  by the overlay components, not Region.\n\n## Anatomy\n\n- **`<Region name=\"…\" />`** — the **target**: marks where a named region renders\n  and registers its DOM node. It is layout-transparent (`display: contents`), so\n  projected content lays out as a direct child of the target's parent — no extra\n  wrapper box. Backed by a `chakra.div`, so it accepts style props; pass\n  `display=\"block\"` (etc.) if you want it to be a real box. Can publish a `value`.\n- **`useRegion(name)`** — returns a stable `Region` portal component to fill the\n  named region, plus the `value` its target published. Resolves safely (`null`\n  value, portal renders nothing) before a target mounts.\n- **`Region.Provider`** — the scope. Mounted ambiently by `NimbusProvider`;\n  reuses an ancestor's scope when nested, so you rarely write it directly.\n\nNote the two sides share the name `Region`: the top-level `<Region name>` is the\n**target**, while the `Region` you get from `useRegion` is the **filler**. Place\nwith the former, fill with the latter.\n\n## Example\n\n```jsx live-dev\nconst Sidebar = () => {\n  // fill the region — `Region` here is the filler from the hook\n  const { Region: Filler } = useRegion(\"docs-sidebar\");\n  return (\n    <Filler>\n      <Box p=\"300\" bg=\"teal.3\">\n        Authored over here, painted in the target over there.\n      </Box>\n    </Filler>\n  );\n};\n\nconst App = () => (\n  // No Region.Provider needed — NimbusProvider supplies the scope ambiently.\n  <Stack direction=\"row\" gap=\"400\">\n    <Box flexGrow=\"1\" p=\"300\" bg=\"amber.3\">\n      <Text>Content area</Text>\n      <Sidebar />\n    </Box>\n    <Box width=\"240px\" minHeight=\"120px\" bg=\"neutral.3\" p=\"200\">\n      <Region name=\"docs-sidebar\" />\n    </Box>\n  </Stack>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use",
+          "href": "#when-to-use",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When not to use",
+          "href": "#when-not-to-use",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Anatomy",
+          "href": "#anatomy",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Example",
+          "href": "#example",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Region, useRegion, type RegionProps } from \"@commercetools/nimbus\";\n```\n\n### Mental model\n\n`Region` is the structured form of `createPortal`. Three pieces:\n\n- **`<Region name=\"…\" />`** — the **target**: marks where a named region renders.\n  It registers its DOM node under `name` and can publish a `value` (control\n  callbacks + state) for consumers.\n- **`useRegion(name)`** — returns `{ Region, value }`: a stable `Region` portal\n  component to **fill** the target, and the published `value`.\n- **`Region.Provider`** — the scope. **Mounted ambiently by `NimbusProvider`**, so\n  in a Nimbus app you never write it: place targets and call `useRegion`\n  directly. It is still exported for standalone use (tests, non-Nimbus roots).\n\nRegions are addressed by **name**, not by tree position — a consumer reaches a\nregion by name regardless of how deeply nested it is. `useRegion` resolves to a\n`null` value (and a portal that renders nothing) before a target mounts, so it is\nalways safe to call.\n\n> **One name, two sides.** The top-level `<Region name>` is the *target*; the\n> `Region` returned by `useRegion` is the *filler*. They can't share a binding in\n> one scope — alias the hook's: `const { Region: Sidebar } = useRegion(\"x\")`.\n\n> **Single occupancy.** A region name is one-to-one on both sides: **exactly one\n> target** and **at most one active filler** at a time. Two targets sharing a name\n> orphan one another (only the last to mount holds the slot); two fillers stack\n> their content into the one target in an undefined order. Both are bugs, so in\n> development each logs a `console.error` naming the region. The fix is always the\n> same — give each its own name. (The registry also releases a target's slot\n> owner-checked, so a stale duplicate unmounting never wipes the live region.)\n\n### Basic usage\n\nContent rendered through the `Region` filler paints at the target but stays a\nchild of its author in the React tree, so all ancestor context (router, intl,\ndata client, permissions) is preserved.\n\n```jsx live-dev\nconst Sidebar = () => {\n  const { Region: Filler } = useRegion(\"getting-started-sidebar\");\n  return (\n    <Filler>\n      <Box p=\"300\" bg=\"teal.3\">\n        Authored here, painted in the target.\n      </Box>\n    </Filler>\n  );\n};\n\n// No Region.Provider — NimbusProvider supplies the scope ambiently.\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Box flexGrow=\"1\" p=\"300\" bg=\"amber.3\">\n      <Text>Content area</Text>\n      <Sidebar />\n    </Box>\n    <Box width=\"240px\" minHeight=\"120px\" bg=\"neutral.3\" p=\"200\">\n      <Region name=\"getting-started-sidebar\" />\n    </Box>\n  </Stack>\n);\n```\n\n## Layout: the target renders no box (`display: contents`)\n\nA portal needs a real DOM node as its container — there is no API to portal \"into\na position.\" So `<Region name>` must render *an* element. But it renders that\nelement with **`display: contents`**, which makes the element generate **no box of\nits own**: its children participate in the layout of the target's *parent*, as if\nthe wrapper were not there. Since projected content are DOM children of that\nelement, they lay out exactly where the target sits — a flex/grid parent treats\nthe projected root as a direct child. You get precise layout with no extra wrapper.\n\nConsequences worth knowing:\n\n- A `display: contents` element can't carry its own visual box — no background,\n  padding, border, `position: relative`, or scroll container. Put those on the\n  **projected content** (or the target's parent) instead.\n- The target is a `chakra.div`, so it accepts style props. To make it a real box\n  again, override the display: `<Region name=\"x\" display=\"block\" p=\"400\" />`.\n\n## Publishing a value\n\nA target can publish a `value` so its host hands consumers a way to drive it —\ntypically control callbacks plus reactive state. Consumers read it from\n`useRegion(name).value`.\n\n```tsx\n// host: publish controls on the target\n<Region name=\"detail\" value={{ isOpen, open, close }} />;\n\n// consumer: read them\nconst { value } = useRegion<DetailControls>(\"detail\");\nvalue?.open();\n```\n\nType the value at the consumer boundary with `useRegion<T>` — the registry treats\nit as opaque, so the generic is where the shape is declared.\n\n## Composition: a shell-owned side panel (with Splitter)\n\n`Region` composes with [Splitter](/components/layout/splitter) to build a\nshell-owned, remotely-controlled side panel — **without the Splitter depending on\nRegion**. The shell mounts the splitter, puts a `<Region name>` in the aside that\npublishes the collapse controls, and drives the splitter through its existing\ncontrolled `collapsed` / `onCollapsedChange`. A consumer anywhere fills the pane\nand opens/closes it via `useRegion`.\n\n```tsx\nconst ShellSidePanel = ({ children }) => {\n  const [open, setOpen] = useState(false);\n\n  // Stable callbacks; value memoized on the reactive bit (see Performance below).\n  const commands = useRef({\n    expand: () => setOpen(true),\n    collapse: () => setOpen(false),\n    toggle: () => setOpen((o) => !o),\n  }).current;\n  const controller = useMemo(\n    () => ({ isCollapsed: !open, ...commands }),\n    [open, commands]\n  );\n\n  return (\n    <Splitter.Root collapsible collapsed={!open} onCollapsedChange={(c) => setOpen(!c)}>\n      <Splitter.Main>{children}</Splitter.Main>\n      <Splitter.Handle />\n      <Splitter.Aside>\n        <Region name=\"app-side-panel\" value={controller} />\n      </Splitter.Aside>\n    </Splitter.Root>\n  );\n};\n\n// A consumer that owns no splitter markup:\nconst SidePanel = ({ panel }) => {\n  const { Region: Aside, value } = useRegion(\"app-side-panel\");\n  const expand = value?.expand;\n  const collapse = value?.collapse;\n  useEffect(() => {\n    expand?.();\n    return () => collapse?.();\n  }, [expand, collapse]);\n  return <Aside>{panel}</Aside>;\n};\n```\n\n## Performance\n\n`Region.Provider` wraps the entire application (it's inside `NimbusProvider`), so\nfilling a region must not re-render the app. That holds because of four things —\none in the primitive, three at your call site:\n\n1. **External store (primitive).** The registry is read via\n   `useSyncExternalStore`. Publishing a node or value notifies only that name's\n   consumers; `Region.Provider` itself never re-renders.\n2. **Stable `children` (host).** Pass the app through as a `children` prop so the\n   host's own state changes (e.g. a collapse toggle) bail out of the app subtree\n   rather than re-rendering it.\n3. **Stable callbacks + memoized value (host).** Keep published callbacks\n   ref-backed so their identity never changes, and `useMemo` the value object on\n   its reactive field. Registering then only churns when something meaningful\n   changes.\n4. **Depend on the callbacks, not the value object (consumer).** A published\n   value object changes identity when its reactive state changes. In effects,\n   depend on the stable callbacks (`value?.expand`), not the whole `value` —\n   otherwise an expand-on-mount effect re-runs on every state change and can\n   ping-pong.\n\n## SSR\n\n`useRegion` and the `Region` filler use a server snapshot of `null`: there are no\ntargets during server rendering and `createPortal` is client-only. A region\ntherefore resolves to nothing on the server and hydrates on the client. Author\ncontent unconditionally and let the portal render it once the target mounts.\n\n## Nested providers share one namespace\n\n`Region.Provider` reuses an ancestor's registry when nested — it does not create\nan isolated scope. Two targets with the same name collide even if they live under\ndifferent `Region.Provider` wrappers. If you need logical isolation between\nsubsystems, use a naming convention (e.g. `\"app-shell:sidebar\"` vs\n`\"admin:sidebar\"`).\n\n## When not to use\n\n- You own both the content and its location and they're co-located — render it\n  directly.\n- You need overlay portalling (modals, tooltips, popovers) — use the overlay\n  components, not `Region`.\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": "Mental model",
+          "href": "#mental-model",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Layout: the target renders no box (display: contents)",
+          "href": "#layout-the-target-renders-no-box-display-contents",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Publishing a value",
+          "href": "#publishing-a-value",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Composition: a shell-owned side panel (with Splitter)",
+          "href": "#composition-a-shell-owned-side-panel-with-splitter",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Performance",
+          "href": "#performance",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "SSR",
+          "href": "#ssr",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Nested providers share one namespace",
+          "href": "#nested-providers-share-one-namespace",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When not to use",
+          "href": "#when-not-to-use",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}