@commercetools/nimbus-mcp 3.2.0 → 3.4.0

package/data/docs/routes/components-feedback-activity-indicator.json

@@ -0,0 +1,396 @@
+{
+  "meta": {
+    "id": "Components-ActivityIndicator",
+    "title": "Activity indicator",
+    "exportName": "ActivityIndicator",
+    "description": "An animated three-dot indicator that signals ongoing agent or system activity, such as \"thinking\", \"processing\", or \"typing\" in chat and AI surfaces.",
+    "lifecycleState": "Experimental",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/activity-indicator/activity-indicator.mdx",
+    "menu": [
+      "Components",
+      "Feedback",
+      "Activity indicator"
+    ],
+    "route": "components/feedback/activity-indicator",
+    "tags": [
+      "component",
+      "activity",
+      "typing",
+      "dots",
+      "chat"
+    ],
+    "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": "Inline with text",
+        "href": "#inline-with-text",
+        "depth": 4,
+        "numbering": [
+          1,
+          2,
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "On a solid colored surface",
+        "href": "#on-a-solid-colored-surface",
+        "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=10603-16574&m=dev",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nThe activity indicator communicates that an agent or system is actively working\n— for example composing a reply, thinking, or processing a request. It is most\ncommonly placed inline next to a short status message (\"Thinking…\", \"Processing\nrequest\") in chat and AI surfaces.\n\nUnlike the [Loading spinner](/components/feedback/loadingspinner), which\nrepresents indeterminate progress and signals \"please wait\", the activity\nindicator is a lightweight, presentational hint. Reach for the loading spinner\nwhen something is loading and for the activity indicator when an agent is\nactive.\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=10603-16574&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visuals\n\n#### Inline with text\n\nBy default the indicator scales with the surrounding `font-size`, so it sits\nnaturally beside a status label.\n\n```jsx live\nconst App = () => (\n  <Text fontSize=\"md\">\n    Thinking <ActivityIndicator />\n  </Text>\n);\n```\n\n#### On a solid colored surface\n\nWhen the indicator sits on a solid colored fill, use `variant=\"contrast\"`. The\ndots take the palette's `contrast` step (black or white, chosen automatically per\npalette) so they stay legible on the surface.\n\n```jsx live\nconst App = () => (\n  <Stack\n    colorPalette=\"primary\"\n    backgroundColor=\"colorPalette.9\"\n    padding=\"400\"\n  >\n    <Text color=\"colorPalette.contrast\">\n      Thinking{\" \"}\n      <ActivityIndicator colorPalette=\"primary\" variant=\"contrast\" />\n    </Text>\n  </Stack>\n);\n```\n\n### Size\n\nThe default `inherit` size tracks the surrounding text. Fixed sizes (`2xs`–`lg`)\nreserve a square icon-box footprint so the indicator can sit in input icon slots\nalongside other icons.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <ActivityIndicator size=\"lg\" />\n    <ActivityIndicator size=\"md\" />\n    <ActivityIndicator size=\"sm\" />\n    <ActivityIndicator size=\"xs\" />\n    <ActivityIndicator size=\"2xs\" />\n  </Stack>\n);\n```\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nThe activity indicator communicates that an agent or system is actively working\n— for example composing a reply, thinking, or processing a request. It is most\ncommonly placed inline next to a short status message (\"Thinking…\", \"Processing\nrequest\") in chat and AI surfaces.\n\nUnlike the [Loading spinner](/components/feedback/loadingspinner), which\nrepresents indeterminate progress and signals \"please wait\", the activity\nindicator is a lightweight, presentational hint. Reach for the loading spinner\nwhen something is loading and for the activity indicator when an agent is\nactive.\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=10603-16574&m=dev)\n\n## Variables\n\nGet familiar with the features.\n\n### Visuals\n\n#### Inline with text\n\nBy default the indicator scales with the surrounding `font-size`, so it sits\nnaturally beside a status label.\n\n```jsx live\nconst App = () => (\n  <Text fontSize=\"md\">\n    Thinking <ActivityIndicator />\n  </Text>\n);\n```\n\n#### On a solid colored surface\n\nWhen the indicator sits on a solid colored fill, use `variant=\"contrast\"`. The\ndots take the palette's `contrast` step (black or white, chosen automatically per\npalette) so they stay legible on the surface.\n\n```jsx live\nconst App = () => (\n  <Stack\n    colorPalette=\"primary\"\n    backgroundColor=\"colorPalette.9\"\n    padding=\"400\"\n  >\n    <Text color=\"colorPalette.contrast\">\n      Thinking{\" \"}\n      <ActivityIndicator colorPalette=\"primary\" variant=\"contrast\" />\n    </Text>\n  </Stack>\n);\n```\n\n### Size\n\nThe default `inherit` size tracks the surrounding text. Fixed sizes (`2xs`–`lg`)\nreserve a square icon-box footprint so the indicator can sit in input icon slots\nalongside other icons.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <ActivityIndicator size=\"lg\" />\n    <ActivityIndicator size=\"md\" />\n    <ActivityIndicator size=\"sm\" />\n    <ActivityIndicator size=\"xs\" />\n    <ActivityIndicator size=\"2xs\" />\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": "Inline with text",
+          "href": "#inline-with-text",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "On a solid colored surface",
+          "href": "#on-a-solid-colored-surface",
+          "depth": 4,
+          "numbering": [
+            1,
+            2,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Size",
+          "href": "#size",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport {\n  ActivityIndicator,\n  type ActivityIndicatorProps,\n} from \"@commercetools/nimbus\";\n```\n\n### Basic usage\n\nThe ActivityIndicator signals that an agent or system is actively working. By\ndefault it is decorative and scales with the surrounding `font-size`, so it can\nsit inline next to a visible status label.\n\n```jsx live-dev\nconst App = () => (\n  <Text>\n    Thinking <ActivityIndicator />\n  </Text>\n);\n```\n\n## Usage examples\n\n### Size options\n\nThe `size` prop defaults to `inherit`, which ties the indicator's box to the\nsurrounding `font-size` (`1em`) so it scales with the text. The fixed sizes\n(`2xs`, `xs`, `sm`, `md`, `lg`) reserve a square icon-box footprint — the same\nscale points `LoadingSpinner` uses — so the indicator drops into input start/end\nicon slots interchangeably with a spinner.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n    <ActivityIndicator size=\"2xs\" />\n    <ActivityIndicator size=\"xs\" />\n    <ActivityIndicator size=\"sm\" />\n    <ActivityIndicator size=\"md\" />\n    <ActivityIndicator size=\"lg\" />\n  </Stack>\n);\n```\n\n### Color palette\n\nThe `colorPalette` prop accepts any Nimbus color palette (default `primary`). The\ndots are filled from the palette's `11` shade.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <ActivityIndicator colorPalette=\"primary\" />\n    <ActivityIndicator colorPalette=\"positive\" />\n    <ActivityIndicator colorPalette=\"info\" />\n  </Stack>\n);\n```\n\n### On a solid colored surface\n\nWhen the dots sit on a solid colored fill (e.g. an agent bubble), use\n`variant=\"contrast\"`. This fills the dots from the palette's `contrast` step,\nwhich resolves to black or white automatically per palette so the dots stay\nlegible on the surface.\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Box colorPalette=\"primary\" bg=\"colorPalette.9\" padding=\"400\" borderRadius=\"200\">\n      <ActivityIndicator colorPalette=\"primary\" variant=\"contrast\" />\n    </Box>\n    <Box colorPalette=\"ctyellow\" bg=\"colorPalette.9\" padding=\"400\" borderRadius=\"200\">\n      <ActivityIndicator colorPalette=\"ctyellow\" variant=\"contrast\" />\n    </Box>\n  </Stack>\n);\n```\n\n## Accessibility\n\nThe ActivityIndicator is **purely decorative** — it is always marked\n`aria-hidden`, so assistive technology never announces the animation itself.\nAlways pair it with visible text that conveys the state (for example\n\"Thinking…\"), so screen-reader users get the same information sighted users do.\n\n```tsx\n// Visible text conveys the state; the indicator is decorative.\n<Text>\n  Thinking <ActivityIndicator />\n</Text>\n```\n\n**Announcing the activity to assistive technology is the consumer's\nresponsibility**, not the component's. The indicator does not own a live region,\nbecause it is typically rendered only while activity is in progress — and a live\nregion mounted together with its content is not announced reliably across screen\nreaders (the region must already exist in the DOM before its content changes).\nIf you need to announce the activity without adjacent visible text, drive a\n**persistent** live region owned by the surrounding chat/turn container (for\nexample via React Aria's [`@react-aria/live-announcer`](https://react-spectrum.adobe.com/react-aria/announce.html)),\nand keep the indicator decorative.\n\nThis component is **not** a progress indicator and does not use\n`role=\"progressbar\"`. For indeterminate progress (\"please wait\"), use\n[LoadingSpinner](/components/feedback/loadingspinner) instead.\n\n## Reduced motion\n\nWhen the user has `prefers-reduced-motion: reduce` enabled, the vertical bounce\nis replaced by a gentle opacity pulse, so the \"working\" state remains\nperceivable without large motion.\n\n## API reference\n\n<PropsTable id=\"ActivityIndicator\" />\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using\nActivityIndicator within your application. As the component's internal\nfunctionality is already tested by Nimbus, these patterns help you verify your\nintegration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the indicator renders and exposes the expected accessibility semantics\n\n```tsx\nimport { describe, it, expect } from \"vitest\";\nimport { render, screen } from \"@testing-library/react\";\nimport { ActivityIndicator, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"ActivityIndicator - Basic rendering\", () => {\n  it(\"is decorative by default (aria-hidden, no role)\", () => {\n    render(\n      <NimbusProvider>\n        <ActivityIndicator data-testid=\"indicator\" />\n      </NimbusProvider>\n    );\n\n    const indicator = screen.getByTestId(\"indicator\");\n    expect(indicator).toBeInTheDocument();\n    expect(indicator).toHaveAttribute(\"aria-hidden\", \"true\");\n    expect(indicator).not.toHaveAttribute(\"role\");\n  });\n\n  it(\"renders three dot elements\", () => {\n    render(\n      <NimbusProvider>\n        <ActivityIndicator data-testid=\"indicator\" />\n      </NimbusProvider>\n    );\n\n    const dots = screen.getByTestId(\"indicator\").querySelectorAll(\"[data-dot]\");\n    expect(dots).toHaveLength(3);\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-activityindicator--docs)\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": "Color palette",
+          "href": "#color-palette",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "On a solid colored surface",
+          "href": "#on-a-solid-colored-surface",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Reduced motion",
+          "href": "#reduced-motion",
+          "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\nActivity indicator guidelines aim to communicate that an agent or system is\nactively working — composing, thinking, or processing — in a way that feels\nlightweight and conversational, without implying that the user must wait for a\nblocking operation to finish.\n\n### Best practices\n\n- **Pair with a status label:** Place the indicator inline next to a short,\n  human-readable message (\"Thinking…\", \"Processing request\"). The default size\n  scales with the surrounding text, so it aligns naturally.\n- **Use the right tool for the job:** Use the activity indicator for agent or\n  conversational activity. For indeterminate loading where the user must wait,\n  use the [Loading spinner](/components/feedback/loadingspinner) instead.\n- **Match the surface:** On neutral or page backgrounds, keep the default\n  (`plain`) treatment. When the dots sit on a solid colored fill — such as an\n  agent bubble — use `variant=\"contrast\"` so they take the palette's contrast\n  color (black or white) and stay legible.\n- **Always pair it with visible text:** The indicator is purely decorative\n  (`aria-hidden`), so screen readers rely on the adjacent text (\"Thinking…\") to\n  convey the state. Never use it as the sole indication of activity.\n- **Announce from the container, not the indicator:** If you need to announce\n  activity without adjacent visible text, drive a persistent live region owned\n  by the surrounding chat/turn container (e.g. `@react-aria/live-announcer`).\n  The indicator itself does not own a live region — it is usually mounted only\n  while active, and a live region mounted with its content does not announce\n  reliably.\n- **Respect motion preferences:** The indicator automatically swaps its bounce\n  for a gentle pulse under `prefers-reduced-motion`. Do not reintroduce large\n  motion on top of it.\n\n### Usage\n\n> [!TIP]\\\n> When to use\n\n- **Agent is composing or thinking:** A chat or AI surface is generating a\n  response.\n- **Short, non-blocking activity:** A brief background step where the user can\n  keep reading or interacting.\n- **Inline with a status message:** Alongside text such as \"Thinking…\" or\n  \"Processing request\".\n\n> [!CAUTION]\\\n> When not to use\n\n- **Indeterminate loading the user must wait for:** Use the\n  [Loading spinner](/components/feedback/loadingspinner).\n- **Determinate progress:** Use a progress bar so the user can see how far along\n  the operation is.\n- **Persistent, page-level busy states:** Prefer a clearly labeled loading state\n  with context.\n\n### Accessibility\n\n- The indicator is purely decorative (`aria-hidden`) and relies on adjacent\n  visible text to convey meaning to assistive technology.\n- It does not own a live region. Announce activity from a persistent live region\n  in the surrounding container (e.g. `@react-aria/live-announcer`) when no\n  adjacent visible text is present.\n- It is not a progress indicator and never uses `role=\"progressbar\"`.\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": "Accessibility",
+          "href": "#accessibility",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            3
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}