@commercetools/nimbus-mcp 3.2.0 → 3.3.0

package/data/docs/routes/components-feedback-activity-indicator.json

@@ -0,0 +1,396 @@
+{
+  "meta": {
+    "id": "Components-ActivityIndicator",
+    "title": "Activity indicator",
+    "exportName": "ActivityIndicator",
+    "description": "An animated three-dot indicator that signals ongoing agent or system activity, such as \"thinking\", \"processing\", or \"typing\" in chat and AI surfaces.",
+    "lifecycleState": "Experimental",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/activity-indicator/activity-indicator.mdx",
+    "menu": [
+      "Components",
+      "Feedback",
+      "Activity indicator"
+    ],
+    "route": "components/feedback/activity-indicator",
+    "tags": [
+      "component",
+      "activity",
+      "typing",
+      "dots",
+      "chat"
+    ],
+    "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": "Visuals",
+        "href": "#visuals",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Inline with text",
+        "href": "#inline-with-text",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "On a solid colored surface",
+        "href": "#on-a-solid-colored-surface",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=10603-16574&m=dev",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nThe activity indicator communicates that an agent or system is actively working\n— for example composing a reply, thinking, or processing a request. It is most\ncommonly placed inline next to a short status message (\"Thinking…\", \"Processing\nrequest\") in chat and AI surfaces.\n\nUnlike the [Loading spinner](/components/feedback/loadingspinner), which\nrepresents indeterminate progress and signals \"please wait\", the activity\nindicator is a lightweight, presentational hint. Reach for the loading spinner\nwhen something is loading and for the activity indicator when an agent is\nactive.\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?node-id=10603-16574&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visuals\n\n#### Inline with text\n\nBy default the indicator scales with the surrounding `font-size`, so it sits\nnaturally beside a status label.\n\n```jsx live\nconst App = () => (\n  <Text fontSize=\"md\">\n    Thinking <ActivityIndicator />\n  </Text>\n);\n```\n\n#### On a solid colored surface\n\nWhen the indicator sits on a solid colored fill, use `variant=\"contrast\"`. The\ndots take the palette's `contrast` step (black or white, chosen automatically per\npalette) so they stay legible on the surface.\n\n```jsx live\nconst App = () => (\n  <Stack\n    colorPalette=\"primary\"\n    backgroundColor=\"colorPalette.9\"\n    padding=\"400\"\n  >\n    <Text color=\"colorPalette.contrast\">\n      Thinking{\" \"}\n      <ActivityIndicator colorPalette=\"primary\" variant=\"contrast\" />\n    </Text>\n  </Stack>\n);\n```\n\n### Size\n\nThe default `inherit` size tracks the surrounding text. Fixed sizes (`2xs`–`lg`)\nreserve a square icon-box footprint so the indicator can sit in input icon slots\nalongside other icons.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <ActivityIndicator size=\"lg\" />\n    <ActivityIndicator size=\"md\" />\n    <ActivityIndicator size=\"sm\" />\n    <ActivityIndicator size=\"xs\" />\n    <ActivityIndicator size=\"2xs\" />\n  </Stack>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThe activity indicator communicates that an agent or system is actively working\n— for example composing a reply, thinking, or processing a request. It is most\ncommonly placed inline next to a short status message (\"Thinking…\", \"Processing\nrequest\") in chat and AI surfaces.\n\nUnlike the [Loading spinner](/components/feedback/loadingspinner), which\nrepresents indeterminate progress and signals \"please wait\", the activity\nindicator is a lightweight, presentational hint. Reach for the loading spinner\nwhen something is loading and for the activity indicator when an agent is\nactive.\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?node-id=10603-16574&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visuals\n\n#### Inline with text\n\nBy default the indicator scales with the surrounding `font-size`, so it sits\nnaturally beside a status label.\n\n```jsx live\nconst App = () => (\n  <Text fontSize=\"md\">\n    Thinking <ActivityIndicator />\n  </Text>\n);\n```\n\n#### On a solid colored surface\n\nWhen the indicator sits on a solid colored fill, use `variant=\"contrast\"`. The\ndots take the palette's `contrast` step (black or white, chosen automatically per\npalette) so they stay legible on the surface.\n\n```jsx live\nconst App = () => (\n  <Stack\n    colorPalette=\"primary\"\n    backgroundColor=\"colorPalette.9\"\n    padding=\"400\"\n  >\n    <Text color=\"colorPalette.contrast\">\n      Thinking{\" \"}\n      <ActivityIndicator colorPalette=\"primary\" variant=\"contrast\" />\n    </Text>\n  </Stack>\n);\n```\n\n### Size\n\nThe default `inherit` size tracks the surrounding text. Fixed sizes (`2xs`–`lg`)\nreserve a square icon-box footprint so the indicator can sit in input icon slots\nalongside other icons.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <ActivityIndicator size=\"lg\" />\n    <ActivityIndicator size=\"md\" />\n    <ActivityIndicator size=\"sm\" />\n    <ActivityIndicator size=\"xs\" />\n    <ActivityIndicator size=\"2xs\" />\n  </Stack>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visuals",
+          "href": "#visuals",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Inline with text",
+          "href": "#inline-with-text",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "On a solid colored surface",
+          "href": "#on-a-solid-colored-surface",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport {\n  ActivityIndicator,\n  type ActivityIndicatorProps,\n} from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\nThe ActivityIndicator signals that an agent or system is actively working. By\ndefault it is decorative and scales with the surrounding `font-size`, so it can\nsit inline next to a visible status label.\n\n```jsx live-dev\nconst App = () => (\n  <Text>\n    Thinking <ActivityIndicator />\n  </Text>\n);\n```\n\n## Usage examples\n\n### Size options\n\nThe `size` prop defaults to `inherit`, which ties the indicator's box to the\nsurrounding `font-size` (`1em`) so it scales with the text. The fixed sizes\n(`2xs`, `xs`, `sm`, `md`, `lg`) reserve a square icon-box footprint — the same\nscale points `LoadingSpinner` uses — so the indicator drops into input start/end\nicon slots interchangeably with a spinner.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <ActivityIndicator size=\"2xs\" />\n    <ActivityIndicator size=\"xs\" />\n    <ActivityIndicator size=\"sm\" />\n    <ActivityIndicator size=\"md\" />\n    <ActivityIndicator size=\"lg\" />\n  </Stack>\n);\n```\n\n### Color palette\n\nThe `colorPalette` prop accepts any Nimbus color palette (default `primary`). The\ndots are filled from the palette's `11` shade.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <ActivityIndicator colorPalette=\"primary\" />\n    <ActivityIndicator colorPalette=\"positive\" />\n    <ActivityIndicator colorPalette=\"info\" />\n  </Stack>\n);\n```\n\n### On a solid colored surface\n\nWhen the dots sit on a solid colored fill (e.g. an agent bubble), use\n`variant=\"contrast\"`. This fills the dots from the palette's `contrast` step,\nwhich resolves to black or white automatically per palette so the dots stay\nlegible on the surface.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Box colorPalette=\"primary\" bg=\"colorPalette.9\" padding=\"400\" borderRadius=\"200\">\n      <ActivityIndicator colorPalette=\"primary\" variant=\"contrast\" />\n    </Box>\n    <Box colorPalette=\"ctyellow\" bg=\"colorPalette.9\" padding=\"400\" borderRadius=\"200\">\n      <ActivityIndicator colorPalette=\"ctyellow\" variant=\"contrast\" />\n    </Box>\n  </Stack>\n);\n```\n\n## Accessibility\n\nThe ActivityIndicator is **purely decorative** — it is always marked\n`aria-hidden`, so assistive technology never announces the animation itself.\nAlways pair it with visible text that conveys the state (for example\n\"Thinking…\"), so screen-reader users get the same information sighted users do.\n\n```tsx\n// Visible text conveys the state; the indicator is decorative.\n<Text>\n  Thinking <ActivityIndicator />\n</Text>\n```\n\n**Announcing the activity to assistive technology is the consumer's\nresponsibility**, not the component's. The indicator does not own a live region,\nbecause it is typically rendered only while activity is in progress — and a live\nregion mounted together with its content is not announced reliably across screen\nreaders (the region must already exist in the DOM before its content changes).\nIf you need to announce the activity without adjacent visible text, drive a\n**persistent** live region owned by the surrounding chat/turn container (for\nexample via React Aria's [`@react-aria/live-announcer`](https://react-spectrum.adobe.com/react-aria/announce.html)),\nand keep the indicator decorative.\n\nThis component is **not** a progress indicator and does not use\n`role=\"progressbar\"`. For indeterminate progress (\"please wait\"), use\n[LoadingSpinner](/components/feedback/loadingspinner) instead.\n\n## Reduced motion\n\nWhen the user has `prefers-reduced-motion: reduce` enabled, the vertical bounce\nis replaced by a gentle opacity pulse, so the \"working\" state remains\nperceivable without large motion.\n\n## API reference\n\n<PropsTable id=\"ActivityIndicator\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using\nActivityIndicator 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### Basic Rendering Tests\n\nVerify the indicator renders and exposes the expected accessibility semantics\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { ActivityIndicator, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ActivityIndicator - Basic rendering\", () => {\n  it(\"is decorative by default (aria-hidden, no role)\", () => {\n    render(\n      <NimbusProvider>\n        <ActivityIndicator data-testid=\"indicator\" />\n      </NimbusProvider>\n    );\n\n    const indicator = screen.getByTestId(\"indicator\");\n    expect(indicator).toBeInTheDocument();\n    expect(indicator).toHaveAttribute(\"aria-hidden\", \"true\");\n    expect(indicator).not.toHaveAttribute(\"role\");\n  });\n\n  it(\"renders three dot elements\", () => {\n    render(\n      <NimbusProvider>\n        <ActivityIndicator data-testid=\"indicator\" />\n      </NimbusProvider>\n    );\n\n    const dots = screen.getByTestId(\"indicator\").querySelectorAll(\"[data-dot]\");\n    expect(dots).toHaveLength(3);\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-activityindicator--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": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Color palette",
+          "href": "#color-palette",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "On a solid colored surface",
+          "href": "#on-a-solid-colored-surface",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Reduced motion",
+          "href": "#reduced-motion",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nActivity indicator guidelines aim to communicate that an agent or system is\nactively working — composing, thinking, or processing — in a way that feels\nlightweight and conversational, without implying that the user must wait for a\nblocking operation to finish.\n\n### Best practices\n\n- **Pair with a status label:** Place the indicator inline next to a short,\n  human-readable message (\"Thinking…\", \"Processing request\"). The default size\n  scales with the surrounding text, so it aligns naturally.\n- **Use the right tool for the job:** Use the activity indicator for agent or\n  conversational activity. For indeterminate loading where the user must wait,\n  use the [Loading spinner](/components/feedback/loadingspinner) instead.\n- **Match the surface:** On neutral or page backgrounds, keep the default\n  (`plain`) treatment. When the dots sit on a solid colored fill — such as an\n  agent bubble — use `variant=\"contrast\"` so they take the palette's contrast\n  color (black or white) and stay legible.\n- **Always pair it with visible text:** The indicator is purely decorative\n  (`aria-hidden`), so screen readers rely on the adjacent text (\"Thinking…\") to\n  convey the state. Never use it as the sole indication of activity.\n- **Announce from the container, not the indicator:** If you need to announce\n  activity without adjacent visible text, drive a persistent live region owned\n  by the surrounding chat/turn container (e.g. `@react-aria/live-announcer`).\n  The indicator itself does not own a live region — it is usually mounted only\n  while active, and a live region mounted with its content does not announce\n  reliably.\n- **Respect motion preferences:** The indicator automatically swaps its bounce\n  for a gentle pulse under `prefers-reduced-motion`. Do not reintroduce large\n  motion on top of it.\n\n### Usage\n\n> [!TIP]\\\n> When to use\n\n- **Agent is composing or thinking:** A chat or AI surface is generating a\n  response.\n- **Short, non-blocking activity:** A brief background step where the user can\n  keep reading or interacting.\n- **Inline with a status message:** Alongside text such as \"Thinking…\" or\n  \"Processing request\".\n\n> [!CAUTION]\\\n> When not to use\n\n- **Indeterminate loading the user must wait for:** Use the\n  [Loading spinner](/components/feedback/loadingspinner).\n- **Determinate progress:** Use a progress bar so the user can see how far along\n  the operation is.\n- **Persistent, page-level busy states:** Prefer a clearly labeled loading state\n  with context.\n\n### Accessibility\n\n- The indicator is purely decorative (`aria-hidden`) and relies on adjacent\n  visible text to convey meaning to assistive technology.\n- It does not own a live region. Announce activity from a persistent live region\n  in the surrounding container (e.g. `@react-aria/live-announcer`) when no\n  adjacent visible text is present.\n- It is not a progress indicator and never uses `role=\"progressbar\"`.\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "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",