@adia-ai/web-components 0.4.5 → 0.4.7

package/components/progress-row/progress-row.js

@@ -1,101 +1,17 @@
 /**
- * <progress-row-ui label="Documents" value="42" meta="32 GB"></progress-row-ui>
+ * `<progress-row-ui>` — auto-registers the tag on import.
  *
- * Inline labeled progress row. Used for storage quotas, capacity
- * breakdowns, budget/usage indicators.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Layout:
- *   ┌──────────────────────────────────────┐
- *   │ Label                          Meta  │  ← flex row, space-between
- *   │ ████████░░░░░░░░░░░░░░░░             │  ← progress bar below
- *   └──────────────────────────────────────┘
+ *   import { UIProgressRow } from '@adia-ai/web-components/components/progress-row/class';
  *
- * Properties:
- *   label   — left-hand label text
- *   value   — 0-100 progress value (null or -1 = indeterminate)
- *   meta    — right-hand meta text (e.g. "32 GB", "4.2k / 10k")
- *   variant — success | warning | danger (colors the fill; inherits otherwise)
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+import { UIProgressRow } from './class.js';
 
-class UIProgressRow extends UIElement {
-  static properties = {
-    label:   { type: String, default: '',  reflect: true },
-    value:   { type: Number, default: null, reflect: true },
-    meta:    { type: String, default: '',  reflect: true },
-    variant: { type: String, default: 'default',  reflect: true },
-  };
-
-  static template = () => null;
-
-  #labelEl = null;
-  #metaEl = null;
-  #progressEl = null;
-
-  connected() {
-    this.setAttribute('role', 'group');
-
-    this.#labelEl = this.querySelector(':scope > [slot="label"]');
-    if (!this.#labelEl) {
-      this.#labelEl = document.createElement('span');
-      this.#labelEl.setAttribute('slot', 'label');
-      this.appendChild(this.#labelEl);
-    }
-
-    this.#metaEl = this.querySelector(':scope > [slot="meta"]');
-    if (!this.#metaEl) {
-      this.#metaEl = document.createElement('span');
-      this.#metaEl.setAttribute('slot', 'meta');
-      this.appendChild(this.#metaEl);
-    }
-
-    this.#progressEl = this.querySelector(':scope > progress-ui');
-    if (!this.#progressEl) {
-      this.#progressEl = document.createElement('progress-ui');
-      // Pre-set value BEFORE append so progress-ui's first paint is
-      // determinate at the target value — `@starting-style { width: 0 }`
-      // in progress.css then transitions 0 → value on mount. Without this,
-      // the bar mounts indeterminate (width: 100% from the shimmer rule),
-      // and `render()` setting value: N triggers a backwards 100% → N
-      // animation, which reads as the bar shrinking right-to-left.
-      if (this.value != null && this.value >= 0) {
-        this.#progressEl.setAttribute('value', String(this.value));
-      }
-      this.appendChild(this.#progressEl);
-    }
-  }
-
-  disconnected() {
-    this.#labelEl = null;
-    this.#metaEl = null;
-    this.#progressEl = null;
-  }
-
-  render() {
-    if (!this.#labelEl) return;
-
-    this.#labelEl.textContent = this.label;
-    this.#labelEl.hidden = !this.label;
-
-    this.#metaEl.textContent = this.meta;
-    this.#metaEl.hidden = !this.meta;
-
-    if (this.value != null && this.value >= 0) {
-      this.#progressEl.setAttribute('value', String(this.value));
-    } else {
-      this.#progressEl.removeAttribute('value');
-    }
-
-    // ARIA: label the group so screen readers announce "Documents, 42 percent"
-    if (this.label) {
-      this.setAttribute('aria-label', this.meta ? `${this.label}, ${this.meta}` : this.label);
-    } else {
-      this.removeAttribute('aria-label');
-    }
-  }
-}
-
-customElements.define('progress-row-ui', UIProgressRow);
+defineIfFree('progress-row-ui', UIProgressRow);
 
 export { UIProgressRow };

package/components/radio/class.js

@@ -0,0 +1,83 @@
+/**
+ * Non-side-effect class export for `<radio-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/radio`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <radio-ui> — Radio button. The host IS the control.
+ * Pure CSS dot via [slot="dot"]::after inner circle. No SVG, no inset shadow hack.
+ */
+
+import { UIFormElement } from '../../core/form.js';
+import { html } from '../../core/element.js';
+
+export class UIRadio extends UIFormElement {
+  static properties = {
+    ...UIFormElement.properties,
+    checked:  { type: Boolean, default: false, reflect: true },
+    label:    { type: String,  default: '', reflect: true },
+  };
+
+  static template = () => html`<span slot="dot"></span>`;
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'radio');
+    this.setAttribute('tabindex', '0');
+    this.addEventListener('click', this.#select);
+    this.addEventListener('keydown', this.#onKey);
+  }
+
+  render() {
+    this.setAttribute('aria-checked', String(this.checked));
+    if (this.label) this.setAttribute('aria-label', this.label);
+    if (this.checked) this.syncValue(this.value || 'on');
+  }
+
+  #select = () => {
+    if (this.disabled || this.checked) return;
+    const group = this.closest('fieldset, [role="radiogroup"]') || this.parentElement;
+    if (group) {
+      for (const r of group.querySelectorAll(`radio-ui[name="${this.name}"]`)) {
+        if (r !== this && r.checked) r.checked = false;
+      }
+    }
+    this.checked = true;
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value, checked: this.checked } }));
+  };
+
+  #onKey = (e) => {
+    if (e.key === ' ' || e.key === 'Enter') { e.preventDefault(); this.#select(); }
+    if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
+      e.preventDefault();
+      const next = this.#sibling(1);
+      if (next) { next.focus(); next.click(); }
+    }
+    if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') {
+      e.preventDefault();
+      const prev = this.#sibling(-1);
+      if (prev) { prev.focus(); prev.click(); }
+    }
+  };
+
+  #sibling(dir) {
+    const group = this.closest('fieldset, [role="radiogroup"]') || this.parentElement;
+    const radios = [...(group?.querySelectorAll(`radio-ui[name="${this.name}"]`) || [])];
+    const i = radios.indexOf(this);
+    return radios[(i + dir + radios.length) % radios.length] || null;
+  }
+
+  disconnected() {
+    super.disconnected();
+    this.removeEventListener('click', this.#select);
+    this.removeEventListener('keydown', this.#onKey);
+  }
+}

package/components/radio/radio.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `<radio-ui>` — Radio button (boolean-semantic form control; group via shared name).
+ *
+ * @see https://ui-kit.exe.xyz/site/components/radio
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+export interface RadioChangeEventDetail {
+  /** Submitted value (the radio's `value` attribute). */
+  value: string;
+  /** Current checked state. */
+  checked: boolean;
+}
+export type RadioChangeEvent = CustomEvent<RadioChangeEventDetail>;
+
+export class UIRadio extends UIFormElement {
+  /** Checked state — reflected; setting `checked=true` deselects siblings in the group. */
+  checked: boolean;
+  label: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIRadio, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: RadioChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/radio/radio.js

@@ -1,73 +1,17 @@
 /**
- * <radio-ui> — Radio button. The host IS the control.
- * Pure CSS dot via [slot="dot"]::after inner circle. No SVG, no inset shadow hack.
+ * `<radio-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIRadio } from '@adia-ai/web-components/components/radio/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIFormElement } from '../../core/form.js';
-import { html } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+import { UIRadio } from './class.js';
 
-class UIRadio extends UIFormElement {
-  static properties = {
-    ...UIFormElement.properties,
-    checked:  { type: Boolean, default: false, reflect: true },
-    label:    { type: String,  default: '', reflect: true },
-  };
-
-  static template = () => html`<span slot="dot"></span>`;
-
-  connected() {
-    super.connected();
-    this.setAttribute('role', 'radio');
-    this.setAttribute('tabindex', '0');
-    this.addEventListener('click', this.#select);
-    this.addEventListener('keydown', this.#onKey);
-  }
-
-  render() {
-    this.setAttribute('aria-checked', String(this.checked));
-    if (this.label) this.setAttribute('aria-label', this.label);
-    if (this.checked) this.syncValue(this.value || 'on');
-  }
-
-  #select = () => {
-    if (this.disabled || this.checked) return;
-    const group = this.closest('fieldset, [role="radiogroup"]') || this.parentElement;
-    if (group) {
-      for (const r of group.querySelectorAll(`radio-ui[name="${this.name}"]`)) {
-        if (r !== this && r.checked) r.checked = false;
-      }
-    }
-    this.checked = true;
-    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value, checked: this.checked } }));
-  };
-
-  #onKey = (e) => {
-    if (e.key === ' ' || e.key === 'Enter') { e.preventDefault(); this.#select(); }
-    if (e.key === 'ArrowDown' || e.key === 'ArrowRight') {
-      e.preventDefault();
-      const next = this.#sibling(1);
-      if (next) { next.focus(); next.click(); }
-    }
-    if (e.key === 'ArrowUp' || e.key === 'ArrowLeft') {
-      e.preventDefault();
-      const prev = this.#sibling(-1);
-      if (prev) { prev.focus(); prev.click(); }
-    }
-  };
-
-  #sibling(dir) {
-    const group = this.closest('fieldset, [role="radiogroup"]') || this.parentElement;
-    const radios = [...(group?.querySelectorAll(`radio-ui[name="${this.name}"]`) || [])];
-    const i = radios.indexOf(this);
-    return radios[(i + dir + radios.length) % radios.length] || null;
-  }
-
-  disconnected() {
-    super.disconnected();
-    this.removeEventListener('click', this.#select);
-    this.removeEventListener('keydown', this.#onKey);
-  }
-}
-customElements.define('radio-ui', UIRadio);
+defineIfFree('radio-ui', UIRadio);
 
 export { UIRadio };

package/components/range/class.js

@@ -0,0 +1,194 @@
+/**
+ * Non-side-effect class export for `<range-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/range`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <range-input label="Width" value="63" min="0" max="100" step="1" suffix="rem"></range-input>
+ *
+ * A draggable numeric field — NOT a slider. The entire field is the scrubber surface.
+ * Horizontal drag on the value changes it. No track, no thumb.
+ *
+ * Layout: [label]  [value] [suffix]
+ *   - Label left-aligned, muted
+ *   - Value right-aligned, bold, editable via horizontal drag
+ *   - Suffix after value, muted
+ *   - While dragging: accent highlight on the field
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+export class UIRange extends UIFormElement {
+  // Opt out of UIFormElement's per-control `label` deprecation warning.
+  // range-ui's `label` is a first-class API: it renders as the in-track
+  // caption next to the value (the entire field is the scrubber surface)
+  // and the host gets `aria-label` wired from it for proper screen-reader
+  // announcement. Same opt-out rationale as input-ui.
+  static labelDeprecated = false;
+
+  static properties = {
+    ...UIFormElement.properties,
+    /** value: Number — overrides UIFormElement.value (String); syncs as string on form submit. */
+    value:  { type: Number,  default: 0,  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;
+
+  #fieldEl = null;
+  #valueEl = null;
+  #dragging = false;
+  #startX = 0;
+  #startVal = 0;
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'spinbutton');
+    this.setAttribute('tabindex', '0');
+
+    if (!this.querySelector('[slot="field"]')) {
+      const inner = `
+        <span slot="label">${this.label}</span>
+        <span slot="value">${this.#format(this.value)}</span>
+        ${this.suffix ? `<span slot="suffix">${this.suffix}</span>` : ''}
+      `;
+      this.innerHTML = `
+        <div slot="field">
+          <div slot="layer" data-layer="base">${inner}</div>
+          <div slot="layer" data-layer="fill" aria-hidden="true">${inner}</div>
+        </div>
+      `;
+    }
+
+    this.#fieldEl = this.querySelector('[slot="field"]');
+    this.#valueEl = this.querySelector('[data-layer="base"] [slot="value"]');
+
+    if (this.#fieldEl) this.#fieldEl.addEventListener('pointerdown', this.#onPointerDown);
+    this.addEventListener('keydown', this.#onKey);
+  }
+
+  render() {
+    if (!this.#fieldEl) return;
+
+    const formatted = this.#format(this.value);
+    if (this.#valueEl) this.#valueEl.textContent = formatted;
+    const fillValueEl = this.querySelector('[data-layer="fill"] [slot="value"]');
+    if (fillValueEl) fillValueEl.textContent = formatted;
+
+    // Update fill percentage via CSS var (drives clip-path on fill layer)
+    const range = this.max - this.min;
+    const pct = range > 0 ? ((this.value - this.min) / range) * 100 : 0;
+    this.style.setProperty('--range-fill-pct', `${pct}%`);
+
+    this.setAttribute('aria-valuemin', this.min);
+    this.setAttribute('aria-valuemax', this.max);
+    this.setAttribute('aria-valuenow', this.value);
+    this.setAttribute('aria-valuetext', `${this.value}${this.suffix ? ' ' + this.suffix : ''}`);
+    this.setAttribute('aria-label', this.label || '');
+
+    this.syncValue(String(this.value));
+  }
+
+  #format(v) {
+    // Show decimal places matching step precision
+    const decimals = (String(this.step).split('.')[1] || '').length;
+    return decimals > 0 ? v.toFixed(decimals) : String(v);
+  }
+
+  #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) {
+    const snapped = this.#snap(v);
+    if (snapped === this.value) return;
+    this.value = snapped;
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+  }
+
+  // ── Pointer drag ──
+
+  #valueFromX(clientX) {
+    const rect = this.#fieldEl.getBoundingClientRect();
+    const ratio = Math.max(0, Math.min(1, (clientX - rect.left) / rect.width));
+    return this.#snap(this.min + ratio * (this.max - this.min));
+  }
+
+  #onPointerDown = (e) => {
+    if (this.disabled) return;
+    e.preventDefault();
+
+    // Click: jump to position immediately
+    this.#setValue(this.#valueFromX(e.clientX));
+
+    // Then start drag from that position
+    this.#dragging = true;
+    this.#startX = e.clientX;
+    this.#startVal = this.value;
+    this.setAttribute('data-dragging', '');
+    this.#fieldEl.setPointerCapture(e.pointerId);
+    this.#fieldEl.addEventListener('pointermove', this.#onPointerMove);
+    this.#fieldEl.addEventListener('pointerup', this.#onPointerUp);
+  };
+
+  #onPointerMove = (e) => {
+    if (!this.#dragging) return;
+    const dx = e.clientX - this.#startX;
+    // 1:1 — dragging across the full field width traverses the full range
+    const fieldWidth = this.#fieldEl.getBoundingClientRect().width;
+    const range = this.max - this.min;
+    const delta = (dx / fieldWidth) * range;
+    this.#setValue(this.#startVal + delta);
+  };
+
+  #onPointerUp = (e) => {
+    this.#dragging = false;
+    this.removeAttribute('data-dragging');
+    this.#fieldEl.releasePointerCapture(e.pointerId);
+    this.#fieldEl.removeEventListener('pointermove', this.#onPointerMove);
+    this.#fieldEl.removeEventListener('pointerup', this.#onPointerUp);
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+  };
+
+  // ── Keyboard ──
+
+  #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(v);
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+  };
+
+  disconnected() {
+    super.disconnected();
+    this.#fieldEl?.removeEventListener('pointerdown', this.#onPointerDown);
+    this.#fieldEl?.removeEventListener('pointermove', this.#onPointerMove);
+    this.#fieldEl?.removeEventListener('pointerup', this.#onPointerUp);
+    this.removeEventListener('keydown', this.#onKey);
+    this.#fieldEl = null;
+    this.#valueEl = null;
+  }
+}

package/components/range/range.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `<range-ui>` — Range track with click-to-jump + drag.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/range
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+export interface RangeChangeEventDetail {
+  value: number;
+}
+export type RangeChangeEvent = CustomEvent<RangeChangeEventDetail>;
+export type RangeInputEvent = CustomEvent<RangeChangeEventDetail>;
+
+export class UIRange 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: UIRange, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: RangeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'input', listener: (ev: RangeInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}