@adia-ai/web-components 0.5.4 → 0.5.6

package/components/slider/class.js

@@ -42,13 +42,31 @@ export class UISlider extends UIFormElement {
     step:   { type: Number,  default: 1,  reflect: true },
     label:  { type: String,  default: '', reflect: true },
     suffix: { type: String,  default: '', reflect: true },
+    // §184 (v0.5.5, FEEDBACK-08 §4): declarative debounce for the
+    // `input` event when driving expensive computation (palette regen,
+    // shader compile, large list reflow). When > 0, value updates +
+    // visual feedback are immediate but `input` event emission is
+    // debounced — only the FINAL value in the throttle window dispatches.
+    // `change` fires unthrottled on pointerup / track click / keyboard;
+    // any pending `input` flushes BEFORE `change` so consumers always
+    // see input→input→…→input→change ordering. throttle="0" (default)
+    // preserves the pre-§184 every-pointer-move-fires-input behavior.
+    throttle: { type: Number, default: 0, reflect: true },
   };
 
   static template = () => null;
 
+  // §184: per-instance hint id counter for aria-describedby wiring.
+  static #hintSeq = 0;
+
   #trackEl = null;
   #thumbEl = null;
   #dragging = false;
+  // §184 (v0.5.5, FEEDBACK-08 §4): debounce timer for the `input`
+  // event. When `throttle > 0`, #setValue stores a pending dispatch
+  // here + restarts the timer on every value change. Flushed before
+  // any `change` event so input always precedes change.
+  #inputTimer = null;
 
   get #pct() {
     const range = this.max - this.min;
@@ -69,6 +87,9 @@ export class UISlider extends UIFormElement {
     if (this.label) this.setAttribute('aria-label', this.label);
 
     if (!this.querySelector('[slot="track"]')) {
+      // §184 (v0.5.5, FEEDBACK-08 §7): hint slot stamped underneath
+      // the track when [hint] is set. Wired to aria-describedby below.
+      const hintId = this.hint ? `slider-hint-${++UISlider.#hintSeq}` : '';
       this.innerHTML = `
         <div slot="header">
           ${this.label ? `<span slot="label">${this.label}</span>` : ''}
@@ -81,7 +102,9 @@ export class UISlider extends UIFormElement {
           <div slot="fill"></div>
           <div slot="thumb" tabindex="0"></div>
         </div>
+        ${this.hint ? `<span slot="hint" id="${hintId}">${this.hint}</span>` : ''}
       `;
+      if (this.hint) this.setAttribute('aria-describedby', hintId);
     }
 
     this.#trackEl = this.querySelector('[slot="track"]');
@@ -148,9 +171,36 @@ export class UISlider extends UIFormElement {
   #setValue(v) {
     if (v === this.value) return;
     this.value = v;
+    // §184: when throttle > 0, debounce the `input` dispatch.
+    // The value update + UI is still immediate; only event emission is
+    // accumulated. Same value can dispatch input multiple times across
+    // pointer moves, but the throttle collapses them to one trailing
+    // emission at quiet+throttle ms.
+    const t = Number(this.throttle) || 0;
+    if (t > 0) {
+      if (this.#inputTimer != null) clearTimeout(this.#inputTimer);
+      this.#inputTimer = setTimeout(() => {
+        this.#inputTimer = null;
+        this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+      }, t);
+      return;
+    }
     this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
   }
 
+  /**
+   * §184: flush any pending throttled `input` dispatch synchronously.
+   * Called before `change` so consumers see the trailing input event
+   * BEFORE the change commit. No-op when no timer is pending.
+   */
+  #flushInput() {
+    if (this.#inputTimer != null) {
+      clearTimeout(this.#inputTimer);
+      this.#inputTimer = null;
+      this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    }
+  }
+
   #onPointerDown = (e) => {
     if (this.disabled) return;
     e.preventDefault();
@@ -170,12 +220,14 @@ export class UISlider extends UIFormElement {
     this.#thumbEl.releasePointerCapture(e.pointerId);
     this.#thumbEl.removeEventListener('pointermove', this.#onPointerMove);
     this.#thumbEl.removeEventListener('pointerup', this.#onPointerUp);
+    this.#flushInput(); // §184: pending throttled input fires before change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
   #onTrackClick = (e) => {
     if (this.disabled || e.target === this.#thumbEl) return;
     this.#setValue(this.#valueFromX(e.clientX));
+    this.#flushInput(); // §184: ensure trailing input precedes change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
@@ -193,6 +245,7 @@ export class UISlider extends UIFormElement {
     }
     e.preventDefault();
     this.#setValue(this.#snap(v));
+    this.#flushInput(); // §184: trailing input fires before change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
@@ -203,6 +256,11 @@ export class UISlider extends UIFormElement {
     this.#thumbEl?.removeEventListener('pointermove', this.#onPointerMove);
     this.#thumbEl?.removeEventListener('pointerup', this.#onPointerUp);
     this.removeEventListener('keydown', this.#onKey);
+    // §184: drop any pending throttle timer (no flush — element is gone)
+    if (this.#inputTimer != null) {
+      clearTimeout(this.#inputTimer);
+      this.#inputTimer = null;
+    }
     this.#trackEl = null;
     this.#thumbEl = null;
   }

package/components/slider/slider.a2ui.json

@@ -31,6 +31,11 @@
       "type": "string",
       "default": ""
     },
+    "hint": {
+      "description": "§184 (v0.5.5, FEEDBACK-08 §7): small caption rendered beneath the slider track. Sets `aria-describedby` on the host so screen readers announce it as a description (distinct from `aria-label`, which comes from `label`). Does not conflict with the in-component `label`. Use for semantic clarifications a `<field-ui>` wrapper would be overkill for.",
+      "type": "string",
+      "default": ""
+    },
     "label": {
       "description": "Label text above the slider",
       "type": "string",
@@ -61,6 +66,11 @@
       "type": "string",
       "default": ""
     },
+    "throttle": {
+      "description": "§184 (v0.5.5, FEEDBACK-08 §4): when > 0, debounce the `input` event by this many milliseconds. Value updates + visual feedback remain immediate; only event dispatch accumulates. Pending input flushes BEFORE `change` so consumers always see input→…→input→change ordering. throttle=\"0\" (default) preserves the pre-§184 every-pointer-move-fires-input behavior. Common values: 50-100ms for palette regen / shader compile / large list reflow.",
+      "type": "number",
+      "default": 0
+    },
     "value": {
       "description": "Current slider value",
       "type": "number",

package/components/slider/slider.css

@@ -134,4 +134,17 @@
   :scope[disabled] [slot="fill"] { background: var(--slider-fill-bg-disabled); }
   :scope[disabled] [slot="thumb"] { cursor: not-allowed; background: var(--slider-thumb-bg-disabled); }
   :scope[disabled] [slot="thumb"]:hover { box-shadow: none; }
+
+  /* ── Hint (§184, v0.5.5, FEEDBACK-08 §7) ──
+     Small caption rendered beneath the track. aria-describedby is
+     wired on the host in class.js so screen readers announce this
+     as a description (distinct from aria-label, which comes from
+     [label]). Uses the same muted typography as field-ui's hint. */
+  [slot="hint"] {
+    display: block;
+    margin-top: var(--slider-hint-mt, var(--a-space-1));
+    font-size: var(--slider-hint-size, var(--a-fine-size));
+    color: var(--slider-hint-fg, var(--a-fg-muted));
+    line-height: var(--slider-hint-lh, 1.4);
+  }
 }

package/components/slider/slider.yaml

@@ -51,6 +51,16 @@ props:
     description: Current slider value
     type: number
     default: 50
+  throttle:
+    description: |-
+      §184 (v0.5.5, FEEDBACK-08 §4): when > 0, debounce the `input` event by this many milliseconds. Value updates + visual feedback remain immediate; only event dispatch accumulates. Pending input flushes BEFORE `change` so consumers always see input→…→input→change ordering. throttle="0" (default) preserves the pre-§184 every-pointer-move-fires-input behavior. Common values: 50-100ms for palette regen / shader compile / large list reflow.
+    type: number
+    default: 0
+  hint:
+    description: |-
+      §184 (v0.5.5, FEEDBACK-08 §7): small caption rendered beneath the slider track. Sets `aria-describedby` on the host so screen readers announce it as a description (distinct from `aria-label`, which comes from `label`). Does not conflict with the in-component `label`. Use for semantic clarifications a `<field-ui>` wrapper would be overkill for.
+    type: string
+    default: ""
 events:
   change:
     description: "Fired when the value changes (on blur for inputs, on selection for pickers)."

package/components/switch/class.js

@@ -26,12 +26,26 @@ export class UISwitch extends UIFormElement {
     checked:  { type: Boolean, default: false, reflect: true },
     label:    { type: String,  default: '', reflect: true },
     size:     { type: String,  default: '', reflect: true },
+    // §184 (v0.5.5, FEEDBACK-08 §7): caption beneath the toggle.
+    // switch.yaml has declared `hint` since §170 but the template
+    // never rendered it — this arc closes the spec-vs-impl gap +
+    // wires aria-describedby on the host for screen readers.
+    hint:     { type: String,  default: '', reflect: true },
   };
 
-  static template = (el) => html`
-    <span slot="track"><span slot="thumb"></span></span>
-    ${el.label ? html`<span slot="label">${el.label}</span>` : null}
-  `;
+  // §184: per-instance hint id counter for aria-describedby wiring.
+  static #hintSeq = 0;
+
+  static template = (el) => {
+    const hintId = el.hint ? `switch-hint-${++UISwitch.#hintSeq}` : '';
+    if (hintId) el.setAttribute('aria-describedby', hintId);
+    else el.removeAttribute('aria-describedby');
+    return html`
+      <span slot="track"><span slot="thumb"></span></span>
+      ${el.label ? html`<span slot="label">${el.label}</span>` : null}
+      ${el.hint ? html`<span slot="hint" id=${hintId}>${el.hint}</span>` : null}
+    `;
+  };
 
   connected() {
     super.connected();

package/components/switch/switch.css

@@ -105,6 +105,16 @@ switch-ui[checked] [slot="thumb"] {
 
   [slot="label"] { font-size: var(--switch-font-size); }
 
+  /* ── Hint (§184, v0.5.5, FEEDBACK-08 §7) ──
+     Caption beneath the toggle row; wired to aria-describedby on host. */
+  [slot="hint"] {
+    display: block;
+    margin-top: var(--switch-hint-mt, var(--a-space-1));
+    font-size: var(--switch-hint-size, var(--a-fine-size));
+    color: var(--switch-hint-fg, var(--a-fg-muted));
+    line-height: var(--switch-hint-lh, 1.4);
+  }
+
   :scope:focus-visible { outline: none; }
   :scope:focus-visible [slot="track"] { box-shadow: var(--switch-focus-ring); }
 

package/components/switch/switch.d.ts

@@ -6,13 +6,13 @@
 
 import { UIFormElement } from '../../core/form.js';
 
-export interface SwitchChangeEventDetail {
+export interface SwitchChangeEventDetail<V extends string = string> {
   /** Submitted value (defaults to `"on"` when checked). */
-  value: string;
+  value: V;
   /** Current checked state. */
   checked: boolean;
 }
-export type SwitchChangeEvent = CustomEvent<SwitchChangeEventDetail>;
+export type SwitchChangeEvent<V extends string = string> = CustomEvent<SwitchChangeEventDetail<V>>;
 
 export class UISwitch extends UIFormElement {
   /** Checked state — reflected, toggles on click. */

package/components/tabs/tab.a2ui.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Tab.json",
+  "title": "Tab",
+  "description": "Child of <tabs-ui>. One tab panel — the tab BUTTON is rendered by the parent from this child's text/icon. Wraps panel content as light DOM.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "Tab"
+    },
+    "disabled": {
+      "description": "Whether the tab is selectable.",
+      "type": "boolean",
+      "default": false
+    },
+    "icon": {
+      "description": "Optional leading icon name (Phosphor) for the tab button.",
+      "type": "string"
+    },
+    "text": {
+      "description": "Tab button label (rendered by parent <tabs-ui>).",
+      "type": "string"
+    },
+    "value": {
+      "description": "Stable id for the tab. Parent uses this to coordinate active state.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "navigation",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UITab",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "tab-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/tabs/tab.yaml

@@ -0,0 +1,33 @@
+# 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
+# + was registered alongside the parent (e.g. UIList + UIListItem both
+# from 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.
+
+# Child component of <tabs-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UITab
+tag: tab-ui
+component: Tab
+category: navigation
+version: 1
+description: |-
+  Child of <tabs-ui>. One tab panel — the tab BUTTON is rendered by the parent from this child's text/icon. Wraps panel content as light DOM.
+
+props:
+  text:
+    description: Tab button label (rendered by parent <tabs-ui>).
+    type: string
+  value:
+    description: Stable id for the tab. Parent uses this to coordinate active state.
+    type: string
+  icon:
+    description: Optional leading icon name (Phosphor) for the tab button.
+    type: string
+  disabled:
+    description: Whether the tab is selectable.
+    type: boolean
+    default: false

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

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/TimelineItem.json",
+  "title": "TimelineItem",
+  "description": "Child of <timeline-ui>. One step in a sequenced reasoning/process timeline. Used heavily by <agent-reasoning-ui> + <agent-trace-ui>.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "description": {
+      "description": "Subtitle below the label.",
+      "type": "string"
+    },
+    "component": {
+      "const": "TimelineItem"
+    },
+    "duration": {
+      "description": "Elapsed time (e.g. \"1.2s\", \"340ms\").",
+      "type": "string"
+    },
+    "icon": {
+      "description": "Optional leading icon name (Phosphor).",
+      "type": "string"
+    },
+    "spinner": {
+      "description": "Show a spinner instead of the icon while status=pending.",
+      "type": "boolean",
+      "default": false
+    },
+    "status": {
+      "description": "Lifecycle state (idle | pending | done | failed).",
+      "type": "string",
+      "default": "idle"
+    },
+    "text": {
+      "description": "Primary step label.",
+      "type": "string"
+    },
+    "time": {
+      "description": "Absolute timestamp (HH:MM or ISO).",
+      "type": "string"
+    },
+    "variant": {
+      "description": "Visual variant (default | accent | success | warning | danger).",
+      "type": "string",
+      "default": "default"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "feedback",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UITimelineItem",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "timeline-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/timeline/timeline-item.yaml

@@ -0,0 +1,47 @@
+# 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
+# + was registered alongside the parent (e.g. UIList + UIListItem both
+# from 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.
+
+# Child component of <timeline-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UITimelineItem
+tag: timeline-item-ui
+component: TimelineItem
+category: feedback
+version: 1
+description: |-
+  Child of <timeline-ui>. One step in a sequenced reasoning/process timeline. Used heavily by <agent-reasoning-ui> + <agent-trace-ui>.
+
+props:
+  text:
+    description: Primary step label.
+    type: string
+  description:
+    description: Subtitle below the label.
+    type: string
+  time:
+    description: Absolute timestamp (HH:MM or ISO).
+    type: string
+  duration:
+    description: Elapsed time (e.g. "1.2s", "340ms").
+    type: string
+  icon:
+    description: Optional leading icon name (Phosphor).
+    type: string
+  variant:
+    description: Visual variant (default | accent | success | warning | danger).
+    type: string
+    default: 'default'
+  status:
+    description: Lifecycle state (idle | pending | done | failed).
+    type: string
+    default: 'idle'
+  spinner:
+    description: Show a spinner instead of the icon while status=pending.
+    type: boolean
+    default: false

package/components/toast/toast.d.ts

@@ -12,6 +12,28 @@
 
 import { UIElement } from '../../core/element.js';
 
+/** Options accepted by `UIToast.show(opts)` — the imperative one-shot path. */
+export interface UIToastShowOptions {
+  /** Toast message text. */
+  text?: string;
+  /** Semantic variant. Legacy alias `"error"` is auto-mapped to `"danger"`. */
+  variant?: 'default' | 'info' | 'success' | 'warning' | 'danger' | 'primary' | 'muted' | 'neutral' | 'error';
+  /** Auto-dismiss time in milliseconds. 0 disables auto-dismiss. Default `4000`. */
+  duration?: number;
+  /** Screen position. Default `'bottom-right'`. */
+  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+}
+
+/** Returned by `UIToast.show()` — imperative handle for dismiss / update. */
+export interface UIToastFeedHandle {
+  /** Stable id assigned by `<feed-ui>`. `null` if the toast couldn't be posted. */
+  id: string | null;
+  /** Dismiss the toast programmatically. */
+  dismiss(): void;
+  /** Mutate the toast's content in-place (e.g. promote from "loading" to "done"). */
+  update(patch: Partial<UIToastShowOptions>): void;
+}
+
 export class UIToast extends UIElement {
   /** Auto-dismiss time in milliseconds. 0 disables auto-dismiss. */
   duration: number;
@@ -21,4 +43,17 @@ export class UIToast extends UIElement {
   text: string;
   /** Semantic variant — `default | info | success | warning | danger`. `primary` and `muted` are style hints; canonical "neutral but interesting" tone is `info`. */
   variant: 'default' | 'info' | 'success' | 'warning' | 'danger' | 'primary' | 'muted' | 'neutral';
+
+  /**
+   * Post a one-shot toast through the shared `<feed-ui>` host. Imperative
+   * alternative to declarative `<toast-ui>`. Returns a `UIToastFeedHandle`
+   * for programmatic dismiss / update.
+   *
+   * Legacy alias `variant: 'error'` is auto-mapped to `variant: 'danger'`.
+   *
+   * @example
+   *   const t = UIToast.show({ text: 'Saved!', variant: 'success' });
+   *   setTimeout(() => t.dismiss(), 1000);
+   */
+  static show(opts?: UIToastShowOptions): UIToastFeedHandle;
 }

package/components/tree/class.js

@@ -63,6 +63,82 @@ export class UITree extends UIElement {
     }));
   }
 
+  // ──────────────────────────────────────────────────────────────────
+  // §184 (v0.5.5, FEEDBACK-08 §2): programmatic expand/collapse API.
+  // Pre-§184 consumers had to maintain local `_expanded[]` state +
+  // manually sync `tree-item.open` on every `tree-select` event. These
+  // five methods + the `auto-expand-selected` reflection let consumers
+  // declare the open state directly. All methods accept either a
+  // tree-item-ui element OR a value string (matched against [value]
+  // first, then [text] for ergonomics).
+  // ──────────────────────────────────────────────────────────────────
+
+  /**
+   * Resolve an `item` argument to a tree-item-ui element, or `null` if
+   * no match. Accepts: HTMLElement (used as-is when it matches `tree-item-ui`)
+   * OR a string (matched against [value] first, then [text]).
+   */
+  #resolveItem(arg) {
+    if (!arg) return null;
+    if (arg instanceof Element) {
+      return arg.matches?.('tree-item-ui') ? arg : null;
+    }
+    if (typeof arg === 'string') {
+      const escaped = arg.replace(/"/g, '\\"');
+      return (
+        this.querySelector(`tree-item-ui[value="${escaped}"]`) ||
+        this.querySelector(`tree-item-ui[text="${escaped}"]`) ||
+        null
+      );
+    }
+    return null;
+  }
+
+  /** Expand the given item (no-op when already open or it has no children). */
+  expand(itemOrValue) {
+    const item = this.#resolveItem(itemOrValue);
+    if (item && item.hasChildren && !item.open) item.open = true;
+  }
+
+  /** Collapse the given item (no-op when already collapsed). */
+  collapse(itemOrValue) {
+    const item = this.#resolveItem(itemOrValue);
+    if (item && item.open) item.open = false;
+  }
+
+  /** Expand every item with children. */
+  expandAll() {
+    for (const it of this.querySelectorAll('tree-item-ui')) {
+      if (it.hasChildren && !it.open) it.open = true;
+    }
+  }
+
+  /** Collapse every item. */
+  collapseAll() {
+    for (const it of this.querySelectorAll('tree-item-ui')) {
+      if (it.open) it.open = false;
+    }
+  }
+
+  /**
+   * Expand every ancestor of the given item so it becomes visible, then
+   * scroll it into view. Useful for revealing a programmatically-selected
+   * item nested inside collapsed parents.
+   */
+  expandTo(itemOrValue) {
+    const item = this.#resolveItem(itemOrValue);
+    if (!item) return;
+    let parent = item.parentElement?.closest('tree-item-ui');
+    while (parent) {
+      if (parent.hasChildren && !parent.open) parent.open = true;
+      parent = parent.parentElement?.closest('tree-item-ui');
+    }
+    item.querySelector(':scope > [slot="row"]')?.scrollIntoView?.({
+      block: 'nearest',
+      inline: 'nearest',
+    });
+  }
+
   #onClick = (e) => {
     const item = e.target.closest('tree-item-ui');
     if (!item || !this.contains(item)) return;
@@ -171,6 +247,10 @@ export class UITreeItem extends UIElement {
     value:    { type: String,  default: '', reflect: true },
     open:     { type: Boolean, default: false, reflect: true },
     selected: { type: Boolean, default: false, reflect: true },
+    // §184 (v0.5.5, FEEDBACK-08 §1): optional trailing badge for counts
+    // / labels (e.g. "Colors (7)" → text="Colors" badge="7"). Mirrors
+    // nav-item-ui badge API; styled muted-and-small via tree.css.
+    badge:    { type: String,  default: '', reflect: true },
   };
 
   static template = () => null;
@@ -222,6 +302,13 @@ export class UITreeItem extends UIElement {
     textEl.textContent = this.text;
     row.appendChild(textEl);
 
+    // §184: trailing badge (when [badge] is set). Stamped even when
+    // empty so render() can populate without re-stamping the DOM.
+    const badgeEl = document.createElement('span');
+    badgeEl.setAttribute('slot', 'badge');
+    if (this.badge) badgeEl.textContent = this.badge;
+    row.appendChild(badgeEl);
+
     // Actions slot placeholder
     const actions = document.createElement('span');
     actions.setAttribute('slot', 'actions');
@@ -247,5 +334,9 @@ export class UITreeItem extends UIElement {
     // Update text
     const textEl = row.querySelector('[slot="text"]');
     if (textEl && this.text) textEl.textContent = this.text;
+
+    // §184: keep badge slot synced with the [badge] attribute.
+    const badgeEl = row.querySelector('[slot="badge"]');
+    if (badgeEl) badgeEl.textContent = this.badge || '';
   }
 }