@adia-ai/web-components 0.4.7 → 0.4.9

package/README.md

@@ -175,6 +175,45 @@ Authoring rules (enforced by `ui-audit-coherence`):
 5. **Light DOM only.** No `::part()`, `::slotted()`, shadow roots. Use
    attribute selectors on children: `:scope > [slot="icon"]`.
 
+### `static template` is a closure — import what it references
+
+The `static template` property is a regular JavaScript closure (typically a tagged template literal — `() => html` followed by the template body). Any signal, variable, or function it references must be **lexically in scope** at the file where the class is defined. This is JavaScript scoping, not anything AdiaUI-specific — but it surprises authors coming from frameworks where templates magically receive props.
+
+```js
+// ❌ WRONG — ReferenceError at runtime: minL is not defined
+//   (no import; the template function can't see minL just because
+//    it's exported elsewhere in the monorepo)
+class MyPanel extends UIElement {
+  static template = () => html`<div>L: ${minL.value}</div>`;
+}
+
+// ✅ RIGHT — import the signal locally
+import { minL } from './state.js';
+
+class MyPanel extends UIElement {
+  static template = () => html`<div>L: ${minL.value}</div>`;
+}
+```
+
+The error surfaces in the browser console as `ReferenceError: minL is not defined` at first render — not at module load, not at `tsc --noEmit`. **The trace points at the template function body**, not at the missing import, which is the disorienting part.
+
+If your primitive needs external reactive state that varies per-instance, **expose it as a property** rather than reaching for module-scoped signals:
+
+```js
+// ✅ Best — per-instance reactive prop
+class MyPanel extends UIElement {
+  static properties = {
+    minL: { type: Number, default: 0 },
+  };
+  static template = el => html`<div>L: ${el.minL}</div>`;
+}
+
+// Consumer:
+<my-panel .minL=${minL}></my-panel>  // signal binds reactively per ADR-template-binding
+```
+
+The `el` parameter is the element instance — every signal-backed property is reactively read.
+
 Full authoring contract: [`docs/specs/component-token-contract.md`](../../docs/specs/component-token-contract.md).
 The `adia-ui-author` skill encodes the 20 non-negotiable rules.
 

package/USAGE.md

@@ -166,11 +166,46 @@ function MinLSlider({ minL, onMinLChange }) {
 <slider-ui value={minL * 100} on:change={e => minL = e.detail.value / 100}></slider-ui>
 ```
 
+### Derived reactive bindings
+
+When the value you want to render is a **transformation of a signal** — e.g. you store `0..1` but the slider displays `0..100`, or the displayed text is `${count} items` — pass a **function** as the binding. The template engine detects functions and wraps them in an `effect()`, so the binding re-evaluates whenever any signal read inside the function changes.
+
+```js
+// ✅ Derived reactive — re-evaluates whenever minL changes
+html`<slider-ui .value=${() => minL.value * 100} min="0" max="100" />`
+
+// ✅ Direct signal — re-evaluates whenever minL changes
+html`<slider-ui .value=${minL} min="0" max="1" step="0.01" />`
+
+// ❌ Static snapshot — reads minL.value ONCE at render time; thumb never moves
+html`<slider-ui .value=${minL.value * 100} />`
+
+// ❌ Function as the value, not a binding — slider receives the function object, not its result
+html`<slider-ui .value=${(v) => v * 100} />`
+```
+
+The rule: **inside `.prop=${…}`, anything that reads `.value` directly is a snapshot. Wrap in `() => …` to get reactivity.**
+
+For more complex derived values, `computed()` gives you a named reactive holder you can pass directly or read in templates:
+
+```js
+import { signal, computed, html } from '@adia-ai/web-components/core';
+
+const minL = signal(0.4);
+const displayPct = computed(() => Math.round(minL.value * 100));
+
+html`<slider-ui .value=${displayPct} />`        // ✅ pass the computed signal direct
+html`<text-ui>${displayPct}</text-ui>`           // ✅ same in text bindings
+html`<text-ui>${() => `${displayPct.value}%`}</text-ui>`  // ✅ function form with template literal
+```
+
+`computed()` memoizes (re-runs only when its dependencies change) and gives you a stable handle you can pass to multiple bindings without re-instantiating the effect at every render.
+
 ### The eager-evaluation trap
 
 Reported real-world bug: a consumer wrote `.value=${signal.value * 100}` and reported "the slider doesn't move on undo." The slider IS reactive; the binding pattern wasn't. `signal.value * 100` evaluates eagerly to a number; the template system never sees the signal, so it can't subscribe.
 
-**Fix:** pass `${signal}` (signal direct) or `${() => signal.value * 100}` (function as value). Both get effect-wrapped.
+**Fix:** pass `${signal}` (signal direct) or `${() => signal.value * 100}` (function as value). Both get effect-wrapped. See the "Derived reactive bindings" section above for the full pattern.
 
 ---
 
@@ -218,7 +253,7 @@ Some primitives emit named events beyond `change`/`input`:
 - `<select-ui>` — emits `action` for option-callbacks with `detail.action`
 - `<search-ui>` — emits `search` after debounce with `detail.value`
 - `<chat-composer>` — emits `composer-submit` on Enter with `detail.value`
-- `<color-picker-ui>` — emits multiple typed events (`input`, `change`, `format-change`) with structured detail
+- `<color-picker-ui>` — emits `input` + `change` with rich detail (`{ value, l, c, h, hex, oklch }`)
 
 Each primitive's yaml lists its complete event surface. Live demos at `https://ui-kit.exe.xyz/site/components/<name>`.
 
@@ -226,6 +261,90 @@ Each primitive's yaml lists its complete event surface. Live demos at `https://u
 
 All standard events bubble. Internal-routing collisions (e.g. a trait listening for an event then re-emitting one with the same name) are avoided by name discipline — see the `event-name-collision` memory entry for the lesson.
 
+### Authoring events in yaml (for contributors)
+
+> *This subsection is for contributors authoring new primitives or extending an existing primitive's event surface. If you're a consumer integrating AdiaUI, skip ahead.*
+
+Each component's `<name>.yaml` declares its event surface in a top-level `events:` block. The build pipeline (`npm run build:components`) carries that block into `<name>.a2ui.json` under `x-adiaui.events`, and v0.4.8 §80 codegen reads it from there to emit typed `addEventListener` overloads + `CustomEvent<X>` aliases in `<name>.d.ts`. **The yaml is the single source of truth**; the sidecar + `.d.ts` regenerate from it.
+
+#### When to add an `events:` entry
+
+Whenever your primitive's `class.js` calls `this.dispatchEvent(new CustomEvent('NAME', ...))` or `new Event('NAME', ...)`, the yaml needs a matching entry. The `check-form-bearing-dts.mjs` audit (v0.5.0-staged) catches drift between dispatch literals and `.d.ts` typings; populating yaml correctly prevents that drift.
+
+#### The shape
+
+```yaml
+events:
+  open:
+    description: Fired when the modal becomes visible.
+    detail:
+      trigger:
+        type: string
+        description: One of 'click' | 'keyboard' | 'programmatic'.
+  close:
+    description: Fired when the modal is dismissed.
+    # No detail block → CustomEvent<unknown> at the .d.ts surface.
+  toggle:
+    description: Fired when state flips.
+    detail:
+      open:
+        type: boolean
+        description: New open state after the toggle.
+    bubbles: false   # default is true; set false only for non-bubbling events
+```
+
+#### What ends up where
+
+For a yaml entry like the `toggle` event above on `<my-thing-ui>`:
+
+| Surface | Shape |
+|---|---|
+| `<my-thing-ui>.a2ui.json` | `x-adiaui.events.toggle = { description, detail: { open: { type, description } }, bubbles? }` |
+| `<my-thing-ui>.d.ts` (codegen) | `interface MyThingToggleEventDetail { open: boolean; }` + `type MyThingToggleEvent = CustomEvent<MyThingToggleEventDetail>` + `addEventListener` overload for `'toggle'` |
+| Runtime | `this.dispatchEvent(new CustomEvent('toggle', { detail: { open: this.open }, bubbles: true }))` |
+
+#### Detail-key types
+
+The codegen recognizes these `type:` values inside a detail key:
+
+| yaml `type:` | TS emitted |
+|---|---|
+| `string` | `string` |
+| `number` / `integer` | `number` |
+| `boolean` | `boolean` |
+| `object` | `Record<string, unknown>` |
+| `array` | `unknown[]` |
+| missing | `unknown` |
+
+If you need a string-literal union, declare via `enum: [a, b, c]` and the codegen emits `'a' | 'b' | 'c'`.
+
+#### Worked example: `<modal-ui>` close
+
+Yaml at `packages/web-components/components/modal/modal.yaml`:
+
+```yaml
+events:
+  close:
+    description: Fires when the modal is dismissed (backdrop click, Escape, programmatic hide()).
+```
+
+Sidecar after `npm run build:components`:
+
+```json
+{ "x-adiaui": { "events": { "close": { "description": "Fires when the modal is dismissed..." } } } }
+```
+
+Emitted `.d.ts` after `npm run codegen:dts`:
+
+```ts
+export type ModalCloseEvent = CustomEvent<unknown>;
+export class UIModal extends UIElement {
+  addEventListener(type: 'close', listener: (ev: ModalCloseEvent) => unknown, options?: ...): void;
+}
+```
+
+Reference: [`docs/conventions/component-events.md`](../../docs/conventions/component-events.md) for the 1-page convention summary; [`scripts/build/dts-codegen.mjs`](../../scripts/build/dts-codegen.mjs) for the codegen logic that reads `x-adiaui.events`; [`scripts/release/check-form-bearing-dts.mjs`](../../scripts/release/check-form-bearing-dts.mjs) for the drift audit.
+
 ---
 
 ## Form participation
@@ -592,6 +711,140 @@ Properties are installed by `installProps()` in `super()`, but the host's render
 
 ---
 
+## Worked examples
+
+Migrations from common custom-helper shapes to AdiaUI primitives. Each example pairs a real consumer's pre-AdiaUI helper with the equivalent AdiaUI declaration.
+
+### Replace a hand-rolled color-token swatch with `<swatch-ui>` (v0.4.9+)
+
+Pre-v0.4.9, design-token tools commonly hand-rolled a `renderSwatch()` helper composing: background color, key label, gamut badge (sRGB / P3 markers), APCA contrast badge, copy-to-clipboard button, light/dark auto-contrast label, keyboard select. v0.4.9 extends `<swatch-ui>` with all six surfaces — the helper collapses to one declarative tag.
+
+```diff
+- // Pre — 70 LOC helper
+- function renderSwatch({ color, label, detail, gamutBadge, copyValue, selected, onSelect }) {
+-   const el = document.createElement('div')
+-   el.className = 'token-swatch'
+-   el.style.backgroundColor = color
+-   el.tabIndex = 0
+-   el.setAttribute('role', 'button')
+-   el.setAttribute('aria-pressed', String(selected))
+-   if (selected) el.classList.add('selected')
+-
+-   const labelEl = document.createElement('span')
+-   labelEl.className = 'swatch-label'
+-   labelEl.textContent = label
+-   labelEl.style.color = isLight(color) ? 'var(--fg-dark)' : 'var(--fg-light)'
+-   el.appendChild(labelEl)
+-
+-   const detailEl = document.createElement('span')
+-   detailEl.className = 'swatch-detail'
+-   detailEl.textContent = detail
+-   el.appendChild(detailEl)
+-
+-   if (gamutBadge) {
+-     const badge = document.createElement('span')
+-     badge.className = 'swatch-badge'
+-     badge.textContent = gamutBadge === 'out-of-gamut' ? '△' : '✦'
+-     badge.setAttribute('aria-label', gamutBadge)
+-     el.appendChild(badge)
+-   }
+-
+-   const copyBtn = document.createElement('button')
+-   copyBtn.className = 'swatch-copy'
+-   copyBtn.textContent = '⧉'
+-   copyBtn.setAttribute('aria-label', `Copy ${copyValue}`)
+-   copyBtn.addEventListener('click', async (e) => {
+-     e.stopPropagation()
+-     try { await navigator.clipboard.writeText(copyValue); copyBtn.textContent = '✓' }
+-     catch { copyBtn.textContent = '⚠' }
+-     setTimeout(() => { copyBtn.textContent = '⧉' }, 1200)
+-   })
+-   el.appendChild(copyBtn)
+-
+-   el.addEventListener('click', (e) => {
+-     if (e.target === copyBtn) return
+-     onSelect({ color, label })
+-   })
+-   el.addEventListener('keydown', (e) => {
+-     if (e.key !== 'Enter' && e.key !== ' ') return
+-     if (e.target === copyBtn) return
+-     e.preventDefault()
+-     onSelect({ color, label })
+-   })
+-
+-   return el
+- }
+
++ // Post — one declarative tag
++ html`<swatch-ui
++   shape="block" size="lg"
++   color=${color}
++   label=${label}
++   detail=${detail}
++   badge=${gamutBadge}
++   copyable
++   copy-value=${copyValue}
++   selectable
++   ?selected=${selected}
++   auto-contrast
++   @select=${(e) => onSelect({ color: e.detail.color, label: e.detail.label })}
++ ></swatch-ui>`
+```
+
+The primitive owns: badge symbol + ARIA mapping, copy-clipboard state machine (⧉ → ✓ / ⚠ → ⧉ after 1.2s), `role="button"` + `tabindex="0"` only when `[selectable]`, focus ring on `:focus-visible` + always-on when `[selected]`, click-on-copy-doesn't-toggle-selection guard, label auto-contrast via OKLCH luminance (when `[auto-contrast]` is set).
+
+The `select` event detail is `{ value, color, label }` — `value` is `[color]` (or `[label]` as fallback) so consumers binding to a value-shaped select handler get the canonical accessor uniformly across form-bearing primitives.
+
+For multiple simultaneous badges (e.g. both `out-of-gamut` and `apca-fail`), pass a comma-separated list: `badge="out-of-gamut, apca-fail"` — v0.4.9 renders both stacked in the upper-right.
+
+### Guard global keyboard shortcuts with `isFocusInInput()` (v0.4.8+)
+
+```diff
+- // Pre — manual cast boilerplate at every shortcut site
+- document.addEventListener('keydown', (e) => {
+-   const active = document.activeElement as HTMLElement | null
+-   if (active && (
+-     active.tagName === 'INPUT' ||
+-     active.tagName === 'TEXTAREA' ||
+-     active.isContentEditable
+-   )) return
+-   if (e.key === '/') openCommandPalette()
+- })
+
++ // Post — one import + one call
++ import { isFocusInInput } from '@adia-ai/web-modules/editor'
++
++ document.addEventListener('keydown', (e) => {
++   if (isFocusInInput()) return
++   if (e.key === '/') openCommandPalette()
++ })
+```
+
+`isFocusInInput()` also recognizes AdiaUI text-input primitives (`<input-ui>`, `<textarea-ui>`, `<otp-input-ui>`, `<search-ui>`) by host tag-name — important because focus may land on the custom-element host before the inner native input mounts.
+
+### Use derived reactive bindings for unit-conversion (v0.4.6+)
+
+```diff
+- // Pre — eager evaluation; slider doesn't move on undo
+- <slider-ui .value=${minL.value * 100} min="0" max="100" step="1"></slider-ui>
+
++ // Post — function-as-value gets effect-wrapped
++ <slider-ui .value=${() => minL.value * 100} min="0" max="100" step="1"></slider-ui>
+```
+
+The function re-runs on every dependency mutation. Same pattern works for derived computations (e.g. `() => clamp(minL.value * 100, 0, 100)`) and signal-array transforms.
+
+### Persist `<editor-sidebar>` width across reloads (v0.4.9+)
+
+```diff
+- <editor-sidebar collapsible name="dts-layout">
++ <editor-sidebar collapsible persist="dts-layout">
+```
+
+`[persist]` is the preferred name in v0.4.9+. `[name]` keeps working (back-compat alias; deprecated, not scheduled for v0.5.x removal). Storage namespace + `sidebar-toggle` event detail are unchanged.
+
+---
+
 ## More
 
 - [`README.md`](./README.md) — package overview + authoring guide

package/components/accordion/accordion.a2ui.json

@@ -29,6 +29,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "change": {
         "description": "Fired when the set of open panels changes"

package/components/accordion/accordion.d.ts

@@ -5,13 +5,23 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
  */
 
 import { UIElement } from '../../core/element.js';
 
+export type AccordionChangeEvent = CustomEvent<unknown>;
+
 export class UIAccordion extends UIElement {
   /** Allow multiple panels to be open simultaneously */
   multiple: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAccordion, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: AccordionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/accordion/accordion.yaml

@@ -7,6 +7,10 @@ component: Accordion
 category: container
 version: 1
 description: Accordion container managing single/multiple open states.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
 props:
   multiple:
     description: Allow multiple panels to be open simultaneously

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

@@ -24,9 +24,26 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "navigation",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "action": {
-        "description": "Fired on action."
+        "description": "Fired on action.",
+        "detail": {
+          "item": {
+            "description": "The triggering list-item element.",
+            "type": "object"
+          },
+          "text": {
+            "description": "Item text content or [text] attribute.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Item value attribute (preferred over text for stable IDs).",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

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

@@ -5,11 +5,30 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
  */
 
 import { UIElement } from '../../core/element.js';
 
+export interface ActionListActionEventDetail {
+  /** The triggering list-item element. */
+  item: Record<string, unknown>;
+  /** Item text content or [text] attribute. */
+  text: string;
+  /** Item value attribute (preferred over text for stable IDs). */
+  value: string;
+}
+
+export type ActionListActionEvent = CustomEvent<ActionListActionEventDetail>;
+
 export class UIActionList extends UIElement {
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIActionList, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'action', listener: (ev: ActionListActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

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

@@ -8,10 +8,24 @@ category: navigation
 version: 1
 description: Inline list of command actions with keyboard navigation. Fires action event when an
   item is clicked or activated via keyboard.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
 props: {}
 events:
   action:
     description: "Fired on action."
+    detail:
+      value:
+        type: string
+        description: Item value attribute (preferred over text for stable IDs).
+      text:
+        type: string
+        description: Item text content or [text] attribute.
+      item:
+        type: object
+        description: The triggering list-item element.
 slots:
   default (action-item-ui children):
     description: "Child content region for the `default (action-item-ui children)` slot."

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

@@ -49,9 +49,19 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "icon-ui",
+      "badge-ui"
+    ],
     "events": {
       "artifact-toggle": {
-        "description": "Fired on artifact-toggle."
+        "description": "Fired on artifact-toggle.",
+        "detail": {
+          "collapsed": {
+            "description": "New collapsed state after the toggle.",
+            "type": "boolean"
+          }
+        }
       }
     },
     "examples": [

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

@@ -5,12 +5,20 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
  */
 
 import { UIElement } from '../../core/element.js';
 
+export interface AgentArtifactArtifactToggleEventDetail {
+  /** New collapsed state after the toggle. */
+  collapsed: boolean;
+}
+
+export type AgentArtifactArtifactToggleEvent = CustomEvent<AgentArtifactArtifactToggleEventDetail>;
+
 export class UIAgentArtifact extends UIElement {
   /** Header title. */
   title: string;
@@ -22,4 +30,11 @@ export class UIAgentArtifact extends UIElement {
   kind: string;
   /** neutral | accent | warning | danger */
   tone: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAgentArtifact, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'artifact-toggle', listener: (ev: AgentArtifactArtifactToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/agent-artifact/agent-artifact.yaml

@@ -7,6 +7,11 @@ component: AgentArtifact
 category: agent
 version: 1
 description: Inline container for structured agent artifacts (A2UI, JSON, tickets).
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
+  - badge-ui
 props:
   kind:
     description: Badge label; value is normalized to uppercase before rendering.
@@ -31,6 +36,10 @@ props:
 events:
   artifact-toggle:
     description: "Fired on artifact-toggle."
+    detail:
+      collapsed:
+        type: boolean
+        description: New collapsed state after the toggle.
 slots:
   default:
     description: "Default slot — primary child content."

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

@@ -39,9 +39,18 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "button-ui"
+    ],
     "events": {
       "feedback-rate": {
-        "description": "Fired on feedback-rate."
+        "description": "Fired on feedback-rate.",
+        "detail": {
+          "rating": {
+            "description": "Rating value selected by the user.",
+            "type": "number"
+          }
+        }
       },
       "feedback-save": {
         "description": "Fired on feedback-save."

package/components/agent-feedback-bar/agent-feedback-bar.d.ts

@@ -5,12 +5,21 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
  */
 
 import { UIElement } from '../../core/element.js';
 
+export interface AgentFeedbackBarFeedbackRateEventDetail {
+  /** Rating value selected by the user. */
+  rating: number;
+}
+
+export type AgentFeedbackBarFeedbackRateEvent = CustomEvent<AgentFeedbackBarFeedbackRateEventDetail>;
+export type AgentFeedbackBarFeedbackSaveEvent = CustomEvent<unknown>;
+
 export class UIAgentFeedbackBar extends UIElement {
   /** Disable all actions. */
   disabled: boolean;
@@ -18,4 +27,12 @@ export class UIAgentFeedbackBar extends UIElement {
   saveIcon: string;
   /** Save button text; empty hides it. */
   saveLabel: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAgentFeedbackBar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'feedback-rate', listener: (ev: AgentFeedbackBarFeedbackRateEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'feedback-save', listener: (ev: AgentFeedbackBarFeedbackSaveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

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

@@ -7,6 +7,10 @@ component: AgentFeedbackBar
 category: agent
 version: 1
 description: Thumbs + save row under an agent response.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - button-ui
 props:
   disabled:
     description: Disable all actions.
@@ -26,6 +30,10 @@ props:
 events:
   feedback-rate:
     description: "Fired on feedback-rate."
+    detail:
+      rating:
+        type: number
+        description: Rating value selected by the user.
   feedback-save:
     description: "Fired on feedback-save."
 slots:

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

@@ -44,9 +44,22 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "button-ui"
+    ],
     "events": {
       "questions-answer": {
-        "description": "Fired on questions-answer."
+        "description": "Fired on questions-answer.",
+        "detail": {
+          "option": {
+            "description": "The full selected option object.",
+            "type": "object"
+          },
+          "selected": {
+            "description": "Array of selected option IDs.",
+            "type": "array"
+          }
+        }
       }
     },
     "examples": [