@adia-ai/web-components 0.6.33 → 0.6.35

package/components/loading-overlay/loading-overlay.yaml

@@ -0,0 +1,260 @@
+# Hand-authored per SPEC-034 (docs/specs/implementation-ready/SPEC-034-loading-overlay.md).
+# Edit this file; run `npm run build:components` to regenerate loading-overlay.a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UILoadingOverlay
+tag: loading-overlay-ui
+status: stable
+component: LoadingOverlay
+category: feedback
+version: 1
+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>.
+props:
+  active:
+    description: When set, overlay is visible and the parent container is marked aria-busy. Toggle from consumer code; default hidden.
+    type: boolean
+    default: false
+    reflect: true
+    dynamic: true
+  delay:
+    description: Suppress the overlay until this many ms elapse. Prevents flash on fast loads. Default 200ms.
+    type: number
+    default: 200
+    reflect: true
+    dynamic: true
+  label:
+    description: Accessible operation name used by the host aria-label and forwarded to the auto-stamped spinner.
+    type: string
+    default: Loading…
+    reflect: true
+    dynamic: true
+  variant:
+    description: Backdrop treatment — default (muted scrim), transparent (no backdrop fill — useful with full-area skeleton indicators), blur (light scrim with backdrop-filter blur).
+    type: string
+    default: default
+    enum:
+      - default
+      - transparent
+      - blur
+    reflect: true
+    dynamic: true
+events: {}
+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:
+  - name: idle
+    description: Default, hidden. Parent interactive.
+  - name: active
+    description: Overlay visible; parent has aria-busy="true".
+    attribute: active
+traits: []
+tokens:
+  --loading-overlay-bg:
+    description: Backdrop fill color. Default uses the generic neutral scrim token.
+    default: var(--a-scrim-default)
+  --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'
+  --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)
+a2ui:
+  rules:
+    - >-
+      <LoadingOverlay> MUST be placed inside a sized container with
+      content (Card, Section, Table body, Chart). It absolutely positions
+      against the nearest positioned ancestor. The parent's CSS must
+      include `position: relative` (or any non-static positioning) — the
+      component does not mutate parent layout styles.
+    - >-
+      Toggle <LoadingOverlay active> from consumer code while async work
+      is in flight. The overlay applies aria-busy="true" to its parent
+      while active; on dismiss, both inert and aria-busy are released.
+    - >-
+      The [delay] grace window (default 200ms) suppresses paint on
+      fast-resolving loads. For server-rendered "definitely-slow" states
+      (>1s known wait) consider [delay="0"] for immediate feedback.
+    - >-
+      Do NOT use as a page-level / viewport loader — use a dedicated
+      route-loader pattern. <LoadingOverlay> is container-scoped.
+    - >-
+      Do NOT nest <LoadingOverlay> inside <Modal> or <Drawer> — those
+      primitives own their own busy state. When they support it, pass
+      [loading] to those directly.
+    - >-
+      Do NOT use <LoadingOverlay> to disable a form during submit — use
+      <Button type="submit" loading> for the submit affordance.
+    - >-
+      The default slot accepts any busy indicator. When empty, a
+      centered <Spinner size="lg"> is auto-stamped. Slot a <Skeleton>
+      stack for placeholder-shaped loading; slot <Progress value=…> when
+      the wait is determinate.
+anti_patterns:
+  - wrong: |
+      {"component": "Page", "children": [
+        {"component": "LoadingOverlay", "active": true}
+      ]}
+    why: |
+      LoadingOverlay is container-scoped. Attaching it directly to Page
+      covers the entire viewport but lacks the route-loader's wiring
+      (skeleton routing, route-level animation). Use the route loader.
+    fix: |
+      {"component": "Card", "children": [
+        {"component": "LoadingOverlay", "active": true},
+        {"component": "Table", "data-stream-src": "..."}
+      ]}
+  - wrong: |
+      {"component": "Modal", "open": true, "children": [
+        {"component": "LoadingOverlay", "active": true}
+      ]}
+    why: |
+      Modal owns its own busy state and focus trap; nesting a
+      LoadingOverlay introduces two competing inert toggles.
+    fix: |
+      {"component": "Modal", "open": true, "loading": true}
+  - wrong: |
+      {"component": "Form", "children": [
+        {"component": "Button", "text": "Submit", "type": "submit"},
+        {"component": "LoadingOverlay", "active": true}
+      ]}
+    why: |
+      A form-submit affordance belongs on the button itself, not as an
+      overlay over the entire form region. Use Button[loading].
+    fix: |
+      {"component": "Form", "children": [
+        {"component": "Button", "text": "Submitting", "type": "submit", "loading": true, "disabled": true}
+      ]}
+examples:
+  - name: card-with-loading-table
+    description: Card containing a table that loads on mount; the overlay covers the card's body while data streams.
+    a2ui: >-
+      [
+        {
+          "id": "card",
+          "component": "Card",
+          "children": ["sec"]
+        },
+        {
+          "id": "sec",
+          "component": "Section",
+          "children": ["overlay", "table"]
+        },
+        {
+          "id": "overlay",
+          "component": "LoadingOverlay",
+          "active": true,
+          "label": "Loading orders…"
+        },
+        {
+          "id": "table",
+          "component": "Table",
+          "data-stream-src": "/api/orders"
+        }
+      ]
+  - name: skeleton-overlay
+    description: Skeleton-shaped placeholder overlay using the transparent variant — slot a stack of <Skeleton> rows.
+    a2ui: >-
+      [
+        {
+          "id": "ov",
+          "component": "LoadingOverlay",
+          "active": true,
+          "variant": "transparent",
+          "label": "Loading content…",
+          "children": ["sk-stack"]
+        },
+        {
+          "id": "sk-stack",
+          "component": "Column",
+          "gap": "2",
+          "children": ["sk1", "sk2", "sk3"]
+        },
+        {
+          "id": "sk1",
+          "component": "Skeleton",
+          "width": "100%",
+          "height": "1rem"
+        },
+        {
+          "id": "sk2",
+          "component": "Skeleton",
+          "width": "80%",
+          "height": "1rem"
+        },
+        {
+          "id": "sk3",
+          "component": "Skeleton",
+          "width": "60%",
+          "height": "1rem"
+        }
+      ]
+  - name: fast-load-no-flash
+    description: Overlay with the default 200ms grace window. If the underlying load resolves in less than 200ms, the overlay never paints.
+    a2ui: >-
+      [
+        {
+          "id": "ov",
+          "component": "LoadingOverlay",
+          "active": true,
+          "delay": 200,
+          "label": "Loading"
+        }
+      ]
+keywords:
+  - loading
+  - overlay
+  - busy
+  - spinner
+  - skeleton
+  - placeholder
+  - feedback
+  - progress
+  - indicator
+  - wait
+synonyms:
+  loading:
+    - loading
+    - overlay
+    - busy
+    - spinner
+    - skeleton
+  overlay:
+    - loading
+    - overlay
+    - busy
+  busy:
+    - loading
+    - overlay
+    - busy
+    - spinner
+  spinner:
+    - loading
+    - overlay
+    - spinner
+  loader:
+    - loading
+    - overlay
+    - spinner
+related:
+  - Spinner
+  - Skeleton
+  - Progress
+  - Card
+  - Table
+  - Modal

package/components/menu/menu-divider.yaml

@@ -1,7 +1,7 @@
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
 #
 # §228 (v0.5.9): authored to close the §229 baseline class-export-undeclared
-# drift for UIMenuDivider. Ships as a sibling class in menu/class.js +
+# drift for UIMenuDivider. Ships as a sibling class in menu/menu.class.js +
 # is registered alongside UIMenu + UIMenuItem.
 
 # Child component of <menu-ui>. Surface only inside that parent.

package/components/menu/menu-item.yaml

@@ -1,7 +1,7 @@
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
 #
 # §228 (v0.5.9): authored to close the §229 baseline class-export-undeclared
-# drift for UIMenuItem. The item ships as a sibling class in menu/class.js
+# drift for UIMenuItem. The item ships as a sibling class in menu/menu.class.js
 # + is registered alongside UIMenu + UIMenuDivider.
 
 # Child component of <menu-ui>. Surface only inside that parent.

package/components/menu/menu.a2ui.json

@@ -91,6 +91,9 @@
     "slots": {
       "default": {
         "description": "Menu items with role=\"menuitem\" and optional <hr> dividers"
+      },
+      "trigger": {
+        "description": "Required. Focusable element that opens the menu when activated. Exactly one child must have slot=\"trigger\" — typically <button-ui>, but any focusable element works. Without it the menu cannot open via keyboard or pointer. Lives in light DOM; the items are hoisted to a top-layer popover on open."
       }
     },
     "states": [

package/components/menu/menu.css

@@ -1,13 +1,13 @@
 @scope (menu-ui) {
   :where(:scope) {
-    --menu-popover-padding:    var(--a-space-1);
-    --menu-popover-border:     var(--a-border-subtle);
-    --menu-popover-radius:     var(--a-radius-lg);
-    --menu-popover-bg:         var(--a-bg-subtle);
-    --menu-popover-shadow:     var(--a-shadow-lg);
-    --menu-popover-min-width:  10rem;
-    --menu-popover-font-size:  var(--a-ui-size);
-    --menu-popover-fg:         var(--a-fg);
+    --menu-popover-padding-default:    var(--a-space-1);
+    --menu-popover-border-default:     var(--a-border-subtle);
+    --menu-popover-radius-default:     var(--a-radius-lg);
+    --menu-popover-bg-default:         var(--a-bg-subtle);
+    --menu-popover-shadow-default:     var(--a-shadow-lg);
+    --menu-popover-min-width-default:  10rem;
+    --menu-popover-font-size-default:  var(--a-ui-size);
+    --menu-popover-fg-default:         var(--a-fg);
   }
 
   :scope {

package/components/menu/menu.js

@@ -10,7 +10,7 @@
  */
 
 import { defineIfFree } from '../../core/register.js';
-import { UIMenu, UIMenuItem, UIMenuDivider } from './class.js';
+import { UIMenu, UIMenuItem, UIMenuDivider } from './menu.class.js';
 
 defineIfFree('menu-ui', UIMenu);
 defineIfFree('menu-item-ui', UIMenuItem);

package/components/menu/menu.yaml

@@ -42,6 +42,13 @@ events:
         type: string
         description: Menu item text.
 slots:
+  trigger:
+    description: >-
+      Required. Focusable element that opens the menu when activated.
+      Exactly one child must have slot="trigger" — typically <button-ui>,
+      but any focusable element works. Without it the menu cannot open
+      via keyboard or pointer. Lives in light DOM; the items are
+      hoisted to a top-layer popover on open.
   default:
     description: Menu items with role="menuitem" and optional <hr> dividers
 states:

package/components/modal/{class.js → modal.class.js}

@@ -142,7 +142,18 @@ export class UIModal extends UIElement {
 
     const header = this.ensure('header');
     if (header.parentElement !== panel) panel.prepend(header);
-    header.setAttribute('text', this.text);
+    // Only set `text=` when actually present — the CSS rule
+    // `:scope [slot="header"][text]:not([text=""])::before { content: attr(text); flex: 1 }`
+    // generates a flex:1 pseudo-element. Setting `text=""` unconditionally
+    // creates a phantom flex slot that pushes slotted title content
+    // (e.g., confirm-dialog-ui's stamped <text-ui slot="heading">) to the
+    // trailing edge of the header row. Defense-in-depth alongside the
+    // CSS gate.
+    if (this.text) {
+      header.setAttribute('text', this.text);
+    } else {
+      header.removeAttribute('text');
+    }
 
     if (!this.permanent) {
       const close = this.ensure('close');

package/components/modal/modal.css

@@ -9,24 +9,24 @@
 
 @scope (modal-ui) {
   :where(:scope) {
-    --modal-width:          32rem;
-    --modal-radius:         var(--a-radius-lg);
-    --modal-bg:             var(--a-bg-subtle);
-    --modal-border:         var(--a-border-subtle);
-    --modal-shadow:         var(--a-shadow-lg);
-    --modal-backdrop:       var(--a-scrim-dialog);
-    --modal-duration:       var(--a-duration);
-    --modal-easing:         var(--a-easing-out);
-    --modal-heading-size:   var(--a-ui-lg);
-    --modal-heading-weight: var(--a-weight-semibold);
-    --modal-header-fg:      var(--a-fg);
-    --modal-close-fg:       var(--a-fg-muted);
-    --modal-close-hover:    var(--a-fg);
-    --modal-pad-header:     var(--a-space-3);
-    --modal-pad-body:       var(--a-space-4);
-    --modal-pad-footer:     var(--a-space-3);
-    --modal-font-family:    var(--a-font-family);
-    --modal-footer-gap:     var(--a-space-2);
+    --modal-width-default:          32rem;
+    --modal-radius-default:         var(--a-radius-lg);
+    --modal-bg-default:             var(--a-bg-subtle);
+    --modal-border-default:         var(--a-border-subtle);
+    --modal-shadow-default:         var(--a-shadow-lg);
+    --modal-backdrop-default:       var(--a-scrim-dialog);
+    --modal-duration-default:       var(--a-duration);
+    --modal-easing-default:         var(--a-easing-out);
+    --modal-heading-size-default:   var(--a-ui-lg);
+    --modal-heading-weight-default: var(--a-weight-semibold);
+    --modal-header-fg-default:      var(--a-fg);
+    --modal-close-fg-default:       var(--a-fg-muted);
+    --modal-close-hover-default:    var(--a-fg);
+    --modal-pad-header-default:     var(--a-space-3);
+    --modal-pad-body-default:       var(--a-space-4);
+    --modal-pad-footer-default:     var(--a-space-3);
+    --modal-font-family-default:    var(--a-font-family);
+    --modal-footer-gap-default:     var(--a-space-2);
   }
 
   :scope {
@@ -35,9 +35,9 @@
   }
 
   /* ── Size variants ── */
-  :scope[size="sm"] { --modal-width: min(24rem, 90vw); }
-  :scope[size="md"] { --modal-width: min(32rem, 90vw); }
-  :scope[size="lg"] { --modal-width: min(48rem, 90vw); }
+  :scope[size="sm"] { --modal-width-default: min(24rem, 90vw); }
+  :scope[size="md"] { --modal-width-default: min(32rem, 90vw); }
+  :scope[size="lg"] { --modal-width-default: min(48rem, 90vw); }
 
   /* ═══════ Closed ═══════ */
   :scope > [slot="dialog"]:not([open]) { display: none; }
@@ -63,9 +63,9 @@
 
   /* ═══════ Backdrop ═══════ */
   :scope > [slot="dialog"]::backdrop {
-    background: var(--modal-backdrop);
+    background: var(--modal-backdrop, var(--modal-backdrop-default));
     opacity: 0;
-    transition: opacity var(--modal-duration) var(--modal-easing);
+    transition: opacity var(--modal-duration, var(--modal-duration-default)) var(--modal-easing, var(--modal-easing-default));
   }
   :scope > [slot="dialog"][data-open]::backdrop    { opacity: 1; }
   :scope > [slot="dialog"][data-closing]::backdrop { opacity: 0; }
@@ -75,14 +75,14 @@
     box-sizing: border-box;
     display: flex;
     flex-direction: column;
-    width: var(--modal-width);
+    width: var(--modal-width, var(--modal-width-default));
     max-height: 85vh;
-    background: var(--modal-bg);
-    color: var(--modal-header-fg);
-    font-family: var(--modal-font-family);
-    border: 1px solid var(--modal-border);
-    border-radius: var(--modal-radius);
-    box-shadow: var(--modal-shadow);
+    background: var(--modal-bg, var(--modal-bg-default));
+    color: var(--modal-header-fg, var(--modal-header-fg-default));
+    font-family: var(--modal-font-family, var(--modal-font-family-default));
+    border: 1px solid var(--modal-border, var(--modal-border-default));
+    border-radius: var(--modal-radius, var(--modal-radius-default));
+    box-shadow: var(--modal-shadow, var(--modal-shadow-default));
     overflow: hidden;
     opacity: 0;
     transform: scale(0.95);
@@ -90,16 +90,16 @@
 
   /* ═══════ Open animation ═══════ */
   :scope > [slot="dialog"][data-open] > [slot="panel"] {
-    transition: transform var(--modal-duration) var(--modal-easing),
-                opacity var(--modal-duration) var(--modal-easing);
+    transition: transform var(--modal-duration, var(--modal-duration-default)) var(--modal-easing, var(--modal-easing-default)),
+                opacity var(--modal-duration, var(--modal-duration-default)) var(--modal-easing, var(--modal-easing-default));
     transform: scale(1);
     opacity: 1;
   }
 
   /* ═══════ Close animation ═══════ */
   :scope > [slot="dialog"][data-closing] > [slot="panel"] {
-    transition: transform var(--modal-duration) var(--modal-easing),
-                opacity var(--modal-duration) var(--modal-easing);
+    transition: transform var(--modal-duration, var(--modal-duration-default)) var(--modal-easing, var(--modal-easing-default)),
+                opacity var(--modal-duration, var(--modal-duration-default)) var(--modal-easing, var(--modal-easing-default));
     transform: scale(0.95);
     opacity: 0;
   }
@@ -109,14 +109,24 @@
     display: flex;
     align-items: center;
     justify-content: space-between;
-    padding: var(--modal-pad-header) var(--modal-pad-body);
-    border-bottom: 1px solid var(--modal-border);
-    font-size: var(--modal-heading-size);
-    font-weight: var(--modal-heading-weight);
-    color: var(--modal-header-fg);
+    padding: var(--modal-pad-header, var(--modal-pad-header-default)) var(--modal-pad-body, var(--modal-pad-body-default));
+    border-bottom: 1px solid var(--modal-border, var(--modal-border-default));
+    font-size: var(--modal-heading-size, var(--modal-heading-size-default));
+    font-weight: var(--modal-heading-weight, var(--modal-heading-weight-default));
+    color: var(--modal-header-fg, var(--modal-header-fg-default));
     flex-shrink: 0;
   }
-  :scope [slot="header"]::before {
+  /* `[text]` gate — same drift class as button-ui / tag-ui / badge-ui /
+     segment-ui (Apr-May 2026 phantom-gap arc). Without the `[text]`
+     attribute selector, an empty `attr(text)` still generates a
+     pseudo-element with `flex: 1` — it claims the row's free space and
+     pushes any slotted title text-ui / icon-ui to the trailing edge,
+     leaving only the close button on the right looking like the title.
+     Gated on `[text]:not([text=""])` because modal/modal.class.js sets
+     `header.setAttribute('text', this.text)` unconditionally; the
+     defensive selector + class skip (see modal/modal.class.js render())
+     close the same trap from both directions. */
+  :scope [slot="header"][text]:not([text=""])::before {
     content: attr(text);
     flex: 1;
   }
@@ -128,7 +138,7 @@
 
   /* ═══════ Body ═══════ */
   :scope [slot="body"] {
-    padding: var(--modal-pad-body);
+    padding: var(--modal-pad-body, var(--modal-pad-body-default));
     flex: 1;
     overflow: auto;
   }
@@ -138,9 +148,9 @@
     display: flex;
     align-items: center;
     justify-content: flex-end;
-    gap: var(--modal-footer-gap);
-    padding: var(--modal-pad-footer) var(--modal-pad-body);
-    border-top: 1px solid var(--modal-border);
+    gap: var(--modal-footer-gap, var(--modal-footer-gap-default));
+    padding: var(--modal-pad-footer, var(--modal-pad-footer-default)) var(--modal-pad-body, var(--modal-pad-body-default));
+    border-top: 1px solid var(--modal-border, var(--modal-border-default));
     flex-shrink: 0;
   }
 }

package/components/modal/modal.js

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