@adia-ai/web-components 0.0.18 → 0.0.20

package/components/accordion/accordion.css

@@ -1,8 +1,9 @@
 /* ═══════════════════════════════════════════════════════════════
-   ACCORDION-N + ACCORDION-ITEM-N
+   ACCORDION-UI + ACCORDION-ITEM-UI
 
-   Two-element component. Container uses @scope for layout.
-   Item tokens use :where() for zero specificity.
+   Two-element component. Each gets its own @scope block —
+   accordion-item-ui is co-located in accordion.js but is a real
+   custom element and must follow the two-block @scope pattern.
    ═══════════════════════════════════════════════════════════════ */
 
 /* ── Container ── */
@@ -19,115 +20,113 @@
   }
 }
 
-/* ── Item tokens ── */
-:where(accordion-item-ui) {
-  /* ── Colors ── */
-  --accordion-border:          var(--a-border-subtle);
-  --accordion-header-fg:       var(--a-fg-subtle);
-  --accordion-header-fg-hover: var(--a-fg-strong);
-  --accordion-header-bg-hover: var(--a-bg-muted);
-  --accordion-caret-fg:        var(--a-fg-muted);
-  --accordion-caret-fg-hover:  var(--a-fg-subtle);
-
-  /* ── Layout ── */
-  --accordion-radius:          var(--a-radius-md);
-  --accordion-px:              var(--a-space-3);
-  --accordion-py:              var(--a-space-2);
-  --accordion-header-gap:      var(--a-space-2);
-
-  /* ── Typography ── */
-  --accordion-header-font:     var(--a-ui-size);
-  --accordion-header-weight:   var(--a-weight-medium);
-
-  /* ── Transition ── */
-  --accordion-duration-fast:   var(--a-duration-fast);
-  --accordion-duration:        var(--a-duration);
-  --accordion-easing:          var(--a-easing);
-
-  /* ── State ── */
-  --accordion-focus-ring:      var(--a-focus-ring);
-}
-
-/* ── Item base ── */
-accordion-item-ui {
-  box-sizing: border-box;
-  display: block;
-  border-bottom: 1px solid var(--accordion-border);
-}
+/* ── Item ── */
+@scope (accordion-item-ui) {
+  :where(:scope) {
+    /* ── Colors ── */
+    --accordion-item-border:          var(--a-border-subtle);
+    --accordion-item-header-fg:       var(--a-fg-subtle);
+    --accordion-item-header-fg-hover: var(--a-fg-strong);
+    --accordion-item-header-bg-hover: var(--a-bg-muted);
+    --accordion-item-caret-fg:        var(--a-fg-muted);
+    --accordion-item-caret-fg-hover:  var(--a-fg-subtle);
+
+    /* ── Layout ── */
+    --accordion-item-radius:          var(--a-radius-md);
+    --accordion-item-px:              var(--a-space-3);
+    --accordion-item-py:              var(--a-space-2);
+    --accordion-item-header-gap:      var(--a-space-2);
+
+    /* ── Typography ── */
+    --accordion-item-header-font:     var(--a-ui-size);
+    --accordion-item-header-weight:   var(--a-weight-medium);
+
+    /* ── Transition ── */
+    --accordion-item-duration-fast:   var(--a-duration-fast);
+    --accordion-item-duration:        var(--a-duration);
+    --accordion-item-easing:          var(--a-easing);
+
+    /* ── State ── */
+    --accordion-item-focus-ring:      var(--a-focus-ring);
+  }
 
-accordion-item-ui:last-child {
-  border-bottom: none;
-}
+  :scope {
+    box-sizing: border-box;
+    display: block;
+    border-bottom: 1px solid var(--accordion-item-border);
+  }
 
-/* ── Header ── */
-accordion-item-ui [slot="header"] {
-  box-sizing: border-box;
-  display: flex;
-  flex-direction: row;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--accordion-header-gap);
-  padding: var(--accordion-py) var(--accordion-px);
-  border-radius: var(--accordion-radius);
-  cursor: pointer;
-  user-select: none;
-  font-size: var(--accordion-header-font);
-  font-weight: var(--accordion-header-weight);
-  color: var(--accordion-header-fg);
-  background: transparent;
-  transition:
-    color var(--accordion-duration-fast) var(--accordion-easing),
-    background var(--accordion-duration-fast) var(--accordion-easing);
-  outline: none;
-}
+  :scope:last-child {
+    border-bottom: none;
+  }
 
-accordion-item-ui [slot="header"]:hover {
-  color: var(--accordion-header-fg-hover);
-  background: var(--accordion-header-bg-hover);
-}
+  /* ── Header ── */
+  :scope [slot="header"] {
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--accordion-item-header-gap);
+    padding: var(--accordion-item-py) var(--accordion-item-px);
+    border-radius: var(--accordion-item-radius);
+    cursor: pointer;
+    user-select: none;
+    font-size: var(--accordion-item-header-font);
+    font-weight: var(--accordion-item-header-weight);
+    color: var(--accordion-item-header-fg);
+    background: transparent;
+    transition:
+      color var(--accordion-item-duration-fast) var(--accordion-item-easing),
+      background var(--accordion-item-duration-fast) var(--accordion-item-easing);
+    outline: none;
+  }
 
-accordion-item-ui [slot="header"]:hover [slot="caret"] {
-  color: var(--accordion-caret-fg-hover);
-}
+  :scope [slot="header"]:hover {
+    color: var(--accordion-item-header-fg-hover);
+    background: var(--accordion-item-header-bg-hover);
+  }
 
-accordion-item-ui [slot="header"]:focus-visible {
-  box-shadow: var(--accordion-focus-ring);
-}
+  :scope [slot="header"]:hover [slot="caret"] {
+    color: var(--accordion-item-caret-fg-hover);
+  }
 
-accordion-item-ui[open] [slot="header"] {
-  color: var(--accordion-header-fg-hover);
-}
+  :scope [slot="header"]:focus-visible {
+    box-shadow: var(--accordion-item-focus-ring);
+  }
 
-/* ── Header text ── */
-accordion-item-ui [slot="header-text"] {
-  flex: 1;
-  min-width: 0;
-}
+  :scope[open] [slot="header"] {
+    color: var(--accordion-item-header-fg-hover);
+  }
 
-/* ── Caret icon ── */
-accordion-item-ui [slot="caret"] {
-  flex-shrink: 0;
-  color: var(--accordion-caret-fg);
-  transition:
-    transform var(--accordion-duration) var(--accordion-easing),
-    color var(--accordion-duration-fast) var(--accordion-easing);
-  transform: rotate(0deg);
-}
+  /* ── Header text ── */
+  :scope [slot="header-text"] {
+    flex: 1;
+    min-width: 0;
+  }
 
-accordion-item-ui[open] [slot="caret"] {
-  color: var(--accordion-caret-fg-hover);
-}
+  /* ── Caret icon ── */
+  :scope [slot="caret"] {
+    flex-shrink: 0;
+    color: var(--accordion-item-caret-fg);
+    transition:
+      transform var(--accordion-item-duration) var(--accordion-item-easing),
+      color var(--accordion-item-duration-fast) var(--accordion-item-easing);
+    transform: rotate(0deg);
+  }
 
-accordion-item-ui[open] [slot="caret"] {
-  transform: rotate(180deg);
-}
+  :scope[open] [slot="caret"] {
+    color: var(--accordion-item-caret-fg-hover);
+    transform: rotate(180deg);
+  }
 
-/* ── Body content ── */
-accordion-item-ui [slot="body"] {
-  display: none;
-}
+  /* ── Body content ── */
+  :scope [slot="body"] {
+    display: none;
+  }
 
-accordion-item-ui[open] [slot="body"] {
-  display: block;
-  padding: 0 var(--accordion-px) var(--accordion-py);
+  :scope[open] [slot="body"] {
+    display: block;
+    padding: 0 var(--accordion-item-px) var(--accordion-item-py);
+  }
 }

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

@@ -34,9 +34,9 @@ import { AdiaElement } from '../../core/element.js';
 
 class AdiaAgentFeedbackBar extends AdiaElement {
   static properties = {
-    'save-label': { type: String,  default: '',                 attribute: 'save-label' },
-    'save-icon':  { type: String,  default: 'bookmark-simple',  attribute: 'save-icon' },
-    disabled:     { type: Boolean, default: false, reflect: true },
+    saveLabel: { type: String,  default: '',                reflect: true, attribute: 'save-label' },
+    saveIcon:  { type: String,  default: 'bookmark-simple', reflect: true, attribute: 'save-icon' },
+    disabled:  { type: Boolean, default: false, reflect: true },
   };
 
   static template = () => null;
@@ -104,8 +104,8 @@ class AdiaAgentFeedbackBar extends AdiaElement {
 
   render() {
     // Re-sync attributes (label/icon) that may have changed.
-    const label = this['save-label'];
-    const icon = this['save-icon'];
+    const label = this.saveLabel;
+    const icon = this.saveIcon;
     if (this.#saveEl) {
       if (label) {
         this.#saveEl.setAttribute('text', label);
@@ -123,10 +123,10 @@ class AdiaAgentFeedbackBar extends AdiaElement {
     this.#upEl = makeButton({ icon: 'thumbs-up' });
     this.#downEl = makeButton({ icon: 'thumbs-down' });
     this.#saveEl = makeButton({
-      icon: this['save-icon'] || 'bookmark-simple',
-      text: this['save-label'] || '',
+      icon: this.saveIcon || 'bookmark-simple',
+      text: this.saveLabel || '',
     });
-    if (!this['save-label']) this.#saveEl.hidden = true;
+    if (!this.saveLabel) this.#saveEl.hidden = true;
 
     this.#upEl.addEventListener('press', this.#onUp);
     this.#downEl.addEventListener('press', this.#onDown);

package/components/agent-questions/agent-questions.css

@@ -27,6 +27,7 @@
     --agent-questions-option-padding:  var(--a-space-3);
     --agent-questions-option-radius:   var(--a-radius);
     --agent-questions-q-padding:       var(--a-space-1);
+    --agent-questions-option-body-gap: var(--a-space-0-5);
     /* Component-intrinsic measurement; no --a-space-* equivalent */
     --agent-questions-check-size:      20px;
 
@@ -107,7 +108,7 @@
     min-width: 0;
     display: flex;
     flex-direction: column;
-    gap: 2px;
+    gap: var(--agent-questions-option-body-gap);
   }
 
   [data-questions-option-label] {

package/components/agent-questions/agent-questions.js

@@ -30,10 +30,10 @@ import { AdiaElement } from '../../core/element.js';
 
 class AdiaAgentQuestions extends AdiaElement {
   static properties = {
-    multi:          { type: Boolean, default: false, reflect: true },
-    question:       { type: String,  default: '',    reflect: true },
-    helper:         { type: String,  default: '',    reflect: true },
-    'submit-label': { type: String,  default: 'Continue', attribute: 'submit-label' },
+    multi:       { type: Boolean, default: false, reflect: true },
+    question:    { type: String,  default: '',    reflect: true },
+    helper:      { type: String,  default: '',    reflect: true },
+    submitLabel: { type: String,  default: 'Continue', reflect: true, attribute: 'submit-label' },
   };
 
   static template = () => null;
@@ -74,7 +74,7 @@ class AdiaAgentQuestions extends AdiaElement {
       this.#helperEl.hidden = !this.helper;
     }
     if (this.#submitEl) {
-      this.#submitEl.setAttribute('text', this['submit-label'] || 'Continue');
+      this.#submitEl.setAttribute('text', this.submitLabel || 'Continue');
       this.#submitEl.hidden = !this.multi;
     }
   }
@@ -96,7 +96,7 @@ class AdiaAgentQuestions extends AdiaElement {
     this.#optionsEl.setAttribute('data-questions-options', '');
 
     this.#submitEl = document.createElement('button-ui');
-    this.#submitEl.setAttribute('text', this['submit-label'] || 'Continue');
+    this.#submitEl.setAttribute('text', this.submitLabel || 'Continue');
     this.#submitEl.setAttribute('variant', 'primary');
     this.#submitEl.setAttribute('size', 'sm');
     this.#submitEl.setAttribute('disabled', '');

package/components/agent-reasoning/agent-reasoning.js

@@ -76,15 +76,29 @@ class AdiaAgentReasoning extends AdiaElement {
   #finishTimer = null;
   #summaryEl = null;
   #bodyEl = null;
+  #bound = false;
 
   get entries() { return this.#entries; }
 
   connected() {
+    if (this.#bound) return;
+    this.#bound = true;
     this.#startTime = Date.now();
     this.#timerInterval = setInterval(() => this.#tickTimers(), 1000);
     this.#buildShell();
   }
 
+  // Single delegated handler for every nested timeline-item's toggle event.
+  // Each step element carries its id on dataset.stepId so the handler can
+  // resolve which step fired without per-item closures.
+  #onStepToggle = (e) => {
+    const item = e.target.closest('timeline-item-ui[data-step-id]');
+    if (!item || !this.#bodyEl?.contains(item)) return;
+    this.dispatchEvent(new CustomEvent('reasoning-step-toggle', {
+      bubbles: true, detail: { stepId: item.dataset.stepId },
+    }));
+  };
+
   disconnected() {
     if (this.#timerInterval != null) {
       clearInterval(this.#timerInterval);
@@ -95,8 +109,10 @@ class AdiaAgentReasoning extends AdiaElement {
       this.#finishTimer = null;
     }
     this.#summaryEl?.removeEventListener('click', this.#onSummaryClick);
+    this.#bodyEl?.removeEventListener('timeline-toggle', this.#onStepToggle);
     this.#summaryEl = null;
     this.#bodyEl = null;
+    this.#bound = false;
   }
 
   // ── Public API ──
@@ -259,6 +275,7 @@ class AdiaAgentReasoning extends AdiaElement {
 
     this.#bodyEl = document.createElement('div');
     this.#bodyEl.setAttribute('data-reasoning-body', '');
+    this.#bodyEl.addEventListener('timeline-toggle', this.#onStepToggle);
     this.appendChild(this.#bodyEl);
 
     this.#render();
@@ -364,11 +381,9 @@ class AdiaAgentReasoning extends AdiaElement {
 
     if (step.outcomes?.length) item.outcomes = step.outcomes;
 
-    item.addEventListener('timeline-toggle', () => {
-      this.dispatchEvent(new CustomEvent('reasoning-step-toggle', {
-        bubbles: true, detail: { stepId: step.id },
-      }));
-    });
+    // Step id stamped on dataset so the parent's delegated #onStepToggle
+    // listener (wired in #buildShell) can resolve which step fired.
+    item.dataset.stepId = step.id || '';
     return item;
   }
 

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

@@ -13,6 +13,11 @@
     }
   ],
   "properties": {
+    "collapsed": {
+      "description": "Hide the trace body. Default-visible disclosure (matches the agent-* family — agent-reasoning, agent-artifact). Set to opt out.",
+      "type": "boolean",
+      "default": false
+    },
     "component": {
       "const": "AgentTrace"
     },
@@ -20,11 +25,6 @@
       "description": "Fallback summary label.",
       "type": "string",
       "default": ""
-    },
-    "open": {
-      "description": "Start expanded.",
-      "type": "boolean",
-      "default": false
     }
   },
   "required": [

package/components/agent-trace/agent-trace.js

@@ -38,8 +38,10 @@ import { AdiaElement } from '../../core/element.js';
 
 class AdiaAgentTrace extends AdiaElement {
   static properties = {
-    open:  { type: Boolean, default: false, reflect: true },
-    label: { type: String,  default: '',    reflect: true },
+    // agent-* family is default-visible disclosure (see component-token-contract.md
+    // §"Toggle state naming"). Use `collapsed` to hide; bare element shows.
+    collapsed: { type: Boolean, default: false, reflect: true },
+    label:     { type: String,  default: '',    reflect: true },
   };
 
   static template = () => null;
@@ -68,9 +70,9 @@ class AdiaAgentTrace extends AdiaElement {
   }
 
   #onToggle = () => {
-    this.open = this.#rootEl.hasAttribute('open');
+    this.collapsed = !this.#rootEl.hasAttribute('open');
     this.dispatchEvent(new CustomEvent('trace-toggle', {
-      bubbles: true, detail: { open: this.open },
+      bubbles: true, detail: { collapsed: this.collapsed },
     }));
   };
 
@@ -78,7 +80,7 @@ class AdiaAgentTrace extends AdiaElement {
     this.innerHTML = '';
     this.#rootEl = document.createElement('details');
     this.#rootEl.setAttribute('data-trace-root', '');
-    if (this.open) this.#rootEl.setAttribute('open', '');
+    if (!this.collapsed) this.#rootEl.setAttribute('open', '');
     this.#rootEl.addEventListener('toggle', this.#onToggle);
     this.appendChild(this.#rootEl);
     this.#render();

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

@@ -12,8 +12,8 @@ props:
     description: Fallback summary label.
     type: string
     default: ""
-  open:
-    description: Start expanded.
+  collapsed:
+    description: Hide the trace body. Default-visible disclosure (matches the agent-* family — agent-reasoning, agent-artifact). Set to opt out.
     type: boolean
     default: false
     reflect: true

package/components/alert/alert.a2ui.json

@@ -32,14 +32,13 @@
       "default": ""
     },
     "variant": {
-      "description": "Semantic color variant. `error` kept as alias for `danger`.",
+      "description": "Semantic color variant.",
       "type": "string",
       "enum": [
         "default",
         "info",
         "success",
         "warning",
-        "error",
         "danger",
         "muted",
         "neutral"

package/components/alert/alert.css

@@ -37,28 +37,28 @@
     --alert-bg:      var(--a-info-muted);
     --alert-fg:      var(--a-info-text);
     --alert-border:  var(--a-info-border-subtle);
-    --alert-icon-fg: var(--a-info);
+    --alert-icon-fg: var(--a-info-strong);
   }
 
   :scope[variant="success"] {
     --alert-bg:      var(--a-success-muted);
     --alert-fg:      var(--a-success-text);
     --alert-border:  var(--a-success-border-subtle);
-    --alert-icon-fg: var(--a-success);
+    --alert-icon-fg: var(--a-success-strong);
   }
 
   :scope[variant="warning"] {
     --alert-bg:      var(--a-warning-muted);
     --alert-fg:      var(--a-warning-text);
     --alert-border:  var(--a-warning-border-subtle);
-    --alert-icon-fg: var(--a-warning);
+    --alert-icon-fg: var(--a-warning-strong);
   }
 
   :scope[variant="danger"] {
     --alert-bg:      var(--a-danger-muted);
     --alert-fg:      var(--a-danger-text);
     --alert-border:  var(--a-danger-border-subtle);
-    --alert-icon-fg: var(--a-danger);
+    --alert-icon-fg: var(--a-danger-strong);
   }
 
   /* ── Slots ── */

package/components/alert/alert.yaml

@@ -21,7 +21,7 @@ props:
     type: string
     default: ""
   variant:
-    description: Semantic color variant. `error` kept as alias for `danger`.
+    description: Semantic color variant.
     type: string
     default: default
     enum:
@@ -29,7 +29,6 @@ props:
       - info
       - success
       - warning
-      - error
       - danger
       - muted
       - neutral

package/components/avatar/avatar.a2ui.json

@@ -17,12 +17,12 @@
       "const": "Avatar"
     },
     "icon": {
-      "description": "Phosphor icon name shown instead of initials when `src`/`name` are empty.",
+      "description": "Phosphor icon name shown instead of initials when `src`/`text` are empty.",
       "type": "string",
       "default": ""
     },
     "name": {
-      "description": "User name for initials (first letter of each word, max 2).",
+      "description": "Deprecated alias for `text` (logs a one-shot console warning; will be removed in a future release). New code should use `text=` instead.",
       "type": "string",
       "default": ""
     },
@@ -57,7 +57,7 @@
       "default": ""
     },
     "text": {
-      "description": "Display name (for initials)",
+      "description": "Display string (full name or initials). Initials derive from spaces — first letter of each word, max 2.",
       "type": "string",
       "default": ""
     }

package/components/avatar/avatar.js

@@ -32,12 +32,22 @@ class AdiaAvatar extends AdiaElement {
 
   static template = () => null;
 
+  static #nameWarned = false;
+
   #imgEl = null;
   #initialsEl = null;
   #iconEl = null;
 
   connected() {
     this.setAttribute('role', 'img');
+    if (this.name && !this.text && !AdiaAvatar.#nameWarned) {
+      AdiaAvatar.#nameWarned = true;
+      // eslint-disable-next-line no-console
+      console.warn(
+        `[AdiaUI] <avatar-ui name="…"> is deprecated — use text="…" instead. ` +
+        `Docs: https://ui-kit.exe.xyz/site/components/avatar`
+      );
+    }
   }
 
   render() {

package/components/avatar/avatar.yaml

@@ -8,12 +8,16 @@ category: display
 version: 1
 description: Avatar with image → initials → empty fallback chain.
 props:
+  text:
+    description: Display string (full name or initials). Initials derive from spaces — first letter of each word, max 2.
+    type: string
+    default: ""
   name:
-    description: User name for initials (first letter of each word, max 2).
+    description: "Deprecated alias for `text` (logs a one-shot console warning; will be removed in a future release). New code should use `text=` instead."
     type: string
     default: ""
   icon:
-    description: Phosphor icon name shown instead of initials when `src`/`name` are empty.
+    description: Phosphor icon name shown instead of initials when `src`/`text` are empty.
     type: string
     default: ""
   shape:
@@ -43,10 +47,6 @@ props:
     description: Image source URL. Falls back to initials on error.
     type: string
     default: ""
-  text:
-    description: Display name (for initials)
-    type: string
-    default: ""
 events: {}
 slots:
   icon:

package/components/button/button.a2ui.json

@@ -18,6 +18,19 @@
       "type": "string",
       "default": "button"
     },
+    "color": {
+      "description": "Semantic intent — composes with [variant]. `<button-ui variant=\"solid\" color=\"danger\">` = filled destructive action; `<button-ui variant=\"outline\" color=\"success\">` = outlined success affordance.",
+      "type": "string",
+      "enum": [
+        "default",
+        "accent",
+        "info",
+        "success",
+        "warning",
+        "danger"
+      ],
+      "default": ""
+    },
     "component": {
       "const": "Button"
     },
@@ -54,14 +67,13 @@
       "default": ""
     },
     "variant": {
-      "description": "Visual style variant. `default` is the base style; `link` renders the button as underlined text for inline actions.",
+      "description": "Visual style — `solid` (default fill), `outline`, `ghost`, `link`. `default` / `primary` are aliases of `solid`. Style is independent of semantic intent — to express destructive / success / info / warning intent, set [color=\"…\"] alongside.",
       "type": "string",
       "enum": [
         "default",
         "solid",
         "outline",
         "ghost",
-        "danger",
         "primary",
         "secondary",
         "soft",