@commercetools/nimbus-mcp 2.10.0 → 3.0.0

package/data/docs/routes/components-layout-scrollarea.json

@@ -0,0 +1,428 @@
+{
+  "meta": {
+    "id": "Components-ScrollArea",
+    "title": "ScrollArea",
+    "exportName": "ScrollArea",
+    "description": "A scrollable container with custom-styled scrollbar overlays. Useful for constrained content areas like panels, sidebars, and dialog bodies.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/scroll-area/scroll-area.mdx",
+    "menu": [
+      "Components",
+      "Layout",
+      "ScrollArea"
+    ],
+    "route": "components/layout/scrollarea",
+    "tags": [
+      "component",
+      "scroll-area",
+      "layout",
+      "overflow",
+      "scrollbar"
+    ],
+    "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": "Orientation",
+        "href": "#orientation",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Visibility",
+        "href": "#visibility",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nScrollArea constrains content within a fixed region and provides themed\nscrollbar overlays that replace native browser scrollbars. The scrollbar\nappears on hover or during scrolling by default, keeping the interface clean\nuntil the user needs to scroll. The component is keyboard accessible — when\ncontent overflows, the area becomes focusable via Tab and scrollable with\narrow keys.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-scrollarea--docs)\n[Chakra UI ScrollArea](https://chakra-ui.com/docs/components/scroll-area)\n\n## Variables\n\nGet familiar with the features.\n\n### Orientation\n\nControl which axes are scrollable. The default is `both`, so overflow on\neither axis surfaces a visible scrollbar.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\">\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">Both (default)</Text>\n      <ScrollArea maxH=\"120px\" maxW=\"300px\" variant=\"always\">\n        <Box whiteSpace=\"nowrap\">\n          {Array.from({ length: 15 }, (_, i) => (\n            <Text key={i} fontSize=\"sm\">{\"Bidirectional content \".repeat(15)}</Text>\n          ))}\n        </Box>\n      </ScrollArea>\n    </Box>\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">Vertical</Text>\n      <ScrollArea maxH=\"120px\" w=\"300px\" orientation=\"vertical\" variant=\"always\">\n        {Array.from({ length: 15 }, (_, i) => (\n          <Text key={i} fontSize=\"sm\">Line {i + 1}: Sample content for vertical scrolling.</Text>\n        ))}\n      </ScrollArea>\n    </Box>\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">Horizontal</Text>\n      <ScrollArea maxW=\"300px\" orientation=\"horizontal\" variant=\"always\">\n        <Box whiteSpace=\"nowrap\">\n          {Array.from({ length: 5 }, (_, i) => (\n            <Text key={i} fontSize=\"sm\">{\"Horizontal content \".repeat(15)}</Text>\n          ))}\n        </Box>\n      </ScrollArea>\n    </Box>\n  </Stack>\n);\n```\n\n### Visibility\n\nThe scrollbar can appear on hover (default) or stay permanently visible.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\" direction=\"row\">\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">Hover (default)</Text>\n      <ScrollArea maxH=\"120px\" w=\"200px\">\n        {Array.from({ length: 15 }, (_, i) => (\n          <Text key={i} fontSize=\"sm\">Line {i + 1}</Text>\n        ))}\n      </ScrollArea>\n    </Box>\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">Always visible</Text>\n      <ScrollArea maxH=\"120px\" w=\"200px\" variant=\"always\">\n        {Array.from({ length: 15 }, (_, i) => (\n          <Text key={i} fontSize=\"sm\">Line {i + 1}</Text>\n        ))}\n      </ScrollArea>\n    </Box>\n  </Stack>\n);\n```\n\n### Size\n\nControl the scrollbar thickness. Available sizes: `xs`, `sm` (default), `md`, `lg`.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\" direction=\"row\" flexWrap=\"wrap\">\n    {[\"xs\", \"sm\", \"md\", \"lg\"].map((size) => (\n      <Box key={size}>\n        <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">{size}</Text>\n        <ScrollArea maxH=\"120px\" w=\"180px\" size={size} variant=\"always\">\n          {Array.from({ length: 15 }, (_, i) => (\n            <Text key={i} fontSize=\"sm\">Line {i + 1}</Text>\n          ))}\n        </ScrollArea>\n      </Box>\n    ))}\n  </Stack>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nScrollArea constrains content within a fixed region and provides themed\nscrollbar overlays that replace native browser scrollbars. The scrollbar\nappears on hover or during scrolling by default, keeping the interface clean\nuntil the user needs to scroll. The component is keyboard accessible — when\ncontent overflows, the area becomes focusable via Tab and scrollable with\narrow keys.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-scrollarea--docs)\n[Chakra UI ScrollArea](https://chakra-ui.com/docs/components/scroll-area)\n\n## Variables\n\nGet familiar with the features.\n\n### Orientation\n\nControl which axes are scrollable. The default is `both`, so overflow on\neither axis surfaces a visible scrollbar.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\">\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">Both (default)</Text>\n      <ScrollArea maxH=\"120px\" maxW=\"300px\" variant=\"always\">\n        <Box whiteSpace=\"nowrap\">\n          {Array.from({ length: 15 }, (_, i) => (\n            <Text key={i} fontSize=\"sm\">{\"Bidirectional content \".repeat(15)}</Text>\n          ))}\n        </Box>\n      </ScrollArea>\n    </Box>\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">Vertical</Text>\n      <ScrollArea maxH=\"120px\" w=\"300px\" orientation=\"vertical\" variant=\"always\">\n        {Array.from({ length: 15 }, (_, i) => (\n          <Text key={i} fontSize=\"sm\">Line {i + 1}: Sample content for vertical scrolling.</Text>\n        ))}\n      </ScrollArea>\n    </Box>\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">Horizontal</Text>\n      <ScrollArea maxW=\"300px\" orientation=\"horizontal\" variant=\"always\">\n        <Box whiteSpace=\"nowrap\">\n          {Array.from({ length: 5 }, (_, i) => (\n            <Text key={i} fontSize=\"sm\">{\"Horizontal content \".repeat(15)}</Text>\n          ))}\n        </Box>\n      </ScrollArea>\n    </Box>\n  </Stack>\n);\n```\n\n### Visibility\n\nThe scrollbar can appear on hover (default) or stay permanently visible.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\" direction=\"row\">\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">Hover (default)</Text>\n      <ScrollArea maxH=\"120px\" w=\"200px\">\n        {Array.from({ length: 15 }, (_, i) => (\n          <Text key={i} fontSize=\"sm\">Line {i + 1}</Text>\n        ))}\n      </ScrollArea>\n    </Box>\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">Always visible</Text>\n      <ScrollArea maxH=\"120px\" w=\"200px\" variant=\"always\">\n        {Array.from({ length: 15 }, (_, i) => (\n          <Text key={i} fontSize=\"sm\">Line {i + 1}</Text>\n        ))}\n      </ScrollArea>\n    </Box>\n  </Stack>\n);\n```\n\n### Size\n\nControl the scrollbar thickness. Available sizes: `xs`, `sm` (default), `md`, `lg`.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\" direction=\"row\" flexWrap=\"wrap\">\n    {[\"xs\", \"sm\", \"md\", \"lg\"].map((size) => (\n      <Box key={size}>\n        <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">{size}</Text>\n        <ScrollArea maxH=\"120px\" w=\"180px\" size={size} variant=\"always\">\n          {Array.from({ length: 15 }, (_, i) => (\n            <Text key={i} fontSize=\"sm\">Line {i + 1}</Text>\n          ))}\n        </ScrollArea>\n      </Box>\n    ))}\n  </Stack>\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": "Orientation",
+          "href": "#orientation",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visibility",
+          "href": "#visibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => (\n  <ScrollArea maxH=\"200px\" w=\"400px\" role=\"region\" aria-label=\"Example content\">\n    {Array.from({ length: 20 }, (_, i) => (\n      <Text key={i} fontSize=\"sm\">\n        Line {i + 1}: Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n      </Text>\n    ))}\n  </ScrollArea>\n);\n```\n\n### Accessibility standards\n\n- **Keyboard focusable:** The scrollable viewport receives `tabIndex={0}`\n  when content overflows on either axis, making it reachable via Tab and\n  scrollable with Arrow keys, Page Up/Down, Home, and End.\n- **Conditional focusability:** When content does not overflow, `tabIndex` is\n  not set, so the container does not appear in the Tab order unnecessarily.\n- **Keyboard-only focus ring:** A Nimbus focus ring appears on the root\n  element only during keyboard navigation (`:focus-visible`), not on mouse\n  click.\n- **Decorative scrollbars:** The custom scrollbar overlays are purely visual.\n  Actual scrolling is handled by the browser's native scroll mechanism.\n- **ARIA landmarks:** When the scroll area represents a distinct page section,\n  consider adding `role=\"region\"` with `aria-label` or `aria-labelledby` to\n  create a named landmark for screen reader navigation.\n- **No keyboard trap:** Standard browser tab order is maintained. Focus moves\n  naturally into and out of the scroll area.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { ScrollArea, type ScrollAreaProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nWrap content in a `ScrollArea` with a size constraint. The scrollbar appears on\nhover or during scrolling:\n\n```jsx live-dev\nconst App = () => (\n  <ScrollArea maxH=\"200px\" w=\"400px\">\n    {Array.from({ length: 20 }, (_, i) => (\n      <Text key={i} fontSize=\"sm\">\n        Line {i + 1}: Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n      </Text>\n    ))}\n  </ScrollArea>\n)\n```\n\n## Usage examples\n\n### Orientation\n\nUse the `orientation` prop to control which scrollbar axes are rendered:\n\n```jsx live-dev\nconst App = () => (\n  <Stack gap=\"600\">\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">both (default)</Text>\n      <ScrollArea maxH=\"120px\" maxW=\"300px\" variant=\"always\">\n        <Box whiteSpace=\"nowrap\">\n          {Array.from({ length: 15 }, (_, i) => (\n            <Text key={i} fontSize=\"sm\">{\"Both axes content \".repeat(15)}</Text>\n          ))}\n        </Box>\n      </ScrollArea>\n    </Box>\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">vertical</Text>\n      <ScrollArea maxH=\"120px\" w=\"300px\" orientation=\"vertical\" variant=\"always\">\n        {Array.from({ length: 15 }, (_, i) => (\n          <Text key={i} fontSize=\"sm\">Line {i + 1}</Text>\n        ))}\n      </ScrollArea>\n    </Box>\n    <Box>\n      <Text fontSize=\"sm\" mb=\"200\" fontWeight=\"bold\">horizontal</Text>\n      <ScrollArea maxW=\"300px\" orientation=\"horizontal\" variant=\"always\">\n        <Box whiteSpace=\"nowrap\">\n          {Array.from({ length: 5 }, (_, i) => (\n            <Text key={i} fontSize=\"sm\">{\"Long horizontal content \".repeat(15)}</Text>\n          ))}\n        </Box>\n      </ScrollArea>\n    </Box>\n  </Stack>\n)\n```\n\n### Content padding\n\nPadding props on `ScrollArea` are forwarded to the content area inside the\nscrollable viewport, so `p`, `px`, `py`, etc. work as expected:\n\n```jsx live-dev\nconst App = () => (\n  <ScrollArea maxH=\"200px\" w=\"400px\" bg=\"neutral.2\" borderRadius=\"300\" variant=\"always\" p=\"200\">\n    {Array.from({ length: 20 }, (_, i) => (\n      <Text key={i} fontSize=\"sm\">\n        Line {i + 1}: Lorem ipsum dolor sit amet, consectetur adipiscing elit.\n      </Text>\n    ))}\n  </ScrollArea>\n)\n```\n\n### Programmatic scroll access\n\n#### Using `viewportRef`\n\nUse the `viewportRef` prop to get a direct reference to the scrollable viewport\nelement. This is the recommended approach when you need to programmatically\nscroll, attach scroll event listeners, or read scroll position. The ref gives\nyou direct access to the native DOM `scrollTo()` method:\n\n```tsx\nconst viewportRef = useRef<HTMLDivElement>(null);\n\n<ScrollArea viewportRef={viewportRef} maxH=\"400px\">\n  {content}\n</ScrollArea>\n\n// Native DOM scrollTo — same API as any scrollable element\nviewportRef.current.scrollTo({ top: 0, behavior: 'smooth' })\n// Or: viewportRef.current.addEventListener('scroll', handler)\n```\n\n#### Using `ids`\n\nWhen ref-forwarding is impractical (e.g., the scroll container is rendered in a\ndifferent component tree), use the `ids` prop to set a known ID on the viewport\nelement for `getElementById` access:\n\n```tsx\n<ScrollArea ids={{ viewport: 'my-scroll-viewport' }} maxH=\"400px\">\n  {content}\n</ScrollArea>\n\n// Later: document.getElementById('my-scroll-viewport').scrollTop\n```\n\n#### Using `useScrollArea` (external control)\n\nWhen you need to read scroll state or call scroll methods from *outside* the\n`ScrollArea` tree (e.g., in a parent component), create the machine externally\nwith `useScrollArea` and pass it via the `value` prop. Unlike `viewportRef`\n(which gives you a native DOM element), the `useScrollArea` hook returns a\nstate-machine API with scroll state and convenience methods:\n\n```tsx\nimport { ScrollArea, useScrollArea } from '@commercetools/nimbus';\n\nfunction ParentComponent() {\n  const scrollArea = useScrollArea();\n\n  return (\n    <>\n      <button onClick={() => scrollArea.scrollToEdge({ edge: 'top' })}>\n        Scroll to top\n      </button>\n      <p>Has vertical overflow: {String(scrollArea.hasOverflowY)}</p>\n      <ScrollArea maxH=\"400px\" value={scrollArea}>\n        {content}\n      </ScrollArea>\n    </>\n  );\n}\n```\n\nThe returned object exposes state (`hasOverflowX`, `hasOverflowY`, `isAtTop`,\n`isAtBottom`, `isAtLeft`, `isAtRight`) and methods (`scrollTo()`,\n`scrollToEdge()`, `getScrollProgress()`).\n\n#### Using `useScrollAreaContext` (internal access)\n\nFor components rendered *inside* a `ScrollArea`, the `useScrollAreaContext` hook\nreads the existing machine from React context — no `value` prop needed:\n\n```tsx\nimport { useScrollAreaContext } from '@commercetools/nimbus';\n\nfunction ScrollToTopButton() {\n  const { scrollToEdge, isAtTop } = useScrollAreaContext();\n  if (isAtTop) return null;\n  return <Button onPress={() => scrollToEdge({ edge: 'top', behavior: 'smooth' })}>Back to top</Button>;\n}\n```\n\n## Component requirements\n\n- The component must have a size constraint (`maxH`, `maxW`, `h`, `w`) for scrolling to occur\n\n## Accessibility\n\nThe ScrollArea component ensures keyboard accessibility:\n\n- **Keyboard focusable**: The scrollable viewport receives `tabIndex={0}` when content overflows, making it reachable via Tab\n- **Focus ring**: A Nimbus focus ring appears on the root element when the viewport receives keyboard focus (via `:focus-visible`)\n- **ARIA landmarks**: When the scroll area represents a distinct page section, consider adding `role=\"region\"` with an `aria-label` or `aria-labelledby` to create a named landmark for screen reader navigation\n\n## API reference\n\n<PropsTable id=\"ScrollArea\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using ScrollArea within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Usage\n\nBasic vertical scrollable container\n\n```tsx\nimport React from \"react\";\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport {\n  ScrollArea,\n  NimbusProvider,\n  useScrollArea,\n  Box,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ScrollArea - Basic usage\", () => {\n  it(\"renders children inside a scrollable container\", () => {\n    render(\n      <NimbusProvider>\n        <ScrollArea maxH=\"200px\">\n          <OverflowingContent />\n        </ScrollArea>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Line 1\")).toBeInTheDocument();\n  });\n\n  it(\"renders with always-visible scrollbars\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <ScrollArea maxH=\"200px\" variant=\"always\">\n          <OverflowingContent />\n        </ScrollArea>\n      </NimbusProvider>\n    );\n\n    expect(\n      container.querySelector('[data-part=\"scrollbar\"]')\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### Orientation\n\nControlling which scrollbar axes render\n\n```tsx\nimport React from \"react\";\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport {\n  ScrollArea,\n  NimbusProvider,\n  useScrollArea,\n  Box,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ScrollArea - Orientation\", () => {\n  it(\"renders horizontal scrollbar\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <ScrollArea maxW=\"300px\" orientation=\"horizontal\">\n          <Box whiteSpace=\"nowrap\">\n            <Text>{\"Wide content \".repeat(30)}</Text>\n          </Box>\n        </ScrollArea>\n      </NimbusProvider>\n    );\n\n    const scrollbar = container.querySelector('[data-part=\"scrollbar\"]');\n    expect(scrollbar).toHaveAttribute(\"data-orientation\", \"horizontal\");\n  });\n\n  it(\"renders both axes with a corner\", () => {\n    const { container } = render(\n      <NimbusProvider>\n        <ScrollArea maxH=\"200px\" maxW=\"300px\" orientation=\"both\">\n          <Box whiteSpace=\"nowrap\">\n            <OverflowingContent />\n          </Box>\n        </ScrollArea>\n      </NimbusProvider>\n    );\n\n    const scrollbars = container.querySelectorAll('[data-part=\"scrollbar\"]');\n    expect(scrollbars).toHaveLength(2);\n    expect(container.querySelector('[data-part=\"corner\"]')).toBeInTheDocument();\n  });\n});\n```\n\n### Programmatic scroll access\n\nAccessing the scrollable viewport via ref or external hook\n\n```tsx\nimport React from \"react\";\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport {\n  ScrollArea,\n  NimbusProvider,\n  useScrollArea,\n  Box,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ScrollArea - Programmatic access\", () => {\n  it(\"forwards a ref to the viewport via viewportRef\", () => {\n    const ref = React.createRef<HTMLDivElement>();\n\n    render(\n      <NimbusProvider>\n        <ScrollArea maxH=\"200px\" viewportRef={ref}>\n          <OverflowingContent />\n        </ScrollArea>\n      </NimbusProvider>\n    );\n\n    expect(ref.current).toHaveAttribute(\"data-part\", \"viewport\");\n    expect(typeof ref.current?.scrollTo).toBe(\"function\");\n  });\n\n  it(\"supports external control via useScrollArea + value prop\", () => {\n    const ExternalControl = () => {\n      const scrollArea = useScrollArea();\n      return (\n        <ScrollArea maxH=\"200px\" value={scrollArea}>\n          <OverflowingContent />\n        </ScrollArea>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <ExternalControl />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Line 1\")).toBeInTheDocument();\n  });\n});\n```\n\n### Content Padding\n\nApplying padding via an inner Box wrapper\n\n```tsx\nimport React from \"react\";\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport {\n  ScrollArea,\n  NimbusProvider,\n  useScrollArea,\n  Box,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ScrollArea - Content padding\", () => {\n  it(\"renders padded content via a nested Box\", () => {\n    render(\n      <NimbusProvider>\n        <ScrollArea maxH=\"200px\">\n          <Box p=\"200\">\n            <OverflowingContent />\n          </Box>\n        </ScrollArea>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Line 1\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-scrollarea--docs)\n- [Chakra UI ScrollArea](https://chakra-ui.com/docs/components/scroll-area)\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": "Orientation",
+          "href": "#orientation",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Content padding",
+          "href": "#content-padding",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Programmatic scroll access",
+          "href": "#programmatic-scroll-access",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Using viewportRef",
+          "href": "#using-viewportref",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Using ids",
+          "href": "#using-ids",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Using useScrollArea (external control)",
+          "href": "#using-usescrollarea-external-control",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Using useScrollAreaContext (internal access)",
+          "href": "#using-usescrollareacontext-internal-access",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            3,
+            4
+          ],
+          "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": "Basic Usage",
+          "href": "#basic-usage-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Orientation",
+          "href": "#orientation-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Programmatic scroll access",
+          "href": "#programmatic-scroll-access-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Content Padding",
+          "href": "#content-padding-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}

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",