@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/components-layout-separator.json

@@ -0,0 +1,461 @@
+{
+  "meta": {
+    "id": "Components-Separator",
+    "title": "Separator",
+    "exportName": "Separator",
+    "description": "A separator is a visual or semantic line that groups and divides content, establishing rhythm and hierarchy within a layout.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/separator/separator.mdx",
+    "menu": [
+      "Components",
+      "Layout",
+      "Separator"
+    ],
+    "route": "components/layout/separator",
+    "tags": [
+      "component",
+      "divider",
+      "separator",
+      "line",
+      "section"
+    ],
+    "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": "Variables",
+        "href": "#variables",
+        "depth": 2,
+        "numbering": [
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Label options",
+        "href": "#label-options",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Horizontal",
+        "href": "#horizontal",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Vertical",
+        "href": "#vertical",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Supports radix colors",
+        "href": "#supports-radix-colors",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          3
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nSeparators enhance clarity by visually breaking up content. They can be\nhorizontal or vertical.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=6041-25167)\n\n## Variables\n\nGet familiar with the features.\n\n### Label options\n\n#### Horizontal\n\nHorizontal separators can be used to divide content or tools. It can span the\nentire page width or small areas.\n\n```jsx live\nconst App = () => (\n  <Box width=\"1600\">\n    <Separator />\n  </Box>\n)\n```\n\n#### Vertical\n\nVertical separators can be used to divide columns of content or tools.\n\n```jsx live\nconst App = () => (\n  <Box height=\"1600\">\n    <Separator orientation=\"vertical\" />\n  </Box>\n)\n```\n\n#### Supports radix colors\n\nThe default color is `neutral` but can be customized with supported token\ncolors.\n\n```jsx live\nconst App = () => {\n  const customColors = ['slate', 'positive', 'teal', 'pink', 'mint'];\n\n return (\n    <Flex height=\"1600\" flexDirection=\"horizontal\" gap=\"200\">\n      {customColors.map((color) => (\n        <Separator key={color} orientation=\"vertical\" colorPalette={color} />\n      ))}\n    </Flex>\n  );\n}\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nSeparators enhance clarity by visually breaking up content. They can be\nhorizontal or vertical.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=6041-25167)\n\n## Variables\n\nGet familiar with the features.\n\n### Label options\n\n#### Horizontal\n\nHorizontal separators can be used to divide content or tools. It can span the\nentire page width or small areas.\n\n```jsx live\nconst App = () => (\n  <Box width=\"1600\">\n    <Separator />\n  </Box>\n)\n```\n\n#### Vertical\n\nVertical separators can be used to divide columns of content or tools.\n\n```jsx live\nconst App = () => (\n  <Box height=\"1600\">\n    <Separator orientation=\"vertical\" />\n  </Box>\n)\n```\n\n#### Supports radix colors\n\nThe default color is `neutral` but can be customized with supported token\ncolors.\n\n```jsx live\nconst App = () => {\n  const customColors = ['slate', 'positive', 'teal', 'pink', 'mint'];\n\n return (\n    <Flex height=\"1600\" flexDirection=\"horizontal\" gap=\"200\">\n      {customColors.map((color) => (\n        <Separator key={color} orientation=\"vertical\" colorPalette={color} />\n      ))}\n    </Flex>\n  );\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": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Label options",
+          "href": "#label-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Horizontal",
+          "href": "#horizontal",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Vertical",
+          "href": "#vertical",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Supports radix colors",
+          "href": "#supports-radix-colors",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nAccessibility ensures that digital content and functionality are usable by\neveryone, including people with disabilities, by addressing visual, auditory,\ncognitive, and physical limitations.\n\n```jsx live\nconst App = () => (\n  <Box width=\"1600\">\n    <Separator />\n  </Box>\n)\n```\n\n### Accessibility standards\n\n- **Role attribute:** The component applies `role=\"separator\"` to define it as a\n  non-focusable, decorative divider.\n- **Semantic separation:** Ensure separators genuinely aid in content\n  organization for all users, including those relying on assistive technologies.\n- **Visual contrast:** While decorative, ensure the separator has sufficient\n  contrast against its background to be perceivable by users with low vision,\n  aligning with WCAG 2.1 1.4.11 for non-text contrast (3:1 contrast ratio).\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Separator, type SeparatorProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation uses the default horizontal orientation:\n\n```jsx live-dev\nconst App = () => (\n  <Box>\n    <Box p=\"400\">Content above the separator</Box>\n    <Separator />\n    <Box p=\"400\">Content below the separator</Box>\n  </Box>\n)\n```\n\n## Usage examples\n\n### Orientation options\n\nThe Separator supports both horizontal and vertical orientations to divide content in different layouts:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"600\">\n    <Box>\n      <Text fontSize=\"sm\" mb=\"300\">Horizontal separator (default)</Text>\n      <Box p=\"300\">Content above</Box>\n      <Separator orientation=\"horizontal\" />\n      <Box p=\"300\">Content below</Box>\n    </Box>\n\n    <Box>\n      <Text fontSize=\"sm\" mb=\"300\">Vertical separator</Text>\n      <Stack direction=\"row\" height=\"100px\" alignItems=\"center\">\n        <Box p=\"300\">Content left</Box>\n        <Separator orientation=\"vertical\" />\n        <Box p=\"300\">Content right</Box>\n      </Stack>\n    </Box>\n  </Stack>\n)\n```\n\n**Orientation differences:**\n- `orientation=\"horizontal\"`: Creates a full-width horizontal divider (default)\n- `orientation=\"vertical\"`: Creates a full-height vertical divider (requires parent with defined height)\n\n## Component requirements\n\n## Accessibility\n\nThe Separator component handles accessibility requirements internally using React Aria:\n\n- Automatically applies `role=\"separator\"` for screen readers\n- Sets `aria-orientation` when orientation is `\"vertical\"` (horizontal is the default and doesn't require explicit ARIA)\n- Non-focusable by default (separators are presentational elements)\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-separator\";\n\nexport const Example = () => (\n  <Separator id={PERSISTENT_ID} />\n);\n```\n\n#### Keyboard navigation\n\nThe Separator component is a presentational element and does not support keyboard interaction. It exists solely to provide visual division between content sections.\n\n## API reference\n\n<PropsTable id=\"Separator\" />\n\n## Common patterns\n\n### Dividing form sections\n\nUse horizontal separators to visually group related form fields:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"column\" gap=\"400\" width=\"400px\">\n    <Box>\n      <Text fontSize=\"md\" fontWeight=\"500\" mb=\"200\">Personal Information</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">Enter your basic details</Text>\n    </Box>\n\n    <Separator />\n\n    <Box>\n      <Text fontSize=\"md\" fontWeight=\"500\" mb=\"200\">Contact Details</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">How can we reach you?</Text>\n    </Box>\n\n    <Separator />\n\n    <Box>\n      <Text fontSize=\"md\" fontWeight=\"500\" mb=\"200\">Preferences</Text>\n      <Text fontSize=\"sm\" color=\"neutral.11\">Customize your experience</Text>\n    </Box>\n  </Stack>\n)\n```\n\n### Toolbar dividers\n\nUse vertical separators within toolbars to organize actions into logical groups:\n\n```jsx live-dev\nconst App = () => (\n  <Toolbar aria-label=\"Text formatting\">\n    <ToggleButtonGroup.Root selectionMode=\"multiple\" defaultSelectedKeys={[\"bold\"]}>\n      <IconToggleButton id=\"bold\" size=\"xs\" variant=\"ghost\" aria-label=\"Bold\">\n        <Icons.FormatBold />\n      </IconToggleButton>\n      <IconToggleButton id=\"italic\" size=\"xs\" variant=\"ghost\" aria-label=\"Italic\">\n        <Icons.FormatItalic />\n      </IconToggleButton>\n      <IconToggleButton id=\"underline\" size=\"xs\" variant=\"ghost\" aria-label=\"Underline\">\n        <Icons.FormatUnderlined />\n      </IconToggleButton>\n    </ToggleButtonGroup.Root>\n\n    <Separator orientation=\"vertical\" />\n\n    <ToggleButtonGroup.Root selectionMode=\"single\" defaultSelectedKeys={[\"left\"]}>\n      <IconToggleButton id=\"left\" size=\"xs\" variant=\"ghost\" aria-label=\"Align Left\">\n        <Icons.FormatAlignLeft />\n      </IconToggleButton>\n      <IconToggleButton id=\"center\" size=\"xs\" variant=\"ghost\" aria-label=\"Align Center\">\n        <Icons.FormatAlignCenter />\n      </IconToggleButton>\n      <IconToggleButton id=\"right\" size=\"xs\" variant=\"ghost\" aria-label=\"Align Right\">\n        <Icons.FormatAlignRight />\n      </IconToggleButton>\n    </ToggleButtonGroup.Root>\n\n    <Separator orientation=\"vertical\" />\n\n    <ToggleButtonGroup.Root selectionMode=\"single\">\n      <IconToggleButton id=\"bulleted\" size=\"xs\" variant=\"ghost\" aria-label=\"Bulleted List\">\n        <Icons.FormatListBulleted />\n      </IconToggleButton>\n      <IconToggleButton id=\"numbered\" size=\"xs\" variant=\"ghost\" aria-label=\"Numbered List\">\n        <Icons.FormatListNumbered />\n      </IconToggleButton>\n    </ToggleButtonGroup.Root>\n  </Toolbar>\n)\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Separator within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the Separator component renders with expected accessibility attributes\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Separator, Box, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Separator - Basic rendering\", () => {\n  it(\"renders with separator role\", () => {\n    render(\n      <NimbusProvider>\n        <Separator data-testid=\"separator-test\" />\n      </NimbusProvider>\n    );\n\n    const separator = screen.getByTestId(\"separator-test\");\n    expect(separator).toHaveAttribute(\"role\", \"separator\");\n  });\n\n  it(\"renders horizontal separator by default\", () => {\n    render(\n      <NimbusProvider>\n        <Separator data-testid=\"separator-horizontal\" />\n      </NimbusProvider>\n    );\n\n    const separator = screen.getByTestId(\"separator-horizontal\");\n    // Horizontal is default, so aria-orientation is not set\n    expect(separator).not.toHaveAttribute(\"aria-orientation\");\n  });\n\n  it(\"renders vertical separator with aria-orientation\", () => {\n    render(\n      <NimbusProvider>\n        <Separator orientation=\"vertical\" data-testid=\"separator-vertical\" />\n      </NimbusProvider>\n    );\n\n    const separator = screen.getByTestId(\"separator-vertical\");\n    expect(separator).toHaveAttribute(\"aria-orientation\", \"vertical\");\n  });\n});\n```\n\n### Layout Integration Tests\n\nTest Separator integration with common layout patterns\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Separator, Box, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Separator - Layout integration\", () => {\n  it(\"renders within content sections\", () => {\n    render(\n      <NimbusProvider>\n        <Box>\n          <Box data-testid=\"content-above\">Content above</Box>\n          <Separator data-testid=\"separator-divider\" />\n          <Box data-testid=\"content-below\">Content below</Box>\n        </Box>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"content-above\")).toBeInTheDocument();\n    expect(screen.getByTestId(\"separator-divider\")).toBeInTheDocument();\n    expect(screen.getByTestId(\"content-below\")).toBeInTheDocument();\n  });\n});\n```\n\n### Accessibility Tests\n\nVerify accessibility attributes and non-interactive behavior\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { Separator, Box, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Separator - Accessibility\", () => {\n  it(\"is not focusable\", () => {\n    render(\n      <NimbusProvider>\n        <Separator data-testid=\"separator-non-focusable\" />\n      </NimbusProvider>\n    );\n\n    const separator = screen.getByTestId(\"separator-non-focusable\");\n    // Separators are presentational and should not be in the tab order\n    expect(separator).not.toHaveAttribute(\"tabindex\");\n  });\n\n  it(\"supports custom id for analytics\", () => {\n    const PERSISTENT_ID = \"analytics-separator\";\n\n    render(\n      <NimbusProvider>\n        <Separator id={PERSISTENT_ID} />\n      </NimbusProvider>\n    );\n\n    const separator = screen.getByRole(\"separator\");\n    expect(separator).toHaveAttribute(\"id\", PERSISTENT_ID);\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-separator--docs)\n- [React Aria Separator](https://react-spectrum.adobe.com/react-aria/useSeparator.html)\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": "Orientation options",
+          "href": "#orientation-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Dividing form sections",
+          "href": "#dividing-form-sections",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Toolbar dividers",
+          "href": "#toolbar-dividers",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Layout Integration Tests",
+          "href": "#layout-integration-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility Tests",
+          "href": "#accessibility-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nDesign guidelines offer a set of standardized rules and recommendations that\nensure consistency, usability, and accessibility across all design elements and\ninteractions.\n\n### Best practices\n\n- **Be subtle:** Separators should be noticeable but not visually jarring.\n- **Prioritize white space:** Use separators only when white space alone is\n  insufficient to define content groups.\n- **Use sparingly:** Overuse of separators creates visual noise and diminishes\n  their impact.\n- **Place logically:** Position separators to reinforce content relationships\n  and hierarchy.\n\n### Usage\n\nSeparators help organize content and guide the user's eye.\n\n> [!TIP]\\\n> When to use\n\n- Separate distinct sections of content on a page.\n- Divide items in a list, especially when items are similar.\n- Group related components within a panel or dialog.\n- Separate elements in a toolbar or navigation menu.\n- Indicate where content might expand or collapse.\n\n> [!CAUTION]\\\n> When not to use\n\n- Separate individual items when white space provides sufficient visual\n  distinction.\n- Overuse within a small area, which can lead to visual clutter.\n- As a primary decorative element.\n- When a component already has inherent visual separation (e.g., card borders).\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}