@commercetools/nimbus-mcp 3.2.0 → 3.4.0

package/data/docs/routes/components-feedback-skeletontext.json

@@ -0,0 +1,417 @@
+{
+  "meta": {
+    "id": "Components-SkeletonText",
+    "title": "SkeletonText",
+    "exportName": "SkeletonText",
+    "description": "A stack of placeholder lines that approximates a paragraph of text while content loads.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/skeleton/derivatives/skeleton-text/skeleton-text.mdx",
+    "menu": [
+      "Components",
+      "Feedback",
+      "SkeletonText"
+    ],
+    "route": "components/feedback/skeletontext",
+    "tags": [
+      "component",
+      "skeleton",
+      "loading",
+      "placeholder",
+      "feedback",
+      "text"
+    ],
+    "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": "Line count",
+        "href": "#line-count",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Matching text size",
+        "href": "#matching-text-size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Last line width",
+        "href": "#last-line-width",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Guidelines",
+        "href": "#guidelines",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Best practices",
+        "href": "#best-practices",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "When to use",
+        "href": "#when-to-use",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\n`SkeletonText` renders a stack of placeholder lines that stand in for a\nparagraph of text while it loads. The last line is narrower by default to mimic\na natural paragraph ending, and the lines are sized to the same vertical rhythm\nas the real text they replace — so the transition to loaded content stays\nsmooth.\n\n`SkeletonText` is part of the Skeleton family, built from\n[Skeleton](/components/feedback/skeleton) lines. For single blocks, images, or\ncustom shapes use `Skeleton` directly; for avatars and icons use\n[SkeletonCircle](/components/feedback/skeletoncircle).\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system)\n\n## Variables\n\nGet familiar with the features.\n\n### Line count\n\nUse `lines` to set how many placeholder lines to render. Set the block's\n`width` to match the column the text will occupy.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"800\" width=\"600px\">\n    <SkeletonText lines={2} width=\"100%\" />\n    <SkeletonText lines={4} width=\"100%\" />\n  </Stack>\n)\n```\n\n### Matching text size\n\nSet `textStyle` (default `body`) so the placeholder lines match the size and\nline spacing of the text they stand in for — from small captions to large\nheadings. Each bar's height and the gaps between them resize together, keeping\nthe same vertical rhythm as real text of that style.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\" width=\"300px\">\n    <SkeletonText textStyle=\"caption\" />\n    <SkeletonText textStyle=\"body\" />\n    <SkeletonText textStyle=\"3xl\" lines={2} />\n  </Stack>\n)\n```\n\n### Last line width\n\nThe last line is narrower by default (`lastLineWidth=\"60%\"`) to mimic a\nparagraph ending. Adjust it to match the content, or set it to `\"100%\"` for a\njustified block.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"800\" width=\"600px\">\n    <SkeletonText lines={3} width=\"100%\" lastLineWidth=\"40%\" />\n    <SkeletonText lines={3} width=\"100%\" lastLineWidth=\"100%\" />\n  </Stack>\n)\n```\n\n## Guidelines\n\n### Best practices\n\n- Match `textStyle` to the text you are standing in for so the placeholder\n  occupies the same space as the loaded content and avoids layout shift.\n- Use `SkeletonText` for multi-line paragraphs; for a single heading or line,\n  the base `Skeleton` gives you more direct control over height and width.\n- Keep the line count realistic — approximating the real paragraph length keeps\n  the transition to loaded content smooth.\n\n### When to use\n\n> [!TIP]\\\n> Use SkeletonText when:\n- You are loading a paragraph, description, or block of running text\n- You want the placeholder to match a specific text style's size and rhythm\n- A detail panel or card contains several lines of text\n\n> [!CAUTION]\\\n> When NOT to use SkeletonText:\n- For a single line, heading, or non-text block — use\n  [Skeleton](/components/feedback/skeleton) instead\n- For circular content such as avatars — use\n  [SkeletonCircle](/components/feedback/skeletoncircle)\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\n`SkeletonText` renders a stack of placeholder lines that stand in for a\nparagraph of text while it loads. The last line is narrower by default to mimic\na natural paragraph ending, and the lines are sized to the same vertical rhythm\nas the real text they replace — so the transition to loaded content stays\nsmooth.\n\n`SkeletonText` is part of the Skeleton family, built from\n[Skeleton](/components/feedback/skeleton) lines. For single blocks, images, or\ncustom shapes use `Skeleton` directly; for avatars and icons use\n[SkeletonCircle](/components/feedback/skeletoncircle).\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system)\n\n## Variables\n\nGet familiar with the features.\n\n### Line count\n\nUse `lines` to set how many placeholder lines to render. Set the block's\n`width` to match the column the text will occupy.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"800\" width=\"600px\">\n    <SkeletonText lines={2} width=\"100%\" />\n    <SkeletonText lines={4} width=\"100%\" />\n  </Stack>\n)\n```\n\n### Matching text size\n\nSet `textStyle` (default `body`) so the placeholder lines match the size and\nline spacing of the text they stand in for — from small captions to large\nheadings. Each bar's height and the gaps between them resize together, keeping\nthe same vertical rhythm as real text of that style.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\" width=\"300px\">\n    <SkeletonText textStyle=\"caption\" />\n    <SkeletonText textStyle=\"body\" />\n    <SkeletonText textStyle=\"3xl\" lines={2} />\n  </Stack>\n)\n```\n\n### Last line width\n\nThe last line is narrower by default (`lastLineWidth=\"60%\"`) to mimic a\nparagraph ending. Adjust it to match the content, or set it to `\"100%\"` for a\njustified block.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"800\" width=\"600px\">\n    <SkeletonText lines={3} width=\"100%\" lastLineWidth=\"40%\" />\n    <SkeletonText lines={3} width=\"100%\" lastLineWidth=\"100%\" />\n  </Stack>\n)\n```\n\n## Guidelines\n\n### Best practices\n\n- Match `textStyle` to the text you are standing in for so the placeholder\n  occupies the same space as the loaded content and avoids layout shift.\n- Use `SkeletonText` for multi-line paragraphs; for a single heading or line,\n  the base `Skeleton` gives you more direct control over height and width.\n- Keep the line count realistic — approximating the real paragraph length keeps\n  the transition to loaded content smooth.\n\n### When to use\n\n> [!TIP]\\\n> Use SkeletonText when:\n- You are loading a paragraph, description, or block of running text\n- You want the placeholder to match a specific text style's size and rhythm\n- A detail panel or card contains several lines of text\n\n> [!CAUTION]\\\n> When NOT to use SkeletonText:\n- For a single line, heading, or non-text block — use\n  [Skeleton](/components/feedback/skeleton) instead\n- For circular content such as avatars — use\n  [SkeletonCircle](/components/feedback/skeletoncircle)\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": "Line count",
+          "href": "#line-count",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Matching text size",
+          "href": "#matching-text-size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Last line width",
+          "href": "#last-line-width",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use",
+          "href": "#when-to-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { SkeletonText, type SkeletonTextProps } from '@commercetools/nimbus';\n```\n\n`SkeletonText` is built on [Skeleton](/components/feedback/skeleton). For single\nblocks use `Skeleton`; for circular placeholders see\n[SkeletonCircle](/components/feedback/skeletoncircle).\n\n### Basic usage\n\n`SkeletonText` renders a configurable number of placeholder lines to approximate\na paragraph. The last line is narrower by default (`lastLineWidth=\"60%\"`) to\nmimic a natural paragraph ending.\n\n```jsx live-dev\nconst App = () => (\n  <SkeletonText lines={4} width=\"300px\" />\n)\n```\n\n## Usage examples\n\n### Matching text size with `textStyle`\n\n`SkeletonText` accepts a `textStyle` prop (default `\"body\"`) that makes the\nplaceholder lines occupy the same vertical rhythm as real text of that style.\nEach line becomes a `1lh` line-box sized by the style, with a `0.75em`\n(≈ cap-height) bar centered in it — so the bar sits where real glyphs sit and the\npitch scales automatically: a `body` skeleton uses a 26 px line pitch, a `3xl`\nheading skeleton a 36 px pitch. Pass any Nimbus text style to match the content\nyou are standing in for.\n\n```jsx live-dev\nconst App = () => (\n  <Stack gap=\"600\" width=\"300px\">\n    <SkeletonText textStyle=\"caption\" />\n    <SkeletonText textStyle=\"body\" />\n    <SkeletonText textStyle=\"3xl\" lines={2} />\n  </Stack>\n)\n```\n\n### Conditional rendering (standalone pattern)\n\nLike the rest of the family, `SkeletonText` has no `isLoaded` prop. Render it\nwhile loading and swap it for the real text with conditional rendering.\n\n```jsx live-dev\nconst App = () => {\n  const [isLoading, setIsLoading] = React.useState(true);\n\n  return (\n    <Stack gap=\"400\" width=\"320px\">\n      <Button onPress={() => setIsLoading(v => !v)}>Toggle loading</Button>\n      <div aria-busy={isLoading}>\n        {isLoading ? (\n          <SkeletonText lines={3} width=\"100%\" />\n        ) : (\n          <Text>\n            A short product description that replaces the placeholder once the\n            data has finished loading.\n          </Text>\n        )}\n      </div>\n    </Stack>\n  )\n}\n```\n\n## Component requirements\n\n### Accessibility\n\n`SkeletonText` is **decorative by default** — its container and lines render\nwith `aria-hidden=\"true\"` so screen readers skip over them.\n\nTo communicate loading state to assistive technology, set `aria-busy=\"true\"` on\nthe **container** that wraps the skeleton region, then clear it and render the\nreal content once loading completes.\n\n```tsx\n<section aria-busy={isLoading} aria-label=\"Product description\">\n  {isLoading ? (\n    <SkeletonText lines={3} width=\"100%\" />\n  ) : (\n    <ProductDescription product={product} />\n  )}\n</section>\n```\n\nAnnounce the loading region on the wrapping container rather than labelling the\nskeleton itself — see [Skeleton](/components/feedback/skeleton) for the full\nrationale.\n\n#### Reduced motion\n\nWhen the user has enabled `prefers-reduced-motion: reduce`, the line animations\nare automatically disabled regardless of the `animation` prop value. No\nadditional configuration is required.\n\n#### Keyboard navigation\n\n`SkeletonText` is non-interactive and decorative. It does not receive focus or\nsupport keyboard interaction.\n\n## API reference\n\n<PropsTable id=\"SkeletonText\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using SkeletonText 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 Rendering\n\nRender a `SkeletonText` block and confirm it renders one placeholder line per `lines`; the container is decorative (`aria-hidden`) by default, so assistive technology skips it.\n\n```tsx\nimport { useState } from \"react\";\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  SkeletonText,\n  Stack,\n  Text,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"SkeletonText - Basic rendering\", () => {\n  it(\"renders one placeholder line per `lines`\", () => {\n    render(\n      <NimbusProvider>\n        <SkeletonText data-testid=\"skeleton-text\" lines={3} width=\"300px\" />\n      </NimbusProvider>\n    );\n\n    const container = screen.getByTestId(\"skeleton-text\");\n    expect(container).toBeInTheDocument();\n    expect(container).toHaveAttribute(\"aria-hidden\", \"true\");\n    // One Skeleton line is rendered for each of the three requested lines.\n    expect(container.children).toHaveLength(3);\n  });\n});\n```\n\n### Standalone Loading Pattern\n\nThe recommended way to use SkeletonText: render placeholder lines while the text is loading, then swap in the real paragraph with conditional rendering — SkeletonText has no `isLoaded` prop, so the consumer owns the loading state.\n\n```tsx\nimport { useState } from \"react\";\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  SkeletonText,\n  Stack,\n  Text,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"SkeletonText - Standalone loading pattern\", () => {\n  /**\n   * A representative consumer component: show placeholder lines while\n   * `isLoading`, then render the real description once loading completes.\n   */\n  function ProductDescription({ isLoading }: { isLoading: boolean }) {\n    return isLoading ? (\n      <SkeletonText lines={3} width=\"100%\" />\n    ) : (\n      <Text>\n        Wireless keyboard with a compact layout and long battery life.\n      </Text>\n    );\n  }\n\n  it(\"shows placeholder lines while loading, then the real text\", async () => {\n    const description =\n      \"Wireless keyboard with a compact layout and long battery life.\";\n\n    const Example = () => {\n      const [isLoading, setIsLoading] = useState(true);\n      return (\n        <Stack gap=\"400\" width=\"320px\">\n          <ProductDescription isLoading={isLoading} />\n          <Button onPress={() => setIsLoading(false)}>Finish loading</Button>\n        </Stack>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <Example />\n      </NimbusProvider>\n    );\n\n    // While loading: real text is absent.\n    expect(screen.queryByText(description)).toBeNull();\n\n    await userEvent.click(\n      screen.getByRole(\"button\", { name: \"Finish loading\" })\n    );\n\n    // After loading: real text is present.\n    expect(screen.getByText(description)).toBeInTheDocument();\n  });\n});\n```\n\n### Announcing Loading with aria-busy\n\nSkeletonText is decorative (`aria-hidden`), so it is not announced on its own; communicate the loading state to assistive technology by setting `aria-busy` on the surrounding container instead.\n\n```tsx\nimport { useState } from \"react\";\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  SkeletonText,\n  Stack,\n  Text,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"SkeletonText - Container aria-busy pattern\", () => {\n  it(\"announces loading state via aria-busy on the container\", () => {\n    render(\n      <NimbusProvider>\n        <section\n          data-testid=\"container\"\n          aria-busy={true}\n          aria-label=\"Product description\"\n        >\n          <SkeletonText lines={3} width=\"100%\" />\n        </section>\n      </NimbusProvider>\n    );\n\n    const container = screen.getByTestId(\"container\");\n    expect(container).toHaveAttribute(\"aria-busy\", \"true\");\n    expect(container).toHaveAttribute(\"aria-label\", \"Product description\");\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-skeleton--docs)\n- [Skeleton](/components/feedback/skeleton)\n- [SkeletonCircle](/components/feedback/skeletoncircle)\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": "Matching text size with textStyle",
+          "href": "#matching-text-size-with-textstyle",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Conditional rendering (standalone pattern)",
+          "href": "#conditional-rendering-standalone-pattern",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Reduced motion",
+          "href": "#reduced-motion",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering",
+          "href": "#basic-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Standalone Loading Pattern",
+          "href": "#standalone-loading-pattern",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Announcing Loading with aria-busy",
+          "href": "#announcing-loading-with-aria-busy",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}

package/data/docs/routes/components-feedback-tooltip.json

@@ -165,7 +165,7 @@
       ]
     },
     "dev": {
-      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Tooltip, MakeElementFocusable } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation wraps a trigger element and tooltip content:\n\n```jsx live-dev\nconst App = () => (\n  <Tooltip.Root>\n    <Button>Hover me</Button>\n    <Tooltip.Content>\n      Helpful information appears here\n    </Tooltip.Content>\n  </Tooltip.Root>\n)\n```\n\n## Usage examples\n\n### Placement options\n\nThe `placement` prop controls where the tooltip appears relative to the trigger element. The default placement is `\"bottom\"`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n    <Tooltip.Root>\n      <Button>Top</Button>\n      <Tooltip.Content placement=\"top\">\n        Top placement\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <Button>Bottom</Button>\n      <Tooltip.Content placement=\"bottom\">\n        Bottom placement\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <Button>Left</Button>\n      <Tooltip.Content placement=\"left\">\n        Left placement\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <Button>Right</Button>\n      <Tooltip.Content placement=\"right\">\n        Right placement\n      </Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n**Available placements:**\n\nThe component supports 26 placement options:\n- **Basic**: `top`, `bottom`, `left`, `right`, `start`, `end`\n- **With alignment**: `top left`, `top right`, `top start`, `top end`, `bottom left`, `bottom right`, `bottom start`, `bottom end`, `left top`, `left bottom`, `right top`, `right bottom`, `start top`, `start bottom`, `end top`, `end bottom`\n\n### Delay configuration\n\nControl when tooltips appear and disappear using `delay` and `closeDelay` props on `Tooltip.Root`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <Button>Instant</Button>\n      <Tooltip.Content>\n        Shows immediately\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root delay={300} closeDelay={200}>\n      <Button>Default timing</Button>\n      <Tooltip.Content>\n        300ms delay to show, 200ms to hide\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root delay={1000}>\n      <Button>Slow</Button>\n      <Tooltip.Content>\n        1000ms delay to show\n      </Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n**Timing considerations:**\n- `delay`: Time in milliseconds before the tooltip appears (default: `300`)\n- `closeDelay`: Time in milliseconds before the tooltip disappears (default: `200`)\n- Shorter delays improve responsiveness but may feel too aggressive\n- Longer delays reduce accidental triggers but may feel sluggish\n\n### Complex content\n\nTooltip content can include multiple elements using layout components:\n\n```jsx live-dev\nconst App = () => (\n  <Tooltip.Root>\n    <Button>Feature info</Button>\n    <Tooltip.Content>\n      <Stack direction=\"column\" gap=\"100\">\n        <Text fontWeight=\"600\" fontSize=\"sm\">Premium Feature</Text>\n        <Text fontSize=\"xs\">\n          Available on Pro and Enterprise plans\n        </Text>\n      </Stack>\n    </Tooltip.Content>\n  </Tooltip.Root>\n)\n```\n\n### With icon buttons\n\nA common pattern is providing context for icon-only buttons:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"300\">\n    <Tooltip.Root>\n      <IconButton aria-label=\"Edit\">\n        <Icons.Edit />\n      </IconButton>\n      <Tooltip.Content placement=\"top\">\n        Edit item\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <IconButton aria-label=\"Delete\">\n        <Icons.Delete />\n      </IconButton>\n      <Tooltip.Content placement=\"top\">\n        Delete item\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <IconButton aria-label=\"Share\">\n        <Icons.Share />\n      </IconButton>\n      <Tooltip.Content placement=\"top\">\n        Share with team\n      </Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n### With focusable elements\n\nTooltips work with any focusable element. For non-interactive elements like Text, use `MakeElementFocusable`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Tooltip.Root>\n      <MakeElementFocusable>\n        <Text\n          as=\"span\"\n          textDecoration=\"underline\"\n          cursor=\"help\"\n        >\n          Hover or focus me\n        </Text>\n      </MakeElementFocusable>\n      <Tooltip.Content>\n        This text element is focusable and shows a tooltip\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <Button variant=\"ghost\">\n        <Icons.Info />\n        Learn more\n      </Button>\n      <Tooltip.Content placement=\"right\">\n        Opens detailed documentation\n      </Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Tooltip component is built with React Aria Components and provides accessible tooltip behavior by default. The component:\n\n- Automatically associates tooltip content with the trigger using `aria-describedby`\n- Assigns the `tooltip` ARIA role to the content\n- Shows on both hover and keyboard focus\n- Hides when focus leaves or `Escape` is pressed\n\n**Important:** Ensure the trigger element has an accessible label. For icon-only buttons, always provide an `aria-label`:\n\n```tsx\n<Tooltip.Root>\n  <IconButton aria-label=\"Delete item\">\n    <Icons.Delete />\n  </IconButton>\n  <Tooltip.Content>Delete this item</Tooltip.Content>\n</Tooltip.Root>\n```\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the trigger element:\n\n```tsx\nconst PERSISTENT_ID = \"delete-button-tooltip\";\n\nexport const Example = () => (\n  <Tooltip.Root>\n    <IconButton id={PERSISTENT_ID} aria-label=\"Delete\">\n      <Icons.Delete />\n    </IconButton>\n    <Tooltip.Content>Delete item</Tooltip.Content>\n  </Tooltip.Root>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n\n- `Tab` / `Shift+Tab`: Move focus to/from the trigger element\n- Tooltip appears automatically when trigger receives focus\n- `Escape`: Dismisses the tooltip (if shown)\n- Tooltip disappears automatically when focus leaves the trigger\n\n### Trigger element requirements\n\nThe first child of `Tooltip.Root` must be a focusable element:\n\n- Use buttons, links, or other interactive elements (recommended)\n- For non-interactive elements like Text or div, wrap with `MakeElementFocusable`\n- Avoid wrapping non-focusable elements without proper handling\n\n```tsx\n// ✅ Good - button is natively focusable\n<Tooltip.Root>\n  <Button>Trigger</Button>\n  <Tooltip.Content>Content</Tooltip.Content>\n</Tooltip.Root>\n\n// ✅ Good - non-interactive element with MakeElementFocusable\n<Tooltip.Root>\n  <MakeElementFocusable>\n    <Text as=\"span\">Trigger</Text>\n  </MakeElementFocusable>\n  <Tooltip.Content>Content</Tooltip.Content>\n</Tooltip.Root>\n\n// ❌ Bad - Text with tabIndex won't work properly\n<Tooltip.Root>\n  <Text as=\"span\" tabIndex={0}>Trigger</Text>\n  <Tooltip.Content>Content</Tooltip.Content>\n</Tooltip.Root>\n```\n\n## API reference\n\n<PropsTable id=\"Tooltip\" />\n\n## Common patterns\n\n### Info tooltips for form fields\n\nProvide additional context for form fields without cluttering the interface:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"row\" gap=\"200\" alignItems=\"center\">\n        <Text as=\"label\" htmlFor=\"username-input\" fontWeight=\"500\">\n          Username\n        </Text>\n        <Tooltip.Root>\n          <IconButton\n            aria-label=\"Username requirements\"\n            size=\"sm\"\n            variant=\"ghost\"\n          >\n            <Icons.Info />\n          </IconButton>\n          <Tooltip.Content placement=\"right\">\n            <Stack direction=\"column\" gap=\"100\">\n              <Text fontSize=\"xs\" fontWeight=\"600\">Requirements:</Text>\n              <Text fontSize=\"xs\">• 3-20 characters</Text>\n              <Text fontSize=\"xs\">• Letters and numbers only</Text>\n              <Text fontSize=\"xs\">• No spaces</Text>\n            </Stack>\n          </Tooltip.Content>\n        </Tooltip.Root>\n      </Stack>\n      <TextInput\n        id=\"username-input\"\n        value={value}\n        onChange={(e) => setValue(e.target.value)}\n        placeholder=\"Enter username\"\n      />\n    </Stack>\n  );\n}\n```\n\n### Action descriptions for icon buttons\n\nClarify what icon buttons do before users click them:\n\n```jsx live-dev\nconst App = () => {\n  const [copied, setCopied] = useState(false);\n\n  const handleCopy = () => {\n    setCopied(true);\n    setTimeout(() => setCopied(false), 2000);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontSize=\"sm\">\n        Code snippet:\n      </Text>\n      <Stack\n        direction=\"row\"\n        gap=\"300\"\n        padding=\"300\"\n        backgroundColor=\"neutral.3\"\n        borderRadius=\"200\"\n        alignItems=\"center\"\n      >\n        <Text fontFamily=\"mono\" fontSize=\"sm\" flex=\"1\">\n          npm install @commercetools/nimbus\n        </Text>\n\n        <Tooltip.Root>\n          <IconButton\n            aria-label=\"Copy to clipboard\"\n            size=\"sm\"\n            variant=\"ghost\"\n            onClick={handleCopy}\n          >\n            {copied ? <Icons.Check /> : <Icons.ContentCopy />}\n          </IconButton>\n          <Tooltip.Content placement=\"top\">\n            {copied ? 'Copied!' : 'Copy to clipboard'}\n          </Tooltip.Content>\n        </Tooltip.Root>\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Contextual help in data tables\n\nProvide explanations for table headers or data values:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"300\">\n    <Stack direction=\"row\" gap=\"400\" paddingX=\"300\" paddingY=\"200\">\n      <Stack direction=\"row\" gap=\"100\" alignItems=\"center\" flex=\"1\">\n        <Text fontWeight=\"600\" fontSize=\"sm\">Product Name</Text>\n      </Stack>\n\n      <Stack direction=\"row\" gap=\"100\" alignItems=\"center\" width=\"150px\">\n        <Text fontWeight=\"600\" fontSize=\"sm\">Conversion Rate</Text>\n        <Tooltip.Root>\n          <IconButton\n            aria-label=\"About conversion rate\"\n            size=\"sm\"\n            variant=\"ghost\"\n          >\n            <Icons.HelpOutline />\n          </IconButton>\n          <Tooltip.Content placement=\"top\">\n            <Text fontSize=\"xs\">\n              Percentage of visitors who make a purchase\n            </Text>\n          </Tooltip.Content>\n        </Tooltip.Root>\n      </Stack>\n\n      <Stack direction=\"row\" gap=\"100\" alignItems=\"center\" width=\"100px\">\n        <Text fontWeight=\"600\" fontSize=\"sm\">Status</Text>\n      </Stack>\n    </Stack>\n\n    <Stack direction=\"row\" gap=\"400\" paddingX=\"300\" paddingY=\"200\" backgroundColor=\"neutral.2\">\n      <Text fontSize=\"sm\" flex=\"1\">Premium Widget</Text>\n      <Text fontSize=\"sm\" width=\"150px\">24.5%</Text>\n      <Text fontSize=\"sm\" width=\"100px\">Active</Text>\n    </Stack>\n  </Stack>\n)\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Tooltip 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 Rendering Tests\n\nVerify the tooltip renders and displays content on interaction\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Tooltip, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Tooltip - Basic rendering\", () => {\n  it(\"renders trigger element\", () => {\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>Hover me</Button>\n          <Tooltip.Content>Tooltip text</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /hover me/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"shows tooltip content on focus\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>Hover me</Button>\n          <Tooltip.Content>Tooltip text</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    // Focus the button using tab\n    await user.tab();\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"tooltip\")).toBeInTheDocument();\n      expect(screen.getByText(\"Tooltip text\")).toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Interaction Tests\n\nTest focus interactions (hover tests require browser environment)\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Tooltip, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Tooltip - Interactions\", () => {\n  it(\"shows tooltip on focus\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>Action Button</Button>\n          <Tooltip.Content>Action tooltip</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"tooltip\")).toBeInTheDocument();\n      expect(screen.getByText(\"Action tooltip\")).toBeInTheDocument();\n    });\n  });\n\n  it(\"hides tooltip when focus leaves\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>First</Button>\n          <Tooltip.Content>First tooltip</Tooltip.Content>\n        </Tooltip.Root>\n        <Button>Second</Button>\n      </NimbusProvider>\n    );\n\n    // Focus first button\n    await user.tab();\n    await waitFor(() => {\n      expect(screen.getByRole(\"tooltip\")).toBeInTheDocument();\n    });\n\n    // Focus second button\n    await user.tab();\n    await waitFor(() => {\n      expect(screen.queryByRole(\"tooltip\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Testing Placement\n\nVerify tooltip positioning\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Tooltip, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Tooltip - Placement\", () => {\n  it(\"renders with top placement\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>Trigger</Button>\n          <Tooltip.Content placement=\"top\">Top tooltip</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    // Tab to focus the button\n    await user.tab();\n\n    await waitFor(() => {\n      const tooltip = screen.getByRole(\"tooltip\");\n      expect(tooltip).toBeInTheDocument();\n      expect(tooltip).toHaveTextContent(\"Top tooltip\");\n    });\n  });\n});\n```\n\n### Testing with Portal Content\n\nTooltips render in a portal, so query from document when needed\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Tooltip, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Tooltip - Portal rendering\", () => {\n  it(\"renders tooltip in portal\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>Show tooltip</Button>\n          <Tooltip.Content>Portal content</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n\n    // Wait for portal content to appear\n    await waitFor(() => {\n      const tooltip = screen.getByRole(\"tooltip\");\n      expect(tooltip).toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Testing Custom Delay Timing\n\nVerify delay configuration works as expected\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Tooltip, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Tooltip - Timing\", () => {\n  it(\"respects custom delay\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root delay={0} closeDelay={0}>\n          <Button>Instant</Button>\n          <Tooltip.Content>Shows immediately</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n\n    // With delay={0}, tooltip should appear immediately\n    await waitFor(\n      () => {\n        expect(screen.getByRole(\"tooltip\")).toBeInTheDocument();\n      },\n      { timeout: 100 }\n    );\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-tooltip-tooltip--docs)\n- [React Aria Tooltip](https://react-spectrum.adobe.com/react-aria/Tooltip.html)\n- [ARIA Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)\n",
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Tooltip, MakeElementFocusable } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation wraps a trigger element and tooltip content:\n\n```jsx live-dev\nconst App = () => (\n  <Tooltip.Root>\n    <Button>Hover me</Button>\n    <Tooltip.Content>\n      Helpful information appears here\n    </Tooltip.Content>\n  </Tooltip.Root>\n)\n```\n\n## Usage examples\n\n### Placement options\n\nThe `placement` prop controls where the tooltip appears relative to the trigger element. The default placement is `\"bottom\"`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n    <Tooltip.Root>\n      <Button>Top</Button>\n      <Tooltip.Content placement=\"top\">\n        Top placement\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <Button>Bottom</Button>\n      <Tooltip.Content placement=\"bottom\">\n        Bottom placement\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <Button>Left</Button>\n      <Tooltip.Content placement=\"left\">\n        Left placement\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <Button>Right</Button>\n      <Tooltip.Content placement=\"right\">\n        Right placement\n      </Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n**Available placements:**\n\nThe component supports 26 placement options:\n- **Basic**: `top`, `bottom`, `left`, `right`, `start`, `end`\n- **With alignment**: `top left`, `top right`, `top start`, `top end`, `bottom left`, `bottom right`, `bottom start`, `bottom end`, `left top`, `left bottom`, `right top`, `right bottom`, `start top`, `start bottom`, `end top`, `end bottom`\n\n### Delay configuration\n\nControl when tooltips appear and disappear using `delay` and `closeDelay` props on `Tooltip.Root`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" wrap=\"wrap\">\n    <Tooltip.Root delay={0} closeDelay={0}>\n      <Button>Instant</Button>\n      <Tooltip.Content>\n        Shows immediately\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root delay={300} closeDelay={200}>\n      <Button>Default timing</Button>\n      <Tooltip.Content>\n        300ms delay to show, 200ms to hide\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root delay={1000}>\n      <Button>Slow</Button>\n      <Tooltip.Content>\n        1000ms delay to show\n      </Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n**Timing considerations:**\n- `delay`: Time in milliseconds before the tooltip appears (default: `300`)\n- `closeDelay`: Time in milliseconds before the tooltip disappears (default: `200`)\n- Shorter delays improve responsiveness but may feel too aggressive\n- Longer delays reduce accidental triggers but may feel sluggish\n\n### Complex content\n\nTooltip content can include multiple elements using layout components:\n\n```jsx live-dev\nconst App = () => (\n  <Tooltip.Root>\n    <Button>Feature info</Button>\n    <Tooltip.Content>\n      <Stack direction=\"column\" gap=\"100\">\n        <Text fontWeight=\"600\" fontSize=\"sm\">Premium Feature</Text>\n        <Text fontSize=\"xs\">\n          Available on Pro and Enterprise plans\n        </Text>\n      </Stack>\n    </Tooltip.Content>\n  </Tooltip.Root>\n)\n```\n\n### With icon buttons\n\nA common pattern is providing context for icon-only buttons:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"300\">\n    <Tooltip.Root>\n      <IconButton aria-label=\"Edit\">\n        <Icons.Edit />\n      </IconButton>\n      <Tooltip.Content placement=\"top\">\n        Edit item\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <IconButton aria-label=\"Delete\">\n        <Icons.Delete />\n      </IconButton>\n      <Tooltip.Content placement=\"top\">\n        Delete item\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <IconButton aria-label=\"Share\">\n        <Icons.Share />\n      </IconButton>\n      <Tooltip.Content placement=\"top\">\n        Share with team\n      </Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n### With focusable elements\n\nTooltips work with any focusable element. For non-interactive elements like Text, use `MakeElementFocusable`:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\">\n    <Tooltip.Root>\n      <MakeElementFocusable>\n        <Text\n          as=\"span\"\n          textDecoration=\"underline\"\n          cursor=\"help\"\n        >\n          Hover or focus me\n        </Text>\n      </MakeElementFocusable>\n      <Tooltip.Content>\n        This text element is focusable and shows a tooltip\n      </Tooltip.Content>\n    </Tooltip.Root>\n\n    <Tooltip.Root>\n      <Button variant=\"ghost\">\n        <Icons.Info />\n        Learn more\n      </Button>\n      <Tooltip.Content placement=\"right\">\n        Opens detailed documentation\n      </Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n### Disabling the tooltip\n\nUse the `isDisabled` prop on `Tooltip.Root` to suppress the tooltip without\nremoving the trigger from the tree. When `isDisabled` is `true`, hover and focus\nlisteners are inactive, the overlay never opens, and no `aria-describedby` is\nadded to the trigger. The trigger element renders unchanged with the same DOM\nand focus order.\n\nThis is useful when tooltip text is conditionally irrelevant (e.g. the trigger\nlabel already conveys the information) or when a parent feature flag should\nsuppress all tooltips in a region.\n\n```jsx live-dev\nconst App = () => {\n  const [isDisabled, setIsDisabled] = useState(true);\n  return (\n    <Stack direction=\"row\" alignItems=\"center\" gap=\"400\">\n      <Switch isSelected={isDisabled} onChange={setIsDisabled}>\n        Tooltip disabled\n      </Switch>\n      <Tooltip.Root isDisabled={isDisabled}>\n        <Button>Hover me</Button>\n        <Tooltip.Content>\n          This tooltip can be toggled\n        </Tooltip.Content>\n      </Tooltip.Root>\n    </Stack>\n  );\n}\n```\n\n> **Note:** `isDisabled` on `Tooltip.Root` disables the *tooltip overlay*. To\n> keep a tooltip visible on a *disabled button*, see\n> [With disabled buttons](#with-disabled-buttons) below.\n\n### With disabled buttons\n\nA natively disabled button cannot host a tooltip: the `disabled` attribute\nremoves it from the tab order and stops it firing hover/focus events, so the\ntooltip has nothing to open from. This is unfortunate precisely when a tooltip\nis most useful — explaining _why_ an action is unavailable.\n\nPass `allowFocusWhenDisabled` together with `isDisabled` on the `Button`. The\nbutton stays focusable and hoverable and is announced as disabled via\n`aria-disabled` (instead of the native `disabled` attribute), while its action\nstays fully suppressed. The tooltip then opens on hover and keyboard focus like\nany other trigger.\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\nPrefer this to wrapping a disabled button in `MakeElementFocusable`: the\n`allowFocusWhenDisabled` path keeps the disabled semantics on the button itself\n(`aria-disabled`) and suppresses activation, whereas a focusable wrapper only\nadds focus and describes the wrong element.\n\n## Component requirements\n\n## Accessibility\n\nThe Tooltip component is built with React Aria Components and provides accessible tooltip behavior by default. The component:\n\n- Automatically associates tooltip content with the trigger using `aria-describedby`\n- Assigns the `tooltip` ARIA role to the content\n- Shows on both hover and keyboard focus\n- Hides when focus leaves or `Escape` is pressed\n\n**Important:** Ensure the trigger element has an accessible label. For icon-only buttons, always provide an `aria-label`:\n\n```tsx\n<Tooltip.Root>\n  <IconButton aria-label=\"Delete item\">\n    <Icons.Delete />\n  </IconButton>\n  <Tooltip.Content>Delete this item</Tooltip.Content>\n</Tooltip.Root>\n```\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the trigger element:\n\n```tsx\nconst PERSISTENT_ID = \"delete-button-tooltip\";\n\nexport const Example = () => (\n  <Tooltip.Root>\n    <IconButton id={PERSISTENT_ID} aria-label=\"Delete\">\n      <Icons.Delete />\n    </IconButton>\n    <Tooltip.Content>Delete item</Tooltip.Content>\n  </Tooltip.Root>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n\n- `Tab` / `Shift+Tab`: Move focus to/from the trigger element\n- Tooltip appears automatically when trigger receives focus\n- `Escape`: Dismisses the tooltip (if shown)\n- Tooltip disappears automatically when focus leaves the trigger\n\n### Trigger element requirements\n\nThe first child of `Tooltip.Root` must be a focusable element:\n\n- Use buttons, links, or other interactive elements (recommended)\n- For non-interactive elements like Text or div, wrap with `MakeElementFocusable`\n- Avoid wrapping non-focusable elements without proper handling\n\n```tsx\n// ✅ Good - button is natively focusable\n<Tooltip.Root>\n  <Button>Trigger</Button>\n  <Tooltip.Content>Content</Tooltip.Content>\n</Tooltip.Root>\n\n// ✅ Good - non-interactive element with MakeElementFocusable\n<Tooltip.Root>\n  <MakeElementFocusable>\n    <Text as=\"span\">Trigger</Text>\n  </MakeElementFocusable>\n  <Tooltip.Content>Content</Tooltip.Content>\n</Tooltip.Root>\n\n// ❌ Bad - Text with tabIndex won't work properly\n<Tooltip.Root>\n  <Text as=\"span\" tabIndex={0}>Trigger</Text>\n  <Tooltip.Content>Content</Tooltip.Content>\n</Tooltip.Root>\n```\n\n## API reference\n\n<PropsTable id=\"Tooltip\" />\n\n## Common patterns\n\n### Info tooltips for form fields\n\nProvide additional context for form fields without cluttering the interface:\n\n```jsx live-dev\nconst App = () => {\n  const [value, setValue] = useState('');\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Stack direction=\"row\" gap=\"200\" alignItems=\"center\">\n        <Text as=\"label\" htmlFor=\"username-input\" fontWeight=\"500\">\n          Username\n        </Text>\n        <Tooltip.Root>\n          <IconButton\n            aria-label=\"Username requirements\"\n            size=\"sm\"\n            variant=\"ghost\"\n          >\n            <Icons.Info />\n          </IconButton>\n          <Tooltip.Content placement=\"right\">\n            <Stack direction=\"column\" gap=\"100\">\n              <Text fontSize=\"xs\" fontWeight=\"600\">Requirements:</Text>\n              <Text fontSize=\"xs\">• 3-20 characters</Text>\n              <Text fontSize=\"xs\">• Letters and numbers only</Text>\n              <Text fontSize=\"xs\">• No spaces</Text>\n            </Stack>\n          </Tooltip.Content>\n        </Tooltip.Root>\n      </Stack>\n      <TextInput\n        id=\"username-input\"\n        value={value}\n        onChange={(e) => setValue(e.target.value)}\n        placeholder=\"Enter username\"\n      />\n    </Stack>\n  );\n}\n```\n\n### Action descriptions for icon buttons\n\nClarify what icon buttons do before users click them:\n\n```jsx live-dev\nconst App = () => {\n  const [copied, setCopied] = useState(false);\n\n  const handleCopy = () => {\n    setCopied(true);\n    setTimeout(() => setCopied(false), 2000);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontSize=\"sm\">\n        Code snippet:\n      </Text>\n      <Stack\n        direction=\"row\"\n        gap=\"300\"\n        padding=\"300\"\n        backgroundColor=\"neutral.3\"\n        borderRadius=\"200\"\n        alignItems=\"center\"\n      >\n        <Text fontFamily=\"mono\" fontSize=\"sm\" flex=\"1\">\n          npm install @commercetools/nimbus\n        </Text>\n\n        <Tooltip.Root>\n          <IconButton\n            aria-label=\"Copy to clipboard\"\n            size=\"sm\"\n            variant=\"ghost\"\n            onClick={handleCopy}\n          >\n            {copied ? <Icons.Check /> : <Icons.ContentCopy />}\n          </IconButton>\n          <Tooltip.Content placement=\"top\">\n            {copied ? 'Copied!' : 'Copy to clipboard'}\n          </Tooltip.Content>\n        </Tooltip.Root>\n      </Stack>\n    </Stack>\n  );\n}\n```\n\n### Contextual help in data tables\n\nProvide explanations for table headers or data values:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"300\">\n    <Stack direction=\"row\" gap=\"400\" paddingX=\"300\" paddingY=\"200\">\n      <Stack direction=\"row\" gap=\"100\" alignItems=\"center\" flex=\"1\">\n        <Text fontWeight=\"600\" fontSize=\"sm\">Product Name</Text>\n      </Stack>\n\n      <Stack direction=\"row\" gap=\"100\" alignItems=\"center\" width=\"150px\">\n        <Text fontWeight=\"600\" fontSize=\"sm\">Conversion Rate</Text>\n        <Tooltip.Root>\n          <IconButton\n            aria-label=\"About conversion rate\"\n            size=\"sm\"\n            variant=\"ghost\"\n          >\n            <Icons.HelpOutline />\n          </IconButton>\n          <Tooltip.Content placement=\"top\">\n            <Text fontSize=\"xs\">\n              Percentage of visitors who make a purchase\n            </Text>\n          </Tooltip.Content>\n        </Tooltip.Root>\n      </Stack>\n\n      <Stack direction=\"row\" gap=\"100\" alignItems=\"center\" width=\"100px\">\n        <Text fontWeight=\"600\" fontSize=\"sm\">Status</Text>\n      </Stack>\n    </Stack>\n\n    <Stack direction=\"row\" gap=\"400\" paddingX=\"300\" paddingY=\"200\" backgroundColor=\"neutral.2\">\n      <Text fontSize=\"sm\" flex=\"1\">Premium Widget</Text>\n      <Text fontSize=\"sm\" width=\"150px\">24.5%</Text>\n      <Text fontSize=\"sm\" width=\"100px\">Active</Text>\n    </Stack>\n  </Stack>\n)\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Tooltip 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 Rendering Tests\n\nVerify the tooltip renders and displays content on interaction\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Tooltip, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Tooltip - Basic rendering\", () => {\n  it(\"renders trigger element\", () => {\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>Hover me</Button>\n          <Tooltip.Content>Tooltip text</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: /hover me/i })\n    ).toBeInTheDocument();\n  });\n\n  it(\"shows tooltip content on focus\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>Hover me</Button>\n          <Tooltip.Content>Tooltip text</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    // Focus the button using tab\n    await user.tab();\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"tooltip\")).toBeInTheDocument();\n      expect(screen.getByText(\"Tooltip text\")).toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Interaction Tests\n\nTest focus interactions (hover tests require browser environment)\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Tooltip, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Tooltip - Interactions\", () => {\n  it(\"shows tooltip on focus\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>Action Button</Button>\n          <Tooltip.Content>Action tooltip</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"tooltip\")).toBeInTheDocument();\n      expect(screen.getByText(\"Action tooltip\")).toBeInTheDocument();\n    });\n  });\n\n  it(\"hides tooltip when focus leaves\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>First</Button>\n          <Tooltip.Content>First tooltip</Tooltip.Content>\n        </Tooltip.Root>\n        <Button>Second</Button>\n      </NimbusProvider>\n    );\n\n    // Focus first button\n    await user.tab();\n    await waitFor(() => {\n      expect(screen.getByRole(\"tooltip\")).toBeInTheDocument();\n    });\n\n    // Focus second button\n    await user.tab();\n    await waitFor(() => {\n      expect(screen.queryByRole(\"tooltip\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Testing Placement\n\nVerify tooltip positioning\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Tooltip, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Tooltip - Placement\", () => {\n  it(\"renders with top placement\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>Trigger</Button>\n          <Tooltip.Content placement=\"top\">Top tooltip</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    // Tab to focus the button\n    await user.tab();\n\n    await waitFor(() => {\n      const tooltip = screen.getByRole(\"tooltip\");\n      expect(tooltip).toBeInTheDocument();\n      expect(tooltip).toHaveTextContent(\"Top tooltip\");\n    });\n  });\n});\n```\n\n### Testing with Portal Content\n\nTooltips render in a portal, so query from document when needed\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Tooltip, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Tooltip - Portal rendering\", () => {\n  it(\"renders tooltip in portal\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root>\n          <Button>Show tooltip</Button>\n          <Tooltip.Content>Portal content</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n\n    // Wait for portal content to appear\n    await waitFor(() => {\n      const tooltip = screen.getByRole(\"tooltip\");\n      expect(tooltip).toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Testing Custom Delay Timing\n\nVerify delay configuration works as expected\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Tooltip, Button, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Tooltip - Timing\", () => {\n  it(\"respects custom delay\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Tooltip.Root delay={0} closeDelay={0}>\n          <Button>Instant</Button>\n          <Tooltip.Content>Shows immediately</Tooltip.Content>\n        </Tooltip.Root>\n      </NimbusProvider>\n    );\n\n    // Use userEvent.tab() instead of element.focus() to avoid act() warnings\n    await user.tab();\n\n    // With delay={0}, tooltip should appear immediately\n    await waitFor(\n      () => {\n        expect(screen.getByRole(\"tooltip\")).toBeInTheDocument();\n      },\n      { timeout: 100 }\n    );\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-tooltip-tooltip--docs)\n- [React Aria Tooltip](https://react-spectrum.adobe.com/react-aria/Tooltip.html)\n- [ARIA Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)\n",
       "toc": [
         {
           "value": "Getting started",
@@ -264,6 +264,28 @@
           ],
           "parent": "root"
         },
+        {
+          "value": "Disabling the tooltip",
+          "href": "#disabling-the-tooltip",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With disabled buttons",
+          "href": "#with-disabled-buttons",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
         {
           "value": "Component requirements",
           "href": "#component-requirements",