@adia-ai/web-components 0.4.7 → 0.4.9

package/components/table/table.yaml

@@ -8,6 +8,14 @@ category: agent
 version: 1
 description: Data table with sorting, selection, pagination, search, column resize, keyboard nav,
   cell types, and CSV export. CSS grid + ARIA grid roles.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - check-ui
+  - icon-ui
+  - progress-ui
+  - pagination-ui
+  - badge-ui
 props:
   columns:
     description: Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children.
@@ -66,15 +74,67 @@ props:
     default: false
 events:
   cell-click:
-    description: Fired when a data cell is clicked.
+    description: Fired when a data cell is clicked. detail carries the cell location + value.
+    detail:
+      key:
+        type: string
+        description: Column key.
+      row:
+        type: object
+        description: Row data object.
+      value:
+        description: Cell value (type depends on column).
+      dataIndex:
+        type: number
+        description: Row index in the underlying data array.
+  filter-change:
+    description: Fired when an interactive filter row applies / clears. detail.filters is the current filter map.
+    detail:
+      filters:
+        type: object
+        description: "Map of `{ [columnKey]: filterValue }` reflecting active filters."
   page:
     description: Fired when the user navigates to a different page.
+    detail:
+      page:
+        type: number
+        description: New active page index (1-based).
   resize:
     description: Fired when a column is resized via drag.
+    detail:
+      key:
+        type: string
+        description: Column key being resized.
+      width:
+        type: number
+        description: New column width in pixels.
+  row-expand:
+    description: Fired when an expandable row's chevron is activated. detail.index is the row position; detail.row is the row data.
+    detail:
+      index:
+        type: number
+        description: Row index in the underlying data array.
+      row:
+        type: object
+        description: Row data object.
   select:
-    description: Fired when row selection changes.
+    description: Fired when row selection changes. detail.selected is an array of row indices or IDs.
+    detail:
+      selected:
+        type: array
+        description: Array of selected row indices or IDs (driven by [select-mode]).
   sort:
     description: Fired when sort state changes via header click.
+    detail:
+      key:
+        type: string
+        description: Column key being sorted.
+      dir:
+        type: string
+        description: Sort direction — "asc" / "desc" / null (cleared).
+      sortState:
+        type: array
+        description: Full sort state array (multi-column support).
 slots: {}
 states:
   - name: idle

package/components/table-toolbar/table-toolbar.a2ui.json

@@ -73,6 +73,18 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "text-ui",
+      "badge-ui",
+      "search-ui",
+      "button-ui",
+      "field-ui",
+      "select-ui",
+      "input-ui",
+      "menu-item-ui",
+      "icon-ui",
+      "check-ui"
+    ],
     "events": {
       "columns-change": {
         "description": "Column visibility changed. Detail: { hiddenColumns }."

package/components/table-toolbar/table-toolbar.d.ts

@@ -5,12 +5,18 @@
  *
  * 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 TableToolbarColumnsChangeEvent = CustomEvent<unknown>;
+export type TableToolbarFilterChangeEvent = CustomEvent<unknown>;
+export type TableToolbarSearchEvent = CustomEvent<unknown>;
+export type TableToolbarSortChangeEvent = CustomEvent<unknown>;
+
 export class UITableToolbar extends UIElement {
   /** Optional count badge value shown next to the title. When unset, falls back to the row count of the bound table. */
   count: string;
@@ -30,4 +36,14 @@ export class UITableToolbar extends UIElement {
   text: string;
   /** Toolbar visual variant. `default` renders bare on parent surface; `card` adds the same chrome as a card-ui header. */
   variant: 'default' | 'card';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UITableToolbar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'columns-change', listener: (ev: TableToolbarColumnsChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'filter-change', listener: (ev: TableToolbarFilterChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'search', listener: (ev: TableToolbarSearchEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'sort-change', listener: (ev: TableToolbarSortChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/table-toolbar/table-toolbar.yaml

@@ -15,6 +15,19 @@ description: >-
   column descriptor's `filter` field overrides the auto-detect: `'select'`
   forces multi-select even on high-cardinality columns; `'text'` forces a
   contains input even on small enums.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - text-ui
+  - badge-ui
+  - search-ui
+  - button-ui
+  - field-ui
+  - select-ui
+  - input-ui
+  - menu-item-ui
+  - icon-ui
+  - check-ui
 props:
   for:
     description: id-ref of the table-ui to control. Falls back to the first sibling table-ui within the same parent when omitted.

package/components/tabs/tabs.a2ui.json

@@ -46,9 +46,18 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "change": {
-        "description": "Fired when the value changes (on blur for inputs, on selection for pickers)."
+        "description": "Fired when the value changes (on blur for inputs, on selection for pickers).",
+        "detail": {
+          "value": {
+            "description": "New active tab value.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

package/components/tabs/tabs.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 TabsChangeEventDetail {
+  /** New active tab value. */
+  value: string;
+}
+
+export type TabsChangeEvent = CustomEvent<TabsChangeEventDetail>;
+
 export class UITabs extends UIElement {
   /** Tab strip orientation. Set to 'vertical' for vertical layout; empty/omitted for horizontal. */
   orientation: string;
@@ -18,4 +26,11 @@ export class UITabs extends UIElement {
   value: string;
   /** Visual variant — default underline strip, `pills` for filled pill tabs, `underline` (explicit). */
   variant: 'default' | 'pills' | 'underline' | 'segmented' | 'bordered';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UITabs, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: TabsChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/tabs/tabs.yaml

@@ -7,6 +7,10 @@ component: Tabs
 category: container
 version: 1
 description: Tabbed panel switcher. Renders button strip from child tab-ui elements.
+# 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:
   orientation:
     description: Tab strip orientation. Set to 'vertical' for vertical layout; empty/omitted for horizontal.
@@ -25,6 +29,10 @@ props:
 events:
   change:
     description: "Fired when the value changes (on blur for inputs, on selection for pickers)."
+    detail:
+      value:
+        type: string
+        description: New active tab value.
 slots:
   default:
     description: Child tab-ui elements that form the tab strip

package/components/tag/tag.a2ui.json

@@ -64,9 +64,20 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
+    "composes": [],
     "events": {
       "remove": {
-        "description": "Fired when the dismiss button is activated."
+        "description": "Fired when the dismiss button is activated.",
+        "detail": {
+          "text": {
+            "description": "Tag text content.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Tag value (same as text).",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

package/components/tag/tag.d.ts

@@ -5,12 +5,22 @@
  *
  * 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 TagRemoveEventDetail {
+  /** Tag text content. */
+  text: string;
+  /** Tag value (same as text). */
+  value: string;
+}
+
+export type TagRemoveEvent = CustomEvent<TagRemoveEventDetail>;
+
 export class UITag extends UIElement {
   /** Disables interaction and dims the tag. */
   disabled: boolean;
@@ -24,4 +34,11 @@ export class UITag extends UIElement {
   textContent: string;
   /** Semantic variant — `default | info | success | warning | danger`. */
   variant: 'default' | 'info' | 'success' | 'warning' | 'danger';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UITag, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'remove', listener: (ev: TagRemoveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/tag/tag.yaml

@@ -45,6 +45,13 @@ props:
 events:
   remove:
     description: Fired when the dismiss button is activated.
+    detail:
+      text:
+        type: string
+        description: Tag text content.
+      value:
+        type: string
+        description: Tag value (same as text).
 slots: {}
 states:
   - name: idle

package/components/text/text.a2ui.json

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

package/components/text/text.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/textarea/textarea.a2ui.json

@@ -60,6 +60,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "change": {
         "description": "Fired when the textarea loses focus after a value change."

package/components/timeline/timeline.a2ui.json

@@ -42,7 +42,20 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
-    "events": {},
+    "composes": [
+      "icon-ui"
+    ],
+    "events": {
+      "timeline-toggle": {
+        "description": "Fired when a collapsible timeline item is expanded or collapsed. detail.expanded carries the new open state.",
+        "detail": {
+          "expanded": {
+            "description": "New open state of the toggled item after the press.",
+            "type": "boolean"
+          }
+        }
+      }
+    },
     "examples": [
       {
         "description": "Order tracking card with a timeline showing order status milestones from placed to delivered.",

package/components/timeline/timeline.d.ts

@@ -5,15 +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 TimelineToggleEventDetail {
+  /** New open state of the toggled item after the press. */
+  expanded: boolean;
+}
+
+export type TimelineToggleEvent = CustomEvent<TimelineToggleEventDetail>;
+
 export class UITimeline extends UIElement {
   /** Layout direction */
   orientation: 'vertical' | 'horizontal';
   /** Rail size preset — use `sm` for agent-reasoning/pipeline views; `md` is the default. */
   size: 'sm' | 'md';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UITimeline, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'timeline-toggle', listener: (ev: TimelineToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/timeline/timeline.yaml

@@ -7,6 +7,10 @@ component: Timeline
 category: display
 version: 1
 description: "Timeline and step wizard. Two modes: timeline (per-item state) and steps (parent-driven)."
+# 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:
   orientation:
     description: Layout direction
@@ -21,7 +25,13 @@ props:
     default: md
     reflect: true
     enum: [sm, md]
-events: {}
+events:
+  timeline-toggle:
+    description: Fired when a collapsible timeline item is expanded or collapsed. detail.expanded carries the new open state.
+    detail:
+      expanded:
+        type: boolean
+        description: New open state of the toggled item after the press.
 slots:
   default:
     description: Accepts <timeline-item-ui> children.

package/components/toast/toast.a2ui.json

@@ -62,6 +62,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "close": {
         "description": "Fired when the toast is dismissed via click or auto-timeout"

package/components/toast/toast.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 ToastCloseEvent = CustomEvent<unknown>;
+
 export class UIToast extends UIElement {
   /** Auto-dismiss time in milliseconds. 0 disables auto-dismiss. */
   duration: number;
@@ -20,4 +23,11 @@ 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';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIToast, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'close', listener: (ev: ToastCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

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

@@ -34,9 +34,16 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "navigation",
+    "composes": [],
     "events": {
       "change": {
-        "description": "Fired when selection changes. detail: { value }"
+        "description": "Fired when selection changes. detail: { value }",
+        "detail": {
+          "value": {
+            "description": "New toggle-group value.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

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

@@ -5,15 +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 ToggleGroupChangeEventDetail {
+  /** New toggle-group value. */
+  value: string;
+}
+
+export type ToggleGroupChangeEvent = CustomEvent<ToggleGroupChangeEventDetail>;
+
 export class UIToggleGroup extends UIElement {
   /** When true, restrict to one active option (single-select). */
   single: boolean;
   /** Comma-separated selected values */
   value: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIToggleGroup, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: ToggleGroupChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/toggle-group/toggle-group.yaml

@@ -19,6 +19,10 @@ props:
 events:
   change:
     description: "Fired when selection changes. detail: { value }"
+    detail:
+      value:
+        type: string
+        description: New toggle-group value.
 slots:
   default:
     description: "Default slot — primary child content."

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

@@ -124,9 +124,22 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "control",
+    "composes": [
+      "button-ui"
+    ],
     "events": {
       "scheme-change": {
-        "description": "Fired when the active scheme changes. detail contains { scheme: \"light\" | \"dark\", source: \"press\" | \"media\" | \"programmatic\" }."
+        "description": "Fired when the active scheme changes. detail contains { scheme: \"light\" | \"dark\", source: \"press\" | \"media\" | \"programmatic\" }.",
+        "detail": {
+          "scheme": {
+            "description": "Active color scheme (\"light\" or \"dark\").",
+            "type": "string"
+          },
+          "source": {
+            "description": "Change source — \"press\" / \"media\" / \"programmatic\".",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

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

@@ -5,12 +5,22 @@
  *
  * 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 ToggleSchemeSchemeChangeEventDetail {
+  /** Active color scheme ("light" or "dark"). */
+  scheme: string;
+  /** Change source — "press" / "media" / "programmatic". */
+  source: string;
+}
+
+export type ToggleSchemeSchemeChangeEvent = CustomEvent<ToggleSchemeSchemeChangeEventDetail>;
+
 export class UIToggleScheme extends UIElement {
   /** Resolved scheme ("light" | "dark"). Read-only; mutate via .setScheme() or .toggle(). */
   activeScheme: '' | 'light' | 'dark';
@@ -38,4 +48,11 @@ export class UIToggleScheme extends UIElement {
   target: string;
   /** Visual style forwarded to the internal <button-ui>. Defaults to "ghost" (matches app practice). */
   variant: 'default' | 'solid' | 'outline' | 'ghost' | 'primary' | 'secondary' | 'soft';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIToggleScheme, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'scheme-change', listener: (ev: ToggleSchemeSchemeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/toggle-scheme/toggle-scheme.yaml

@@ -13,6 +13,10 @@ description: >-
   <theme-panel>), and the moon/sun icon swap. Replaces the hand-wired
   `<button-ui id="theme-toggle">` + `applyScheme()` pattern previously
   duplicated across apps/genui, apps/construct-canvas, playgrounds/chat.
+# 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:
   scheme:
     description: Initial scheme — "auto" follows prefers-color-scheme; "light" / "dark" force.
@@ -120,6 +124,13 @@ events:
     description: >-
       Fired when the active scheme changes. detail contains
       { scheme: "light" | "dark", source: "press" | "media" | "programmatic" }.
+    detail:
+      scheme:
+        type: string
+        description: Active color scheme ("light" or "dark").
+      source:
+        type: string
+        description: Change source — "press" / "media" / "programmatic".
 slots: {}
 states:
   - name: idle

package/components/toolbar/toolbar.a2ui.json

@@ -48,6 +48,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [
+      "button-ui"
+    ],
     "events": {},
     "examples": [
       {

package/components/toolbar/toolbar.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/toolbar/toolbar.yaml

@@ -8,6 +8,10 @@ category: layout
 version: 1
 description: Horizontal action bar with automatic overflow. Items that don't fit move to a spillover
   popover menu.
+# 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:
   bordered:
     description: Adds a border around the toolbar for visual separation from surrounding content.