@adia-ai/web-components 0.4.6 → 0.4.7

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 };

package/components/toggle-group/class.js

@@ -0,0 +1,154 @@
+/**
+ * Non-side-effect class export for `<toggle-option-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/toggle-group`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <toggle-group-ui value="bold,italic">
+ *   <toggle-option-ui value="bold" icon="text-b"></toggle-option-ui>
+ *   <toggle-option-ui value="italic" icon="text-italic"></toggle-option-ui>
+ *   <toggle-option-ui value="underline" icon="text-underline"></toggle-option-ui>
+ * </toggle-group-ui>
+ *
+ * Multi-select button group (unlike segmented which is single-select).
+ *
+ * Properties:
+ *   value  — comma-separated selected values
+ *   single — restrict to one active option at a time (default false: multi-select)
+ */
+
+import { UIElement } from '../../core/element.js';
+
+// ── Toggle Option ──
+//
+// Parent-managed. Selection state flows through `toggle-group-ui`'s `value`
+// (and `single` mode flag). Items don't expose `checked` — parent applies
+// `data-selected` on the DOM element when the item's `value` is part of the
+// group's comma-separated `value` list. Consistent with native `<option>`
+// inside `<select>`.
+
+export class UIToggleOption extends UIElement {
+  static properties = {
+    value:    { type: String,  default: '', reflect: true },
+    text:     { type: String,  default: '', reflect: true },
+    icon:     { type: String,  default: '', reflect: true },
+    disabled: { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  #stamped = false;
+
+  connected() {
+    this.setAttribute('role', 'button');
+    this.setAttribute('tabindex', '0');
+  }
+
+  render() {
+    if (!this.#stamped) {
+      this.#stamped = true;
+      this.#stamp();
+    }
+    if (this.disabled) this.setAttribute('aria-disabled', 'true');
+    else this.removeAttribute('aria-disabled');
+  }
+
+  #stamp() {
+    let inner = '';
+    if (this.icon) inner += `<icon-ui name="${this.icon}"></icon-ui>`;
+    if (this.text) inner += `<span data-text>${this.text}</span>`;
+    this.innerHTML = inner;
+  }
+
+  disconnected() {
+    this.#stamped = false;
+  }
+}
+
+export class UIToggleGroup extends UIElement {
+  static properties = {
+    value:  { type: String,  default: '',    reflect: true },
+    single: { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  #bound = false;
+
+  get #valueSet() {
+    return new Set(this.value ? this.value.split(',').map(v => v.trim()).filter(Boolean) : []);
+  }
+
+  connected() {
+    if (!this.#bound) {
+      this.#bound = true;
+      this.addEventListener('click', this.#onClick);
+      this.addEventListener('keydown', this.#onKey);
+    }
+    this.setAttribute('role', 'group');
+  }
+
+  render() {
+    const selected = this.#valueSet;
+    for (const opt of this.querySelectorAll('toggle-option-ui')) {
+      const optVal = opt.value || opt.getAttribute('value') || '';
+      if (selected.has(optVal)) {
+        opt.setAttribute('data-selected', '');
+        opt.setAttribute('aria-pressed', 'true');
+      } else {
+        opt.removeAttribute('data-selected');
+        opt.setAttribute('aria-pressed', 'false');
+      }
+    }
+  }
+
+  #toggle(opt) {
+    if (opt.disabled) return;
+    const optVal = opt.value || opt.getAttribute('value') || '';
+    if (!optVal) return;
+
+    const selected = this.#valueSet;
+
+    if (this.single) {
+      if (selected.has(optVal)) {
+        selected.clear();
+      } else {
+        selected.clear();
+        selected.add(optVal);
+      }
+    } else {
+      if (selected.has(optVal)) selected.delete(optVal);
+      else selected.add(optVal);
+    }
+
+    this.value = [...selected].join(',');
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+  }
+
+  #onClick = (e) => {
+    const opt = e.target.closest('toggle-option-ui');
+    if (opt && this.contains(opt)) this.#toggle(opt);
+  };
+
+  #onKey = (e) => {
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      const opt = e.target.closest('toggle-option-ui');
+      if (opt && this.contains(opt)) this.#toggle(opt);
+    }
+  };
+
+  disconnected() {
+    this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('keydown', this.#onKey);
+    this.#bound = false;
+  }
+}

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

@@ -0,0 +1,19 @@
+/**
+ * `<toggle-group-ui>` — Multi-select button group (unlike segmented which is single-select).
+ *
+ * @see https://ui-kit.exe.xyz/site/components/toggle-group
+ *
+ * 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 UIToggleGroup extends UIElement {
+  /** When true, restrict to one active option (single-select). */
+  single: boolean;
+  /** Comma-separated selected values */
+  value: string;
+}