@adia-ai/web-components 0.4.7 → 0.4.8

package/components/button/button.a2ui.json

@@ -98,6 +98,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "action",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "press": {
         "description": "Fired on complete press (pointer up or Enter/Space)"

package/components/button/button.d.ts

@@ -5,12 +5,15 @@
  *
  * 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 ButtonPressEvent = CustomEvent<unknown>;
+
 export class UIButton extends UIElement {
   /** HTML button type (button, submit, reset) */
   type: string;
@@ -31,4 +34,11 @@ export class UIButton extends UIElement {
   /** Visual style — `solid` (default fill), `outline`, `ghost`. `default` / `primary` are aliases of `solid`. Style is independent of semantic intent — to express destructive / success / info / warning intent, set [color="…"] alongside.
 For **inline navigation** (Terms of Service, Privacy Policy, footer links, "Sign in" / "Sign up" cross-page affordances) use `<link-ui>` instead — it carries proper `<a href>` semantics, keyboard handling (Enter only, no Space), middle-click open-new-tab, and screen-reader announces "link" instead of "button". Mixing navigation and action affordances under the same primitive is a category error fixed at this junction. */
   variant: 'default' | 'solid' | 'outline' | 'ghost' | 'primary' | 'secondary' | 'soft' | 'current';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIButton, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'press', listener: (ev: ButtonPressEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/button/button.yaml

@@ -7,6 +7,11 @@ component: Button
 category: action
 version: 1
 description: Clickable button with text, icon, and variant support. Supports submit type for forms.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# in their render() do NOT auto-import them. Consumer (or demo shell) must
+# explicitly import each composed primitive.
+composes:
+  - icon-ui  # created via document.createElement('icon-ui') when [icon] is set
 props:
   aria-label:
     description: Accessible label for screen readers. Auto-set from `text` when text is non-empty; meaningful override for icon-only buttons.

package/components/calendar-picker/calendar-picker.a2ui.json

@@ -79,6 +79,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "input",
+    "composes": [],
     "events": {
       "change": {
         "description": "Fired when a date is selected"

package/components/canvas/canvas.a2ui.json

@@ -29,6 +29,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [],
     "events": {
       "canvas-interaction": {
         "description": "Fired on canvas-interaction."

package/components/canvas/canvas.d.ts

@@ -5,13 +5,29 @@
  *
  * 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 CanvasInteractionEvent = CustomEvent<unknown>;
+export type CanvasChangeEvent = CustomEvent<unknown>;
+export type CanvasClickEvent = CustomEvent<unknown>;
+export type CanvasInputEvent = CustomEvent<unknown>;
+
 export class UICanvas extends UIElement {
   /** Component property: theme. */
   theme: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UICanvas, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'canvas-interaction', listener: (ev: CanvasInteractionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'change', listener: (ev: CanvasChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'click', listener: (ev: CanvasClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: CanvasInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/canvas/canvas.yaml

@@ -5,6 +5,16 @@ component: Canvas
 category: agent
 version: 1
 description: A2UI rendering surface.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+# NOTE: <canvas-ui> mounts <a2ui-root> (web-modules/runtime) and optionally
+# <theme-ui> (web-modules/theme). These are CROSS-PACKAGE compositions that
+# the current composes: field can't express as same-package siblings. Cross-
+# package composition tracking is queued for v0.4.9; for now consumers
+# loading <canvas-ui> with a2ui-root rendering must import:
+#   @adia-ai/web-modules/runtime/a2ui-root
+#   @adia-ai/web-modules/theme/theme  (only if [theme-wrapper] is used)
+composes: []
 props:
   theme:
     description: 'Component property: theme.'

package/components/card/card.a2ui.json

@@ -75,6 +75,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "drag-end": {
         "description": "Fired when a drag completes."

package/components/card/card.d.ts

@@ -5,12 +5,15 @@
  *
  * 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 CardDragEndEvent = CustomEvent<unknown>;
+
 export class UICard extends UIElement {
   /** Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end. */
   draggable: boolean;
@@ -24,4 +27,11 @@ export class UICard extends UIElement {
   size: 'sm' | 'md' | 'lg';
   /** Visual style. `outline` is an alias for `outlined`; `flat` removes shadow; `soft`/`primary` apply tinted surfaces. */
   variant: 'default' | 'outlined' | 'outline' | 'filled' | 'ghost' | 'flat' | 'soft' | 'primary';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UICard, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'drag-end', listener: (ev: CardDragEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/chart/chart.a2ui.json

@@ -133,6 +133,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [],
     "events": {
       "chart-hover": {
         "description": "Fires when the pointer enters a datum (bar / dot / slice). Detail includes {label, value, pct, series, slot, pointerX, pointerY}. Only re-fires when the hovered datum changes — moving inside the same datum is quiet."

package/components/chart/chart.d.ts

@@ -5,12 +5,17 @@
  *
  * 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 ChartHoverEvent = CustomEvent<unknown>;
+export type ChartLeaveEvent = CustomEvent<unknown>;
+export type ChartSelectEvent = CustomEvent<unknown>;
+
 export class UIChart extends UIElement {
   /** Chart type. All 18 enum values have dedicated render paths in chart.js. */
   type: 'bar' | 'line' | 'pie' | 'donut' | 'radar' | 'sparkline' | 'segments' | 'area' | 'scatter' | 'radial-bar' | 'gauge' | 'stacked-bar' | 'grouped-bar' | 'multi-line' | 'funnel' | 'treemap' | 'sankey' | 'composed';
@@ -38,4 +43,13 @@ export class UIChart extends UIElement {
   x: string;
   /** Y-axis key(s), comma-separated for multi-series */
   y: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChart, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'chart-hover', listener: (ev: ChartHoverEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'chart-leave', listener: (ev: ChartLeaveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'chart-select', listener: (ev: ChartSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/chart-legend/chart-legend.a2ui.json

@@ -70,6 +70,10 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "badge-ui",
+      "swatch-ui"
+    ],
     "events": {
       "toggle": {
         "description": "Fires on row click (non-static). Detail: {key, active, mode}. `active` is the new state (true=visible). Consumers (or chart-ui via [for]) wire this to series visibility."

package/components/chart-legend/chart-legend.d.ts

@@ -5,12 +5,15 @@
  *
  * 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 ChartLegendToggleEvent = CustomEvent<unknown>;
+
 export class UIChartLegend extends UIElement {
   /** JSON array of {key, label, slot?, pct?} legend items. Takes precedence over [for] when both are provided. */
   items: string;
@@ -24,4 +27,11 @@ export class UIChartLegend extends UIElement {
   shape: 'dot' | 'square' | 'line' | 'dashed';
   /** When set, rows are non-interactive <span>s (no click, no toggle). */
   static: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChartLegend, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'toggle', listener: (ev: ChartLegendToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/chart-legend/chart-legend.yaml

@@ -9,6 +9,11 @@ description: >-
   badge-ui chips (swatch + label) that are keyboard-focusable and
   click-toggleable. Composes with chart-ui via [for] id-ref (auto-mirror) or
   via explicit [items] JSON.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - badge-ui
+  - swatch-ui
 props:
   for:
     description: id-ref of a chart-ui / heatmap-ui to mirror series from.

package/components/chat-thread/chat-thread.a2ui.json

@@ -29,6 +29,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [],
     "events": {
       "submit": {
         "description": "Fired when the user submits a chat message via Enter or send button. Detail: { text, model }."

package/components/chat-thread/chat-thread.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 ChatThreadSubmitEvent = CustomEvent<unknown>;
+
 export class UIChatThread extends UIElement {
   /** Component property: streaming. */
   streaming: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChatThread, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'submit', listener: (ev: ChatThreadSubmitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/check/check.a2ui.json

@@ -71,6 +71,7 @@
       }
     ],
     "category": "layout",
+    "composes": [],
     "events": {
       "change": {
         "description": "Fired when checked state changes"

package/components/code/code.a2ui.json

@@ -83,6 +83,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
+    "composes": [],
     "events": {
       "change": {
         "description": "Fired on blur if the buffer changed since focus (editable mode); detail.value is the final buffer"

package/components/col/col.a2ui.json

@@ -44,6 +44,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [
       {

package/components/col/col.d.ts

@@ -5,8 +5,9 @@
  *
  * 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';

package/components/color-picker/color-picker.a2ui.json

@@ -48,6 +48,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "input",
+    "composes": [
+      "slider-ui"
+    ],
     "events": {
       "change": {
         "description": "Fired on every color change"

package/components/color-picker/color-picker.yaml

@@ -7,6 +7,10 @@ component: ColorPicker
 category: input
 version: 1
 description: OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - slider-ui
 props:
   name:
     description: Form field name

package/components/command/command.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "dismiss": {
         "description": "Fired when Escape is pressed"

package/components/command/command.d.ts

@@ -5,15 +5,27 @@
  *
  * 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 CommandDismissEvent = CustomEvent<unknown>;
+export type CommandSelectEvent = CustomEvent<unknown>;
+
 export class UICommand extends UIElement {
   /** Whether the command palette is visible */
   open: boolean;
   /** Placeholder text for the search input */
   placeholder: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UICommand, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'dismiss', listener: (ev: CommandDismissEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'select', listener: (ev: CommandSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/demo-toggle/demo-toggle.a2ui.json

@@ -53,6 +53,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "change": {
         "description": "Fired when the toggle flips. detail contains { state }."

package/components/demo-toggle/demo-toggle.d.ts

@@ -5,12 +5,15 @@
  *
  * 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 DemoToggleChangeEvent = CustomEvent<unknown>;
+
 export class UIDemoToggle extends UIElement {
   /** Initial state when [state] is not set on connect ("on" | "off"). */
   initial: 'on' | 'off';
@@ -20,4 +23,11 @@ export class UIDemoToggle extends UIElement {
   labelOn: string;
   /** Current toggle state ("on" | "off"). Reflected as data-state on the host. */
   state: '' | 'on' | 'off';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIDemoToggle, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: DemoToggleChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

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

@@ -47,6 +47,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

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

@@ -5,8 +5,9 @@
  *
  * 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';

package/components/divider/divider.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
+    "composes": [],
     "events": {},
     "examples": [
       {

package/components/divider/divider.d.ts

@@ -5,8 +5,9 @@
  *
  * 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';

package/components/drawer/drawer.a2ui.json

@@ -60,6 +60,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "close": {
         "description": "Fired when the drawer is dismissed via close button or backdrop click"

package/components/drawer/drawer.d.ts

@@ -5,12 +5,15 @@
  *
  * 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 DrawerCloseEvent = CustomEvent<unknown>;
+
 export class UIDrawer extends UIElement {
   /** Controls visibility. When false, backdrop and panel are removed from DOM. */
   open: boolean;
@@ -22,4 +25,11 @@ export class UIDrawer extends UIElement {
   size: 'sm' | 'md' | 'lg';
   /** Title text displayed in the drawer header */
   text: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIDrawer, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'close', listener: (ev: DrawerCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/embed/embed.a2ui.json

@@ -44,6 +44,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [],
     "events": {},
     "examples": [
       {

package/components/embed/embed.d.ts

@@ -5,8 +5,9 @@
  *
  * 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';

package/components/empty-state/empty-state.a2ui.json

@@ -39,6 +39,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {},
     "examples": [
       {

package/components/empty-state/empty-state.d.ts

@@ -5,8 +5,9 @@
  *
  * 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';

package/components/empty-state/empty-state.yaml

@@ -7,6 +7,10 @@ component: EmptyState
 category: display
 version: 1
 description: Placeholder for empty views with icon, heading, description, and action slot.
+# 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:
   description:
     description: Secondary descriptive text below the heading

package/components/feed/feed.a2ui.json

@@ -43,7 +43,15 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
-    "events": {},
+    "composes": [
+      "button-ui",
+      "feed-item-ui"
+    ],
+    "events": {
+      "close": {
+        "description": "Fired on per-item dismissal (manual close, swipe, or auto-timeout). Bubbles."
+      }
+    },
     "examples": [],
     "keywords": [],
     "name": "UIFeedContainer",

package/components/feed/feed.d.ts

@@ -5,15 +5,25 @@
  *
  * 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 FeedCloseEvent = CustomEvent<unknown>;
+
 export class UIFeed extends UIElement {
   /** Cap on simultaneously visible items per lane */
   max: number;
   /** Lane the feed renders into */
   position: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right' | 'inline';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIFeed, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'close', listener: (ev: FeedCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }