@adia-ai/web-components 0.4.5 → 0.4.7

package/components/timeline/class.js

@@ -0,0 +1,176 @@
+/**
+ * Non-side-effect class export for `<timeline-ui>` (+ co-located primitives).
+ *
+ * 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/timeline`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <timeline-ui> — Vertical (or horizontal) event / progress log.
+ *
+ * Each <timeline-item-ui> is one entry, with its own state via the `status`
+ * enum (idle | active | completed | error), optional icon, duration, and an
+ * expandable outcomes list. `[spinner]` is an orthogonal presentation hint
+ * that animates the dot as a ring when combined with `status="active"`.
+ *
+ *   <timeline-ui>
+ *     <timeline-item-ui text="Shipped"   time="2h ago" status="completed"></timeline-item-ui>
+ *     <timeline-item-ui text="Delivery"  time="now"    status="active" spinner></timeline-item-ui>
+ *     <timeline-item-ui text="Received"></timeline-item-ui>
+ *   </timeline-ui>
+ *
+ * For agent reasoning / pipeline views, set size="sm" and use
+ *   duration, outcomes, spinner, status="error"
+ *
+ *   <timeline-ui size="sm">
+ *     <timeline-item-ui text="search" duration="850ms" status="completed"></timeline-item-ui>
+ *     <timeline-item-ui text="generate" status="active" spinner></timeline-item-ui>
+ *   </timeline-ui>
+ *
+ * For wizard / numbered-circle patterns, use the dedicated <stepper-ui>.
+ *
+ * Attributes (container):
+ *   orientation — vertical (default) | horizontal
+ *   size        — md (default) | sm
+ *
+ * Attributes (item):
+ *   text        — primary label
+ *   description — secondary text (optional)
+ *   time        — right-aligned timestamp (optional; mutually exclusive with duration)
+ *   duration    — right-aligned duration label (e.g. "850ms", "2s"); also set when live=true
+ *   icon        — icon-ui name (replaces the dot when set)
+ *   variant     — default | success | accent | warning | danger  (colors the dot/icon)
+ *   completed   — boolean; renders "done" state
+ *   active      — boolean; renders "active" state
+ *   error       — boolean; renders "error" state (red dot)
+ *   spinner     — boolean; spinning dot while active
+ *
+ * JS (item):
+ *   .outcomes = string[]    // renders an expandable sub-list under the row
+ */
+
+import { UIElement } from '../../core/element.js';
+
+// ── Container ──────────────────────────────────────────────────
+
+export class UITimeline extends UIElement {
+  static properties = {
+    orientation: { type: String, default: 'vertical', reflect: true },
+    size:        { type: String, default: 'md',       reflect: true },
+  };
+
+  static template = () => null;
+
+  render() {
+    const items = [...this.querySelectorAll(':scope > timeline-item-ui')];
+    for (const item of items) item.removeAttribute('data-last');
+    const last = items[items.length - 1];
+    if (last) last.setAttribute('data-last', '');
+  }
+}
+
+export class UITimelineItem extends UIElement {
+  static properties = {
+    text:        { type: String,  default: '',        reflect: true },
+    description: { type: String,  default: '',        reflect: true },
+    time:        { type: String,  default: '',        reflect: true },
+    duration:    { type: String,  default: '',        reflect: true },
+    icon:        { type: String,  default: '',        reflect: true },
+    variant:     { type: String,  default: 'default', reflect: true },
+    status:      { type: String,  default: 'idle',    reflect: true },
+    spinner:     { type: Boolean, default: false,     reflect: true },
+  };
+
+  static template = () => null;
+
+  #outcomes = [];
+  #expanded = false;
+
+  get outcomes() { return this.#outcomes; }
+  set outcomes(v) {
+    this.#outcomes = Array.isArray(v) ? v.slice() : [];
+    this.render();
+  }
+
+  connected() {
+    if (!this.querySelector(':scope > [slot="label"]')) {
+      // Author provided just text/time — stamp the default slot structure
+      this.innerHTML = `
+        <span slot="label"></span>
+        <span slot="description"></span>
+        <span slot="time"></span>
+      `;
+    }
+  }
+
+  render() {
+    const label = this.querySelector(':scope > [slot="label"]');
+    const desc  = this.querySelector(':scope > [slot="description"]');
+    const time  = this.querySelector(':scope > [slot="time"]');
+    if (label) label.textContent = this.text;
+    if (desc)  desc.textContent  = this.description;
+    if (time)  time.textContent  = this.duration || this.time;
+
+    if (this.icon) {
+      let iconEl = this.querySelector(':scope > [slot="icon"]');
+      if (!iconEl) {
+        iconEl = document.createElement('icon-ui');
+        iconEl.setAttribute('slot', 'icon');
+        this.prepend(iconEl);
+      }
+      iconEl.setAttribute('name', this.icon);
+    } else {
+      this.querySelector(':scope > [slot="icon"]')?.remove();
+    }
+
+    // Outcomes sub-list + toggle chevron
+    let body = this.querySelector(':scope > [slot="outcomes"]');
+    if (this.#outcomes.length > 0) {
+      if (!body) {
+        body = document.createElement('ul');
+        body.setAttribute('slot', 'outcomes');
+        this.appendChild(body);
+      }
+      body.innerHTML = '';
+      for (const o of this.#outcomes) {
+        const li = document.createElement('li');
+        li.textContent = o;
+        body.appendChild(li);
+      }
+      body.hidden = !this.#expanded;
+
+      // Toggle chevron lives on the row — we stamp a button once
+      let toggle = this.querySelector(':scope > [data-timeline-toggle]');
+      if (!toggle) {
+        toggle = document.createElement('button');
+        toggle.type = 'button';
+        toggle.setAttribute('data-timeline-toggle', '');
+        toggle.setAttribute('aria-label', 'Toggle details');
+        toggle.addEventListener('click', (e) => {
+          e.stopPropagation();
+          this.#expanded = !this.#expanded;
+          this.render();
+          this.dispatchEvent(new CustomEvent('timeline-toggle', {
+            bubbles: true, detail: { expanded: this.#expanded },
+          }));
+        });
+        this.appendChild(toggle);
+      }
+      toggle.innerHTML = '';
+      const caret = document.createElement('icon-ui');
+      caret.setAttribute('name', this.#expanded ? 'caret-down' : 'caret-right');
+      caret.setAttribute('color', 'muted');
+      caret.setAttribute('size', 'sm');
+      toggle.appendChild(caret);
+    } else {
+      this.querySelector(':scope > [data-timeline-toggle]')?.remove();
+      body?.remove();
+    }
+  }
+}

package/components/timeline/timeline.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `<timeline-ui>` — Timeline and step wizard. Two modes: timeline (per-item state) and steps (parent-driven).
+ *
+ * @see https://ui-kit.exe.xyz/site/components/timeline
+ *
+ * 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.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+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';
+}

package/components/timeline/timeline.js

@@ -1,171 +1,18 @@
 /**
- * <timeline-ui> — Vertical (or horizontal) event / progress log.
+ * `<timeline-ui>` — auto-registers the tag on import.
  *
- * Each <timeline-item-ui> is one entry, with its own state via the `status`
- * enum (idle | active | completed | error), optional icon, duration, and an
- * expandable outcomes list. `[spinner]` is an orthogonal presentation hint
- * that animates the dot as a ring when combined with `status="active"`.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- *   <timeline-ui>
- *     <timeline-item-ui text="Shipped"   time="2h ago" status="completed"></timeline-item-ui>
- *     <timeline-item-ui text="Delivery"  time="now"    status="active" spinner></timeline-item-ui>
- *     <timeline-item-ui text="Received"></timeline-item-ui>
- *   </timeline-ui>
+ *   import { UITimeline, UITimelineItem } from '@adia-ai/web-components/components/timeline/class';
  *
- * For agent reasoning / pipeline views, set size="sm" and use
- *   duration, outcomes, spinner, status="error"
- *
- *   <timeline-ui size="sm">
- *     <timeline-item-ui text="search" duration="850ms" status="completed"></timeline-item-ui>
- *     <timeline-item-ui text="generate" status="active" spinner></timeline-item-ui>
- *   </timeline-ui>
- *
- * For wizard / numbered-circle patterns, use the dedicated <stepper-ui>.
- *
- * Attributes (container):
- *   orientation — vertical (default) | horizontal
- *   size        — md (default) | sm
- *
- * Attributes (item):
- *   text        — primary label
- *   description — secondary text (optional)
- *   time        — right-aligned timestamp (optional; mutually exclusive with duration)
- *   duration    — right-aligned duration label (e.g. "850ms", "2s"); also set when live=true
- *   icon        — icon-ui name (replaces the dot when set)
- *   variant     — default | success | accent | warning | danger  (colors the dot/icon)
- *   completed   — boolean; renders "done" state
- *   active      — boolean; renders "active" state
- *   error       — boolean; renders "error" state (red dot)
- *   spinner     — boolean; spinning dot while active
- *
- * JS (item):
- *   .outcomes = string[]    // renders an expandable sub-list under the row
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-// ── Container ──────────────────────────────────────────────────
-
-class UITimeline extends UIElement {
-  static properties = {
-    orientation: { type: String, default: 'vertical', reflect: true },
-    size:        { type: String, default: 'md',       reflect: true },
-  };
-
-  static template = () => null;
-
-  render() {
-    const items = [...this.querySelectorAll(':scope > timeline-item-ui')];
-    for (const item of items) item.removeAttribute('data-last');
-    const last = items[items.length - 1];
-    if (last) last.setAttribute('data-last', '');
-  }
-}
-
-customElements.define('timeline-ui', UITimeline);
-
-// ── Item ───────────────────────────────────────────────────────
-
-class UITimelineItem extends UIElement {
-  static properties = {
-    text:        { type: String,  default: '',        reflect: true },
-    description: { type: String,  default: '',        reflect: true },
-    time:        { type: String,  default: '',        reflect: true },
-    duration:    { type: String,  default: '',        reflect: true },
-    icon:        { type: String,  default: '',        reflect: true },
-    variant:     { type: String,  default: 'default', reflect: true },
-    status:      { type: String,  default: 'idle',    reflect: true },
-    spinner:     { type: Boolean, default: false,     reflect: true },
-  };
-
-  static template = () => null;
-
-  #outcomes = [];
-  #expanded = false;
-
-  get outcomes() { return this.#outcomes; }
-  set outcomes(v) {
-    this.#outcomes = Array.isArray(v) ? v.slice() : [];
-    this.render();
-  }
-
-  connected() {
-    if (!this.querySelector(':scope > [slot="label"]')) {
-      // Author provided just text/time — stamp the default slot structure
-      this.innerHTML = `
-        <span slot="label"></span>
-        <span slot="description"></span>
-        <span slot="time"></span>
-      `;
-    }
-  }
-
-  render() {
-    const label = this.querySelector(':scope > [slot="label"]');
-    const desc  = this.querySelector(':scope > [slot="description"]');
-    const time  = this.querySelector(':scope > [slot="time"]');
-    if (label) label.textContent = this.text;
-    if (desc)  desc.textContent  = this.description;
-    if (time)  time.textContent  = this.duration || this.time;
-
-    if (this.icon) {
-      let iconEl = this.querySelector(':scope > [slot="icon"]');
-      if (!iconEl) {
-        iconEl = document.createElement('icon-ui');
-        iconEl.setAttribute('slot', 'icon');
-        this.prepend(iconEl);
-      }
-      iconEl.setAttribute('name', this.icon);
-    } else {
-      this.querySelector(':scope > [slot="icon"]')?.remove();
-    }
-
-    // Outcomes sub-list + toggle chevron
-    let body = this.querySelector(':scope > [slot="outcomes"]');
-    if (this.#outcomes.length > 0) {
-      if (!body) {
-        body = document.createElement('ul');
-        body.setAttribute('slot', 'outcomes');
-        this.appendChild(body);
-      }
-      body.innerHTML = '';
-      for (const o of this.#outcomes) {
-        const li = document.createElement('li');
-        li.textContent = o;
-        body.appendChild(li);
-      }
-      body.hidden = !this.#expanded;
-
-      // Toggle chevron lives on the row — we stamp a button once
-      let toggle = this.querySelector(':scope > [data-timeline-toggle]');
-      if (!toggle) {
-        toggle = document.createElement('button');
-        toggle.type = 'button';
-        toggle.setAttribute('data-timeline-toggle', '');
-        toggle.setAttribute('aria-label', 'Toggle details');
-        toggle.addEventListener('click', (e) => {
-          e.stopPropagation();
-          this.#expanded = !this.#expanded;
-          this.render();
-          this.dispatchEvent(new CustomEvent('timeline-toggle', {
-            bubbles: true, detail: { expanded: this.#expanded },
-          }));
-        });
-        this.appendChild(toggle);
-      }
-      toggle.innerHTML = '';
-      const caret = document.createElement('icon-ui');
-      caret.setAttribute('name', this.#expanded ? 'caret-down' : 'caret-right');
-      caret.setAttribute('color', 'muted');
-      caret.setAttribute('size', 'sm');
-      toggle.appendChild(caret);
-    } else {
-      this.querySelector(':scope > [data-timeline-toggle]')?.remove();
-      body?.remove();
-    }
-  }
-}
+import { defineIfFree } from '../../core/register.js';
+import { UITimeline, UITimelineItem } from './class.js';
 
-customElements.define('timeline-item-ui', UITimelineItem);
+defineIfFree('timeline-ui', UITimeline);
+defineIfFree('timeline-item-ui', UITimelineItem);
 
 export { UITimeline, UITimelineItem };

package/components/toast/class.js

@@ -0,0 +1,92 @@
+/**
+ * Non-side-effect class export for `<toast-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/toast`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <toast-ui> — Thin facade over `<feed-ui>` / `UIFeed.post()`.
+ *
+ * Phase 4 of `docs/specs/feed-channel.md` (SPEC-FEED-CHANNEL-001) —
+ * toast-ui no longer owns its own per-position container. Both
+ * declarative `<toast-ui>` and imperative `UIToast.show()` paths
+ * route through `UIFeed`. The element exists for back-compat:
+ * authoring `<toast-ui text="…">` still produces a feed item.
+ *
+ *     // Imperative API (delegates to UIFeed.post)
+ *     UIToast.show({ text: 'Saved!', variant: 'success' });
+ *
+ *     // Global event channel — same shape, same delegation.
+ *     window.dispatchEvent(new CustomEvent('toast', {
+ *       detail: { text: 'Saved!', variant: 'success' }
+ *     }));
+ *
+ *     // Declarative — auto-posts and removes self on connect.
+ *     <toast-ui text="Saved!" variant="success"></toast-ui>
+ *
+ * The legacy `[data-toast-container]` per-position-Map plumbing was
+ * retired in this migration; the lane infrastructure now lives in
+ * `<feed-ui>` (see ../feed/feed.js).
+ */
+
+import { UIElement, html } from '../../core/element.js';
+import { UIFeed } from '../feed/feed.js';
+
+export class UIToast extends UIElement {
+  static properties = {
+    text:     { type: String,  default: '', reflect: true },
+    variant:  { type: String,  default: 'info', reflect: true },
+    duration: { type: Number,  default: 4000, reflect: true },
+    position: { type: String,  default: 'bottom-right', reflect: true },
+  };
+
+  static template = () => html``;
+
+  connected() {
+    /* Declarative path: post into UIFeed and remove self. The
+       element is fire-and-forget — its only job is to forward the
+       authored attributes to the feed, then dissolve. Re-entrant
+       guard keeps this safe under HMR / dev-mode re-attachment. */
+    if (this.__routedToFeed) return;
+    this.__routedToFeed = true;
+    UIFeed.post({
+      text:     this.text,
+      variant:  this.variant === 'error' ? 'danger' : this.variant,
+      duration: this.duration,
+      position: this.position,
+    });
+    /* Schedule removal so the calling code can read the attributes
+       if it inspected this element on the same microtask. */
+    queueMicrotask(() => { try { this.remove(); } catch { /* noop */ } });
+  }
+
+  /**
+   * Static facade — delegates to UIFeed.post(). Kept for back-compat
+   * with consumer code shaped like `customElements.get('toast-ui').show(...)`
+   * or `UIToast.show(...)`. New code should call UIFeed.post()
+   * directly.
+   *
+   * @param {Object} opts
+   * @param {string} opts.text
+   * @param {string} [opts.variant='info']  — `error` aliases to `danger`.
+   * @param {number} [opts.duration=4000]
+   * @param {string} [opts.position='bottom-right']
+   * @returns {{id:string|null, dismiss:function, update:function}}  FeedHandle.
+   */
+  static show(opts = {}) {
+    const { text, variant = 'info', duration = 4000, position = 'bottom-right' } = opts;
+    return UIFeed.post({
+      text,
+      variant: variant === 'error' ? 'danger' : variant,
+      duration,
+      position,
+    });
+  }
+}

package/components/toast/toast.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `<toast-ui>` — Notification popup with auto-dismiss. Animated enter/exit.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/toast
+ *
+ * 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.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIToast extends UIElement {
+  /** Auto-dismiss time in milliseconds. 0 disables auto-dismiss. */
+  duration: number;
+  /** Screen position */
+  position: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+  /** Toast message text */
+  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';
+}

package/components/toast/toast.js

@@ -1,88 +1,23 @@
 /**
- * <toast-ui> — Thin facade over `<feed-ui>` / `UIFeed.post()`.
+ * `<toast-ui>` — auto-registers the tag on import.
  *
- * Phase 4 of `docs/specs/feed-channel.md` (SPEC-FEED-CHANNEL-001) —
- * toast-ui no longer owns its own per-position container. Both
- * declarative `<toast-ui>` and imperative `UIToast.show()` paths
- * route through `UIFeed`. The element exists for back-compat:
- * authoring `<toast-ui text="…">` still produces a feed item.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- *     // Imperative API (delegates to UIFeed.post)
- *     UIToast.show({ text: 'Saved!', variant: 'success' });
+ *   import { UIToast } from '@adia-ai/web-components/components/toast/class';
  *
- *     // Global event channel — same shape, same delegation.
- *     window.dispatchEvent(new CustomEvent('toast', {
- *       detail: { text: 'Saved!', variant: 'success' }
- *     }));
- *
- *     // Declarative — auto-posts and removes self on connect.
- *     <toast-ui text="Saved!" variant="success"></toast-ui>
- *
- * The legacy `[data-toast-container]` per-position-Map plumbing was
- * retired in this migration; the lane infrastructure now lives in
- * `<feed-ui>` (see ../feed/feed.js).
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement, html } from '../../core/element.js';
-import { UIFeed } from '../feed/feed.js';
-
-class UIToast extends UIElement {
-  static properties = {
-    text:     { type: String,  default: '', reflect: true },
-    variant:  { type: String,  default: 'info', reflect: true },
-    duration: { type: Number,  default: 4000, reflect: true },
-    position: { type: String,  default: 'bottom-right', reflect: true },
-  };
-
-  static template = () => html``;
+import { defineIfFree } from '../../core/register.js';
+import { UIToast } from './class.js';
 
-  connected() {
-    /* Declarative path: post into UIFeed and remove self. The
-       element is fire-and-forget — its only job is to forward the
-       authored attributes to the feed, then dissolve. Re-entrant
-       guard keeps this safe under HMR / dev-mode re-attachment. */
-    if (this.__routedToFeed) return;
-    this.__routedToFeed = true;
-    UIFeed.post({
-      text:     this.text,
-      variant:  this.variant === 'error' ? 'danger' : this.variant,
-      duration: this.duration,
-      position: this.position,
-    });
-    /* Schedule removal so the calling code can read the attributes
-       if it inspected this element on the same microtask. */
-    queueMicrotask(() => { try { this.remove(); } catch { /* noop */ } });
-  }
-
-  /**
-   * Static facade — delegates to UIFeed.post(). Kept for back-compat
-   * with consumer code shaped like `customElements.get('toast-ui').show(...)`
-   * or `UIToast.show(...)`. New code should call UIFeed.post()
-   * directly.
-   *
-   * @param {Object} opts
-   * @param {string} opts.text
-   * @param {string} [opts.variant='info']  — `error` aliases to `danger`.
-   * @param {number} [opts.duration=4000]
-   * @param {string} [opts.position='bottom-right']
-   * @returns {{id:string|null, dismiss:function, update:function}}  FeedHandle.
-   */
-  static show(opts = {}) {
-    const { text, variant = 'info', duration = 4000, position = 'bottom-right' } = opts;
-    return UIFeed.post({
-      text,
-      variant: variant === 'error' ? 'danger' : variant,
-      duration,
-      position,
-    });
-  }
-}
+defineIfFree('toast-ui', UIToast);
 
 /* Idempotent install of the global 'toast' CustomEvent listener.
    Same shape as the historical channel — code that posts via
    `window.dispatchEvent(new CustomEvent('toast', {detail:{…}}))`
-   keeps working. The listener delegates to UIToast.show(), which
-   delegates to UIFeed.post(). */
+   keeps working. Delegates to UIToast.show() → UIFeed.post(). */
 if (typeof window !== 'undefined' && !window.__adiaToastListenerInstalled) {
   window.__adiaToastListenerInstalled = true;
   window.addEventListener('toast', (e) => {
@@ -90,6 +25,4 @@ if (typeof window !== 'undefined' && !window.__adiaToastListenerInstalled) {
   });
 }
 
-customElements.define('toast-ui', UIToast);
-
 export { UIToast };