@commercetools/nimbus-mcp 2.11.0 → 3.1.0

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

@@ -0,0 +1,358 @@
+{
+  "meta": {
+    "id": "Patterns-FormDialog",
+    "title": "Form dialog",
+    "exportName": "FormDialog",
+    "description": "A pre-composed save/cancel dialog with a flat, opinionated API for hosting a form in a modal.",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/patterns/dialogs/form-dialog/form-dialog.mdx",
+    "menu": [
+      "Patterns",
+      "Dialogs",
+      "Form dialog"
+    ],
+    "route": "patterns/dialogs/form-dialog",
+    "tags": [
+      "component",
+      "pattern",
+      "dialog",
+      "FormDialog"
+    ],
+    "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\nFormDialog is a pattern component that wraps the Dialog primitive plus two Buttons in a flat, opinionated API for the most common form-in-a-modal shape: a title, form content, two action callbacks, and optional state props. It is the recommended replacement for the Merchant Center Application Kit's `FormDialog`.\n\nThe pattern exposes a small, flat set of props — `title`, `children`, `onSave`, `onCancel`, plus optional state, label, 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- Hosting an editable form inside a modal (create / edit a single entity, configure settings, edit a profile)\n- Any scenario that needs a save/cancel pair with an in-flight loading state and a unified cancel route across the cancel button and ambient dismiss affordances\n- Replacing app-kit's `FormDialog` during the migration\n\n### When not to use\n\n- Read-only informational dialogs without action buttons — use the `InfoDialog` pattern\n- Confirm/cancel dialogs without an editable form (e.g. \"Are you sure you want to delete this?\") — use the `ConfirmationDialog` pattern, which adds a destructive intent variant\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-formdialog--docs)\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nFormDialog is a pattern component that wraps the Dialog primitive plus two Buttons in a flat, opinionated API for the most common form-in-a-modal shape: a title, form content, two action callbacks, and optional state props. It is the recommended replacement for the Merchant Center Application Kit's `FormDialog`.\n\nThe pattern exposes a small, flat set of props — `title`, `children`, `onSave`, `onCancel`, plus optional state, label, 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- Hosting an editable form inside a modal (create / edit a single entity, configure settings, edit a profile)\n- Any scenario that needs a save/cancel pair with an in-flight loading state and a unified cancel route across the cancel button and ambient dismiss affordances\n- Replacing app-kit's `FormDialog` during the migration\n\n### When not to use\n\n- Read-only informational dialogs without action buttons — use the `InfoDialog` pattern\n- Confirm/cancel dialogs without an editable form (e.g. \"Are you sure you want to delete this?\") — use the `ConfirmationDialog` pattern, which adds a destructive intent variant\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-formdialog--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## Getting started\n\n### Import\n\n```tsx\nimport { FormDialog, type FormDialogProps } 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  const [name, setName] = useState(\"\");\n\n  return (\n    <>\n      <Button onPress={() => setIsOpen(true)}>Edit display name</Button>\n      <FormDialog\n        title=\"Edit display name\"\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        onSave={() => {\n          console.log(\"saving\", name);\n          setIsOpen(false);\n        }}\n        onCancel={() => setIsOpen(false)}\n      >\n        <FormField.Root>\n          <FormField.Label>Display name</FormField.Label>\n          <FormField.Input>\n            <TextInput value={name} onChange={setName} />\n          </FormField.Input>\n        </FormField.Root>\n      </FormDialog>\n    </>\n  );\n};\n```\n\n## Comparison: FormDialog vs manual Dialog composition\n\n**With FormDialog:**\n\n```tsx\n<FormDialog\n  title=\"Edit profile\"\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n  onSave={handleSave}\n  onCancel={() => setIsOpen(false)}\n  isSaveDisabled={!isDirty}\n>\n  <FormField.Root>\n    <FormField.Label>Display name</FormField.Label>\n    <FormField.Input>\n      <TextInput value={name} onChange={setName} />\n    </FormField.Input>\n  </FormField.Root>\n</FormDialog>\n```\n\n**Manual composition:**\n\n```tsx\n<Dialog.Root isOpen={isOpen} onOpenChange={setIsOpen} isDismissable>\n  <Dialog.Content>\n    <Dialog.Header>\n      <Dialog.Title>Edit profile</Dialog.Title>\n      <Dialog.CloseTrigger />\n    </Dialog.Header>\n    <Dialog.Body>\n      <FormField.Root>\n        <FormField.Label>Display name</FormField.Label>\n        <FormField.Input>\n          <TextInput value={name} onChange={setName} />\n        </FormField.Input>\n      </FormField.Root>\n    </Dialog.Body>\n    <Dialog.Footer>\n      <Button variant=\"outline\" onPress={() => setIsOpen(false)}>\n        Cancel\n      </Button>\n      <Button\n        variant=\"solid\"\n        colorPalette=\"primary\"\n        isDisabled={!isDirty}\n        onPress={() => {\n          handleSave();\n          setIsOpen(false);\n        }}\n      >\n        Save\n      </Button>\n    </Dialog.Footer>\n  </Dialog.Content>\n</Dialog.Root>\n```\n\n### When to use which\n\n**Use FormDialog when:**\n\n- You need a save/cancel dialog hosting an editable form\n- You want localized default Save/Cancel labels without wiring `useIntl` boilerplate\n- You want a built-in loading lockout for async save handlers (with in-flight data-loss protection)\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 (e.g. wider for two-column form layouts)\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- You need a confirm/cancel dialog without an editable form — use `ConfirmationDialog` instead\n- You need a read-only informational dialog — use `InfoDialog` instead\n\n## Migrating from `merchant-center-application-kit`\n\nThe Nimbus `FormDialog` 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`                              | `saveLabel`, `cancelLabel`                                                       |\n| `isPrimaryButtonDisabled`                                     | `isSaveDisabled`                                                                 |\n| `onCancel`, `onSecondaryButtonClick`                          | unified onto a single `onCancel`                                                 |\n| `onPrimaryButtonClick`, `onSubmit`                            | unified onto a single `onSave`                                                   |\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| _no equivalent_                                               | new: `isSaveLoading` for async save lockout                                      |\n| _no equivalent_                                               | new: `onSave` accepts `() => void \\| Promise<void>` for deferred close           |\n\nThe most consequential semantic changes are:\n\n1. **`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. If your app relies on the distinction, drop down to `Dialog` directly.\n2. **The pattern does NOT wrap `children` in a `<form>` element.** `onSave` is invoked from the save button's `onPress`, not from a form `submit` event. Consumers wanting Enter-to-submit semantics should wrap their fields in `<form onSubmit={handleSubmit}>` inside `children` and call `onSave` from `handleSubmit`.\n\n## Usage examples\n\n### Async save with loading lockout\n\nIf `onSave` returns a `Promise`, the dialog stays open while the promise is pending and closes automatically when it fulfills. Hold `isSaveLoading` true for the duration so the pattern can:\n\n- Show a spinner inside the save button\n- Disable both buttons\n- Suppress Escape, overlay click, and the X button (preventing accidental in-flight data loss)\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n  const [isLoading, setIsLoading] = useState(false);\n  const [name, setName] = useState(\"\");\n\n  const handleSave = 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)}>Edit profile</Button>\n      <FormDialog\n        title=\"Edit profile\"\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        isSaveLoading={isLoading}\n        onSave={handleSave}\n        onCancel={() => setIsOpen(false)}\n      >\n        <FormField.Root>\n          <FormField.Label>Display name</FormField.Label>\n          <FormField.Input>\n            <TextInput value={name} onChange={setName} />\n          </FormField.Input>\n        </FormField.Root>\n      </FormDialog>\n    </>\n  );\n};\n```\n\nIf the promise **rejects**, the dialog stays open so the consumer can surface validation errors (e.g. server-side field errors as inline `FormField.Error`) and let the user correct and retry. Let the error propagate out of `onSave` to keep the dialog open — catching the error inside the handler resolves the promise successfully and closes the dialog.\n\nFor long-running saves, 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 save\n\nUse `isSaveDisabled` to gate the save action on consumer-side validity (e.g. required form fields are empty or invalid).\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState(false);\n  const [name, setName] = useState(\"\");\n  const isValid = name.trim().length > 0;\n\n  return (\n    <>\n      <Button onPress={() => setIsOpen(true)}>New project</Button>\n      <FormDialog\n        title=\"Create project\"\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        isSaveDisabled={!isValid}\n        saveLabel=\"Create\"\n        onSave={() => {\n          console.log(\"creating\", name);\n          setIsOpen(false);\n          setName(\"\");\n        }}\n        onCancel={() => {\n          setIsOpen(false);\n          setName(\"\");\n        }}\n      >\n        <FormField.Root>\n          <FormField.Label>Project name</FormField.Label>\n          <FormField.Input>\n            <TextInput value={name} onChange={setName} />\n          </FormField.Input>\n        </FormField.Root>\n      </FormDialog>\n    </>\n  );\n};\n```\n\n### Custom labels\n\n`saveLabel` and `cancelLabel` accept any `ReactNode`, so consumer-localized strings (e.g. from `intl.formatMessage(...)`) work directly:\n\n```tsx\n<FormDialog\n  title={intl.formatMessage(messages.editProfileTitle)}\n  saveLabel={intl.formatMessage(messages.editProfileSave)}\n  cancelLabel={intl.formatMessage(messages.editProfileCancel)}\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n  onSave={handleSave}\n  onCancel={() => setIsOpen(false)}\n>\n  {/* form fields */}\n</FormDialog>\n```\n\n### Enter-to-submit via native `<form>`\n\nThe pattern does not wrap `children` in a native `<form>` element. To get Enter-to-submit and browser-native validation, wrap your fields in your own `<form onSubmit={...}>` and call `onSave` from the submit handler:\n\n```tsx\nconst handleSubmit = (event) => {\n  event.preventDefault();\n  handleSave();\n};\n\n<FormDialog\n  title=\"Edit profile\"\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n  onSave={handleSave}\n  onCancel={() => setIsOpen(false)}\n>\n  <form onSubmit={handleSubmit}>\n    <FormField.Root>\n      <FormField.Label>Display name</FormField.Label>\n      <FormField.Input>\n        <TextInput value={name} onChange={setName} />\n      </FormField.Input>\n    </FormField.Root>\n  </form>\n</FormDialog>;\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<FormDialog\n  title={\n    <Flex alignItems=\"center\" gap=\"200\">\n      <Text>Edit billing</Text>\n      <Badge>Pro</Badge>\n    </Flex>\n  }\n  aria-label=\"Edit billing\"\n  isOpen={isOpen}\n  onOpenChange={setIsOpen}\n  onSave={handleSave}\n  onCancel={() => setIsOpen(false)}\n>\n  {/* form fields */}\n</FormDialog>\n```\n\n## Close affordances\n\nEvery close path other than the save button invokes `onCancel`:\n\n- **Cancel button** → `onCancel()` then `onOpenChange(false)`\n- **Save button** → `onSave()` 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 `isSaveLoading` is `true`, all four cancel paths are suppressed and neither callback fires.\n\n## Accessibility\n\nFormDialog 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 — typically landing on the first focusable form field\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\n## Escape hatch\n\nIf you need a non-default size (e.g. wider for two-column forms), 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  const [name, setName] = useState(\"\");\n\n  return (\n    <>\n      <Button onPress={() => setIsOpen(true)}>Open wide form</Button>\n      <Dialog.Root\n        isOpen={isOpen}\n        onOpenChange={setIsOpen}\n        isDismissable\n        aria-label=\"Edit profile\"\n      >\n        <Dialog.Content size=\"lg\">\n          <Dialog.Header>\n            <Dialog.Title>Edit profile</Dialog.Title>\n            <Dialog.CloseTrigger data-test-id=\"profile-close\" />\n          </Dialog.Header>\n          <Dialog.Body>\n            <FormField.Root>\n              <FormField.Label>Display name</FormField.Label>\n              <FormField.Input>\n                <TextInput value={name} onChange={setName} />\n              </FormField.Input>\n            </FormField.Root>\n          </Dialog.Body>\n          <Dialog.Footer>\n            <Button\n              variant=\"outline\"\n              data-test-id=\"profile-cancel\"\n              onPress={() => setIsOpen(false)}\n            >\n              Cancel\n            </Button>\n            <Button\n              variant=\"solid\"\n              colorPalette=\"primary\"\n              data-test-id=\"profile-save\"\n              onPress={() => setIsOpen(false)}\n            >\n              Save\n            </Button>\n          </Dialog.Footer>\n        </Dialog.Content>\n      </Dialog.Root>\n    </>\n  );\n};\n```\n\n## API reference\n\n<PropsTable id=\"FormDialog\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using FormDialog 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 FormDialog opens with form content and 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  FormDialog,\n  FormField,\n  NimbusProvider,\n  TextInput,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"FormDialog - Basic rendering\", () => {\n  it(\"renders title, form content, and default Save/Cancel labels when isOpen is true\", () => {\n    render(\n      <NimbusProvider>\n        <FormDialog\n          title=\"Edit display name\"\n          isOpen\n          onSave={() => {}}\n          onCancel={() => {}}\n        >\n          <FormField.Root>\n            <FormField.Label>Display name</FormField.Label>\n            <FormField.Input>\n              <TextInput defaultValue=\"\" />\n            </FormField.Input>\n          </FormField.Root>\n        </FormDialog>\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"heading\", { name: \"Edit display name\" })\n    ).toBeInTheDocument();\n    expect(screen.getByLabelText(\"Display name\")).toBeInTheDocument();\n    expect(screen.getByRole(\"button\", { name: \"Save\" })).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        <FormDialog\n          title=\"Edit profile\"\n          isOpen\n          onSave={() => {}}\n          onCancel={() => {}}\n        >\n          <FormField.Root>\n            <FormField.Label>Display name</FormField.Label>\n            <FormField.Input>\n              <TextInput defaultValue=\"\" />\n            </FormField.Input>\n          </FormField.Root>\n        </FormDialog>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"dialog\")).toHaveAccessibleName(\"Edit profile\");\n  });\n});\n```\n\n### Save and Cancel callbacks\n\nWire onSave 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  FormDialog,\n  FormField,\n  NimbusProvider,\n  TextInput,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"FormDialog - Save and Cancel callbacks\", () => {\n  it(\"invokes onSave and closes the dialog when the save button is clicked\", async () => {\n    const user = userEvent.setup();\n    const handleSave = vi.fn();\n    const handleCancel = vi.fn();\n\n    const ControlledFormDialog = () => {\n      const [isOpen, setIsOpen] = useState(true);\n      return (\n        <FormDialog\n          title=\"Edit display name\"\n          isOpen={isOpen}\n          onOpenChange={setIsOpen}\n          onSave={handleSave}\n          onCancel={handleCancel}\n        >\n          <FormField.Root>\n            <FormField.Label>Display name</FormField.Label>\n            <FormField.Input>\n              <TextInput defaultValue=\"\" />\n            </FormField.Input>\n          </FormField.Root>\n        </FormDialog>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <ControlledFormDialog />\n      </NimbusProvider>\n    );\n\n    await waitFor(() => expect(screen.getByRole(\"dialog\")).toBeInTheDocument());\n\n    await user.click(screen.getByRole(\"button\", { name: \"Save\" }));\n\n    expect(handleSave).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 handleSave = vi.fn();\n    const handleCancel = vi.fn();\n\n    const ControlledFormDialog = () => {\n      const [isOpen, setIsOpen] = useState(true);\n      return (\n        <FormDialog\n          title=\"Edit display name\"\n          isOpen={isOpen}\n          onOpenChange={setIsOpen}\n          onSave={handleSave}\n          onCancel={handleCancel}\n        >\n          <FormField.Root>\n            <FormField.Label>Display name</FormField.Label>\n            <FormField.Input>\n              <TextInput defaultValue=\"\" />\n            </FormField.Input>\n          </FormField.Root>\n        </FormDialog>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <ControlledFormDialog />\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(handleSave).not.toHaveBeenCalled();\n    await waitFor(() => {\n      expect(screen.queryByRole(\"dialog\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Save Disabled\n\nGate the save action behind consumer-side validity (e.g. required fields are empty).\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  FormDialog,\n  FormField,\n  NimbusProvider,\n  TextInput,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"FormDialog - Save disabled\", () => {\n  it(\"disables the save button when isSaveDisabled is true\", () => {\n    render(\n      <NimbusProvider>\n        <FormDialog\n          title=\"Edit profile\"\n          isOpen\n          isSaveDisabled\n          onSave={() => {}}\n          onCancel={() => {}}\n        >\n          <FormField.Root>\n            <FormField.Label>Display name</FormField.Label>\n            <FormField.Input>\n              <TextInput defaultValue=\"\" />\n            </FormField.Input>\n          </FormField.Root>\n        </FormDialog>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\", { name: \"Save\" })).toBeDisabled();\n    expect(screen.getByRole(\"button\", { name: \"Cancel\" })).toBeEnabled();\n  });\n});\n```\n\n### Custom button labels\n\nOverride the default localized Save and Cancel labels via saveLabel and cancelLabel.\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  FormDialog,\n  FormField,\n  NimbusProvider,\n  TextInput,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"FormDialog - Custom labels\", () => {\n  it(\"renders custom saveLabel and cancelLabel when provided\", () => {\n    render(\n      <NimbusProvider>\n        <FormDialog\n          title=\"New project\"\n          isOpen\n          saveLabel=\"Create\"\n          cancelLabel=\"Discard\"\n          onSave={() => {}}\n          onCancel={() => {}}\n        >\n          <FormField.Root>\n            <FormField.Label>Project name</FormField.Label>\n            <FormField.Input>\n              <TextInput defaultValue=\"\" />\n            </FormField.Input>\n          </FormField.Root>\n        </FormDialog>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\", { name: \"Create\" })).toBeInTheDocument();\n    expect(screen.getByRole(\"button\", { name: \"Discard\" })).toBeInTheDocument();\n  });\n});\n```\n\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": "Comparison: FormDialog vs manual Dialog composition",
+          "href": "#comparison-formdialog-vs-manual-dialog-composition",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use which",
+          "href": "#when-to-use-which",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Migrating from merchant-center-application-kit",
+          "href": "#migrating-from-merchant-center-application-kit",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Async save with loading lockout",
+          "href": "#async-save-with-loading-lockout",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled save",
+          "href": "#disabled-save",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom labels",
+          "href": "#custom-labels",
+          "depth": 3,
+          "numbering": [
+            1,
+            4,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Enter-to-submit via native <form>",
+          "href": "#enter-to-submit-via-native-form",
+          "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": "Save and Cancel callbacks",
+          "href": "#save-and-cancel-callbacks",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Save Disabled",
+          "href": "#save-disabled",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom button labels",
+          "href": "#custom-button-labels",
+          "depth": 3,
+          "numbering": [
+            1,
+            9,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}