@ds-mo/ui 9.0.0 → 9.1.0

package/dist/mcp-data/registry/loader.json

@@ -0,0 +1,192 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "loader",
+  "title": "Loader",
+  "description": "Indeterminate progress glyph for ongoing operations, inheriting owner color and optionally exposing standalone polite status text.",
+  "type": "registry:ui",
+  "meta": {
+    "library": "@ds-mo/ui",
+    "distribution": "npm",
+    "storybook": "https://zainadeel.github.io/compomo/?path=/story/loader",
+    "source": "src/wc/components/Loader/Loader.tsx",
+    "intentStatus": "complete",
+    "intent": {
+      "audience": "general",
+      "status": "stable",
+      "summary": "Indeterminate progress glyph for ongoing operations, inheriting owner color and optionally exposing standalone polite status text.",
+      "useWhen": [
+        "An action or operation is in progress and its remaining duration cannot be quantified.",
+        "A button, field, or bounded workflow needs a compact visual busy indicator owned by that control or region.",
+        "A standalone operation needs a visible spinner with contextual polite status text."
+      ],
+      "avoidWhen": [
+        "Pending content has a predictable structure; use Skeleton to preserve that layout.",
+        "Progress is measurable; use an appropriate determinate progress pattern.",
+        "The UI needs a blocking overlay or automatic centering; the owning layout must provide that structure.",
+        "Success, failure, retry, or completion must be communicated; the owning workflow handles outcomes."
+      ],
+      "alternatives": [
+        {
+          "when": "A content region is waiting for structured data.",
+          "component": "component:ds-skeleton",
+          "reason": "Skeleton preserves the expected content geometry while data loads."
+        },
+        {
+          "when": "A static visual symbol is needed without progress semantics.",
+          "component": "component:ds-icon",
+          "reason": "Icon owns non-progress system and flag glyphs."
+        }
+      ],
+      "commonlyComposedWith": [
+        "component:ds-button-filled",
+        "component:ds-button-unfilled",
+        "component:ds-input",
+        "component:ds-select"
+      ],
+      "accessibility": [
+        "When Loader is nested in a busy button, field, or region, keep it unnamed and expose busy state from the owner.",
+        "Standalone Loader requires contextual status text that explains what is loading; do not rely on a generic visual spinner alone.",
+        "Loader is an informative progress graphic and must retain sufficient rendered contrast; tertiary and quaternary are not supported standalone or informative Loader treatments.",
+        "Avoid duplicate announcements from both Loader and its owning busy region.",
+        "Reduced motion stops rotation while keeping the glyph and status semantics visible."
+      ],
+      "states": [
+        "Loader communicates indeterminate progress only and does not emit completion or failure events.",
+        "Omitted color inherits currentColor. Explicit semantic aliases and CSS-variable references match Icon when an independent progress color is required.",
+        "Nested Loader inherits a readable color from its owning busy control or region rather than selecting tertiary or quaternary directly.",
+        "The owner decides whether to delay Loader visibility for short operations and removes it when the operation settles.",
+        "The owner reserves space and supplies centering or overlay layout so Loader never causes unexpected layout movement."
+      ],
+      "responsiveBehavior": [
+        "The owning component or layout chooses Loader size, placement, and any responsive changes.",
+        "Loader does not infer container size or viewport breakpoints."
+      ],
+      "frameworkCaveats": {
+        "customElements": [
+          "Use the label only for standalone status; nested usage should synchronize aria-busy on the owning element."
+        ],
+        "react": [
+          "Derive Loader visibility and the owner's busy state from the same operation state."
+        ],
+        "angular": [
+          "Derive Loader visibility and the owner's busy state from the same operation state."
+        ]
+      },
+      "references": [
+        {
+          "label": "Storybook examples",
+          "path": "src/wc/components/Loader/Loader.stories.ts"
+        }
+      ]
+    },
+    "api": {
+      "props": {
+        "color": {
+          "type": "LoaderColor",
+          "resolvedType": "\"ai\" | \"bold-ai\" | \"bold-brand\" | \"bold-caution\" | \"bold-negative\" | \"bold-neutral\" | \"bold-positive\" | \"bold-warning\" | \"brand\" | \"caution\" | \"faint-ai\" | \"faint-brand\" | \"faint-caution\" | \"faint-negative\" | \"faint-neutral\" | \"faint-positive\" | \"faint-warning\" | \"guide\" | \"inherit\" | \"medium-ai\" | \"medium-brand\" | \"medium-caution\" | \"medium-negative\" | \"medium-neutral\" | \"medium-positive\" | \"medium-warning\" | \"negative\" | \"neutral\" | \"on-bold\" | \"on-strong\" | \"positive\" | \"primary\" | \"quaternary\" | \"secondary\" | \"strong-ai\" | \"strong-brand\" | \"strong-caution\" | \"strong-negative\" | \"strong-neutral\" | \"strong-positive\" | \"strong-warning\" | \"tertiary\" | \"warning\" | `var(--${string})`",
+          "attribute": "color",
+          "default": "'inherit'",
+          "required": false,
+          "mutable": false,
+          "description": "Semantic foreground color token, or a raw CSS var reference. Same tokens\nas `ds-icon`. Do not use `tertiary` or `quaternary` for a standalone or\ninformative Loader; inherit a readable color from the owning busy control\nor region."
+        },
+        "label": {
+          "type": "string | undefined",
+          "resolvedType": "string | undefined",
+          "attribute": "label",
+          "required": false,
+          "mutable": false,
+          "description": "Accessible label for standalone usage. Wraps the spinner in a live region\nand renders the label visually-hidden. Omit when the host element already\nconveys busy state via aria-busy."
+        },
+        "size": {
+          "type": "LoaderSize",
+          "resolvedType": "\"2xl\" | \"3xl\" | \"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\"",
+          "attribute": "size",
+          "default": "'md'",
+          "required": false,
+          "mutable": false,
+          "description": "Iconography size token. Maps to `--dimension-iconography-{size}`. Default `md` = 20 px."
+        }
+      },
+      "events": [],
+      "methods": [],
+      "slots": []
+    },
+    "props": {
+      "color": {
+        "type": "LoaderColor",
+        "resolvedType": "\"ai\" | \"bold-ai\" | \"bold-brand\" | \"bold-caution\" | \"bold-negative\" | \"bold-neutral\" | \"bold-positive\" | \"bold-warning\" | \"brand\" | \"caution\" | \"faint-ai\" | \"faint-brand\" | \"faint-caution\" | \"faint-negative\" | \"faint-neutral\" | \"faint-positive\" | \"faint-warning\" | \"guide\" | \"inherit\" | \"medium-ai\" | \"medium-brand\" | \"medium-caution\" | \"medium-negative\" | \"medium-neutral\" | \"medium-positive\" | \"medium-warning\" | \"negative\" | \"neutral\" | \"on-bold\" | \"on-strong\" | \"positive\" | \"primary\" | \"quaternary\" | \"secondary\" | \"strong-ai\" | \"strong-brand\" | \"strong-caution\" | \"strong-negative\" | \"strong-neutral\" | \"strong-positive\" | \"strong-warning\" | \"tertiary\" | \"warning\" | `var(--${string})`",
+        "attribute": "color",
+        "default": "'inherit'",
+        "required": false,
+        "mutable": false,
+        "description": "Semantic foreground color token, or a raw CSS var reference. Same tokens\nas `ds-icon`. Do not use `tertiary` or `quaternary` for a standalone or\ninformative Loader; inherit a readable color from the owning busy control\nor region."
+      },
+      "label": {
+        "type": "string | undefined",
+        "resolvedType": "string | undefined",
+        "attribute": "label",
+        "required": false,
+        "mutable": false,
+        "description": "Accessible label for standalone usage. Wraps the spinner in a live region\nand renders the label visually-hidden. Omit when the host element already\nconveys busy state via aria-busy."
+      },
+      "size": {
+        "type": "LoaderSize",
+        "resolvedType": "\"2xl\" | \"3xl\" | \"lg\" | \"md\" | \"sm\" | \"xl\" | \"xs\"",
+        "attribute": "size",
+        "default": "'md'",
+        "required": false,
+        "mutable": false,
+        "description": "Iconography size token. Maps to `--dimension-iconography-{size}`. Default `md` = 20 px."
+      }
+    },
+    "events": [],
+    "methods": [],
+    "slots": [],
+    "exports": {
+      "customElement": "ds-loader",
+      "react": "DsLoader",
+      "angular": "DsLoader"
+    },
+    "consumption": {
+      "install": "npm install @ds-mo/ui @ds-mo/tokens @ds-mo/icons",
+      "cssSetup": "import '@ds-mo/tokens';\nimport '@ds-mo/tokens/reset';\nimport '@ds-mo/tokens/globals';",
+      "customElements": {
+        "import": "import '@ds-mo/ui/dist/components/ds-loader.js';",
+        "example": "<ds-loader></ds-loader>"
+      },
+      "react": {
+        "import": "import { DsLoader } from '@ds-mo/ui/react';",
+        "example": "<DsLoader />"
+      },
+      "angular": {
+        "import": "import { DsLoader } from '@ds-mo/ui/angular/ds-loader';",
+        "example": "<ds-loader></ds-loader>"
+      },
+      "peerDependencies": {
+        "required": [
+          "@ds-mo/tokens ^3.1.1",
+          "@ds-mo/icons ^6.2.0"
+        ],
+        "frameworks": "Custom Elements; React 18/19 wrappers; Angular 19-22 standalone adapters."
+      }
+    }
+  },
+  "dependencies": [
+    "@ds-mo/ui",
+    "@ds-mo/tokens"
+  ],
+  "registryDependencies": [],
+  "files": [
+    {
+      "path": "src/wc/components/Loader/Loader.css",
+      "content": "/* ── Base loader (mirrors ds-icon box metrics) ───────────────────────────── */\n\n.loader {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  flex-shrink: 0;\n  line-height: 0;\n  color: inherit;\n  width: var(--_loader-sz, var(--dimension-iconography-md));\n  height: var(--_loader-sz, var(--dimension-iconography-md));\n  animation: loader-spin var(--effect-animation-duration-long-2) var(--effect-animation-easing-linear) infinite;\n}\n\n.loader__svg {\n  display: block;\n  flex-shrink: 0;\n  width: 100%;\n  height: 100%;\n}\n\n.status {\n  display: inline-flex;\n  align-items: center;\n}\n\n.visually-hidden {\n  position: absolute;\n  /* stylelint-disable declaration-property-value-disallowed-list -- classic visually-hidden clip pattern */\n  width: 1px;\n  height: 1px;\n  padding: 0;\n  margin: -1px;\n  overflow: hidden;\n  clip: rect(0, 0, 0, 0);\n  white-space: nowrap;\n  border: 0;\n  /* stylelint-enable declaration-property-value-disallowed-list */\n}\n\n/* Anti-clockwise continuous spin — 1000ms via long-2. */\n@keyframes loader-spin {\n  from { transform: rotate(0deg); }\n  to   { transform: rotate(-360deg); }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .loader {\n    animation: none;\n    transform: none;\n  }\n}\n\n/* ── Sizes (same tokens as ds-icon) ──────────────────────────────────────── */\n\n.loader--size-xs  { --_loader-sz: var(--dimension-iconography-xs);  }\n.loader--size-sm  { --_loader-sz: var(--dimension-iconography-sm);  }\n.loader--size-md  { --_loader-sz: var(--dimension-iconography-md);  }\n.loader--size-lg  { --_loader-sz: var(--dimension-iconography-lg);  }\n.loader--size-xl  { --_loader-sz: var(--dimension-iconography-xl);  }\n.loader--size-2xl { --_loader-sz: var(--dimension-iconography-2xl); }\n.loader--size-3xl { --_loader-sz: var(--dimension-iconography-3xl); }\n\n/* ── Colors — hierarchy ──────────────────────────────────────────────────── */\n\n.loader--color-primary    { color: var(--color-foreground-primary);    }\n.loader--color-secondary  { color: var(--color-foreground-secondary);  }\n.loader--color-tertiary   { color: var(--color-foreground-tertiary);   }\n.loader--color-quaternary { color: var(--color-foreground-quaternary); }\n.loader--color-inherit    { color: inherit; }\n\n/* ── Colors — intent (bold contrast default) ─────────────────────────────── */\n\n.loader--color-brand    { color: var(--color-foreground-bold-brand);    }\n.loader--color-negative { color: var(--color-foreground-bold-negative); }\n.loader--color-positive { color: var(--color-foreground-bold-positive); }\n.loader--color-warning  { color: var(--color-foreground-bold-warning);  }\n.loader--color-caution  { color: var(--color-foreground-bold-caution);  }\n.loader--color-ai       { color: var(--color-foreground-bold-ai);       }\n.loader--color-guide    { color: var(--color-foreground-bold-guide);    }\n.loader--color-neutral  { color: var(--color-foreground-bold-neutral);  }\n\n/* ── Colors — intent faint ───────────────────────────────────────────────── */\n\n.loader--color-faint-brand    { color: var(--color-foreground-faint-brand);    }\n.loader--color-faint-negative { color: var(--color-foreground-faint-negative); }\n.loader--color-faint-positive { color: var(--color-foreground-faint-positive); }\n.loader--color-faint-warning  { color: var(--color-foreground-faint-warning);  }\n.loader--color-faint-caution  { color: var(--color-foreground-faint-caution);  }\n.loader--color-faint-ai       { color: var(--color-foreground-faint-ai);       }\n.loader--color-faint-neutral  { color: var(--color-foreground-faint-neutral);  }\n\n/* ── Colors — intent medium ─────────────────────────────────────────────── */\n\n.loader--color-medium-brand    { color: var(--color-foreground-medium-brand);    }\n.loader--color-medium-negative { color: var(--color-foreground-medium-negative); }\n.loader--color-medium-positive { color: var(--color-foreground-medium-positive); }\n.loader--color-medium-warning  { color: var(--color-foreground-medium-warning);  }\n.loader--color-medium-caution  { color: var(--color-foreground-medium-caution);  }\n.loader--color-medium-ai       { color: var(--color-foreground-medium-ai);       }\n.loader--color-medium-neutral  { color: var(--color-foreground-medium-neutral);  }\n\n/* ── Colors — intent bold (explicit) ────────────────────────────────────── */\n\n.loader--color-bold-brand    { color: var(--color-foreground-bold-brand);    }\n.loader--color-bold-negative { color: var(--color-foreground-bold-negative); }\n.loader--color-bold-positive { color: var(--color-foreground-bold-positive); }\n.loader--color-bold-warning  { color: var(--color-foreground-bold-warning);  }\n.loader--color-bold-caution  { color: var(--color-foreground-bold-caution);  }\n.loader--color-bold-ai       { color: var(--color-foreground-bold-ai);       }\n.loader--color-bold-neutral  { color: var(--color-foreground-bold-neutral);  }\n\n/* ── Colors — intent strong ──────────────────────────────────────────────── */\n\n.loader--color-strong-brand    { color: var(--color-foreground-strong-brand);    }\n.loader--color-strong-negative { color: var(--color-foreground-strong-negative); }\n.loader--color-strong-positive { color: var(--color-foreground-strong-positive); }\n.loader--color-strong-warning  { color: var(--color-foreground-strong-warning);  }\n.loader--color-strong-caution  { color: var(--color-foreground-strong-caution);  }\n.loader--color-strong-ai       { color: var(--color-foreground-strong-ai);       }\n.loader--color-strong-neutral  { color: var(--color-foreground-strong-neutral);  }\n\n/* ── Colors — contextual ────────────────────────────────────────────────── */\n\n.loader--color-on-strong { color: var(--color-foreground-on-strong-background-primary); }\n.loader--color-on-bold   { color: var(--color-foreground-on-bold-background-primary);   }\n",
+      "type": "registry:ui"
+    },
+    {
+      "path": "src/wc/components/Loader/Loader.tsx",
+      "content": "import { Component, Prop, h, Host } from '@stencil/core';\nimport type { IconColor, IconSize } from '../Icon/Icon';\n\nexport type LoaderSize = IconSize;\nexport type LoaderColor = IconColor;\n\n@Component({\n  tag: 'ds-loader',\n  styleUrl: 'Loader.css',\n  shadow: true,\n})\nexport class Loader {\n  /** Iconography size token. Maps to `--dimension-iconography-{size}`. Default `md` = 20 px. */\n  @Prop() size: LoaderSize = 'md';\n  /**\n   * Semantic foreground color token, or a raw CSS var reference. Same tokens\n   * as `ds-icon`. Do not use `tertiary` or `quaternary` for a standalone or\n   * informative Loader; inherit a readable color from the owning busy control\n   * or region.\n   */\n  @Prop() color: LoaderColor = 'inherit';\n  /**\n   * Accessible label for standalone usage. Wraps the spinner in a live region\n   * and renders the label visually-hidden. Omit when the host element already\n   * conveys busy state via aria-busy.\n   */\n  @Prop() label: string | undefined;\n\n  render() {\n    const isCustomColor = typeof this.color === 'string' && this.color.startsWith('var(--');\n\n    const cls: Record<string, boolean> = {\n      loader: true,\n      [`loader--size-${this.size}`]: true,\n      [`loader--color-${this.color}`]: !!this.color && !isCustomColor && this.color !== 'inherit',\n      'loader--color-inherit': this.color === 'inherit',\n    };\n\n    const style = isCustomColor ? { color: this.color as string } : undefined;\n\n    const spinner = (\n      <span class={cls} style={style} aria-hidden=\"true\">\n        <svg class=\"loader__svg\" viewBox=\"0 0 16 16\" fill=\"none\" focusable=\"false\">\n          <path\n            opacity=\"0.1\"\n            d=\"M3 8C3 5.23858 5.23858 3 8 3V2C4.68629 2 2 4.68629 2 8C2 9.99456 2.97323 11.7618 4.47072 12.8528L5.05894 12.044C3.81102 11.1348 3 9.66213 3 8Z\"\n            fill=\"currentColor\"\n          />\n          <path\n            opacity=\"0.2\"\n            fill-rule=\"evenodd\"\n            clip-rule=\"evenodd\"\n            d=\"M5.05892 12.0438C5.88425 12.6451 6.90069 12.9998 7.99998 12.9998C9.66211 12.9998 11.1348 12.1888 12.0439 10.9409L12.8527 11.5291C11.7618 13.0266 9.99454 13.9998 7.99998 13.9998C6.68083 13.9998 5.46111 13.5741 4.4707 12.8526L5.05892 12.0438Z\"\n            fill=\"currentColor\"\n          />\n          <path\n            opacity=\"0.4\"\n            fill-rule=\"evenodd\"\n            clip-rule=\"evenodd\"\n            d=\"M12.0435 10.9408C12.6447 10.1155 12.9995 9.09906 12.9995 7.99976C12.9995 7.45884 12.9136 6.93798 12.7547 6.45007L13.7057 6.14014C13.8964 6.72562 13.9995 7.35065 13.9995 7.99976C13.9995 9.31891 13.5738 10.5386 12.8523 11.529L12.0435 10.9408Z\"\n            fill=\"currentColor\"\n          />\n          <path\n            opacity=\"0.6\"\n            fill-rule=\"evenodd\"\n            clip-rule=\"evenodd\"\n            d=\"M12.7555 6.45152C12.4263 5.43958 11.7831 4.56933 10.9409 3.95577L11.5291 3.14697C12.5398 3.88325 13.3116 4.92755 13.7067 6.14188L12.7555 6.45152Z\"\n            fill=\"currentColor\"\n          />\n          <path\n            opacity=\"0.8\"\n            fill-rule=\"evenodd\"\n            clip-rule=\"evenodd\"\n            d=\"M10.941 3.95583C10.5307 3.65688 10.0731 3.41886 9.58154 3.25509L9.89786 2.30615C10.4877 2.50267 11.0368 2.78829 11.5293 3.14704L10.941 3.95583Z\"\n            fill=\"currentColor\"\n          />\n          <path\n            fill-rule=\"evenodd\"\n            clip-rule=\"evenodd\"\n            d=\"M9.89788 2.30636C9.3014 2.10762 8.66327 2 8 2V3C8.55272 3 9.0845 3.08968 9.58157 3.2553L9.89788 2.30636Z\"\n            fill=\"currentColor\"\n          />\n        </svg>\n      </span>\n    );\n\n    if (!this.label) {\n      return (\n        <Host style={{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center' }}>\n          {spinner}\n        </Host>\n      );\n    }\n\n    return (\n      <Host style={{ display: 'inline-flex', alignItems: 'center', justifyContent: 'center' }}>\n        <span role=\"status\" aria-live=\"polite\" class=\"status\">\n          {spinner}\n          <span class=\"visually-hidden\">{this.label}</span>\n        </span>\n      </Host>\n    );\n  }\n}\n",
+      "type": "registry:ui"
+    }
+  ]
+}