@commercetools/nimbus-mcp 3.2.0 → 3.3.0

package/data/docs/routes/components-buttons-button.json

@@ -375,7 +375,7 @@
       ]
     },
     "dev": {
-      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Button, type ButtonProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe Button component wraps React Aria's `useButton` hook to provide accessible, interactive elements.\n\n```jsx live-dev\nconst App = () => (\n  <Button onPress={() => alert('Button pressed')}>\n    Action\n  </Button>\n)\n```\n\n## Usage examples\n\n### Size options\n\nButton supports three size variants to match different interface densities. The `md` size is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Button size=\"2xs\">2XS Button</Button>\n    <Button size=\"xs\">XS Button</Button>\n    <Button size=\"sm\">SM Button</Button>\n    <Button size=\"md\">MD Button (Default)</Button>\n  </Stack>\n)\n```\n\n### Visual variants\n\nChoose between five visual variants to match your design context. The `subtle` variant is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n    <Button variant=\"solid\">Solid</Button>\n    <Button variant=\"subtle\">Subtle (Default)</Button>\n    <Button variant=\"outline\">Outline</Button>\n    <Button variant=\"ghost\">Ghost</Button>\n    <Button variant=\"link\">Link</Button>\n  </Stack>\n)\n```\n\n### Color palette options\n\nThe Button component supports all semantic color palettes to convey meaning and hierarchy. The `primary` color palette is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n      <Button colorPalette=\"primary\">Primary (Default)</Button>\n      <Button colorPalette=\"neutral\">Neutral</Button>\n      <Button colorPalette=\"info\">Info</Button>\n    </Stack>\n    <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n      <Button colorPalette=\"positive\">Positive</Button>\n      <Button colorPalette=\"warning\">Warning</Button>\n      <Button colorPalette=\"critical\">Critical</Button>\n    </Stack>\n  </Stack>\n)\n```\n\nYou can also override the color palette using Chakra UI style props for one-off customizations:\n\n```jsx live-dev\nconst App = () => (\n  <Button backgroundColor=\"purple.9\" color=\"purple.contrast\" _hover={{ backgroundColor: \"purple.10\" }}>\n    Custom Purple Button\n  </Button>\n)\n```\n\n### With icons\n\nButtons automatically handle spacing between icons and text. You can place icons before or after the text.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Button>\n      <Icons.Add />\n      Add Item\n    </Button>\n    <Button variant=\"outline\">\n      Next\n      <Icons.ArrowForward />\n    </Button>\n  </Stack>\n)\n```\n\n### As link\n\nUse the `as` prop to render the button as an anchor tag while maintaining button styling. This is useful for navigation links that need to look like actions.\n\n```jsx live-dev\nconst App = () => (\n  <Button as=\"a\" href=\"#\" variant=\"link\">\n    Go to Home\n  </Button>\n)\n```\n\n### Disabled state\n\nUse the `isDisabled` prop to prevent interaction. This visualizes the button as disabled and removes it from the tab order.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Button isDisabled variant=\"solid\">Disabled Solid</Button>\n    <Button isDisabled variant=\"outline\">Disabled Outline</Button>\n  </Stack>\n)\n```\n\n### Event handling\n\nUse `onPress` instead of `onClick` for consistent behavior across mouse, touch, and keyboard interactions.\n\n```jsx live-dev\nconst App = () => {\n  const [count, setCount] = useState(0);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Button onPress={() => setCount(c => c + 1)}>\n        Increment\n      </Button>\n      <Text>Count: {count}</Text>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Button component handles most accessibility requirements internally via React Aria.\n\n- **Labeling**: Ensure the button has a visible label (children) or an `aria-label` if it contains only an icon.\n- **Role**: Renders as `button` by default, or `link` (a tag) when using `as=\"a\"`.\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"submit-order-button\";\n\nexport const Example = () => (\n  <Button id={PERSISTENT_ID}>Submit</Button>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab`: Focuses the button.\n- `Enter` or `Space`: Activates the button (triggers `onPress`).\n\n## API reference\n\n<PropsTable id=\"Button\" />\n\n## Common patterns\n\n### Loading state\n\nWhile the Button component doesn't have a built-in `isLoading` prop yet, you can implement a loading state by disabling the button and showing a spinner.\n\n```jsx live-dev\nconst App = () => {\n  const [isLoading, setIsLoading] = useState(false);\n\n  const handleClick = () => {\n    setIsLoading(true);\n    // Simulate async action\n    setTimeout(() => setIsLoading(false), 2000);\n  };\n\n  return (\n    <Button \n      isDisabled={isLoading} \n      onPress={handleClick}\n    >\n      {isLoading ? 'Loading...' : 'Save Changes'}\n    </Button>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Button in 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 Rendering Tests\n\nVerify the Button renders with expected content and attributes\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Basic rendering\", () => {\n  it(\"renders with correct text\", () => {\n    render(\n      <NimbusProvider>\n        <Button>Click me</Button>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /click me/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders with custom data attributes\", () => {\n    render(\n      <NimbusProvider>\n        <Button data-testid=\"my-button\">Action</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"my-button\")).toBeInTheDocument();\n  });\n\n  it(\"renders as an anchor element when using the as prop\", () => {\n    render(\n      <NimbusProvider>\n        <Button as=\"a\" href=\"/home\" data-testid=\"link-button\">\n          Go Home\n        </Button>\n      </NimbusProvider>\n    );\n\n    const element = screen.getByTestId(\"link-button\");\n    expect(element.tagName).toBe(\"A\");\n    expect(element).toHaveAttribute(\"href\", \"/home\");\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the Button\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Interactions\", () => {\n  it(\"calls onPress when clicked\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Button onPress={handlePress}>Action</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /action/i });\n    await user.click(button);\n\n    expect(handlePress).toHaveBeenCalledTimes(1);\n  });\n\n  it(\"does not call onPress when disabled\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Button isDisabled onPress={handlePress}>\n          Action\n        </Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /action/i });\n    await user.click(button);\n\n    expect(handlePress).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Keyboard Navigation Tests\n\nTest keyboard interactions with the Button\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Keyboard navigation\", () => {\n  it(\"is focusable with Tab key\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Button>Focus me</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /focus me/i });\n    await user.tab();\n\n    expect(button).toHaveFocus();\n  });\n\n  it(\"can be activated with Enter key\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Button onPress={handlePress}>Press me</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /press me/i });\n    button.focus();\n\n    await user.keyboard(\"{Enter}\");\n\n    expect(handlePress).toHaveBeenCalledTimes(1);\n  });\n\n  it(\"can be activated with Space key\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Button onPress={handlePress}>Press me</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /press me/i });\n    button.focus();\n\n    await user.keyboard(\" \");\n\n    expect(handlePress).toHaveBeenCalledTimes(1);\n  });\n});\n```\n\n### State Tests\n\nTest different states of the Button\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - States\", () => {\n  it(\"applies disabled state on native button\", () => {\n    render(\n      <NimbusProvider>\n        <Button isDisabled>Disabled</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /disabled/i });\n    expect(button).toBeDisabled();\n  });\n\n  it(\"is not focusable when disabled\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Button isDisabled>Cannot focus</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /cannot focus/i });\n    await user.tab();\n\n    expect(button).not.toHaveFocus();\n  });\n});\n```\n\n### Visual Variant Tests\n\nTest rendering with different visual variants and sizes\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Visual variants\", () => {\n  it(\"renders with different size variants\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Button size=\"sm\">Small</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Button size=\"md\">Medium</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n\n  it(\"renders with different visual variants\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Button variant=\"solid\">Solid</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Button variant=\"outline\">Outline</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n\n  it(\"renders with color palettes\", () => {\n    render(\n      <NimbusProvider>\n        <Button colorPalette=\"primary\" variant=\"solid\">\n          Primary\n        </Button>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /primary/i })\n    ).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-buttons-button--docs)\n- [React Aria Button](https://react-spectrum.adobe.com/react-aria/Button.html)\n\n",
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Button, type ButtonProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe Button component wraps React Aria's `useButton` hook to provide accessible, interactive elements.\n\n```jsx live-dev\nconst App = () => (\n  <Button onPress={() => alert('Button pressed')}>\n    Action\n  </Button>\n)\n```\n\n## Usage examples\n\n### Size options\n\nButton supports three size variants to match different interface densities. The `md` size is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <Button size=\"2xs\">2XS Button</Button>\n    <Button size=\"xs\">XS Button</Button>\n    <Button size=\"sm\">SM Button</Button>\n    <Button size=\"md\">MD Button (Default)</Button>\n  </Stack>\n)\n```\n\n### Visual variants\n\nChoose between five visual variants to match your design context. The `subtle` variant is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n    <Button variant=\"solid\">Solid</Button>\n    <Button variant=\"subtle\">Subtle (Default)</Button>\n    <Button variant=\"outline\">Outline</Button>\n    <Button variant=\"ghost\">Ghost</Button>\n    <Button variant=\"link\">Link</Button>\n  </Stack>\n)\n```\n\n### Color palette options\n\nThe Button component supports all semantic color palettes to convey meaning and hierarchy. The `primary` color palette is the default.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n      <Button colorPalette=\"primary\">Primary (Default)</Button>\n      <Button colorPalette=\"neutral\">Neutral</Button>\n      <Button colorPalette=\"info\">Info</Button>\n    </Stack>\n    <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n      <Button colorPalette=\"positive\">Positive</Button>\n      <Button colorPalette=\"warning\">Warning</Button>\n      <Button colorPalette=\"critical\">Critical</Button>\n    </Stack>\n  </Stack>\n)\n```\n\nYou can also override the color palette using Chakra UI style props for one-off customizations:\n\n```jsx live-dev\nconst App = () => (\n  <Button backgroundColor=\"purple.9\" color=\"purple.contrast\" _hover={{ backgroundColor: \"purple.10\" }}>\n    Custom Purple Button\n  </Button>\n)\n```\n\n### With icons\n\nButtons automatically handle spacing between icons and text. You can place icons before or after the text.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Button>\n      <Icons.Add />\n      Add Item\n    </Button>\n    <Button variant=\"outline\">\n      Next\n      <Icons.ArrowForward />\n    </Button>\n  </Stack>\n)\n```\n\n### As link\n\nUse the `as` prop to render the button as an anchor tag while maintaining button styling. This is useful for navigation links that need to look like actions.\n\n```jsx live-dev\nconst App = () => (\n  <Button as=\"a\" href=\"#\" variant=\"link\">\n    Go to Home\n  </Button>\n)\n```\n\n### Disabled state\n\nUse the `isDisabled` prop to prevent interaction. This visualizes the button as disabled and removes it from the tab order.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Button isDisabled variant=\"solid\">Disabled Solid</Button>\n    <Button isDisabled variant=\"outline\">Disabled Outline</Button>\n  </Stack>\n)\n```\n\n#### Keeping a disabled button focusable (for tooltips)\n\nA natively disabled button cannot receive focus or hover, so it cannot host a\n`Tooltip` — exactly when you'd want one to explain why the action is\nunavailable. Add `allowFocusWhenDisabled` alongside `isDisabled` to keep the\nbutton focusable and hoverable while it stays disabled: it renders\n`aria-disabled` instead of the native `disabled` attribute, stays in the tab\norder, and suppresses activation (press, click, `Enter`/`Space`, form submit,\nand link navigation).\n\n```jsx live-dev\nconst App = () => (\n  <Tooltip.Root>\n    <Button isDisabled allowFocusWhenDisabled>\n      Publish\n    </Button>\n    <Tooltip.Content>\n      Complete all required fields before publishing.\n    </Tooltip.Content>\n  </Tooltip.Root>\n)\n```\n\n### Event handling\n\nUse `onPress` instead of `onClick` for consistent behavior across mouse, touch, and keyboard interactions.\n\n```jsx live-dev\nconst App = () => {\n  const [count, setCount] = useState(0);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Button onPress={() => setCount(c => c + 1)}>\n        Increment\n      </Button>\n      <Text>Count: {count}</Text>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Button component handles most accessibility requirements internally via React Aria.\n\n- **Labeling**: Ensure the button has a visible label (children) or an `aria-label` if it contains only an icon.\n- **Role**: Renders as `button` by default, or `link` (a tag) when using `as=\"a\"`.\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"submit-order-button\";\n\nexport const Example = () => (\n  <Button id={PERSISTENT_ID}>Submit</Button>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n- `Tab`: Focuses the button.\n- `Enter` or `Space`: Activates the button (triggers `onPress`).\n\n## API reference\n\n<PropsTable id=\"Button\" />\n\n## Common patterns\n\n### Loading state\n\nWhile the Button component doesn't have a built-in `isLoading` prop yet, you can implement a loading state by disabling the button and showing a spinner.\n\n```jsx live-dev\nconst App = () => {\n  const [isLoading, setIsLoading] = useState(false);\n\n  const handleClick = () => {\n    setIsLoading(true);\n    // Simulate async action\n    setTimeout(() => setIsLoading(false), 2000);\n  };\n\n  return (\n    <Button \n      isDisabled={isLoading} \n      onPress={handleClick}\n    >\n      {isLoading ? 'Loading...' : 'Save Changes'}\n    </Button>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Button in 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 Rendering Tests\n\nVerify the Button renders with expected content and attributes\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Button, NimbusProvider, Tooltip } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Basic rendering\", () => {\n  it(\"renders with correct text\", () => {\n    render(\n      <NimbusProvider>\n        <Button>Click me</Button>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /click me/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders with custom data attributes\", () => {\n    render(\n      <NimbusProvider>\n        <Button data-testid=\"my-button\">Action</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"my-button\")).toBeInTheDocument();\n  });\n\n  it(\"renders as an anchor element when using the as prop\", () => {\n    render(\n      <NimbusProvider>\n        <Button as=\"a\" href=\"/home\" data-testid=\"link-button\">\n          Go Home\n        </Button>\n      </NimbusProvider>\n    );\n\n    const element = screen.getByTestId(\"link-button\");\n    expect(element.tagName).toBe(\"A\");\n    expect(element).toHaveAttribute(\"href\", \"/home\");\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the Button\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Button, NimbusProvider, Tooltip } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Interactions\", () => {\n  it(\"calls onPress when clicked\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Button onPress={handlePress}>Action</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /action/i });\n    await user.click(button);\n\n    expect(handlePress).toHaveBeenCalledTimes(1);\n  });\n\n  it(\"does not call onPress when disabled\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Button isDisabled onPress={handlePress}>\n          Action\n        </Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /action/i });\n    await user.click(button);\n\n    expect(handlePress).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Keyboard Navigation Tests\n\nTest keyboard interactions with the Button\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Button, NimbusProvider, Tooltip } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Keyboard navigation\", () => {\n  it(\"is focusable with Tab key\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Button>Focus me</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /focus me/i });\n    await user.tab();\n\n    expect(button).toHaveFocus();\n  });\n\n  it(\"can be activated with Enter key\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Button onPress={handlePress}>Press me</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /press me/i });\n    button.focus();\n\n    await user.keyboard(\"{Enter}\");\n\n    expect(handlePress).toHaveBeenCalledTimes(1);\n  });\n\n  it(\"can be activated with Space key\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Button onPress={handlePress}>Press me</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /press me/i });\n    button.focus();\n\n    await user.keyboard(\" \");\n\n    expect(handlePress).toHaveBeenCalledTimes(1);\n  });\n});\n```\n\n### State Tests\n\nTest different states of the Button\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Button, NimbusProvider, Tooltip } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - States\", () => {\n  it(\"applies disabled state on native button\", () => {\n    render(\n      <NimbusProvider>\n        <Button isDisabled>Disabled</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /disabled/i });\n    expect(button).toBeDisabled();\n  });\n\n  it(\"is not focusable when disabled\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Button isDisabled>Cannot focus</Button>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /cannot focus/i });\n    await user.tab();\n\n    expect(button).not.toHaveFocus();\n  });\n});\n```\n\n### Tooltip on a disabled Button\n\nPair `isDisabled` with `allowFocusWhenDisabled` to keep a\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Button, NimbusProvider, Tooltip } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Disabled with a Tooltip\", () => {\n  it(\"stays focusable so a Tooltip can explain why it is disabled\", async () => {\n    const user = userEvent.setup();\n    const handlePress = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Tooltip.Root delay={0} closeDelay={0}>\n          <Button isDisabled allowFocusWhenDisabled onPress={handlePress}>\n            Publish\n          </Button>\n          <Tooltip.Content>\n            Complete all required fields to publish.\n          </Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    const button = screen.getByRole(\"button\", { name: /publish/i });\n\n    // Announced as disabled, but still reachable (no native `disabled`).\n    expect(button).toHaveAttribute(\"aria-disabled\", \"true\");\n    expect(button).not.toBeDisabled();\n\n    // Keyboard users can focus it and the tooltip reveals the explanation.\n    await user.tab();\n    expect(button).toHaveFocus();\n    expect(await screen.findByRole(\"tooltip\")).toHaveTextContent(\n      /required fields/i\n    );\n\n    // ...yet the action remains suppressed.\n    await user.click(button);\n    expect(handlePress).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Visual Variant Tests\n\nTest rendering with different visual variants and sizes\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Button, NimbusProvider, Tooltip } from \"@commercetools/nimbus\";\n\ndescribe(\"Button - Visual variants\", () => {\n  it(\"renders with different size variants\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Button size=\"sm\">Small</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Button size=\"md\">Medium</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n\n  it(\"renders with different visual variants\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <Button variant=\"solid\">Solid</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <Button variant=\"outline\">Outline</Button>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\")).toBeInTheDocument();\n  });\n\n  it(\"renders with color palettes\", () => {\n    render(\n      <NimbusProvider>\n        <Button colorPalette=\"primary\" variant=\"solid\">\n          Primary\n        </Button>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /primary/i })\n    ).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-buttons-button--docs)\n- [React Aria Button](https://react-spectrum.adobe.com/react-aria/Button.html)\n\n",
       "toc": [
         {
           "value": "Getting started",
@@ -485,6 +485,18 @@
           ],
           "parent": "root"
         },
+        {
+          "value": "Keeping a disabled button focusable (for tooltips)",
+          "href": "#keeping-a-disabled-button-focusable-for-tooltips",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
         {
           "value": "Event handling",
           "href": "#event-handling",
@@ -613,6 +625,17 @@
           ],
           "parent": "root"
         },
+        {
+          "value": "Tooltip on a disabled Button",
+          "href": "#tooltip-on-a-disabled-button",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
         {
           "value": "Visual Variant Tests",
           "href": "#visual-variant-tests",
@@ -620,7 +643,7 @@
           "numbering": [
             1,
             7,
-            5
+            6
           ],
           "parent": "root"
         },

package/data/docs/routes/components-chat-chat-message-list.json

@@ -0,0 +1,448 @@
+{
+  "meta": {
+    "id": "Components-ChatMessageList",
+    "title": "Chat message list",
+    "exportName": "ChatMessageList",
+    "description": "A scrollable transcript that arranges chat messages and notices, owning autoscroll, the \"jump to latest\" control, and the live region that announces new and streamed replies.",
+    "lifecycleState": "Experimental",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/chat-message-list/chat-message-list.mdx",
+    "menu": [
+      "Components",
+      "Chat",
+      "Chat message list"
+    ],
+    "route": "components/chat/chat-message-list",
+    "tags": [
+      "component",
+      "chat",
+      "message",
+      "list",
+      "transcript",
+      "ai",
+      "conversation"
+    ],
+    "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": "A conversation transcript",
+        "href": "#a-conversation-transcript",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Empty state",
+        "href": "#empty-state",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Autoscroll and \"jump to latest\"",
+        "href": "#autoscroll-and-jump-to-latest",
+        "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\n`ChatMessageList` presents a **scrollable sequence of chat messages** and owns\nthe transcript-level behavior that a single `ChatMessage` deliberately does not:\nscrolling, autoscroll / stick-to-bottom, the \"jump to latest\" affordance, and\nthe single live region that announces appended and streamed replies.\n\nA list is defined by its items, so `ChatMessageList` is a compound of a `Root`\nand its `Item`s — not a box that happens to contain children:\n\n- `ChatMessageList.Root` — the scroll container. Wraps `ScrollArea`, keeps the\n  view pinned to the newest message while you are at the bottom, and is the\n  transcript's `role=\"log\"` live region.\n- `ChatMessageList.Item` — one list member. It is content-agnostic: it holds a\n  `ChatMessage` or any other content, which is what lets a system notice be a\n  peer of a message rather than a message variant.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n## Variables\n\nGet familiar with the features.\n\n### A conversation transcript\n\nWrap each turn in a `ChatMessageList.Item`. A system notice is just another\nmember — the list does not treat it specially, so a consumer renders their own\ncentered, subdued content.\n\n```jsx live\nconst App = () => (\n  <ChatMessageList.Root aria-label=\"Conversation with the agent\" height=\"360px\">\n    <ChatMessageList.Item>\n      <ChatMessage.Root sender=\"user\">\n        <ChatMessage.Avatar firstName=\"Ada\" lastName=\"Lovelace\" />\n        <ChatMessage.Body>\n          <Text>Can you summarise last week's orders?</Text>\n        </ChatMessage.Body>\n      </ChatMessage.Root>\n    </ChatMessageList.Item>\n\n    <ChatMessageList.Item>\n      <ChatMessage.Root sender=\"agent\">\n        <ChatMessage.Avatar>\n          <Icons.AutoAwesome />\n        </ChatMessage.Avatar>\n        <ChatMessage.Body>\n          <Markdown>\n            {[\n              \"Here's what I found:\",\n              \"\",\n              \"- **Revenue** is up 12% week-over-week\",\n              \"- Top SKU: `ABC-123`\",\n            ].join(\"\\n\")}\n          </Markdown>\n        </ChatMessage.Body>\n      </ChatMessage.Root>\n    </ChatMessageList.Item>\n\n    <ChatMessageList.Item>\n      <Box mx=\"auto\" textAlign=\"center\" color=\"neutral.11\" textStyle=\"sm\">\n        Conversation history was cleared.\n      </Box>\n    </ChatMessageList.Item>\n  </ChatMessageList.Root>\n);\n```\n\n### Empty state\n\nWith no items, the list renders the `emptyState` you supply — an onboarding\nprompt or a simple \"no messages yet\" line.\n\n```jsx live\nconst App = () => (\n  <ChatMessageList.Root\n    aria-label=\"Conversation\"\n    height=\"220px\"\n    emptyState={\n      <Text>No messages yet — ask the agent anything to get started.</Text>\n    }\n  />\n);\n```\n\n### Autoscroll and \"jump to latest\"\n\n`Root` keeps the newest message in view while you are at the bottom, including\nwhile a reply streams. Scroll up to read history and the pin releases, revealing\na \"jump to latest\" control that returns you to the bottom and re-engages the\npin. Set `autoScroll={false}` to turn automatic scrolling off and drive it\nyourself via the ref's `scrollToBottom()`.\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\n`ChatMessageList` presents a **scrollable sequence of chat messages** and owns\nthe transcript-level behavior that a single `ChatMessage` deliberately does not:\nscrolling, autoscroll / stick-to-bottom, the \"jump to latest\" affordance, and\nthe single live region that announces appended and streamed replies.\n\nA list is defined by its items, so `ChatMessageList` is a compound of a `Root`\nand its `Item`s — not a box that happens to contain children:\n\n- `ChatMessageList.Root` — the scroll container. Wraps `ScrollArea`, keeps the\n  view pinned to the newest message while you are at the bottom, and is the\n  transcript's `role=\"log\"` live region.\n- `ChatMessageList.Item` — one list member. It is content-agnostic: it holds a\n  `ChatMessage` or any other content, which is what lets a system notice be a\n  peer of a message rather than a message variant.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n## Variables\n\nGet familiar with the features.\n\n### A conversation transcript\n\nWrap each turn in a `ChatMessageList.Item`. A system notice is just another\nmember — the list does not treat it specially, so a consumer renders their own\ncentered, subdued content.\n\n```jsx live\nconst App = () => (\n  <ChatMessageList.Root aria-label=\"Conversation with the agent\" height=\"360px\">\n    <ChatMessageList.Item>\n      <ChatMessage.Root sender=\"user\">\n        <ChatMessage.Avatar firstName=\"Ada\" lastName=\"Lovelace\" />\n        <ChatMessage.Body>\n          <Text>Can you summarise last week's orders?</Text>\n        </ChatMessage.Body>\n      </ChatMessage.Root>\n    </ChatMessageList.Item>\n\n    <ChatMessageList.Item>\n      <ChatMessage.Root sender=\"agent\">\n        <ChatMessage.Avatar>\n          <Icons.AutoAwesome />\n        </ChatMessage.Avatar>\n        <ChatMessage.Body>\n          <Markdown>\n            {[\n              \"Here's what I found:\",\n              \"\",\n              \"- **Revenue** is up 12% week-over-week\",\n              \"- Top SKU: `ABC-123`\",\n            ].join(\"\\n\")}\n          </Markdown>\n        </ChatMessage.Body>\n      </ChatMessage.Root>\n    </ChatMessageList.Item>\n\n    <ChatMessageList.Item>\n      <Box mx=\"auto\" textAlign=\"center\" color=\"neutral.11\" textStyle=\"sm\">\n        Conversation history was cleared.\n      </Box>\n    </ChatMessageList.Item>\n  </ChatMessageList.Root>\n);\n```\n\n### Empty state\n\nWith no items, the list renders the `emptyState` you supply — an onboarding\nprompt or a simple \"no messages yet\" line.\n\n```jsx live\nconst App = () => (\n  <ChatMessageList.Root\n    aria-label=\"Conversation\"\n    height=\"220px\"\n    emptyState={\n      <Text>No messages yet — ask the agent anything to get started.</Text>\n    }\n  />\n);\n```\n\n### Autoscroll and \"jump to latest\"\n\n`Root` keeps the newest message in view while you are at the bottom, including\nwhile a reply streams. Scroll up to read history and the pin releases, revealing\na \"jump to latest\" control that returns you to the bottom and re-engages the\npin. Set `autoScroll={false}` to turn automatic scrolling off and drive it\nyourself via the ref's `scrollToBottom()`.\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": "A conversation transcript",
+          "href": "#a-conversation-transcript",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Empty state",
+          "href": "#empty-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Autoscroll and \"jump to latest\"",
+          "href": "#autoscroll-and-jump-to-latest",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\n`ChatMessageList` owns the half of chat accessibility that a single\n`ChatMessage` intentionally leaves to the transcript: the container's live\nregion and the announcement of new content. This page covers what the list does\nfor you and the small amount you are responsible for.\n\n```jsx live\nconst App = () => (\n  <ChatMessageList.Root aria-label=\"Conversation with the agent\" height=\"260px\">\n    <ChatMessageList.Item>\n      <ChatMessage.Root sender=\"user\" aria-label=\"Message from Ada Lovelace\">\n        <ChatMessage.Avatar firstName=\"Ada\" lastName=\"Lovelace\" />\n        <ChatMessage.Body>\n          <Text>Can you summarise last week's orders?</Text>\n        </ChatMessage.Body>\n      </ChatMessage.Root>\n    </ChatMessageList.Item>\n    <ChatMessageList.Item>\n      <ChatMessage.Root sender=\"agent\" aria-label=\"Message from the agent\">\n        <ChatMessage.Avatar aria-label=\"Agent\">\n          <Icons.AutoAwesome />\n        </ChatMessage.Avatar>\n        <ChatMessage.Body>\n          <Text>Revenue is up 12% week-over-week.</Text>\n        </ChatMessage.Body>\n      </ChatMessage.Root>\n    </ChatMessageList.Item>\n  </ChatMessageList.Root>\n);\n```\n\n### Naming the transcript\n\n`ChatMessageList.Root` renders a `role=\"log\"` region that needs an accessible\nname. Provide one with `aria-label` or `aria-labelledby`. If you supply neither,\nthe list falls back to a localized default (\"Conversation\") so the region is\nnever anonymous — but a name specific to the conversation is better.\n\n### Why `log`, not `feed`\n\nTwo ARIA container roles fit a message transcript, and they are not\ninterchangeable:\n\n- **`role=\"log\"` with `aria-live=\"polite\"`** (the default here) — a live region\n  that announces appended content, including streamed replies, without\n  re-announcing the whole history on every token. It has **no constraint on\n  child roles**, so it validly contains `<article>` messages, centered notices,\n  date separators, or anything else the transcript needs.\n- **`role=\"feed\"`** — the ARIA APG's dedicated pattern for scrollable article\n  collections, with built-in \"read next/previous article\" keyboard support. Its\n  trade-off: `feed` has an `aria-required-children` constraint — **every** child\n  must have role `article`. A centered notice or a divider inside a `feed` is an\n  accessibility violation, not just a lint warning.\n\nBecause a real transcript mixes messages with notices and dividers,\n`ChatMessageList` defaults to `log`. If you are specifically building\narticle-to-article keyboard navigation, you can compose a `role=\"feed\"` yourself\nfrom message `article`s only — but then you cannot mix in non-article members.\n\n### One announcer during streaming\n\nStreaming has a single announcer. The list's `log` region announces\nmessage-level changes (a message appended, a reply arriving). The streamed\nmessage itself only sets `aria-busy` via `isStreaming` on its\n`ChatMessage.Root`; it does **not** create its own live region — a region\nmounted at the same moment as its content is not reliably announced, and two\noverlapping live regions would double-announce.\n\nHow much of the streamed text is announced depends on how you render it.\n`aria-busy=\"true\"` asks assistive technology to defer announcing changes inside\nthe message until the stream settles and the flag clears — which keeps a\ncompliant screen reader from reading every token — but support for that deferral\nvaries between screen readers. The recommended path is to render the body with\n`<Markdown isStreaming>`: it owns a single, coalesced completion announcement\ninstead of emitting text token by token. If you stream raw growing text into the\n`log` with neither `aria-busy` nor a component that coalesces its own\nannouncement, expect some screen readers to announce intermediate updates.\n\n### The list is always mounted\n\nThe `log` region persists across messages — it is present before content\nchanges, which is what makes appended and streamed content announce reliably.\nRender `ChatMessageList.Root` for the life of the conversation rather than\nmounting it alongside the first message.\n\n### `Item` does not assert `listitem`\n\n`ChatMessageList.Item` provides DOM order and a styling hook but deliberately\ndoes not set `role=\"listitem\"`, which would require a `list`/`log` parent\nrelationship that conflicts with the live-region semantics. Members keep their\nown roles (a message `article`, a notice) unchanged.\n\n### Accessibility standards\n\n- **Status messages:** `Root` is `role=\"log\"` `aria-live=\"polite\"` so new and\n  streamed messages are announced without the consumer building custom\n  live-region logic.\n- **Name, role, value:** name the `log` region with `aria-label` /\n  `aria-labelledby`; a localized default applies only as a fallback.\n- **Info and relationships:** a mixed transcript stays valid because `log`\n  imposes no required-children constraint — messages, notices, and dividers can\n  coexist.\n- **Focus order / no keyboard trap:** the scroll-to-bottom control is a single\n  focusable button that appears only while the pin is released; it never traps\n  focus.\n\n### Resources\n\n- [WAI-ARIA: `log` role](https://www.w3.org/TR/wai-aria-1.2/#log)\n- [ARIA APG: Feed Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/feed/)\n- [WCAG 2.1: Status Messages (4.1.3)](https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html)\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Naming the transcript",
+          "href": "#naming-the-transcript",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Why log, not feed",
+          "href": "#why-log-not-feed",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "One announcer during streaming",
+          "href": "#one-announcer-during-streaming",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "The list is always mounted",
+          "href": "#the-list-is-always-mounted",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Item does not assert listitem",
+          "href": "#item-does-not-assert-listitem",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport {\n  ChatMessageList,\n  type ChatMessageListHandle,\n} from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\n`ChatMessageList` is a compound component: wrap each turn in a\n`ChatMessageList.Item` inside `ChatMessageList.Root`. Give `Root` a bounded\nheight (directly, or by placing it in a flex/grid parent) so it scrolls\ninternally instead of growing the page.\n\n```jsx live-dev\nconst App = () => (\n  <ChatMessageList.Root aria-label=\"Conversation\" height=\"320px\">\n    <ChatMessageList.Item>\n      <ChatMessage.Root sender=\"user\">\n        <ChatMessage.Avatar firstName=\"Ada\" lastName=\"Lovelace\" />\n        <ChatMessage.Body>\n          <Text>Can you summarise last week's orders?</Text>\n        </ChatMessage.Body>\n      </ChatMessage.Root>\n    </ChatMessageList.Item>\n    <ChatMessageList.Item>\n      <ChatMessage.Root sender=\"agent\">\n        <ChatMessage.Avatar>\n          <Icons.AutoAwesome />\n        </ChatMessage.Avatar>\n        <ChatMessage.Body>\n          <Text>Revenue is up 12% week-over-week.</Text>\n        </ChatMessage.Body>\n      </ChatMessage.Root>\n    </ChatMessageList.Item>\n  </ChatMessageList.Root>\n);\n```\n\n## Usage examples\n\n### Items are content-agnostic\n\nA `ChatMessageList.Item` is the list-membership socket; it does not care what\nplugs into it. The same `Item` holds a `ChatMessage` or any other content, so a\nsystem notice is a peer of a message rather than a `sender` variant.\n\n```jsx live-dev\nconst App = () => (\n  <ChatMessageList.Root aria-label=\"Conversation\" height=\"260px\">\n    <ChatMessageList.Item>\n      <Box mx=\"auto\" textAlign=\"center\" color=\"neutral.11\" textStyle=\"sm\">\n        Today\n      </Box>\n    </ChatMessageList.Item>\n    <ChatMessageList.Item>\n      <ChatMessage.Root sender=\"agent\">\n        <ChatMessage.Avatar>\n          <Icons.AutoAwesome />\n        </ChatMessage.Avatar>\n        <ChatMessage.Body>\n          <Text>How can I help you today?</Text>\n        </ChatMessage.Body>\n      </ChatMessage.Root>\n    </ChatMessageList.Item>\n  </ChatMessageList.Root>\n);\n```\n\n### Empty state\n\nWhen the list has no items, `Root` renders the `emptyState` node.\n\n```jsx live-dev\nconst App = () => (\n  <ChatMessageList.Root\n    aria-label=\"Conversation\"\n    height=\"220px\"\n    emptyState={<Text>No messages yet.</Text>}\n  />\n);\n```\n\n### Autoscroll and streaming\n\n`autoScroll` (default `true`) keeps the view pinned to the newest message while\nthe user is at the bottom, including while a reply streams and grows. The\nmessage being streamed sets `isStreaming` on its `ChatMessage.Root` (which sets\n`aria-busy`) and renders its text with `<Markdown isStreaming>`; the list owns\nthe announcement, the message owns the busy flag. Scrolling up releases the pin\nand reveals a \"jump to latest\" control.\n\n```jsx live-dev\nconst App = () => (\n  <ChatMessageList.Root aria-label=\"Conversation\" height=\"300px\">\n    <ChatMessageList.Item>\n      <ChatMessage.Root sender=\"user\">\n        <ChatMessage.Body>\n          <Text>Tell me about last week's revenue.</Text>\n        </ChatMessage.Body>\n      </ChatMessage.Root>\n    </ChatMessageList.Item>\n    <ChatMessageList.Item>\n      <ChatMessage.Root sender=\"agent\" isStreaming>\n        <ChatMessage.Avatar>\n          <Icons.AutoAwesome />\n        </ChatMessage.Avatar>\n        <ChatMessage.Body>\n          <Markdown isStreaming>\n            {\"Revenue is up **12%** week-over-week, driven by\"}\n          </Markdown>\n        </ChatMessage.Body>\n      </ChatMessage.Root>\n    </ChatMessageList.Item>\n  </ChatMessageList.Root>\n);\n```\n\n### Imperative scroll control\n\n`Root` exposes a `scrollToBottom()` handle on its `ref` — useful after\nprepending history, or to jump to the newest message from a keyboard shortcut.\nIt re-engages stick-to-bottom and honors `prefers-reduced-motion`.\n\n```tsx\nconst ref = useRef<ChatMessageListHandle>(null);\n\n// later, e.g. after loading older messages:\nref.current?.scrollToBottom(\"smooth\");\n\nreturn (\n  <ChatMessageList.Root ref={ref} aria-label=\"Conversation\">\n    {/* items */}\n  </ChatMessageList.Root>\n);\n```\n\n## Component requirements\n\n- Give `ChatMessageList.Root` a bounded height (directly or via a flex/grid\n  parent) so it scrolls internally.\n- Wrap every transcript member — a `ChatMessage` or any other content — in its\n  own `ChatMessageList.Item`.\n- Name the transcript with `aria-label` (or `aria-labelledby`); `Root` provides\n  a localized default if you omit both, but a specific name is better.\n- v1 renders items directly (no windowing); very long transcripts render every\n  item. Virtualization is a planned fast-follow.\n\n## Accessibility\n\n`ChatMessageList.Root` is the transcript's single, persistent `role=\"log\"`\n`aria-live=\"polite\"` region — appended and streamed messages are announced\nwithout per-token spam, and mixed children (message `article`s plus notices) are\nvalid because `log` imposes no `aria-required-children` constraint. See the\n**Accessibility tab** for the full `log`-vs-`feed` rationale and how streaming\nannouncement ownership is split between the list and the message.\n\n## API reference\n\n<PropsTable id=\"ChatMessageList\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using\nChatMessageList within your application. As the component's internal\nfunctionality is already tested by Nimbus, these patterns help you verify your\nintegration and application-specific logic.\n\n### Rendering a transcript\n\nWrap each turn in a ChatMessageList.Item inside ChatMessageList.Root.\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport {\n  ChatMessageList,\n  ChatMessage,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ChatMessageList - Rendering a transcript\", () => {\n  it(\"renders each item's member as a vertical sequence\", () => {\n    render(\n      <NimbusProvider>\n        <ChatMessageList.Root aria-label=\"Conversation\">\n          <ChatMessageList.Item>\n            <ChatMessage.Root sender=\"user\">\n              <ChatMessage.Body>\n                <Text>Summarise last week's orders?</Text>\n              </ChatMessage.Body>\n            </ChatMessage.Root>\n          </ChatMessageList.Item>\n          <ChatMessageList.Item>\n            <ChatMessage.Root sender=\"agent\">\n              <ChatMessage.Body>\n                <Text>Revenue is up 12%.</Text>\n              </ChatMessage.Body>\n            </ChatMessage.Root>\n          </ChatMessageList.Item>\n        </ChatMessageList.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByText(\"Summarise last week's orders?\")\n    ).toBeInTheDocument();\n    expect(screen.getByText(\"Revenue is up 12%.\")).toBeInTheDocument();\n  });\n\n  it(\"holds arbitrary content as a member, not just messages\", () => {\n    render(\n      <NimbusProvider>\n        <ChatMessageList.Root aria-label=\"Conversation\">\n          <ChatMessageList.Item>\n            {/* The list is content-agnostic — an Item can hold any content,\n                e.g. a consumer-rendered notice. */}\n            <Text>Conversation history was cleared.</Text>\n          </ChatMessageList.Item>\n        </ChatMessageList.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByText(\"Conversation history was cleared.\")\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### Accessible live region\n\nRoot is a named role=\"log\" aria-live=\"polite\" region for the transcript.\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport {\n  ChatMessageList,\n  ChatMessage,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ChatMessageList - Accessible live region\", () => {\n  it(\"exposes a polite log region named by aria-label\", () => {\n    render(\n      <NimbusProvider>\n        <ChatMessageList.Root aria-label=\"Conversation with the agent\">\n          <ChatMessageList.Item>\n            <ChatMessage.Root sender=\"agent\">\n              <ChatMessage.Body>\n                <Text>Hello!</Text>\n              </ChatMessage.Body>\n            </ChatMessage.Root>\n          </ChatMessageList.Item>\n        </ChatMessageList.Root>\n      </NimbusProvider>\n    );\n\n    // Scope by name: under the unit project's shared JSDOM (isolate:false),\n    // React Aria's global LiveAnnouncer leaves nameless role=\"log\" nodes on\n    // document.body that an unscoped query would also match.\n    const log = screen.getByRole(\"log\", {\n      name: \"Conversation with the agent\",\n    });\n    expect(log).toHaveAttribute(\"aria-live\", \"polite\");\n    expect(log).toHaveAccessibleName(\"Conversation with the agent\");\n  });\n\n  it(\"falls back to a localized name when none is provided\", () => {\n    render(\n      <NimbusProvider>\n        <ChatMessageList.Root>\n          <ChatMessageList.Item>\n            <ChatMessage.Root sender=\"agent\">\n              <ChatMessage.Body>\n                <Text>Hello!</Text>\n              </ChatMessage.Body>\n            </ChatMessage.Root>\n          </ChatMessageList.Item>\n        </ChatMessageList.Root>\n      </NimbusProvider>\n    );\n\n    // Scope by name (see note above) to exclude LiveAnnouncer's nameless logs.\n    expect(\n      screen.getByRole(\"log\", { name: \"Conversation\" })\n    ).toHaveAccessibleName(\"Conversation\");\n  });\n});\n```\n\n### Empty state\n\nRoot renders emptyState when there are no items.\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport {\n  ChatMessageList,\n  ChatMessage,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ChatMessageList - Empty state\", () => {\n  it(\"renders the empty state when there are no items\", () => {\n    render(\n      <NimbusProvider>\n        <ChatMessageList.Root\n          aria-label=\"Conversation\"\n          emptyState={<Text>No messages yet.</Text>}\n        />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"No messages yet.\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-chatmessagelist--docs)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Items are content-agnostic",
+          "href": "#items-are-content-agnostic",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Empty state",
+          "href": "#empty-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Autoscroll and streaming",
+          "href": "#autoscroll-and-streaming",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Imperative scroll control",
+          "href": "#imperative-scroll-control",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            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": "Rendering a transcript",
+          "href": "#rendering-a-transcript",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessible live region",
+          "href": "#accessible-live-region",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Empty state",
+          "href": "#empty-state-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}