@commercetools/nimbus-mcp 3.3.0 → 3.5.0

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

@@ -0,0 +1,417 @@
+{
+  "meta": {
+    "id": "Components-SkeletonText",
+    "title": "SkeletonText",
+    "exportName": "SkeletonText",
+    "description": "A stack of placeholder lines that approximates a paragraph of text while content loads.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/skeleton/derivatives/skeleton-text/skeleton-text.mdx",
+    "menu": [
+      "Components",
+      "Feedback",
+      "SkeletonText"
+    ],
+    "route": "components/feedback/skeletontext",
+    "tags": [
+      "component",
+      "skeleton",
+      "loading",
+      "placeholder",
+      "feedback",
+      "text"
+    ],
+    "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": "Line count",
+        "href": "#line-count",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Matching text size",
+        "href": "#matching-text-size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Last line width",
+        "href": "#last-line-width",
+        "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`SkeletonText` renders a stack of placeholder lines that stand in for a\nparagraph of text while it loads. The last line is narrower by default to mimic\na natural paragraph ending, and the lines are sized to the same vertical rhythm\nas the real text they replace — so the transition to loaded content stays\nsmooth.\n\n`SkeletonText` is part of the Skeleton family, built from\n[Skeleton](/components/feedback/skeleton) lines. For single blocks, images, or\ncustom shapes use `Skeleton` directly; for avatars and icons use\n[SkeletonCircle](/components/feedback/skeletoncircle).\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### Line count\n\nUse `lines` to set how many placeholder lines to render. Set the block's\n`width` to match the column the text will occupy.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"800\" width=\"600px\">\n    <SkeletonText lines={2} width=\"100%\" />\n    <SkeletonText lines={4} width=\"100%\" />\n  </Stack>\n)\n```\n\n### Matching text size\n\nSet `textStyle` (default `body`) so the placeholder lines match the size and\nline spacing of the text they stand in for — from small captions to large\nheadings. Each bar's height and the gaps between them resize together, keeping\nthe same vertical rhythm as real text of that style.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\" width=\"300px\">\n    <SkeletonText textStyle=\"caption\" />\n    <SkeletonText textStyle=\"body\" />\n    <SkeletonText textStyle=\"3xl\" lines={2} />\n  </Stack>\n)\n```\n\n### Last line width\n\nThe last line is narrower by default (`lastLineWidth=\"60%\"`) to mimic a\nparagraph ending. Adjust it to match the content, or set it to `\"100%\"` for a\njustified block.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"800\" width=\"600px\">\n    <SkeletonText lines={3} width=\"100%\" lastLineWidth=\"40%\" />\n    <SkeletonText lines={3} width=\"100%\" lastLineWidth=\"100%\" />\n  </Stack>\n)\n```\n\n## Guidelines\n\n### Best practices\n\n- Match `textStyle` to the text you are standing in for so the placeholder\n  occupies the same space as the loaded content and avoids layout shift.\n- Use `SkeletonText` for multi-line paragraphs; for a single heading or line,\n  the base `Skeleton` gives you more direct control over height and width.\n- Keep the line count realistic — approximating the real paragraph length keeps\n  the transition to loaded content smooth.\n\n### When to use\n\n> [!TIP]\\\n> Use SkeletonText when:\n- You are loading a paragraph, description, or block of running text\n- You want the placeholder to match a specific text style's size and rhythm\n- A detail panel or card contains several lines of text\n\n> [!CAUTION]\\\n> When NOT to use SkeletonText:\n- For a single line, heading, or non-text block — use\n  [Skeleton](/components/feedback/skeleton) instead\n- For circular content such as avatars — use\n  [SkeletonCircle](/components/feedback/skeletoncircle)\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\n`SkeletonText` renders a stack of placeholder lines that stand in for a\nparagraph of text while it loads. The last line is narrower by default to mimic\na natural paragraph ending, and the lines are sized to the same vertical rhythm\nas the real text they replace — so the transition to loaded content stays\nsmooth.\n\n`SkeletonText` is part of the Skeleton family, built from\n[Skeleton](/components/feedback/skeleton) lines. For single blocks, images, or\ncustom shapes use `Skeleton` directly; for avatars and icons use\n[SkeletonCircle](/components/feedback/skeletoncircle).\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### Line count\n\nUse `lines` to set how many placeholder lines to render. Set the block's\n`width` to match the column the text will occupy.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"800\" width=\"600px\">\n    <SkeletonText lines={2} width=\"100%\" />\n    <SkeletonText lines={4} width=\"100%\" />\n  </Stack>\n)\n```\n\n### Matching text size\n\nSet `textStyle` (default `body`) so the placeholder lines match the size and\nline spacing of the text they stand in for — from small captions to large\nheadings. Each bar's height and the gaps between them resize together, keeping\nthe same vertical rhythm as real text of that style.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"600\" width=\"300px\">\n    <SkeletonText textStyle=\"caption\" />\n    <SkeletonText textStyle=\"body\" />\n    <SkeletonText textStyle=\"3xl\" lines={2} />\n  </Stack>\n)\n```\n\n### Last line width\n\nThe last line is narrower by default (`lastLineWidth=\"60%\"`) to mimic a\nparagraph ending. Adjust it to match the content, or set it to `\"100%\"` for a\njustified block.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"800\" width=\"600px\">\n    <SkeletonText lines={3} width=\"100%\" lastLineWidth=\"40%\" />\n    <SkeletonText lines={3} width=\"100%\" lastLineWidth=\"100%\" />\n  </Stack>\n)\n```\n\n## Guidelines\n\n### Best practices\n\n- Match `textStyle` to the text you are standing in for so the placeholder\n  occupies the same space as the loaded content and avoids layout shift.\n- Use `SkeletonText` for multi-line paragraphs; for a single heading or line,\n  the base `Skeleton` gives you more direct control over height and width.\n- Keep the line count realistic — approximating the real paragraph length keeps\n  the transition to loaded content smooth.\n\n### When to use\n\n> [!TIP]\\\n> Use SkeletonText when:\n- You are loading a paragraph, description, or block of running text\n- You want the placeholder to match a specific text style's size and rhythm\n- A detail panel or card contains several lines of text\n\n> [!CAUTION]\\\n> When NOT to use SkeletonText:\n- For a single line, heading, or non-text block — use\n  [Skeleton](/components/feedback/skeleton) instead\n- For circular content such as avatars — use\n  [SkeletonCircle](/components/feedback/skeletoncircle)\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": "Line count",
+          "href": "#line-count",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Matching text size",
+          "href": "#matching-text-size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Last line width",
+          "href": "#last-line-width",
+          "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 { SkeletonText, type SkeletonTextProps } from '@commercetools/nimbus';\n```\n\n`SkeletonText` is built on [Skeleton](/components/feedback/skeleton). For single\nblocks use `Skeleton`; for circular placeholders see\n[SkeletonCircle](/components/feedback/skeletoncircle).\n\n### Basic usage\n\n`SkeletonText` renders a configurable number of placeholder lines to approximate\na paragraph. The last line is narrower by default (`lastLineWidth=\"60%\"`) to\nmimic a natural paragraph ending.\n\n```jsx live-dev\nconst App = () => (\n  <SkeletonText lines={4} width=\"300px\" />\n)\n```\n\n## Usage examples\n\n### Matching text size with `textStyle`\n\n`SkeletonText` accepts a `textStyle` prop (default `\"body\"`) that makes the\nplaceholder lines occupy the same vertical rhythm as real text of that style.\nEach line becomes a `1lh` line-box sized by the style, with a `0.75em`\n(≈ cap-height) bar centered in it — so the bar sits where real glyphs sit and the\npitch scales automatically: a `body` skeleton uses a 26 px line pitch, a `3xl`\nheading skeleton a 36 px pitch. Pass any Nimbus text style to match the content\nyou are standing in for.\n\n```jsx live-dev\nconst App = () => (\n  <Stack gap=\"600\" width=\"300px\">\n    <SkeletonText textStyle=\"caption\" />\n    <SkeletonText textStyle=\"body\" />\n    <SkeletonText textStyle=\"3xl\" lines={2} />\n  </Stack>\n)\n```\n\n### Conditional rendering (standalone pattern)\n\nLike the rest of the family, `SkeletonText` has no `isLoaded` prop. Render it\nwhile loading and swap it for the real text with conditional rendering.\n\n```jsx live-dev\nconst App = () => {\n  const [isLoading, setIsLoading] = React.useState(true);\n\n  return (\n    <Stack gap=\"400\" width=\"320px\">\n      <Button onPress={() => setIsLoading(v => !v)}>Toggle loading</Button>\n      <div aria-busy={isLoading}>\n        {isLoading ? (\n          <SkeletonText lines={3} width=\"100%\" />\n        ) : (\n          <Text>\n            A short product description that replaces the placeholder once the\n            data has finished loading.\n          </Text>\n        )}\n      </div>\n    </Stack>\n  )\n}\n```\n\n## Component requirements\n\n### Accessibility\n\n`SkeletonText` is **decorative by default** — its container and lines render\nwith `aria-hidden=\"true\"` so screen readers skip over them.\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<section aria-busy={isLoading} aria-label=\"Product description\">\n  {isLoading ? (\n    <SkeletonText lines={3} width=\"100%\" />\n  ) : (\n    <ProductDescription product={product} />\n  )}\n</section>\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 line animations\nare automatically disabled regardless of the `animation` prop value. No\nadditional configuration is required.\n\n#### Keyboard navigation\n\n`SkeletonText` is non-interactive and decorative. It does not receive focus or\nsupport keyboard interaction.\n\n## API reference\n\n<PropsTable id=\"SkeletonText\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using SkeletonText 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 `SkeletonText` block and confirm it renders one placeholder line per `lines`; the container 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  SkeletonText,\n  Stack,\n  Text,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"SkeletonText - Basic rendering\", () => {\n  it(\"renders one placeholder line per `lines`\", () => {\n    render(\n      <NimbusProvider>\n        <SkeletonText data-testid=\"skeleton-text\" lines={3} width=\"300px\" />\n      </NimbusProvider>\n    );\n\n    const container = screen.getByTestId(\"skeleton-text\");\n    expect(container).toBeInTheDocument();\n    expect(container).toHaveAttribute(\"aria-hidden\", \"true\");\n    // One Skeleton line is rendered for each of the three requested lines.\n    expect(container.children).toHaveLength(3);\n  });\n});\n```\n\n### Standalone Loading Pattern\n\nThe recommended way to use SkeletonText: render placeholder lines while the text is loading, then swap in the real paragraph with conditional rendering — SkeletonText 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  SkeletonText,\n  Stack,\n  Text,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"SkeletonText - Standalone loading pattern\", () => {\n  /**\n   * A representative consumer component: show placeholder lines while\n   * `isLoading`, then render the real description once loading completes.\n   */\n  function ProductDescription({ isLoading }: { isLoading: boolean }) {\n    return isLoading ? (\n      <SkeletonText lines={3} width=\"100%\" />\n    ) : (\n      <Text>\n        Wireless keyboard with a compact layout and long battery life.\n      </Text>\n    );\n  }\n\n  it(\"shows placeholder lines while loading, then the real text\", async () => {\n    const description =\n      \"Wireless keyboard with a compact layout and long battery life.\";\n\n    const Example = () => {\n      const [isLoading, setIsLoading] = useState(true);\n      return (\n        <Stack gap=\"400\" width=\"320px\">\n          <ProductDescription 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 text is absent.\n    expect(screen.queryByText(description)).toBeNull();\n\n    await userEvent.click(\n      screen.getByRole(\"button\", { name: \"Finish loading\" })\n    );\n\n    // After loading: real text is present.\n    expect(screen.getByText(description)).toBeInTheDocument();\n  });\n});\n```\n\n### Announcing Loading with aria-busy\n\nSkeletonText is decorative (`aria-hidden`), so it is not announced on its own; communicate the loading state to assistive technology by setting `aria-busy` on the surrounding container instead.\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  SkeletonText,\n  Stack,\n  Text,\n  Button,\n  NimbusProvider,\n} from \"@commercetools/nimbus\";\n\ndescribe(\"SkeletonText - Container aria-busy pattern\", () => {\n  it(\"announces loading state via aria-busy on the container\", () => {\n    render(\n      <NimbusProvider>\n        <section\n          data-testid=\"container\"\n          aria-busy={true}\n          aria-label=\"Product description\"\n        >\n          <SkeletonText lines={3} width=\"100%\" />\n        </section>\n      </NimbusProvider>\n    );\n\n    const container = screen.getByTestId(\"container\");\n    expect(container).toHaveAttribute(\"aria-busy\", \"true\");\n    expect(container).toHaveAttribute(\"aria-label\", \"Product description\");\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- [SkeletonCircle](/components/feedback/skeletoncircle)\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": "Matching text size with textStyle",
+          "href": "#matching-text-size-with-textstyle",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Conditional rendering (standalone pattern)",
+          "href": "#conditional-rendering-standalone-pattern",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "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": "Standalone Loading Pattern",
+          "href": "#standalone-loading-pattern",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Announcing Loading with aria-busy",
+          "href": "#announcing-loading-with-aria-busy",
+          "depth": 3,
+          "numbering": [
+            1,
+            5,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}