@adia-ai/web-components 0.4.6 → 0.4.8

package/components/step-progress/step-progress.js

@@ -1,88 +1,17 @@
 /**
- * <step-progress-ui value="3" total="10" caption="Step 3 of 10"></step-progress-ui>
- * <step-progress-ui value="3" total="10"></step-progress-ui>            <!-- no caption -->
- * <step-progress-ui value="10" total="10" caption="All steps complete"></step-progress-ui>
+ * `<step-progress-ui>` — auto-registers the tag on import.
  *
- * Discrete-dash step progress indicator. One dash per step in the
- * total; the first `value` dashes carry [data-active] and paint with
- * --a-accent. Used in registration + onboarding flows; replaces the
- * bespoke `[data-onb-progress]` / `[data-reg-progress]` markup.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Primitive shape (per ROADMAP § Done):
- *   `<step-progress-ui value="N" total="M" caption="...">`
+ *   import { UIStepProgress } from '@adia-ai/web-components/components/step-progress/class';
  *
- * Caption is optional; pass via attribute. Free-form text passes
- * straight through; `<text-ui>` styling can be replicated with
- * default-slot HTML if needed (the auto-mint uses plain text).
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+import { UIStepProgress } from './class.js';
 
-class UIStepProgress extends UIElement {
-  static properties = {
-    value:   { type: Number, default: 0,  reflect: true },
-    total:   { type: Number, default: 0,  reflect: true },
-    caption: { type: String, default: '', reflect: true },
-  };
+defineIfFree('step-progress-ui', UIStepProgress);
 
-  static template = () => null;
-
-  #captionEl = null;
-  #trackEl = null;
-
-  connected() {
-    this.setAttribute('role', 'progressbar');
-    this.setAttribute('aria-valuemin', '0');
-
-    // Auto-mint internal structure if the consumer didn't provide custom slots.
-    if (!this.querySelector(':scope > [slot="caption"]') && !this.querySelector(':scope > [slot="track"]')) {
-      this.#captionEl = document.createElement('span');
-      this.#captionEl.setAttribute('slot', 'caption');
-      this.appendChild(this.#captionEl);
-
-      this.#trackEl = document.createElement('div');
-      this.#trackEl.setAttribute('slot', 'track');
-      this.appendChild(this.#trackEl);
-    } else {
-      this.#captionEl = this.querySelector(':scope > [slot="caption"]');
-      this.#trackEl = this.querySelector(':scope > [slot="track"]');
-    }
-  }
-
-  render() {
-    const total = Math.max(0, this.total | 0);
-    const clamped = Math.max(0, Math.min(total, this.value | 0));
-
-    this.setAttribute('aria-valuemax', String(total));
-    this.setAttribute('aria-valuenow', String(clamped));
-
-    // Caption — text content if attribute set; cleared otherwise.
-    // Skip if the consumer passed in a custom caption slot (preserve their content).
-    if (this.#captionEl && !this.#captionEl.dataset.custom) {
-      this.#captionEl.textContent = this.caption || '';
-      this.#captionEl.toggleAttribute('hidden', !this.caption);
-    }
-
-    // Track — sync span count with `total`; mark first `value` as active.
-    if (this.#trackEl) {
-      const existing = this.#trackEl.children.length;
-      while (this.#trackEl.children.length < total) {
-        this.#trackEl.appendChild(document.createElement('span'));
-      }
-      while (this.#trackEl.children.length > total) {
-        this.#trackEl.lastElementChild.remove();
-      }
-      for (let i = 0; i < this.#trackEl.children.length; i++) {
-        this.#trackEl.children[i].toggleAttribute('data-active', i < clamped);
-      }
-    }
-  }
-
-  disconnected() {
-    this.#captionEl = null;
-    this.#trackEl = null;
-  }
-}
-
-customElements.define('step-progress-ui', UIStepProgress);
 export { UIStepProgress };

package/components/stepper/class.js

@@ -0,0 +1,126 @@
+/**
+ * Non-side-effect class export for `<stepper-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/stepper`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <stepper-ui> — Wizard / process stepper.
+ *
+ * Split out of the old <timeline-ui mode="steps">. Where timeline-ui is for
+ * event/progress logs with per-item state, stepper-ui is a wizard: the parent
+ * `step` index drives all children (numbered circles, auto-checkmark on the
+ * ones before it, active ring on the current).
+ *
+ * Usage:
+ *   <stepper-ui step="1">
+ *     <stepper-item-ui text="Account"></stepper-item-ui>
+ *     <stepper-item-ui text="Details"></stepper-item-ui>
+ *     <stepper-item-ui text="Review"></stepper-item-ui>
+ *   </stepper-ui>
+ *
+ *   el.next(); el.prev(); el.goTo(2);
+ *
+ * Attributes:
+ *   step        — current step index (0-based)
+ *   orientation — horizontal (default) | vertical
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIStepper extends UIElement {
+  static properties = {
+    step:        { type: Number, default: 0,            reflect: true },
+    orientation: { type: String, default: 'horizontal', reflect: true },
+  };
+
+  static template = () => null;
+
+  render() {
+    const items = [...this.querySelectorAll('stepper-item-ui')];
+
+    // Mark last item — the connector line hides on the last one
+    for (const item of items) item.removeAttribute('data-last');
+    const last = items[items.length - 1];
+    if (last) last.setAttribute('data-last', '');
+
+    // Parent drives child state via step index. Canonical Phase 6
+    // contract: `status` enum (`completed` / `active` / `idle`).
+    // CSS only matches `[status="…"]`; the legacy `[completed]` /
+    // `[active]` Booleans were removed in 0.0.20.
+    items.forEach((item, i) => {
+      item.setAttribute('data-index', i);
+      if (i < this.step) {
+        item.setAttribute('status', 'completed');
+      } else if (i === this.step) {
+        item.setAttribute('status', 'active');
+      } else {
+        item.setAttribute('status', 'idle');
+      }
+    });
+  }
+
+  next() {
+    const count = this.querySelectorAll('stepper-item-ui').length;
+    if (this.step < count - 1) this.step++;
+  }
+
+  prev() {
+    if (this.step > 0) this.step--;
+  }
+
+  goTo(index) {
+    const max = this.querySelectorAll('stepper-item-ui').length - 1;
+    this.step = Math.max(0, Math.min(index, max));
+  }
+}
+
+export class UIStepperItem extends UIElement {
+  static properties = {
+    text:        { type: String,  default: '', reflect: true },
+    description: { type: String,  default: '', reflect: true },
+    icon:        { type: String,  default: '', reflect: true },
+    // `status` is the canonical stage-progress shape across timeline-item,
+    // stepper-item, pipeline-status, agent-reasoning. Mutually exclusive
+    // values prevent the `active && completed` footgun the prior multi-
+    // Boolean shape allowed.
+    status:      { type: String,  default: 'idle', reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    if (!this.querySelector('[slot="label"]')) {
+      this.innerHTML = `
+        <span slot="label"></span>
+        <span slot="description"></span>
+      `;
+    }
+  }
+
+  render() {
+    const label = this.querySelector('[slot="label"]');
+    const desc = this.querySelector('[slot="description"]');
+    if (label) label.textContent = this.text;
+    if (desc) desc.textContent = this.description;
+
+    if (this.icon) {
+      let iconEl = this.querySelector('[slot="icon"]');
+      if (!iconEl) {
+        iconEl = document.createElement('icon-ui');
+        iconEl.setAttribute('slot', 'icon');
+        this.prepend(iconEl);
+      }
+      iconEl.setAttribute('name', this.icon);
+    } else {
+      this.querySelector('[slot="icon"]')?.remove();
+    }
+  }
+}

package/components/stepper/stepper.a2ui.json

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

package/components/stepper/stepper.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `<stepper-ui>` — Wizard / process stepper — parent step index drives numbered children.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/stepper
+ *
+ * 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 UIStepper extends UIElement {
+  /** horizontal | vertical */
+  orientation: string;
+  /** Current step index (0-based). */
+  step: number;
+}

package/components/stepper/stepper.js

@@ -1,121 +1,18 @@
 /**
- * <stepper-ui> — Wizard / process stepper.
+ * `<stepper-ui>` — auto-registers the tag on import.
  *
- * Split out of the old <timeline-ui mode="steps">. Where timeline-ui is for
- * event/progress logs with per-item state, stepper-ui is a wizard: the parent
- * `step` index drives all children (numbered circles, auto-checkmark on the
- * ones before it, active ring on the current).
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Usage:
- *   <stepper-ui step="1">
- *     <stepper-item-ui text="Account"></stepper-item-ui>
- *     <stepper-item-ui text="Details"></stepper-item-ui>
- *     <stepper-item-ui text="Review"></stepper-item-ui>
- *   </stepper-ui>
+ *   import { UIStepper, UIStepperItem } from '@adia-ai/web-components/components/stepper/class';
  *
- *   el.next(); el.prev(); el.goTo(2);
- *
- * Attributes:
- *   step        — current step index (0-based)
- *   orientation — horizontal (default) | vertical
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIStepper extends UIElement {
-  static properties = {
-    step:        { type: Number, default: 0,            reflect: true },
-    orientation: { type: String, default: 'horizontal', reflect: true },
-  };
-
-  static template = () => null;
-
-  render() {
-    const items = [...this.querySelectorAll('stepper-item-ui')];
-
-    // Mark last item — the connector line hides on the last one
-    for (const item of items) item.removeAttribute('data-last');
-    const last = items[items.length - 1];
-    if (last) last.setAttribute('data-last', '');
-
-    // Parent drives child state via step index. Canonical Phase 6
-    // contract: `status` enum (`completed` / `active` / `idle`).
-    // CSS only matches `[status="…"]`; the legacy `[completed]` /
-    // `[active]` Booleans were removed in 0.0.20.
-    items.forEach((item, i) => {
-      item.setAttribute('data-index', i);
-      if (i < this.step) {
-        item.setAttribute('status', 'completed');
-      } else if (i === this.step) {
-        item.setAttribute('status', 'active');
-      } else {
-        item.setAttribute('status', 'idle');
-      }
-    });
-  }
-
-  next() {
-    const count = this.querySelectorAll('stepper-item-ui').length;
-    if (this.step < count - 1) this.step++;
-  }
-
-  prev() {
-    if (this.step > 0) this.step--;
-  }
-
-  goTo(index) {
-    const max = this.querySelectorAll('stepper-item-ui').length - 1;
-    this.step = Math.max(0, Math.min(index, max));
-  }
-}
-
-customElements.define('stepper-ui', UIStepper);
-
-// ── Item ───────────────────────────────────────────────────────
-
-class UIStepperItem extends UIElement {
-  static properties = {
-    text:        { type: String,  default: '', reflect: true },
-    description: { type: String,  default: '', reflect: true },
-    icon:        { type: String,  default: '', reflect: true },
-    // `status` is the canonical stage-progress shape across timeline-item,
-    // stepper-item, pipeline-status, agent-reasoning. Mutually exclusive
-    // values prevent the `active && completed` footgun the prior multi-
-    // Boolean shape allowed.
-    status:      { type: String,  default: 'idle', reflect: true },
-  };
-
-  static template = () => null;
-
-  connected() {
-    if (!this.querySelector('[slot="label"]')) {
-      this.innerHTML = `
-        <span slot="label"></span>
-        <span slot="description"></span>
-      `;
-    }
-  }
-
-  render() {
-    const label = this.querySelector('[slot="label"]');
-    const desc = this.querySelector('[slot="description"]');
-    if (label) label.textContent = this.text;
-    if (desc) desc.textContent = this.description;
-
-    if (this.icon) {
-      let iconEl = this.querySelector('[slot="icon"]');
-      if (!iconEl) {
-        iconEl = document.createElement('icon-ui');
-        iconEl.setAttribute('slot', 'icon');
-        this.prepend(iconEl);
-      }
-      iconEl.setAttribute('name', this.icon);
-    } else {
-      this.querySelector('[slot="icon"]')?.remove();
-    }
-  }
-}
+import { defineIfFree } from '../../core/register.js';
+import { UIStepper, UIStepperItem } from './class.js';
 
-customElements.define('stepper-item-ui', UIStepperItem);
+defineIfFree('stepper-ui', UIStepper);
+defineIfFree('stepper-item-ui', UIStepperItem);
 
 export { UIStepper, UIStepperItem };

package/components/stepper/stepper.yaml

@@ -7,6 +7,10 @@ component: Stepper
 category: navigation
 version: 1
 description: Wizard / process stepper — parent step index drives numbered children.
+# 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:
   orientation:
     description: horizontal | vertical

package/components/stream/class.js

@@ -0,0 +1,109 @@
+/**
+ * Non-side-effect class export for `<stream-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/stream`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <stream-ui></stream-ui>
+ * el.tokens = asyncIterable; // starts streaming
+ *
+ * Renders an AsyncIterable<string> as streaming text.
+ * Used for agent prose, LLM output, real-time logs.
+ *
+ * Props (attributes):
+ *   pace:        ms between character renders (default: 0, real-time)
+ *   hide-cursor: hide the blinking cursor during stream (default: false — cursor visible)
+ *
+ * Props (JS only):
+ *   .tokens: AsyncIterable<string> — the stream source
+ *
+ * Events:
+ *   stream-start  — streaming begins
+ *   stream-end    — stream completed
+ *   stream-error  — stream error (detail: { error })
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIStream extends UIElement {
+  static properties = {
+    pace:       { type: Number,  default: 0,     reflect: true },
+    hideCursor: { type: Boolean, default: false, reflect: true, attribute: 'hide-cursor' },
+    streaming:  { type: Boolean, default: false, reflect: true },
+  };
+
+  #tokens = null;
+  #abortCtrl = null;
+  #buffer = '';
+
+  get tokens() { return this.#tokens; }
+  set tokens(iterable) {
+    this.#tokens = iterable;
+    if (iterable) this.#startStream(iterable);
+  }
+
+  static template = () => null;
+
+  async #startStream(iterable) {
+    this.#abortCtrl?.abort();
+    this.#abortCtrl = new AbortController();
+    const signal = this.#abortCtrl.signal;
+
+    this.#buffer = '';
+    this.textContent = '';
+    this.streaming = true;
+    this.dispatchEvent(new Event('stream-start', { bubbles: true }));
+
+    try {
+      for await (const token of iterable) {
+        if (signal.aborted) break;
+        this.#buffer += token;
+
+        if (this.pace > 0) {
+          for (const char of token) {
+            if (signal.aborted) break;
+            this.textContent += char;
+            await new Promise(r => setTimeout(r, this.pace));
+          }
+        } else {
+          this.textContent = this.#buffer;
+        }
+      }
+    } catch (err) {
+      if (!signal.aborted) {
+        this.dispatchEvent(new CustomEvent('stream-error', {
+          bubbles: true,
+          detail: { error: err },
+        }));
+      }
+    }
+
+    if (!signal.aborted) {
+      this.streaming = false;
+      this.dispatchEvent(new Event('stream-end', { bubbles: true }));
+    }
+  }
+
+  stop() {
+    this.#abortCtrl?.abort();
+    this.streaming = false;
+  }
+
+  clear() {
+    this.stop();
+    this.#buffer = '';
+    this.textContent = '';
+  }
+
+  disconnected() {
+    this.stop();
+  }
+}

package/components/stream/stream.a2ui.json

@@ -39,6 +39,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [],
     "events": {
       "stream-end": {
         "description": "Fired when stream completes naturally"

package/components/stream/stream.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `<stream-ui>` — Renders an AsyncIterable<string> as streaming text. Used for LLM output and real-time logs.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/stream
+ *
+ * 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 StreamEndEvent = CustomEvent<unknown>;
+export type StreamErrorEvent = CustomEvent<unknown>;
+export type StreamStartEvent = CustomEvent<unknown>;
+
+export class UIStream extends UIElement {
+  /** Milliseconds between character renders. 0 = real-time. */
+  pace: number;
+  /** Read-only reflected state, true while stream is active */
+  streaming: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIStream, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'stream-end', listener: (ev: StreamEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'stream-error', listener: (ev: StreamErrorEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'stream-start', listener: (ev: StreamStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/stream/stream.js

@@ -1,99 +1,17 @@
 /**
- * <stream-ui></stream-ui>
- * el.tokens = asyncIterable; // starts streaming
+ * `<stream-ui>` — auto-registers the tag on import.
  *
- * Renders an AsyncIterable<string> as streaming text.
- * Used for agent prose, LLM output, real-time logs.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Props (attributes):
- *   pace:        ms between character renders (default: 0, real-time)
- *   hide-cursor: hide the blinking cursor during stream (default: false — cursor visible)
+ *   import { UIStream } from '@adia-ai/web-components/components/stream/class';
  *
- * Props (JS only):
- *   .tokens: AsyncIterable<string> — the stream source
- *
- * Events:
- *   stream-start  — streaming begins
- *   stream-end    — stream completed
- *   stream-error  — stream error (detail: { error })
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIStream extends UIElement {
-  static properties = {
-    pace:       { type: Number,  default: 0,     reflect: true },
-    hideCursor: { type: Boolean, default: false, reflect: true, attribute: 'hide-cursor' },
-    streaming:  { type: Boolean, default: false, reflect: true },
-  };
-
-  #tokens = null;
-  #abortCtrl = null;
-  #buffer = '';
-
-  get tokens() { return this.#tokens; }
-  set tokens(iterable) {
-    this.#tokens = iterable;
-    if (iterable) this.#startStream(iterable);
-  }
-
-  static template = () => null;
-
-  async #startStream(iterable) {
-    this.#abortCtrl?.abort();
-    this.#abortCtrl = new AbortController();
-    const signal = this.#abortCtrl.signal;
-
-    this.#buffer = '';
-    this.textContent = '';
-    this.streaming = true;
-    this.dispatchEvent(new Event('stream-start', { bubbles: true }));
-
-    try {
-      for await (const token of iterable) {
-        if (signal.aborted) break;
-        this.#buffer += token;
-
-        if (this.pace > 0) {
-          for (const char of token) {
-            if (signal.aborted) break;
-            this.textContent += char;
-            await new Promise(r => setTimeout(r, this.pace));
-          }
-        } else {
-          this.textContent = this.#buffer;
-        }
-      }
-    } catch (err) {
-      if (!signal.aborted) {
-        this.dispatchEvent(new CustomEvent('stream-error', {
-          bubbles: true,
-          detail: { error: err },
-        }));
-      }
-    }
-
-    if (!signal.aborted) {
-      this.streaming = false;
-      this.dispatchEvent(new Event('stream-end', { bubbles: true }));
-    }
-  }
-
-  stop() {
-    this.#abortCtrl?.abort();
-    this.streaming = false;
-  }
-
-  clear() {
-    this.stop();
-    this.#buffer = '';
-    this.textContent = '';
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIStream } from './class.js';
 
-  disconnected() {
-    this.stop();
-  }
-}
-customElements.define('stream-ui', UIStream);
+defineIfFree('stream-ui', UIStream);
 
 export { UIStream };