@commercetools/nimbus-mcp 2.11.0 → 3.0.0

package/data/docs/routes/patterns-dialogs-info-dialog.json

@@ -0,0 +1,315 @@
+{
+  "meta": {
+    "id": "Patterns-InfoDialog",
+    "title": "Info dialog",
+    "exportName": "InfoDialog",
+    "description": "A pre-composed read-only informational dialog with a flat, minimal API.",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/patterns/dialogs/info-dialog/info-dialog.mdx",
+    "menu": [
+      "Patterns",
+      "Dialogs",
+      "Info dialog"
+    ],
+    "route": "patterns/dialogs/info-dialog",
+    "tags": [
+      "component",
+      "pattern",
+      "dialog",
+      "InfoDialog"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "When to use",
+        "href": "#when-to-use",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "When not to use",
+        "href": "#when-not-to-use",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          3
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nInfoDialog is a pattern component that wraps the Dialog primitive in a flat, minimal API for the most common read-only informational dialog shape: a title, some content, and a close affordance. It is the recommended replacement for the Merchant Center Application Kit's `InfoDialog`.\n\nThe pattern exposes a small, flat set of props — `title`, `children`, and optional `isOpen` / `defaultOpen` / `onOpenChange` / `aria-label` — and delegates everything else (sizing, stacking, portaling, focus management) to the underlying `Dialog` primitive.\n\n### When to use\n\n- Displaying read-only information the user needs to acknowledge and dismiss (help text, details panels, metadata)\n- Any scenario where the dialog has no footer actions — the user's only task is to read and close\n\n### When not to use\n\n- Dialogs that need confirmation, cancellation, or destructive action buttons — use `Dialog` directly or a confirmation pattern\n- Dialogs hosting editable forms — use `Dialog` directly with form wiring\n- Any scenario that needs a non-default size or non-default dismiss behaviour — drop down to `Dialog` directly (see the escape hatch in the developer documentation)\n\n### Resources\n\nFor detailed guidance on the underlying primitive, consult the component guidelines:\n\n- [Dialog Guidelines](/components/feedback/dialog) — Variants, dismissability, sizing, placement, accessibility\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-dialogs-infodialog--docs)\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nInfoDialog is a pattern component that wraps the Dialog primitive in a flat, minimal API for the most common read-only informational dialog shape: a title, some content, and a close affordance. It is the recommended replacement for the Merchant Center Application Kit's `InfoDialog`.\n\nThe pattern exposes a small, flat set of props — `title`, `children`, and optional `isOpen` / `defaultOpen` / `onOpenChange` / `aria-label` — and delegates everything else (sizing, stacking, portaling, focus management) to the underlying `Dialog` primitive.\n\n### When to use\n\n- Displaying read-only information the user needs to acknowledge and dismiss (help text, details panels, metadata)\n- Any scenario where the dialog has no footer actions — the user's only task is to read and close\n\n### When not to use\n\n- Dialogs that need confirmation, cancellation, or destructive action buttons — use `Dialog` directly or a confirmation pattern\n- Dialogs hosting editable forms — use `Dialog` directly with form wiring\n- Any scenario that needs a non-default size or non-default dismiss behaviour — drop down to `Dialog` directly (see the escape hatch in the developer documentation)\n\n### Resources\n\nFor detailed guidance on the underlying primitive, consult the component guidelines:\n\n- [Dialog Guidelines](/components/feedback/dialog) — Variants, dismissability, sizing, placement, accessibility\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-dialogs-infodialog--docs)\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use",
+          "href": "#when-to-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When not to use",
+          "href": "#when-not-to-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Comparison: InfoDialog vs manual Dialog composition\n\n**With InfoDialog:**\n```tsx\n<InfoDialog\n  title=\"Shipping restrictions\"\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n>\n  <Text>Some goods cannot be shipped to the selected region.</Text>\n</InfoDialog>\n```\n\n**Manual composition:**\n```tsx\n<Dialog.Root\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n  isDismissable\n>\n  <Dialog.Content>\n    <Dialog.Header>\n      <Dialog.Title>Shipping restrictions</Dialog.Title>\n      <Dialog.CloseTrigger />\n    </Dialog.Header>\n    <Dialog.Body>\n      <Text>Some goods cannot be shipped to the selected region.</Text>\n    </Dialog.Body>\n  </Dialog.Content>\n</Dialog.Root>\n```\n\n### When to use which\n\n**Use InfoDialog when:**\n- You need a read-only informational dialog with no footer actions\n- The default dialog size and dismiss behaviour are appropriate\n- You want a flat four-prop API instead of composing six nested elements\n\n**Use Dialog directly when:**\n- You need a non-default size\n- You need to override dismissability (disable overlay click, disable Escape)\n- Your dialog has footer actions (Cancel/Confirm, destructive action, etc.)\n\n## Getting started\n\n### Import\n\n```tsx\nimport { InfoDialog, type InfoDialogProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation with a string title and controlled open state:\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n\n  return (\n    <>\n      <Button onPress={() => setIsOpen(true)}>Show shipping info</Button>\n      <InfoDialog\n        title=\"Shipping restrictions\"\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n      >\n        <Text>\n          Some goods cannot be shipped to the selected region. Review the\n          restricted items and update the shipping address if needed.\n        </Text>\n      </InfoDialog>\n    </>\n  );\n}\n```\n\n## Usage examples\n\n### ReactNode title\n\nThe `title` prop accepts any ReactNode, so you can compose a heading with inline elements like a badge or icon:\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n\n  return (\n    <>\n      <Button onPress={() => setIsOpen(true)}>Show plan details</Button>\n      <InfoDialog\n        title={\n          <Flex alignItems=\"center\" gap=\"200\">\n            <Text>Plan details</Text>\n            <Badge>Pro</Badge>\n          </Flex>\n        }\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n      >\n        <Text>\n          Your current plan includes unlimited projects and priority support.\n        </Text>\n      </InfoDialog>\n    </>\n  );\n}\n```\n\nWhen the `title` is not a plain string, pass an explicit `aria-label` if the composed markup does not form a meaningful accessible name on its own:\n\n```tsx\n<InfoDialog\n  title={\n    <Flex alignItems=\"center\" gap=\"200\">\n      <Text>Plan details</Text>\n      <Badge>Pro</Badge>\n    </Flex>\n  }\n  aria-label=\"Plan details\"\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n>\n  {/* ... */}\n</InfoDialog>\n```\n\n### Long, scrollable content\n\nContent that exceeds the available dialog height scrolls within the body; the header with the title and close button stays pinned at the top.\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n\n  return (\n    <>\n      <Button onPress={() => setIsOpen(true)}>Show terms</Button>\n      <InfoDialog\n        title=\"Terms of service\"\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n      >\n        <Stack gap=\"400\">\n          {Array.from({ length: 20 }, (_, i) => (\n            <Text key={i}>\n              Paragraph {i + 1}: Lorem ipsum dolor sit amet, consectetur\n              adipiscing elit. Sed do eiusmod tempor incididunt ut labore et\n              dolore magna aliqua.\n            </Text>\n          ))}\n        </Stack>\n      </InfoDialog>\n    </>\n  );\n}\n```\n\n## Close affordances\n\nBecause InfoDialog has no footer actions, the underlying Dialog is always rendered with `isDismissable` enabled so the user has multiple ways to close it:\n\n- The X button in the header\n- The Escape key\n- A click on the overlay outside the dialog content\n\nAll three routes invoke `onOpenChange(false)`.\n\n## Accessibility\n\nInfoDialog inherits its accessibility guarantees from the Nimbus `Dialog` primitive:\n\n- `role=\"dialog\"` is exposed to assistive technology while open\n- Focus moves into the dialog on open and is trapped within it\n- Focus is restored to the triggering element on close\n- When `title` is a string, the dialog's accessible name is derived from it automatically — no extra `aria-label` is required\n\nIf the `title` is a composed ReactNode, pass an explicit `aria-label` to InfoDialog so the dialog has a meaningful accessible name.\n\n## Escape hatch\n\nIf you need a non-default size or a custom dismiss behaviour, drop down to composing `Dialog` directly. The equivalent manual composition is:\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n\n  return (\n    <>\n      <Button onPress={() => setIsOpen(true)}>Open large dialog</Button>\n      <Dialog.Root\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        isDismissable\n        aria-label=\"Shipping restrictions\"\n      >\n        <Dialog.Content size=\"lg\">\n          <Dialog.Header>\n            <Dialog.Title>Shipping restrictions</Dialog.Title>\n            <Dialog.CloseTrigger />\n          </Dialog.Header>\n          <Dialog.Body>\n            <Text>\n              Some goods cannot be shipped to the selected region.\n            </Text>\n          </Dialog.Body>\n        </Dialog.Content>\n      </Dialog.Root>\n    </>\n  );\n}\n```\n\n## API reference\n\n<PropsTable id=\"InfoDialog\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using InfoDialog within your application. The component's internal behaviour is already covered by Nimbus — these tests help you verify your integration.\n\n### Basic Rendering\n\nVerify the InfoDialog opens and renders its title and content.\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Badge,\n  Flex,\n  InfoDialog,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"InfoDialog - Basic rendering\", () => {\n  it(\"renders title and children when isOpen is true\", () => {\n    render(\n      <NimbusProvider>\n        <InfoDialog title=\"Heads up\" isOpen>\n          <p>Something you should know.</p>\n        </InfoDialog>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"heading\", { name: \"Heads up\" })\n    ).toBeInTheDocument();\n    expect(screen.getByText(\"Something you should know.\")).toBeInTheDocument();\n  });\n\n  it(\"uses the string title as the dialog's accessible name\", () => {\n    render(\n      <NimbusProvider>\n        <InfoDialog title=\"Account details\" isOpen>\n          <p>Body</p>\n        </InfoDialog>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"dialog\")).toHaveAccessibleName(\"Account details\");\n  });\n\n  it(\"does not render the dialog when isOpen is false\", () => {\n    render(\n      <NimbusProvider>\n        <InfoDialog title=\"Hidden\" isOpen={false}>\n          <p>Not visible</p>\n        </InfoDialog>\n      </NimbusProvider>\n    );\n\n    expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n  });\n});\n```\n\n### Controlled Open State\n\nDrive the InfoDialog from consumer state via isOpen and onOpenChange.\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Badge,\n  Flex,\n  InfoDialog,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"InfoDialog - Controlled state\", () => {\n  it(\"invokes onOpenChange(false) when the close button is clicked\", async () => {\n    const user = userEvent.setup();\n\n    const ControlledInfoDialog = () => {\n      const [isOpen, setIsOpen] = useState(true);\n      return (\n        <InfoDialog title=\"Close me\" isOpen={isOpen} onOpenChange={setIsOpen}>\n          <p>Dismissable content</p>\n        </InfoDialog>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <ControlledInfoDialog />\n      </NimbusProvider>\n    );\n\n    await waitFor(() => expect(screen.getByRole(\"dialog\")).toBeInTheDocument());\n\n    await user.click(screen.getByRole(\"button\", { name: /close/i }));\n\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Uncontrolled Open State\n\nOpen the InfoDialog by default without managing state via defaultOpen.\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Badge,\n  Flex,\n  InfoDialog,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"InfoDialog - Uncontrolled state\", () => {\n  it(\"opens by default in uncontrolled mode via defaultOpen\", () => {\n    render(\n      <NimbusProvider>\n        <InfoDialog title=\"Welcome\" defaultOpen>\n          <p>Shown immediately on mount.</p>\n        </InfoDialog>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n    expect(screen.getByText(\"Shown immediately on mount.\")).toBeInTheDocument();\n  });\n});\n```\n\n### Accessible Name Override\n\nProvide an explicit aria-label when a composed ReactNode title does not form a meaningful accessible name.\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport { userEvent } from \"@testing-library/user-event\";\nimport { useState } from \"react\";\nimport {\n  Badge,\n  Flex,\n  InfoDialog,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"InfoDialog - Accessible name override\", () => {\n  it(\"uses aria-label as the accessible name when provided\", () => {\n    render(\n      <NimbusProvider>\n        <InfoDialog\n          title={\n            <Flex alignItems=\"center\" gap=\"200\">\n              <Text>Plan details</Text>\n              <Badge>Pro</Badge>\n            </Flex>\n          }\n          aria-label=\"Plan details\"\n          isOpen\n        >\n          <p>Your current plan includes unlimited projects.</p>\n        </InfoDialog>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"dialog\")).toHaveAccessibleName(\"Plan details\");\n  });\n});\n```\n\n",
+      "toc": [
+        {
+          "value": "Comparison: InfoDialog vs manual Dialog composition",
+          "href": "#comparison-infodialog-vs-manual-dialog-composition",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use which",
+          "href": "#when-to-use-which",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "ReactNode title",
+          "href": "#reactnode-title",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Long, scrollable content",
+          "href": "#long-scrollable-content",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Close affordances",
+          "href": "#close-affordances",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Escape hatch",
+          "href": "#escape-hatch",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering",
+          "href": "#basic-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled Open State",
+          "href": "#controlled-open-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled Open State",
+          "href": "#uncontrolled-open-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessible Name Override",
+          "href": "#accessible-name-override",
+          "depth": 3,
+          "numbering": [
+            1,
+            8,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}

package/data/docs/routes/patterns-dialogs.json

@@ -0,0 +1,78 @@
+{
+  "meta": {
+    "id": "Patterns-Dialogs",
+    "title": "Dialogs",
+    "description": "Pre-composed dialog patterns built on top of the Dialog primitive for common read-only and confirmation scenarios",
+    "order": 2,
+    "repoPath": "packages/nimbus/src/docs/dialogs.mdx",
+    "menu": [
+      "Patterns",
+      "Dialogs"
+    ],
+    "route": "patterns/dialogs",
+    "tags": [
+      "patterns",
+      "dialogs",
+      "overlays"
+    ],
+    "toc": [
+      {
+        "value": "When to use dialog patterns",
+        "href": "#when-to-use-dialog-patterns",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Available dialog patterns",
+        "href": "#available-dialog-patterns",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "icon": "OpenInNew",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Dialogs\n\nDialog pattern components wrap the `Dialog` primitive in small, opinionated APIs for the most common dialog shapes. Use them to avoid hand-composing `Dialog.Root`, `Dialog.Content`, `Dialog.Header`, `Dialog.Title`, `Dialog.Body`, and `Dialog.CloseTrigger` for everyday cases.\n\n## When to use dialog patterns\n\nDialog patterns are ideal for:\n- Read-only informational dialogs (help text, details, metadata)\n- Simple, scoped dialog shapes that appear many times across an app\n- Reducing boilerplate and ensuring consistent close affordances\n\nFor dialogs with bespoke footer actions, non-default sizing, or custom dismiss behaviour, compose the `Dialog` primitive directly.\n\n## Available dialog patterns\n\n<CategoryOverview variant=\"list\" />\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Dialogs\n\nDialog pattern components wrap the `Dialog` primitive in small, opinionated APIs for the most common dialog shapes. Use them to avoid hand-composing `Dialog.Root`, `Dialog.Content`, `Dialog.Header`, `Dialog.Title`, `Dialog.Body`, and `Dialog.CloseTrigger` for everyday cases.\n\n## When to use dialog patterns\n\nDialog patterns are ideal for:\n- Read-only informational dialogs (help text, details, metadata)\n- Simple, scoped dialog shapes that appear many times across an app\n- Reducing boilerplate and ensuring consistent close affordances\n\nFor dialogs with bespoke footer actions, non-default sizing, or custom dismiss behaviour, compose the `Dialog` primitive directly.\n\n## Available dialog patterns\n\n<CategoryOverview variant=\"list\" />\n",
+      "toc": [
+        {
+          "value": "When to use dialog patterns",
+          "href": "#when-to-use-dialog-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Available dialog patterns",
+          "href": "#available-dialog-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}