@adia-ai/web-components 0.8.40 → 0.8.42

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ActionItem.json",
   "title": "ActionItem",
-  "description": "Child of <action-list-ui>. One actionable row — icon + label, forwards activation to the parent action-list.",
+  "description": "Child of <action-list-ui>. One actionable row — icon + label + optional\ndescription, forwards activation to the parent action-list. Row contract\nconverges on <menu-item-ui>: icon/text/description/value/variant/disabled\nprops and icon/text/subtitle/trailing slot overrides (#1363 C5).\n(`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1571.)",
   "type": "object",
   "allOf": [
     {
@@ -13,6 +13,11 @@
     }
   ],
   "properties": {
+    "description": {
+      "description": "Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1571) replacing `subtitle` — converges action-item onto the same spelling <menu-item-ui> adopted under gh#1563.",
+      "type": "string",
+      "default": ""
+    },
     "component": {
       "const": "ActionItem"
     },
@@ -25,6 +30,11 @@
       "description": "Leading icon name (Phosphor).",
       "type": "string"
     },
+    "subtitle": {
+      "description": "DEPRECATED (ADR-0063, gh#1571) — use `description` instead. Same type/default/rendered position; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface, deliberately left unrenamed in this pass — see its own description.)",
+      "type": "string",
+      "default": ""
+    },
     "text": {
       "description": "Action label.",
       "type": "string"
@@ -34,8 +44,12 @@
       "type": "string"
     },
     "variant": {
-      "description": "Visual variant (default | accent | danger).",
+      "description": "Visual variant (default | danger).",
       "type": "string",
+      "enum": [
+        "default",
+        "danger"
+      ],
       "default": "default"
     }
   },
@@ -44,6 +58,9 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
+    "allowedParents": [
+      "ActionList"
+    ],
     "anti_patterns": [],
     "category": "navigation",
     "composes": [],
@@ -57,6 +74,7 @@
       "action-list-row"
     ],
     "name": "UIActionItem",
+    "parts": {},
     "related": [
       "ActionList",
       "MenuItem",
@@ -65,6 +83,15 @@
     "slots": {
       "icon": {
         "description": "Override the [icon] glyph with a custom slotted element (custom icon-ui, image, avatar). Mutually exclusive with the [icon] attribute — slot child wins."
+      },
+      "subtitle": {
+        "description": "Custom secondary-line content override; falls through to the [description] prop (or its deprecated [subtitle] alias — ADR-0063, gh#1571) if not slotted. The slot's own name is unchanged by that rename — this is a distinct, deliberately-unrenamed surface."
+      },
+      "text": {
+        "description": "Custom label content; falls through to [text] 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."
       }
     },
     "states": [],

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

@@ -16,7 +16,11 @@ 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
+  description, forwards activation to the parent action-list. Row contract
+  converges on <menu-item-ui>: icon/text/description/value/variant/disabled
+  props and icon/text/subtitle/trailing slot overrides (#1363 C5).
+  (`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1571.)
 
 props:
   icon:
@@ -25,13 +29,31 @@ props:
   text:
     description: Action label.
     type: string
+  subtitle:
+    description: >-
+      DEPRECATED (ADR-0063, gh#1571) — use `description` instead. Same
+      type/default/rendered position; kept working as a dual-read compat
+      shim (one-time console.warn when it's the name that resolves).
+      Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface,
+      deliberately left unrenamed in this pass — see its own description.)
+    type: string
+    default: ''
+  description:
+    description: >-
+      Optional secondary description line rendered under the label.
+      Canonical spelling (ADR-0063, gh#1571) replacing `subtitle` —
+      converges action-item onto the same spelling <menu-item-ui> adopted
+      under gh#1563.
+    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 +65,19 @@ 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 the
+      [description] prop (or its deprecated [subtitle] alias — ADR-0063,
+      gh#1571) if not slotted. The slot's own name is unchanged by that
+      rename — this is a distinct, deliberately-unrenamed surface.
+  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 +95,18 @@ 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 description + 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]/[description] 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).'
+    - rule: 'NOTE (ADR-0063, gh#1571): [subtitle] is now a deprecated alias for [description] — kept as a dual-read compat shim (new-name precedence, one-time console.warn), removed at the 0.9.0 cut.'
+      reason: 'Convergence with <menu-item-ui>''s own subtitle -> description rename (gh#1563).'

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,14 @@ export class UIActionItem extends UIElement {
   static properties = {
     icon:     { type: String,  default: '', reflect: true },
     text:     { type: String,  default: '', reflect: true },
+    // ADR-0063 (gh#1571) — `subtitle` is DEPRECATED (action-item was the
+    // corpus's remaining `subtitle` outlier once <menu-item-ui> converged
+    // under gh#1563); `description` is canonical. `subtitle` stays declared
+    // (dual-read compat, additive). The `subtitle` SLOT (a separate
+    // surface — see action-item.yaml) is deliberately unchanged; only the
+    // PROP renames.
+    subtitle: { type: String,  default: '', reflect: true },
+    description: { 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,7 +109,71 @@ export class UIActionItem extends UIElement {
 
   static template = () => null;
 
+  // ADR-0063 (gh#1571) one-shot-per-class deprecation warn for [subtitle].
+  static #warnedSubtitle = false;
+
+  // Guards + tracks the [subtitle] -> [description] compat mirror (below).
+  // action-item-ui (unlike menu-item-ui) has pre-existing tests that set
+  // [subtitle] AFTER mount and expect the rendered row to keep tracking it
+  // (gh#1374) — a resolve-once-at-connect shim (menu-item-ui's own shape)
+  // would silently stop mirroring once `description` picks up its first
+  // reflected value. `#mirroring` suppresses the authored-flag while WE
+  // write `this.description` ourselves; `#descriptionAuthored` latches
+  // true the moment a REAL (non-mirrored) `description` attribute shows
+  // up, so [description] wins permanently from that point on, even
+  // across later [subtitle] attribute churn.
+  #mirroring = false;
+  #descriptionAuthored = false;
+
+  attributeChangedCallback(name, oldVal, val) {
+    if (name === 'description' && !this.#mirroring) this.#descriptionAuthored = true;
+    super.attributeChangedCallback(name, oldVal, val);
+  }
+
+  // ADR-0063 (gh#1571) compat shim. New-name precedence: once [description]
+  // has ever been authored directly, it wins outright and [subtitle] is
+  // ignored from then on. Until then, [subtitle] mirrors into [description]
+  // on every resolve (initial connect AND every subsequent render), so a
+  // post-mount [subtitle] update keeps propagating exactly like it did
+  // before this shim existed.
+  #resolveSubtitleCompat() {
+    if (this.#descriptionAuthored) return;
+    const mirrored = this.hasAttribute('subtitle') ? this.subtitle : '';
+    if (this.description === mirrored) return;
+    this.#mirroring = true;
+    this.description = mirrored;
+    this.#mirroring = false;
+    if (mirrored && !UIActionItem.#warnedSubtitle) {
+      UIActionItem.#warnedSubtitle = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[AdiaUI] <action-item-ui [subtitle]> is deprecated — use ' +
+        '[description] instead (ADR-0063, gh#1571). Kept working as-is; ' +
+        'no behavior change.',
+      );
+    }
+  }
+
+  // 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() {
+    // ADR-0063 (gh#1571) compat shim — resolve BEFORE #stamp() reads
+    // `this.description`, so there's no wrong-then-right flash.
+    this.#resolveSubtitleCompat();
+
     // Adopt-or-stamp (gh#753): a consumer-authored role survives connect —
     // only stamp "listitem" when the host has no author-set role at all.
     if (!this.hasAttribute('role')) this.setAttribute('role', 'listitem');
@@ -111,21 +183,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.description && !this.#ownChild('[slot="subtitle"]')) {
+      const sub = this.#stampMark(document.createElement('span'));
+      sub.setAttribute('slot', 'subtitle');
+      sub.textContent = this.description;
+      this.appendChild(sub);
+    }
   }
 
   #syncAria() {
@@ -139,21 +218,45 @@ export class UIActionItem extends UIElement {
   }
 
   render() {
-    const iconEl = this.querySelector('[slot="icon"]');
+    // ADR-0063 (gh#1571) compat shim — re-resolve on every render so a
+    // post-mount [subtitle] update keeps mirroring into [description]
+    // until an author sets [description] directly (see #resolveSubtitleCompat).
+    this.#resolveSubtitleCompat();
+
+    // 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 (backed by the `description` prop — ADR-0063, gh#1571)
+    // — only touch elements we stamped.
+    const subEl = this.#ownChild('[slot="subtitle"]');
+    if (this.description) {
+      if (subEl) {
+        if (this.#wasStamped(subEl)) subEl.textContent = this.description;
+      } else {
+        const sub = this.#stampMark(document.createElement('span'));
+        sub.setAttribute('slot', 'subtitle');
+        sub.textContent = this.description;
+        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

@@ -34,14 +34,18 @@ export class UIActionList extends UIElement {
 }
 
 export class UIActionItem extends UIElement {
+  /** Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1571) replacing `subtitle` — converges action-item onto the same spelling <menu-item-ui> adopted under gh#1563. */
+  description: string;
   /** Disables click + keyboard activation; aria-disabled is set. */
   disabled: boolean;
   /** Leading icon name (Phosphor). */
   icon: string;
+  /** DEPRECATED (ADR-0063, gh#1571) — use `description` instead. Same type/default/rendered position; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface, deliberately left unrenamed in this pass — see its own description.) */
+  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."