@adia-ai/web-components 0.6.34 → 0.6.36

package/components/inline-message/inline-message.yaml

@@ -0,0 +1,205 @@
+# Hand-authored — SPEC-033.
+# Edit this file; run `npm run build:components` to regenerate a2ui.json + .d.ts.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIInlineMessage
+tag: inline-message-ui
+status: stable
+component: InlineMessage
+category: feedback
+version: 1
+description: |
+  In-flow message glyph + text used in form-field rows for validation
+  feedback, hint copy, and inline confirmations. Distinguished from
+  <alert-ui> (banner / surface-bearing notice) by carrying no surface
+  fill, no border, no padding box — severity is foreground color +
+  icon only. Variants map to severity (info / success / warning /
+  danger). Nests inside <field-ui>, <col-ui>, <row-ui> without
+  breaking field rhythm. Non-interactive annotation only.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
+props:
+  variant:
+    description: Semantic severity tone — drives icon + foreground color. Default carries no leading icon (pure hint copy).
+    type: string
+    default: default
+    reflect: true
+    dynamic: true
+    enum:
+      - default
+      - info
+      - success
+      - warning
+      - danger
+  icon:
+    description: Phosphor glyph override; each [variant] ships a sensible default (info / check-circle / warning / x-circle).
+    type: string
+    default: ""
+    reflect: true
+    dynamic: true
+  text:
+    description: Single-line message text. Default-slot content wins when present.
+    type: string
+    default: ""
+    dynamic: true
+  live:
+    description: Sets `aria-live` on the host for dynamic message updates. Empty = no live region (static annotation).
+    type: string
+    default: ""
+    reflect: true
+    enum:
+      - ""
+      - polite
+      - assertive
+events: {}
+slots:
+  default:
+    description: >-
+      Message body — text or inline DOM (e.g. <link-ui>, <kbd-ui>). Wins
+      over the [text] attribute when present. Stays inline so the
+      message reads as one annotation line under the field.
+  leading:
+    description: >-
+      Leading icon slot. Stamped automatically from [icon] or the
+      variant's default glyph. Consumer-provided <icon-ui slot="leading">
+      is preserved across [variant] changes (never overwritten).
+states:
+  - name: idle
+    description: Default, ready for screen-reader pickup.
+traits: []
+tokens: {}
+requiredIcons:
+  - info
+  - check-circle
+  - warning
+  - x-circle
+a2ui:
+  rules:
+    - rule: 'In-flow annotation under a form input (validation feedback, hint copy, inline confirmation). Severity via [variant] (info, success, warning, danger).'
+      reason: 'Distinct from <alert-ui>: no surface fill, no padding box, no dismiss — reads as helper text, not a banner.'
+    - rule: 'For overlay / banner-style notices use <alert-ui> instead; for transient toasts use <toast-ui>.'
+      reason: 'Surface-bearing vs in-flow boundary — collision invites visual confusion.'
+    - rule: 'Place inside <field-ui>, <col-ui>, or <row-ui>; never as a page-level banner.'
+      reason: 'Inline-flow contract; banner placement breaks the WAI inline-message pattern.'
+    - rule: 'Do not nest a focusable child (button, link with action) — InlineMessage is non-interactive annotation.'
+      reason: 'A focusable child requires role=alert + focus management, breaking the static-inline WAI pattern.'
+anti_patterns: []
+examples:
+  - name: field-validation
+    description: Email field with a danger inline-message under the input.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Field",
+          "label": "Email",
+          "children": [
+            "input",
+            "msg"
+          ]
+        },
+        {
+          "id": "input",
+          "component": "Input",
+          "type": "email"
+        },
+        {
+          "id": "msg",
+          "component": "InlineMessage",
+          "variant": "danger",
+          "text": "Email address is required"
+        }
+      ]
+  - name: password-hint
+    description: Password field with a muted hint (default variant, no icon).
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Field",
+          "label": "Password",
+          "children": [
+            "input",
+            "hint"
+          ]
+        },
+        {
+          "id": "input",
+          "component": "Input",
+          "type": "password"
+        },
+        {
+          "id": "hint",
+          "component": "InlineMessage",
+          "text": "At least 8 characters"
+        }
+      ]
+  - name: username-success
+    description: Username field with a polite live-region success confirmation.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Field",
+          "label": "Username",
+          "children": [
+            "input",
+            "msg"
+          ]
+        },
+        {
+          "id": "input",
+          "component": "Input"
+        },
+        {
+          "id": "msg",
+          "component": "InlineMessage",
+          "variant": "success",
+          "live": "polite",
+          "text": "Username is available"
+        }
+      ]
+keywords:
+  - inline
+  - message
+  - hint
+  - helper
+  - validation
+  - error
+  - field-error
+  - helper-text
+  - error-text
+  - form-feedback
+  - status
+  - notice
+synonyms:
+  hint:
+    - hint
+    - tooltip
+    - help
+  helper:
+    - hint
+    - help
+    - tooltip
+  validation:
+    - validation
+    - error
+    - alert
+  error:
+    - error
+    - alert
+    - validation
+  message:
+    - alert
+    - notification
+    - hint
+  notice:
+    - alert
+    - banner
+    - hint
+related:
+  - alert
+  - field
+  - input
+  - text

package/components/input/input.css

@@ -121,6 +121,10 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
     outline: none;
     white-space: nowrap;
     overflow: hidden;
+    /* Positioning context for the [data-empty]::before placeholder
+       pseudo, which is taken out of inline flow so the caret renders
+       at the actual content-start (not after the pseudo box). */
+    position: relative;
   }
 
   /* Text (native input — password only) */
@@ -138,11 +142,21 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
     color: var(--input-placeholder-fg, var(--input-placeholder-fg-default));
   }
 
-  /* Placeholder (contenteditable only) */
+  /* Placeholder (contenteditable only).
+     Out-of-flow positioning is load-bearing — an in-flow ::before with
+     `content: attr(...)` puts the pseudo box INLINE before the empty
+     text node, which means the caret-at-position-0 visually renders to
+     the RIGHT of the placeholder text (after the user types and deletes).
+     `position: absolute; inset: 0; padding: inherit` makes the pseudo
+     fill the host's content-box without occupying any inline-flow space,
+     so the caret renders at the actual content-start where it belongs. */
   span[slot="text"][data-empty]::before {
     content: attr(data-placeholder);
     color: var(--input-placeholder-fg, var(--input-placeholder-fg-default));
     pointer-events: none;
+    position: absolute;
+    inset: 0;
+    padding: inherit;
   }
 
   /* ── Number mode (type="number") ──
@@ -278,7 +292,7 @@ input-ui:not([disabled]) [slot="field"]:hover [slot="suffix"] {
 
   /* §199 (v0.5.7) — Leading + trailing affordance slots inside the field.
      Consumer authors `<button-ui slot="leading|trailing">` as a direct
-     child of <input-ui>; class.js#installAffordances moves it into
+     child of <input-ui>; input.class.js#installAffordances moves it into
      [slot="field"] at the right insertion point on connected(). CSS
      normalizes the chrome here.
 

package/components/input/input.js

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

package/components/input/input.test.js

@@ -10,9 +10,15 @@
  */
 
 import { describe, it, expect, beforeEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
 import '../../core/element.js';
 import './input.js';
 
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const INPUT_CSS = readFileSync(resolve(__dirname, 'input.css'), 'utf8');
+
 const tick = () => new Promise((r) => queueMicrotask(r));
 
 function mount(html) {
@@ -220,3 +226,37 @@ describe('input-ui — §220 (v0.5.9) throttle parity', () => {
     expect(events).toEqual([]);
   });
 });
+
+// ── Placeholder caret-position regression guard ─────────────────────
+//
+// Per the v0.6.35 bug report: with the `::before { content: attr(data-placeholder) }`
+// pseudo rendered in inline flow, typing-then-deleting left the caret
+// visually at the END of the placeholder text (not at position 0) because
+// the in-flow pseudo box pushed the caret rendering position to its right.
+// Fix: pseudo is `position: absolute` so it doesn't occupy inline-flow
+// space; the host carries `position: relative` as its anchor.
+// These tests assert the CSS-source contract that prevents accidental
+// revert to the in-flow pseudo shape.
+
+describe('input-ui — CSS source contract: placeholder pseudo is out of flow', () => {
+  it('host [slot="text"] declares position: relative (pseudo anchor)', () => {
+    expect(INPUT_CSS).toMatch(
+      /\[slot="text"\]\s*\{[^}]*position:\s*relative/s
+    );
+  });
+
+  it('[data-empty]::before is position: absolute (not inline-flow)', () => {
+    expect(INPUT_CSS).toMatch(
+      /span\[slot="text"\]\[data-empty\]::before\s*\{[^}]*position:\s*absolute/s
+    );
+  });
+
+  it('[data-empty]::before fills the host content-box (inset: 0 + padding: inherit)', () => {
+    expect(INPUT_CSS).toMatch(
+      /span\[slot="text"\]\[data-empty\]::before\s*\{[^}]*inset:\s*0/s
+    );
+    expect(INPUT_CSS).toMatch(
+      /span\[slot="text"\]\[data-empty\]::before\s*\{[^}]*padding:\s*inherit/s
+    );
+  });
+});

package/components/input/input.yaml

@@ -262,10 +262,11 @@ a2ui:
       Number. Never substitute a native <input type="number">.
     - >-
       Inside <chat-composer>, the canonical inner input is
-      <chat-input-ui submit-on-enter> (chat variant subclass — owns
-      the submit-on-enter contract explicitly). The plain <input-ui>
-      primitive already fires `submit` on Enter, but only chat-input-ui
-      reflects the [submit-on-enter] attribute.
+      <chat-input-ui> (chat variant subclass — adds the send button +
+      model picker + paste-to-attach plumbing). The plain <input-ui>
+      primitive ALSO fires a bubbling `submit` event on Enter
+      (unconditional, no opt-in attribute); <chat-input-ui> simply
+      builds on that semantic.
 anti_patterns: []
 examples:
 - name: quantity-stepper

package/components/inspector/inspector.js

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

package/components/integration-card/integration-card.js

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

package/components/kbd/kbd.js

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

package/components/link/link.js

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

package/components/list/list-item.yaml

@@ -1,9 +1,9 @@
 # Edit this file; run `npm run build:components` to regenerate a2ui.json.
 #
 # §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
-# component already existed as a sibling class in the parent's class.js
+# component already existed as a sibling class in the parent's list.class.js
 # + was registered alongside the parent (e.g. UIList + UIListItem both
-# from list/class.js). The catalog just lacked its own entry. With the
+# from list/list.class.js). The catalog just lacked its own entry. With the
 # §172 sibling-yaml scanner, this file gets picked up next to the parent
 # yaml.
 

package/components/list/list.js

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

package/components/list-window/list-window.js

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

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