@adia-ai/web-components 0.6.33 → 0.6.35

package/components/slider/slider.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UISlider } from './class.js';
+import { UISlider } from './slider.class.js';
 
 defineIfFree('slider-ui', UISlider);
 

package/components/spinner/spinner.a2ui.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Spinner.json",
+  "title": "Spinner",
+  "description": "Circular animated indicator for indeterminate loading. Renders a rotating arc, full ring, or three bouncing dots inside a sized box; the animation runs while the element is in the DOM and `[paused]` is unset. Fills the circular-spinner gap left by <skeleton-ui> (rectangular placeholder) and <progress-ui> (linear determinate bar) — use <spinner-ui> when the wait duration is unknown and the shape of the eventual content is irregular or the region is too small for a placeholder block.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "Spinner"
+    },
+    "label": {
+      "description": "Accessible operation name surfaced via `aria-valuetext`. Override for context-specific labels (\"Saving\", \"Uploading\").",
+      "type": "string",
+      "default": "Loading"
+    },
+    "paused": {
+      "description": "Pause the animation in-place. Useful for screenshot tests and explicit-control flows.",
+      "type": "boolean",
+      "default": false
+    },
+    "size": {
+      "description": "Diameter — matches icon-ui's ladder (sm 14px, md 16px, lg 20px).",
+      "type": "string",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ],
+      "default": "md"
+    },
+    "tone": {
+      "description": "Color tone — `current` inherits parent text color (matches button label), `accent` uses brand accent, `subtle` is muted, `inverse` flips for on-accent surfaces.",
+      "type": "string",
+      "enum": [
+        "current",
+        "accent",
+        "subtle",
+        "inverse"
+      ],
+      "default": "current"
+    },
+    "variant": {
+      "description": "Visual flavor — `arc` (rotating quarter-circle, the default glyph spinner), `ring` (full ring with one colored segment rotating around it), `dots` (three bouncing dots — animated in a left-to-right wave), `knight` (horizontal \"knight-rider\" bar — a sliding thumb that bounces back-and-forth across a track; widest variant, reads as a determinate-looking bar but is indeterminate by intent).",
+      "type": "string",
+      "enum": [
+        "arc",
+        "ring",
+        "dots",
+        "knight"
+      ],
+      "default": "arc"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "{\"component\": \"Progress\", \"value\": 42, \"max\": 100}\n",
+        "why": "Spinner is INDETERMINATE only. `value` and any quantitative\nprogress field belongs on Progress, not Spinner. Also \"Spin\" is\nnot a valid operation label.\n",
+        "wrong": "{\"component\": \"Spinner\", \"label\": \"Spin\", \"value\": 0.42}\n"
+      },
+      {
+        "fix": "{\"component\": \"Spinner\", \"size\": \"md\"}\n",
+        "why": "Skeleton is a placeholder; rotation is not part of its contract.\nA rotating circle is a Spinner.\n",
+        "wrong": "{\"component\": \"Skeleton\", \"variant\": \"circle\", \"animation\": \"rotate\"}\n"
+      },
+      {
+        "fix": "{\"component\": \"Card\", \"children\": [\n  {\"component\": \"Spinner\", \"size\": \"lg\"}\n]}\n",
+        "why": "Multiple sibling spinners in one region produce visual noise\nwithout extra information. Use one parent-level Spinner.\n",
+        "wrong": "{\"component\": \"Card\", \"children\": [\n  {\"component\": \"Spinner\"},\n  {\"component\": \"Spinner\"},\n  {\"component\": \"Spinner\"}\n]}\n"
+      }
+    ],
+    "category": "feedback",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "Loading button — primary action with a saving spinner. The button is disabled while the operation is in progress; the spinner matches the button label color via tone=\"current\".",
+        "a2ui": "[\n  {\n    \"id\": \"btn-save\",\n    \"component\": \"Button\",\n    \"text\": \"Saving\",\n    \"variant\": \"primary\",\n    \"disabled\": true,\n    \"children\": [\"sp-1\"]\n  },\n  {\n    \"id\": \"sp-1\",\n    \"component\": \"Spinner\",\n    \"size\": \"sm\",\n    \"tone\": \"current\",\n    \"label\": \"Saving\"\n  }\n]",
+        "name": "button-saving"
+      },
+      {
+        "description": "Standalone centered spinner inside a card while body content fetches.",
+        "a2ui": "[\n  {\n    \"id\": \"card\",\n    \"component\": \"Card\",\n    \"children\": [\"row\"]\n  },\n  {\n    \"id\": \"row\",\n    \"component\": \"Row\",\n    \"justify\": \"center\",\n    \"align\": \"center\",\n    \"children\": [\"sp\"]\n  },\n  {\n    \"id\": \"sp\",\n    \"component\": \"Spinner\",\n    \"size\": \"lg\",\n    \"tone\": \"subtle\",\n    \"label\": \"Loading dashboard\"\n  }\n]",
+        "name": "centered-card-loading"
+      },
+      {
+        "description": "Three bouncing dots — good for chat / typing indicators.",
+        "a2ui": "[\n  {\n    \"id\": \"sp\",\n    \"component\": \"Spinner\",\n    \"variant\": \"dots\",\n    \"tone\": \"subtle\",\n    \"label\": \"Assistant is typing\"\n  }\n]",
+        "name": "typing-indicator"
+      }
+    ],
+    "keywords": [
+      "spinner",
+      "loader",
+      "loading",
+      "indeterminate",
+      "progress",
+      "busy",
+      "feedback",
+      "circular"
+    ],
+    "name": "UISpinner",
+    "related": [
+      "Progress",
+      "Skeleton",
+      "Button",
+      "EmptyState"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "Default; animation active.",
+        "name": "running"
+      },
+      {
+        "description": "Animation frozen at the current frame.",
+        "attribute": "paused",
+        "name": "paused"
+      },
+      {
+        "description": "Triggered by prefers-reduced-motion. Animation replaced with a static ellipsis. Detected via CSS, not JS.",
+        "name": "reduced"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "busy": [
+        "spinner",
+        "loading"
+      ],
+      "indeterminate": [
+        "spinner",
+        "progress"
+      ],
+      "loader": [
+        "spinner",
+        "loading",
+        "progress"
+      ],
+      "loading": [
+        "spinner",
+        "loading",
+        "progress",
+        "skeleton"
+      ],
+      "saving": [
+        "spinner",
+        "loading"
+      ],
+      "spinner": [
+        "spinner",
+        "loader",
+        "progress"
+      ],
+      "uploading": [
+        "spinner",
+        "loading"
+      ]
+    },
+    "tag": "spinner-ui",
+    "tokens": {
+      "--spinner-color": {
+        "description": "Color of the active arc / ring / dots. Defaults to currentColor so a tone-driven cascade resolves naturally.",
+        "default": "currentColor"
+      },
+      "--spinner-duration": {
+        "description": "One full rotation duration.",
+        "default": "var(--a-duration-slow)"
+      },
+      "--spinner-size": {
+        "description": "Diameter of the spinner box.",
+        "default": "1rem"
+      },
+      "--spinner-stroke": {
+        "description": "Border thickness for the arc / ring variants.",
+        "default": "2px"
+      },
+      "--spinner-track-opacity": {
+        "description": "Opacity for the non-rotating ring track (variant=ring only).",
+        "default": "0.25"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/spinner/spinner.class.js

@@ -0,0 +1,99 @@
+/**
+ * Non-side-effect class export for `<spinner-ui>`.
+ *
+ * Importing this file gives you the class without auto-registering the
+ * tag. Useful for test isolation, subclassing with tag-name override, or
+ * selective composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/spinner`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <spinner-ui size="md" variant="arc" tone="current" label="Loading"></spinner-ui>
+ * <spinner-ui variant="dots" tone="subtle" label="Assistant is typing"></spinner-ui>
+ * <spinner-ui paused size="lg"></spinner-ui>
+ *
+ * Circular animated indicator for INDETERMINATE loading. The visual is
+ * rendered entirely via `::before` (and per-variant peers) on the host;
+ * the component stamps no internal DOM (`static template = () => null`).
+ *
+ * Props (attributes):
+ *   size     — sm | md (default) | lg
+ *   variant  — arc (default) | ring | dots
+ *   tone     — current (default) | subtle | accent | inverse
+ *   paused   — freeze the animation in place (default: false)
+ *   label    — accessible operation name (default: "Loading")
+ *
+ * ARIA: role="progressbar" + aria-busy="true" + aria-valuetext=<label>.
+ * Reduced motion: when prefers-reduced-motion: reduce is active, the
+ * spinning animation is replaced with a static "…" ellipsis via CSS
+ * only — no JS observer required. WCAG 2.3.3.
+ *
+ * Lifecycle: pure-CSS animation. No timers, no observers. connected()
+ * sets the three ARIA attributes once; render() keeps aria-valuetext in
+ * sync with the [label] prop.
+ *
+ * @see SPEC-001 (docs/specs/implementation-ready/SPEC-001-spinner-loader.md)
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UISpinner extends UIElement {
+  static properties = {
+    size:    { type: String,  default: 'md',      reflect: true },
+    variant: { type: String,  default: 'arc',     reflect: true },
+    tone:    { type: String,  default: 'current', reflect: true },
+    paused:  { type: Boolean, default: false,     reflect: true },
+    label:   { type: String,  default: 'Loading', reflect: false },
+  };
+
+  // Arc / ring / knight variants are pure ::before paint — no children.
+  // Dots variant stamps three <span data-spinner-dot=N> children in
+  // #syncDots() so each dot can carry an independent animation-delay.
+  // Pre-fix: ::before painted dot1, ::after painted dot3, and a
+  // box-shadow on ::before painted the middle dot. The pseudo-element
+  // approach broke spacing (the box-shadow dot doesn't participate in
+  // flex-gap math; the middle dot can't animate; the outer dots picked
+  // up scale from keyframes but the middle stayed static). Three real
+  // children let flex-gap distribute the row evenly AND give each dot
+  // its own animation phase.
+  static template = () => null;
+
+  connected() {
+    // ARIA wiring — fixed for the lifetime of the element.
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'progressbar');
+    if (!this.hasAttribute('aria-busy')) this.setAttribute('aria-busy', 'true');
+    this.setAttribute('aria-valuetext', this.label || 'Loading');
+    this.#syncDots();
+  }
+
+  render() {
+    // Keep aria-valuetext in sync if `label` changes after connect.
+    this.setAttribute('aria-valuetext', this.label || 'Loading');
+    this.#syncDots();
+  }
+
+  #syncDots() {
+    const isDots = this.variant === 'dots';
+    const existing = this.querySelectorAll(':scope > [data-spinner-dot]');
+    if (isDots) {
+      if (existing.length === 3) return; // already stamped
+      // Wipe any stale dots from a previous variant + stamp fresh.
+      existing.forEach((n) => n.remove());
+      const frag = document.createDocumentFragment();
+      for (let i = 1; i <= 3; i++) {
+        const span = document.createElement('span');
+        span.setAttribute('data-spinner-dot', String(i));
+        span.setAttribute('aria-hidden', 'true');
+        frag.appendChild(span);
+      }
+      this.appendChild(frag);
+    } else if (existing.length) {
+      // Variant changed away from dots — drop the stamped children.
+      existing.forEach((n) => n.remove());
+    }
+  }
+}

package/components/spinner/spinner.css

@@ -0,0 +1,221 @@
+@scope (spinner-ui) {
+  /* ── Block 1 — TOKENS ─────────────────────────────────────────────
+     Spinner inherits the icon ladder for sizing (matches icon-ui's
+     `:scope[size="..."]` rems). The semantic colors come via `tone=…`
+     re-assigning --spinner-color. Stroke is 2px (raw px allowed for
+     borders 1-2px per component-token-contract §"Forbidden patterns"). */
+  :where(:scope) {
+    --spinner-size-default:           1rem;                       /* icon-ui md */
+    --spinner-color-default:          currentColor;
+    --spinner-stroke-default:         2px;
+    /* Rotational cadence — interaction-duration tokens (`--a-duration-*`,
+       120-300 ms) are tuned for hover/focus transitions; a full spinner
+       revolution at 300 ms reads as a frantic blur. Canonical loader
+       cadence is ~0.8 s per revolution (smooth, perceptible motion). */
+    --spinner-duration-default:       0.8s;
+    --spinner-track-opacity-default:  0.25;
+    --spinner-dot-size-default:       calc(var(--spinner-size, var(--spinner-size-default)) / 4);
+    --spinner-dot-gap-default:        calc(var(--spinner-size, var(--spinner-size-default)) / 8);
+    /* Knight-rider variant — horizontal track with a sliding thumb.
+       Track width is a separate scale from the round-spinner --spinner-size
+       (Knight reads as a bar, not a glyph). Track height defaults to the
+       spinner-stroke for visual continuity with arc/ring. Thumb width
+       expressed as a 0-1 ratio of the track so the keyframe math is
+       single-variable. */
+    --spinner-bar-track-width-default:  4rem;
+    --spinner-bar-track-height-default: var(--spinner-stroke, var(--spinner-stroke-default));
+    --spinner-bar-thumb-ratio-default:  0.3;
+  }
+
+  /* ── Block 2 — BASE ────────────────────────────────────────────── */
+  :scope {
+    box-sizing: border-box;
+    display: inline-block;
+    width:  var(--spinner-size, var(--spinner-size-default));
+    height: var(--spinner-size, var(--spinner-size-default));
+    color:  var(--spinner-color, var(--spinner-color-default));
+    vertical-align: middle;
+    flex-shrink: 0;
+  }
+
+  /* ── Size ladder (mirrors icon-ui's local rem declarations) ─────── */
+  :scope[size="sm"]  { --spinner-size-default: 0.875rem; }   /* 14px */
+  :scope[size="md"]  { --spinner-size-default: 1rem; }       /* 16px */
+  :scope[size="lg"]  { --spinner-size-default: 1.25rem; }    /* 20px */
+
+  /* ── Tones (override --spinner-color token) ────────────────────── */
+  :scope[tone="current"] { --spinner-color-default: currentColor; }
+  :scope[tone="subtle"]  { --spinner-color-default: var(--a-fg-subtle); }
+  :scope[tone="accent"]  { --spinner-color-default: var(--a-accent-strong); }
+  :scope[tone="inverse"] { --spinner-color-default: var(--a-chrome-light); }
+
+  /* ── Variant: ARC (default) — rotating quarter-circle border ───── */
+  :scope[variant="arc"]::before,
+  :scope:not([variant])::before {
+    content: "";
+    box-sizing: border-box;
+    display: block;
+    width: 100%;
+    height: 100%;
+    border-radius: 50%;
+    border: var(--spinner-stroke, var(--spinner-stroke-default)) solid;
+    border-color: currentColor transparent transparent transparent;
+    animation: spinner-ui-rotate var(--spinner-duration, var(--spinner-duration-default)) linear infinite;
+  }
+
+  /* ── Variant: RING — full ring with one rotating colored segment ── */
+  :scope[variant="ring"]::before {
+    content: "";
+    box-sizing: border-box;
+    display: block;
+    width: 100%;
+    height: 100%;
+    border-radius: 50%;
+    border: var(--spinner-stroke, var(--spinner-stroke-default)) solid;
+    border-color: color-mix(in oklch, currentColor calc(var(--spinner-track-opacity, var(--spinner-track-opacity-default)) * 100%), transparent);
+    border-top-color: currentColor;
+    animation: spinner-ui-rotate var(--spinner-duration, var(--spinner-duration-default)) linear infinite;
+  }
+
+  /* ── Variant: DOTS — three bouncing dots ─────────────────────────
+     Layout: inline-flex with three real <span data-spinner-dot=N>
+     children stamped by spinner.class.js #syncDots(). flex-gap distributes
+     the row evenly; each child carries its own animation-delay so
+     the bounce reads as a left-to-right wave.
+
+     Why three real children (instead of ::before / ::after + a
+     middle dot painted via box-shadow): box-shadow paints the
+     middle dot but does NOT participate in flex-gap, so the box-
+     shadow dot and the right pseudo had asymmetric spacing. The
+     middle dot also couldn't carry its own @keyframes animation
+     (box-shadow can't animate per-stop). Stamped children fix both. */
+  :scope[variant="dots"] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: auto;             /* dots row is wider than tall */
+    min-width: var(--spinner-size, var(--spinner-size-default));
+    gap: var(--spinner-dot-gap, var(--spinner-dot-gap-default));
+  }
+
+  :scope[variant="dots"] > [data-spinner-dot] {
+    width:  var(--spinner-dot-size, var(--spinner-dot-size-default));
+    height: var(--spinner-dot-size, var(--spinner-dot-size-default));
+    border-radius: 50%;
+    background: currentColor;
+    animation: spinner-ui-bounce var(--spinner-duration, var(--spinner-duration-default)) ease-in-out infinite;
+  }
+  /* Stagger each dot so the row reads as a wave left → right.
+     Three equal slices of one revolution (0, T/3, 2T/3) give the
+     classic three-dot loading rhythm. */
+  :scope[variant="dots"] > [data-spinner-dot="1"] { animation-delay: 0s; }
+  :scope[variant="dots"] > [data-spinner-dot="2"] {
+    animation-delay: calc(var(--spinner-duration, var(--spinner-duration-default)) / 3);
+  }
+  :scope[variant="dots"] > [data-spinner-dot="3"] {
+    animation-delay: calc(var(--spinner-duration, var(--spinner-duration-default)) * 2 / 3);
+  }
+
+  /* ── Variant: KNIGHT — knight-rider sliding bar ──────────────────
+     Horizontal track with a thumb sliding back-and-forth via
+     `animation-direction: alternate`. Thumb width is a 0–1 ratio of
+     the track so the keyframe math reduces to translateX(((1/ratio) - 1) * 100%)
+     of the THUMB's own width — i.e. travel = (track - thumb) px,
+     expressed in thumb-relative percentages so it scales with any
+     track width without a calc that touches both axes. Default
+     ratio 0.3 → translate end = 233.33% (of thumb width). */
+  :scope[variant="knight"] {
+    display: inline-block;
+    width: var(--spinner-bar-track-width, var(--spinner-bar-track-width-default));
+    height: var(--spinner-bar-track-height, var(--spinner-bar-track-height-default));
+    background: color-mix(
+      in oklch,
+      currentColor calc(var(--spinner-track-opacity, var(--spinner-track-opacity-default)) * 100%),
+      transparent
+    );
+    border-radius: 9999px;
+    position: relative;
+    overflow: hidden;
+  }
+  :scope[variant="knight"]::before {
+    content: "";
+    position: absolute;
+    inset: 0 auto 0 0;       /* top:0; right:auto; bottom:0; left:0 */
+    width: calc(var(--spinner-bar-thumb-ratio, var(--spinner-bar-thumb-ratio-default)) * 100%);
+    background: currentColor;
+    border-radius: inherit;
+    animation: spinner-ui-knight
+      var(--spinner-duration, var(--spinner-duration-default))
+      ease-in-out infinite alternate;
+  }
+
+  /* ── Paused state — freeze in place ────────────────────────────── */
+  :scope[paused]::before,
+  :scope[paused]::after,
+  :scope[paused] > [data-spinner-dot] {
+    animation-play-state: paused;
+  }
+
+  /* ── Reduced-motion replacement: static "…" ellipsis ────────────
+     WCAG 2.3.3 — animations of any duration are a vestibular risk.
+     The static replacement still announces aria-busy="true" via the
+     JS lifecycle. */
+  @media (prefers-reduced-motion: reduce) {
+    :scope::before,
+    :scope::after,
+    :scope > [data-spinner-dot] {
+      animation: none !important;
+    }
+    :scope::before {
+      content: "…";
+      border: none;
+      background: transparent;
+      box-shadow: none;
+      margin: 0;
+      width: 100%;
+      height: 100%;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      font: inherit;
+      line-height: 1;
+      text-align: center;
+      color: currentColor;
+    }
+    /* Dots variant — hide all three stamped dots and let the host's
+       ::before paint the ellipsis fallback. */
+    :scope[variant="dots"] > [data-spinner-dot] { display: none; }
+    :scope[variant="dots"] {
+      width: var(--spinner-size, var(--spinner-size-default));   /* shrink back to a square in reduced mode */
+    }
+    /* Knight-rider — hide the sliding thumb; the host's ::before
+       above repaints as the ellipsis fallback. */
+    :scope[variant="knight"] {
+      width: var(--spinner-size, var(--spinner-size-default));
+      background: transparent;
+    }
+  }
+
+  /* ── Keyframes ─────────────────────────────────────────────────── */
+  @keyframes spinner-ui-rotate {
+    to { transform: rotate(360deg); }
+  }
+
+  @keyframes spinner-ui-bounce {
+    0%, 80%, 100% { transform: scale(0.6); opacity: 0.6; }
+    40%           { transform: scale(1);   opacity: 1; }
+  }
+
+  /* Knight-rider — thumb slides from left edge to (track - thumb)
+     and bounces back via `animation-direction: alternate`. The
+     translate distance is expressed in thumb-relative percentages:
+     translateX(((1 / ratio) - 1) * 100%) of the thumb's own width
+     equals (track - thumb) px. At default ratio 0.3 this resolves
+     to translateX(233.33%). */
+  @keyframes spinner-ui-knight {
+    from { transform: translateX(0); }
+    to   { transform: translateX(
+      calc((1 / var(--spinner-bar-thumb-ratio, var(--spinner-bar-thumb-ratio-default)) - 1) * 100%)
+    ); }
+  }
+}

package/components/spinner/spinner.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `<spinner-ui>` — Circular animated indicator for indeterminate loading. Renders a rotating arc, full ring, or three bouncing dots inside a sized box; the animation runs while the element is in the DOM and `[paused]` is unset. Fills the circular-spinner gap left by <skeleton-ui> (rectangular placeholder) and <progress-ui> (linear determinate bar) — use <spinner-ui> when the wait duration is unknown and the shape of the eventual content is irregular or the region is too small for a placeholder block.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/spinner
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UISpinner extends UIElement {
+  /** Accessible operation name surfaced via `aria-valuetext`. Override for context-specific labels ("Saving", "Uploading"). */
+  label: string;
+  /** Pause the animation in-place. Useful for screenshot tests and explicit-control flows. */
+  paused: boolean;
+  /** Diameter — matches icon-ui's ladder (sm 14px, md 16px, lg 20px). */
+  size: 'sm' | 'md' | 'lg';
+  /** Color tone — `current` inherits parent text color (matches button label), `accent` uses brand accent, `subtle` is muted, `inverse` flips for on-accent surfaces. */
+  tone: 'current' | 'accent' | 'subtle' | 'inverse';
+  /** Visual flavor — `arc` (rotating quarter-circle, the default glyph spinner), `ring` (full ring with one colored segment rotating around it), `dots` (three bouncing dots — animated in a left-to-right wave), `knight` (horizontal "knight-rider" bar — a sliding thumb that bounces back-and-forth across a track; widest variant, reads as a determinate-looking bar but is indeterminate by intent). */
+  variant: 'arc' | 'ring' | 'dots' | 'knight';
+}

package/components/spinner/spinner.examples.md

@@ -0,0 +1,26 @@
+# spinner — Examples
+
+## Default
+
+```html
+<spinner-ui></spinner-ui>
+```
+
+## Loading button
+
+Canonical composition. Disable the button while the operation is in
+progress; `tone="current"` keeps the spinner matched to the button's
+label color.
+
+```html
+<button-ui variant="primary" disabled>
+  <spinner-ui size="sm" tone="current" label="Saving"></spinner-ui>
+  Saving
+</button-ui>
+```
+
+## Typing indicator
+
+```html
+<spinner-ui variant="dots" tone="subtle" label="Assistant is typing"></spinner-ui>
+```

package/components/spinner/spinner.js

@@ -0,0 +1,17 @@
+/**
+ * `<spinner-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UISpinner } from '@adia-ai/web-components/components/spinner/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UISpinner } from './spinner.class.js';
+
+defineIfFree('spinner-ui', UISpinner);
+
+export { UISpinner };