@adia-ai/web-components 0.4.7 → 0.4.9

package/components/heatmap/heatmap.d.ts

@@ -5,12 +5,19 @@
  *
  * 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 HeatmapCellClickEvent = CustomEvent<unknown>;
+export type HeatmapCellHoverEvent = CustomEvent<unknown>;
+export type HeatmapChartHoverEvent = CustomEvent<unknown>;
+export type HeatmapChartLeaveEvent = CustomEvent<unknown>;
+export type HeatmapChartSelectEvent = CustomEvent<unknown>;
+
 export class UIHeatmap extends UIElement {
   /** Heatmap type */
   type: 'day-grid' | 'matrix' | 'density';
@@ -28,4 +35,15 @@ export class UIHeatmap extends UIElement {
   scale: 'linear' | 'log' | 'quantile';
   /** ISO start date; labels months in day-grid mode */
   startDate: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIHeatmap, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'cell-click', listener: (ev: HeatmapCellClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'cell-hover', listener: (ev: HeatmapCellHoverEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'chart-hover', listener: (ev: HeatmapChartHoverEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'chart-leave', listener: (ev: HeatmapChartLeaveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'chart-select', listener: (ev: HeatmapChartSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/heatmap/heatmap.yaml

@@ -62,9 +62,24 @@ props:
     attribute: start-date
 events:
   cell-click:
-    description: "Fired on cell-click."
+    description: Fired on cell click. detail carries the cell's row + column indices + value.
   cell-hover:
-    description: "Fired on cell-hover."
+    description: Fired on cell hover. detail carries the cell's row + column indices + value.
+  chart-hover:
+    description: |
+      Canonical chart-hover shape — same detail as cell-hover. Re-emitted
+      alongside cell-hover so consumers wiring a pointer-follow tooltip via
+      tooltip-ui[follows=pointer] can listen for one event-name regardless
+      of chart kind (chart-ui + heatmap-ui both emit it).
+  chart-leave:
+    description: |
+      Signal-only counterpart to chart-hover. Fires when the pointer leaves
+      the heatmap grid. Detail-free — receivers should clear their hover
+      state on receipt.
+  chart-select:
+    description: |
+      Canonical chart-select shape — same detail as cell-click. Re-emitted
+      alongside cell-click for chart-kind-agnostic listeners.
 slots:
   title:
     description: "Child content region for the `title` slot."

package/components/icon/icon.a2ui.json

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

package/components/icon/icon.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/image/image.a2ui.json

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

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

@@ -7,6 +7,10 @@ component: Image
 category: display
 version: 1
 description: Lazy-loading image with skeleton fallback. Shows skeleton while loading, falls back on error.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - skeleton-ui
 props:
   alt:
     description: Alt text for the image.

package/components/index.js

@@ -9,6 +9,14 @@
    list-ui). See packages/web-components/core/data-stream.js. */
 import '../core/data-stream.js';
 
+/* Side-effect import — wires the full @phosphor-icons/core asset tree
+   into the icon registry (`core/icons.js`). Consumers who load the
+   components barrel are loading ~90 elements; pulling phosphor along is
+   the zero-config expectation. Apps with bundle-size SLOs should skip
+   this barrel, import primitives piecemeal, and call
+   `installIconLoaders()` with a scoped glob — see `core/icons.js` JSDoc. */
+import '../core/icons-phosphor.js';
+
 export { UIIcon } from './icon/icon.js';
 export { UIButton } from './button/button.js';
 export { UILink } from './link/link.js';

package/components/input/input.a2ui.json

@@ -159,6 +159,10 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "input",
+    "composes": [
+      "button-ui",
+      "icon-ui"
+    ],
     "events": {
       "change": {
         "description": "Fired on blur, Enter, or a stepper-button click (bubbles)"

package/components/input/input.yaml

@@ -8,6 +8,12 @@ description: Text input field with contenteditable surface. Supports prefix/suff
   `type="number"` mode that renders [+]/[-] stepper buttons, numeric input filtering, and ARIA spinbutton semantics — no native
   `<input type="number">` under the hood. Password type uses a native `<input>` (only path that still wraps native, for `-webkit-text-security`
   disc masking).
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - button-ui  # [+]/[-] stepper buttons (created when type="number")
+  - icon-ui    # caret-up/caret-down icons inside the stepper buttons
+
 props:
   name:
     description: Form control name for form data submission

package/components/inspector/inspector.a2ui.json

@@ -29,6 +29,11 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "tabs-ui",
+      "tab-ui",
+      "code-ui"
+    ],
     "events": {},
     "examples": [
       {

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

@@ -5,6 +5,12 @@ component: Inspector
 category: agent
 version: 1
 description: Developer tools pane for inspecting A2UI state.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - tabs-ui
+  - tab-ui
+  - code-ui
 props:
   value:
     description: Active tab. One of 'catalog', 'surface', 'messages', 'code'.

package/components/kbd/kbd.a2ui.json

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

package/components/kbd/kbd.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/link/link.a2ui.json

@@ -80,9 +80,20 @@
       "❌ `<link-ui>` for form submission — submission is a button concern. Use `<button-ui type=\"submit\">`."
     ],
     "category": "content",
+    "composes": [],
     "events": {
       "press": {
-        "description": "Bubbles when the link is activated by click or Enter. Detail: `{ href, target }`. Fires BEFORE the browser's native navigation so handlers can `preventDefault()` and route through the A2UI action handler system. If no handler intercepts, native navigation proceeds."
+        "description": "Bubbles when the link is activated by click or Enter. Detail: `{ href, target }`. Fires BEFORE the browser's native navigation so handlers can `preventDefault()` and route through the A2UI action handler system. If no handler intercepts, native navigation proceeds.",
+        "detail": {
+          "href": {
+            "description": "Link href attribute.",
+            "type": "string"
+          },
+          "target": {
+            "description": "Link target attribute (e.g. _blank).",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

package/components/link/link.d.ts

@@ -29,12 +29,22 @@ wiring. ARIA role is "link" (set automatically by `<a>` element).
  *
  * 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 LinkPressEventDetail {
+  /** Link href attribute. */
+  href: string;
+  /** Link target attribute (e.g. _blank). */
+  target: string;
+}
+
+export type LinkPressEvent = CustomEvent<LinkPressEventDetail>;
+
 export class UILink extends UIElement {
   /** Stretches the link to fill its container; useful for standalone link rows. */
   block: boolean;
@@ -52,4 +62,11 @@ export class UILink extends UIElement {
   text: string;
   /** Visual treatment. `default` underlines on rest + hover (standard link affordance). `subtle` underlines only on hover (for tighter designs where always-underlined would be noisy). `quiet` drops the link color and matches surrounding text color (used for footer-link rows where the link affordance is implied by context, not by color). */
   variant: 'default' | 'subtle' | 'quiet';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UILink, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'press', listener: (ev: LinkPressEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/link/link.yaml

@@ -102,6 +102,13 @@ events:
       so handlers can `preventDefault()` and route through the A2UI
       action handler system. If no handler intercepts, native
       navigation proceeds.
+    detail:
+      href:
+        type: string
+        description: Link href attribute.
+      target:
+        type: string
+        description: Link target attribute (e.g. _blank).
 
 slots:
   default:

package/components/list/list.a2ui.json

@@ -44,9 +44,22 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "selection-change": {
-        "description": "Fired on selection-change."
+        "description": "Fired on selection-change.",
+        "detail": {
+          "key": {
+            "description": "New selection key.",
+            "type": "string"
+          },
+          "previousKey": {
+            "description": "Previously selected key.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

package/components/list/list.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 ListSelectionChangeEventDetail {
+  /** New selection key. */
+  key: string;
+  /** Previously selected key. */
+  previousKey: string;
+}
+
+export type ListSelectionChangeEvent = CustomEvent<ListSelectionChangeEventDetail>;
+
 export class UIList extends UIElement {
   /** Show dividers between items */
   divider: boolean;
@@ -20,4 +30,11 @@ export class UIList extends UIElement {
   selectedKey: string;
   /** Item spacing */
   spacing: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIList, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'selection-change', listener: (ev: ListSelectionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/list/list.yaml

@@ -7,6 +7,10 @@ component: List
 category: layout
 version: 1
 description: Styled list with optional icons and dividers.
+# 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:
   divider:
     description: Show dividers between items
@@ -28,6 +32,13 @@ props:
 events:
   selection-change:
     description: "Fired on selection-change."
+    detail:
+      key:
+        type: string
+        description: New selection key.
+      previousKey:
+        type: string
+        description: Previously selected key.
 slots: {}
 states:
   - name: idle

package/components/menu/menu.a2ui.json

@@ -45,9 +45,22 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "action": {
-        "description": "Fired when a menu item is activated. Detail contains the triggering element."
+        "description": "Fired when a menu item is activated. Detail contains the triggering element.",
+        "detail": {
+          "text": {
+            "description": "Menu item text.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Menu item value.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

package/components/menu/menu.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 MenuActionEventDetail {
+  /** Menu item text. */
+  text: string;
+  /** Menu item value. */
+  value: string;
+}
+
+export type MenuActionEvent = CustomEvent<MenuActionEventDetail>;
+
 export class UIMenu extends UIElement {
   /** Gap in px */
   gap: number;
@@ -18,4 +28,11 @@ export class UIMenu extends UIElement {
   open: boolean;
   /** Preferred position relative to the anchor element */
   placement: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIMenu, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'action', listener: (ev: MenuActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/menu/menu.yaml

@@ -7,6 +7,10 @@ component: Menu
 category: container
 version: 1
 description: Dropdown action menu with roving focus and keyboard navigation. Uses Popover API.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui  # leading affordances on menu items (created in render)
 props:
   gap:
     description: Gap in px
@@ -29,6 +33,13 @@ props:
 events:
   action:
     description: Fired when a menu item is activated. Detail contains the triggering element.
+    detail:
+      value:
+        type: string
+        description: Menu item value.
+      text:
+        type: string
+        description: Menu item text.
 slots:
   default:
     description: Menu items with role="menuitem" and optional <hr> dividers

package/components/modal/modal.a2ui.json

@@ -50,6 +50,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "close": {
         "description": "Fired when the overlay is dismissed via backdrop click, Escape key, popover toggle, or programmatic hide(). Bubbles."

package/components/modal/modal.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 ModalCloseEvent = CustomEvent<unknown>;
+
 export class UIModal extends UIElement {
   /** Controls overlay visibility. Setting to true opens the surface with entry animation. */
   open: boolean;
@@ -20,4 +23,11 @@ export class UIModal extends UIElement {
   size: 'sm' | 'md' | 'lg' | 'xl';
   /** Aria label applied to the surface element for accessibility */
   text: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIModal, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'close', listener: (ev: ModalCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/nav/nav.a2ui.json

@@ -48,9 +48,24 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "nav-select": {
-        "description": "Bubbles from <nav-item-ui> children when one is selected. Detail: { item, text, value }."
+        "description": "Bubbles from <nav-item-ui> children when one is selected. Detail: { item, text, value }.",
+        "detail": {
+          "item": {
+            "description": "Selected nav-item element.",
+            "type": "object"
+          },
+          "text": {
+            "description": "Item text content.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Item value attribute.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

package/components/nav/nav.d.ts

@@ -13,12 +13,24 @@ and a [heading] kicker rendered via CSS.
  *
  * 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 NavSelectEventDetail {
+  /** Selected nav-item element. */
+  item: Record<string, unknown>;
+  /** Item text content. */
+  text: string;
+  /** Item value attribute. */
+  value: string;
+}
+
+export type NavSelectEvent = CustomEvent<NavSelectEventDetail>;
+
 export class UINav extends UIElement {
   /** Primary-variant only. Force icon-only collapse regardless of viewport width. */
   collapsed: boolean;
@@ -28,4 +40,11 @@ export class UINav extends UIElement {
   heading: string;
   /** Visual treatment. primary = app sidebar; section = subnav rail. */
   variant: 'primary' | 'section';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UINav, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'nav-select', listener: (ev: NavSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/nav/nav.yaml

@@ -36,6 +36,16 @@ props:
 events:
   nav-select:
     description: "Bubbles from <nav-item-ui> children when one is selected. Detail: { item, text, value }."
+    detail:
+      item:
+        type: object
+        description: Selected nav-item element.
+      text:
+        type: string
+        description: Item text content.
+      value:
+        type: string
+        description: Item value attribute.
 
 slots:
   default:

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

@@ -58,9 +58,20 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "group-toggle": {
-        "description": "Fired when the header toggles via click/keyboard. Detail: { text, open }."
+        "description": "Fired when the header toggles via click/keyboard. Detail: { text, open }.",
+        "detail": {
+          "open": {
+            "description": "Whether the group is now open.",
+            "type": "boolean"
+          },
+          "text": {
+            "description": "Group label text.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [],