@adia-ai/web-components 0.6.33 → 0.6.35

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*\(/);
+  });
+});