@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/components-layout-modalpage.json

@@ -0,0 +1,716 @@
+{
+  "meta": {
+    "id": "Components-ModalPage",
+    "title": "ModalPage",
+    "exportName": "ModalPage",
+    "description": "A fullscreen modal overlay for form, info, and tabular page patterns. Provides a structured compound component API for complex editing and detail workflows in Merchant Center.",
+    "lifecycleState": "Experimental",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/modal-page/modal-page.mdx",
+    "menu": [
+      "Components",
+      "Layout",
+      "ModalPage"
+    ],
+    "route": "components/layout/modalpage",
+    "tags": [
+      "component",
+      "overlay",
+      "modal",
+      "page",
+      "dialog",
+      "fullscreen"
+    ],
+    "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": "Info page",
+        "href": "#info-page",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Form page",
+        "href": "#form-page",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Tabular page",
+        "href": "#tabular-page",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Multi-column content",
+        "href": "#multi-column-content",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Stacked pages",
+        "href": "#stacked-pages",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Guidelines",
+        "href": "#guidelines",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Best practices",
+        "href": "#best-practices",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Specs",
+        "href": "#specs",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Accessibility",
+        "href": "#accessibility",
+        "depth": 2,
+        "numbering": [
+          1,
+          5
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Keyboard Navigation",
+        "href": "#keyboard-navigation",
+        "depth": 3,
+        "numbering": [
+          1,
+          5,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Screen Reader Support",
+        "href": "#screen-reader-support",
+        "depth": 3,
+        "numbering": [
+          1,
+          5,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "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\nModalPage is a fullscreen overlay that covers nearly the entire viewport,\nproviding a dedicated context for complex workflows. It is the Nimbus\nequivalent of the Merchant Center Application Kit's modal page patterns\n(form, info, and tabular variants).\n\nUnlike a regular Drawer, ModalPage has a fixed, structured layout with a\ntop navigation bar, header, scrollable content area, and optional footer.\nIt is always controlled — consumers manage the open state with `isOpen` and\n`onClose`.\n\n### Key features\n\n- **Controlled-only API**: Explicit `isOpen` + `onClose` — no hidden state\n- **Breadcrumb navigation**: `ModalPage.TopBar` shows previous/current path with an accessible back button\n- **Structured layout**: TopBar / Header / Content (scrollable) / Footer\n- **Tab navigation**: `ModalPage.TabNav` for tabular page patterns\n- **Multi-column content**: Use `PageContent.Root` inside `ModalPage.Content` for column layouts\n- **Accessibility first**: WCAG 2.1 AA compliant with focus management, keyboard navigation, and screen reader support\n\n### Resources\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\n## Variables\n\nGet familiar with the features.\n\n### Info page\n\nA read-only detail view. Footer is optional.\n\n```jsx live\nconst App = () => {\n  const [isOpen, setIsOpen] = React.useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Info Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Product Details\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Product Details</ModalPage.Title>\n          <ModalPage.Subtitle>View the product information</ModalPage.Subtitle>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Text>Product information goes here.</Text>\n        </ModalPage.Content>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Form page\n\nUse when the user needs to create or edit an entity. Always include a Footer\nwith Save/Cancel actions.\n\n```jsx live\nconst App = () => {\n  const [isOpen, setIsOpen] = React.useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Form Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Add Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Add Product</ModalPage.Title>\n          <ModalPage.Subtitle>Fill in the product details</ModalPage.Subtitle>\n          <ModalPage.Actions>\n            <Button size=\"sm\" variant=\"outline\">Preview</Button>\n          </ModalPage.Actions>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Text>Form fields go here.</Text>\n        </ModalPage.Content>\n        <ModalPage.Footer>\n          <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n          <Button colorPalette=\"primary\" variant=\"solid\">Save</Button>\n        </ModalPage.Footer>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Tabular page\n\nUse when content is organized into multiple sections via tab navigation.\nPlace `ModalPage.TabNav` inside the header and display the active section\nin the content area.\n\n```jsx live\nconst App = () => {\n  const [isOpen, setIsOpen] = React.useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Tabular Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Orders\"\n          currentPathLabel=\"Order #12345\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Order #12345</ModalPage.Title>\n          <ModalPage.Subtitle>Placed on 2024-01-15</ModalPage.Subtitle>\n          <ModalPage.TabNav>\n            <TabNav.Root aria-label=\"Order sections\">\n              <TabNav.Item href=\"#general\" isCurrent>General</TabNav.Item>\n              <TabNav.Item href=\"#items\">Items</TabNav.Item>\n              <TabNav.Item href=\"#shipping\">Shipping</TabNav.Item>\n            </TabNav.Root>\n          </ModalPage.TabNav>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Text>General information</Text>\n        </ModalPage.Content>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Multi-column content\n\nUse `PageContent.Root` with `columns` inside `ModalPage.Content` for\nside-by-side layouts:\n\n```jsx live\nconst App = () => {\n  const [isOpen, setIsOpen] = React.useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Two-Column Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Edit Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Edit Product</ModalPage.Title>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <PageContent.Root variant=\"wide\" columns=\"2/1\">\n            <PageContent.Column>\n              <Text>Main form area (2/3 width)</Text>\n            </PageContent.Column>\n            <PageContent.Column sticky>\n              <Text>Sidebar summary (1/3 width, sticky)</Text>\n            </PageContent.Column>\n          </PageContent.Root>\n        </ModalPage.Content>\n        <ModalPage.Footer>\n          <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n          <Button colorPalette=\"primary\" variant=\"solid\">Save</Button>\n        </ModalPage.Footer>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Stacked pages\n\nUse when a workflow requires drilling into a sub-task — for example, opening\n\"Add Variant\" while the \"Edit Product\" page is open. Place the second\n`ModalPage.Root` inside the first `ModalPage.Content`. Each page manages its\nown independent open state.\n\n```jsx live\nconst App = () => {\n  const [isFirstOpen, setIsFirstOpen] = React.useState(false);\n  const [isSecondOpen, setIsSecondOpen] = React.useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsFirstOpen(true)}>Open Edit Product</Button>\n      <ModalPage.Root\n        isOpen={isFirstOpen}\n        onClose={() => setIsFirstOpen(false)}\n      >\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Edit Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Edit Product</ModalPage.Title>\n          <ModalPage.Subtitle>Update the product details</ModalPage.Subtitle>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Stack>\n            <Text>Product form content goes here.</Text>\n            <Button onPress={() => setIsSecondOpen(true)}>\n              Open Add Variant\n            </Button>\n          </Stack>\n\n          <ModalPage.Root\n            isOpen={isSecondOpen}\n            onClose={() => setIsSecondOpen(false)}\n          >\n            <ModalPage.TopBar\n              previousPathLabel=\"Edit Product\"\n              currentPathLabel=\"Add Variant\"\n            />\n            <ModalPage.Header>\n              <ModalPage.Title>Add Variant</ModalPage.Title>\n              <ModalPage.Subtitle>Define a new product variant</ModalPage.Subtitle>\n            </ModalPage.Header>\n            <ModalPage.Content>\n              <Text>Variant form content goes here.</Text>\n            </ModalPage.Content>\n            <ModalPage.Footer>\n              <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n              <Button colorPalette=\"primary\" variant=\"solid\">Save Variant</Button>\n            </ModalPage.Footer>\n          </ModalPage.Root>\n        </ModalPage.Content>\n        <ModalPage.Footer>\n          <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n          <Button colorPalette=\"primary\" variant=\"solid\">Save Product</Button>\n        </ModalPage.Footer>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n## Guidelines\n\nUse ModalPage strategically to enhance user workflow without disrupting the\nexperience.\n\n### Best practices\n\n- **Always provide a title**: Use `ModalPage.Title` so screen readers can identify the dialog\n- **Use TopBar navigation**: Always supply meaningful `previousPathLabel` and `currentPathLabel`\n- **Footer actions for forms**: Include Save/Cancel in `ModalPage.Footer` for form pages\n- **Prefer Escape key close**: Don't disable keyboard dismissal — it matches OS conventions and WCAG 2.1\n- **Backdrop click is disabled**: Users must close via back button, Cancel, or Escape to prevent accidental data loss\n\n> [!TIP]\\\n> When to use\n\n- **Complex editing workflows**: Creating or editing entities with many fields\n- **Multi-section detail views**: When content is too rich for a standard Drawer\n- **Tabular data workflows**: When content requires tabs (general, items, shipping)\n- **Full-page focused context**: When the user needs to focus entirely on the task\n\n> [!CAUTION]\\\n> When not to use\n\n- **Simple confirmation dialogs**: Use `Dialog` instead\n- **Single-form quick edits**: Use `Drawer` instead — ModalPage is for complex, multi-field scenarios\n- **Navigation overlays**: Use proper routing for section changes\n\n## Specs\n\n<PropsTable id=\"ModalPage\" />\n\n## Accessibility\n\n### Keyboard Navigation\n\n| Key | Action |\n|-----|--------|\n| `Escape` | Closes the modal page |\n| `Tab` / `Shift+Tab` | Moves focus between interactive elements |\n\nFocus is trapped inside the modal while open and returns to the triggering\nelement when the modal closes.\n\n### Screen Reader Support\n\n- The dialog has `role=\"dialog\"` and `aria-modal=\"true\"`\n- `ModalPage.Title` automatically provides the accessible name for the dialog\n- The back button has a localized label referencing the previous path (e.g. \"Go back to Products\")\n- The breadcrumb separator is hidden from assistive technology\n- The current path label is marked as the current page\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nModalPage is a fullscreen overlay that covers nearly the entire viewport,\nproviding a dedicated context for complex workflows. It is the Nimbus\nequivalent of the Merchant Center Application Kit's modal page patterns\n(form, info, and tabular variants).\n\nUnlike a regular Drawer, ModalPage has a fixed, structured layout with a\ntop navigation bar, header, scrollable content area, and optional footer.\nIt is always controlled — consumers manage the open state with `isOpen` and\n`onClose`.\n\n### Key features\n\n- **Controlled-only API**: Explicit `isOpen` + `onClose` — no hidden state\n- **Breadcrumb navigation**: `ModalPage.TopBar` shows previous/current path with an accessible back button\n- **Structured layout**: TopBar / Header / Content (scrollable) / Footer\n- **Tab navigation**: `ModalPage.TabNav` for tabular page patterns\n- **Multi-column content**: Use `PageContent.Root` inside `ModalPage.Content` for column layouts\n- **Accessibility first**: WCAG 2.1 AA compliant with focus management, keyboard navigation, and screen reader support\n\n### Resources\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\n## Variables\n\nGet familiar with the features.\n\n### Info page\n\nA read-only detail view. Footer is optional.\n\n```jsx live\nconst App = () => {\n  const [isOpen, setIsOpen] = React.useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Info Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Product Details\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Product Details</ModalPage.Title>\n          <ModalPage.Subtitle>View the product information</ModalPage.Subtitle>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Text>Product information goes here.</Text>\n        </ModalPage.Content>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Form page\n\nUse when the user needs to create or edit an entity. Always include a Footer\nwith Save/Cancel actions.\n\n```jsx live\nconst App = () => {\n  const [isOpen, setIsOpen] = React.useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Form Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Add Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Add Product</ModalPage.Title>\n          <ModalPage.Subtitle>Fill in the product details</ModalPage.Subtitle>\n          <ModalPage.Actions>\n            <Button size=\"sm\" variant=\"outline\">Preview</Button>\n          </ModalPage.Actions>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Text>Form fields go here.</Text>\n        </ModalPage.Content>\n        <ModalPage.Footer>\n          <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n          <Button colorPalette=\"primary\" variant=\"solid\">Save</Button>\n        </ModalPage.Footer>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Tabular page\n\nUse when content is organized into multiple sections via tab navigation.\nPlace `ModalPage.TabNav` inside the header and display the active section\nin the content area.\n\n```jsx live\nconst App = () => {\n  const [isOpen, setIsOpen] = React.useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Tabular Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Orders\"\n          currentPathLabel=\"Order #12345\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Order #12345</ModalPage.Title>\n          <ModalPage.Subtitle>Placed on 2024-01-15</ModalPage.Subtitle>\n          <ModalPage.TabNav>\n            <TabNav.Root aria-label=\"Order sections\">\n              <TabNav.Item href=\"#general\" isCurrent>General</TabNav.Item>\n              <TabNav.Item href=\"#items\">Items</TabNav.Item>\n              <TabNav.Item href=\"#shipping\">Shipping</TabNav.Item>\n            </TabNav.Root>\n          </ModalPage.TabNav>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Text>General information</Text>\n        </ModalPage.Content>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Multi-column content\n\nUse `PageContent.Root` with `columns` inside `ModalPage.Content` for\nside-by-side layouts:\n\n```jsx live\nconst App = () => {\n  const [isOpen, setIsOpen] = React.useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Two-Column Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Edit Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Edit Product</ModalPage.Title>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <PageContent.Root variant=\"wide\" columns=\"2/1\">\n            <PageContent.Column>\n              <Text>Main form area (2/3 width)</Text>\n            </PageContent.Column>\n            <PageContent.Column sticky>\n              <Text>Sidebar summary (1/3 width, sticky)</Text>\n            </PageContent.Column>\n          </PageContent.Root>\n        </ModalPage.Content>\n        <ModalPage.Footer>\n          <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n          <Button colorPalette=\"primary\" variant=\"solid\">Save</Button>\n        </ModalPage.Footer>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Stacked pages\n\nUse when a workflow requires drilling into a sub-task — for example, opening\n\"Add Variant\" while the \"Edit Product\" page is open. Place the second\n`ModalPage.Root` inside the first `ModalPage.Content`. Each page manages its\nown independent open state.\n\n```jsx live\nconst App = () => {\n  const [isFirstOpen, setIsFirstOpen] = React.useState(false);\n  const [isSecondOpen, setIsSecondOpen] = React.useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsFirstOpen(true)}>Open Edit Product</Button>\n      <ModalPage.Root\n        isOpen={isFirstOpen}\n        onClose={() => setIsFirstOpen(false)}\n      >\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Edit Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Edit Product</ModalPage.Title>\n          <ModalPage.Subtitle>Update the product details</ModalPage.Subtitle>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Stack>\n            <Text>Product form content goes here.</Text>\n            <Button onPress={() => setIsSecondOpen(true)}>\n              Open Add Variant\n            </Button>\n          </Stack>\n\n          <ModalPage.Root\n            isOpen={isSecondOpen}\n            onClose={() => setIsSecondOpen(false)}\n          >\n            <ModalPage.TopBar\n              previousPathLabel=\"Edit Product\"\n              currentPathLabel=\"Add Variant\"\n            />\n            <ModalPage.Header>\n              <ModalPage.Title>Add Variant</ModalPage.Title>\n              <ModalPage.Subtitle>Define a new product variant</ModalPage.Subtitle>\n            </ModalPage.Header>\n            <ModalPage.Content>\n              <Text>Variant form content goes here.</Text>\n            </ModalPage.Content>\n            <ModalPage.Footer>\n              <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n              <Button colorPalette=\"primary\" variant=\"solid\">Save Variant</Button>\n            </ModalPage.Footer>\n          </ModalPage.Root>\n        </ModalPage.Content>\n        <ModalPage.Footer>\n          <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n          <Button colorPalette=\"primary\" variant=\"solid\">Save Product</Button>\n        </ModalPage.Footer>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n## Guidelines\n\nUse ModalPage strategically to enhance user workflow without disrupting the\nexperience.\n\n### Best practices\n\n- **Always provide a title**: Use `ModalPage.Title` so screen readers can identify the dialog\n- **Use TopBar navigation**: Always supply meaningful `previousPathLabel` and `currentPathLabel`\n- **Footer actions for forms**: Include Save/Cancel in `ModalPage.Footer` for form pages\n- **Prefer Escape key close**: Don't disable keyboard dismissal — it matches OS conventions and WCAG 2.1\n- **Backdrop click is disabled**: Users must close via back button, Cancel, or Escape to prevent accidental data loss\n\n> [!TIP]\\\n> When to use\n\n- **Complex editing workflows**: Creating or editing entities with many fields\n- **Multi-section detail views**: When content is too rich for a standard Drawer\n- **Tabular data workflows**: When content requires tabs (general, items, shipping)\n- **Full-page focused context**: When the user needs to focus entirely on the task\n\n> [!CAUTION]\\\n> When not to use\n\n- **Simple confirmation dialogs**: Use `Dialog` instead\n- **Single-form quick edits**: Use `Drawer` instead — ModalPage is for complex, multi-field scenarios\n- **Navigation overlays**: Use proper routing for section changes\n\n## Specs\n\n<PropsTable id=\"ModalPage\" />\n\n## Accessibility\n\n### Keyboard Navigation\n\n| Key | Action |\n|-----|--------|\n| `Escape` | Closes the modal page |\n| `Tab` / `Shift+Tab` | Moves focus between interactive elements |\n\nFocus is trapped inside the modal while open and returns to the triggering\nelement when the modal closes.\n\n### Screen Reader Support\n\n- The dialog has `role=\"dialog\"` and `aria-modal=\"true\"`\n- `ModalPage.Title` automatically provides the accessible name for the dialog\n- The back button has a localized label referencing the previous path (e.g. \"Go back to Products\")\n- The breadcrumb separator is hidden from assistive technology\n- The current path label is marked as the current page\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": "Info page",
+          "href": "#info-page",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form page",
+          "href": "#form-page",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tabular page",
+          "href": "#tabular-page",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-column content",
+          "href": "#multi-column-content",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Stacked pages",
+          "href": "#stacked-pages",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Specs",
+          "href": "#specs",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard Navigation",
+          "href": "#keyboard-navigation",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Screen Reader Support",
+          "href": "#screen-reader-support",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "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  const [isOpen, setIsOpen] = React.useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Modal Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Edit Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Edit Product</ModalPage.Title>\n          <ModalPage.Subtitle>Update the product details</ModalPage.Subtitle>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Text>\n            This modal page demonstrates accessibility features: dialog role,\n            focus trap, Escape key dismissal, and breadcrumb navigation.\n          </Text>\n        </ModalPage.Content>\n        <ModalPage.Footer>\n          <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n          <Button colorPalette=\"primary\" variant=\"solid\">Save</Button>\n        </ModalPage.Footer>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Accessibility standards\n\n- **Role identification**: ModalPage has `role=\"dialog\"` with proper labeling via `ModalPage.Title`.\n- **Focus management**: Focus moves to the back button on open and returns to the trigger on close.\n- **Focus containment**: Tab navigation stays within the modal while it is open.\n- **Accessible names**: `ModalPage.Title` automatically provides the dialog's accessible name via `aria-labelledby`.\n- **Accessible description**: `ModalPage.Subtitle`, when present, automatically provides the dialog's accessible description via `aria-describedby`.\n- **Modal indication**: `aria-modal=\"true\"` is set, blocking screen reader interaction with the background.\n- **State announcements**: Screen readers announce when the dialog opens and closes.\n- **Breadcrumb accessibility**: The `/` separator is `aria-hidden=\"true\"`; the current path has `aria-current=\"page\"`.\n- **Back button label**: The back button in `ModalPage.TopBar` uses a localized `aria-label` referencing the `previousPathLabel`.\n- **Breadcrumb previous path**: The `previousPathLabel` text is `aria-hidden=\"true\"` since the back button's label already conveys this information.\n- **Keyboard dismissal**: Escape key always closes the modal (WCAG 2.1 SC 2.1.2 — No Keyboard Trap).\n- **No keyboard trap**: Focus is contained but always escapable via Escape key.\n- **Focus order**: Logical focus progression through all interactive elements.\n- **Focus visible**: Clear focus indicators on all interactive elements.\n- **Contrast**: All text meets minimum contrast requirements.\n- **Non-text contrast**: Focus indicators and UI components meet contrast standards.\n- **Name, role, value**: Proper semantic markup and ARIA attributes throughout.\n\n### Resources\n\n- [W3C ARIA Authoring Practices Guide (APG) - Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)\n- [WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)\n- [WCAG 2.1 SC 2.1.2 - No Keyboard Trap](https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap.html)\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 { ModalPage } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nModalPage is a controlled compound component. The basic implementation shows\nhow to manage open state and compose the required sub-components:\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Modal Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Edit Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Edit Product</ModalPage.Title>\n          <ModalPage.Subtitle>Update the product details</ModalPage.Subtitle>\n          <ModalPage.Actions>\n            <Button size=\"sm\" variant=\"outline\">Preview</Button>\n          </ModalPage.Actions>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Text>Form content goes here.</Text>\n        </ModalPage.Content>\n        <ModalPage.Footer>\n          <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n          <Button colorPalette=\"primary\" variant=\"solid\">Save</Button>\n        </ModalPage.Footer>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n## Usage examples\n\n### Closing the modal page\n\nThere are three ways to close a ModalPage — all route through the same\n`onClose` callback:\n\n1. **Back button in TopBar** — acts as a close trigger, calling `onClose`\n2. **Any button with `slot=\"close\"`** — automatically triggers `onClose`\n3. **Escape key** — always enabled; matches browser/OS convention and WCAG 2.1\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Edit Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Edit Product</ModalPage.Title>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Text>\n            Close via: back button in TopBar, slot=\"close\" button, or Escape key.\n          </Text>\n        </ModalPage.Content>\n        <ModalPage.Footer>\n          <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n          <Button colorPalette=\"primary\" variant=\"solid\">Save</Button>\n        </ModalPage.Footer>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Multi-column content\n\nUse `PageContent.Root` with `columns` inside `ModalPage.Content` for\nside-by-side layouts:\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Two-Column Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Edit Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Edit Product</ModalPage.Title>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <PageContent.Root variant=\"wide\" columns=\"2/1\">\n            <PageContent.Column>\n              <Text>Main form (2/3 width)</Text>\n            </PageContent.Column>\n            <PageContent.Column sticky>\n              <Text>Summary sidebar (1/3 width, sticky)</Text>\n            </PageContent.Column>\n          </PageContent.Root>\n        </ModalPage.Content>\n        <ModalPage.Footer>\n          <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n          <Button colorPalette=\"primary\" variant=\"solid\">Save</Button>\n        </ModalPage.Footer>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Header actions\n\nUse `ModalPage.Actions` to place secondary actions (e.g. Preview, Export) in\nthe right column of the header grid:\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open with Header Actions</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Edit Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Edit Product</ModalPage.Title>\n          <ModalPage.Subtitle>Last saved 2 minutes ago</ModalPage.Subtitle>\n          <ModalPage.Actions>\n            <Button size=\"sm\" variant=\"ghost\">Preview</Button>\n            <Button size=\"sm\" variant=\"outline\">Export</Button>\n          </ModalPage.Actions>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Text>Content area</Text>\n        </ModalPage.Content>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Tabular page with TabNav\n\nUse `ModalPage.TabNav` inside the header for tabular page patterns with\nroute-based tab navigation:\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsOpen(true)}>Open Tabular Page</Button>\n      <ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n        <ModalPage.TopBar\n          previousPathLabel=\"Orders\"\n          currentPathLabel=\"Order #12345\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Order #12345</ModalPage.Title>\n          <ModalPage.Subtitle>Placed on 2024-01-15</ModalPage.Subtitle>\n          <ModalPage.TabNav>\n            <TabNav.Root aria-label=\"Order sections\">\n              <TabNav.Item href=\"#general\" isCurrent>General</TabNav.Item>\n              <TabNav.Item href=\"#items\">Items</TabNav.Item>\n              <TabNav.Item href=\"#shipping\">Shipping</TabNav.Item>\n            </TabNav.Root>\n          </ModalPage.TabNav>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Text>General information</Text>\n        </ModalPage.Content>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n### Stacked modal pages\n\nWhen a workflow requires drilling into a sub-task (e.g. adding a variant\nwhile editing a product), place a second `ModalPage.Root` inside the first\n`ModalPage.Content`. Each modal page manages its own independent state.\n\nThe breadcrumb in `ModalPage.TopBar` naturally reflects the depth:\nset `previousPathLabel` to the parent page's title so the back button\nreads contextually.\n\nBehaviour that works automatically:\n- Escape closes only the topmost page\n- Focus is trapped in the topmost page; previous page is inert\n- When the second page closes, focus returns to its trigger inside the first page\n- When the first page closes, focus returns to the original page trigger\n\n```jsx live-dev\nconst App = () => {\n  const [isFirstOpen, setIsFirstOpen] = useState(false);\n  const [isSecondOpen, setIsSecondOpen] = useState(false);\n  return (\n    <Stack>\n      <Button onPress={() => setIsFirstOpen(true)}>Open Edit Product</Button>\n      <ModalPage.Root\n        isOpen={isFirstOpen}\n        onClose={() => setIsFirstOpen(false)}\n      >\n        <ModalPage.TopBar\n          previousPathLabel=\"Products\"\n          currentPathLabel=\"Edit Product\"\n        />\n        <ModalPage.Header>\n          <ModalPage.Title>Edit Product</ModalPage.Title>\n          <ModalPage.Subtitle>Update the product details</ModalPage.Subtitle>\n        </ModalPage.Header>\n        <ModalPage.Content>\n          <Stack>\n            <Text>Product form content goes here.</Text>\n            <Button onPress={() => setIsSecondOpen(true)}>\n              Open Add Variant\n            </Button>\n          </Stack>\n\n          <ModalPage.Root\n            isOpen={isSecondOpen}\n            onClose={() => setIsSecondOpen(false)}\n          >\n            <ModalPage.TopBar\n              previousPathLabel=\"Edit Product\"\n              currentPathLabel=\"Add Variant\"\n            />\n            <ModalPage.Header>\n              <ModalPage.Title>Add Variant</ModalPage.Title>\n              <ModalPage.Subtitle>Define a new product variant</ModalPage.Subtitle>\n            </ModalPage.Header>\n            <ModalPage.Content>\n              <Text>Variant form content goes here.</Text>\n            </ModalPage.Content>\n            <ModalPage.Footer>\n              <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n              <Button colorPalette=\"primary\" variant=\"solid\">Save Variant</Button>\n            </ModalPage.Footer>\n          </ModalPage.Root>\n        </ModalPage.Content>\n        <ModalPage.Footer>\n          <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n          <Button colorPalette=\"primary\" variant=\"solid\">Save Product</Button>\n        </ModalPage.Footer>\n      </ModalPage.Root>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n### Accessible dialog label\n\nThe dialog must have an accessible name. Use `ModalPage.Title` (recommended):\n\n```tsx\n<ModalPage.Header>\n  <ModalPage.Title>Edit Product</ModalPage.Title>\n</ModalPage.Header>\n```\n\n`ModalPage.Title` automatically provides the accessible name for the dialog.\nScreen readers will announce the title text when the dialog opens.\n\n### Custom page width\n\nThe default width is near-fullscreen. Pass a `width` prop to\n`ModalPage.Root` to override:\n\n```tsx\n<ModalPage.Root isOpen={isOpen} onClose={handleClose} width=\"xl\">\n  ...\n</ModalPage.Root>\n```\n\n### Footer button spacing\n\n`ModalPage.Footer` automatically spaces its children — place buttons directly\nwithout a layout wrapper:\n\n```tsx\n<ModalPage.Footer>\n  <Button slot=\"close\" variant=\"outline\">Cancel</Button>\n  <Button colorPalette=\"primary\" variant=\"solid\">Save</Button>\n</ModalPage.Footer>\n```\n\n### Controlled state\n\nModalPage is controlled-only. You must always supply both `isOpen` and\n`onClose`:\n\n```tsx\nconst [isOpen, setIsOpen] = useState(false);\n\n<ModalPage.Root isOpen={isOpen} onClose={() => setIsOpen(false)}>\n  ...\n</ModalPage.Root>\n```\n\n## Accessibility\n\nModalPage handles most accessibility requirements internally:\n\n- The dialog has `role=\"dialog\"` and `aria-modal=\"true\"`\n- Focus is trapped inside the modal while open\n- Focus moves to the back button on open and returns to the trigger on close\n- Escape key dismissal is always active\n- Backdrop click is disabled — full-page forms should not close accidentally\n\n#### Keyboard navigation\n\n| Key | Action |\n|-----|--------|\n| `Escape` | Closes the modal page |\n| `Tab` / `Shift+Tab` | Navigate focusable elements within the modal |\n\n#### ARIA attributes\n\n- `role=\"dialog\"`: Applied to the dialog container\n- `aria-labelledby`: Automatically linked to `ModalPage.Title`\n- `aria-modal=\"true\"`: Marks the overlay as modal to screen readers\n- `aria-current=\"page\"`: Applied to the current path label in `ModalPage.TopBar`\n- `aria-hidden=\"true\"`: Applied to the breadcrumb separator\n\n## API reference\n\n<PropsTable id=\"ModalPage\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using ModalPage\nin your application. As the component's internal functionality is already tested\nby Nimbus, these patterns help you verify your integration and application-specific\nlogic.\n\n### Basic usage\n\n```tsx\nimport { useState } from \"react\";\nimport { render, screen, fireEvent } from \"@testing-library/react\";\nimport { describe, it, expect, vi } from \"vitest\";\nimport {\n  Button,\n  ModalPage,\n  NimbusProvider,\n  PageContent,\n  Stack,\n  TabNav,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ModalPage - Basic usage\", () => {\n  it(\"opens and closes via controlled state\", () => {\n    const onClose = vi.fn();\n\n    const Example = () => {\n      const [isOpen, setIsOpen] = useState(false);\n      return (\n        <NimbusProvider>\n          <Button onPress={() => setIsOpen(true)}>Open</Button>\n          <ModalPage.Root\n            isOpen={isOpen}\n            onClose={() => {\n              onClose();\n              setIsOpen(false);\n            }}\n          >\n            <ModalPage.TopBar\n              previousPathLabel=\"Products\"\n              currentPathLabel=\"Edit Product\"\n            />\n            <ModalPage.Header>\n              <ModalPage.Title>Edit Product</ModalPage.Title>\n              <ModalPage.Subtitle>\n                Update the product details\n              </ModalPage.Subtitle>\n            </ModalPage.Header>\n            <ModalPage.Content>\n              <Text>Form content</Text>\n            </ModalPage.Content>\n            <ModalPage.Footer>\n              <Button slot=\"close\" variant=\"outline\">\n                Cancel\n              </Button>\n              <Button colorPalette=\"primary\" variant=\"solid\">\n                Save\n              </Button>\n            </ModalPage.Footer>\n          </ModalPage.Root>\n        </NimbusProvider>\n      );\n    };\n\n    render(<Example />);\n\n    // Dialog is not in DOM before opening\n    expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n\n    // Open the modal\n    fireEvent.click(screen.getByRole(\"button\", { name: \"Open\" }));\n    expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n    expect(\n      screen.getByRole(\"heading\", { name: \"Edit Product\" })\n    ).toBeInTheDocument();\n\n    // Close via slot=\"close\" button\n    fireEvent.click(screen.getByRole(\"button\", { name: \"Cancel\" }));\n    expect(onClose).toHaveBeenCalledOnce();\n  });\n});\n```\n\n### Form page with header actions and footer\n\n```tsx\nimport { useState } from \"react\";\nimport { render, screen, fireEvent } from \"@testing-library/react\";\nimport { describe, it, expect, vi } from \"vitest\";\nimport {\n  Button,\n  ModalPage,\n  NimbusProvider,\n  PageContent,\n  Stack,\n  TabNav,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ModalPage - Form page\", () => {\n  it(\"renders header actions and footer buttons\", () => {\n    render(\n      <NimbusProvider>\n        <ModalPage.Root isOpen onClose={() => {}}>\n          <ModalPage.TopBar\n            previousPathLabel=\"Products\"\n            currentPathLabel=\"Add Product\"\n          />\n          <ModalPage.Header>\n            <ModalPage.Title>Add Product</ModalPage.Title>\n            <ModalPage.Subtitle>Fill in the product details</ModalPage.Subtitle>\n            <ModalPage.Actions>\n              <Button size=\"sm\" variant=\"outline\">\n                Preview\n              </Button>\n            </ModalPage.Actions>\n          </ModalPage.Header>\n          <ModalPage.Content>\n            <Text>Form fields go here</Text>\n          </ModalPage.Content>\n          <ModalPage.Footer>\n            <Button slot=\"close\" variant=\"outline\">\n              Cancel\n            </Button>\n            <Button colorPalette=\"primary\" variant=\"solid\">\n              Save\n            </Button>\n          </ModalPage.Footer>\n        </ModalPage.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\", { name: \"Preview\" })).toBeInTheDocument();\n    expect(screen.getByRole(\"button\", { name: \"Cancel\" })).toBeInTheDocument();\n    expect(screen.getByRole(\"button\", { name: \"Save\" })).toBeInTheDocument();\n  });\n});\n```\n\n### Multi-column layout\n\n```tsx\nimport { useState } from \"react\";\nimport { render, screen, fireEvent } from \"@testing-library/react\";\nimport { describe, it, expect, vi } from \"vitest\";\nimport {\n  Button,\n  ModalPage,\n  NimbusProvider,\n  PageContent,\n  Stack,\n  TabNav,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ModalPage - Multi-column layout\", () => {\n  it(\"renders a 2/1 column layout\", () => {\n    render(\n      <NimbusProvider>\n        <ModalPage.Root isOpen onClose={() => {}}>\n          <ModalPage.TopBar\n            previousPathLabel=\"Products\"\n            currentPathLabel=\"Edit Product\"\n          />\n          <ModalPage.Header>\n            <ModalPage.Title>Edit Product</ModalPage.Title>\n          </ModalPage.Header>\n          <ModalPage.Content>\n            <PageContent.Root variant=\"wide\" columns=\"2/1\">\n              <PageContent.Column>\n                <Text>Main form area</Text>\n              </PageContent.Column>\n              <PageContent.Column sticky>\n                <Text>Summary sidebar</Text>\n              </PageContent.Column>\n            </PageContent.Root>\n          </ModalPage.Content>\n        </ModalPage.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByText(\"Main form area\")).toBeInTheDocument();\n    expect(screen.getByText(\"Summary sidebar\")).toBeInTheDocument();\n  });\n});\n```\n\n### Tabular page with TabNav\n\n```tsx\nimport { useState } from \"react\";\nimport { render, screen, fireEvent } from \"@testing-library/react\";\nimport { describe, it, expect, vi } from \"vitest\";\nimport {\n  Button,\n  ModalPage,\n  NimbusProvider,\n  PageContent,\n  Stack,\n  TabNav,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ModalPage - Tabular page\", () => {\n  it(\"renders tab navigation inside the header\", () => {\n    render(\n      <NimbusProvider>\n        <ModalPage.Root isOpen onClose={() => {}}>\n          <ModalPage.TopBar\n            previousPathLabel=\"Orders\"\n            currentPathLabel=\"Order #12345\"\n          />\n          <ModalPage.Header>\n            <ModalPage.Title>Order #12345</ModalPage.Title>\n            <ModalPage.Subtitle>Placed on 2024-01-15</ModalPage.Subtitle>\n            <ModalPage.TabNav>\n              <TabNav.Root aria-label=\"Order sections\">\n                <TabNav.Item href=\"#general\" isCurrent>\n                  General\n                </TabNav.Item>\n                <TabNav.Item href=\"#items\">Items</TabNav.Item>\n                <TabNav.Item href=\"#shipping\">Shipping</TabNav.Item>\n              </TabNav.Root>\n            </ModalPage.TabNav>\n          </ModalPage.Header>\n          <ModalPage.Content>\n            <Text>General information</Text>\n          </ModalPage.Content>\n        </ModalPage.Root>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"heading\", { name: \"Order #12345\" })\n    ).toBeInTheDocument();\n    expect(screen.getByText(\"General\")).toBeInTheDocument();\n    expect(screen.getByText(\"Items\")).toBeInTheDocument();\n    expect(screen.getByText(\"Shipping\")).toBeInTheDocument();\n  });\n});\n```\n\n### Stacked modal pages\n\n```tsx\nimport { useState } from \"react\";\nimport { render, screen, fireEvent } from \"@testing-library/react\";\nimport { describe, it, expect, vi } from \"vitest\";\nimport {\n  Button,\n  ModalPage,\n  NimbusProvider,\n  PageContent,\n  Stack,\n  TabNav,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ModalPage - Stacked pages\", () => {\n  it(\"renders nested modal pages independently\", () => {\n    const Example = () => {\n      const [isFirstOpen, setIsFirstOpen] = useState(true);\n      const [isSecondOpen, setIsSecondOpen] = useState(false);\n      return (\n        <NimbusProvider>\n          <ModalPage.Root\n            isOpen={isFirstOpen}\n            onClose={() => setIsFirstOpen(false)}\n          >\n            <ModalPage.TopBar\n              previousPathLabel=\"Products\"\n              currentPathLabel=\"Edit Product\"\n            />\n            <ModalPage.Header>\n              <ModalPage.Title>Edit Product</ModalPage.Title>\n            </ModalPage.Header>\n            <ModalPage.Content>\n              <Stack>\n                <Text>Product form content</Text>\n                <Button onPress={() => setIsSecondOpen(true)}>\n                  Add Variant\n                </Button>\n              </Stack>\n              <ModalPage.Root\n                isOpen={isSecondOpen}\n                onClose={() => setIsSecondOpen(false)}\n              >\n                <ModalPage.TopBar\n                  previousPathLabel=\"Edit Product\"\n                  currentPathLabel=\"Add Variant\"\n                />\n                <ModalPage.Header>\n                  <ModalPage.Title>Add Variant</ModalPage.Title>\n                </ModalPage.Header>\n                <ModalPage.Content>\n                  <Text>Variant form content</Text>\n                </ModalPage.Content>\n              </ModalPage.Root>\n            </ModalPage.Content>\n          </ModalPage.Root>\n        </NimbusProvider>\n      );\n    };\n\n    render(<Example />);\n\n    expect(screen.getByText(\"Product form content\")).toBeInTheDocument();\n\n    // Open stacked page\n    fireEvent.click(screen.getByRole(\"button\", { name: \"Add Variant\" }));\n    expect(screen.getByText(\"Variant form content\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-layout-modalpage--docs)\n- [React Aria Dialog](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": "Closing the modal page",
+          "href": "#closing-the-modal-page",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-column content",
+          "href": "#multi-column-content",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Header actions",
+          "href": "#header-actions",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tabular page with TabNav",
+          "href": "#tabular-page-with-tabnav",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Stacked modal pages",
+          "href": "#stacked-modal-pages",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessible dialog label",
+          "href": "#accessible-dialog-label",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom page width",
+          "href": "#custom-page-width",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Footer button spacing",
+          "href": "#footer-button-spacing",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled state",
+          "href": "#controlled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "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": "ARIA attributes",
+          "href": "#aria-attributes",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Form page with header actions and footer",
+          "href": "#form-page-with-header-actions-and-footer",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multi-column layout",
+          "href": "#multi-column-layout",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Tabular page with TabNav",
+          "href": "#tabular-page-with-tabnav-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Stacked modal pages",
+          "href": "#stacked-modal-pages-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nUse ModalPage strategically to enhance user workflow without disrupting the\nexperience.\n\n### Best practices\n\n- **Always provide a title**: Use `ModalPage.Title` so screen readers can identify the dialog\n- **Use meaningful navigation labels**: `previousPathLabel` and `currentPathLabel` orient the user within the application\n- **Include footer actions for forms**: Form pages should always have Save/Cancel in `ModalPage.Footer`\n- **Avoid disabling Escape key**: Keyboard dismissal is always active — it matches OS conventions and WCAG 2.1\n- **Keep content focused**: ModalPage should have a single, clear purpose — a form, a detail view, or a tabular view\n- **Use the right variant**: Choose the content variant that matches your data (`wide`, `narrow`, or `full`)\n\n> [!TIP]\\\n> When to use\n\n- **Complex editing workflows**: Creating or editing entities with many fields (product forms, order details)\n- **Multi-section detail views**: When content is too rich for a standard Drawer\n- **Tabular data workflows**: When the content is organized into tabs (General, Items, Shipping)\n- **Full-page focused context**: When the user must focus entirely on the task before returning to the list\n\n> [!CAUTION]\\\n> When not to use\n\n- **Simple confirmation dialogs**: Use `Dialog` instead — ModalPage is for content-rich workflows\n- **Single-form quick edits**: Use `Drawer` instead — reserve ModalPage for complex, multi-field scenarios\n- **Navigation overlays**: Use proper routing for moving between application sections\n- **Informational banners or toasts**: Use `Alert` or `Toast` for non-blocking messages\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"
+        }
+      ]
+    }
+  }
+}