@commercetools/nimbus-mcp 0.1.0 → 2.11.0

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

@@ -0,0 +1,682 @@
+{
+  "meta": {
+    "id": "Components-Dialog",
+    "title": "Dialog",
+    "exportName": "Dialog",
+    "description": "A foundational dialog component for overlays that require user attention and interaction. Built with React Aria Components for accessibility and WCAG 2.1 AA compliance.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/dialog/dialog.mdx",
+    "menu": [
+      "Components",
+      "Feedback",
+      "Dialog"
+    ],
+    "route": "components/feedback/dialog",
+    "tags": [
+      "component",
+      "overlay",
+      "dialog",
+      "modal",
+      "interactive"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Key features",
+        "href": "#key-features",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Basic Usage",
+        "href": "#basic-usage",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Placement Options",
+        "href": "#placement-options",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Scroll Behavior",
+        "href": "#scroll-behavior",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Controlled State",
+        "href": "#controlled-state",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          5
+        ],
+        "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\nDialogs are overlay windows that appear on top of the main content to display\nimportant information, gather user input, or require user decisions. They\ntemporarily disable the main interface until the user completes an action or\ndismisses the dialog.\n\n### Key features\n\n- **Accessibility First**: Built with React Aria Components for WCAG 2.1 AA\n  compliance\n- **Flexible Positioning**: Support for center, top, and bottom placements\n- **Responsive Sizing**: Multiple size variants from xs to full-screen\n- **Smooth Animations**: Customizable motion presets for entrance/exit\n- **Focus Management**: Automatic focus trapping and restoration\n- **Keyboard Navigation**: Full keyboard support including Escape to close\n- **Scroll Handling**: Options for inside or outside scrolling behavior\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria Dialog Docs](https://react-spectrum.adobe.com/react-aria/Dialog.html)\n[ARIA Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)\n[Figma Design 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### Basic Usage\n\n```jsx live\nconst App = () => (\n  <Dialog.Root>\n    <Dialog.Trigger>Anything can be a trigger</Dialog.Trigger>\n    <Dialog.Content>\n      <Dialog.Header>\n        <Dialog.Title>Dialog Title</Dialog.Title>\n        <Dialog.CloseTrigger />\n      </Dialog.Header>\n      <Dialog.Body>\n        This is a basic dialog with default settings. It includes a backdrop,\n        title, description, and close button for a complete experience.\n      </Dialog.Body>\n      <Dialog.Footer>\n        <Button variant=\"outline\" slot=\"close\">\n          Cancel\n        </Button>\n        <Button>Save</Button>\n      </Dialog.Footer>\n    </Dialog.Content>\n  </Dialog.Root>\n);\n```\n\n### Size\n\nControl the dialog width by applying `width` prop on the Content component, it's\na regular style-prop, so you can use all size-tokens but also custom values.\n\n```jsx live\nconst App = () => (\n  <Dialog.Root>\n    <Dialog.Trigger asChild>\n      <Button>Open Large Dialog</Button>\n    </Dialog.Trigger>\n    <Dialog.Content width=\"3xl\">\n      <Dialog.Header>\n        <Dialog.Title>Large Dialog</Dialog.Title>\n        <Dialog.CloseTrigger />\n      </Dialog.Header>\n      <Dialog.Body>\n        This dialog uses a custom width. You can change the width by adjusting\n        the width prop on Dialog.Root to values like \"xs\", \"sm\", \"md\", \"lg\",\n        \"xl\", or \"full\", but also raw css values.\n      </Dialog.Body>\n    </Dialog.Content>\n  </Dialog.Root>\n);\n```\n\n### Placement Options\n\nPosition the dialog at different locations using the `placement` prop:\n\n```jsx live\nconst App = () => {\n  const placements = [\n    {\n      value: \"center\",\n      label: \"Center (default)\",\n      description: \"Centered in the viewport, works well for most use cases\",\n    },\n    {\n      value: \"top\",\n      label: \"Top\",\n      description: \"Appears at the top, useful for notifications or alerts\",\n    },\n    {\n      value: \"bottom\",\n      label: \"Bottom\",\n      description:\n        \"Appears at the bottom, good for mobile-friendly sheets or action panels\",\n    },\n  ];\n\n  return (\n    <Stack direction=\"row\" gap=\"400\">\n      {placements.map((placement) => (\n        <Dialog.Root key={placement.value} placement={placement.value}>\n          <Dialog.Trigger asChild>\n            <Button>{placement.label}</Button>\n          </Dialog.Trigger>\n          <Dialog.Content>\n            <Dialog.Header>\n              <Dialog.Title>{placement.label} Placement</Dialog.Title>\n              <Dialog.CloseTrigger />\n            </Dialog.Header>\n            <Dialog.Body>{placement.description}</Dialog.Body>\n          </Dialog.Content>\n        </Dialog.Root>\n      ))}\n    </Stack>\n  );\n};\n```\n\n### Scroll Behavior\n\nHandle long content with different scrolling approaches using the\n`scrollBehavior` prop:\n\n```jsx live\nconst App = () => {\n  const scrollBehaviors = [\n    {\n      value: \"outside\",\n      label: \"Outside (default)\",\n      description: \"Default scroll behavior, entire dialog scrolls\",\n    },\n    {\n      value: \"inside\",\n      label: \"Inside\",\n      description: \"Contained scrolling within the dialog body\",\n    },\n  ];\n\n  return (\n    <Stack direction=\"row\" gap=\"400\">\n      {scrollBehaviors.map((behavior) => (\n        <Dialog.Root key={behavior.value} scrollBehavior={behavior.value}>\n          <Dialog.Trigger asChild>\n            <Button>{behavior.label}</Button>\n          </Dialog.Trigger>\n          <Dialog.Content width=\"sm\">\n            <Dialog.Header>\n              <Dialog.Title>{behavior.label} Scrolling</Dialog.Title>\n              <Dialog.CloseTrigger />\n            </Dialog.Header>\n            <Dialog.Body>\n              <Stack>\n                <Text>{behavior.description}</Text>\n                {Array.from({ length: 20 }, (_, i) => (\n                  <Text key={i}>\n                    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed\n                    do eiusmod tempor incididunt ut labore et dolore magna\n                    aliqua.\n                  </Text>\n                ))}\n              </Stack>\n            </Dialog.Body>\n          </Dialog.Content>\n        </Dialog.Root>\n      ))}\n    </Stack>\n  );\n};\n```\n\n### Controlled State\n\nUse external state to control the dialog programmatically:\n\n```jsx live\nconst App = () => {\n  const [isOpen, setIsOpen] = React.useState(false);\n\n  return (\n    <Stack>\n      <Button onClick={() => setIsOpen(true)}>Open Controlled Dialog</Button>\n\n      <Text>Dialog is currently: {isOpen ? \"open\" : \"closed\"}</Text>\n\n      <Dialog.Root isOpen={isOpen} onOpenChange={setIsOpen}>\n        <Dialog.Content>\n          <Dialog.Header>\n            <Dialog.Title>Controlled Dialog</Dialog.Title>\n            <Dialog.CloseTrigger />\n          </Dialog.Header>\n          <Dialog.Body>\n            This dialog's state is controlled by the parent component. You can\n            open/close it programmatically or through user interaction.\n          </Dialog.Body>\n          <Dialog.Footer>\n            <Button variant=\"outline\" onClick={() => setIsOpen(false)}>\n              Cancel\n            </Button>\n            <Button onClick={() => setIsOpen(false)}>Save</Button>\n          </Dialog.Footer>\n        </Dialog.Content>\n      </Dialog.Root>\n    </Stack>\n  );\n};\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nDialogs are overlay windows that appear on top of the main content to display\nimportant information, gather user input, or require user decisions. They\ntemporarily disable the main interface until the user completes an action or\ndismisses the dialog.\n\n### Key features\n\n- **Accessibility First**: Built with React Aria Components for WCAG 2.1 AA\n  compliance\n- **Flexible Positioning**: Support for center, top, and bottom placements\n- **Responsive Sizing**: Multiple size variants from xs to full-screen\n- **Smooth Animations**: Customizable motion presets for entrance/exit\n- **Focus Management**: Automatic focus trapping and restoration\n- **Keyboard Navigation**: Full keyboard support including Escape to close\n- **Scroll Handling**: Options for inside or outside scrolling behavior\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React Aria Dialog Docs](https://react-spectrum.adobe.com/react-aria/Dialog.html)\n[ARIA Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)\n[Figma Design 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### Basic Usage\n\n```jsx live\nconst App = () => (\n  <Dialog.Root>\n    <Dialog.Trigger>Anything can be a trigger</Dialog.Trigger>\n    <Dialog.Content>\n      <Dialog.Header>\n        <Dialog.Title>Dialog Title</Dialog.Title>\n        <Dialog.CloseTrigger />\n      </Dialog.Header>\n      <Dialog.Body>\n        This is a basic dialog with default settings. It includes a backdrop,\n        title, description, and close button for a complete experience.\n      </Dialog.Body>\n      <Dialog.Footer>\n        <Button variant=\"outline\" slot=\"close\">\n          Cancel\n        </Button>\n        <Button>Save</Button>\n      </Dialog.Footer>\n    </Dialog.Content>\n  </Dialog.Root>\n);\n```\n\n### Size\n\nControl the dialog width by applying `width` prop on the Content component, it's\na regular style-prop, so you can use all size-tokens but also custom values.\n\n```jsx live\nconst App = () => (\n  <Dialog.Root>\n    <Dialog.Trigger asChild>\n      <Button>Open Large Dialog</Button>\n    </Dialog.Trigger>\n    <Dialog.Content width=\"3xl\">\n      <Dialog.Header>\n        <Dialog.Title>Large Dialog</Dialog.Title>\n        <Dialog.CloseTrigger />\n      </Dialog.Header>\n      <Dialog.Body>\n        This dialog uses a custom width. You can change the width by adjusting\n        the width prop on Dialog.Root to values like \"xs\", \"sm\", \"md\", \"lg\",\n        \"xl\", or \"full\", but also raw css values.\n      </Dialog.Body>\n    </Dialog.Content>\n  </Dialog.Root>\n);\n```\n\n### Placement Options\n\nPosition the dialog at different locations using the `placement` prop:\n\n```jsx live\nconst App = () => {\n  const placements = [\n    {\n      value: \"center\",\n      label: \"Center (default)\",\n      description: \"Centered in the viewport, works well for most use cases\",\n    },\n    {\n      value: \"top\",\n      label: \"Top\",\n      description: \"Appears at the top, useful for notifications or alerts\",\n    },\n    {\n      value: \"bottom\",\n      label: \"Bottom\",\n      description:\n        \"Appears at the bottom, good for mobile-friendly sheets or action panels\",\n    },\n  ];\n\n  return (\n    <Stack direction=\"row\" gap=\"400\">\n      {placements.map((placement) => (\n        <Dialog.Root key={placement.value} placement={placement.value}>\n          <Dialog.Trigger asChild>\n            <Button>{placement.label}</Button>\n          </Dialog.Trigger>\n          <Dialog.Content>\n            <Dialog.Header>\n              <Dialog.Title>{placement.label} Placement</Dialog.Title>\n              <Dialog.CloseTrigger />\n            </Dialog.Header>\n            <Dialog.Body>{placement.description}</Dialog.Body>\n          </Dialog.Content>\n        </Dialog.Root>\n      ))}\n    </Stack>\n  );\n};\n```\n\n### Scroll Behavior\n\nHandle long content with different scrolling approaches using the\n`scrollBehavior` prop:\n\n```jsx live\nconst App = () => {\n  const scrollBehaviors = [\n    {\n      value: \"outside\",\n      label: \"Outside (default)\",\n      description: \"Default scroll behavior, entire dialog scrolls\",\n    },\n    {\n      value: \"inside\",\n      label: \"Inside\",\n      description: \"Contained scrolling within the dialog body\",\n    },\n  ];\n\n  return (\n    <Stack direction=\"row\" gap=\"400\">\n      {scrollBehaviors.map((behavior) => (\n        <Dialog.Root key={behavior.value} scrollBehavior={behavior.value}>\n          <Dialog.Trigger asChild>\n            <Button>{behavior.label}</Button>\n          </Dialog.Trigger>\n          <Dialog.Content width=\"sm\">\n            <Dialog.Header>\n              <Dialog.Title>{behavior.label} Scrolling</Dialog.Title>\n              <Dialog.CloseTrigger />\n            </Dialog.Header>\n            <Dialog.Body>\n              <Stack>\n                <Text>{behavior.description}</Text>\n                {Array.from({ length: 20 }, (_, i) => (\n                  <Text key={i}>\n                    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed\n                    do eiusmod tempor incididunt ut labore et dolore magna\n                    aliqua.\n                  </Text>\n                ))}\n              </Stack>\n            </Dialog.Body>\n          </Dialog.Content>\n        </Dialog.Root>\n      ))}\n    </Stack>\n  );\n};\n```\n\n### Controlled State\n\nUse external state to control the dialog programmatically:\n\n```jsx live\nconst App = () => {\n  const [isOpen, setIsOpen] = React.useState(false);\n\n  return (\n    <Stack>\n      <Button onClick={() => setIsOpen(true)}>Open Controlled Dialog</Button>\n\n      <Text>Dialog is currently: {isOpen ? \"open\" : \"closed\"}</Text>\n\n      <Dialog.Root isOpen={isOpen} onOpenChange={setIsOpen}>\n        <Dialog.Content>\n          <Dialog.Header>\n            <Dialog.Title>Controlled Dialog</Dialog.Title>\n            <Dialog.CloseTrigger />\n          </Dialog.Header>\n          <Dialog.Body>\n            This dialog's state is controlled by the parent component. You can\n            open/close it programmatically or through user interaction.\n          </Dialog.Body>\n          <Dialog.Footer>\n            <Button variant=\"outline\" onClick={() => setIsOpen(false)}>\n              Cancel\n            </Button>\n            <Button onClick={() => setIsOpen(false)}>Save</Button>\n          </Dialog.Footer>\n        </Dialog.Content>\n      </Dialog.Root>\n    </Stack>\n  );\n};\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Key features",
+          "href": "#key-features",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Placement Options",
+          "href": "#placement-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Scroll Behavior",
+          "href": "#scroll-behavior",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled State",
+          "href": "#controlled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => (\n  <Dialog.Root>\n    <Dialog.Trigger>\n      <Button>Open dialog</Button>\n    </Dialog.Trigger>\n    <Dialog.Content>\n      <Dialog.Header>\n        <Dialog.Title>Dialog Title</Dialog.Title>\n        <Dialog.CloseTrigger />\n      </Dialog.Header>\n      <Dialog.Body>\n          This is a basic dialog with default settings. It includes a backdrop,\n          title, description, and close button for a complete experience.\n      </Dialog.Body>\n      <Dialog.Footer>\n        <Button variant=\"outline\" slot=\"close\">Cancel</Button>\n        <Button>Save</Button>\n      </Dialog.Footer>\n    </Dialog.Content>\n  </Dialog.Root>\n)\n```\n\n### Accessibility standards\n\n- **Keyboard navigation:** Tab moves focus to next focusable element within\n  dialog, Shift + Tab moves to previous element, Escape closes the dialog\n  (unless disabled), Enter/Space activates focused button or trigger.\n- **Role identification:** Dialog has `dialog` role with proper labeling.\n- **Focus management:** Focus moves to dialog on open and returns to trigger on\n  close.\n- **Focus containment:** Tab navigation stays within dialog boundaries.\n- **Accessible names:** Title and description properly associate with dialog.\n- **State announcements:** Screen readers announce when dialog opens/closes.\n- **Info and relationships:** Proper semantic structure with header, body, and\n  footer.\n- **Contrast:** All text meets minimum contrast requirements.\n- **Non-text contrast:** Focus indicators and UI components meet contrast\n  standards.\n- **No keyboard trap:** Focus contained but escapable via Escape key.\n- **Focus order:** Logical focus progression through dialog elements.\n- **Focus visible:** Clear focus indicators on all interactive elements.\n- **On focus:** No unexpected context changes when focusing elements.\n- **On input:** Predictable behavior for all user interactions.\n- **Labels or instructions:** Clear labeling and instructions where needed.\n- **Name, role, value:** Proper semantic markup and ARIA attributes.\n- **Status messages:** Appropriate announcements for state changes.\n\n### Resources\n\n- [W3C ARIA Authoring Practices Guide (APG) - Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)\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"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Dialog, type DialogRootProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe Dialog component uses a compound component pattern. You must wrap all parts in `Dialog.Root`. The component handles focus management, keyboard navigation, and portal rendering automatically.\n\n```jsx live-dev\nconst App = () => (\n  <Dialog.Root>\n    <Dialog.Trigger>Open Dialog</Dialog.Trigger>\n    <Dialog.Content>\n      <Dialog.Header>\n        <Dialog.Title>Dialog Title</Dialog.Title>\n        <Dialog.CloseTrigger />\n      </Dialog.Header>\n      <Dialog.Body>\n        <Text>This is the dialog content. It automatically handles focus management and keyboard navigation.</Text>\n      </Dialog.Body>\n      <Dialog.Footer>\n        <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n        <Button variant=\"solid\">Confirm</Button>\n      </Dialog.Footer>\n    </Dialog.Content>\n  </Dialog.Root>\n)\n```\n\n## Usage examples\n\n### Placement options\n\nThe `placement` prop on `Dialog.Root` controls where the dialog appears in the viewport. Three options are available: `center` (default), `top`, and `bottom`.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" flexWrap=\"wrap\">\n    <Dialog.Root placement=\"center\">\n      <Dialog.Trigger>Center (Default)</Dialog.Trigger>\n      <Dialog.Content>\n        <Dialog.Header>\n          <Dialog.Title>Center Placement</Dialog.Title>\n          <Dialog.CloseTrigger />\n        </Dialog.Header>\n        <Dialog.Body>\n          <Text>The dialog is centered vertically and horizontally in the viewport.</Text>\n        </Dialog.Body>\n      </Dialog.Content>\n    </Dialog.Root>\n\n    <Dialog.Root placement=\"top\">\n      <Dialog.Trigger>Top Placement</Dialog.Trigger>\n      <Dialog.Content>\n        <Dialog.Header>\n          <Dialog.Title>Top Placement</Dialog.Title>\n          <Dialog.CloseTrigger />\n        </Dialog.Header>\n        <Dialog.Body>\n          <Text>The dialog appears near the top of the viewport with margin spacing.</Text>\n        </Dialog.Body>\n      </Dialog.Content>\n    </Dialog.Root>\n\n    <Dialog.Root placement=\"bottom\">\n      <Dialog.Trigger>Bottom Placement</Dialog.Trigger>\n      <Dialog.Content>\n        <Dialog.Header>\n          <Dialog.Title>Bottom Placement</Dialog.Title>\n          <Dialog.CloseTrigger />\n        </Dialog.Header>\n        <Dialog.Body>\n          <Text>The dialog appears near the bottom of the viewport with margin spacing.</Text>\n        </Dialog.Body>\n      </Dialog.Content>\n    </Dialog.Root>\n  </Stack>\n)\n```\n\n### Scroll behavior\n\nThe `scrollBehavior` prop determines how overflow content is handled. Use `outside` (default) for page-level scrolling or `inside` to confine scrolling to the dialog body.\n\n```jsx live-dev\nconst App = () => {\n  const longContent = Array.from({ length: 60 }, (_, i) => (\n    <Text key={i}>Line {i + 1} of long content that will cause overflow.</Text>\n  ));\n\n  return (\n    <Stack direction=\"row\" gap=\"400\">\n      <Dialog.Root scrollBehavior=\"outside\">\n        <Dialog.Trigger>Outside (Default)</Dialog.Trigger>\n        <Dialog.Content>\n          <Dialog.Header>\n            <Dialog.Title>Scroll Outside</Dialog.Title>\n            <Dialog.CloseTrigger />\n          </Dialog.Header>\n          <Dialog.Body>\n            <Stack direction=\"column\" gap=\"200\">\n              <Text fontWeight=\"600\">The entire modal scrolls when content overflows.</Text>\n              {longContent}\n            </Stack>\n          </Dialog.Body>\n        </Dialog.Content>\n      </Dialog.Root>\n\n      <Dialog.Root scrollBehavior=\"inside\">\n        <Dialog.Trigger>Inside Body</Dialog.Trigger>\n        <Dialog.Content>\n          <Dialog.Header>\n            <Dialog.Title>Scroll Inside Body</Dialog.Title>\n            <Dialog.CloseTrigger />\n          </Dialog.Header>\n          <Dialog.Body>\n            <Stack direction=\"column\" gap=\"200\">\n              <Text fontWeight=\"600\">Only the body scrolls; header and footer remain fixed.</Text>\n              {longContent}\n            </Stack>\n          </Dialog.Body>\n          <Dialog.Footer>\n            <Button slot=\"close\">Close</Button>\n          </Dialog.Footer>\n        </Dialog.Content>\n      </Dialog.Root>\n    </Stack>\n  );\n}\n```\n\n### Uncontrolled mode\n\nThe dialog manages its own open/close state internally without requiring external state management. Use the `defaultOpen` prop if you need the dialog to start open on mount (though this is rarely needed in practice).\n\n```jsx live-dev\nconst App = () => (\n  <Dialog.Root>\n    <Dialog.Trigger>Open Dialog</Dialog.Trigger>\n    <Dialog.Content>\n      <Dialog.Header>\n        <Dialog.Title>Uncontrolled Dialog</Dialog.Title>\n        <Dialog.CloseTrigger />\n      </Dialog.Header>\n      <Dialog.Body>\n        <Text>\n          This dialog manages its own state. The parent component doesn't need to track whether it's open or closed.\n          You can set defaultOpen={'{true}'} on Dialog.Root if you need it to start open on mount.\n        </Text>\n      </Dialog.Body>\n      <Dialog.Footer>\n        <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n        <Button slot=\"close\">Save</Button>\n      </Dialog.Footer>\n    </Dialog.Content>\n  </Dialog.Root>\n)\n```\n\n### Controlled mode\n\nUse `isOpen` and `onOpenChange` to control the dialog state externally. This is essential when you need to open the dialog programmatically or track state changes.\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState<DialogRootProps[\"isOpen\"]>(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\" alignItems=\"flex-start\">\n      <Button onPress={() => setIsOpen(true)}>Open Dialog</Button>\n\n      <Text>Dialog state: <Code>{isOpen ? 'Open' : 'Closed'}</Code></Text>\n\n      <Dialog.Root isOpen={isOpen} onOpenChange={setIsOpen}>\n        <Dialog.Content>\n          <Dialog.Header>\n            <Dialog.Title>Controlled Dialog</Dialog.Title>\n            <Dialog.CloseTrigger />\n          </Dialog.Header>\n          <Dialog.Body>\n            <Text>This dialog's state is controlled externally.</Text>\n          </Dialog.Body>\n          <Dialog.Footer>\n            <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n            <Button onPress={() => setIsOpen(false)}>Confirm</Button>\n          </Dialog.Footer>\n        </Dialog.Content>\n      </Dialog.Root>\n    </Stack>\n  );\n}\n```\n\n### Dismissal behavior\n\nControl how users can close the dialog using three props: `isDismissable`, `isKeyboardDismissDisabled`, and `shouldCloseOnInteractOutside`. These work together to create the right dismissal behavior for your use case.\n\n#### Default\n\nBy default, dialogs can only be closed with the Escape key or close buttons. Clicking the backdrop does nothing. This is the standard behavior for most dialogs.\n\n```jsx live-dev\nconst App = () => (\n  <Dialog.Root>\n    <Dialog.Trigger>Default Behavior</Dialog.Trigger>\n    <Dialog.Content>\n      <Dialog.Header>\n        <Dialog.Title>Default Dismissal</Dialog.Title>\n        <Dialog.CloseTrigger />\n      </Dialog.Header>\n      <Dialog.Body>\n        <Stack direction=\"column\" gap=\"200\">\n          <Text fontWeight=\"600\">Can be closed by:</Text>\n          <Text>✓ Escape key</Text>\n          <Text>✓ Close button</Text>\n          <Text>✗ Clicking backdrop (does nothing)</Text>\n        </Stack>\n      </Dialog.Body>\n    </Dialog.Content>\n  </Dialog.Root>\n)\n```\n\n#### Dismissable Dialogs\n\nUse `isDismissable={true}` for non-critical dialogs like notifications or informational content where users should be able to quickly dismiss by clicking outside.\n\n```jsx live-dev\nconst App = () => (\n  <Dialog.Root isDismissable>\n    <Dialog.Trigger>Dismissible Notification</Dialog.Trigger>\n    <Dialog.Content>\n      <Dialog.Header>\n        <Dialog.Title>Quick Notification</Dialog.Title>\n        <Dialog.CloseTrigger />\n      </Dialog.Header>\n      <Dialog.Body>\n        <Stack direction=\"column\" gap=\"200\">\n          <Text>Use isDismissable={'{true}'} for non-critical dialogs.</Text>\n          <Text fontWeight=\"600\">Can be closed by:</Text>\n          <Text>✓ Escape key</Text>\n          <Text>✓ Close button</Text>\n          <Text>✓ Clicking backdrop</Text>\n        </Stack>\n      </Dialog.Body>\n    </Dialog.Content>\n  </Dialog.Root>\n)\n```\n\n#### Critical Confirmations\n\nUse `isKeyboardDismissDisabled={true}` for critical confirmations where you need to ensure users explicitly choose an action rather than accidentally dismissing.\n\n```jsx live-dev\nconst App = () => (\n  <Dialog.Root isKeyboardDismissDisabled>\n    <Dialog.Trigger>Critical Action</Dialog.Trigger>\n    <Dialog.Content>\n      <Dialog.Header>\n        <Dialog.Title>Confirm Deletion</Dialog.Title>\n      </Dialog.Header>\n      <Dialog.Body>\n        <Stack direction=\"column\" gap=\"200\">\n          <Text>Use isKeyboardDismissDisabled={'{true}'} for critical confirmations.</Text>\n          <Text fontWeight=\"600\">Can be closed by:</Text>\n          <Text>✓ Close button only</Text>\n          <Text>✗ Escape key (disabled)</Text>\n          <Text>✗ Clicking backdrop (does nothing)</Text>\n        </Stack>\n      </Dialog.Body>\n      <Dialog.Footer>\n        <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n        <Button colorPalette=\"critical\">Delete</Button>\n      </Dialog.Footer>\n    </Dialog.Content>\n  </Dialog.Root>\n)\n```\n\n#### Conditional dismissal\n\nCombine `isDismissable` with `isKeyboardDismissDisabled` &  `shouldCloseOnInteractOutside` to implement custom logic, such as protecting unsaved form changes.\nThis example prevents backdrop and keyboard dismissal when there are unsaved changes.\n\n```jsx live-dev\nconst App = () => {\n  const [formData, setFormData] = useState('');\n  const [lastAction, setLastAction] = useState('');\n\n  const hasUnsavedChanges = formData.length > 0;\n\n  const canBeClosed = () => {\n    if (hasUnsavedChanges) {\n      setLastAction('Prevented - unsaved changes detected');\n      alert('Unsaved changes detected');\n      return false;\n    }\n    setLastAction('Allowed - no unsaved changes');\n    return true;\n  }\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Text fontSize=\"sm\" color=\"fg.muted\">\n        Last dismissal attempt: {lastAction || 'None'}\n      </Text>\n\n      <Dialog.Root\n        isDismissable\n        isKeyboardDismissDisabled={hasUnsavedChanges}\n        shouldCloseOnInteractOutside={canBeClosed}\n      >\n        <Dialog.Trigger>Form with Protection</Dialog.Trigger>\n        <Dialog.Content>\n          <Dialog.Header>\n            <Dialog.Title>Edit Profile</Dialog.Title>\n            <Dialog.CloseTrigger />\n          </Dialog.Header>\n          <Dialog.Body>\n            <Stack direction=\"column\" gap=\"400\">\n              <Text>\n                Combines isDismissable with shouldCloseOnInteractOutside to protect unsaved work.\n                Try typing, then clicking outside.\n              </Text>\n              <TextInput\n                placeholder=\"Your name\"\n                value={formData}\n                onChange={(value) => setFormData(value)}\n              />\n              <Text fontSize=\"sm\">\n                Unsaved changes: <Code>{hasUnsavedChanges ? 'Yes' : 'No'}</Code>\n              </Text>\n            </Stack>\n          </Dialog.Body>\n          <Dialog.Footer>\n            <Button\n              slot=\"close\"\n              variant=\"outline\"\n              onPress={() => setFormData('')}\n            >\n              Cancel\n            </Button>\n            <Button onPress={() => {\n              setFormData('');\n              setLastAction('Saved and closed');\n            }}>\n              Save\n            </Button>\n          </Dialog.Footer>\n        </Dialog.Content>\n      </Dialog.Root>\n    </Stack>\n  );\n}\n```\n\n### Flexible composition\n\nThe dialog parts are composable. You can omit optional parts based on your needs. These real-world examples demonstrate when and why to use different compositions.\n\n#### Order cancellation with full context\n\nUse the complete structure (header, body, footer) when users need detailed information before making a decision. This e-commerce example shows refund implications before confirming cancellation.\n\n```jsx live-dev\nconst App = () => {\n  const [isCancelling, setIsCancelling] = useState(false);\n  const [isOpen, setIsOpen] = useState<DialogRootProps[\"isOpen\"]>(false);\n\n  const handleCancel = () => {\n    setIsCancelling(true);\n    // Simulate API call\n    setTimeout(() => {\n      setIsCancelling(false);\n      setIsOpen(false);\n      alert('Order #12345 has been cancelled. Refund will be processed in 3-5 business days.');\n    }, 1500);\n  };\n\n  return (\n    <Dialog.Root isOpen={isOpen} onOpenChange={setIsOpen}>\n      <Dialog.Trigger>Cancel Order</Dialog.Trigger>\n      <Dialog.Content>\n        <Dialog.Header>\n          <Dialog.Title>Cancel Order #12345</Dialog.Title>\n          <Dialog.CloseTrigger />\n        </Dialog.Header>\n        <Dialog.Body>\n          <Stack direction=\"column\" gap=\"400\">\n            <Text>\n              Are you sure you want to cancel this order? This action will:\n            </Text>\n            <Stack direction=\"column\" gap=\"200\" paddingLeft=\"400\">\n              <Text>• Process a full refund to your original payment method</Text>\n              <Text>• Stop the shipment if it hasn't been dispatched</Text>\n              <Text>• Send a cancellation confirmation email</Text>\n            </Stack>\n            <Text fontSize=\"sm\" color=\"fg.muted\">\n              Refunds typically take 3-5 business days to appear in your account.\n            </Text>\n          </Stack>\n        </Dialog.Body>\n        <Dialog.Footer>\n          <Button slot=\"close\" variant=\"outline\" isDisabled={isCancelling}>\n            Keep Order\n          </Button>\n          <Button\n            colorPalette=\"critical\"\n            onPress={handleCancel}\n            isLoading={isCancelling}\n          >\n            Cancel Order\n          </Button>\n        </Dialog.Footer>\n      </Dialog.Content>\n    </Dialog.Root>\n  );\n}\n```\n\n#### Feature announcement without footer\n\nOmit the footer when actions are embedded in the body content or when only dismissal is needed. This pattern works well for informational dialogs with inline calls-to-action.\n\n```jsx live-dev\nconst App = () => (\n  <Dialog.Root>\n    <Dialog.Trigger>What's New</Dialog.Trigger>\n    <Dialog.Content>\n      <Dialog.Header>\n        <Dialog.Title>New Dashboard Available</Dialog.Title>\n        <Dialog.CloseTrigger />\n      </Dialog.Header>\n      <Dialog.Body>\n        <Stack direction=\"column\" gap=\"400\">\n          <Text>\n            We've redesigned the analytics dashboard with enhanced data visualization,\n            real-time updates, and customizable widgets.\n          </Text>\n          <Stack direction=\"column\" gap=\"200\">\n            <Text fontWeight=\"600\">Key improvements:</Text>\n            <Text>• Interactive charts with drill-down capabilities</Text>\n            <Text>• Custom date range filtering</Text>\n            <Text>• Export reports in multiple formats</Text>\n          </Stack>\n          <Button variant=\"solid\" width=\"full\">\n            Explore New Dashboard\n          </Button>\n        </Stack>\n      </Dialog.Body>\n    </Dialog.Content>\n  </Dialog.Root>\n)\n```\n\n#### Processing state without actions\n\nOmit the footer entirely when showing non-interruptible processes. Users can't take action until the operation completes, so only the header and progress information are needed.\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState<DialogRootProps[\"isOpen\"]>(false);\n  const [progress, setProgress] = useState(0);\n  const [deletedCount, setDeletedCount] = useState(0);\n  const totalItems = 247;\n\n  const startDeletion = () => {\n    setIsOpen(true);\n    setProgress(0);\n    setDeletedCount(0);\n\n    // Simulate progressive deletion\n    const interval = setInterval(() => {\n      setProgress((prev) => {\n        const newProgress = prev + 5;\n        if (newProgress >= 100) {\n          clearInterval(interval);\n          setTimeout(() => {\n            setIsOpen(false);\n            alert(`Successfully deleted ${totalItems} products`);\n          }, 500);\n          return 100;\n        }\n        return newProgress;\n      });\n      setDeletedCount((prev) => Math.min(prev + 12, totalItems));\n    }, 200);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Button onPress={startDeletion}>Delete 247 Products</Button>\n      <Dialog.Root\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        isDismissable={false}\n        isKeyboardDismissDisabled\n      >\n        <Dialog.Content width=\"sm\">\n          <Dialog.Header>\n            <Dialog.Title>Deleting Products</Dialog.Title>\n          </Dialog.Header>\n          <Dialog.Body>\n            <Stack direction=\"column\" gap=\"400\">\n              <Text>\n                Please wait while we delete the selected products. This may take a moment.\n              </Text>\n              <Stack direction=\"column\" gap=\"200\">\n                <Text fontSize=\"sm\" color=\"fg.muted\">\n                  {deletedCount} of {totalItems} products deleted\n                </Text>\n                <Box\n                  width=\"full\"\n                  height=\"8px\"\n                  backgroundColor=\"neutral.3\"\n                  borderRadius=\"full\"\n                  overflow=\"hidden\"\n                >\n                  <Box\n                    height=\"full\"\n                    width={`${progress}%`}\n                    backgroundColor=\"primary.9\"\n                    transition=\"width 0.2s\"\n                  />\n                </Box>\n              </Stack>\n            </Stack>\n          </Dialog.Body>\n        </Dialog.Content>\n      </Dialog.Root>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nThe `Dialog` component is built with React Aria Components and follows WCAG 2.1 AA guidelines:\n\n- **Role**: The dialog content has `role=\"dialog\"` and is properly labeled using either `Dialog.Title` or an `aria-label` prop on `Dialog.Root`.\n- **Focus Management**: When opened, focus moves to the first focusable element inside the dialog. When closed, focus returns to the trigger element.\n- **Keyboard Navigation**:\n  - `Escape` - Closes the dialog (unless `isKeyboardDismissDisabled` is true)\n  - `Tab` - Moves focus through interactive elements within the dialog\n  - Focus is trapped within the dialog while open\n- **Labeling**: The `Dialog.Title` component automatically provides the accessible name. If you don't use `Dialog.Title`, provide an `aria-label` on `Dialog.Root`.\n- **Backdrop**: Clicking outside the dialog closes it by default (controlled by `isDismissable`).\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"confirm-delete-dialog\";\n\nexport const DeleteConfirmation = () => (\n  <Dialog.Root id={PERSISTENT_ID}>\n    <Dialog.Trigger>Delete Item</Dialog.Trigger>\n    <Dialog.Content>\n      <Dialog.Title>Confirm Deletion</Dialog.Title>\n    </Dialog.Content>\n  </Dialog.Root>\n);\n```\n\n### Composition constraints\n\nThe `Dialog` component uses specific layout slots for proper rendering:\n\n- Keep sub-components (`Header`, `Body`, `Footer`, `Title`, `CloseTrigger`) as direct children of `Dialog.Content`.\n- `Dialog.Title` should be placed inside `Dialog.Header` for proper layout.\n- `Dialog.CloseTrigger` can be placed anywhere but is typically in `Dialog.Header`.\n- You can use layout components *inside* `Dialog.Body` or `Dialog.Footer` to organize content within those sections.\n- The `Dialog.Content` is portaled to the document body by React Aria, so it renders outside your component tree.\n\n## Common patterns\n\n### Confirmation dialogs\n\nUse dialogs to confirm destructive actions. Make the intent clear with appropriate button variants.\n\n```jsx live-dev\nconst App = () => {\n  const [isDeleting, setIsDeleting] = useState(false);\n  const [isOpen, setIsOpen] = useState<DialogRootProps[\"isOpen\"]>(false);\n\n  const handleDelete = () => {\n    setIsDeleting(true);\n    // Simulate async delete operation\n    setTimeout(() => {\n      setIsDeleting(false);\n      setIsOpen(false);\n      alert('Item deleted successfully');\n    }, 1500);\n  };\n\n  return (\n    <Dialog.Root isOpen={isOpen} onOpenChange={setIsOpen}>\n      <Dialog.Trigger>Delete Item</Dialog.Trigger>\n      <Dialog.Content>\n        <Dialog.Header>\n          <Dialog.Title>Confirm Deletion</Dialog.Title>\n          <Dialog.CloseTrigger />\n        </Dialog.Header>\n        <Dialog.Body>\n          <Text>\n            Are you sure you want to delete this item? This action cannot be undone.\n          </Text>\n        </Dialog.Body>\n        <Dialog.Footer>\n          <Button slot=\"close\" variant=\"outline\" isDisabled={isDeleting}>\n            Cancel\n          </Button>\n          <Button\n            colorPalette=\"critical\"\n            onPress={handleDelete}\n            isLoading={isDeleting}\n          >\n            Delete\n          </Button>\n        </Dialog.Footer>\n      </Dialog.Content>\n    </Dialog.Root>\n  );\n}\n```\n\n### Form dialogs\n\nDialogs can contain forms for data entry. Use controlled mode to handle form submission and validation.\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState<DialogRootProps[\"isOpen\"]>(false);\n  const [formData, setFormData] = useState({ name: '', email: '' });\n  const [isSaving, setIsSaving] = useState(false);\n\n  const handleSubmit = (e: React.FormEvent) => {\n    e.preventDefault();\n    setIsSaving(true);\n    // Simulate async save\n    setTimeout(() => {\n      setIsSaving(false);\n      setIsOpen(false);\n      alert(`Saved: ${formData.name} (${formData.email})`);\n      setFormData({ name: '', email: '' });\n    }, 1500);\n  };\n\n  return (\n    <Dialog.Root isOpen={isOpen} onOpenChange={setIsOpen}>\n      <Dialog.Trigger>Add User</Dialog.Trigger>\n      <Dialog.Content>\n        <form onSubmit={handleSubmit}>\n          <Dialog.Header>\n            <Dialog.Title>Create New User</Dialog.Title>\n            <Dialog.CloseTrigger />\n          </Dialog.Header>\n          <Dialog.Body>\n            <Stack direction=\"column\" gap=\"400\">\n              <FormField.Root>\n                <FormField.Label>Name</FormField.Label>\n                <FormField.Input>\n                  <TextInput\n                    value={formData.name}\n                    onChange={(value) => setFormData({ ...formData, name: value })}\n                    required\n                  />\n                </FormField.Input>\n              </FormField.Root>\n\n              <FormField.Root>\n                <FormField.Label>Email</FormField.Label>\n                <FormField.Input>\n                  <TextInput\n                    type=\"email\"\n                    value={formData.email}\n                    onChange={(value) => setFormData({ ...formData, email: value })}\n                    required\n                  />\n                </FormField.Input>\n              </FormField.Root>\n            </Stack>\n          </Dialog.Body>\n          <Dialog.Footer>\n            <Button\n              slot=\"close\"\n              variant=\"outline\"\n              isDisabled={isSaving}\n              onPress={() => setFormData({ name: '', email: '' })}\n            >\n              Cancel\n            </Button>\n            <Button type=\"submit\" isLoading={isSaving}>\n              Create User\n            </Button>\n          </Dialog.Footer>\n        </form>\n      </Dialog.Content>\n    </Dialog.Root>\n  );\n}\n```\n\n### Alert dialogs\n\nFor important messages that require acknowledgment. Consider making these non-dismissable to ensure users see the message.\n\n```jsx live-dev\nconst App = () => (\n  <Dialog.Root isDismissable={false}>\n    <Dialog.Trigger>Show Alert</Dialog.Trigger>\n    <Dialog.Content>\n      <Dialog.Header>\n        <Dialog.Title>System Maintenance</Dialog.Title>\n      </Dialog.Header>\n      <Dialog.Body>\n        <Stack direction=\"column\" gap=\"300\">\n          <Text>\n            The system will undergo scheduled maintenance on Saturday at 2:00 AM UTC.\n            During this time, the service will be unavailable for approximately 30 minutes.\n          </Text>\n          <Text fontWeight=\"600\">\n            Please save your work and plan accordingly.\n          </Text>\n        </Stack>\n      </Dialog.Body>\n      <Dialog.Footer>\n        <Button slot=\"close\">I Understand</Button>\n      </Dialog.Footer>\n    </Dialog.Content>\n  </Dialog.Root>\n)\n```\n### Keyboard navigation\n\n| Key | Action |\n|-----|--------|\n| `Tab` | Move focus to next focusable element within dialog |\n| `Shift + Tab` | Move focus to previous focusable element within dialog |\n| `Escape` | Close the dialog (unless disabled) |\n| `Enter/Space` | Activate focused button or trigger |\n\n## API reference\n\n<PropsTable id=\"Dialog\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Dialog 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 dialog renders with expected elements\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Dialog,\n  Button,\n  TextInput,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"Dialog - Basic rendering\", () => {\n  it(\"renders trigger button\", () => {\n    render(\n      <NimbusProvider>\n        <Dialog.Root>\n          <Dialog.Trigger>Open Dialog</Dialog.Trigger>\n          <Dialog.Content>\n            <Dialog.Body>Content</Dialog.Body>\n          </Dialog.Content>\n        </Dialog.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"button\", { name: \"Open Dialog\" })\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### Opening and Closing Interaction Tests\n\nTest opening and closing the dialog\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Dialog,\n  Button,\n  TextInput,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"Dialog - Opening and closing\", () => {\n  it(\"opens dialog when trigger is clicked\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Dialog.Root>\n          <Dialog.Trigger>Open</Dialog.Trigger>\n          <Dialog.Content>\n            <Dialog.Title>Test Dialog</Dialog.Title>\n            <Dialog.Body>Dialog content</Dialog.Body>\n          </Dialog.Content>\n        </Dialog.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Open\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n      expect(screen.getByText(\"Dialog content\")).toBeInTheDocument();\n    });\n  });\n\n  it(\"closes dialog when close trigger is clicked\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Dialog.Root>\n          <Dialog.Trigger>Open</Dialog.Trigger>\n          <Dialog.Content>\n            <Dialog.Title>Test Dialog</Dialog.Title>\n            <Dialog.Body>Content</Dialog.Body>\n            <Dialog.CloseTrigger />\n          </Dialog.Content>\n        </Dialog.Root>\n      </NimbusProvider>\n    );\n\n    // Open dialog\n    await user.click(screen.getByRole(\"button\", { name: \"Open\" }));\n    await waitFor(() => expect(screen.getByRole(\"dialog\")).toBeInTheDocument());\n\n    // Close dialog\n    await user.click(screen.getByRole(\"button\", { name: \"Close dialog\" }));\n\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled component behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Dialog,\n  Button,\n  TextInput,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"Dialog - Controlled mode\", () => {\n  const ControlledDialog = () => {\n    const [isOpen, setIsOpen] = useState(false);\n\n    return (\n      <NimbusProvider>\n        <Button onPress={() => setIsOpen(true)}>Open External</Button>\n        <Dialog.Root isOpen={isOpen} onOpenChange={setIsOpen}>\n          <Dialog.Content>\n            <Dialog.Title>Controlled Dialog</Dialog.Title>\n            <Dialog.Body>Content</Dialog.Body>\n          </Dialog.Content>\n        </Dialog.Root>\n      </NimbusProvider>\n    );\n  };\n\n  it(\"opens dialog via external control\", async () => {\n    const user = userEvent.setup();\n    render(<ControlledDialog />);\n\n    await user.click(screen.getByRole(\"button\", { name: \"Open External\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Form Submission Tests\n\nTest form handling within dialogs\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Dialog,\n  Button,\n  TextInput,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"Dialog - Form submission\", () => {\n  const FormDialog = ({\n    onSubmit,\n  }: {\n    onSubmit: (data: { name: string }) => void;\n  }) => {\n    const [name, setName] = useState(\"\");\n\n    return (\n      <NimbusProvider>\n        <Dialog.Root>\n          <Dialog.Trigger>Add User</Dialog.Trigger>\n          <Dialog.Content>\n            <form\n              onSubmit={(e) => {\n                e.preventDefault();\n                onSubmit({ name });\n              }}\n            >\n              <Dialog.Header>\n                <Dialog.Title>Create User</Dialog.Title>\n              </Dialog.Header>\n              <Dialog.Body>\n                <TextInput\n                  aria-label=\"Name\"\n                  placeholder=\"Name\"\n                  value={name}\n                  onChange={(value) => setName(value)}\n                />\n              </Dialog.Body>\n              <Dialog.Footer>\n                <Button type=\"submit\">Create</Button>\n              </Dialog.Footer>\n            </form>\n          </Dialog.Content>\n        </Dialog.Root>\n      </NimbusProvider>\n    );\n  };\n\n  it(\"submits form with entered data\", async () => {\n    const user = userEvent.setup();\n    const handleSubmit = vi.fn();\n\n    render(<FormDialog onSubmit={handleSubmit} />);\n\n    // Open dialog\n    await user.click(screen.getByRole(\"button\", { name: \"Add User\" }));\n    await waitFor(() => expect(screen.getByRole(\"dialog\")).toBeInTheDocument());\n\n    // Fill form\n    await user.type(screen.getByPlaceholderText(\"Name\"), \"John Doe\");\n\n    // Submit\n    await user.click(screen.getByRole(\"button\", { name: \"Create\" }));\n\n    expect(handleSubmit).toHaveBeenCalledWith({ name: \"John Doe\" });\n  });\n});\n```\n\n### Keyboard Navigation Tests\n\nTest keyboard interactions\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Dialog,\n  Button,\n  TextInput,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"Dialog - Keyboard navigation\", () => {\n  it(\"closes dialog when Escape is pressed\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Dialog.Root>\n          <Dialog.Trigger>Open</Dialog.Trigger>\n          <Dialog.Content>\n            <Dialog.Title>Test Dialog</Dialog.Title>\n            <Dialog.Body>Content</Dialog.Body>\n          </Dialog.Content>\n        </Dialog.Root>\n      </NimbusProvider>\n    );\n\n    // Open dialog\n    await user.click(screen.getByRole(\"button\", { name: \"Open\" }));\n    await waitFor(() => expect(screen.getByRole(\"dialog\")).toBeInTheDocument());\n\n    // Press Escape\n    await user.keyboard(\"{Escape}\");\n\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n  });\n\n  it(\"does not close when Escape is disabled\", async () => {\n    const user = userEvent.setup();\n\n    render(\n      <NimbusProvider>\n        <Dialog.Root isKeyboardDismissDisabled>\n          <Dialog.Trigger>Open</Dialog.Trigger>\n          <Dialog.Content>\n            <Dialog.Title>Test Dialog</Dialog.Title>\n            <Dialog.Body>Content</Dialog.Body>\n          </Dialog.Content>\n        </Dialog.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Open\" }));\n    await waitFor(() => expect(screen.getByRole(\"dialog\")).toBeInTheDocument());\n\n    await user.keyboard(\"{Escape}\");\n\n    // Dialog should still be open\n    expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Dialog Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-overlay-dialog--docs)\n- [React Aria Dialog Documentation](https://react-spectrum.adobe.com/react-aria/Dialog.html)\n- [ARIA Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)\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": "Scroll behavior",
+          "href": "#scroll-behavior",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Dismissal behavior",
+          "href": "#dismissal-behavior",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Default",
+          "href": "#default",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Dismissable Dialogs",
+          "href": "#dismissable-dialogs",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Critical Confirmations",
+          "href": "#critical-confirmations",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            5,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Conditional dismissal",
+          "href": "#conditional-dismissal",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            5,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Flexible composition",
+          "href": "#flexible-composition",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Order cancellation with full context",
+          "href": "#order-cancellation-with-full-context",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Feature announcement without footer",
+          "href": "#feature-announcement-without-footer",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Processing state without actions",
+          "href": "#processing-state-without-actions",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            6,
+            3
+          ],
+          "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": "Composition constraints",
+          "href": "#composition-constraints",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Confirmation dialogs",
+          "href": "#confirmation-dialogs",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form dialogs",
+          "href": "#form-dialogs",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Alert dialogs",
+          "href": "#alert-dialogs",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "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": "Opening and Closing Interaction Tests",
+          "href": "#opening-and-closing-interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled Mode Tests",
+          "href": "#controlled-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form Submission Tests",
+          "href": "#form-submission-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard Navigation Tests",
+          "href": "#keyboard-navigation-tests",
+          "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 dialogs strategically to enhance user workflow without disrupting the\nexperience.\n\n### Best practices\n\n- **Use dialogs sparingly**: Only when you need to interrupt the user's flow for\n  critical actions\n- **Keep content focused**: Dialogs should have a single, clear purpose\n- **Provide clear actions**: Always include obvious ways to proceed or dismiss\n- **Make dismissal easy**: Support Escape key, close buttons, and click-outside\n  behavior\n- **Maintain focus flow**: Focus should move logically through interactive\n  elements\n- **Size appropriately**: Choose sizes that fit your content without\n  overwhelming the viewport\n- **Consider mobile**: Ensure dialogs work well on small screens\n\n> [!TIP]\\\n> When to use\n\n- **Confirming destructive actions**: Delete confirmations and critical warnings\n- **Collecting focused input**: Forms, settings, and data entry that requires\n  attention\n- **Displaying critical alerts**: Important information that requires immediate\n  user attention\n- **Showing detailed information**: Content that doesn't require navigation to a\n  new page\n- **Authentication flows**: Login, signup, and security-related interactions\n\n> [!CAUTION]\\\n> When not to use\n\n- **Complex multi-step workflows**: Use pages instead for lengthy processes\n- **Non-critical information**: Use inline content for supplementary information\n- **Navigation**: Use proper routing instead of dialogs for moving between\n  sections\n- **Content that needs to be referenced**: Avoid for information users need\n  while working elsewhere\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"
+        }
+      ]
+    }
+  }
+}