@adia-ai/web-components 0.4.5 → 0.4.7

package/components/slider/class.js

@@ -0,0 +1,184 @@
+/**
+ * Non-side-effect class export for `<slider-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/slider`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <slider-ui label="Width" value="63" min="0" max="200" step="1" suffix="rem"></slider-ui>
+ *
+ * Layout:
+ *   [label]                                  [value] [suffix]
+ *   [=====fill=====●─────────────────track───────────────────]
+ *
+ * The `label` attribute renders as a first-class in-component caption in
+ * the slider header and is mirrored to `aria-label` on the host for
+ * screen-reader announcement. Wrap in `<field-ui>` only when you need
+ * external label-row composition (hint, error, action slot, etc.).
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+export class UISlider extends UIFormElement {
+  // Opt out of UIFormElement's per-control `label` deprecation warning.
+  // slider-ui's `label` is a first-class API rendering as the in-header
+  // caption next to the value, with `aria-label` wired on the host for
+  // a11y. Same opt-out rationale as input-ui and range-ui.
+  static labelDeprecated = false;
+
+  static properties = {
+    ...UIFormElement.properties,
+    /** value: Number — overrides UIFormElement.value (String); syncs as string on form submit. */
+    value:  { type: Number,  default: 50, reflect: true },
+    min:    { type: Number,  default: 0,  reflect: true },
+    max:    { type: Number,  default: 100, reflect: true },
+    step:   { type: Number,  default: 1,  reflect: true },
+    label:  { type: String,  default: '', reflect: true },
+    suffix: { type: String,  default: '', reflect: true },
+  };
+
+  static template = () => null;
+
+  #trackEl = null;
+  #thumbEl = null;
+  #dragging = false;
+
+  get #pct() {
+    const range = this.max - this.min;
+    return range > 0 ? ((this.value - this.min) / range) * 100 : 0;
+  }
+
+  #format(v) {
+    const decimals = (String(this.step).split('.')[1] || '').length;
+    return decimals > 0 ? v.toFixed(decimals) : String(v);
+  }
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'slider');
+    this.setAttribute('tabindex', '0');
+    this.setAttribute('aria-valuemin', this.min);
+    this.setAttribute('aria-valuemax', this.max);
+    if (this.label) this.setAttribute('aria-label', this.label);
+
+    if (!this.querySelector('[slot="track"]')) {
+      this.innerHTML = `
+        <div slot="header">
+          ${this.label ? `<span slot="label">${this.label}</span>` : ''}
+          <span slot="readout">
+            <span slot="value">${this.#format(this.value)}</span>
+            ${this.suffix ? `<span slot="suffix">${this.suffix}</span>` : ''}
+          </span>
+        </div>
+        <div slot="track">
+          <div slot="fill"></div>
+          <div slot="thumb" tabindex="0"></div>
+        </div>
+      `;
+    }
+
+    this.#trackEl = this.querySelector('[slot="track"]');
+    this.#thumbEl = this.querySelector('[slot="thumb"]');
+
+    if (this.#thumbEl) this.#thumbEl.addEventListener('pointerdown', this.#onPointerDown);
+    if (this.#trackEl) this.#trackEl.addEventListener('click', this.#onTrackClick);
+    this.addEventListener('keydown', this.#onKey);
+  }
+
+  render() {
+    if (!this.#trackEl) return;
+
+    const pct = this.#pct;
+    const fill = this.querySelector('[slot="fill"]');
+    if (fill) fill.style.width = `${pct}%`;
+    if (this.#thumbEl) this.#thumbEl.style.left = `${pct}%`;
+
+    const valueEl = this.querySelector('[slot="value"]');
+    if (valueEl) valueEl.textContent = this.#format(this.value);
+
+    this.setAttribute('aria-valuenow', this.value);
+    this.setAttribute('aria-valuetext', `${this.#format(this.value)}${this.suffix ? ' ' + this.suffix : ''}`);
+    this.syncValue(String(this.value));
+  }
+
+  #valueFromX(clientX) {
+    const rect = this.#trackEl.getBoundingClientRect();
+    const ratio = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+    const raw = this.min + ratio * (this.max - this.min);
+    return this.#snap(raw);
+  }
+
+  #snap(raw) {
+    const stepped = Math.round((raw - this.min) / this.step) * this.step + this.min;
+    return Math.max(this.min, Math.min(this.max, parseFloat(stepped.toFixed(10))));
+  }
+
+  #setValue(v) {
+    if (v === this.value) return;
+    this.value = v;
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+  }
+
+  #onPointerDown = (e) => {
+    if (this.disabled) return;
+    e.preventDefault();
+    this.#dragging = true;
+    this.#thumbEl.setPointerCapture(e.pointerId);
+    this.#thumbEl.addEventListener('pointermove', this.#onPointerMove);
+    this.#thumbEl.addEventListener('pointerup', this.#onPointerUp);
+  };
+
+  #onPointerMove = (e) => {
+    if (!this.#dragging) return;
+    this.#setValue(this.#valueFromX(e.clientX));
+  };
+
+  #onPointerUp = (e) => {
+    this.#dragging = false;
+    this.#thumbEl.releasePointerCapture(e.pointerId);
+    this.#thumbEl.removeEventListener('pointermove', this.#onPointerMove);
+    this.#thumbEl.removeEventListener('pointerup', this.#onPointerUp);
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+  };
+
+  #onTrackClick = (e) => {
+    if (this.disabled || e.target === this.#thumbEl) return;
+    this.#setValue(this.#valueFromX(e.clientX));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+  };
+
+  #onKey = (e) => {
+    if (this.disabled) return;
+    let v = this.value;
+    switch (e.key) {
+      case 'ArrowRight': case 'ArrowUp':   v += this.step; break;
+      case 'ArrowLeft':  case 'ArrowDown': v -= this.step; break;
+      case 'Home': v = this.min; break;
+      case 'End':  v = this.max; break;
+      case 'PageUp':   v += this.step * 10; break;
+      case 'PageDown': v -= this.step * 10; break;
+      default: return;
+    }
+    e.preventDefault();
+    this.#setValue(this.#snap(v));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+  };
+
+  disconnected() {
+    super.disconnected();
+    this.#thumbEl?.removeEventListener('pointerdown', this.#onPointerDown);
+    this.#trackEl?.removeEventListener('click', this.#onTrackClick);
+    this.#thumbEl?.removeEventListener('pointermove', this.#onPointerMove);
+    this.#thumbEl?.removeEventListener('pointerup', this.#onPointerUp);
+    this.removeEventListener('keydown', this.#onKey);
+    this.#trackEl = null;
+    this.#thumbEl = null;
+  }
+}

package/components/slider/slider.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `<slider-ui>` — Single-handle slider for numeric input.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/slider
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+export interface SliderChangeEventDetail {
+  value: number;
+}
+export type SliderChangeEvent = CustomEvent<SliderChangeEventDetail>;
+export type SliderInputEvent = CustomEvent<SliderChangeEventDetail>;
+
+export class UISlider extends UIFormElement {
+  /** Numeric value — overrides UIFormElement.value (which is String). */
+  value: number;
+  min: number;
+  max: number;
+  step: number;
+  label: string;
+  suffix: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UISlider, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: SliderChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: SliderInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/slider/slider.js

@@ -1,174 +1,17 @@
 /**
- * <slider-ui label="Width" value="63" min="0" max="200" step="1" suffix="rem"></slider-ui>
+ * `<slider-ui>` — auto-registers the tag on import.
  *
- * Layout:
- *   [label]                                  [value] [suffix]
- *   [=====fill=====●─────────────────track───────────────────]
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * The `label` attribute renders as a first-class in-component caption in
- * the slider header and is mirrored to `aria-label` on the host for
- * screen-reader announcement. Wrap in `<field-ui>` only when you need
- * external label-row composition (hint, error, action slot, etc.).
+ *   import { UISlider } from '@adia-ai/web-components/components/slider/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIFormElement } from '../../core/form.js';
-
-class UISlider extends UIFormElement {
-  // Opt out of UIFormElement's per-control `label` deprecation warning.
-  // slider-ui's `label` is a first-class API rendering as the in-header
-  // caption next to the value, with `aria-label` wired on the host for
-  // a11y. Same opt-out rationale as input-ui and range-ui.
-  static labelDeprecated = false;
-
-  static properties = {
-    ...UIFormElement.properties,
-    /** value: Number — overrides UIFormElement.value (String); syncs as string on form submit. */
-    value:  { type: Number,  default: 50, reflect: true },
-    min:    { type: Number,  default: 0,  reflect: true },
-    max:    { type: Number,  default: 100, reflect: true },
-    step:   { type: Number,  default: 1,  reflect: true },
-    label:  { type: String,  default: '', reflect: true },
-    suffix: { type: String,  default: '', reflect: true },
-  };
-
-  static template = () => null;
-
-  #trackEl = null;
-  #thumbEl = null;
-  #dragging = false;
-
-  get #pct() {
-    const range = this.max - this.min;
-    return range > 0 ? ((this.value - this.min) / range) * 100 : 0;
-  }
-
-  #format(v) {
-    const decimals = (String(this.step).split('.')[1] || '').length;
-    return decimals > 0 ? v.toFixed(decimals) : String(v);
-  }
-
-  connected() {
-    super.connected();
-    this.setAttribute('role', 'slider');
-    this.setAttribute('tabindex', '0');
-    this.setAttribute('aria-valuemin', this.min);
-    this.setAttribute('aria-valuemax', this.max);
-    if (this.label) this.setAttribute('aria-label', this.label);
-
-    if (!this.querySelector('[slot="track"]')) {
-      this.innerHTML = `
-        <div slot="header">
-          ${this.label ? `<span slot="label">${this.label}</span>` : ''}
-          <span slot="readout">
-            <span slot="value">${this.#format(this.value)}</span>
-            ${this.suffix ? `<span slot="suffix">${this.suffix}</span>` : ''}
-          </span>
-        </div>
-        <div slot="track">
-          <div slot="fill"></div>
-          <div slot="thumb" tabindex="0"></div>
-        </div>
-      `;
-    }
-
-    this.#trackEl = this.querySelector('[slot="track"]');
-    this.#thumbEl = this.querySelector('[slot="thumb"]');
-
-    if (this.#thumbEl) this.#thumbEl.addEventListener('pointerdown', this.#onPointerDown);
-    if (this.#trackEl) this.#trackEl.addEventListener('click', this.#onTrackClick);
-    this.addEventListener('keydown', this.#onKey);
-  }
-
-  render() {
-    if (!this.#trackEl) return;
-
-    const pct = this.#pct;
-    const fill = this.querySelector('[slot="fill"]');
-    if (fill) fill.style.width = `${pct}%`;
-    if (this.#thumbEl) this.#thumbEl.style.left = `${pct}%`;
-
-    const valueEl = this.querySelector('[slot="value"]');
-    if (valueEl) valueEl.textContent = this.#format(this.value);
-
-    this.setAttribute('aria-valuenow', this.value);
-    this.setAttribute('aria-valuetext', `${this.#format(this.value)}${this.suffix ? ' ' + this.suffix : ''}`);
-    this.syncValue(String(this.value));
-  }
-
-  #valueFromX(clientX) {
-    const rect = this.#trackEl.getBoundingClientRect();
-    const ratio = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
-    const raw = this.min + ratio * (this.max - this.min);
-    return this.#snap(raw);
-  }
-
-  #snap(raw) {
-    const stepped = Math.round((raw - this.min) / this.step) * this.step + this.min;
-    return Math.max(this.min, Math.min(this.max, parseFloat(stepped.toFixed(10))));
-  }
-
-  #setValue(v) {
-    if (v === this.value) return;
-    this.value = v;
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-  }
-
-  #onPointerDown = (e) => {
-    if (this.disabled) return;
-    e.preventDefault();
-    this.#dragging = true;
-    this.#thumbEl.setPointerCapture(e.pointerId);
-    this.#thumbEl.addEventListener('pointermove', this.#onPointerMove);
-    this.#thumbEl.addEventListener('pointerup', this.#onPointerUp);
-  };
-
-  #onPointerMove = (e) => {
-    if (!this.#dragging) return;
-    this.#setValue(this.#valueFromX(e.clientX));
-  };
-
-  #onPointerUp = (e) => {
-    this.#dragging = false;
-    this.#thumbEl.releasePointerCapture(e.pointerId);
-    this.#thumbEl.removeEventListener('pointermove', this.#onPointerMove);
-    this.#thumbEl.removeEventListener('pointerup', this.#onPointerUp);
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-  };
-
-  #onTrackClick = (e) => {
-    if (this.disabled || e.target === this.#thumbEl) return;
-    this.#setValue(this.#valueFromX(e.clientX));
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-  };
-
-  #onKey = (e) => {
-    if (this.disabled) return;
-    let v = this.value;
-    switch (e.key) {
-      case 'ArrowRight': case 'ArrowUp':   v += this.step; break;
-      case 'ArrowLeft':  case 'ArrowDown': v -= this.step; break;
-      case 'Home': v = this.min; break;
-      case 'End':  v = this.max; break;
-      case 'PageUp':   v += this.step * 10; break;
-      case 'PageDown': v -= this.step * 10; break;
-      default: return;
-    }
-    e.preventDefault();
-    this.#setValue(this.#snap(v));
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
-  };
+import { defineIfFree } from '../../core/register.js';
+import { UISlider } from './class.js';
 
-  disconnected() {
-    super.disconnected();
-    this.#thumbEl?.removeEventListener('pointerdown', this.#onPointerDown);
-    this.#trackEl?.removeEventListener('click', this.#onTrackClick);
-    this.#thumbEl?.removeEventListener('pointermove', this.#onPointerMove);
-    this.#thumbEl?.removeEventListener('pointerup', this.#onPointerUp);
-    this.removeEventListener('keydown', this.#onKey);
-    this.#trackEl = null;
-    this.#thumbEl = null;
-  }
-}
-customElements.define('slider-ui', UISlider);
+defineIfFree('slider-ui', UISlider);
 
 export { UISlider };

package/components/stack/class.js

@@ -0,0 +1,28 @@
+/**
+ * Non-side-effect class export for `<stack-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/stack`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * stack-ui — grid-overlay primitive. Children stack on top of each other
+ * (grid area 1/1), useful for badges-on-avatars, skeleton overlays, etc.
+ *
+ * <stack-ui align="center">...</stack-ui>
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIStack extends UIElement {
+  static properties = {
+    align: { type: String, default: 'center', reflect: true },
+  };
+  static template = () => null;
+}

package/components/stack/stack.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `<stack-ui>` — Grid overlay layout — children stack on top of each other.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/stack
+ *
+ * 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 UIStack extends UIElement {
+  /** Alignment of stacked items */
+  align: string;
+}

package/components/stack/stack.js

@@ -1,18 +1,17 @@
 /**
- * stack-ui — grid-overlay primitive. Children stack on top of each other
- * (grid area 1/1), useful for badges-on-avatars, skeleton overlays, etc.
+ * `<stack-ui>` — auto-registers the tag on import.
  *
- * <stack-ui align="center">...</stack-ui>
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIStack } from '@adia-ai/web-components/components/stack/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+import { UIStack } from './class.js';
 
-class UIStack extends UIElement {
-  static properties = {
-    align: { type: String, default: 'center', reflect: true },
-  };
-  static template = () => null;
-}
-customElements.define('stack-ui', UIStack);
+defineIfFree('stack-ui', UIStack);
 
 export { UIStack };

package/components/step-progress/class.js

@@ -0,0 +1,98 @@
+/**
+ * Non-side-effect class export for `<step-progress-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/step-progress`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <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>
+ *
+ * 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.
+ *
+ * Primitive shape (per ROADMAP § Done):
+ *   `<step-progress-ui value="N" total="M" caption="...">`
+ *
+ * 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).
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export 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 },
+  };
+
+  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;
+  }
+}

package/components/step-progress/step-progress.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `<step-progress-ui>` — Discrete-dash step-progress indicator. One <span> dash per step in
+[total]; the first [value] dashes are filled with --a-accent. Used
+in multi-step flows (registration, onboarding, wizards). Replaces
+the bespoke `[data-onb-progress]` + `[data-reg-progress]` markup
+that lived in onboarding.css + registration.css with a single
+primitive.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/step-progress
+ *
+ * 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 UIStepProgress extends UIElement {
+  /** Optional caption text rendered above the track (e.g. 'Step 3 of 10', 'Step 3 of 10 · Optional', 'All steps complete'). Hidden when empty. */
+  caption: string;
+  /** Total number of steps. The track renders this many dashes. */
+  total: number;
+  /** Number of steps completed (1-indexed). Clamped to [0, total]. */
+  value: number;
+}