@adia-ai/web-components 0.4.6 → 0.4.8

package/components/agent-suggestions/class.js

@@ -0,0 +1,97 @@
+/**
+ * Non-side-effect class export for `<agent-suggestions-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/agent-suggestions`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <agent-suggestions-ui> — Row of follow-up suggestion chips.
+ *
+ * The agent proposes 2-4 next-step prompts; user picks one. The host listens
+ * for `suggestion-select` and dispatches the associated prompt.
+ *
+ * JS API:
+ *   el.suggestions = [
+ *     { label: 'Add price comparison' },                    // label === prompt
+ *     { label: 'Add quantity stepper', prompt: 'add a stepper' },
+ *     { label: 'Variants picker',       prompt: 'add a variants picker', icon: 'tag' },
+ *   ];
+ *
+ *   el.addEventListener('suggestion-select', (e) => {
+ *     submit(e.detail.prompt);
+ *   });
+ *
+ * Attributes:
+ *   variant   — outline (default) | ghost | subtle
+ *   size      — sm (default) | md
+ *   disabled  — disable all chips
+ *
+ * Events:
+ *   suggestion-select — detail: { label, prompt, index }
+ */
+
+import { UIElement } from '../../core/element.js';
+
+function truncate(s, n) {
+  if (typeof s !== 'string') return '';
+  return s.length > n ? s.slice(0, n - 1) + '…' : s;
+}
+
+export class UIAgentSuggestions extends UIElement {
+  static properties = {
+    variant:  { type: String,  default: 'outline', reflect: true },
+    size:     { type: String,  default: 'sm',      reflect: true },
+    disabled: { type: Boolean, default: false,     reflect: true },
+  };
+
+  static template = () => null;
+
+  #suggestions = [];
+
+  get suggestions() { return this.#suggestions; }
+  set suggestions(v) {
+    this.#suggestions = Array.isArray(v) ? v.slice() : [];
+    this.#render();
+  }
+
+  connected() {
+    this.#render();
+  }
+
+  disconnected() {
+    this.innerHTML = '';
+  }
+
+  #render() {
+    this.innerHTML = '';
+    for (let i = 0; i < this.#suggestions.length; i++) {
+      const s = this.#suggestions[i];
+      const label = typeof s === 'string' ? s : s.label || s.prompt || '';
+      const prompt = typeof s === 'string' ? s : s.prompt || s.label || '';
+      const icon = typeof s === 'object' ? s.icon : null;
+
+      const chip = document.createElement('button-ui');
+      chip.setAttribute('text', truncate(label, 42));
+      chip.setAttribute('variant', this.variant);
+      chip.setAttribute('size', this.size);
+      if (icon) chip.setAttribute('icon', icon);
+      if (this.disabled) chip.setAttribute('disabled', '');
+
+      chip.addEventListener('press', () => {
+        if (this.disabled) return;
+        this.dispatchEvent(new CustomEvent('suggestion-select', {
+          bubbles: true,
+          detail: { label, prompt, index: i },
+        }));
+      });
+      this.appendChild(chip);
+    }
+  }
+}

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

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [],
     "events": {
       "trace-toggle": {
         "description": "Fired on trace-toggle."

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

@@ -0,0 +1,29 @@
+/**
+ * `<agent-trace-ui>` — Collapsible metrics + training-feedback panel for an agent turn.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/agent-trace
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * 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 AgentTraceTraceToggleEvent = CustomEvent<unknown>;
+
+export class UIAgentTrace extends UIElement {
+  /** Hide the trace body. Default-visible disclosure (matches the agent-* family — agent-reasoning, agent-artifact). Set to opt out. */
+  collapsed: boolean;
+  /** Fallback summary label. */
+  label: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAgentTrace, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'trace-toggle', listener: (ev: AgentTraceTraceToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/alert/alert.a2ui.json

@@ -68,6 +68,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "close": {
         "description": "Fired when the close button is clicked"

package/components/alert/alert.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `<alert-ui>` — Inline alert banner with optional icon and close button.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/alert
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * 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 AlertCloseEvent = CustomEvent<unknown>;
+
+export class UIAlert extends UIElement {
+  /** Bold headline rendered as the first line of the alert content. Pair with [description] for the canonical "banner" pattern (headline + body). When [title] or [description] is set, the [text] prop is ignored. */
+  title: string;
+  /** Body text rendered as the second line of the alert content, below [title]. May be used alone (without [title]) for a single muted-body message. */
+  description: string;
+  /** Whether a close button is displayed. Alias [dismissible] is also accepted (same semantics, different spelling — the corpus and many libraries use both; both map to the same state). */
+  closable: boolean;
+  /** Public alias for [closable] — same semantics. Both attributes render the close button. Use whichever spelling matches your authoring style. */
+  dismissible: boolean;
+  /** Icon identifier displayed before the message content */
+  icon: string;
+  /** Single-line alert message. For two-line "headline + body" alerts, use [title] + [description] instead. For rich content (links, formatting), use the [slot="content"] slot. */
+  text: string;
+  /** Semantic color variant. */
+  variant: 'default' | 'info' | 'success' | 'warning' | 'danger' | 'muted' | 'neutral';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAlert, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'close', listener: (ev: AlertCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/alert/alert.js

@@ -1,184 +1,17 @@
 /**
- * <alert-ui text="Something happened" variant="info" icon="info-circle"></alert-ui>
- * <alert-ui text="Deleted." variant="danger" closable></alert-ui>
+ * `<alert-ui>` — auto-registers the tag on import.
  *
- * Inline alert banner with optional icon and close button.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Variants: default, info, success, warning, danger, muted, neutral
- * Slots: leading (icon), content (text), close (dismiss button)
+ *   import { UIAlert } from '@adia-ai/web-components/components/alert/class';
  *
- * Events:
- *   close — fired when the user dismisses the alert
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+import { UIAlert } from './class.js';
 
-// One-time warn cache so the same alias hit doesn't spam the console
-// across hundreds of components per render. We use warnings ONLY for
-// genuine hallucinations the LLM should learn to stop emitting:
-//   - variant="error" (canonical: "danger" — explicit in the enum)
-//   - [closeable]      (canonical: "closable" — established spelling)
-// First-class props ([title], [description], [dismissible]) do NOT warn —
-// they're public, supported, documented in alert.yaml.
-const _aliasWarned = new Set();
-function _warnOnce(key, message) {
-  if (_aliasWarned.has(key)) return;
-  _aliasWarned.add(key);
-  // eslint-disable-next-line no-console
-  console.warn(`[alert-ui] ${message}`);
-}
-
-class UIAlert extends UIElement {
-  static properties = {
-    text:        { type: String,  default: '', reflect: true },
-    title:       { type: String,  default: '', reflect: true },
-    description: { type: String,  default: '', reflect: true },
-    variant:     { type: String,  default: 'default', reflect: true },
-    closable:    { type: Boolean, default: false, reflect: true },
-    dismissible: { type: Boolean, default: false, reflect: true },
-    icon:        { type: String,  default: '', reflect: true },
-  };
-
-  static parts = {
-    leading: '<icon-ui slot="leading"></icon-ui>',
-    content: '<span slot="content"></span>',
-    /* Close affordance is a real button-ui \u2014 inherits the system focus
-       ring, hover transition, and icon sizing automatically. Listen for
-       the canonical `press` event (button-ui dispatches on click + Enter
-       + Space, no extra keydown wiring needed). */
-    close:   '<button-ui slot="close" icon="x" variant="ghost" size="sm" aria-label="Close"></button-ui>',
-  };
-
-  static template = () => null;
-
-  /**
-   * Normalize alias attrs that the LLM / corpus occasionally emits in
-   * non-canonical forms. Runs once at connected() before render(). Two
-   * categories:
-   *
-   *   FIRST-CLASS ALIASES (public, supported, no warn):
-   *     - [dismissible] ↔ [closable]  (same semantics; either spelling
-   *       maps to the same close-button affordance)
-   *
-   *   HALLUCINATION ALIASES (warn-once, encourage canonical form):
-   *     - variant="error" → variant="danger"  (not in the canonical
-   *       enum [default, info, success, warning, danger, muted, neutral])
-   *     - [closeable] → [closable]  (alternate spelling, less standard
-   *       than dismissible/closable; warn to discourage)
-   */
-  #normalizeAliases() {
-    // variant=error → danger (hallucination; warn)
-    if (this.getAttribute('variant') === 'error') {
-      _warnOnce('variant-error', 'variant="error" is not in the canonical enum [default, info, success, warning, danger, muted, neutral]. Mapping to "danger". Fix the source (LLM prompt / corpus pattern) to emit "danger" directly.');
-      this.setAttribute('variant', 'danger');
-    }
-
-    // closeable → closable (typo-class; warn)
-    if (this.hasAttribute('closeable') && !this.hasAttribute('closable') && !this.hasAttribute('dismissible')) {
-      _warnOnce('alias-closeable', 'attribute [closeable] is a misspelled alias of canonical [closable]. Mapping. Fix the source to use [closable] or [dismissible].');
-      this.setAttribute('closable', '');
-      this.removeAttribute('closeable');
-    }
-
-    // dismissible ↔ closable (first-class alias; no warn)
-    if (this.hasAttribute('dismissible') && !this.hasAttribute('closable')) {
-      this.setAttribute('closable', '');
-    }
-  }
-
-  #onPress = (e) => {
-    if (e.target.closest('[slot="close"]')) this.#close();
-  };
-
-  connected() {
-    this.#normalizeAliases();
-    this.#updateRole();
-
-    // Stamp default DOM if nothing was provided
-    if (this.icon) this.ensure('leading');
-    this.ensure('content');
-    if (this.closable) this.ensure('close');
-
-    this.addEventListener('press', this.#onPress);
-  }
-
-  disconnected() {
-    this.removeEventListener('press', this.#onPress);
-  }
-
-  render() {
-    // Icon
-    if (this.icon) {
-      const leading = this.ensure('leading');
-      if (leading) leading.setAttribute('name', this.icon);
-    } else {
-      this.drop('leading');
-    }
-
-    // Content rendering — three modes, in precedence order:
-    //   1. Author-provided <span slot="content">…</span> with content
-    //      already inside wins (rich content path)
-    //   2. [title] and/or [description] — bolded headline + body paragraph
-    //   3. [text] — single-line message
-    //
-    // Detection of "author content" is by checking whether the slot
-    // element has its `data-alert-auto` flag (set by us when we stamp
-    // content). If the flag is absent AND the element has any content,
-    // the author provided it; leave it alone.
-    const content = this.ensure('content');
-    if (content) {
-      const wasAutoStamped = content.hasAttribute('data-alert-auto');
-      const hasContent = content.childNodes.length > 0;
-      if (!wasAutoStamped && hasContent) {
-        // Author-provided rich content. Mirror title/description to
-        // aria-label if they were set, but don't touch the markup.
-        if (this.title || this.description) {
-          const aria = [this.title, this.description].filter(Boolean).join('. ');
-          this.setAttribute('aria-label', aria);
-        }
-      } else if (this.title || this.description) {
-        // Mode 2: title + description composed
-        content.setAttribute('data-alert-auto', 'title-desc');
-        content.replaceChildren();
-        if (this.title) {
-          const strong = document.createElement('strong');
-          strong.textContent = this.title;
-          content.appendChild(strong);
-          if (this.description) content.appendChild(document.createTextNode(' '));
-        }
-        if (this.description) {
-          content.appendChild(document.createTextNode(this.description));
-        }
-        const aria = [this.title, this.description].filter(Boolean).join('. ');
-        this.setAttribute('aria-label', aria);
-      } else if (this.text) {
-        // Mode 3: single-line text
-        content.setAttribute('data-alert-auto', 'text');
-        content.textContent = this.text;
-      }
-    }
-
-    // Close button
-    if (this.closable || this.dismissible) {
-      this.ensure('close');
-    } else {
-      this.drop('close');
-    }
-
-    // Role
-    this.#updateRole();
-  }
-
-  #updateRole() {
-    const role = (this.variant === 'danger' || this.variant === 'warning') ? 'alert' : 'status';
-    this.setAttribute('role', role);
-  }
-
-  #close() {
-    this.dispatchEvent(new Event('close', { bubbles: true }));
-    this.remove();
-  }
-}
-customElements.define('alert-ui', UIAlert);
+defineIfFree('alert-ui', UIAlert);
 
 export { UIAlert };

package/components/alert/class.js

@@ -0,0 +1,194 @@
+/**
+ * Non-side-effect class export for `<alert-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/alert`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <alert-ui text="Something happened" variant="info" icon="info-circle"></alert-ui>
+ * <alert-ui text="Deleted." variant="danger" closable></alert-ui>
+ *
+ * Inline alert banner with optional icon and close button.
+ *
+ * Variants: default, info, success, warning, danger, muted, neutral
+ * Slots: leading (icon), content (text), close (dismiss button)
+ *
+ * Events:
+ *   close — fired when the user dismisses the alert
+ */
+
+import { UIElement } from '../../core/element.js';
+
+// One-time warn cache so the same alias hit doesn't spam the console
+// across hundreds of components per render. We use warnings ONLY for
+// genuine hallucinations the LLM should learn to stop emitting:
+//   - variant="error" (canonical: "danger" — explicit in the enum)
+//   - [closeable]      (canonical: "closable" — established spelling)
+// First-class props ([title], [description], [dismissible]) do NOT warn —
+// they're public, supported, documented in alert.yaml.
+const _aliasWarned = new Set();
+function _warnOnce(key, message) {
+  if (_aliasWarned.has(key)) return;
+  _aliasWarned.add(key);
+  // eslint-disable-next-line no-console
+  console.warn(`[alert-ui] ${message}`);
+}
+
+export class UIAlert extends UIElement {
+  static properties = {
+    text:        { type: String,  default: '', reflect: true },
+    title:       { type: String,  default: '', reflect: true },
+    description: { type: String,  default: '', reflect: true },
+    variant:     { type: String,  default: 'default', reflect: true },
+    closable:    { type: Boolean, default: false, reflect: true },
+    dismissible: { type: Boolean, default: false, reflect: true },
+    icon:        { type: String,  default: '', reflect: true },
+  };
+
+  static parts = {
+    leading: '<icon-ui slot="leading"></icon-ui>',
+    content: '<span slot="content"></span>',
+    /* Close affordance is a real button-ui \u2014 inherits the system focus
+       ring, hover transition, and icon sizing automatically. Listen for
+       the canonical `press` event (button-ui dispatches on click + Enter
+       + Space, no extra keydown wiring needed). */
+    close:   '<button-ui slot="close" icon="x" variant="ghost" size="sm" aria-label="Close"></button-ui>',
+  };
+
+  static template = () => null;
+
+  /**
+   * Normalize alias attrs that the LLM / corpus occasionally emits in
+   * non-canonical forms. Runs once at connected() before render(). Two
+   * categories:
+   *
+   *   FIRST-CLASS ALIASES (public, supported, no warn):
+   *     - [dismissible] ↔ [closable]  (same semantics; either spelling
+   *       maps to the same close-button affordance)
+   *
+   *   HALLUCINATION ALIASES (warn-once, encourage canonical form):
+   *     - variant="error" → variant="danger"  (not in the canonical
+   *       enum [default, info, success, warning, danger, muted, neutral])
+   *     - [closeable] → [closable]  (alternate spelling, less standard
+   *       than dismissible/closable; warn to discourage)
+   */
+  #normalizeAliases() {
+    // variant=error → danger (hallucination; warn)
+    if (this.getAttribute('variant') === 'error') {
+      _warnOnce('variant-error', 'variant="error" is not in the canonical enum [default, info, success, warning, danger, muted, neutral]. Mapping to "danger". Fix the source (LLM prompt / corpus pattern) to emit "danger" directly.');
+      this.setAttribute('variant', 'danger');
+    }
+
+    // closeable → closable (typo-class; warn)
+    if (this.hasAttribute('closeable') && !this.hasAttribute('closable') && !this.hasAttribute('dismissible')) {
+      _warnOnce('alias-closeable', 'attribute [closeable] is a misspelled alias of canonical [closable]. Mapping. Fix the source to use [closable] or [dismissible].');
+      this.setAttribute('closable', '');
+      this.removeAttribute('closeable');
+    }
+
+    // dismissible ↔ closable (first-class alias; no warn)
+    if (this.hasAttribute('dismissible') && !this.hasAttribute('closable')) {
+      this.setAttribute('closable', '');
+    }
+  }
+
+  #onPress = (e) => {
+    if (e.target.closest('[slot="close"]')) this.#close();
+  };
+
+  connected() {
+    this.#normalizeAliases();
+    this.#updateRole();
+
+    // Stamp default DOM if nothing was provided
+    if (this.icon) this.ensure('leading');
+    this.ensure('content');
+    if (this.closable) this.ensure('close');
+
+    this.addEventListener('press', this.#onPress);
+  }
+
+  disconnected() {
+    this.removeEventListener('press', this.#onPress);
+  }
+
+  render() {
+    // Icon
+    if (this.icon) {
+      const leading = this.ensure('leading');
+      if (leading) leading.setAttribute('name', this.icon);
+    } else {
+      this.drop('leading');
+    }
+
+    // Content rendering — three modes, in precedence order:
+    //   1. Author-provided <span slot="content">…</span> with content
+    //      already inside wins (rich content path)
+    //   2. [title] and/or [description] — bolded headline + body paragraph
+    //   3. [text] — single-line message
+    //
+    // Detection of "author content" is by checking whether the slot
+    // element has its `data-alert-auto` flag (set by us when we stamp
+    // content). If the flag is absent AND the element has any content,
+    // the author provided it; leave it alone.
+    const content = this.ensure('content');
+    if (content) {
+      const wasAutoStamped = content.hasAttribute('data-alert-auto');
+      const hasContent = content.childNodes.length > 0;
+      if (!wasAutoStamped && hasContent) {
+        // Author-provided rich content. Mirror title/description to
+        // aria-label if they were set, but don't touch the markup.
+        if (this.title || this.description) {
+          const aria = [this.title, this.description].filter(Boolean).join('. ');
+          this.setAttribute('aria-label', aria);
+        }
+      } else if (this.title || this.description) {
+        // Mode 2: title + description composed
+        content.setAttribute('data-alert-auto', 'title-desc');
+        content.replaceChildren();
+        if (this.title) {
+          const strong = document.createElement('strong');
+          strong.textContent = this.title;
+          content.appendChild(strong);
+          if (this.description) content.appendChild(document.createTextNode(' '));
+        }
+        if (this.description) {
+          content.appendChild(document.createTextNode(this.description));
+        }
+        const aria = [this.title, this.description].filter(Boolean).join('. ');
+        this.setAttribute('aria-label', aria);
+      } else if (this.text) {
+        // Mode 3: single-line text
+        content.setAttribute('data-alert-auto', 'text');
+        content.textContent = this.text;
+      }
+    }
+
+    // Close button
+    if (this.closable || this.dismissible) {
+      this.ensure('close');
+    } else {
+      this.drop('close');
+    }
+
+    // Role
+    this.#updateRole();
+  }
+
+  #updateRole() {
+    const role = (this.variant === 'danger' || this.variant === 'warning') ? 'alert' : 'status';
+    this.setAttribute('role', role);
+  }
+
+  #close() {
+    this.dispatchEvent(new Event('close', { bubbles: true }));
+    this.remove();
+  }
+}

package/components/aside/aside.a2ui.json

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

package/components/avatar/avatar.a2ui.json

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

package/components/avatar/avatar.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `<avatar-ui>` — Avatar with image → initials → empty fallback chain.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/avatar
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * 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 class UIAvatar extends UIElement {
+  /** Phosphor icon name shown instead of initials when `src`/`text` are empty. */
+  icon: string;
+  /** Deprecated alias for `text` (logs a one-shot console warning; will be removed in a future release). New code should use `text=` instead. */
+  name: string;
+  /** Avatar shape */
+  shape: 'circle' | 'square';
+  /** Avatar size. Canonical scale (xs/sm/md/lg/xl); long-form aliases (small/medium/large/xlarge) accepted for back-compat. */
+  size: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'small' | 'medium' | 'large' | 'xlarge';
+  /** Image source URL. Falls back to initials on error. */
+  src: string;
+  /** Display string (full name or initials). Initials derive from spaces — first letter of each word, max 2. */
+  text: string;
+}