@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/data/docs/routes/components-feedback-loading-spinner.json

@@ -0,0 +1,415 @@
+{
+  "meta": {
+    "id": "Components-LoadingSpinner",
+    "title": "Loading spinner",
+    "exportName": "LoadingSpinner",
+    "description": "A circular visual indicator that displays the loading status of an ongoing process. It can represent either determinate or indeterminate progress.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/loading-spinner/loading-spinner.mdx",
+    "menu": [
+      "Components",
+      "Feedback",
+      "Loading spinner"
+    ],
+    "route": "components/feedback/loading-spinner",
+    "tags": [
+      "component",
+      "loading",
+      "spinner",
+      "progress"
+    ],
+    "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": "Visuals",
+        "href": "#visuals",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "On white background",
+        "href": "#on-white-background",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "On dark background",
+        "href": "#on-dark-background",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          2
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Size",
+        "href": "#size",
+        "depth": 3,
+        "numbering": [
+          1,
+          2,
+          2
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=5605-25451&m=dev",
+    "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\nA loading spinner's primary usage is to visually communicate to the user that a\nprocess is ongoing and that they need to wait. It indicates that the system is\nworking and prevents the user from thinking the application is frozen or\nunresponsive.\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=5605-25451&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visuals\n\n#### On white background\n\nMost common, this is the default spinner animation to be used on white\nbackgrounds.\n\n```jsx live\nconst App = () => <LoadingSpinner aria-label=\"Loading content\" />\n```\n\n#### On dark background\n\nThis is the default spinner animation to be used on dark backgrounds.\n\n```jsx live\nconst App = () => <Stack backgroundColor=\"neutral.8\"><LoadingSpinner aria-label=\"Loading content\" colorPalette=\"white\" /></Stack>\n```\n\n### Size\n\nLoading spinners have five sizes to choose from: large, medium, small, x-small,\nand 2x-small.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <LoadingSpinner size=\"lg\" aria-label=\"Large spinner\" />\n    <LoadingSpinner size=\"md\" aria-label=\"Medium spinner\" />\n    <LoadingSpinner size=\"sm\" aria-label=\"Small spinner\" />\n    <LoadingSpinner size=\"xs\" aria-label=\"Extra small spinner\" />\n    <LoadingSpinner size=\"2xs\" aria-label=\"Extra extra small spinner\" />\n  </Stack>\n)\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nA loading spinner's primary usage is to visually communicate to the user that a\nprocess is ongoing and that they need to wait. It indicates that the system is\nworking and prevents the user from thinking the application is frozen or\nunresponsive.\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=5605-25451&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visuals\n\n#### On white background\n\nMost common, this is the default spinner animation to be used on white\nbackgrounds.\n\n```jsx live\nconst App = () => <LoadingSpinner aria-label=\"Loading content\" />\n```\n\n#### On dark background\n\nThis is the default spinner animation to be used on dark backgrounds.\n\n```jsx live\nconst App = () => <Stack backgroundColor=\"neutral.8\"><LoadingSpinner aria-label=\"Loading content\" colorPalette=\"white\" /></Stack>\n```\n\n### Size\n\nLoading spinners have five sizes to choose from: large, medium, small, x-small,\nand 2x-small.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <LoadingSpinner size=\"lg\" aria-label=\"Large spinner\" />\n    <LoadingSpinner size=\"md\" aria-label=\"Medium spinner\" />\n    <LoadingSpinner size=\"sm\" aria-label=\"Small spinner\" />\n    <LoadingSpinner size=\"xs\" aria-label=\"Extra small spinner\" />\n    <LoadingSpinner size=\"2xs\" aria-label=\"Extra extra small spinner\" />\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": "Variables",
+          "href": "#variables",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visuals",
+          "href": "#visuals",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "On white background",
+          "href": "#on-white-background",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "On dark background",
+          "href": "#on-dark-background",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "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 = () => <LoadingSpinner aria-label=\"Loading data\" />;\n```\n\n### Accessibility standards\n\n- **Use an accessible label to provide context:** Always provide an `aria-label`\n  to describe what is loading.\n- **Hide the spinner from assistive technologies when it's not visible or in\n  use:** Use appropriate ARIA attributes to manage visibility.\n- **Announce a change in state to screen readers:** Update users on the loading\n  progress using live regions.\n- **Ensure the contrast ratio is at least 3:1 against the background:** Verify\n  color contrast meets accessibility standards.\n- **Use aria-label to describe the spinner:** Provide clear, concise\n  descriptions like \"Loading data\" or \"Processing request\".\n- **Do not rely on color alone to communicate information:** Use additional\n  visual cues beyond color.\n- **Provide a clear indication of what is loading or the action being\n  performed:** Be specific in your aria-label.\n- **Ensure the spinner has a valid HTML structure and role:** The component uses\n  `role=\"progressbar\"` by default.\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 { LoadingSpinner, type LoadingSpinnerProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe LoadingSpinner component indicates an ongoing process or indeterminate loading state.\n\n```jsx live-dev\nconst App = () => (\n  <LoadingSpinner />\n)\n```\n\n## Usage examples\n\n### Size options\n\nThe `size` prop controls the dimensions of the spinner to match your interface density. Available sizes are `2xs`, `xs`, `sm` (default), `md`, and `lg`.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <LoadingSpinner size=\"2xs\" />\n    <LoadingSpinner size=\"xs\" />\n    <LoadingSpinner size=\"sm\" />\n    <LoadingSpinner size=\"md\" />\n    <LoadingSpinner size=\"lg\" />\n  </Stack>\n)\n```\n\n### Visual variants\n\nThe `colorPalette` prop enables rendering a high-contrast loading spinner on light and dark backgrounds.\n\n- `primary`: The default color, suitable for light backgrounds.\n- `white`: Suitable for dark backgrounds or colored surfaces.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <LoadingSpinner colorPalette=\"primary\" margin=\"400\"/>\n    <LoadingSpinner colorPalette=\"white\" margin=\"400\" bgColor=\"black\" />\n  </Stack>\n)\n```\n\n## Component requirements\n\n## Accessibility\n\nThe LoadingSpinner uses `role=\"progressbar\"` and an indeterminate state by default.\n\nYou **must** ensure the spinner has an accessible label. The component provides a default localized label (\"Loading\"), but you should provide a more specific label when possible using `aria-label` or `aria-labelledby`.\n\n```tsx\n// Recommended: Specific label describing what is loading\n<LoadingSpinner aria-label=\"Loading order details\" />\n\n// Using aria-labelledby\n<h3 id=\"loading-heading\">Loading Users</h3>\n<LoadingSpinner aria-labelledby=\"loading-heading\" />\n```\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 = \"user-list-loading-spinner\";\n\nexport const UserList = () => (\n  <LoadingSpinner id={PERSISTENT_ID} />\n);\n```\n\n## API reference\n\n<PropsTable id=\"LoadingSpinner\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using LoadingSpinner 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 component renders with the expected accessibility attributes\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { LoadingSpinner, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"LoadingSpinner - Basic rendering\", () => {\n  it(\"renders with default accessibility attributes\", () => {\n    render(\n      <NimbusProvider>\n        <LoadingSpinner />\n      </NimbusProvider>\n    );\n\n    // Verify role and default label\n    const spinner = screen.getByRole(\"progressbar\");\n    expect(spinner).toBeInTheDocument();\n    expect(spinner).toHaveAttribute(\"aria-label\", \"Loading data\");\n  });\n\n  it(\"renders with a custom accessible label\", () => {\n    render(\n      <NimbusProvider>\n        <LoadingSpinner aria-label=\"Loading products\" />\n      </NimbusProvider>\n    );\n\n    expect(\n      screen.getByRole(\"progressbar\", { name: \"Loading products\" })\n    ).toBeInTheDocument();\n  });\n\n  it(\"renders with different sizes\", () => {\n    const { rerender } = render(\n      <NimbusProvider>\n        <LoadingSpinner size=\"sm\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"progressbar\")).toBeInTheDocument();\n\n    rerender(\n      <NimbusProvider>\n        <LoadingSpinner size=\"lg\" />\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"progressbar\")).toBeInTheDocument();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-loadingspinner--docs)\n- [React Aria ProgressBar](https://react-spectrum.adobe.com/react-aria/ProgressBar.html)\n\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": "Size options",
+          "href": "#size-options",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Visual variants",
+          "href": "#visual-variants",
+          "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": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nLoading spinner guidelines aim to provide clear and consistent visual feedback\nto users during processing delays, ensuring they understand the system is active\nand preventing frustration by indicating that they need to wait.\n\n### Best practices\n\n- **Appropriate placement:** Position the spinner close to the element or area\n  that's loading. For full-page loads, center the spinner on the screen. For\n  inline loading, place the spinner in the location of the content that will be\n  loading.\n- **Provide context:** If the loading time is expected to be lengthy, consider\n  adding a brief message like \"Loading...\" or \"Please wait...\" alongside the\n  spinner. For very long loading periods, consider adding a percentage bar, or\n  estimated time to let the user come back when ready.\n- **Responsive and smooth animation:** Ensure the spinner's animation is smooth\n  and doesn't lag or stutter.\n- **Accessibility:** Use ARIA attributes (e.g., aria-busy, aria-label) to\n  provide context for screen readers. If the loading time is excessive, provide\n  a way to cancel the loading process.\n- **Avoid overuse:** Use spinners only when necessary, such as during data\n  fetching or processing.\n- **Fallback options:** Have a fallback plan in case the loading action fails.\n  Display an error message, and provide a way for the user to retry.\n\n### Usage\n\n> [!TIP]\\\n> When to use\n\n- **Data is being fetched:** When your application is retrieving data from a\n  server or database, especially if it might take a noticeable amount of time.\n- **Processes are running:** During background operations, file uploads, or\n  complex calculations that cause a delay.\n- **Content is loading:** When new content is being loaded dynamically, such as\n  images, videos, or web pages.\n- **Actions are being processed:** After a user initiates an action, such as\n  submitting a form or saving data, and the system requires time to complete the\n  task.\n- **Any time a user action causes a delay:** When a user interacts with the UI\n  and there is a delay that could cause confusion or a perception of the UI\n  being broken.\n\n> [!CAUTION]\\\n> When not to use\n\n- **For extremely quick actions:** If an action completes in less than a few\n  hundred milliseconds, a spinner is unnecessary and can feel jarring or\n  distracting.\n- **For simple UI interactions:** Actions like toggling a switch, expanding a\n  menu, or simple animations shouldn't trigger a spinner.\n- **When the wait is unpredictable or excessively long:** If you can't provide\n  any indication of how long the wait will be, or if it might be excessively\n  long, consider alternative indicators with a cancel option or other help text.\n- **When it creates unnecessary visual clutter:** Overusing spinners can make\n  the UI feel busy and distracting.\n- **When a more subtle visual cue is sufficient:** For very short delays, a\n  change in cursor, a slight fade, or a brief message might be more appropriate.\n\n### Loading spinner within elements\n\nWhen showing the process of content loading you may add the loading spinner\nwithin elements.\n\n> [!TIP]\\\n> **Do**\n>\n> - Use loading spinner in a disabled state so a user cannot interact with the\n>   button fully till the action is complete.\n> - If the time expected to complete is short, no language is needed.\n\n```jsx live\nconst App = () => (\n  <Flex gap=\"200\">\n    <Button colorPalette=\"primary\" variant=\"solid\" isDisabled>\n      <LoadingSpinner colorPalette=\"white\" />\n      Saving...\n    </Button>\n    <Button colorPalette=\"primary\" variant=\"solid\" isDisabled>\n      <LoadingSpinner colorPalette=\"white\" />\n    </Button>\n  </Flex>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not keep the button clickable while using a loading state.\n> - Do not use creative or funny phrases if using loading spinner in small\n>   areas, to avoid confusing the user.\n\n```jsx live\nconst App = () => (\n  <Flex gap=\"200\">\n    <Button colorPalette=\"primary\" variant=\"solid\">\n      <LoadingSpinner colorPalette=\"white\" />\n      Remembering details...\n    </Button>\n  </Flex>\n);\n```\n\n> [!TIP]\\\n> **Do**\n>\n> - Use the loading spinner to show that content will be populated in that area.\n> - Keep loading messages short and clear.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"200\" alignItems=\"start\">\n    <Button variant=\"ghost\" size=\"sm\" colorPalette=\"primary\">\n      <Icons.Add />\n      Add filter\n    </Button>\n    <Card.Root elevation=\"elevated\">\n      <Card.Content>\n        <Stack gap=\"200\">\n          <ComboBox.Root\n            inputValue=\"abc\"\n            aria-label=\"Search filters\"\n            allowsEmptyMenu\n          >\n            <ComboBox.Trigger />\n          </ComboBox.Root>\n          <Stack direction=\"horizontal\" alignSelf=\"center\" gap=\"200\">\n            <LoadingSpinner colorPalette=\"primary\" />\n            <Text>Loading results...</Text>\n          </Stack>\n        </Stack>\n      </Card.Content>\n    </Card.Root>\n  </Stack>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't use long statements. Try to keep updates and explainers short, as\n>   translation will consistently add about 20% more length.\n\n```jsx live\nconst App = () => (\n  <Stack gap=\"200\" alignItems=\"start\">\n    <Button variant=\"ghost\" size=\"sm\" colorPalette=\"primary\">\n      <Icons.Add />\n      Add filter\n    </Button>\n    <Card.Root elevation=\"elevated\">\n      <Card.Content>\n        <Stack gap=\"200\">\n          <ComboBox.Root\n            inputValue=\"abc\"\n            aria-label=\"Search filters\"\n            allowsEmptyMenu\n          >\n            <ComboBox.Trigger />\n          </ComboBox.Root>\n          <Stack\n            direction=\"horizontal\"\n            gap=\"200\"\n            alignSelf=\"center\"\n            width=\"2/3\"\n          >\n            <LoadingSpinner colorPalette=\"primary\" flexShrink=\"0\" />\n            <Text>this is taking an unusually long time</Text>\n          </Stack>\n        </Stack>\n      </Card.Content>\n    </Card.Root>\n  </Stack>\n);\n```\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"
+        },
+        {
+          "value": "Loading spinner within elements",
+          "href": "#loading-spinner-within-elements",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}