@adia-ai/web-components 0.8.40 → 0.8.41

package/components/action-list/action-item.yaml

@@ -16,7 +16,10 @@ component: ActionItem
 category: navigation
 version: 1
 description: |-
-  Child of <action-list-ui>. One actionable row — icon + label, forwards activation to the parent action-list.
+  Child of <action-list-ui>. One actionable row — icon + label + optional
+  subtitle, forwards activation to the parent action-list. Row contract
+  converges on <menu-item-ui>: icon/text/subtitle/value/variant/disabled
+  props and icon/text/subtitle/trailing slot overrides (#1363 C5).
 
 props:
   icon:
@@ -25,13 +28,18 @@ props:
   text:
     description: Action label.
     type: string
+  subtitle:
+    description: Optional secondary description line rendered under the label.
+    type: string
+    default: ''
   value:
     description: Identifier passed to the action-list change/activate handlers.
     type: string
   variant:
-    description: Visual variant (default | accent | danger).
+    description: Visual variant (default | danger).
     type: string
     default: 'default'
+    enum: [default, danger]
   disabled:
     description: Disables click + keyboard activation; aria-disabled is set.
     type: boolean
@@ -43,6 +51,17 @@ slots:
       Override the [icon] glyph with a custom slotted element (custom
       icon-ui, image, avatar). Mutually exclusive with the [icon]
       attribute — slot child wins.
+  text:
+    description: Custom label content; falls through to [text] prop if not slotted.
+  subtitle:
+    description: >-
+      Custom secondary-line content override; falls through to [subtitle]
+      prop if not slotted.
+  trailing:
+    description: >-
+      Trailing element pinned to the far edge (shortcut hint, badge, caret).
+      Supersedes the unnamed default slot this row previously used for
+      trailing content — see MIGRATION GUIDE.
 
 keywords:
   - action-item
@@ -60,10 +79,16 @@ related:
   - Button
 
 a2ui:
+  allowedParents:
+    - ActionList
   rules:
-    - rule: 'Child of <action-list-ui> — one inline-action row with icon + label + optional shortcut + optional sublabel.'
+    - rule: 'Child of <action-list-ui> — one inline-action row with icon + label + optional subtitle + optional trailing shortcut/badge.'
       reason: 'Action-list cluster contract.'
     - rule: 'Different from <menu-item-ui>: action-items live inline in content surfaces; menu-items live inside <menu-ui> popovers.'
       reason: 'Context boundary.'
     - rule: 'For navigation entries (route-changing) use <nav-item-ui> instead.'
       reason: 'Different intent — actions vs navigation.'
+    - rule: 'Use [variant="danger"] exclusively for destructive/irreversible actions (Delete, Remove). Pair danger items with an explicit confirm flow when the action cannot be undone.'
+      reason: 'Converged with <menu-item-ui>''s danger-variant guidance (#1363 C5).'
+    - rule: 'Prefer [icon]/[text]/[subtitle] props over slotted markup; use slot="icon"/"text"/"subtitle"/"trailing" only for custom markup (e.g. a slotted <kbd> shortcut hint).'
+      reason: 'Row-contract convergence with <menu-item-ui> (#1363 C5).'

package/components/action-list/action-list.a2ui.json

@@ -22,6 +22,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedChildren": [
+      "ActionItem"
+    ],
     "anti_patterns": [],
     "category": "navigation",
     "composes": [
@@ -60,10 +63,12 @@
       "list"
     ],
     "name": "UIActionList",
+    "parts": {},
     "related": [
       "ActionItem",
       "Menu",
-      "Button"
+      "Button",
+      "List"
     ],
     "slots": {
       "default": {

package/components/action-list/action-list.class.js

@@ -94,6 +94,7 @@ export class UIActionItem extends UIElement {
   static properties = {
     icon:     { type: String,  default: '', reflect: true },
     text:     { type: String,  default: '', reflect: true },
+    subtitle: { type: String,  default: '', reflect: true },
     value:    { type: String,  default: '', reflect: true },
     variant:  { type: String,  default: 'default', reflect: true },
     disabled: { type: Boolean, default: false, reflect: true },
@@ -101,6 +102,21 @@ export class UIActionItem extends UIElement {
 
   static template = () => null;
 
+  // Set when connected()/render() stamped this fallback child from a prop —
+  // never touch a consumer-authored slot="icon"/"text"/"subtitle" child
+  // (ADR-0010, slot content is source of truth). Mirrors menu-item-ui's
+  // UIMenuItem stamp-marking exactly (CodeRabbit review, PR #1429).
+  #stampMark(el) { el.dataset.actionItemStamped = '1'; return el; }
+  #wasStamped(el) { return el?.dataset?.actionItemStamped === '1'; }
+
+  #ownChild(selector) {
+    // wrapper-trap-ok: finds component-stamped children (data-action-item-stamped) — consumer children are read but never overwritten
+    for (const ch of this.children) {
+      if (ch.matches(selector)) return ch;
+    }
+    return null;
+  }
+
   connected() {
     // Adopt-or-stamp (gh#753): a consumer-authored role survives connect —
     // only stamp "listitem" when the host has no author-set role at all.
@@ -111,21 +127,28 @@ export class UIActionItem extends UIElement {
   }
 
   #stamp() {
-    if (this.querySelector('[slot="text"]')) return;
+    if (this.#ownChild('[slot="text"]')) return;
 
-    if (this.icon) {
-      const iconEl = document.createElement('icon-ui');
+    if (this.icon && !this.#ownChild('[slot="icon"]')) {
+      const iconEl = this.#stampMark(document.createElement('icon-ui'));
       iconEl.setAttribute('slot', 'icon');
       iconEl.setAttribute('name', this.icon);
       this.appendChild(iconEl);
     }
 
     if (this.text) {
-      const span = document.createElement('span');
+      const span = this.#stampMark(document.createElement('span'));
       span.setAttribute('slot', 'text');
       span.textContent = this.text;
       this.appendChild(span);
     }
+
+    if (this.subtitle && !this.#ownChild('[slot="subtitle"]')) {
+      const sub = this.#stampMark(document.createElement('span'));
+      sub.setAttribute('slot', 'subtitle');
+      sub.textContent = this.subtitle;
+      this.appendChild(sub);
+    }
   }
 
   #syncAria() {
@@ -139,21 +162,39 @@ export class UIActionItem extends UIElement {
   }
 
   render() {
-    const iconEl = this.querySelector('[slot="icon"]');
+    // Sync icon — only touch elements we stamped.
+    const iconEl = this.#ownChild('[slot="icon"]');
     if (this.icon) {
-      if (iconEl) iconEl.setAttribute('name', this.icon);
-      else {
-        const el = document.createElement('icon-ui');
+      if (iconEl) {
+        if (this.#wasStamped(iconEl)) iconEl.setAttribute('name', this.icon);
+      } else {
+        const el = this.#stampMark(document.createElement('icon-ui'));
         el.setAttribute('slot', 'icon');
         el.setAttribute('name', this.icon);
         this.prepend(el);
       }
-    } else if (iconEl) {
+    } else if (this.#wasStamped(iconEl)) {
       iconEl.remove();
     }
 
-    const textEl = this.querySelector('[slot="text"]');
-    if (textEl) textEl.textContent = this.text;
+    // Sync text — only touch elements we stamped.
+    const textEl = this.#ownChild('[slot="text"]');
+    if (this.#wasStamped(textEl)) textEl.textContent = this.text;
+
+    // Sync subtitle — only touch elements we stamped.
+    const subEl = this.#ownChild('[slot="subtitle"]');
+    if (this.subtitle) {
+      if (subEl) {
+        if (this.#wasStamped(subEl)) subEl.textContent = this.subtitle;
+      } else {
+        const sub = this.#stampMark(document.createElement('span'));
+        sub.setAttribute('slot', 'subtitle');
+        sub.textContent = this.subtitle;
+        this.appendChild(sub);
+      }
+    } else if (this.#wasStamped(subEl)) {
+      subEl.remove();
+    }
 
     this.#syncAria();
   }

package/components/action-list/action-list.css

@@ -47,6 +47,8 @@ action-item-ui:hover [slot="icon"] {
 
     --action-item-font-size:       var(--a-ui-size);
     --action-item-icon-size:       var(--action-item-font-size);
+    --action-item-subtitle-size:   var(--a-ui-sm);
+    --action-item-subtitle-fg:     var(--a-fg-muted);
 
     --action-item-focus-ring:      var(--a-focus-ring);
 
@@ -98,11 +100,49 @@ action-item-ui:hover [slot="icon"] {
     text-overflow: ellipsis;
   }
 
-  /* Default slot (trailing content: kbd, badge, caret) pushed to far right */
-  & > :not([slot="icon"]):not([slot="text"]) {
+  /* Trailing (shortcut hint, badge, caret) — pinned to the far edge.
+     Converged onto <menu-item-ui>'s named-slot contract (#1363 C5); the
+     unnamed default slot this row previously used for trailing content had
+     zero known consumers (verified across the monorepo at dispatch time —
+     see MIGRATION GUIDE) and is retired in favor of an explicit slot. */
+  [slot="trailing"] {
     flex-shrink: 0;
     margin-inline-start: auto;
-    color: var(--action-item-icon-fg);
+  }
+
+  /* ── Subtitle — two-line anatomy, mirrors <menu-item-ui> ──
+     Content-driven: a present [slot="subtitle"] switches the row to a
+     grid so the subtitle sits under the label while icon and trailing
+     content span both lines. */
+  :scope:has(> [slot="subtitle"]) {
+    display: grid;
+    grid-template-columns: auto 1fr auto;
+    align-items: center;
+    column-gap: var(--action-item-gap);
+    row-gap: 0;
+  }
+  :scope:has(> [slot="subtitle"]) > [slot="icon"] {
+    grid-column: 1;
+    grid-row: 1 / span 2;
+  }
+  :scope:has(> [slot="subtitle"]) > [slot="text"] {
+    grid-column: 2;
+    grid-row: 1;
+  }
+  :scope:has(> [slot="subtitle"]) > [slot="trailing"] {
+    grid-column: 3;
+    grid-row: 1 / span 2;
+    margin-inline-start: 0;
+  }
+  :scope > [slot="subtitle"] {
+    grid-column: 2;
+    grid-row: 2;
+    min-width: 0;
+    font-size: var(--action-item-subtitle-size);
+    color: var(--action-item-subtitle-fg);
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
   }
 
   /* Variant: danger (destructive action) — only remaps tokens */

package/components/action-list/action-list.d.ts

@@ -38,10 +38,12 @@ export class UIActionItem extends UIElement {
   disabled: boolean;
   /** Leading icon name (Phosphor). */
   icon: string;
+  /** Optional secondary description line rendered under the label. */
+  subtitle: string;
   /** Action label. */
   text: string;
   /** Identifier passed to the action-list change/activate handlers. */
   value: string;
-  /** Visual variant (default | accent | danger). */
-  variant: string;
+  /** Visual variant (default | danger). */
+  variant: 'default' | 'danger';
 }

package/components/action-list/action-list.yaml

@@ -36,6 +36,8 @@ states:
 traits: []
 tokens: {}
 a2ui:
+  allowedChildren:
+    - ActionItem
   rules:
     - rule: 'Hosts <action-item-ui> children as a vertical command list inline in content surfaces.'
       reason: 'Cluster contract.'
@@ -43,6 +45,8 @@ a2ui:
       reason: 'Inline vs popover.'
     - rule: 'Typical use: command palettes, settings panels, agent suggestion lists.'
       reason: 'Surface examples.'
+    - rule: 'For a persisted, non-firing single selection (highlight the current row, no keyboard-activated command) use <list-ui selectable> instead — action-list-ui always fires and never holds a selected state.'
+      reason: 'Container-level decision (#1363 C5): kept as its own component rather than a <list-ui> mode axis; rationale in gh#1374 Findings.'
 anti_patterns: []
 examples:
   - name: basic-action-list
@@ -79,3 +83,4 @@ related:
   - ActionItem
   - Menu
   - Button
+  - List

package/components/adia-mark/adia-mark.a2ui.json

@@ -70,6 +70,7 @@
       "icon"
     ],
     "name": "UIAdiaMark",
+    "parts": {},
     "related": [
       "AdiaWordmark",
       "Icon",

package/components/adia-wordmark/adia-wordmark.a2ui.json

@@ -67,6 +67,7 @@
       "identity"
     ],
     "name": "UIAdiaWordmark",
+    "parts": {},
     "related": [
       "AdiaMark",
       "Icon",

package/components/agent-artifact/agent-artifact.a2ui.json

@@ -79,6 +79,7 @@
       "attachment"
     ],
     "name": "UIAgentArtifact",
+    "parts": {},
     "related": [
       "card-ui",
       "code-ui"

package/components/agent-feedback-bar/agent-feedback-bar.a2ui.json

@@ -71,15 +71,16 @@
       "bookmark"
     ],
     "name": "UIAgentFeedbackBar",
+    "parts": {
+      "default": {
+        "description": "Template-owned anatomy, not a light-DOM insertion point (gh#1454). `#build()` unconditionally wipes the host (`this.innerHTML = ''`) and rebuilds a fixed thumbs-up/thumbs-down/save row from props — no pre-existing children are captured or preserved."
+      }
+    },
     "related": [
       "agent-suggestions-ui",
       "agent-trace-ui"
     ],
-    "slots": {
-      "default": {
-        "description": "Default slot — primary child content."
-      }
-    },
+    "slots": {},
     "states": [
       {
         "description": "Default, ready for interaction.",

package/components/agent-feedback-bar/agent-feedback-bar.yaml

@@ -44,9 +44,13 @@ events:
         description: Rating value selected by the user.
   feedback-save:
     description: "Fired on feedback-save."
-slots:
+parts:
   default:
-    description: "Default slot — primary child content."
+    description: >-
+      Template-owned anatomy, not a light-DOM insertion point (gh#1454).
+      `#build()` unconditionally wipes the host (`this.innerHTML = ''`) and
+      rebuilds a fixed thumbs-up/thumbs-down/save row from props — no
+      pre-existing children are captured or preserved.
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/agent-questions/agent-questions.a2ui.json

@@ -79,6 +79,7 @@
       "clarify"
     ],
     "name": "UIAgentQuestions",
+    "parts": {},
     "related": [
       "agent-suggestions-ui",
       "agent-reasoning-ui"

package/components/agent-reasoning/agent-reasoning.a2ui.json

@@ -105,15 +105,16 @@
       "iteration"
     ],
     "name": "UIAgentReasoning",
+    "parts": {
+      "default": {
+        "description": "Template-owned anatomy, not a light-DOM insertion point (gh#938, gh#1454): the component rebuilds its body from the addStep()/addThought() pipeline (`this.innerHTML = ''` then rebuild) and does not consume authored children."
+      }
+    },
     "related": [
       "agent-trace-ui",
       "pipeline-status-ui"
     ],
-    "slots": {
-      "default": {
-        "description": "Default slot — NOT a step-authoring surface: the component rebuilds its body from the addStep()/addThought() pipeline and does not consume authored children (gh#938)."
-      }
-    },
+    "slots": {},
     "states": [
       {
         "description": "Default, ready for interaction.",

package/components/agent-reasoning/agent-reasoning.yaml

@@ -55,9 +55,13 @@ events:
       collapsed:
         type: boolean
         description: Whether the reasoning section is now collapsed.
-slots:
+parts:
   default:
-    description: "Default slot — NOT a step-authoring surface: the component rebuilds its body from the addStep()/addThought() pipeline and does not consume authored children (gh#938)."
+    description: >-
+      Template-owned anatomy, not a light-DOM insertion point (gh#938,
+      gh#1454): the component rebuilds its body from the
+      addStep()/addThought() pipeline (`this.innerHTML = ''` then rebuild)
+      and does not consume authored children.
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/agent-suggestions/agent-suggestions.a2ui.json

@@ -22,13 +22,21 @@
       "default": false
     },
     "size": {
-      "description": "sm | md",
+      "description": "sm | md — forwarded to each chip's <button-ui size>.",
       "type": "string",
+      "enum": [
+        "sm",
+        "md"
+      ],
       "default": "sm"
     },
     "variant": {
-      "description": "outline | ghost | subtle",
+      "description": "outline | ghost — forwarded to each chip's <button-ui variant>.",
       "type": "string",
+      "enum": [
+        "outline",
+        "ghost"
+      ],
       "default": "outline"
     }
   },
@@ -75,6 +83,7 @@
       "quick replies"
     ],
     "name": "UIAgentSuggestions",
+    "parts": {},
     "related": [
       "agent-questions-ui",
       "agent-feedback-bar-ui"

package/components/agent-suggestions/agent-suggestions.class.js

@@ -29,7 +29,8 @@
  *   });
  *
  * Attributes:
- *   variant   — outline (default) | ghost | subtle
+ *   variant   — outline (default) | ghost  (forwarded to each chip's button-ui;
+ *               "subtle" is not a real button-ui variant — dropped gh#1378)
  *   size      — sm (default) | md
  *   disabled  — disable all chips
  *

package/components/agent-suggestions/agent-suggestions.d.ts

@@ -32,10 +32,10 @@ export type AgentSuggestionsSuggestionSelectEvent = CustomEvent<AgentSuggestions
 export class UIAgentSuggestions extends UIElement {
   /** Disable all chips. */
   disabled: boolean;
-  /** sm | md */
-  size: string;
-  /** outline | ghost | subtle */
-  variant: string;
+  /** sm | md — forwarded to each chip's <button-ui size>. */
+  size: 'sm' | 'md';
+  /** outline | ghost — forwarded to each chip's <button-ui variant>. */
+  variant: 'outline' | 'ghost';
 
   addEventListener(type: 'suggestion-select', listener: (ev: AgentSuggestionsSuggestionSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener<K extends keyof HTMLElementEventMap>(

package/components/agent-suggestions/agent-suggestions.yaml

@@ -25,13 +25,15 @@ props:
     default: false
     reflect: true
   size:
-    description: sm | md
+    description: sm | md — forwarded to each chip's <button-ui size>.
     type: string
     default: sm
+    enum: [sm, md]
   variant:
-    description: outline | ghost | subtle
+    description: outline | ghost — forwarded to each chip's <button-ui variant>.
     type: string
     default: outline
+    enum: [outline, ghost]
 events:
   suggestion-select:
     description: "Fired on suggestion-select."

package/components/agent-trace/agent-trace.a2ui.json

@@ -61,15 +61,16 @@
       "training feedback"
     ],
     "name": "UIAgentTrace",
+    "parts": {
+      "default": {
+        "description": "Template-owned anatomy, not a light-DOM insertion point (gh#1454). `#buildShell()` unconditionally wipes the host (`this.innerHTML = ''`) and rebuilds a `<details>` root from the `pills`/`metrics`/`feedback` properties — no pre-existing children are captured or preserved."
+      }
+    },
     "related": [
       "agent-reasoning-ui",
       "agent-feedback-bar-ui"
     ],
-    "slots": {
-      "default": {
-        "description": "Default slot — primary child content."
-      }
-    },
+    "slots": {},
     "states": [
       {
         "description": "Default, ready for interaction.",

package/components/agent-trace/agent-trace.yaml

@@ -29,9 +29,13 @@ events:
       collapsed:
         type: boolean
         description: Whether the trace is now collapsed.
-slots:
+parts:
   default:
-    description: "Default slot — primary child content."
+    description: >-
+      Template-owned anatomy, not a light-DOM insertion point (gh#1454).
+      `#buildShell()` unconditionally wipes the host (`this.innerHTML = ''`)
+      and rebuilds a `<details>` root from the `pills`/`metrics`/`feedback`
+      properties — no pre-existing children are captured or preserved.
 states:
   - name: idle
     description: Default, ready for interaction.

package/components/alert/alert.a2ui.json

@@ -163,6 +163,7 @@
       "announce"
     ],
     "name": "UIAlert",
+    "parts": {},
     "related": [
       "button"
     ],

package/components/alert/alert.css

@@ -14,7 +14,7 @@
 
     /* ── Typography ── */
     --alert-font:        var(--a-ui-size);
-    --alert-line-height: var(--a-ui-line-height, 1.5);
+    --alert-line-height: var(--a-ui-line-height, var(--a-font-leading-relaxed));
 
     /* ── SPEC-006 dunning pattern tokens ── */
     --alert-amount-font: var(--a-font-mono, ui-monospace, SFMono-Regular, Menlo, monospace);

package/components/anchor-bar/anchor-bar.a2ui.json

@@ -82,6 +82,7 @@
       "bulk action"
     ],
     "name": "UIAnchorBar",
+    "parts": {},
     "related": [],
     "slots": {
       "default": {

package/components/aside/aside.a2ui.json

@@ -58,6 +58,7 @@
       "nav-rail"
     ],
     "name": "UIAside",
+    "parts": {},
     "related": [
       "app-shell",
       "drawer",

package/components/avatar/avatar-group.a2ui.json

@@ -23,7 +23,12 @@
     },
     "size": {
       "description": "Forwards to each child <avatar-ui> (sm|md|lg). Empty uses the per-avatar size. For denser or larger sets, set [scale] on an ancestor.",
-      "type": "string"
+      "type": "string",
+      "enum": [
+        "sm",
+        "md",
+        "lg"
+      ]
     }
   },
   "required": [
@@ -45,6 +50,7 @@
       "overflow-avatars"
     ],
     "name": "UIAvatarGroup",
+    "parts": {},
     "related": [
       "Avatar",
       "Tag"

package/components/avatar/avatar-group.yaml

@@ -25,6 +25,7 @@ props:
   size:
     description: Forwards to each child <avatar-ui> (sm|md|lg). Empty uses the per-avatar size. For denser or larger sets, set [scale] on an ancestor.
     type: string
+    enum: [sm, md, lg]
 
 keywords:
   - avatar-group

package/components/avatar/avatar.a2ui.json

@@ -88,24 +88,25 @@
       "user"
     ],
     "name": "UIAvatar",
-    "related": [
-      "input",
-      "button",
-      "check-box",
-      "badge",
-      "avatar-group"
-    ],
-    "slots": {
+    "parts": {
       "icon": {
-        "description": "Phosphor icon rendered inside the avatar circle (system-event avatars)"
+        "description": "Phosphor icon rendered inside the avatar circle (system-event avatars) — template-owned anatomy part, not a light-DOM insertion point (gh#1454). render() always creates it from the `icon` prop; no consumer override path exists in source."
       },
       "img": {
-        "description": "Avatar image element"
+        "description": "Avatar image element — template-owned anatomy part, not a light-DOM insertion point (gh#1454). render() always creates it from the `src` prop; no consumer override path exists in source."
       },
       "initials": {
-        "description": "Initials text span"
+        "description": "Initials text span — template-owned anatomy part, not a light-DOM insertion point (gh#1454). render() always creates it from the `text` prop; no consumer override path exists in source."
       }
     },
+    "related": [
+      "input",
+      "button",
+      "check-box",
+      "badge",
+      "avatar-group"
+    ],
+    "slots": {},
     "states": [
       {
         "description": "Default, ready for interaction.",

package/components/avatar/avatar.d.ts

@@ -35,5 +35,5 @@ export class UIAvatarGroup extends UIElement {
   /** Maximum avatars to show before the +N overflow indicator. */
   max: number;
   /** Forwards to each child <avatar-ui> (sm|md|lg). Empty uses the per-avatar size. For denser or larger sets, set [scale] on an ancestor. */
-  size: string;
+  size: 'sm' | 'md' | 'lg';
 }