@adia-ai/web-components 0.4.8 → 0.5.0

package/components/command/command.a2ui.json

@@ -40,7 +40,17 @@
         "description": "Fired when Escape is pressed"
       },
       "select": {
-        "description": "Fired when an item is selected. Detail contains { value, label, item }."
+        "description": "Fired when an item is selected. Detail contains { value, label, item }.",
+        "detail": {
+          "label": {
+            "description": "Item label text.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Item value attribute.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

package/components/command/command.d.ts

@@ -13,7 +13,14 @@
 import { UIElement } from '../../core/element.js';
 
 export type CommandDismissEvent = CustomEvent<unknown>;
-export type CommandSelectEvent = CustomEvent<unknown>;
+export interface CommandSelectEventDetail {
+  /** Item label text. */
+  label: string;
+  /** Item value attribute. */
+  value: string;
+}
+
+export type CommandSelectEvent = CustomEvent<CommandSelectEventDetail>;
 
 export class UICommand extends UIElement {
   /** Whether the command palette is visible */

package/components/command/command.yaml

@@ -20,6 +20,13 @@ events:
     description: Fired when Escape is pressed
   select:
     description: Fired when an item is selected. Detail contains { value, label, item }.
+    detail:
+      value:
+        type: string
+        description: Item value attribute.
+      label:
+        type: string
+        description: Item label text.
 slots:
   empty:
     description: Empty state shown when no items match

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

@@ -56,7 +56,13 @@
     "composes": [],
     "events": {
       "change": {
-        "description": "Fired when the toggle flips. detail contains { state }."
+        "description": "Fired when the toggle flips. detail contains { state }.",
+        "detail": {
+          "state": {
+            "description": "New toggle state.",
+            "type": "boolean"
+          }
+        }
       }
     },
     "examples": [

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

@@ -12,7 +12,12 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type DemoToggleChangeEvent = CustomEvent<unknown>;
+export interface DemoToggleChangeEventDetail {
+  /** New toggle state. */
+  state: boolean;
+}
+
+export type DemoToggleChangeEvent = CustomEvent<DemoToggleChangeEventDetail>;
 
 export class UIDemoToggle extends UIElement {
   /** Initial state when [state] is not set on connect ("on" | "off"). */

package/components/demo-toggle/demo-toggle.yaml

@@ -44,6 +44,10 @@ props:
 events:
   change:
     description: Fired when the toggle flips. detail contains { state }.
+    detail:
+      state:
+        type: boolean
+        description: New toggle state.
 slots:
   bar:
     description: Internal header bar (auto-stamped). Hosts the embedded switch + label.

package/components/heatmap/heatmap.a2ui.json

@@ -87,10 +87,19 @@
     "composes": [],
     "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\nalongside cell-hover so consumers wiring a pointer-follow tooltip via\ntooltip-ui[follows=pointer] can listen for one event-name regardless\nof chart kind (chart-ui + heatmap-ui both emit it).\n"
+      },
+      "chart-leave": {
+        "description": "Signal-only counterpart to chart-hover. Fires when the pointer leaves\nthe heatmap grid. Detail-free — receivers should clear their hover\nstate on receipt.\n"
+      },
+      "chart-select": {
+        "description": "Canonical chart-select shape — same detail as cell-click. Re-emitted\nalongside cell-click for chart-kind-agnostic listeners.\n"
       }
     },
     "examples": [

package/components/heatmap/heatmap.d.ts

@@ -14,6 +14,9 @@ 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 */
@@ -40,4 +43,7 @@ export class UIHeatmap extends UIElement {
   ): 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/link/link.a2ui.json

@@ -83,7 +83,17 @@
     "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

@@ -36,7 +36,14 @@ wiring. ARIA role is "link" (set automatically by `<a>` element).
 
 import { UIElement } from '../../core/element.js';
 
-export type LinkPressEvent = CustomEvent<unknown>;
+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. */

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

@@ -49,7 +49,17 @@
     ],
     "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

@@ -12,7 +12,14 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type ListSelectionChangeEvent = CustomEvent<unknown>;
+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 */

package/components/list/list.yaml

@@ -32,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

@@ -50,7 +50,17 @@
     ],
     "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

@@ -12,7 +12,14 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type MenuActionEvent = CustomEvent<unknown>;
+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 */

package/components/menu/menu.yaml

@@ -33,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/nav/nav.a2ui.json

@@ -51,7 +51,21 @@
     "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

@@ -20,7 +20,16 @@ and a [heading] kicker rendered via CSS.
 
 import { UIElement } from '../../core/element.js';
 
-export type NavSelectEvent = CustomEvent<unknown>;
+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. */

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

@@ -61,7 +61,17 @@
     "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": [],

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

@@ -20,7 +20,14 @@ when [collapsible] (default true).
 
 import { UIElement } from '../../core/element.js';
 
-export type NavGroupGroupToggleEvent = CustomEvent<unknown>;
+export interface NavGroupGroupToggleEventDetail {
+  /** Whether the group is now open. */
+  open: boolean;
+  /** Group label text. */
+  text: string;
+}
+
+export type NavGroupGroupToggleEvent = CustomEvent<NavGroupGroupToggleEventDetail>;
 
 export class UINavGroup extends UIElement {
   /** Optional trailing badge (count, label). */

package/components/nav-group/nav-group.yaml

@@ -44,6 +44,13 @@ props:
 events:
   group-toggle:
     description: "Fired when the header toggles via click/keyboard. Detail: { text, open }."
+    detail:
+      text:
+        type: string
+        description: Group label text.
+      open:
+        type: boolean
+        description: Whether the group is now open.
 
 slots:
   default:

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

@@ -66,7 +66,21 @@
     "composes": [],
     "events": {
       "nav-select": {
-        "description": "Bubbles when the item is activated. Detail: { item, text, value }."
+        "description": "Bubbles when the item is activated. Detail: { item, text, value }.",
+        "detail": {
+          "item": {
+            "description": "The nav-item element itself.",
+            "type": "object"
+          },
+          "text": {
+            "description": "Item text content.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Item value attribute.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [],

package/components/nav-item/nav-item.d.ts

@@ -20,7 +20,16 @@ bubbles a `nav-select` event.
 
 import { UIElement } from '../../core/element.js';
 
-export type NavItemNavSelectEvent = CustomEvent<unknown>;
+export interface NavItemNavSelectEventDetail {
+  /** The nav-item element itself. */
+  item: Record<string, unknown>;
+  /** Item text content. */
+  text: string;
+  /** Item value attribute. */
+  value: string;
+}
+
+export type NavItemNavSelectEvent = CustomEvent<NavItemNavSelectEventDetail>;
 
 export class UINavItem extends UIElement {
   /** Optional trailing badge. */

package/components/nav-item/nav-item.yaml

@@ -48,6 +48,16 @@ props:
 events:
   nav-select:
     description: "Bubbles when the item is activated. Detail: { item, text, value }."
+    detail:
+      item:
+        type: object
+        description: The nav-item element itself.
+      text:
+        type: string
+        description: Item text content.
+      value:
+        type: string
+        description: Item value attribute.
 
 slots:
   default:

package/components/noodles/noodles.a2ui.json

@@ -92,10 +92,54 @@
     "composes": [],
     "events": {
       "noodle-connect": {
-        "description": "Fired when a connection is created. detail: { id, from, to, fromPort, toPort }"
+        "description": "Fired when a connection is created. detail: { id, from, to, fromPort, toPort }",
+        "detail": {
+          "from": {
+            "description": "Source node ID.",
+            "type": "string"
+          },
+          "fromPort": {
+            "description": "Source port identifier.",
+            "type": "string"
+          },
+          "id": {
+            "description": "Connection ID.",
+            "type": "string"
+          },
+          "to": {
+            "description": "Target node ID.",
+            "type": "string"
+          },
+          "toPort": {
+            "description": "Target port identifier.",
+            "type": "string"
+          }
+        }
       },
       "noodle-disconnect": {
-        "description": "Fired when a connection is removed. detail: { id, from, to, fromPort, toPort }"
+        "description": "Fired when a connection is removed. detail: { id, from, to, fromPort, toPort }",
+        "detail": {
+          "from": {
+            "description": "Source node ID.",
+            "type": "string"
+          },
+          "fromPort": {
+            "description": "Source port identifier.",
+            "type": "string"
+          },
+          "id": {
+            "description": "Connection ID.",
+            "type": "string"
+          },
+          "to": {
+            "description": "Target node ID.",
+            "type": "string"
+          },
+          "toPort": {
+            "description": "Target port identifier.",
+            "type": "string"
+          }
+        }
       },
       "noodle-drag": {
         "description": "Fired during drag-to-connect. detail: { from, fromPort, x, y, reconnect }"

package/components/noodles/noodles.d.ts

@@ -12,8 +12,34 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type NoodlesNoodleConnectEvent = CustomEvent<unknown>;
-export type NoodlesNoodleDisconnectEvent = CustomEvent<unknown>;
+export interface NoodlesNoodleConnectEventDetail {
+  /** Source node ID. */
+  from: string;
+  /** Source port identifier. */
+  fromPort: string;
+  /** Connection ID. */
+  id: string;
+  /** Target node ID. */
+  to: string;
+  /** Target port identifier. */
+  toPort: string;
+}
+
+export type NoodlesNoodleConnectEvent = CustomEvent<NoodlesNoodleConnectEventDetail>;
+export interface NoodlesNoodleDisconnectEventDetail {
+  /** Source node ID. */
+  from: string;
+  /** Source port identifier. */
+  fromPort: string;
+  /** Connection ID. */
+  id: string;
+  /** Target node ID. */
+  to: string;
+  /** Target port identifier. */
+  toPort: string;
+}
+
+export type NoodlesNoodleDisconnectEvent = CustomEvent<NoodlesNoodleDisconnectEventDetail>;
 export type NoodlesNoodleDragEvent = CustomEvent<unknown>;
 
 export class UINoodles extends UIElement {

package/components/noodles/noodles.yaml

@@ -68,8 +68,40 @@ props:
 events:
   noodle-connect:
     description: "Fired when a connection is created. detail: { id, from, to, fromPort, toPort }"
+    detail:
+      id:
+        type: string
+        description: Connection ID.
+      from:
+        type: string
+        description: Source node ID.
+      to:
+        type: string
+        description: Target node ID.
+      fromPort:
+        type: string
+        description: Source port identifier.
+      toPort:
+        type: string
+        description: Target port identifier.
   noodle-disconnect:
     description: "Fired when a connection is removed. detail: { id, from, to, fromPort, toPort }"
+    detail:
+      id:
+        type: string
+        description: Connection ID.
+      from:
+        type: string
+        description: Source node ID.
+      to:
+        type: string
+        description: Target node ID.
+      fromPort:
+        type: string
+        description: Source port identifier.
+      toPort:
+        type: string
+        description: Target port identifier.
   noodle-drag:
     description: "Fired during drag-to-connect. detail: { from, fromPort, x, y, reconnect }"
 slots: {}

package/components/otp-input/otp-input.a2ui.json

@@ -47,10 +47,22 @@
     "composes": [],
     "events": {
       "complete": {
-        "description": "Fired when all digits are filled. Detail contains { code }."
+        "description": "Fired exactly once when the user fills the last digit slot. detail.value is the combined string.",
+        "detail": {
+          "value": {
+            "description": "Combined digits (e.g. \"123456\").",
+            "type": "string"
+          }
+        }
       },
       "input": {
-        "description": "Fired on every digit change"
+        "description": "Fired on every digit change. detail.value is the current combined string.",
+        "detail": {
+          "value": {
+            "description": "Combined digits at the moment of the change.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [