@commercetools/nimbus-mcp 0.1.0 → 2.10.0

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

@@ -0,0 +1,510 @@
+{
+  "meta": {
+    "id": "Components-tooltip",
+    "title": "Tooltip",
+    "exportName": "Tooltip",
+    "description": "A contextual popup that displays a description for an element.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/tooltip/tooltip.mdx",
+    "menu": [
+      "Components",
+      "Feedback",
+      "Tooltip"
+    ],
+    "route": "components/feedback/tooltip",
+    "tags": [
+      "component",
+      "tooltip",
+      "popover",
+      "hint",
+      "hover"
+    ],
+    "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": "Placements",
+        "href": "#placements",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?node-id=1695-45519&m",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nTooltips offer concise, non-obtrusive guidance and supplemental information,\nenhancing user understanding and interaction with UI elements.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React-Aria Tooltip Docs](https://react-spectrum.adobe.com/react-aria/Tooltip.html#tooltip)\n[ARIA Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)\n[Figma library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?node-id=1695-45519&m)\n\n## Variables\n\nGet familiar with the features.\n\n### Placements\n\nTooltip placements can populate in different areas, please chose a direction\nthat will be most visible for the users. and the elements that may be\ninteracting around them. Options include bottom left, bottom center, bottom\nright, top left, top center, top right, left top, left center, left bottom,\nright top, right center, right bottom.\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nTooltips offer concise, non-obtrusive guidance and supplemental information,\nenhancing user understanding and interaction with UI elements.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React-Aria Tooltip Docs](https://react-spectrum.adobe.com/react-aria/Tooltip.html#tooltip)\n[ARIA Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/)\n[Figma library](https://www.figma.com/design/gHbAJGfcrCv7f2bgzUQgHq/NIMBUS-Guidelines?node-id=1695-45519&m)\n\n## Variables\n\nGet familiar with the features.\n\n### Placements\n\nTooltip placements can populate in different areas, please chose a direction\nthat will be most visible for the users. and the elements that may be\ninteracting around them. Options include bottom left, bottom center, bottom\nright, top left, top center, top right, left top, left center, left bottom,\nright top, right center, right bottom.\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": "Placements",
+          "href": "#placements",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nTooltip triggers must be focusable and hoverable in order to ensure that all\nusers can activate them. When displayed, the Tooltip automatically associates\nthe tooltip with the trigger element so that it is described by the tooltip\ncontent.\n\nAuthors should ensure that elements with the\n[role](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles)\ntooltip are referenced through the use of\n[aria-describedby](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-describedby)\nbefore or at the time the tooltip is displayed.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" alignItems=\"center\" marginLeft=\"800\" padding=\"800\" gap=\"400\">\n    <Tooltip.Root>\n      <Button>Hover me</Button>\n      <Tooltip.Content>This is a tooltip</Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n### Accessibility standards\n\n- **Non-text content:** Provide a text alternative (alt text or equivalent) for\n  non-text content within tooltips.\n- **Info and relationships:** Programmatically establish the relationship\n  between a tooltip and its trigger element using ARIA attributes like\n  `aria-describedby`. Assign an id to the trigger element and point\n  `aria-describedby` to that id.\n- **Use of color:** Avoid relying solely on color to convey information within\n  tooltips.\n- **Color contrast:** Ensure tooltip text meets minimum contrast ratio\n  requirements. Use a contrast checking tool.\n- **Keyboard accessibility:** Make tooltips triggered by keyboard focus operable\n  via keyboard. Allow users to navigate to the trigger using the Tab key. Make\n  the tooltip appear on focus. Prevent tooltips from trapping keyboard focus.\n  Make interactive tooltip content keyboard accessible.\n- **Focus visible:** Provide a visible focus indicator for the tooltip trigger\n  element when it receives keyboard focus.\n- **Language of page:** Programmatically determine the tooltip content's\n  language. Use the `lang` attribute on the tooltip element.\n- **On focus:** Prevent tooltips that appear on focus from unexpectedly changing\n  the page context.\n- **Labels or instructions:** Write tooltip text that is clear, concise, and\n  easy to understand.\n- **Name, role, value:** Ensure assistive technologies correctly interpret the\n  role of the tooltip trigger element. Use semantic HTML. Use `aria-describedby`\n  to associate the tooltip with the trigger.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { 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",
+      "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": "Placement options",
+          "href": "#placement-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Delay configuration",
+          "href": "#delay-configuration",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Complex content",
+          "href": "#complex-content",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With icon buttons",
+          "href": "#with-icon-buttons",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "With focusable elements",
+          "href": "#with-focusable-elements",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Trigger element requirements",
+          "href": "#trigger-element-requirements",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Info tooltips for form fields",
+          "href": "#info-tooltips-for-form-fields",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Action descriptions for icon buttons",
+          "href": "#action-descriptions-for-icon-buttons",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Contextual help in data tables",
+          "href": "#contextual-help-in-data-tables",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Placement",
+          "href": "#testing-placement",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing with Portal Content",
+          "href": "#testing-with-portal-content",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing Custom Delay Timing",
+          "href": "#testing-custom-delay-timing",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nUse tooltips to provide brief explanations, definitions, or instructions for\ninteractive elements, enhancing the user experience.\n\n### Best practices\n\n- **Be concise:** Keep tooltip text short and to the point. Avoid lengthy\n  explanations; if more detail is needed, consider a different approach like a\n  modal or help documentation.\n- **Provide valuable context:** Tooltips should offer information that isn't\n  immediately obvious from the UI element itself. They should add value, not\n  just restate what's already visible.\n- **Use clear and simple language:** Avoid jargon, technical terms, or overly\n  complex phrasing. Tooltips should be easily understood by all users.\n- **Position tooltips appropriately:** Place tooltips so they don't obscure the\n  element they're related to or other important UI elements. Consider the user's\n  mouse path and avoid accidental triggers.\n- **Maintain accessibility:** Includes keyboard navigation and screen reader\n  compatibility. Use ARIA attributes like `aria-describedby`to link the tooltip\n  to its target element.\n- **Avoid overuse:** Don't use tooltips for every single UI element. Overuse can\n  make the interface feel cluttered.\n- **Don't rely on tooltips for essential information:** Crucial information\n  (like error states) should never be exclusively conveyed through tooltips, as\n  they are not always discoverable or accessible to all users. Use tooltips for\n  supplementary or secondary details.\n\n## Usage\n\nTooltips are a valuable tool for providing concise, contextual information, but\nthey should be used strategically and not as a replacement for clear and\naccessible design. Think carefully about the type of information you're\npresenting and choose the most appropriate UI element for the job.\n\n### Basic usage\n\nThe recommended approach using the compound component pattern:\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" alignItems=\"center\" marginLeft=\"800\" padding=\"800\" gap=\"400\">\n    <Tooltip.Root>\n      <Button>Hover me</Button>\n      <Tooltip.Content>This is a tooltip</Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n### Using tooltips for icons buttons\n\nIcons often rely on shared universal understanding. A tooltip provides a text\nlabel that removes any ambiguity and ensures users understand the button's\nfunction. This is especially important for less common or custom icons.\n\n> [!TIP]\\\n> **Do**\n>\n> - Describe the icon's action quickly and concisely.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" alignItems=\"center\" marginLeft=\"800\" padding=\"800\" gap=\"400\">\n    <Tooltip.Root>\n      <IconButton colorPalette=\"primary\" variant=\"ghost\" size=\"md\">\n        <Icons.Edit/>\n      </IconButton>\n      <Tooltip.Content>Edit name</Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not describe the icon visually.\n> - Do not over explain the action to the user.\n> - Don't overlap tooltips with the object it is clarifying.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" alignItems=\"center\" gap=\"100\" marginLeft=\"800\" padding=\"800\">\n    <Tooltip.Root>\n      <IconButton\n        colorPalette=\"primary\"\n        variant=\"ghost\"\n        size=\"md\"\n      >\n        <Icons.Edit/>\n      </IconButton>\n      <Tooltip.Content>\n        Pencil icon that will let you edit your profile name if you like.\n      </Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\n\n### Placement options\n\nControl where the tooltip appears relative to its trigger:\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" alignItems=\"center\" marginLeft=\"800\" padding=\"800\" gap=\"400\">\n    <Tooltip.Root>\n      <Button>Top placement</Button>\n      <Tooltip.Content placement=\"top\">Tooltip on top</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root>\n      <Button>Bottom placement</Button>\n      <Tooltip.Content placement=\"bottom\">Tooltip on bottom</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root>\n      <Button>Left placement</Button>\n      <Tooltip.Content placement=\"left\">Tooltip on left</Tooltip.Content>\n    </Tooltip.Root>\n    <Tooltip.Root>\n      <Button>Right placement</Button>\n      <Tooltip.Content placement=\"right\">Tooltip on right</Tooltip.Content>\n    </Tooltip.Root>\n  </Stack>\n)\n```\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": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Using tooltips for icons buttons",
+          "href": "#using-tooltips-for-icons-buttons",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Placement options",
+          "href": "#placement-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,34 @@
+{
+  "meta": {
+    "id": "Components-Feedback",
+    "title": "Feedback",
+    "description": "Components for providing user feedback.",
+    "order": 6,
+    "repoPath": "packages/nimbus/src/docs/feedback.mdx",
+    "menu": [
+      "Components",
+      "Feedback"
+    ],
+    "route": "components/feedback",
+    "tags": [
+      "document"
+    ],
+    "toc": [],
+    "icon": "CommentBank",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Feedback\n\nComponents for providing user feedback.\n\n<CategoryOverview variant=\"list\" />\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Feedback\n\nComponents for providing user feedback.\n\n<CategoryOverview variant=\"list\" />\n",
+      "toc": []
+    }
+  }
+}