@commercetools/nimbus-mcp 3.2.0 → 3.3.0

package/data/docs/routes/patterns-buttons-floating-action-button.json

@@ -0,0 +1,392 @@
+{
+  "meta": {
+    "id": "Patterns-FloatingActionButton",
+    "title": "Floating action button",
+    "exportName": "FloatingActionButton",
+    "description": "A circular, icon-only floating button for prominent single actions, such as opening a chat panel or triggering a primary workflow.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/patterns/buttons/floating-action-button/floating-action-button.mdx",
+    "menu": [
+      "Patterns",
+      "Buttons",
+      "Floating action button"
+    ],
+    "route": "patterns/buttons/floating-action-button",
+    "tags": [
+      "component",
+      "pattern",
+      "buttons",
+      "actions",
+      "floating"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Usage",
+        "href": "#usage",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "States",
+        "href": "#states",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Default",
+        "href": "#default",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Disabled",
+        "href": "#disabled",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Color palette",
+        "href": "#color-palette",
+        "depth": 2,
+        "numbering": [
+          1,
+          4
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=11090-7295",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nThe floating action button (FAB) is a 48px circular button used for a single,\nprominent action on the screen — such as opening an agent chat panel. It uses\nthe primary color palette and includes a drop shadow to float above page\ncontent.\n\nPositioning is the consumer's responsibility via style props. The Figma spec\nsuggests 32px from both the right and bottom edges as a starting point.\n\n### Resources\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=11090-7295)\n\n## Usage\n\n```jsx live\nconst App = () => {\n  return (\n    <FloatingActionButton aria-label=\"Open assistant\">\n      <Icons.Chat />\n    </FloatingActionButton>\n  );\n};\n```\n\n## States\n\n### Default\n\n```jsx live\nconst App = () => (\n  <FloatingActionButton aria-label=\"Open assistant\">\n    <Icons.Chat />\n  </FloatingActionButton>\n);\n```\n\n### Disabled\n\n```jsx live\nconst App = () => (\n  <FloatingActionButton aria-label=\"Open assistant\" isDisabled>\n    <Icons.Chat />\n  </FloatingActionButton>\n);\n```\n\n## Color palette\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <FloatingActionButton aria-label=\"Primary\" colorPalette=\"primary\">\n      <Icons.Chat />\n    </FloatingActionButton>\n    <FloatingActionButton aria-label=\"Critical\" colorPalette=\"critical\">\n      <Icons.Chat />\n    </FloatingActionButton>\n  </Stack>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThe floating action button (FAB) is a 48px circular button used for a single,\nprominent action on the screen — such as opening an agent chat panel. It uses\nthe primary color palette and includes a drop shadow to float above page\ncontent.\n\nPositioning is the consumer's responsibility via style props. The Figma spec\nsuggests 32px from both the right and bottom edges as a starting point.\n\n### Resources\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=11090-7295)\n\n## Usage\n\n```jsx live\nconst App = () => {\n  return (\n    <FloatingActionButton aria-label=\"Open assistant\">\n      <Icons.Chat />\n    </FloatingActionButton>\n  );\n};\n```\n\n## States\n\n### Default\n\n```jsx live\nconst App = () => (\n  <FloatingActionButton aria-label=\"Open assistant\">\n    <Icons.Chat />\n  </FloatingActionButton>\n);\n```\n\n### Disabled\n\n```jsx live\nconst App = () => (\n  <FloatingActionButton aria-label=\"Open assistant\" isDisabled>\n    <Icons.Chat />\n  </FloatingActionButton>\n);\n```\n\n## Color palette\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <FloatingActionButton aria-label=\"Primary\" colorPalette=\"primary\">\n      <Icons.Chat />\n    </FloatingActionButton>\n    <FloatingActionButton aria-label=\"Critical\" colorPalette=\"critical\">\n      <Icons.Chat />\n    </FloatingActionButton>\n  </Stack>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "States",
+          "href": "#states",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Default",
+          "href": "#default",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled",
+          "href": "#disabled",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Color palette",
+          "href": "#color-palette",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport {\n  FloatingActionButton,\n  type FloatingActionButtonProps,\n} from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nFloatingActionButton is a 48px circular icon-only button. `aria-label` is\nrequired since there is no visible text:\n\n```jsx live-dev\nconst App = () => (\n  <FloatingActionButton aria-label=\"Open assistant\">\n    <Icons.Chat />\n  </FloatingActionButton>\n)\n```\n\n## Usage examples\n\n### Disabled state\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <FloatingActionButton aria-label=\"Enabled\">\n      <Icons.Chat />\n    </FloatingActionButton>\n    <FloatingActionButton aria-label=\"Disabled\" isDisabled>\n      <Icons.Chat />\n    </FloatingActionButton>\n  </Stack>\n)\n```\n\n### Color palettes\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <FloatingActionButton aria-label=\"Primary action\" colorPalette=\"primary\">\n      <Icons.Chat />\n    </FloatingActionButton>\n    <FloatingActionButton aria-label=\"Critical action\" colorPalette=\"critical\">\n      <Icons.Chat />\n    </FloatingActionButton>\n  </Stack>\n)\n```\n\n### Press handling\n\n```jsx live-dev\nconst App = () => {\n  const [open, setOpen] = React.useState(false);\n\n  return (\n    <Stack direction=\"column\" gap=\"400\" alignItems=\"flex-start\">\n      <FloatingActionButton\n        aria-label={open ? 'Close panel' : 'Open panel'}\n        onPress={() => setOpen(!open)}\n      >\n        <Icons.Chat />\n      </FloatingActionButton>\n      <Text fontSize=\"sm\">{open ? 'Panel open' : 'Panel closed'}</Text>\n    </Stack>\n  );\n}\n```\n\n### Fixed positioning\n\nPositioning is the consumer's responsibility. The FAB accepts Chakra UI style\nprops directly, so `position`, `bottom`, and `right` can be passed as props\nrather than via the `style` attribute. The FAB has a default `z-index` of\n`banner` (1200), which keeps it floating above standard page content and sticky\nelements without displacing them:\n\n```jsx live-dev\nconst App = () => (\n  <FloatingActionButton\n    aria-label=\"Open assistant\"\n    position=\"fixed\"\n    bottom=\"800\"\n    right=\"800\"\n  >\n    <Icons.Chat />\n  </FloatingActionButton>\n)\n```\n\n### Overriding z-index\n\nIf your app uses a custom stacking context, pass `zIndex` directly as a prop:\n\n```jsx live-dev\nconst App = () => (\n  <FloatingActionButton\n    aria-label=\"Open assistant\"\n    zIndex={50}\n  >\n    <Icons.Chat />\n  </FloatingActionButton>\n)\n```\n\n## Accessibility\n\n`aria-label` is a **required** prop since the button contains only an icon.\nThe label should clearly describe the action.\n\n```tsx\n<FloatingActionButton aria-label=\"Open AI assistant\">\n  <Icons.Chat />\n</FloatingActionButton>\n```\n\nIf your use case requires tracking and analytics for this component, it is good\npractice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-floating-action-button\";\n\nexport const Example = () => (\n  <FloatingActionButton id={PERSISTENT_ID} aria-label=\"Open assistant\">\n    <Icons.Chat />\n  </FloatingActionButton>\n);\n```\n\n#### Keyboard navigation\n\n- `Tab` / `Shift+Tab`: Move focus to/from the button\n- `Enter` / `Space`: Activate the button\n\n## API reference\n\n<PropsTable id=\"FloatingActionButton\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using\nFloatingActionButton within your application. As the component's internal\nfunctionality is already tested by Nimbus, these patterns help you verify your\nintegration and application-specific logic.\n\n### Panel Toggle Integration\n\nUse FloatingActionButton to toggle application state such as a side panel\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { FloatingActionButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Add as AddIcon } from \"@commercetools/nimbus-icons\";\nimport { useState } from \"react\";\n\ndescribe(\"FloatingActionButton - Panel toggle integration\", () => {\n  const PanelToggle = () => {\n    const [open, setOpen] = useState(false);\n    return (\n      <NimbusProvider>\n        <FloatingActionButton\n          aria-label={open ? \"Close panel\" : \"Open panel\"}\n          onPress={() => setOpen((prev) => !prev)}\n          data-testid=\"fab\"\n        >\n          <AddIcon />\n        </FloatingActionButton>\n        {open && <div data-testid=\"panel\">Panel content</div>}\n      </NimbusProvider>\n    );\n  };\n\n  it(\"opens a panel on press\", async () => {\n    const user = userEvent.setup();\n    render(<PanelToggle />);\n\n    expect(screen.queryByTestId(\"panel\")).not.toBeInTheDocument();\n\n    await user.click(screen.getByTestId(\"fab\"));\n\n    expect(screen.getByTestId(\"panel\")).toBeInTheDocument();\n  });\n\n  it(\"toggles the panel closed on second press\", async () => {\n    const user = userEvent.setup();\n    render(<PanelToggle />);\n\n    await user.click(screen.getByTestId(\"fab\"));\n    expect(screen.getByTestId(\"panel\")).toBeInTheDocument();\n\n    await user.click(screen.getByTestId(\"fab\"));\n    expect(screen.queryByTestId(\"panel\")).not.toBeInTheDocument();\n  });\n\n  it(\"updates aria-label to reflect panel state\", async () => {\n    const user = userEvent.setup();\n    render(<PanelToggle />);\n\n    expect(\n      screen.getByRole(\"button\", { name: \"Open panel\" })\n    ).toBeInTheDocument();\n    await user.click(screen.getByRole(\"button\", { name: \"Open panel\" }));\n    expect(\n      screen.getByRole(\"button\", { name: \"Close panel\" })\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### Async Action Integration\n\nUse FloatingActionButton to trigger an async operation\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { FloatingActionButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Add as AddIcon } from \"@commercetools/nimbus-icons\";\nimport { useState } from \"react\";\n\ndescribe(\"FloatingActionButton - Async action integration\", () => {\n  it(\"triggers an async callback on press\", async () => {\n    const user = userEvent.setup();\n    const asyncAction = vi.fn().mockResolvedValue(undefined);\n\n    render(\n      <NimbusProvider>\n        <FloatingActionButton\n          aria-label=\"Save\"\n          onPress={asyncAction}\n          data-testid=\"fab\"\n        >\n          <AddIcon />\n        </FloatingActionButton>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByTestId(\"fab\"));\n\n    expect(asyncAction).toHaveBeenCalledTimes(1);\n  });\n\n  it(\"does not trigger callback when disabled\", async () => {\n    const user = userEvent.setup();\n    const asyncAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <FloatingActionButton\n          aria-label=\"Save\"\n          onPress={asyncAction}\n          isDisabled\n          data-testid=\"fab\"\n        >\n          <AddIcon />\n        </FloatingActionButton>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByTestId(\"fab\"));\n\n    expect(asyncAction).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Stacking Context\n\nThe FAB has a default z-index of \"banner\" (1200) so it floats above page\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { FloatingActionButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Add as AddIcon } from \"@commercetools/nimbus-icons\";\nimport { useState } from \"react\";\n\ndescribe(\"FloatingActionButton - Stacking context\", () => {\n  it(\"accepts a zIndex prop override for custom stacking contexts\", () => {\n    // zIndex is a Chakra style prop — applied via CSS class, not inline style.\n    // This test verifies the prop is accepted and the component renders correctly.\n    render(\n      <NimbusProvider>\n        <FloatingActionButton\n          aria-label=\"Open assistant\"\n          zIndex={50}\n          data-testid=\"fab\"\n        >\n          <AddIcon />\n        </FloatingActionButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"fab\")).toBeInTheDocument();\n  });\n});\n```\n\n### Analytics Tracking Integration\n\nUse a persistent id for analytics tracking\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { FloatingActionButton, NimbusProvider } from \"@commercetools/nimbus\";\nimport { Add as AddIcon } from \"@commercetools/nimbus-icons\";\nimport { useState } from \"react\";\n\ndescribe(\"FloatingActionButton - Analytics tracking integration\", () => {\n  it(\"renders with a persistent id for tracking\", () => {\n    const PERSISTENT_ID = \"main-fab-open-assistant\";\n\n    render(\n      <NimbusProvider>\n        <FloatingActionButton\n          id={PERSISTENT_ID}\n          aria-label=\"Open assistant\"\n          data-testid=\"fab\"\n        >\n          <AddIcon />\n        </FloatingActionButton>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"fab\")).toHaveAttribute(\"id\", PERSISTENT_ID);\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/patterns-buttons-floatingactionbutton--docs)\n- [React Aria Button](https://react-spectrum.adobe.com/react-aria/Button.html)\n- [ARIA Button Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/button/)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled state",
+          "href": "#disabled-state",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Color palettes",
+          "href": "#color-palettes",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Press handling",
+          "href": "#press-handling",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Fixed positioning",
+          "href": "#fixed-positioning",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Overriding z-index",
+          "href": "#overriding-z-index",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Panel Toggle Integration",
+          "href": "#panel-toggle-integration",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Async Action Integration",
+          "href": "#async-action-integration",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Stacking Context",
+          "href": "#stacking-context",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Analytics Tracking Integration",
+          "href": "#analytics-tracking-integration",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,58 @@
+{
+  "meta": {
+    "id": "Patterns-Buttons",
+    "title": "Buttons",
+    "description": "Pre-styled button patterns for prominent, single-purpose actions",
+    "order": 5,
+    "repoPath": "packages/nimbus/src/docs/patterns-buttons.mdx",
+    "menu": [
+      "Patterns",
+      "Buttons"
+    ],
+    "route": "patterns/buttons",
+    "tags": [
+      "patterns",
+      "buttons",
+      "actions"
+    ],
+    "toc": [
+      {
+        "value": "Available button patterns",
+        "href": "#available-button-patterns",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      }
+    ],
+    "icon": "SmartButton",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      }
+    ]
+  },
+  "mdx": "\n# Buttons\n\nButton pattern components wrap the base button components in small, opinionated APIs for common, high-visibility actions. Use them to get consistent styling and placement without re-deriving the defaults each time.\n\n## Available button patterns\n\n<CategoryOverview variant=\"list\" />\n</content>\n</invoke>\n",
+  "views": {
+    "overview": {
+      "mdx": "\n# Buttons\n\nButton pattern components wrap the base button components in small, opinionated APIs for common, high-visibility actions. Use them to get consistent styling and placement without re-deriving the defaults each time.\n\n## Available button patterns\n\n<CategoryOverview variant=\"list\" />\n</content>\n</invoke>\n",
+      "toc": [
+        {
+          "value": "Available button patterns",
+          "href": "#available-button-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}