@commercetools/nimbus-mcp 3.3.0 → 3.5.0

package/data/docs/routes/components-feedback-skeletoncircle.json

@@ -0,0 +1,429 @@
+{
+  "meta": {
+    "id": "Components-SkeletonCircle",
+    "title": "SkeletonCircle",
+    "exportName": "SkeletonCircle",
+    "description": "A circular loading placeholder sized to the Avatar scale, for avatars and icons.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/skeleton/derivatives/skeleton-circle/skeleton-circle.mdx",
+    "menu": [
+      "Components",
+      "Feedback",
+      "SkeletonCircle"
+    ],
+    "route": "components/feedback/skeletoncircle",
+    "tags": [
+      "component",
+      "skeleton",
+      "loading",
+      "placeholder",
+      "feedback",
+      "circle",
+      "avatar"
+    ],
+    "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": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Custom dimension",
+        "href": "#custom-dimension",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Inline default",
+        "href": "#inline-default",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Guidelines",
+        "href": "#guidelines",
+        "depth": 2,
+        "numbering": [
+          1,
+          3
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Best practices",
+        "href": "#best-practices",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "When to use",
+        "href": "#when-to-use",
+        "depth": 3,
+        "numbering": [
+          1,
+          3,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\n`SkeletonCircle` is a circular loading placeholder for avatars, user icons, and\ncircular thumbnails. Its `size` prop is aligned with the Avatar scale, so it can\nstand in for an `Avatar` at the same dimensions while the image loads — keeping\nthe layout stable during the transition.\n\n`SkeletonCircle` is part of the Skeleton family, a convenience wrapper over\n[Skeleton](/components/feedback/skeleton) with `shape=\"circle\"`. For rectangular\nblocks use `Skeleton`; for paragraphs of text use\n[SkeletonText](/components/feedback/skeletontext).\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)\n\n## Variables\n\nGet familiar with the features.\n\n### Size\n\nUse the avatar-aligned `size` prop to match an `Avatar`: `2xs` (24 px), `xs`\n(32 px), or `md` (40 px). The value applies equally to width and height.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <SkeletonCircle size=\"2xs\" />\n    <SkeletonCircle size=\"xs\" />\n    <SkeletonCircle size=\"md\" />\n  </Stack>\n)\n```\n\n### Custom dimension\n\nFor a size outside the Avatar scale, pass `boxSize` (a spacing token or CSS\nvalue). It sets both width and height, keeping the circle perfectly round.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <SkeletonCircle boxSize=\"1600\" />\n    <SkeletonCircle boxSize=\"4800\" />\n    <SkeletonCircle boxSize=\"80px\" />\n  </Stack>\n)\n```\n\n### Inline default\n\nWith neither `size` nor `boxSize` set, `SkeletonCircle` defaults to a `1em`\ncircle that matches the current line height — handy for a placeholder icon\nsitting inline next to text.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"200\" alignItems=\"center\">\n    <SkeletonCircle />\n    <Text>Loading inline label…</Text>\n  </Stack>\n)\n```\n\n## Guidelines\n\n### Best practices\n\n- When standing in for an `Avatar`, use the matching `size` value so the\n  placeholder and the loaded avatar occupy exactly the same space.\n- Reach for `boxSize` only when the circle sits outside the Avatar scale;\n  otherwise prefer the named `size` for consistency.\n- Pair `SkeletonCircle` with [SkeletonText](/components/feedback/skeletontext)\n  to build avatar-plus-text loading rows.\n\n### When to use\n\n> [!TIP]\\\n> Use SkeletonCircle when:\n- You are loading an avatar, user icon, or circular thumbnail\n- You want the placeholder to match the Avatar size scale\n- A row or card pairs a circular image with adjacent text\n\n> [!CAUTION]\\\n> When NOT to use SkeletonCircle:\n- For rectangular content such as images or cards — use\n  [Skeleton](/components/feedback/skeleton) instead\n- For paragraphs of text — use\n  [SkeletonText](/components/feedback/skeletontext)\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\n`SkeletonCircle` is a circular loading placeholder for avatars, user icons, and\ncircular thumbnails. Its `size` prop is aligned with the Avatar scale, so it can\nstand in for an `Avatar` at the same dimensions while the image loads — keeping\nthe layout stable during the transition.\n\n`SkeletonCircle` is part of the Skeleton family, a convenience wrapper over\n[Skeleton](/components/feedback/skeleton) with `shape=\"circle\"`. For rectangular\nblocks use `Skeleton`; for paragraphs of text use\n[SkeletonText](/components/feedback/skeletontext).\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)\n\n## Variables\n\nGet familiar with the features.\n\n### Size\n\nUse the avatar-aligned `size` prop to match an `Avatar`: `2xs` (24 px), `xs`\n(32 px), or `md` (40 px). The value applies equally to width and height.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <SkeletonCircle size=\"2xs\" />\n    <SkeletonCircle size=\"xs\" />\n    <SkeletonCircle size=\"md\" />\n  </Stack>\n)\n```\n\n### Custom dimension\n\nFor a size outside the Avatar scale, pass `boxSize` (a spacing token or CSS\nvalue). It sets both width and height, keeping the circle perfectly round.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <SkeletonCircle boxSize=\"1600\" />\n    <SkeletonCircle boxSize=\"4800\" />\n    <SkeletonCircle boxSize=\"80px\" />\n  </Stack>\n)\n```\n\n### Inline default\n\nWith neither `size` nor `boxSize` set, `SkeletonCircle` defaults to a `1em`\ncircle that matches the current line height — handy for a placeholder icon\nsitting inline next to text.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"200\" alignItems=\"center\">\n    <SkeletonCircle />\n    <Text>Loading inline label…</Text>\n  </Stack>\n)\n```\n\n## Guidelines\n\n### Best practices\n\n- When standing in for an `Avatar`, use the matching `size` value so the\n  placeholder and the loaded avatar occupy exactly the same space.\n- Reach for `boxSize` only when the circle sits outside the Avatar scale;\n  otherwise prefer the named `size` for consistency.\n- Pair `SkeletonCircle` with [SkeletonText](/components/feedback/skeletontext)\n  to build avatar-plus-text loading rows.\n\n### When to use\n\n> [!TIP]\\\n> Use SkeletonCircle when:\n- You are loading an avatar, user icon, or circular thumbnail\n- You want the placeholder to match the Avatar size scale\n- A row or card pairs a circular image with adjacent text\n\n> [!CAUTION]\\\n> When NOT to use SkeletonCircle:\n- For rectangular content such as images or cards — use\n  [Skeleton](/components/feedback/skeleton) instead\n- For paragraphs of text — use\n  [SkeletonText](/components/feedback/skeletontext)\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": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom dimension",
+          "href": "#custom-dimension",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Inline default",
+          "href": "#inline-default",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "When to use",
+          "href": "#when-to-use",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { SkeletonCircle, type SkeletonCircleProps } from '@commercetools/nimbus';\n```\n\n`SkeletonCircle` is a convenience wrapper over\n[Skeleton](/components/feedback/skeleton) with `shape=\"circle\"`. For rectangular\nblocks use `Skeleton`; for paragraphs use\n[SkeletonText](/components/feedback/skeletontext).\n\n### Basic usage\n\n`SkeletonCircle` renders a circular placeholder. Use the avatar-aligned `size`\nprop (`\"2xs\"` / `\"xs\"` / `\"md\"`) to stand in for an `Avatar`.\n\n```jsx live-dev\nconst App = () => (\n  <SkeletonCircle size=\"md\" />\n)\n```\n\n## Usage examples\n\n### Avatar-aligned sizes\n\nThe `size` prop is aligned with the `Avatar` size scale — `2xs` = 24 px,\n`xs` = 32 px, `md` = 40 px — and applies equally to width and height, so the\ncircle stays round.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <SkeletonCircle size=\"2xs\" />\n    <SkeletonCircle size=\"xs\" />\n    <SkeletonCircle size=\"md\" />\n  </Stack>\n)\n```\n\n### Custom dimension with `boxSize`\n\nFor a dimension outside the Avatar scale, pass `boxSize` (a spacing token or CSS\nvalue) instead of `size`. `width` and `height` are intentionally omitted from\nthe props in favor of `size`/`boxSize`, so the placeholder can never be\nnon-circular. With neither set, it defaults to a `1em` circle useful inline next\nto text.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <SkeletonCircle />\n    <SkeletonCircle boxSize=\"1600\" />\n    <SkeletonCircle boxSize=\"80px\" />\n  </Stack>\n)\n```\n\n### Conditional rendering (standalone pattern)\n\nLike the rest of the family, `SkeletonCircle` has no `isLoaded` prop. Render it\nwhile loading and swap it for the real avatar with conditional rendering.\n\n```jsx live-dev\nconst App = () => {\n  const [isLoading, setIsLoading] = React.useState(true);\n\n  return (\n    <Stack gap=\"400\">\n      <Button onPress={() => setIsLoading(v => !v)}>Toggle loading</Button>\n      <div aria-busy={isLoading}>\n        {isLoading ? (\n          <SkeletonCircle size=\"md\" />\n        ) : (\n          <Avatar size=\"md\" firstName=\"Ada\" lastName=\"Lovelace\" />\n        )}\n      </div>\n    </Stack>\n  )\n}\n```\n\n## Component requirements\n\n### Accessibility\n\n`SkeletonCircle` is **decorative by default** — it renders with\n`aria-hidden=\"true\"` so screen readers skip over it.\n\nTo communicate loading state to assistive technology, set `aria-busy=\"true\"` on\nthe **container** that wraps the skeleton region, then clear it and render the\nreal content once loading completes.\n\n```tsx\n<div aria-busy={isLoading} aria-label=\"User avatar\">\n  {isLoading ? (\n    <SkeletonCircle size=\"md\" />\n  ) : (\n    <Avatar size=\"md\" firstName={user.firstName} lastName={user.lastName} />\n  )}\n</div>\n```\n\nAnnounce the loading region on the wrapping container rather than labelling the\nskeleton itself — see [Skeleton](/components/feedback/skeleton) for the full\nrationale.\n\n#### Reduced motion\n\nWhen the user has enabled `prefers-reduced-motion: reduce`, the animation is\nautomatically disabled regardless of the `animation` prop value. No additional\nconfiguration is required.\n\n#### Keyboard navigation\n\n`SkeletonCircle` is non-interactive and decorative. It does not receive focus or\nsupport keyboard interaction.\n\n## API reference\n\n<PropsTable id=\"SkeletonCircle\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using SkeletonCircle 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\n\nRender a `SkeletonCircle` and confirm it is present; the circle is decorative (`aria-hidden`) by default, so assistive technology skips it.\n\n```tsx\nimport { useState } from \"react\";\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  SkeletonCircle,\n  Stack,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"SkeletonCircle - Basic rendering\", () => {\n  it(\"renders a decorative circular placeholder\", () => {\n    render(\n      <NimbusProvider>\n        <SkeletonCircle data-testid=\"skeleton-circle\" size=\"md\" />\n      </NimbusProvider>\n    );\n\n    const circle = screen.getByTestId(\"skeleton-circle\");\n    expect(circle).toBeInTheDocument();\n    expect(circle).toHaveAttribute(\"aria-hidden\", \"true\");\n  });\n});\n```\n\n### Avatar-aligned Sizes\n\nRender the avatar-aligned `size` values (`2xs`, `xs`, `md`) that let a SkeletonCircle stand in for an `Avatar` at the same dimensions.\n\n```tsx\nimport { useState } from \"react\";\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  SkeletonCircle,\n  Stack,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"SkeletonCircle - Avatar-aligned sizes\", () => {\n  it(\"renders each avatar-aligned size\", () => {\n    render(\n      <NimbusProvider>\n        <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n          <SkeletonCircle data-testid=\"circle-2xs\" size=\"2xs\" />\n          <SkeletonCircle data-testid=\"circle-xs\" size=\"xs\" />\n          <SkeletonCircle data-testid=\"circle-md\" size=\"md\" />\n        </Stack>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByTestId(\"circle-2xs\")).toBeInTheDocument();\n    expect(screen.getByTestId(\"circle-xs\")).toBeInTheDocument();\n    expect(screen.getByTestId(\"circle-md\")).toBeInTheDocument();\n  });\n});\n```\n\n### Standalone Loading Pattern\n\nThe recommended way to use SkeletonCircle: render the circle while an avatar is loading, then swap in the real image with conditional rendering — SkeletonCircle has no `isLoaded` prop, so the consumer owns the loading state.\n\n```tsx\nimport { useState } from \"react\";\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport {\n  SkeletonCircle,\n  Stack,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"SkeletonCircle - Standalone loading pattern\", () => {\n  /**\n   * A representative consumer component: show a circular placeholder while\n   * `isLoading`, then render the real avatar image once loading completes.\n   */\n  function UserAvatar({ isLoading }: { isLoading: boolean }) {\n    return isLoading ? (\n      <SkeletonCircle size=\"md\" />\n    ) : (\n      <img src=\"/avatar.png\" alt=\"Ada Lovelace\" width={40} height={40} />\n    );\n  }\n\n  it(\"shows a circular placeholder while loading, then the real avatar\", async () => {\n    const Example = () => {\n      const [isLoading, setIsLoading] = useState(true);\n      return (\n        <Stack gap=\"400\">\n          <UserAvatar isLoading={isLoading} />\n          <Button onPress={() => setIsLoading(false)}>Finish loading</Button>\n        </Stack>\n      );\n    };\n\n    render(\n      <NimbusProvider>\n        <Example />\n      </NimbusProvider>\n    );\n\n    // While loading: real avatar is absent.\n    expect(screen.queryByAltText(\"Ada Lovelace\")).toBeNull();\n\n    await userEvent.click(\n      screen.getByRole(\"button\", { name: \"Finish loading\" })\n    );\n\n    // After loading: real avatar is present.\n    expect(screen.getByAltText(\"Ada Lovelace\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-skeleton--docs)\n- [Skeleton](/components/feedback/skeleton)\n- [SkeletonText](/components/feedback/skeletontext)\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": "Avatar-aligned sizes",
+          "href": "#avatar-aligned-sizes",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom dimension with boxSize",
+          "href": "#custom-dimension-with-boxsize",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Conditional rendering (standalone pattern)",
+          "href": "#conditional-rendering-standalone-pattern",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            3,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Reduced motion",
+          "href": "#reduced-motion",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            3,
+            1,
+            2
+          ],
+          "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": "Basic Rendering",
+          "href": "#basic-rendering",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Avatar-aligned Sizes",
+          "href": "#avatar-aligned-sizes-1",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Standalone Loading Pattern",
+          "href": "#standalone-loading-pattern",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}