@adia-ai/web-components 0.6.34 → 0.6.35

package/components/loading-overlay/loading-overlay.class.js

@@ -0,0 +1,203 @@
+/**
+ * Non-side-effect class export for `<loading-overlay-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/loading-overlay`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <loading-overlay-ui active label="Loading orders…"></loading-overlay-ui>
+ * <loading-overlay-ui active variant="transparent" delay="0">
+ *   <skeleton-ui width="100%" height="1rem"></skeleton-ui>
+ *   <skeleton-ui width="80%"  height="1rem"></skeleton-ui>
+ * </loading-overlay-ui>
+ *
+ * Container-scoped busy overlay. Covers a positioned parent region with
+ * a spinner, skeleton, or custom busy indicator while async work is in
+ * flight. The host:
+ *
+ *   1. Absolutely positions to fill the offsetParent (consumer's
+ *      responsibility to ensure that parent is `position: relative` or
+ *      similar — documented in the spec / usage notes; we do NOT mutate
+ *      parent layout styles).
+ *   2. Applies aria-busy="true" to the parent on activate; releases on
+ *      deactivate / disconnect. This is screen-reader politeness; the
+ *      backdrop's pointer-events:auto handles the click/focus block at
+ *      the CSS level (no native [inert] attribute toggling — that's
+ *      kept minimal to avoid disturbing the consumer's focus model).
+ *   3. Auto-stamps a centered <spinner-ui size="lg"> when the default
+ *      slot is empty.
+ *   4. Honors a `[delay]` grace window (default 200ms) — if the active
+ *      flag is cleared before the timer fires, the overlay never
+ *      paints. Avoids flash on fast loads.
+ *
+ * Props (attributes):
+ *   active   — overlay visible (default: false)
+ *   delay    — grace window in ms before paint (default: 200)
+ *   label    — accessible label, also forwarded to auto-stamped spinner
+ *   variant  — default | transparent | blur
+ *
+ * Lifecycle: connected() seeds aria-label on host + caches parent
+ * reference for aria-busy bookkeeping. Disconnected() clears any
+ * pending delay timer and releases aria-busy on the parent. State
+ * changes are driven by the reactive [active] setter wrapper, which
+ * starts/cancels the timer + applies aria-busy when the timer fires.
+ *
+ * @see SPEC-034 (docs/specs/implementation-ready/SPEC-034-loading-overlay.md)
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UILoadingOverlay extends UIElement {
+  static properties = {
+    active:  { type: Boolean, default: false,      reflect: true },
+    delay:   { type: Number,  default: 200,        reflect: true },
+    label:   { type: String,  default: 'Loading…', reflect: true },
+    variant: { type: String,  default: 'default',  reflect: true },
+  };
+
+  // No stamped children authored by the template engine; auto-stamp of
+  // the default spinner happens imperatively in connected() / render()
+  // when the slot is empty. Authored children (skeleton/progress/etc.)
+  // are left in place per ADR-0033 (light-DOM substrate).
+  static template = () => null;
+
+  #parent = null;
+  #delayTimer = null;
+  #activeApplied = false;   // tracks whether aria-busy / opacity actually painted
+
+  constructor() {
+    super();
+    // Wrap the auto-installed `active` setter so state transitions kick
+    // the delay timer synchronously with the assignment — matching the
+    // drawer-ui Safari pattern (avoids microtask scheduling delays).
+    const desc = Object.getOwnPropertyDescriptor(this, 'active');
+    if (desc?.set) {
+      const origSet = desc.set;
+      Object.defineProperty(this, 'active', {
+        get: desc.get,
+        set: (v) => {
+          const prev = !!desc.get.call(this);
+          origSet.call(this, v);
+          if (!!v !== prev) this.#syncActive(!!v);
+        },
+        configurable: true,
+      });
+    }
+  }
+
+  connected() {
+    // Host ARIA: role=status is a polite live region; aria-label
+    // names the operation. Both are seeded once; render() keeps the
+    // label fresh on prop changes.
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'status');
+    if (!this.hasAttribute('aria-live')) this.setAttribute('aria-live', 'polite');
+    this.setAttribute('aria-label', this.label || 'Loading');
+
+    // Cache the parent so disconnected() can release aria-busy even if
+    // the element is detached before parentElement is re-readable.
+    this.#parent = this.parentElement;
+
+    // If the element mounted with [active] already set (declarative),
+    // honor it. The reactive setter wrapper only fires on subsequent
+    // assignments, so we kick the timer here too.
+    if (this.active) this.#syncActive(true);
+  }
+
+  disconnected() {
+    // Symmetric lifecycle: clear any in-flight timer + release aria-busy
+    // on the parent we cached at connect time.
+    this.#clearTimer();
+    if (this.#activeApplied) this.#releaseBusy();
+    this.#parent = null;
+  }
+
+  render() {
+    // Keep the host label fresh if [label] is mutated after connect.
+    // Forward it to an auto-stamped spinner-ui (if present) so screen
+    // readers hear a single coherent name.
+    const label = this.label || 'Loading';
+    this.setAttribute('aria-label', label);
+
+    const ownSpinner = this.querySelector(':scope > spinner-ui[data-loading-overlay-auto]');
+    if (ownSpinner && ownSpinner.getAttribute('label') !== label) {
+      ownSpinner.setAttribute('label', label);
+    }
+
+    // Ensure the auto-stamped spinner exists when the slot is empty.
+    // Authored children (consumer-supplied indicators) win; we only
+    // stamp when there are no element children at all.
+    if (this.children.length === 0) {
+      this.#stampDefaultSpinner();
+    }
+  }
+
+  // ── Internals ───────────────────────────────────────────────────────
+
+  #syncActive(next) {
+    // Clear any prior in-flight timer first; the new state owns the
+    // grace window.
+    this.#clearTimer();
+
+    if (next) {
+      const delay = Math.max(0, Number(this.delay) || 0);
+      if (delay === 0) {
+        this.#applyBusy();
+      } else {
+        this.#delayTimer = setTimeout(() => {
+          this.#delayTimer = null;
+          // Only paint if we're still active — caller may have cleared
+          // [active] during the grace window.
+          if (this.active) this.#applyBusy();
+        }, delay);
+      }
+    } else if (this.#activeApplied) {
+      this.#releaseBusy();
+    }
+  }
+
+  #applyBusy() {
+    const parent = this.#parent || this.parentElement;
+    if (parent && !parent.hasAttribute('aria-busy')) {
+      parent.setAttribute('aria-busy', 'true');
+    }
+    this.#activeApplied = true;
+  }
+
+  #releaseBusy() {
+    const parent = this.#parent || this.parentElement;
+    // Only remove aria-busy if WE set it (heuristic: matches "true").
+    // If the consumer authored their own aria-busy="true" before we
+    // mounted, we leave it; if they set "false" we leave it. Same
+    // shape as drawer-ui releasing dialog state.
+    if (parent && parent.getAttribute('aria-busy') === 'true') {
+      parent.removeAttribute('aria-busy');
+    }
+    this.#activeApplied = false;
+  }
+
+  #clearTimer() {
+    if (this.#delayTimer !== null) {
+      clearTimeout(this.#delayTimer);
+      this.#delayTimer = null;
+    }
+  }
+
+  #stampDefaultSpinner() {
+    // Imperative stamp — light-DOM child, marked with a data attribute
+    // so render()'s "did the consumer slot something?" check stays
+    // unambiguous on subsequent renders.
+    const sp = document.createElement('spinner-ui');
+    sp.setAttribute('size', 'lg');
+    sp.setAttribute('tone', 'subtle');
+    sp.setAttribute('label', this.label || 'Loading');
+    sp.setAttribute('data-loading-overlay-auto', '');
+    this.appendChild(sp);
+  }
+}

package/components/loading-overlay/loading-overlay.css

@@ -0,0 +1,81 @@
+@scope (loading-overlay-ui) {
+  /* ── Block 1 — TOKENS ─────────────────────────────────────────────
+     Loading-overlay covers a positioned parent. Backdrop tint, corner
+     radius, stacking order, and motion are all consumer-overridable
+     via the `var(--public, var(--public-default))` chain (per
+     component-token-contract.md §"The two-block @scope pattern"). */
+  :where(:scope) {
+    --loading-overlay-bg-default:        var(--a-scrim-default);
+    --loading-overlay-radius-default:    var(--a-radius-md);
+    --loading-overlay-z-default:         50;
+    --loading-overlay-duration-default:  var(--a-duration);
+    --loading-overlay-easing-default:    var(--a-easing-out);
+    --loading-overlay-gap-default:       var(--a-space-3);
+  }
+
+  /* ── Block 2 — BASE
+     Idle state: hidden but mounted. The element stays in the DOM so
+     state transitions on `[active]` animate; `display: none` would
+     skip the transition entirely. We pair `opacity: 0` with
+     `pointer-events: none` so the dim overlay doesn't intercept
+     clicks on the underlying content when idle. */
+  :scope {
+    box-sizing: border-box;
+    position: absolute;
+    inset: 0;
+    display: grid;
+    place-items: center;
+    gap: var(--loading-overlay-gap, var(--loading-overlay-gap-default));
+    background: var(--loading-overlay-bg, var(--loading-overlay-bg-default));
+    border-radius: var(--loading-overlay-radius, var(--loading-overlay-radius-default));
+    z-index: var(--loading-overlay-z, var(--loading-overlay-z-default));
+    opacity: 0;
+    pointer-events: none;
+    transition:
+      opacity var(--loading-overlay-duration, var(--loading-overlay-duration-default))
+              var(--loading-overlay-easing, var(--loading-overlay-easing-default));
+  }
+
+  /* ── Active state — fade in + capture pointer events ─────────────
+     Active state is gated by the delay timer in JS (see loading-overlay.class.js); by
+     the time `[active]` is set, the grace window has elapsed and the
+     overlay should paint immediately on next frame. */
+  :scope[active] {
+    opacity: 1;
+    pointer-events: auto;
+  }
+
+  /* ── Variants ─────────────────────────────────────────────────────
+     transparent: no backdrop fill — useful when the indicator IS the
+     overlay (e.g. a full-area skeleton stack). The parent is still
+     marked aria-busy and pointer events still blocked.
+     blur: light scrim plus backdrop-filter blur on the underlying
+     content. Use sparingly — Safari < 18 paint cost. */
+  :scope[variant="transparent"] {
+    --loading-overlay-bg-default: transparent;
+  }
+
+  :scope[variant="blur"] {
+    --loading-overlay-bg-default: var(--a-scrim-weak);
+    backdrop-filter: blur(4px);
+    -webkit-backdrop-filter: blur(4px);
+  }
+
+  /* ── Auto-stamped spinner sizing ──────────────────────────────────
+     When the default slot is empty, the JS layer auto-stamps a
+     `<spinner-ui size="lg">` child. Style it as the default centered
+     indicator so consumer slots and the auto-stamp render identically. */
+  :scope > spinner-ui {
+    --spinner-color: var(--a-fg-muted);
+  }
+
+  /* ── Reduced motion ───────────────────────────────────────────────
+     WCAG 2.3.3 — suppress the fade. The overlay still paints / hides
+     instantly (no transition), and the auto-stamped spinner falls
+     back to its own reduced-motion ellipsis via spinner.css. */
+  @media (prefers-reduced-motion: reduce) {
+    :scope {
+      transition: none;
+    }
+  }
+}

package/components/loading-overlay/loading-overlay.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `<loading-overlay-ui>` — Container-scoped busy overlay. Covers a positioned parent region with a centered spinner (auto-stamped) or slotted indicator (skeleton-ui, progress-ui, custom) while async work is in flight. Wires aria-busy onto the parent on connect; applies a [delay] grace window to avoid flash on fast loads. For viewport-scoped / route loaders use a dedicated route-loader pattern; for submit-button busy use <button-ui loading>.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/loading-overlay
+ *
+ * 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 UILoadingOverlay extends UIElement {
+  /** When set, overlay is visible and the parent container is marked aria-busy. Toggle from consumer code; default hidden. */
+  active: string;
+  /** Suppress the overlay until this many ms elapse. Prevents flash on fast loads. Default 200ms. */
+  delay: string;
+  /** Accessible operation name used by the host aria-label and forwarded to the auto-stamped spinner. */
+  label: string;
+  /** Backdrop treatment — default (muted scrim), transparent (no backdrop fill — useful with full-area skeleton indicators), blur (light scrim with backdrop-filter blur). */
+  variant: string;
+}

package/components/loading-overlay/loading-overlay.examples.md

@@ -0,0 +1,50 @@
+# loading-overlay — Examples
+
+## Default (auto-stamped spinner)
+
+The host parent must be positioned (`position: relative` or similar);
+the overlay does not mutate parent layout. When the default slot is
+empty, a centered `<spinner-ui size="lg">` is auto-stamped.
+
+```html
+<card-ui style="position: relative;">
+  <section>
+    <table-ui id="orders" data-stream-src="/api/orders"></table-ui>
+    <loading-overlay-ui active label="Loading orders…"></loading-overlay-ui>
+  </section>
+</card-ui>
+```
+
+## Skeleton placeholder
+
+Pair `variant="transparent"` with a slotted skeleton stack to render
+shape-of-content placeholders instead of a centered spinner.
+
+```html
+<div style="position: relative;">
+  <loading-overlay-ui active variant="transparent" label="Loading content">
+    <stack-ui>
+      <skeleton-ui width="100%" height="1rem"></skeleton-ui>
+      <skeleton-ui width="80%"  height="1rem"></skeleton-ui>
+      <skeleton-ui width="60%"  height="1rem"></skeleton-ui>
+    </stack-ui>
+  </loading-overlay-ui>
+</div>
+```
+
+## Fast-load (no flash)
+
+The default 200 ms grace window suppresses paint on fast-resolving
+loads. If the underlying work resolves before the timer fires, the
+overlay never paints.
+
+```html
+<loading-overlay-ui active delay="200"></loading-overlay-ui>
+```
+
+For known-slow operations (server-side jobs, large uploads) opt out
+with `delay="0"`:
+
+```html
+<loading-overlay-ui active delay="0" label="Generating report…"></loading-overlay-ui>
+```

package/components/loading-overlay/loading-overlay.js

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

package/components/loading-overlay/loading-overlay.test.js

@@ -0,0 +1,257 @@
+/**
+ * loading-overlay-ui tests — covers SPEC-034 § Verification.
+ *
+ * The component is JS-driven (delay timer + aria-busy bookkeeping) with
+ * a CSS-only fade transition. Tests split:
+ *
+ *   1. Defaults + property reflection.
+ *   2. aria-busy parent wiring (apply on activate, release on
+ *      deactivate / disconnect).
+ *   3. [delay] grace-window suppression — fast-load no-flash.
+ *   4. Auto-stamped spinner-ui (default slot empty) vs slotted content.
+ *   5. CSS source contract — two-block @scope, token surface, variants.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const LO_CSS = readFileSync(resolve(HERE, 'loading-overlay.css'), 'utf8');
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+beforeAll(async () => {
+  await import('./loading-overlay.js');
+  // Side-effect import so the auto-stamp can construct spinner-ui.
+  await import('../spinner/spinner.js');
+});
+
+function mountInPositionedParent(html) {
+  const parent = document.createElement('div');
+  parent.style.position = 'relative';
+  parent.style.width = '200px';
+  parent.style.height = '120px';
+  parent.id = 'lo-parent';
+  parent.innerHTML = html;
+  document.body.appendChild(parent);
+  return { parent, overlay: parent.querySelector('loading-overlay-ui') };
+}
+
+// ── 1. Defaults + property reflection ────────────────────────────────
+
+describe('loading-overlay-ui — defaults', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('renders without props using documented defaults', async () => {
+    const { overlay } = mountInPositionedParent('<loading-overlay-ui></loading-overlay-ui>');
+    await tick();
+    expect(overlay.active).toBe(false);
+    expect(overlay.delay).toBe(200);
+    expect(overlay.label).toBe('Loading…');
+    expect(overlay.variant).toBe('default');
+  });
+
+  it('sets role="status" + aria-live="polite" on the host', async () => {
+    const { overlay } = mountInPositionedParent('<loading-overlay-ui></loading-overlay-ui>');
+    await tick();
+    expect(overlay.getAttribute('role')).toBe('status');
+    expect(overlay.getAttribute('aria-live')).toBe('polite');
+  });
+
+  it('seeds aria-label from the [label] prop', async () => {
+    const { overlay } = mountInPositionedParent('<loading-overlay-ui label="Saving"></loading-overlay-ui>');
+    await tick();
+    expect(overlay.getAttribute('aria-label')).toBe('Saving');
+  });
+
+  it('reflects [active], [variant], [delay], [label] to the host attributes', async () => {
+    const { overlay } = mountInPositionedParent('<loading-overlay-ui active variant="blur" delay="500" label="Wait"></loading-overlay-ui>');
+    await tick();
+    expect(overlay.hasAttribute('active')).toBe(true);
+    expect(overlay.getAttribute('variant')).toBe('blur');
+    expect(overlay.getAttribute('delay')).toBe('500');
+    expect(overlay.getAttribute('label')).toBe('Wait');
+  });
+});
+
+// ── 2. aria-busy parent wiring ───────────────────────────────────────
+
+describe('loading-overlay-ui — aria-busy parent wiring', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    vi.useFakeTimers();
+  });
+  afterEach(() => { vi.useRealTimers(); });
+
+  it('applies aria-busy="true" to parent on activate (after delay)', async () => {
+    const { parent } = mountInPositionedParent('<loading-overlay-ui delay="0"></loading-overlay-ui>');
+    await tick();
+    const overlay = parent.querySelector('loading-overlay-ui');
+    expect(parent.hasAttribute('aria-busy')).toBe(false);
+    overlay.active = true;
+    // delay=0 → applies synchronously via setTimeout(0)
+    vi.advanceTimersByTime(0);
+    expect(parent.getAttribute('aria-busy')).toBe('true');
+  });
+
+  it('releases aria-busy on deactivate', async () => {
+    const { parent } = mountInPositionedParent('<loading-overlay-ui active delay="0"></loading-overlay-ui>');
+    await tick();
+    vi.advanceTimersByTime(0);
+    expect(parent.getAttribute('aria-busy')).toBe('true');
+
+    const overlay = parent.querySelector('loading-overlay-ui');
+    overlay.active = false;
+    expect(parent.hasAttribute('aria-busy')).toBe(false);
+  });
+
+  it('releases aria-busy on disconnect', async () => {
+    const { parent } = mountInPositionedParent('<loading-overlay-ui active delay="0"></loading-overlay-ui>');
+    await tick();
+    vi.advanceTimersByTime(0);
+    expect(parent.getAttribute('aria-busy')).toBe('true');
+
+    const overlay = parent.querySelector('loading-overlay-ui');
+    overlay.remove();
+    expect(parent.hasAttribute('aria-busy')).toBe(false);
+  });
+
+  it('honors mount-time [active] (declarative)', async () => {
+    const { parent } = mountInPositionedParent('<loading-overlay-ui active delay="0"></loading-overlay-ui>');
+    await tick();
+    vi.advanceTimersByTime(0);
+    expect(parent.getAttribute('aria-busy')).toBe('true');
+  });
+});
+
+// ── 3. [delay] grace window ──────────────────────────────────────────
+
+describe('loading-overlay-ui — [delay] grace window', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+    vi.useFakeTimers();
+  });
+  afterEach(() => { vi.useRealTimers(); });
+
+  it('suppresses paint when [active] is cleared before delay expires', async () => {
+    const { parent } = mountInPositionedParent('<loading-overlay-ui delay="200"></loading-overlay-ui>');
+    await tick();
+    const overlay = parent.querySelector('loading-overlay-ui');
+
+    overlay.active = true;
+    // Within the grace window — parent should NOT be marked yet.
+    vi.advanceTimersByTime(100);
+    expect(parent.hasAttribute('aria-busy')).toBe(false);
+
+    // Clear before timer fires.
+    overlay.active = false;
+    vi.advanceTimersByTime(200);
+    expect(parent.hasAttribute('aria-busy')).toBe(false);
+  });
+
+  it('paints after delay elapses when [active] stays true', async () => {
+    const { parent } = mountInPositionedParent('<loading-overlay-ui delay="200"></loading-overlay-ui>');
+    await tick();
+    const overlay = parent.querySelector('loading-overlay-ui');
+
+    overlay.active = true;
+    expect(parent.hasAttribute('aria-busy')).toBe(false);
+    vi.advanceTimersByTime(200);
+    expect(parent.getAttribute('aria-busy')).toBe('true');
+  });
+});
+
+// ── 4. Default-slot auto-stamp ───────────────────────────────────────
+
+describe('loading-overlay-ui — auto-stamped spinner', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('auto-stamps a <spinner-ui size="lg"> when default slot is empty', async () => {
+    const { overlay } = mountInPositionedParent('<loading-overlay-ui></loading-overlay-ui>');
+    await tick();
+    const sp = overlay.querySelector(':scope > spinner-ui[data-loading-overlay-auto]');
+    expect(sp).not.toBeNull();
+    expect(sp.getAttribute('size')).toBe('lg');
+  });
+
+  it('does NOT auto-stamp when consumer slots their own indicator', async () => {
+    const { overlay } = mountInPositionedParent(
+      '<loading-overlay-ui><skeleton-ui width="100%" height="1rem"></skeleton-ui></loading-overlay-ui>'
+    );
+    await tick();
+    expect(overlay.querySelector(':scope > spinner-ui[data-loading-overlay-auto]')).toBeNull();
+    expect(overlay.querySelector(':scope > skeleton-ui')).not.toBeNull();
+  });
+
+  it('forwards [label] changes to the auto-stamped spinner', async () => {
+    const { overlay } = mountInPositionedParent('<loading-overlay-ui label="Loading"></loading-overlay-ui>');
+    await tick();
+    overlay.label = 'Uploading';
+    await tick();
+    const sp = overlay.querySelector(':scope > spinner-ui[data-loading-overlay-auto]');
+    expect(sp.getAttribute('label')).toBe('Uploading');
+  });
+});
+
+// ── 5. CSS source contract ───────────────────────────────────────────
+
+describe('loading-overlay-ui — CSS source contract', () => {
+  it('opens with the canonical @scope (loading-overlay-ui) block', () => {
+    expect(LO_CSS).toMatch(/^@scope \(loading-overlay-ui\)/);
+  });
+
+  it('declares both the :where(:scope) token block and a :scope base block', () => {
+    expect(LO_CSS).toMatch(/:where\(:scope\)\s*\{/);
+    expect(LO_CSS).toMatch(/^\s*:scope\s*\{/m);
+  });
+
+  it('declares the documented component tokens with -default suffix', () => {
+    for (const tok of [
+      '--loading-overlay-bg-default',
+      '--loading-overlay-radius-default',
+      '--loading-overlay-z-default',
+      '--loading-overlay-duration-default',
+      '--loading-overlay-easing-default',
+      '--loading-overlay-gap-default',
+    ]) {
+      expect(LO_CSS).toContain(tok);
+    }
+  });
+
+  it('positions absolutely with inset:0 (fills the parent)', () => {
+    expect(LO_CSS).toMatch(/position:\s*absolute/);
+    expect(LO_CSS).toMatch(/inset:\s*0/);
+  });
+
+  it('idle state: opacity:0 + pointer-events:none', () => {
+    // The base :scope block carries both — fail-fast if either is dropped.
+    expect(LO_CSS).toMatch(/opacity:\s*0/);
+    expect(LO_CSS).toMatch(/pointer-events:\s*none/);
+  });
+
+  it('active state: opacity:1 + pointer-events:auto', () => {
+    expect(LO_CSS).toMatch(/:scope\[active\][^}]*opacity:\s*1/);
+    expect(LO_CSS).toMatch(/:scope\[active\][^}]*pointer-events:\s*auto/);
+  });
+
+  it('transparent variant drops the backdrop fill', () => {
+    expect(LO_CSS).toMatch(/:scope\[variant="transparent"\][^}]*--loading-overlay-bg-default:\s*transparent/);
+  });
+
+  it('blur variant applies backdrop-filter blur', () => {
+    expect(LO_CSS).toMatch(/:scope\[variant="blur"\][^}]*backdrop-filter:\s*blur/);
+  });
+
+  it('reduced-motion media query suppresses the fade transition', () => {
+    expect(LO_CSS).toMatch(/@media\s*\(prefers-reduced-motion:\s*reduce\)/);
+    expect(LO_CSS).toMatch(/transition:\s*none/);
+  });
+
+  it('uses semantic --a-* tokens; no raw hex / rgb / oklch in the file', () => {
+    expect(LO_CSS).not.toMatch(/#[0-9a-fA-F]{3,8}\b/);
+    expect(LO_CSS).not.toMatch(/\brgb\s*\(/);
+    expect(LO_CSS).not.toMatch(/\boklch\s*\(/);
+  });
+});