@adia-ai/web-components 0.4.6 → 0.4.7

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.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `<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 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 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/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.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `<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 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 UIStream extends UIElement {
+  /** Milliseconds between character renders. 0 = real-time. */
+  pace: number;
+  /** Read-only reflected state, true while stream is active */
+  streaming: boolean;
+}

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

package/components/swatch/class.js

@@ -0,0 +1,131 @@
+/**
+ * Non-side-effect class export for `<swatch-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/swatch`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <swatch-ui> — color / style sample primitive.
+ *
+ * A small inline tile representing one visual sample — a chart series's
+ * legend marker, a design-token step in a color or spacing scale, a
+ * theme-preview pill. Replaces docs-only `<span data-swatch>` usage and
+ * the per-shape CSS that used to live inside chart-legend-ui.
+ *
+ * Usage:
+ *   <swatch-ui shape="dot" color="var(--a-data-0)" label="Revenue"></swatch-ui>
+ *   <swatch-ui shape="block" size="lg" color="var(--a-neutral-50)" label="50"></swatch-ui>
+ *   <swatch-ui shape="line" color="#0ea5e9">Forecast</swatch-ui>
+ *
+ * Attributes:
+ *   shape  — block | dot | square | line | dashed (default square)
+ *   size   — sm | md | lg (default md). lg is the 40px-tall token-scale block.
+ *   color  — any CSS color (or var() ref). Sets --swatch-color internally.
+ *   label  — optional text label rendered beside / below the swatch
+ *
+ * Slots:
+ *   default — rich label content; takes precedence over [label] attr
+ *
+ * Stamping is light-DOM with two children:
+ *   <span data-tile></span>     — the colored shape
+ *   <span data-label></span>    — the label text (omitted when no label/slot)
+ */
+
+import { UIElement } from '../../core/element.js';
+
+const SHAPES = new Set(['block', 'dot', 'square', 'line', 'dashed']);
+const SIZES = new Set(['sm', 'md', 'lg']);
+
+export class UISwatch extends UIElement {
+  static properties = {
+    shape: { type: String, default: 'square', reflect: true },
+    size:  { type: String, default: 'md',     reflect: true },
+    color: { type: String, default: '',       reflect: true },
+    label: { type: String, default: '',       reflect: true },
+  };
+
+  static template = () => null;
+
+  #tileEl = null;
+  #labelEl = null;
+  #stamped = false;
+
+  connected() {
+    this.#stamp();
+  }
+
+  render() {
+    this.#stamp();
+    this.#sync();
+  }
+
+  #stamp() {
+    if (this.#stamped) return;
+    // Capture pre-existing default-slot content so consumer-authored
+    // children (e.g. <swatch-ui>Forecast</swatch-ui>) survive stamping.
+    const slotted = Array.from(this.childNodes).filter(n =>
+      !(n.nodeType === 1 && (n.dataset?.tile !== undefined || n.dataset?.label !== undefined))
+    );
+    this.innerHTML = '';
+
+    this.#tileEl = document.createElement('span');
+    this.#tileEl.setAttribute('data-tile', '');
+    this.#tileEl.setAttribute('aria-hidden', 'true');
+    this.appendChild(this.#tileEl);
+
+    this.#labelEl = document.createElement('span');
+    this.#labelEl.setAttribute('data-label', '');
+    if (slotted.length) {
+      for (const n of slotted) this.#labelEl.appendChild(n);
+    }
+    this.appendChild(this.#labelEl);
+
+    this.#stamped = true;
+  }
+
+  #sync() {
+    if (!this.#tileEl || !this.#labelEl) return;
+
+    // Normalize enum values; fall back silently when a consumer sets a typo.
+    const shape = SHAPES.has(this.shape) ? this.shape : 'square';
+    const size  = SIZES.has(this.size)   ? this.size  : 'md';
+    if (shape !== this.shape) this.setAttribute('shape', shape);
+    if (size  !== this.size)  this.setAttribute('size', size);
+
+    // Color: only write the inline custom property when [color] is set
+    // explicitly; otherwise leave whatever the consumer wrote via
+    // style="--swatch-color: …" alone.
+    if (this.color) {
+      this.style.setProperty('--swatch-color', this.color);
+    }
+
+    // Label: prefer slotted content (already in #labelEl from #stamp);
+    // when label-attr is set and the slot is empty, write the attribute.
+    if (!this.#labelEl.firstChild && this.label) {
+      this.#labelEl.textContent = this.label;
+    } else if (this.#labelEl.firstChild?.nodeType === 3 && this.label) {
+      // Pure-text node from a previous label-attr render — keep it
+      // synced to the current attr value.
+      this.#labelEl.textContent = this.label;
+    }
+
+    // Hide the label box when there's no content. Empty-but-stamped span
+    // would otherwise eat the layout gap.
+    const hasLabel = this.#labelEl.textContent.trim().length > 0
+      || (this.#labelEl.firstElementChild != null);
+    this.#labelEl.toggleAttribute('hidden', !hasLabel);
+  }
+
+  disconnected() {
+    this.#tileEl = null;
+    this.#labelEl = null;
+    this.#stamped = false;
+  }
+}

package/components/swatch/swatch.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `<swatch-ui>` — Color/style swatch primitive — a small inline tile representing a single
+visual sample. Renders as block, dot, square, line, or dashed depending on
+shape; pairs with an optional label slot or attribute. Composed by chart-
+legend-ui's per-row swatch and consumed directly by the token-colors /
+spacing demo pages.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/swatch
+ *
+ * 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 UISwatch extends UIElement {
+  /** Swatch color. Accepts any CSS color value or var() reference. Sets the internal --swatch-color custom property; consumers can also set --swatch-color via inline style. */
+  color: string;
+  /** Optional label rendered next to (or below, for shape="block") the swatch. Use the default slot for richer content. */
+  label: string;
+  /** Visual shape — block (filled tile), dot (small circle), square (small filled square), line (solid hairline), dashed (dashed hairline). */
+  shape: 'block' | 'dot' | 'square' | 'line' | 'dashed';
+  /** Size preset — sm / md / lg. Drives the swatch's intrinsic dimensions; lg is reserved for the token-scale demo (40 px tall). */
+  size: 'sm' | 'md' | 'lg';
+}