@adia-ai/web-components 0.6.34 → 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.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

@@ -116,7 +116,17 @@
     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;
   }

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

package/components/nav/nav.js

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

package/components/nav-group/nav-group.js

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

package/components/nav-item/nav-item.js

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

package/components/noodles/noodles.js

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

package/components/option-card/option-card.js

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

package/components/otp-input/otp-input.js

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

package/components/page/page.js

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

package/components/pagination/pagination.js

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

package/components/pane/pane.js

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

package/components/pipeline-status/pipeline-status.js

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

package/components/popover/popover.a2ui.json

@@ -91,7 +91,14 @@
       "button",
       "divider"
     ],
-    "slots": {},
+    "slots": {
+      "content": {
+        "description": "Popover body — any interactive content. Hoisted to the top-layer via :popover-open when shown. Positioned via the Popover API + CSS Anchor Positioning per [placement] / [gap]; no manual positioning required."
+      },
+      "trigger": {
+        "description": "Focusable element that opens the popover when activated. Typically <button-ui>, but any focusable element works (button, a link with href). MUST be focusable for keyboard accessibility — bare <span> or <div> children will not respond to keyboard activation. Positioned at the anchor point per [placement]."
+      }
+    },
     "states": [
       {
         "description": "Default, ready for interaction.",

package/components/popover/popover.js

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

package/components/popover/popover.yaml

@@ -40,7 +40,20 @@ props:
       - hover
       - manual
 events: {}
-slots: {}
+slots:
+  trigger:
+    description: >-
+      Focusable element that opens the popover when activated.
+      Typically <button-ui>, but any focusable element works (button,
+      a link with href). MUST be focusable for keyboard accessibility —
+      bare <span> or <div> children will not respond to keyboard
+      activation. Positioned at the anchor point per [placement].
+  content:
+    description: >-
+      Popover body — any interactive content. Hoisted to the top-layer
+      via :popover-open when shown. Positioned via the Popover API +
+      CSS Anchor Positioning per [placement] / [gap]; no manual
+      positioning required.
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/progress/progress.js

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

package/components/progress-row/progress-row.js

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

package/components/radio/radio.js

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

package/components/range/range.js

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

package/components/rating/rating.js

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

package/components/richtext/richtext.js

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

package/components/row/row.js

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

package/components/search/search.js

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

package/components/segment/segment.js

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

package/components/segmented/segmented.js

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