@commercetools/nimbus-mcp 2.11.0 → 3.1.0

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

@@ -0,0 +1,391 @@
+{
+  "meta": {
+    "id": "Patterns-ConfirmationDialog",
+    "title": "Confirmation dialog",
+    "exportName": "ConfirmationDialog",
+    "description": "A pre-composed confirm/cancel dialog with a flat, opinionated API.",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/patterns/dialogs/confirmation-dialog/confirmation-dialog.mdx",
+    "menu": [
+      "Patterns",
+      "Dialogs",
+      "Confirmation dialog"
+    ],
+    "route": "patterns/dialogs/confirmation-dialog",
+    "tags": [
+      "component",
+      "pattern",
+      "dialog",
+      "ConfirmationDialog"
+    ],
+    "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\nConfirmationDialog is a pattern component that wraps the Dialog primitive plus two Buttons in a flat, opinionated API for the most common confirm/cancel dialog shape: a title, a body, two action callbacks, and optional state and intent props. It is the recommended replacement for the Merchant Center Application Kit's `ConfirmationDialog`.\n\nThe pattern exposes a small, flat set of props — `title`, `children`, `onConfirm`, `onCancel`, plus optional state, label, intent, and accessibility props — and delegates everything else (sizing, stacking, portaling, focus management, button styling) to the underlying `Dialog` and `Button` primitives.\n\n### When to use\n\n- Asking the user to confirm an action before it executes (delete, remove, discard, submit, publish)\n- Any scenario that needs a confirm/cancel pair with optional destructive styling and an in-flight loading state\n- Replacing app-kit's `ConfirmationDialog` during the migration\n\n### When not to use\n\n- Read-only informational dialogs without action buttons — use the `InfoDialog` pattern\n- Dialogs hosting editable forms — use `Dialog` directly with form wiring\n- Any scenario that needs a non-default size, custom dismissability behaviour, per-button `data-*` attributes, or a separate `onClose`/`onCancel` distinction — drop down to `Dialog` directly (see the escape hatch in the developer documentation)\n\n### Resources\n\nFor detailed guidance on the underlying primitives, consult the component guidelines:\n\n- [Dialog Guidelines](/components/feedback/dialog) — Variants, dismissability, sizing, placement, accessibility\n- [Button Guidelines](/components/forms/button) — Variants, color palettes, loading states\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-dialogs-confirmationdialog--docs)\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nConfirmationDialog is a pattern component that wraps the Dialog primitive plus two Buttons in a flat, opinionated API for the most common confirm/cancel dialog shape: a title, a body, two action callbacks, and optional state and intent props. It is the recommended replacement for the Merchant Center Application Kit's `ConfirmationDialog`.\n\nThe pattern exposes a small, flat set of props — `title`, `children`, `onConfirm`, `onCancel`, plus optional state, label, intent, and accessibility props — and delegates everything else (sizing, stacking, portaling, focus management, button styling) to the underlying `Dialog` and `Button` primitives.\n\n### When to use\n\n- Asking the user to confirm an action before it executes (delete, remove, discard, submit, publish)\n- Any scenario that needs a confirm/cancel pair with optional destructive styling and an in-flight loading state\n- Replacing app-kit's `ConfirmationDialog` during the migration\n\n### When not to use\n\n- Read-only informational dialogs without action buttons — use the `InfoDialog` pattern\n- Dialogs hosting editable forms — use `Dialog` directly with form wiring\n- Any scenario that needs a non-default size, custom dismissability behaviour, per-button `data-*` attributes, or a separate `onClose`/`onCancel` distinction — drop down to `Dialog` directly (see the escape hatch in the developer documentation)\n\n### Resources\n\nFor detailed guidance on the underlying primitives, consult the component guidelines:\n\n- [Dialog Guidelines](/components/feedback/dialog) — Variants, dismissability, sizing, placement, accessibility\n- [Button Guidelines](/components/forms/button) — Variants, color palettes, loading states\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-dialogs-confirmationdialog--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: ConfirmationDialog vs manual Dialog composition\n\n**With ConfirmationDialog:**\n\n```tsx\n<ConfirmationDialog\n  title=\"Delete project\"\n  intent=\"destructive\"\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n  onConfirm={handleDelete}\n  onCancel={() => setIsOpen(false)}\n>\n  <Text>This action cannot be undone.</Text>\n</ConfirmationDialog>\n```\n\n**Manual composition:**\n\n```tsx\n<Dialog.Root\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n  isDismissable\n>\n  <Dialog.Content>\n    <Dialog.Header>\n      <Dialog.Title>Delete project</Dialog.Title>\n      <Dialog.CloseTrigger />\n    </Dialog.Header>\n    <Dialog.Body>\n      <Text>This action cannot be undone.</Text>\n    </Dialog.Body>\n    <Dialog.Footer>\n      <Button variant=\"outline\" onPress={() => setIsOpen(false)}>\n        Cancel\n      </Button>\n      <Button\n        variant=\"solid\"\n        colorPalette=\"critical\"\n        onPress={() => {\n          handleDelete();\n          setIsOpen(false);\n        }}\n      >\n        Delete\n      </Button>\n    </Dialog.Footer>\n  </Dialog.Content>\n</Dialog.Root>\n```\n\n### When to use which\n\n**Use ConfirmationDialog when:**\n\n- You need a confirm/cancel dialog with default or destructive intent\n- You want localized default Confirm/Cancel labels without wiring `useIntl` boilerplate\n- You want a built-in loading lockout for async confirm handlers\n- You're happy treating Escape, overlay click, and the X button as equivalent to clicking Cancel\n\n**Use Dialog directly when:**\n\n- You need a non-default size or custom dismissability behaviour\n- You need per-button `data-*` attributes (test IDs, tracking)\n- You need to distinguish the cancel button click from ambient dismissals (Escape, overlay, X) in your handlers\n- Your confirm action needs custom styling beyond `default` and `destructive` intent\n\n## Migrating from `merchant-center-application-kit`\n\nThe Nimbus `ConfirmationDialog` is intentionally smaller and more opinionated than the app-kit equivalent.\n\n| app-kit prop | Nimbus equivalent |\n| --- | --- |\n| `isOpen`, `onClose` | `isOpen`, `onOpenChange` (close routes through `onCancel` for ambient dismissals) |\n| `title`, `aria-label` | unchanged |\n| `children` | unchanged |\n| `labelPrimary`, `labelSecondary` | `confirmLabel`, `cancelLabel` |\n| `isPrimaryButtonDisabled` | `isConfirmDisabled` |\n| `onCancel`, `onConfirm` | unchanged |\n| `size` | dropped — drop down to `Dialog` for non-default sizes |\n| `zIndex` | dropped — Dialog primitive handles z-index stacking |\n| `dataAttributesPrimaryButton`, `dataAttributesSecondaryButton` | dropped — drop down to `Dialog` to add `data-*` attributes per button |\n| `getParentSelector` | dropped — React Aria handles portaling |\n| `ConfirmationDialog.TextTitle` | dropped — `title` accepts any `ReactNode` |\n| `ConfirmationDialog.Intl` | dropped — pass `confirmLabel` / `cancelLabel` directly |\n| _no equivalent_ | new: `intent=\"destructive\"` for delete/remove flows |\n| _no equivalent_ | new: `isConfirmLoading` for async confirm lockout |\n\nThe most consequential semantic change is that **`onClose` and `onCancel` are unified onto a single `onCancel`** that fires from every close path: the cancel button, Escape, overlay click, and the X button. ~55% of audited app-kit consumers already wire both to the same handler, so this is a no-op for the majority. If your app relies on the distinction, drop down to `Dialog` directly.\n\n## Getting started\n\n### Import\n\n```tsx\nimport {\n  ConfirmationDialog,\n  type ConfirmationDialogProps,\n} 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)}>Submit order</Button>\n      <ConfirmationDialog\n        title=\"Submit order\"\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        onConfirm={() => {\n          console.log(\"submitting\");\n          setIsOpen(false);\n        }}\n        onCancel={() => setIsOpen(false)}\n      >\n        <Text>You're about to submit this order for fulfillment.</Text>\n      </ConfirmationDialog>\n    </>\n  );\n};\n```\n\n## Usage examples\n\n### Destructive intent\n\nSet `intent=\"destructive\"` for delete, remove, discard, and other irreversible actions. The confirm button receives the critical color palette automatically.\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n\n  return (\n    <>\n      <Button colorPalette=\"critical\" onPress={() => setIsOpen(true)}>\n        Delete project\n      </Button>\n      <ConfirmationDialog\n        title=\"Delete project\"\n        intent=\"destructive\"\n        confirmLabel=\"Delete\"\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        onConfirm={() => {\n          console.log(\"deleting\");\n          setIsOpen(false);\n        }}\n        onCancel={() => setIsOpen(false)}\n      >\n        <Text>\n          This will permanently delete the project and all its data.\n        </Text>\n      </ConfirmationDialog>\n    </>\n  );\n};\n```\n\n### Async confirm with loading lockout\n\nIf `onConfirm` returns a `Promise`, the dialog stays open while the promise is pending and closes automatically when it fulfills. Hold `isConfirmLoading` true for the duration so the pattern can:\n\n- Show a spinner inside the confirm button\n- Disable both buttons\n- Suppress Escape, overlay click, and the X button\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n  const [isLoading, setIsLoading] = useState(false);\n\n  const handleConfirm = async () => {\n    setIsLoading(true);\n    try {\n      await new Promise((resolve) => setTimeout(resolve, 1500));\n      // Dialog closes automatically when the promise fulfills.\n    } finally {\n      setIsLoading(false);\n    }\n  };\n\n  return (\n    <>\n      <Button onPress={() => setIsOpen(true)}>Publish</Button>\n      <ConfirmationDialog\n        title=\"Publish to production?\"\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        isConfirmLoading={isLoading}\n        onConfirm={handleConfirm}\n        onCancel={() => setIsOpen(false)}\n      >\n        <Text>The change will be visible to all customers.</Text>\n      </ConfirmationDialog>\n    </>\n  );\n};\n```\n\nIf the promise **rejects**, the dialog stays open so the consumer can surface the error (e.g. a Toast or an inline banner) and let the user retry. Let the error propagate out of `onConfirm` to keep the dialog open — catching the error inside the handler resolves the promise successfully and closes the dialog.\n\nFor long-running operations, prefer closing the dialog optimistically and reporting progress via a Toast or a banner, rather than holding the dialog open with a spinner.\n\n### Disabled confirm\n\nUse `isConfirmDisabled` to gate the confirm action on consumer-side validity (e.g. a required acknowledgement checkbox is unchecked).\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n  const [acknowledged, setAcknowledged] = useState(false);\n\n  return (\n    <>\n      <Button onPress={() => setIsOpen(true)}>Continue</Button>\n      <ConfirmationDialog\n        title=\"Confirm acknowledgement\"\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        isConfirmDisabled={!acknowledged}\n        onConfirm={() => setIsOpen(false)}\n        onCancel={() => setIsOpen(false)}\n      >\n        <Stack gap=\"200\">\n          <Text>Please acknowledge before continuing.</Text>\n          <Checkbox isSelected={acknowledged} onChange={setAcknowledged}>\n            I understand\n          </Checkbox>\n        </Stack>\n      </ConfirmationDialog>\n    </>\n  );\n};\n```\n\n### Custom labels\n\n`confirmLabel` and `cancelLabel` accept any `ReactNode`, so consumer-localized strings (e.g. from `intl.formatMessage(...)`) work directly:\n\n```tsx\n<ConfirmationDialog\n  title={intl.formatMessage(messages.unpublishTitle)}\n  confirmLabel={intl.formatMessage(messages.unpublishConfirm)}\n  cancelLabel={intl.formatMessage(messages.unpublishCancel)}\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n  onConfirm={handleUnpublish}\n  onCancel={() => setIsOpen(false)}\n>\n  <Text>{intl.formatMessage(messages.unpublishBody)}</Text>\n</ConfirmationDialog>\n```\n\n### ReactNode title with aria-label\n\n`title` accepts any ReactNode, so you can compose a heading with an icon or badge alongside text. When the composed markup wouldn't form a meaningful accessible name, pass `aria-label`:\n\n```tsx\n<ConfirmationDialog\n  title={\n    <Flex alignItems=\"center\" gap=\"200\">\n      <Text>Cancel subscription</Text>\n      <Badge>Pro</Badge>\n    </Flex>\n  }\n  aria-label=\"Cancel subscription\"\n  intent=\"destructive\"\n  confirmLabel=\"Cancel subscription\"\n  cancelLabel=\"Keep subscription\"\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n  onConfirm={handleCancel}\n  onCancel={() => setIsOpen(false)}\n>\n  <Text>You'll keep access until the end of the billing period.</Text>\n</ConfirmationDialog>\n```\n\n## Close affordances\n\nEvery close path other than the confirm button invokes `onCancel`:\n\n- **Cancel button** → `onCancel()` then `onOpenChange(false)`\n- **Confirm button** → `onConfirm()` then `onOpenChange(false)` (after the returned `Promise` fulfills, if any; rejected promises leave the dialog open). Does NOT invoke `onCancel`.\n- **Escape key** → `onCancel()` then `onOpenChange(false)`\n- **Overlay click** → `onCancel()` then `onOpenChange(false)`\n- **X button in header** → `onCancel()` then `onOpenChange(false)`\n\nWhile `isConfirmLoading` is `true`, all four cancel paths are suppressed and neither callback fires.\n\n## Accessibility\n\nConfirmationDialog 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` so the dialog has a meaningful accessible name.\n\nThe cancel button is rendered before the confirm button in DOM order, so the natural first-focusable target is Cancel — a safer default for destructive confirmations.\n\n## Escape hatch\n\nIf you need a non-default size, per-button `data-*` attributes, custom dismissability, or a separate `onClose`-vs-`onCancel` distinction, drop down to composing `Dialog` and `Button` directly:\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n\n  return (\n    <>\n      <Button onPress={() => setIsOpen(true)}>Open large confirmation</Button>\n      <Dialog.Root\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        isDismissable\n        aria-label=\"Bulk delete\"\n      >\n        <Dialog.Content size=\"lg\">\n          <Dialog.Header>\n            <Dialog.Title>Delete 250 records?</Dialog.Title>\n            <Dialog.CloseTrigger data-test-id=\"bulk-delete-close\" />\n          </Dialog.Header>\n          <Dialog.Body>\n            <Text>This action cannot be undone.</Text>\n          </Dialog.Body>\n          <Dialog.Footer>\n            <Button\n              variant=\"outline\"\n              data-test-id=\"bulk-delete-cancel\"\n              onPress={() => setIsOpen(false)}\n            >\n              Cancel\n            </Button>\n            <Button\n              variant=\"solid\"\n              colorPalette=\"critical\"\n              data-test-id=\"bulk-delete-confirm\"\n              onPress={() => setIsOpen(false)}\n            >\n              Delete\n            </Button>\n          </Dialog.Footer>\n        </Dialog.Content>\n      </Dialog.Root>\n    </>\n  );\n};\n```\n\n## API reference\n\n<PropsTable id=\"ConfirmationDialog\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using ConfirmationDialog 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 ConfirmationDialog opens with default localized button labels.\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  Button,\n  ConfirmationDialog,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ConfirmationDialog - Basic rendering\", () => {\n  it(\"renders title, body, and default Confirm/Cancel labels when isOpen is true\", () => {\n    render(\n      <NimbusProvider>\n        <ConfirmationDialog\n          title=\"Discard changes?\"\n          isOpen\n          onConfirm={() => {}}\n          onCancel={() => {}}\n        >\n          <Text>You will lose any unsaved changes.</Text>\n        </ConfirmationDialog>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"heading\", { name: \"Discard changes?\" })\n    ).toBeInTheDocument();\n    expect(\n      screen.getByText(\"You will lose any unsaved changes.\")\n    ).toBeInTheDocument();\n    expect(screen.getByRole(\"button\", { name: \"Confirm\" })).toBeInTheDocument();\n    expect(screen.getByRole(\"button\", { name: \"Cancel\" })).toBeInTheDocument();\n  });\n\n  it(\"uses the string title as the dialog's accessible name\", () => {\n    render(\n      <NimbusProvider>\n        <ConfirmationDialog\n          title=\"Delete project\"\n          isOpen\n          onConfirm={() => {}}\n          onCancel={() => {}}\n        >\n          <Text>This action cannot be undone.</Text>\n        </ConfirmationDialog>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"dialog\")).toHaveAccessibleName(\"Delete project\");\n  });\n});\n```\n\n### Confirm and Cancel callbacks\n\nWire onConfirm and onCancel to consumer state to react to user choices.\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  Button,\n  ConfirmationDialog,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ConfirmationDialog - Confirm and Cancel callbacks\", () => {\n  it(\"invokes onConfirm and closes the dialog when the confirm button is clicked\", async () => {\n    const user = userEvent.setup();\n    const handleConfirm = vi.fn();\n    const handleCancel = vi.fn();\n\n    const ControlledConfirmationDialog = () => {\n      const [isOpen, setIsOpen] = useState(true);\n      return (\n        <ConfirmationDialog\n          title=\"Submit order\"\n          isOpen={isOpen}\n          onOpenChange={setIsOpen}\n          onConfirm={handleConfirm}\n          onCancel={handleCancel}\n        >\n          <Text>Submit this order for fulfillment.</Text>\n        </ConfirmationDialog>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <ControlledConfirmationDialog />\n      </NimbusProvider>\n    );\n\n    await waitFor(() => expect(screen.getByRole(\"dialog\")).toBeInTheDocument());\n\n    await user.click(screen.getByRole(\"button\", { name: \"Confirm\" }));\n\n    expect(handleConfirm).toHaveBeenCalledTimes(1);\n    expect(handleCancel).not.toHaveBeenCalled();\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n  });\n\n  it(\"invokes onCancel and closes the dialog when the cancel button is clicked\", async () => {\n    const user = userEvent.setup();\n    const handleConfirm = vi.fn();\n    const handleCancel = vi.fn();\n\n    const ControlledConfirmationDialog = () => {\n      const [isOpen, setIsOpen] = useState(true);\n      return (\n        <ConfirmationDialog\n          title=\"Discard changes?\"\n          isOpen={isOpen}\n          onOpenChange={setIsOpen}\n          onConfirm={handleConfirm}\n          onCancel={handleCancel}\n        >\n          <Text>You will lose any unsaved changes.</Text>\n        </ConfirmationDialog>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <ControlledConfirmationDialog />\n      </NimbusProvider>\n    );\n\n    await waitFor(() => expect(screen.getByRole(\"dialog\")).toBeInTheDocument());\n\n    await user.click(screen.getByRole(\"button\", { name: \"Cancel\" }));\n\n    expect(handleCancel).toHaveBeenCalledTimes(1);\n    expect(handleConfirm).not.toHaveBeenCalled();\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Destructive intent\n\nUse intent=\"destructive\" for delete, remove, and discard flows.\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  Button,\n  ConfirmationDialog,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ConfirmationDialog - Destructive intent\", () => {\n  it(\"renders a destructive confirm button styled with the critical palette\", () => {\n    render(\n      <NimbusProvider>\n        <ConfirmationDialog\n          title=\"Delete project\"\n          intent=\"destructive\"\n          confirmLabel=\"Delete\"\n          isOpen\n          onConfirm={() => {}}\n          onCancel={() => {}}\n        >\n          <Text>This will permanently delete the project.</Text>\n        </ConfirmationDialog>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\", { name: \"Delete\" })).toBeInTheDocument();\n  });\n});\n```\n\n### Loading state lockout\n\nHold the dialog open while an async confirm is in flight.\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  Button,\n  ConfirmationDialog,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ConfirmationDialog - Loading state\", () => {\n  it(\"disables both buttons while isConfirmLoading is true\", () => {\n    render(\n      <NimbusProvider>\n        <ConfirmationDialog\n          title=\"Submitting…\"\n          isOpen\n          isConfirmLoading\n          onConfirm={() => {}}\n          onCancel={() => {}}\n        >\n          <Text>Your request is being processed.</Text>\n        </ConfirmationDialog>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\", { name: /confirm/i })).toBeDisabled();\n    expect(screen.getByRole(\"button\", { name: /cancel/i })).toBeDisabled();\n  });\n});\n```\n\n### Gated confirm button\n\nUse isConfirmDisabled to gate confirm on consumer-side validity.\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  Button,\n  ConfirmationDialog,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ConfirmationDialog - Disabled confirm\", () => {\n  it(\"disables the confirm button when isConfirmDisabled is true\", async () => {\n    const user = userEvent.setup();\n    const handleConfirm = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <ConfirmationDialog\n          title=\"Confirm acknowledgement\"\n          isOpen\n          isConfirmDisabled\n          onConfirm={handleConfirm}\n          onCancel={() => {}}\n        >\n          <Text>Please review the disclaimer before confirming.</Text>\n        </ConfirmationDialog>\n      </NimbusProvider>\n    );\n\n    const confirm = screen.getByRole(\"button\", { name: \"Confirm\" });\n    expect(confirm).toBeDisabled();\n\n    await user.click(confirm);\n    expect(handleConfirm).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Uncontrolled open state\n\nOpen the dialog by default with defaultOpen instead of managing state.\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  Button,\n  ConfirmationDialog,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ConfirmationDialog - Uncontrolled state\", () => {\n  it(\"opens by default in uncontrolled mode via defaultOpen\", () => {\n    render(\n      <NimbusProvider>\n        <ConfirmationDialog\n          title=\"Confirm action\"\n          defaultOpen\n          onConfirm={() => {}}\n          onCancel={() => {}}\n        >\n          <Text>Are you sure?</Text>\n        </ConfirmationDialog>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"dialog\")).toBeInTheDocument();\n    expect(screen.getByText(\"Are you sure?\")).toBeInTheDocument();\n  });\n});\n```\n\n### Triggering from a button\n\nRender your own trigger and drive isOpen / onOpenChange from state.\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  Button,\n  ConfirmationDialog,\n  NimbusProvider,\n  Text,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"ConfirmationDialog - Trigger pattern\", () => {\n  it(\"opens from a consumer-rendered trigger and closes after confirm\", async () => {\n    const user = userEvent.setup();\n    const handleConfirm = vi.fn();\n    const handleCancel = vi.fn();\n\n    const App = () => {\n      const [isOpen, setIsOpen] = useState(false);\n      return (\n        <>\n          <Button onPress={() => setIsOpen(true)}>Submit order</Button>\n          <ConfirmationDialog\n            title=\"Submit order\"\n            isOpen={isOpen}\n            onOpenChange={setIsOpen}\n            onConfirm={handleConfirm}\n            onCancel={handleCancel}\n          >\n            <Text>Submit this order for fulfillment.</Text>\n          </ConfirmationDialog>\n        </>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <App />\n      </NimbusProvider>\n    );\n\n    expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n\n    await user.click(screen.getByRole(\"button\", { name: \"Submit order\" }));\n\n    await waitFor(() => expect(screen.getByRole(\"dialog\")).toBeInTheDocument());\n\n    await user.click(screen.getByRole(\"button\", { name: \"Confirm\" }));\n\n    expect(handleConfirm).toHaveBeenCalledTimes(1);\n    expect(handleCancel).not.toHaveBeenCalled();\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n",
+      "toc": [
+        {
+          "value": "Comparison: ConfirmationDialog vs manual Dialog composition",
+          "href": "#comparison-confirmationdialog-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": "Migrating from merchant-center-application-kit",
+          "href": "#migrating-from-merchant-center-application-kit",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Destructive intent",
+          "href": "#destructive-intent",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Async confirm with loading lockout",
+          "href": "#async-confirm-with-loading-lockout",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled confirm",
+          "href": "#disabled-confirm",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom labels",
+          "href": "#custom-labels",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "ReactNode title with aria-label",
+          "href": "#reactnode-title-with-aria-label",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Close affordances",
+          "href": "#close-affordances",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Escape hatch",
+          "href": "#escape-hatch",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering",
+          "href": "#basic-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Confirm and Cancel callbacks",
+          "href": "#confirm-and-cancel-callbacks",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Destructive intent",
+          "href": "#destructive-intent-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Loading state lockout",
+          "href": "#loading-state-lockout",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Gated confirm button",
+          "href": "#gated-confirm-button",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled open state",
+          "href": "#uncontrolled-open-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Triggering from a button",
+          "href": "#triggering-from-a-button",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}