@adia-ai/web-components 0.6.33 → 0.6.35

package/components/list-window/list-window.yaml

@@ -0,0 +1,270 @@
+# Authored 2026-05-23 for SPEC-022 (Virtualized / Windowed List). The
+# component name in catalog metadata reads "Virtualized Windowed List"
+# for retrieval / searchability; the tag is the shorter `list-window-ui`
+# which lives alongside `<list-ui>` / `<list-item-ui>` in the list-*
+# namespace.
+#
+# Edit this file; run `npm run build:components` to regenerate the
+# `list-window.a2ui.json` sidecar. Never hand-edit the .a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIListWindow
+tag: list-window-ui
+status: stable
+component: ListWindow
+category: display
+version: 1
+description: >-
+  Virtualized / windowed list primitive. Renders only the visible slice
+  of a large items[] array (chat threads, feeds, log streams, nav lists,
+  search-result panes) — typically ≤50 DOM rows regardless of the
+  underlying collection size. Composes a `render`-function prop OR a
+  slotted <template> for row materialization; ships a fixed-size
+  fast-path (constant-time index→offset math) and a variable-size
+  measurement fallback. Distinct from <list-ui> (renders every child,
+  preferred for short lists < 50 items) and <table-ui> (tabular data
+  with columns). Use list-window-ui when items.length is large enough
+  that rendering every row would block the main thread or stutter
+  scroll.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - skeleton-ui
+props:
+  items:
+    description: The items to virtualize. Required for prop-driven authoring; ignored when data-stream-src is set.
+    type: array
+    default: []
+  itemSize:
+    description: Fixed item height in pixels. When > 0, uses the constant-time fast path (avoids per-row measurement).
+    type: number
+    default: 0
+    reflect: true
+    attribute: item-size
+  itemSizeRem:
+    description: Fixed item height in rem. Useful for typographic-scale rows that should track the body type.
+    type: number
+    default: 0
+    reflect: true
+    attribute: item-size-rem
+  estimatedSize:
+    description: Initial guess for variable-height rows. Used until the first measurement pass refines the offset cache.
+    type: number
+    default: 48
+    reflect: true
+    attribute: estimated-size
+  overscan:
+    description: >-
+      Rows to render above + below the visible window. 0–20 is reasonable; > 50 negates the windowing benefit.
+    type: number
+    default: 3
+    reflect: true
+  direction:
+    description: Scroll axis — vertical (default) or horizontal carousel.
+    type: string
+    default: vertical
+    enum:
+      - vertical
+      - horizontal
+    reflect: true
+  pinBottom:
+    description: When appending items, keep scroll pinned to the bottom (chat-thread / log-tail pattern).
+    type: boolean
+    default: false
+    reflect: true
+    attribute: pin-bottom
+  startIndex:
+    description: Index to scroll to on mount. Useful for restoring scroll position on remount.
+    type: number
+    default: 0
+    attribute: start-index
+  loading:
+    description: Render skeleton rows in the visible window. Sets aria-busy="true" on the host.
+    type: boolean
+    default: false
+    reflect: true
+events:
+  range-change:
+    description: Fired when the visible row range (start/end indices) changes due to scroll.
+    detail:
+      startIndex:
+        type: number
+        description: First rendered row index.
+      endIndex:
+        type: number
+        description: Last rendered row index (exclusive).
+      items:
+        type: array
+        description: The items currently materialized in the window.
+  item-click:
+    description: Fired when a rendered row is clicked.
+    detail:
+      item:
+        description: The clicked item (full item-shape from items[]).
+      index:
+        type: number
+        description: Item index in the full items[] array.
+  scroll-end:
+    description: Fired when the user scrolls to the bottom (within 1 viewport). Use for infinite-load patterns.
+    detail:
+      index:
+        type: number
+        description: Last visible row index.
+  scroll-start:
+    description: Fired when the user scrolls to the top (within 1 viewport). Use for "load older" patterns.
+    detail:
+      index:
+        type: number
+        description: First visible row index.
+  measure:
+    description: Fired when a variable-height row is measured. Useful for instrumenting the offset cache.
+    detail:
+      index:
+        type: number
+        description: Index of the row that was measured.
+      height:
+        type: number
+        description: Measured row height in pixels.
+slots:
+  default:
+    description: A single <template> element used to clone rows (declarative-template authoring). Mutually exclusive with the render prop.
+  empty:
+    description: Custom empty-state content when items.length === 0.
+  loading:
+    description: Custom skeleton row template; falls back to <skeleton-ui> when omitted.
+  before:
+    description: Sticky-top content (filter chips, summary stat).
+  after:
+    description: Sticky-bottom content (composer, "load older" button).
+states:
+  - name: idle
+    description: Default — rendering and reconciling normally.
+  - name: loading
+    attribute: loading
+    description: Skeleton rows; data fetch in flight.
+  - name: empty
+    attribute: empty
+    description: items.length === 0.
+  - name: measuring
+    attribute: measuring
+    description: First-mount measurement pass on variable-height rows; suppresses scroll-end events.
+  - name: disabled
+    attribute: disabled
+    description: Pointer events blocked.
+traits: []
+tokens:
+  --list-window-bg:
+    description: Host background (defaults to --a-bg).
+  --list-window-row-gap:
+    description: Row spacing in the visible window (defaults to --a-space-1).
+  --list-window-overscan-bg:
+    description: Visible buffer rows background — transparent by default.
+  --list-window-sentinel-size:
+    description: Top + bottom IntersectionObserver-target sentinel size (defaults to --a-space-2).
+keywords:
+  - list-window
+  - virtualized
+  - windowed
+  - virtual-scroll
+  - infinite-scroll
+  - large-list
+  - feed
+  - chat-thread
+  - log-stream
+  - 10k-rows
+synonyms:
+  virtualized:
+    - virtual-scroll
+    - windowed
+    - list-window
+  windowed:
+    - virtualized
+    - virtual-scroll
+    - list-window
+  virtual-scroll:
+    - virtualized
+    - windowed
+    - list-window
+  infinite-scroll:
+    - virtualized
+    - virtual-scroll
+    - list-window
+  large-list:
+    - virtualized
+    - list-window
+related:
+  - List
+  - ListItem
+  - Feed
+  - ChatThread
+  - Table
+a2ui:
+  rules:
+    - rule: 'ListWindow.items MUST be an array of plain objects OR scalars. Functions / DOM nodes / Promises are invalid.'
+      reason: 'Items are reconciled via key-fn + serialized to row DOM; non-data values cannot survive the round-trip.'
+    - rule: 'ListWindow.render cannot be expressed in A2UI JSON — declarative authoring MUST use a <template> child (or default <list-item-ui> for objects with a text field).'
+      reason: 'A2UI is a JSON catalog; function values have no transport.'
+    - rule: 'When items.length > 200, the validator SHOULD recommend ListWindow over List to keep the DOM tractable.'
+      reason: 'List renders every item; at large N the cost is super-linear in layout / paint / memory.'
+    - rule: 'ListWindow MUST have a defined height (via parent layout or style="height:..."). An unbounded-height windowed list defeats the windowing math.'
+      reason: 'Without a viewport bound the scroll container has no visible-window size; every item would mount.'
+    - rule: 'ListWindow.item-size SHOULD be set when item heights are known and constant — the fast-path is significantly cheaper.'
+      reason: 'Constant-time index→offset math beats per-row measurement.'
+    - rule: 'Do NOT nest ListWindow inside another scroll container; double-scroll containers break the IntersectionObserver math. Use one scroll boundary.'
+      reason: 'Nested scroll containers create ambiguous visible-window targets.'
+    - rule: 'Do NOT use ListWindow for short lists (< 50 items). The windowing overhead exceeds the cost of rendering all rows. Use List for short lists.'
+      reason: 'Below the windowing threshold the bookkeeping is pure cost.'
+    - rule: 'Do NOT use for tabular data — that is Table with virtualized rows.'
+      reason: 'Different surface; Table owns columns + grid roles.'
+anti_patterns:
+  - wrong: |
+      { "component": "List", "items": [/* 10000 items */] }
+    why: |
+      Rendering 10k items into <list-ui> blows up the DOM and main thread. Scroll
+      jank, mount lag, and memory pressure all degrade.
+    fix: |
+      { "component": "ListWindow", "items": [/* 10000 items */], "item-size": 48 }
+  - wrong: |
+      { "component": "ListWindow", "items": [/* … */] }
+      (with no parent height + no item-size + no estimated-size)
+    why: |
+      Without a height bound, the scroll container has no viewport, so the windowing
+      math reports "all items visible" and the whole list mounts.
+    fix: |
+      Wrap in a container with a height, or set style="height:480px" on the
+      ListWindow itself.
+  - wrong: |
+      { "component": "ListWindow", "overscan": 200, "items": [/* … */] }
+    why: |
+      Overscan=200 materializes 200 rows above + below the viewport. That defeats
+      the entire point of windowing.
+    fix: |
+      { "component": "ListWindow", "overscan": 5, "items": [/* … */] }
+examples:
+  - name: chat-thread-list
+    description: Virtualized chat-thread message list with declarative <template> rows.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Card",
+          "children": ["thread"]
+        },
+        {
+          "id": "thread",
+          "component": "ListWindow",
+          "item-size": 56,
+          "overscan": 5,
+          "pin-bottom": true
+        }
+      ]
+  - name: log-tail-stream
+    description: SSE-streamed JSONL log tail with sticky-bottom pin.
+    a2ui: >-
+      [
+        {
+          "id": "logs",
+          "component": "ListWindow",
+          "item-size": 24,
+          "pin-bottom": true
+        }
+      ]

package/components/loading-overlay/loading-overlay.a2ui.json

@@ -0,0 +1,176 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/LoadingOverlay.json",
+  "title": "LoadingOverlay",
+  "description": "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>.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "active": {
+      "description": "When set, overlay is visible and the parent container is marked aria-busy. Toggle from consumer code; default hidden.",
+      "$ref": "common_types.json#/$defs/DynamicBoolean"
+    },
+    "component": {
+      "const": "LoadingOverlay"
+    },
+    "delay": {
+      "description": "Suppress the overlay until this many ms elapse. Prevents flash on fast loads. Default 200ms.",
+      "$ref": "common_types.json#/$defs/DynamicNumber"
+    },
+    "label": {
+      "description": "Accessible operation name used by the host aria-label and forwarded to the auto-stamped spinner.",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    },
+    "variant": {
+      "description": "Backdrop treatment — default (muted scrim), transparent (no backdrop fill — useful with full-area skeleton indicators), blur (light scrim with backdrop-filter blur).",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "{\"component\": \"Card\", \"children\": [\n  {\"component\": \"LoadingOverlay\", \"active\": true},\n  {\"component\": \"Table\", \"data-stream-src\": \"...\"}\n]}\n",
+        "why": "LoadingOverlay is container-scoped. Attaching it directly to Page\ncovers the entire viewport but lacks the route-loader's wiring\n(skeleton routing, route-level animation). Use the route loader.\n",
+        "wrong": "{\"component\": \"Page\", \"children\": [\n  {\"component\": \"LoadingOverlay\", \"active\": true}\n]}\n"
+      },
+      {
+        "fix": "{\"component\": \"Modal\", \"open\": true, \"loading\": true}\n",
+        "why": "Modal owns its own busy state and focus trap; nesting a\nLoadingOverlay introduces two competing inert toggles.\n",
+        "wrong": "{\"component\": \"Modal\", \"open\": true, \"children\": [\n  {\"component\": \"LoadingOverlay\", \"active\": true}\n]}\n"
+      },
+      {
+        "fix": "{\"component\": \"Form\", \"children\": [\n  {\"component\": \"Button\", \"text\": \"Submitting\", \"type\": \"submit\", \"loading\": true, \"disabled\": true}\n]}\n",
+        "why": "A form-submit affordance belongs on the button itself, not as an\noverlay over the entire form region. Use Button[loading].\n",
+        "wrong": "{\"component\": \"Form\", \"children\": [\n  {\"component\": \"Button\", \"text\": \"Submit\", \"type\": \"submit\"},\n  {\"component\": \"LoadingOverlay\", \"active\": true}\n]}\n"
+      }
+    ],
+    "category": "feedback",
+    "composes": [],
+    "events": {},
+    "examples": [
+      {
+        "description": "Card containing a table that loads on mount; the overlay covers the card's body while data streams.",
+        "a2ui": "[\n  {\n    \"id\": \"card\",\n    \"component\": \"Card\",\n    \"children\": [\"sec\"]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\"overlay\", \"table\"]\n  },\n  {\n    \"id\": \"overlay\",\n    \"component\": \"LoadingOverlay\",\n    \"active\": true,\n    \"label\": \"Loading orders…\"\n  },\n  {\n    \"id\": \"table\",\n    \"component\": \"Table\",\n    \"data-stream-src\": \"/api/orders\"\n  }\n]",
+        "name": "card-with-loading-table"
+      },
+      {
+        "description": "Skeleton-shaped placeholder overlay using the transparent variant — slot a stack of <Skeleton> rows.",
+        "a2ui": "[\n  {\n    \"id\": \"ov\",\n    \"component\": \"LoadingOverlay\",\n    \"active\": true,\n    \"variant\": \"transparent\",\n    \"label\": \"Loading content…\",\n    \"children\": [\"sk-stack\"]\n  },\n  {\n    \"id\": \"sk-stack\",\n    \"component\": \"Column\",\n    \"gap\": \"2\",\n    \"children\": [\"sk1\", \"sk2\", \"sk3\"]\n  },\n  {\n    \"id\": \"sk1\",\n    \"component\": \"Skeleton\",\n    \"width\": \"100%\",\n    \"height\": \"1rem\"\n  },\n  {\n    \"id\": \"sk2\",\n    \"component\": \"Skeleton\",\n    \"width\": \"80%\",\n    \"height\": \"1rem\"\n  },\n  {\n    \"id\": \"sk3\",\n    \"component\": \"Skeleton\",\n    \"width\": \"60%\",\n    \"height\": \"1rem\"\n  }\n]",
+        "name": "skeleton-overlay"
+      },
+      {
+        "description": "Overlay with the default 200ms grace window. If the underlying load resolves in less than 200ms, the overlay never paints.",
+        "a2ui": "[\n  {\n    \"id\": \"ov\",\n    \"component\": \"LoadingOverlay\",\n    \"active\": true,\n    \"delay\": 200,\n    \"label\": \"Loading\"\n  }\n]",
+        "name": "fast-load-no-flash"
+      }
+    ],
+    "keywords": [
+      "loading",
+      "overlay",
+      "busy",
+      "spinner",
+      "skeleton",
+      "placeholder",
+      "feedback",
+      "progress",
+      "indicator",
+      "wait"
+    ],
+    "name": "UILoadingOverlay",
+    "related": [
+      "Spinner",
+      "Skeleton",
+      "Progress",
+      "Card",
+      "Table",
+      "Modal"
+    ],
+    "slots": {
+      "default": {
+        "description": "Busy indicator content — <spinner-ui>, <skeleton-ui>, <progress-ui>, or custom. If empty, a centered <spinner-ui size=\"lg\"> is auto-stamped."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, hidden. Parent interactive.",
+        "name": "idle"
+      },
+      {
+        "description": "Overlay visible; parent has aria-busy=\"true\".",
+        "attribute": "active",
+        "name": "active"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "busy": [
+        "loading",
+        "overlay",
+        "busy",
+        "spinner"
+      ],
+      "loader": [
+        "loading",
+        "overlay",
+        "spinner"
+      ],
+      "loading": [
+        "loading",
+        "overlay",
+        "busy",
+        "spinner",
+        "skeleton"
+      ],
+      "overlay": [
+        "loading",
+        "overlay",
+        "busy"
+      ],
+      "spinner": [
+        "loading",
+        "overlay",
+        "spinner"
+      ]
+    },
+    "tag": "loading-overlay-ui",
+    "tokens": {
+      "--loading-overlay-bg": {
+        "description": "Backdrop fill color. Default uses the generic neutral scrim token.",
+        "default": "var(--a-scrim-default)"
+      },
+      "--loading-overlay-duration": {
+        "description": "Fade in / fade out duration.",
+        "default": "var(--a-duration)"
+      },
+      "--loading-overlay-easing": {
+        "description": "Fade easing curve.",
+        "default": "var(--a-easing-out)"
+      },
+      "--loading-overlay-gap": {
+        "description": "Vertical gap between the indicator and any sibling content (e.g. label, skeleton stack).",
+        "default": "var(--a-space-3)"
+      },
+      "--loading-overlay-radius": {
+        "description": "Backdrop corner radius. Matches the parent surface by default.",
+        "default": "var(--a-radius-md)"
+      },
+      "--loading-overlay-z": {
+        "description": "Stacking order. Sits above sibling content, below modal-ui (which uses ::backdrop on top-layer dialog).",
+        "default": "50"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

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);
+  }
+}