@commercetools/nimbus-mcp 2.10.0 → 3.0.0

package/data/docs/routes/patterns-actions-form-action-bar.json

@@ -0,0 +1,412 @@
+{
+  "meta": {
+    "id": "Patterns-FormActionBar",
+    "title": "Form action bar",
+    "exportName": "FormActionBar",
+    "description": "This pattern component provides standard save/cancel/delete action buttons for form footers, working inside any footer slot.",
+    "lifecycleState": "Beta",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/patterns/actions/form-action-bar/form-action-bar.mdx",
+    "menu": [
+      "Patterns",
+      "Actions",
+      "Form action bar"
+    ],
+    "route": "patterns/actions/form-action-bar",
+    "tags": [
+      "component",
+      "pattern",
+      "actions",
+      "Button",
+      "Group"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Anatomy",
+        "href": "#anatomy",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Usage",
+        "href": "#usage",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "When to use",
+        "href": "#when-to-use",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "When not to use",
+        "href": "#when-not-to-use",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Do",
+        "href": "#do",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Don't",
+        "href": "#dont",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          4
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          5
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nFormActionBar is a pattern component that composes a `Group` of action\n`Button`s for form footers. It replaces the need for separate form-page\nwrappers — one `FormActionBar` works in any footer slot:\n`DefaultPage.Footer`, `ModalPage.Footer`, `Drawer.Footer`, `Dialog.Footer`.\n\n## Anatomy\n\n- An accessible group wrapper labelled \"Form actions\" (override via\n  `aria-label`).\n- Optional destructive delete button on the leading edge — only rendered when\n  `onDelete` is provided.\n- Cancel button (outline) that reverts pending changes.\n- Primary save button (solid) on the trailing edge.\n\nButton order is fixed: delete → cancel → save. This keeps the primary action\nanchored to the same spot across every form and places destructive actions\nfurthest from the primary action to reduce mis-clicks.\n\n## Usage\n\n### When to use\n\n- Any form footer where the user commits or discards pending edits.\n- Detail and full-page create/edit flows (`DefaultPage.Footer`).\n- Modal and drawer forms (`ModalPage.Footer`, `Dialog.Footer`,\n  `Drawer.Footer`).\n\n### When not to use\n\n- For a single action (e.g., \"Close\") use a standalone `Button`.\n- For toolbar-style actions unrelated to saving a form, use `Group` directly\n  with the buttons you need.\n- For destructive actions that require a separate confirmation step beyond the\n  in-place delete button, pair with an `AlertDialog`.\n\n### Do\n\n- Disable save (`isSaveDisabled`) when the form is pristine or has validation\n  errors.\n- Drive `isSaveLoading` / `isDeleteLoading` from your async submit flow so all\n  actions lock during the mutation.\n- Override labels (`saveLabel`, `cancelLabel`, `deleteLabel`) to match domain\n  vocabulary when \"Save\"/\"Cancel\"/\"Delete\" are not precise (e.g., \"Publish\",\n  \"Discard\", \"Archive\").\n\n### Don't\n\n- Don't render custom action buttons alongside FormActionBar in the same\n  footer — keep the action set predictable.\n- Don't reorder the buttons; delete → cancel → save is load-bearing for muscle\n  memory and accessibility.\n- Don't drive `isSaveDisabled` and `isSaveLoading` from the same piece of\n  state — they are independent flags representing different UX intents (form\n  is invalid / pristine vs. submit is in-flight). Both can be `true`\n  simultaneously, but they should come from distinct sources.\n\n### Resources\n\nFor detailed guidance on the individual components that make up this pattern,\nconsult the component guidelines:\n\n- [Button Guidelines](/components/inputs/button) - Button variants, sizes, and\n  accessibility\n- [Group Guidelines](/components/layout/group) - Grouping related controls\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-actions-formactionbar--docs)\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nFormActionBar is a pattern component that composes a `Group` of action\n`Button`s for form footers. It replaces the need for separate form-page\nwrappers — one `FormActionBar` works in any footer slot:\n`DefaultPage.Footer`, `ModalPage.Footer`, `Drawer.Footer`, `Dialog.Footer`.\n\n## Anatomy\n\n- An accessible group wrapper labelled \"Form actions\" (override via\n  `aria-label`).\n- Optional destructive delete button on the leading edge — only rendered when\n  `onDelete` is provided.\n- Cancel button (outline) that reverts pending changes.\n- Primary save button (solid) on the trailing edge.\n\nButton order is fixed: delete → cancel → save. This keeps the primary action\nanchored to the same spot across every form and places destructive actions\nfurthest from the primary action to reduce mis-clicks.\n\n## Usage\n\n### When to use\n\n- Any form footer where the user commits or discards pending edits.\n- Detail and full-page create/edit flows (`DefaultPage.Footer`).\n- Modal and drawer forms (`ModalPage.Footer`, `Dialog.Footer`,\n  `Drawer.Footer`).\n\n### When not to use\n\n- For a single action (e.g., \"Close\") use a standalone `Button`.\n- For toolbar-style actions unrelated to saving a form, use `Group` directly\n  with the buttons you need.\n- For destructive actions that require a separate confirmation step beyond the\n  in-place delete button, pair with an `AlertDialog`.\n\n### Do\n\n- Disable save (`isSaveDisabled`) when the form is pristine or has validation\n  errors.\n- Drive `isSaveLoading` / `isDeleteLoading` from your async submit flow so all\n  actions lock during the mutation.\n- Override labels (`saveLabel`, `cancelLabel`, `deleteLabel`) to match domain\n  vocabulary when \"Save\"/\"Cancel\"/\"Delete\" are not precise (e.g., \"Publish\",\n  \"Discard\", \"Archive\").\n\n### Don't\n\n- Don't render custom action buttons alongside FormActionBar in the same\n  footer — keep the action set predictable.\n- Don't reorder the buttons; delete → cancel → save is load-bearing for muscle\n  memory and accessibility.\n- Don't drive `isSaveDisabled` and `isSaveLoading` from the same piece of\n  state — they are independent flags representing different UX intents (form\n  is invalid / pristine vs. submit is in-flight). Both can be `true`\n  simultaneously, but they should come from distinct sources.\n\n### Resources\n\nFor detailed guidance on the individual components that make up this pattern,\nconsult the component guidelines:\n\n- [Button Guidelines](/components/inputs/button) - Button variants, sizes, and\n  accessibility\n- [Group Guidelines](/components/layout/group) - Grouping related controls\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-actions-formactionbar--docs)\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Anatomy",
+          "href": "#anatomy",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use",
+          "href": "#when-to-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When not to use",
+          "href": "#when-not-to-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Do",
+          "href": "#do",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Don't",
+          "href": "#dont",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            5
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Comparison: pattern vs manual composition\n\n**With FormActionBar:**\n\n```tsx\n<FormActionBar\n  onSave={handleSave}\n  onCancel={handleCancel}\n  onDelete={handleDelete}\n  isSaveDisabled={!isDirty}\n  isSaveLoading={isSaving}\n/>\n```\n\n**Manual composition (escape hatch):**\n\n```tsx\n<Group aria-label=\"Form actions\" gap=\"300\">\n  <Button\n    variant=\"solid\"\n    colorPalette=\"critical\"\n    isDisabled={isSaving || isDeleting}\n    onPress={handleDelete}\n  >\n    {isDeleting ? <LoadingSpinner /> : \"Delete\"}\n  </Button>\n  <Button\n    variant=\"outline\"\n    isDisabled={isSaving || isDeleting}\n    onPress={handleCancel}\n  >\n    Cancel\n  </Button>\n  <Button\n    variant=\"solid\"\n    colorPalette=\"primary\"\n    isDisabled={!isDirty || isSaving || isDeleting}\n    onPress={handleSave}\n  >\n    {isSaving ? <LoadingSpinner /> : \"Save\"}\n  </Button>\n</Group>\n```\n\n### When to use which\n\n**Use FormActionBar when:**\n\n- Building standard forms with save/cancel/delete actions\n- You want consistent button variants and ordering across your app\n- You need built-in i18n defaults for button labels\n- You want to minimize boilerplate\n\n**Use manual composition with Button + Group when:**\n\n- You need a different action set (e.g., submit + reset + preview)\n- You need custom button layouts or non-standard variants\n- You're building highly specialized forms\n\n## Getting started\n\n### Import\n\n```tsx\nimport { FormActionBar, type FormActionBarProps } from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\nProvide `onSave` and `onCancel` handlers — labels come from i18n defaults.\n\n```jsx live-dev\nconst App = () => (\n  <FormActionBar\n    onSave={() => console.log(\"Save pressed\")}\n    onCancel={() => console.log(\"Cancel pressed\")}\n  />\n);\n```\n\n## Usage examples\n\n### With delete action\n\nProvide `onDelete` to render a destructive delete button at the start of the\ngroup.\n\n```jsx live-dev\nconst App = () => (\n  <FormActionBar\n    onSave={() => console.log(\"Save\")}\n    onCancel={() => console.log(\"Cancel\")}\n    onDelete={() => console.log(\"Delete\")}\n  />\n);\n```\n\n### Disabled save\n\nDisable the save button while the form has validation errors or no pending\nchanges.\n\n```jsx live-dev\nconst App = () => (\n  <FormActionBar\n    onSave={() => console.log(\"Save\")}\n    onCancel={() => console.log(\"Cancel\")}\n    isSaveDisabled\n  />\n);\n```\n\n### Saving state\n\nShow a loading indicator inside the save button and disable all buttons while\nthe save is in flight.\n\n```jsx live-dev\nconst App = () => (\n  <FormActionBar\n    onSave={() => {}}\n    onCancel={() => {}}\n    onDelete={() => {}}\n    isSaveLoading\n  />\n);\n```\n\n### Deleting state\n\nThe delete button has its own loading state for destructive operations.\n\n```jsx live-dev\nconst App = () => (\n  <FormActionBar\n    onSave={() => {}}\n    onCancel={() => {}}\n    onDelete={() => {}}\n    isDeleteLoading\n  />\n);\n```\n\n### Custom labels\n\nOverride any of the default labels with `saveLabel`, `cancelLabel`,\n`deleteLabel`. When provided, these bypass the i18n defaults.\n\n```jsx live-dev\nconst App = () => (\n  <FormActionBar\n    onSave={() => {}}\n    onCancel={() => {}}\n    onDelete={() => {}}\n    saveLabel=\"Publish\"\n    cancelLabel=\"Discard\"\n    deleteLabel=\"Archive\"\n  />\n);\n```\n\n## Use inside footers\n\nFormActionBar is designed to drop into any footer slot.\n\n```tsx\n<DefaultPage.Footer>\n  <FormActionBar onSave={...} onCancel={...} />\n</DefaultPage.Footer>\n\n<ModalPage.Footer>\n  <FormActionBar onSave={...} onCancel={...} cancelSlot=\"close\" />\n</ModalPage.Footer>\n\n<Drawer.Footer>\n  <FormActionBar onSave={...} onCancel={...} onDelete={...} />\n</Drawer.Footer>\n\n<Dialog.Footer>\n  <FormActionBar onSave={...} onCancel={...} />\n</Dialog.Footer>\n```\n\n## Accessibility\n\n- The `Group` wrapping the buttons has an `aria-label` (defaults to \"Form\n  actions\", overridable via the `aria-label` prop)\n- All buttons are fully keyboard accessible via `Tab` / `Shift+Tab`\n- Buttons are disabled (not just visually) while a loading state is active, so\n  keyboard and screen-reader users get the same signal as sighted users\n- Button order follows a left-to-right reading order: destructive on the\n  start, dismissive in the middle, confirming on the end\n\n## API reference\n\n<PropsTable id=\"FormActionBar\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your integration of FormActionBar\ninside a form. The component's own behavior is already tested by Nimbus.\n\n### Verify callbacks\n\n```tsx\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { FormActionBar } from \"@commercetools/nimbus\";\n\nit(\"submits the form when save is pressed\", async () => {\n  const user = userEvent.setup();\n  const handleSave = vi.fn();\n\n  render(<FormActionBar onSave={handleSave} onCancel={() => {}} />);\n\n  await user.click(screen.getByRole(\"button\", { name: /save/i }));\n  expect(handleSave).toHaveBeenCalledTimes(1);\n});\n```\n\n### Verify delete button visibility\n\n```tsx\nit(\"hides the delete button when onDelete is not provided\", () => {\n  render(<FormActionBar onSave={() => {}} onCancel={() => {}} />);\n\n  expect(\n    screen.queryByRole(\"button\", { name: /delete/i })\n  ).not.toBeInTheDocument();\n});\n```\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-actions-formactionbar--docs)\n- [Button Component](/components/inputs/button)\n- [Group Component](/components/layout/group)\n",
+      "toc": [
+        {
+          "value": "Comparison: pattern vs manual composition",
+          "href": "#comparison-pattern-vs-manual-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": "With delete action",
+          "href": "#with-delete-action",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled save",
+          "href": "#disabled-save",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Saving state",
+          "href": "#saving-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Deleting state",
+          "href": "#deleting-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom labels",
+          "href": "#custom-labels",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Use inside footers",
+          "href": "#use-inside-footers",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Verify callbacks",
+          "href": "#verify-callbacks",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Verify delete button visibility",
+          "href": "#verify-delete-button-visibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}