@adia-ai/web-components 0.6.49 → 0.6.50

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog — @adia-ai/web-components
 
+## [0.6.50] — 2026-05-30
+
+### Changed — `slot="caret"` disclosure-indicator convention + FEEDBACK-89 (ADR-0036)
+
+- **`components/tree/` (`tree-item-ui`) + `components/pane/` (`pane-ui`)** — renamed the expand/collapse indicator slot `slot="chevron"` → **`slot="caret"`** (and tokens `--*-chevron-*` → `--*-caret-*`, e.g. `--tree-caret-size`, `--pane-caret-fg`), standardizing on the slot name already used by `accordion-item-ui` / `nav-group-ui` / `select-ui` and matching the Phosphor `caret-*` icon vocabulary. **No backward-compat alias** (hard rename; the caret is auto-stamped, so blast radius is small). See [ADR-0036](../../.brain/adrs/0036-caret-slot-disclosure-convention.md).
+- **`tree-item-ui` adopt-or-stamp (FEEDBACK-89)** — `#stamp()` now adopts a consumer's declarative `slot="caret"` and `slot="actions"` children into the auto-stamped row instead of leaving them as siblings below it. A `<button-ui slot="actions">` (the natural way to add a per-row action — add / rename / overflow) now lands inline in the styled, hover-revealed actions area. The host `#onClick` already excludes `[slot="actions"] *` from row selection, so adoption is click-safe. +3 unit tests.
+- **`dist/` CDN bundles** (`web-components.min.css` + `web-components.min.js`) regenerated to carry the renamed `--*-caret-*` tokens + caret stamp logic.
+
 ## [0.6.49] — 2026-05-30
 
 ### Changed — card-ui header slot sweep + `nav-group-ui` fixes (demos)

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

@@ -379,7 +379,7 @@ export class UIAgentReasoning extends UIElement {
       <span data-reasoning-meta>
         ${total ? `<span data-reasoning-counter>${done}/${total}</span>` : ''}
         <span data-reasoning-time>${elapsed}s</span>
-        <icon-ui name="${this.collapsed ? 'caret-right' : 'caret-up'}" color="muted" data-reasoning-chevron></icon-ui>
+        <icon-ui name="${this.collapsed ? 'caret-right' : 'caret-up'}" color="muted" data-reasoning-caret></icon-ui>
       </span>
     `;
 

package/components/agent-trace/agent-trace.css

@@ -27,7 +27,7 @@
     --agent-trace-detail-label-col-default: 9rem;
 
     /* ── Motion ── */
-    --agent-trace-chevron-dur-default:   var(--a-duration-fast);
+    --agent-trace-caret-dur-default:   var(--a-duration-fast);
   }
 
   :scope {
@@ -50,7 +50,7 @@
     border-radius: var(--a-radius-sm);
     padding: var(--a-space-0-5) var(--a-space-1);
     margin: calc(var(--a-space-0-5) * -1) calc(var(--a-space-1) * -1);
-    transition: background var(--agent-trace-chevron-dur, var(--agent-trace-chevron-dur-default));
+    transition: background var(--agent-trace-caret-dur, var(--agent-trace-caret-dur-default));
   }
 
   [data-trace-root] > summary:hover {
@@ -94,12 +94,12 @@
     margin-inline: 2px;
   }
 
-  [data-trace-chevron] {
+  [data-trace-caret] {
     flex-shrink: 0;
-    transition: transform var(--agent-trace-chevron-dur, var(--agent-trace-chevron-dur-default));
+    transition: transform var(--agent-trace-caret-dur, var(--agent-trace-caret-dur-default));
   }
 
-  [data-trace-root][open] [data-trace-chevron] {
+  [data-trace-root][open] [data-trace-caret] {
     transform: rotate(90deg);
   }
 
@@ -225,20 +225,20 @@
     text-align: end;
   }
 
-  /* Chevron in the trailing column */
-  [data-trace-row-chevron] {
+  /* Caret in the trailing column */
+  [data-trace-row-caret] {
     --a-icon-size: 0.875em;
     justify-self: end;
     align-self: center;
-    transition: transform var(--a-duration-fast) var(--agent-trace-chevron-dur, var(--a-duration-fast));
+    transition: transform var(--a-duration-fast) var(--agent-trace-caret-dur, var(--a-duration-fast));
     color: var(--agent-trace-fg-muted, var(--agent-trace-fg-muted-default));
   }
 
-  details[data-trace-row][open] > summary > [data-trace-row-chevron] {
+  details[data-trace-row][open] > summary > [data-trace-row-caret] {
     transform: rotate(90deg);
   }
 
-  [data-trace-row-chevron-spacer] {
+  [data-trace-row-caret-spacer] {
     width: 0.875em;
     justify-self: end;
   }

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

@@ -128,7 +128,7 @@ class UIAgentTrace extends UIElement {
     this.#rootEl.innerHTML = `
       <summary>
         <span data-trace-status>${pillsHTML}</span>
-        <icon-ui name="caret-right" color="muted" size="sm" data-trace-chevron></icon-ui>
+        <icon-ui name="caret-right" color="muted" size="sm" data-trace-caret></icon-ui>
       </summary>
       <div data-trace-body>
         ${this.#metrics.length ? `<div data-trace-rows${hasAnyDetails ? ' data-has-details' : ''}>${headerRow}${rowsHTML}</div>` : ''}
@@ -156,8 +156,8 @@ class UIAgentTrace extends UIElement {
       <span data-trace-aux>${aux}</span>
       ${hasAnyDetails
         ? (hasDetails
-            ? '<icon-ui name="caret-right" color="muted" data-trace-row-chevron></icon-ui>'
-            : '<span data-trace-row-chevron-spacer aria-hidden="true"></span>')
+            ? '<icon-ui name="caret-right" color="muted" data-trace-row-caret></icon-ui>'
+            : '<span data-trace-row-caret-spacer aria-hidden="true"></span>')
         : ''}
     `;
 

package/components/pane/pane.a2ui.json

@@ -82,6 +82,9 @@
       "text-area"
     ],
     "slots": {
+      "caret": {
+        "description": "Collapse caret inside the header. Auto-stamped as `<icon-ui slot=\"caret\" name=\"caret-right\">` (rotates on `[collapsed]`). Supply your own `slot=\"caret\"` child in the header to customize — adopt-or-stamp honors a declarative caret instead of stamping."
+      },
       "header": {
         "description": "Auto-created header element with label text and toggle arrow"
       }

package/components/pane/pane.class.js

@@ -100,12 +100,13 @@ export class UIPane extends UIElement {
       header.setAttribute('tabindex', '0');
       header.setAttribute('aria-expanded', String(!this.collapsed));
 
-      // Stamp chevron icon if not present
-      if (!header.querySelector('[slot="chevron"]')) {
-        const chevron = document.createElement('icon-ui');
-        chevron.setAttribute('slot', 'chevron');
-        chevron.setAttribute('name', 'caret-right');
-        header.append(chevron);
+      // Stamp the caret icon if not present (adopt-or-stamp: a declarative
+      // [slot="caret"] child is honored, else we stamp the default).
+      if (!header.querySelector('[slot="caret"]')) {
+        const caret = document.createElement('icon-ui');
+        caret.setAttribute('slot', 'caret');
+        caret.setAttribute('name', 'caret-right');
+        header.append(caret);
       }
     }
   }

package/components/pane/pane.css

@@ -29,7 +29,7 @@
 
     /* ── Header interaction ── */
     --pane-header-bg-hover-default: var(--a-bg-subtle);
-    --pane-chevron-fg-default:      var(--a-fg-muted);
+    --pane-caret-fg-default:        var(--a-fg-muted);
 
     /* ── Section header ── */
     --pane-section-header-weight-default: var(--a-weight-medium);
@@ -107,17 +107,17 @@
     box-shadow: var(--a-focus-ring) inset;
   }
 
-  /* Collapse indicator — stamped by JS as icon-ui */
-  & > header > [slot="chevron"] {
+  /* Collapse indicator (caret) — stamped by JS as icon-ui */
+  & > header > [slot="caret"] {
     --a-icon-size: var(--a-caret-size);
     flex-shrink: 0;
     margin-inline-start: auto;
-    color: var(--pane-chevron-fg, var(--pane-chevron-fg-default));
+    color: var(--pane-caret-fg, var(--pane-caret-fg-default));
     transition: transform var(--pane-duration, var(--pane-duration-default)) var(--pane-easing, var(--pane-easing-default));
     transform: rotate(90deg);
   }
 
-  :scope[collapsed] > header > [slot="chevron"] {
+  :scope[collapsed] > header > [slot="caret"] {
     transform: rotate(0deg);
   }
 

package/components/pane/pane.yaml

@@ -62,6 +62,12 @@ events:
 slots:
   header:
     description: Auto-created header element with label text and toggle arrow
+  caret:
+    description: >-
+      Collapse caret inside the header. Auto-stamped as
+      `<icon-ui slot="caret" name="caret-right">` (rotates on `[collapsed]`).
+      Supply your own `slot="caret"` child in the header to customize —
+      adopt-or-stamp honors a declarative caret instead of stamping.
 states:
 - name: idle
   description: Default, ready for interaction.

package/components/tree/tree-item.a2ui.json

@@ -65,6 +65,12 @@
       "Accordion"
     ],
     "slots": {
+      "actions": {
+        "description": "Per-row action buttons (rename / add / overflow menu), right-aligned and hover-revealed. A declarative `slot=\"actions\"` child is adopted into the auto-stamped row (FEEDBACK-89), so it sits inline in the row rather than wrapping below it."
+      },
+      "caret": {
+        "description": "Override slot for the expand/collapse caret. Auto-stamped as `<icon-ui slot=\"caret\" name=\"caret-right\">` (rotates on `[open]`, hidden for leaf nodes). Supply your own `slot=\"caret\"` child to customize — adopt-or-stamp moves a declarative caret into the row."
+      },
       "icon": {
         "description": "Override the leading [icon] glyph with a custom slotted element (custom icon-ui, folder open/closed glyph, file-type marker). Mutually exclusive with the [icon] attribute — slot child wins."
       }

package/components/tree/tree-item.yaml

@@ -47,6 +47,18 @@ slots:
       Override the leading [icon] glyph with a custom slotted element (custom
       icon-ui, folder open/closed glyph, file-type marker). Mutually exclusive
       with the [icon] attribute — slot child wins.
+  caret:
+    description: >-
+      Override slot for the expand/collapse caret. Auto-stamped as
+      `<icon-ui slot="caret" name="caret-right">` (rotates on `[open]`,
+      hidden for leaf nodes). Supply your own `slot="caret"` child to
+      customize — adopt-or-stamp moves a declarative caret into the row.
+  actions:
+    description: >-
+      Per-row action buttons (rename / add / overflow menu), right-aligned
+      and hover-revealed. A declarative `slot="actions"` child is adopted
+      into the auto-stamped row (FEEDBACK-89), so it sits inline in the row
+      rather than wrapping below it.
 
 a2ui:
   rules:
@@ -72,7 +84,7 @@ a2ui:
     - >-
       Nest further <tree-item-ui> in the default slot only — no
       <list-item-ui>, <nav-item-ui>, or arbitrary content inside a
-      tree row. The chevron is auto-stamped when the row has nested
+      tree row. The caret is auto-stamped when the row has nested
       tree-item-ui children.
 
 keywords:

package/components/tree/tree.a2ui.json

@@ -126,8 +126,8 @@
       "--tree-bg-selected": {
         "description": "Background color when selected"
       },
-      "--tree-chevron-size": {
-        "description": "Size of the collapse chevron icon"
+      "--tree-caret-size": {
+        "description": "Size of the collapse caret icon"
       },
       "--tree-duration": {
         "description": "Transition duration"
@@ -139,7 +139,7 @@
         "description": "Primary text color"
       },
       "--tree-fg-muted": {
-        "description": "Muted text color (icons, chevrons)"
+        "description": "Muted text color (icons, carets)"
       },
       "--tree-focus-ring": {
         "description": "Focus ring box-shadow"

package/components/tree/tree.class.js

@@ -293,11 +293,17 @@ export class UITreeItem extends UIElement {
     row.setAttribute('slot', 'row');
     row.setAttribute('tabindex', '0');
 
-    // Chevron
-    const chevron = document.createElement('icon-ui');
-    chevron.setAttribute('slot', 'chevron');
-    chevron.setAttribute('name', 'caret-right');
-    row.appendChild(chevron);
+    // Caret — adopt a declarative [slot="caret"] child if the consumer supplied
+    // one, else stamp the default. (Adopt-or-stamp; same pattern as actions.)
+    const declaredCaret = this.querySelector(':scope > [slot="caret"]');
+    if (declaredCaret) {
+      row.appendChild(declaredCaret);
+    } else {
+      const caret = document.createElement('icon-ui');
+      caret.setAttribute('slot', 'caret');
+      caret.setAttribute('name', 'caret-right');
+      row.appendChild(caret);
+    }
 
     // Icon
     if (this.icon) {
@@ -320,10 +326,19 @@ export class UITreeItem extends UIElement {
     if (this.badge) badgeEl.textContent = this.badge;
     row.appendChild(badgeEl);
 
-    // Actions slot placeholder
-    const actions = document.createElement('span');
-    actions.setAttribute('slot', 'actions');
-    row.appendChild(actions);
+    // Actions — adopt pre-existing declarative [slot="actions"] children into
+    // the row (FEEDBACK-89) so per-row action buttons land in the styled,
+    // hover-revealed actions area; else stamp an empty placeholder. The host
+    // #onClick already excludes [slot="actions"] * from row selection, so
+    // adoption is click-safe.
+    const declaredActions = this.querySelectorAll(':scope > [slot="actions"]');
+    if (declaredActions.length) {
+      for (const a of declaredActions) row.appendChild(a);
+    } else {
+      const actions = document.createElement('span');
+      actions.setAttribute('slot', 'actions');
+      row.appendChild(actions);
+    }
 
     this.prepend(row);
   }

package/components/tree/tree.css

@@ -7,7 +7,7 @@
     --tree-row-gap-default:         var(--a-space-1);
     --tree-actions-gap-default:     var(--a-space-0-5);
     --tree-indent-default:          var(--a-space-4);
-    --tree-chevron-size-default:    var(--a-space-2);
+    --tree-caret-size-default:      var(--a-space-2);
     --tree-icon-size-default:       var(--a-space-3);
 
     /* ── Typography ── */
@@ -47,7 +47,7 @@
     --tree-item-row-gap:       var(--tree-row-gap, var(--a-space-1));
     --tree-item-actions-gap:   var(--tree-actions-gap, var(--a-space-0-5));
     --tree-item-indent:        var(--tree-indent, var(--a-space-4));
-    --tree-item-chevron-size:  var(--tree-chevron-size, var(--a-space-2));
+    --tree-item-caret-size:    var(--tree-caret-size, var(--a-space-2));
     --tree-item-icon-size:     var(--tree-icon-size, var(--a-space-3));
 
     --tree-item-fg:            var(--tree-fg, var(--a-fg));
@@ -92,21 +92,21 @@
 
   /* :scope[selected] rules moved outside @scope — see tree-ui Safari note at end of file. */
 
-  /* ── Chevron ── */
-  [slot="chevron"] {
-    --a-icon-size: var(--tree-chevron-size, var(--tree-chevron-size-default));
+  /* ── Caret ── */
+  [slot="caret"] {
+    --a-icon-size: var(--tree-caret-size, var(--tree-caret-size-default));
     flex-shrink: 0;
     color: var(--tree-fg-muted, var(--tree-fg-muted-default));
     transition: transform var(--tree-duration, var(--tree-duration-default)) var(--tree-easing, var(--tree-easing-default));
     transform: rotate(90deg);
   }
 
-  :scope:not([open]) > [slot="row"] > [slot="chevron"] {
+  :scope:not([open]) > [slot="row"] > [slot="caret"] {
     transform: rotate(0deg);
   }
 
-  /* Hide chevron for leaf nodes */
-  :scope:not(:has(> tree-item-ui)) > [slot="row"] > [slot="chevron"] {
+  /* Hide caret for leaf nodes */
+  :scope:not(:has(> tree-item-ui)) > [slot="row"] > [slot="caret"] {
     visibility: hidden;
   }
 

package/components/tree/tree.test.js

@@ -101,3 +101,55 @@ describe('<tree-ui> tree-select forwards modifier keys (FB-46)', () => {
     expect(received.shiftKey).toBe(false);
   });
 });
+
+describe('<tree-item-ui> caret slot + actions adoption (caret convention + FB-89)', () => {
+  let host;
+  const settle = () => new Promise((r) => setTimeout(r, 30));
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+  afterEach(() => host.remove());
+
+  it('auto-stamps a slot="caret" icon (renamed from slot="chevron")', async () => {
+    const item = document.createElement('tree-item-ui');
+    item.setAttribute('text', 'Colors');
+    host.appendChild(item);
+    await settle();
+    const row = item.querySelector(':scope > [slot="row"]');
+    expect(row.querySelector('[slot="caret"]')).toBeTruthy();
+    expect(row.querySelector('[slot="chevron"]')).toBeNull();
+  });
+
+  it('adopts a declarative slot="actions" child into the stamped row (FB-89)', async () => {
+    const item = document.createElement('tree-item-ui');
+    item.setAttribute('text', 'Colors');
+    const btn = document.createElement('button-ui');
+    btn.setAttribute('slot', 'actions');
+    btn.setAttribute('icon', 'plus');
+    item.appendChild(btn);
+    host.appendChild(item);
+    await settle();
+    const row = item.querySelector(':scope > [slot="row"]');
+    // The action button is now INSIDE the row, not a sibling left below it.
+    expect(btn.parentElement).toBe(row);
+    expect(item.querySelector(':scope > [slot="actions"]')).toBeNull();
+  });
+
+  it('adopts a declarative slot="caret" child instead of stamping a default', async () => {
+    const item = document.createElement('tree-item-ui');
+    item.setAttribute('text', 'Colors');
+    const customCaret = document.createElement('icon-ui');
+    customCaret.setAttribute('slot', 'caret');
+    customCaret.setAttribute('name', 'folder');
+    item.appendChild(customCaret);
+    host.appendChild(item);
+    await settle();
+    const row = item.querySelector(':scope > [slot="row"]');
+    const carets = row.querySelectorAll('[slot="caret"]');
+    expect(carets.length).toBe(1);                    // no double-stamp
+    expect(carets[0]).toBe(customCaret);              // consumer's caret used
+    expect(carets[0].getAttribute('name')).toBe('folder');
+  });
+});

package/components/tree/tree.yaml

@@ -59,8 +59,8 @@ tokens:
     description: Background color on hover
   --tree-bg-selected:
     description: Background color when selected
-  --tree-chevron-size:
-    description: Size of the collapse chevron icon
+  --tree-caret-size:
+    description: Size of the collapse caret icon
   --tree-duration:
     description: Transition duration
   --tree-easing:
@@ -68,7 +68,7 @@ tokens:
   --tree-fg:
     description: Primary text color
   --tree-fg-muted:
-    description: Muted text color (icons, chevrons)
+    description: Muted text color (icons, carets)
   --tree-focus-ring:
     description: Focus ring box-shadow
   --tree-font-size:
@@ -121,7 +121,7 @@ a2ui:
       rows — selection is managed by the parent and bubbles once.
       Detail = {item, text, value, ctrlKey, metaKey, shiftKey}.
     - >-
-      Per ADR-0027, <tree-ui> composes <icon-ui> (for chevrons) but
+      Per ADR-0027, <tree-ui> composes <icon-ui> (for carets) but
       does NOT auto-import its children. Consumer pages must
       explicitly import both <tree-ui> and <tree-item-ui>.
 anti_patterns: []