@adia-ai/web-components 0.4.6 → 0.4.7

package/components/row/row.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `<row-ui>` — Flex row layout primitive.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/row
+ *
+ * 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 UIRow extends UIElement {
+  /** Align items */
+  align: string;
+  /** Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end. */
+  draggable: boolean;
+  /** Gap between children. Accepts either the named scale (xs/sm/md/lg/xl) or a numeric rung on the spacing scale ("1"…"16"). */
+  gap: string;
+  /** Fills remaining space in a flex parent. CSS-only attribute via :scope[grow] in row.css. */
+  grow: boolean;
+  /** Justify content */
+  justify: string;
+  /** Enable flex wrap */
+  wrap: boolean;
+}

package/components/row/row.js

@@ -1,40 +1,17 @@
 /**
- * row-ui — Flex row layout primitive.
+ * `<row-ui>` — auto-registers the tag on import.
  *
- * <row-ui gap="sm" justify="space-between" wrap>...</row-ui>
- * <row-ui draggable>...</row-ui>   wires the draggable trait, emits drag-end
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIRow } from '@adia-ai/web-components/components/row/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-import { draggable } from '../../traits/draggable/draggable.js';
-
-class UIRow extends UIElement {
-  static properties = {
-    justify:   { type: String,  default: 'start',  reflect: true },
-    align:     { type: String,  default: 'center', reflect: true },
-    gap:       { type: String,  default: 'md',     reflect: true },
-    grow:      { type: Boolean, default: false,    reflect: true },
-    wrap:      { type: Boolean, default: false,    reflect: true },
-    draggable: { type: Boolean, default: false,    reflect: true },
-  };
-  static template = () => null;
-
-  #dragAttached = false;
-
-  connected() {
-    if (this.draggable && !this.#dragAttached) {
-      this.addTrait(draggable);
-      this.#dragAttached = true;
-    }
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIRow } from './class.js';
 
-  updated(changed) {
-    if (changed.has('draggable') && this.draggable && !this.#dragAttached) {
-      this.addTrait(draggable);
-      this.#dragAttached = true;
-    }
-  }
-}
-customElements.define('row-ui', UIRow);
+defineIfFree('row-ui', UIRow);
 
 export { UIRow };

package/components/search/class.js

@@ -0,0 +1,134 @@
+/**
+ * Non-side-effect class export for `<search-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/search`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <search-ui placeholder="Search..."></search-ui>
+ * <search-ui debounce="500"></search-ui>
+ *
+ * Search input with magnifying-glass icon, clear button, and debounce.
+ * Composes input-ui internally — no raw <input> stamping.
+ * Fires debounced 'search' event. Clear button resets and fires immediately.
+ */
+
+import { UIFormElement } from '../../core/form.js';
+
+export class UISearch extends UIFormElement {
+  static properties = {
+    ...UIFormElement.properties,
+    placeholder: { type: String, default: 'Search...', reflect: true },
+    debounce:    { type: Number, default: 300, reflect: true },
+  };
+
+  static template = () => null;
+
+  #inputEl = null;
+  #suffixEl = null;
+  #timer = null;
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'search');
+
+    if (!this.querySelector('input-ui')) {
+      this.innerHTML = `<input-ui
+        type="search"
+        prefix="magnifying-glass"
+        suffix="x-circle"
+        placeholder="${this.placeholder}"
+        ${this.disabled ? 'disabled' : ''}
+      ></input-ui>`;
+    }
+
+    this.#inputEl = this.querySelector('input-ui');
+    if (this.#inputEl) {
+      this.#inputEl.addEventListener('input', this.#onInput);
+      this.#inputEl.addEventListener('keydown', this.#onKeydown);
+      this.#suffixEl = this.#inputEl.querySelector('[slot="suffix"]');
+      if (this.#suffixEl) {
+        this.#suffixEl.style.cursor = 'pointer';
+        this.#suffixEl.addEventListener('click', this.#onClear);
+      }
+    }
+  }
+
+  render() {
+    if (!this.#inputEl) return;
+
+    this.#inputEl.setAttribute('placeholder', this.placeholder);
+    if (this.disabled) this.#inputEl.setAttribute('disabled', '');
+    else this.#inputEl.removeAttribute('disabled');
+
+    // Reflect value for CSS (clear button visibility)
+    this.setAttribute('value', this.value || '');
+  }
+
+  #onInput = () => {
+    this.value = this.#inputEl.value;
+    this.syncValue(this.value);
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+
+    clearTimeout(this.#timer);
+    this.#timer = setTimeout(() => {
+      this.dispatchEvent(new CustomEvent('search', {
+        bubbles: true,
+        detail: { value: this.value },
+      }));
+    }, this.debounce || 300);
+  };
+
+  #onKeydown = (e) => {
+    if (e.key === 'Enter') {
+      clearTimeout(this.#timer);
+      this.dispatchEvent(new CustomEvent('search', {
+        bubbles: true,
+        detail: { value: this.value },
+      }));
+    }
+    if (e.key === 'Escape') {
+      this.#onClear();
+    }
+  };
+
+  #onClear = () => {
+    clearTimeout(this.#timer);
+    this.value = '';
+    if (this.#inputEl) this.#inputEl.value = '';
+    this.syncValue('');
+    this.setAttribute('value', '');
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('search', {
+      bubbles: true,
+      detail: { value: '' },
+    }));
+    this.#inputEl?.focus();
+  };
+
+  focus() { this.#inputEl?.focus(); }
+
+  clear() { this.#onClear(); }
+
+  disconnected() {
+    super.disconnected();
+    clearTimeout(this.#timer);
+    this.#timer = null;
+    if (this.#inputEl) {
+      this.#inputEl.removeEventListener('input', this.#onInput);
+      this.#inputEl.removeEventListener('keydown', this.#onKeydown);
+    }
+    if (this.#suffixEl) {
+      this.#suffixEl.removeEventListener('click', this.#onClear);
+    }
+    this.#inputEl = null;
+    this.#suffixEl = null;
+  }
+}

package/components/search/search.js

@@ -1,124 +1,17 @@
 /**
- * <search-ui placeholder="Search..."></search-ui>
- * <search-ui debounce="500"></search-ui>
+ * `<search-ui>` — auto-registers the tag on import.
  *
- * Search input with magnifying-glass icon, clear button, and debounce.
- * Composes input-ui internally — no raw <input> stamping.
- * Fires debounced 'search' event. Clear button resets and fires immediately.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UISearch } from '@adia-ai/web-components/components/search/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIFormElement } from '../../core/form.js';
-
-class UISearch extends UIFormElement {
-  static properties = {
-    ...UIFormElement.properties,
-    placeholder: { type: String, default: 'Search...', reflect: true },
-    debounce:    { type: Number, default: 300, reflect: true },
-  };
-
-  static template = () => null;
-
-  #inputEl = null;
-  #suffixEl = null;
-  #timer = null;
-
-  connected() {
-    super.connected();
-    this.setAttribute('role', 'search');
-
-    if (!this.querySelector('input-ui')) {
-      this.innerHTML = `<input-ui
-        type="search"
-        prefix="magnifying-glass"
-        suffix="x-circle"
-        placeholder="${this.placeholder}"
-        ${this.disabled ? 'disabled' : ''}
-      ></input-ui>`;
-    }
-
-    this.#inputEl = this.querySelector('input-ui');
-    if (this.#inputEl) {
-      this.#inputEl.addEventListener('input', this.#onInput);
-      this.#inputEl.addEventListener('keydown', this.#onKeydown);
-      this.#suffixEl = this.#inputEl.querySelector('[slot="suffix"]');
-      if (this.#suffixEl) {
-        this.#suffixEl.style.cursor = 'pointer';
-        this.#suffixEl.addEventListener('click', this.#onClear);
-      }
-    }
-  }
-
-  render() {
-    if (!this.#inputEl) return;
-
-    this.#inputEl.setAttribute('placeholder', this.placeholder);
-    if (this.disabled) this.#inputEl.setAttribute('disabled', '');
-    else this.#inputEl.removeAttribute('disabled');
-
-    // Reflect value for CSS (clear button visibility)
-    this.setAttribute('value', this.value || '');
-  }
-
-  #onInput = () => {
-    this.value = this.#inputEl.value;
-    this.syncValue(this.value);
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-
-    clearTimeout(this.#timer);
-    this.#timer = setTimeout(() => {
-      this.dispatchEvent(new CustomEvent('search', {
-        bubbles: true,
-        detail: { value: this.value },
-      }));
-    }, this.debounce || 300);
-  };
-
-  #onKeydown = (e) => {
-    if (e.key === 'Enter') {
-      clearTimeout(this.#timer);
-      this.dispatchEvent(new CustomEvent('search', {
-        bubbles: true,
-        detail: { value: this.value },
-      }));
-    }
-    if (e.key === 'Escape') {
-      this.#onClear();
-    }
-  };
-
-  #onClear = () => {
-    clearTimeout(this.#timer);
-    this.value = '';
-    if (this.#inputEl) this.#inputEl.value = '';
-    this.syncValue('');
-    this.setAttribute('value', '');
-    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
-    this.dispatchEvent(new CustomEvent('search', {
-      bubbles: true,
-      detail: { value: '' },
-    }));
-    this.#inputEl?.focus();
-  };
-
-  focus() { this.#inputEl?.focus(); }
-
-  clear() { this.#onClear(); }
+import { defineIfFree } from '../../core/register.js';
+import { UISearch } from './class.js';
 
-  disconnected() {
-    super.disconnected();
-    clearTimeout(this.#timer);
-    this.#timer = null;
-    if (this.#inputEl) {
-      this.#inputEl.removeEventListener('input', this.#onInput);
-      this.#inputEl.removeEventListener('keydown', this.#onKeydown);
-    }
-    if (this.#suffixEl) {
-      this.#suffixEl.removeEventListener('click', this.#onClear);
-    }
-    this.#inputEl = null;
-    this.#suffixEl = null;
-  }
-}
-customElements.define('search-ui', UISearch);
+defineIfFree('search-ui', UISearch);
 
 export { UISearch };

package/components/segment/class.js

@@ -0,0 +1,62 @@
+/**
+ * Non-side-effect class export for `<segment-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/segment`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <segment-ui value="tab1" text="Tab 1" icon="list"></segment-ui>
+ * Child of segmented-ui. Represents one option.
+ *
+ * `icon=` stamps a leading <icon-ui name="…"> child on render.
+ * Mirrors the button-ui pattern.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UISegment 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 },
+    selected: { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    this.setAttribute('role', 'radio');
+    if (!this.getAttribute('tabindex')) this.setAttribute('tabindex', '-1');
+  }
+
+  render() {
+    if (this.text) this.setAttribute('aria-label', this.text);
+    this.setAttribute('aria-checked', this.selected ? 'true' : 'false');
+    if (this.disabled) this.setAttribute('aria-disabled', 'true');
+    else this.removeAttribute('aria-disabled');
+
+    // Stamp/refresh leading icon-ui child when [icon] is set.
+    // Mirrors button-ui's pattern (button.js:29) — author code never
+    // hand-rolls an icon-ui inside a segment.
+    if (this.icon) {
+      const existing = this.querySelector(':scope > icon-ui');
+      if (!existing || existing.getAttribute('name') !== this.icon) {
+        existing?.remove();
+        const iconEl = document.createElement('icon-ui');
+        iconEl.setAttribute('name', this.icon);
+        iconEl.setAttribute('aria-hidden', 'true');
+        this.prepend(iconEl);
+      }
+    } else {
+      this.querySelector(':scope > icon-ui')?.remove();
+    }
+  }
+}

package/components/segment/segment.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `<segment-ui>` — Individual segment option, child of segmented-ui.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/segment
+ *
+ * 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 UISegment extends UIElement {
+  /** Disables this segment. */
+  disabled: boolean;
+  /** Phosphor icon name. Rendered as a leading <icon-ui> child stamped on render. */
+  icon: string;
+  /** Whether this segment is currently selected. Managed by the parent Segmented container; don't set multiple siblings selected. */
+  selected: boolean;
+  /** Display text. Rendered via CSS attr(text) on ::after pseudo-element. */
+  text: string;
+  /** Value emitted when this segment is selected. */
+  value: string;
+}

package/components/segment/segment.js

@@ -1,52 +1,17 @@
 /**
- * <segment-ui value="tab1" text="Tab 1" icon="list"></segment-ui>
- * Child of segmented-ui. Represents one option.
+ * `<segment-ui>` — auto-registers the tag on import.
  *
- * `icon=` stamps a leading <icon-ui name="…"> child on render.
- * Mirrors the button-ui pattern.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UISegment } from '@adia-ai/web-components/components/segment/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UISegment 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 },
-    selected: { type: Boolean, default: false, reflect: true },
-  };
-
-  static template = () => null;
-
-  connected() {
-    this.setAttribute('role', 'radio');
-    if (!this.getAttribute('tabindex')) this.setAttribute('tabindex', '-1');
-  }
-
-  render() {
-    if (this.text) this.setAttribute('aria-label', this.text);
-    this.setAttribute('aria-checked', this.selected ? 'true' : 'false');
-    if (this.disabled) this.setAttribute('aria-disabled', 'true');
-    else this.removeAttribute('aria-disabled');
+import { defineIfFree } from '../../core/register.js';
+import { UISegment } from './class.js';
 
-    // Stamp/refresh leading icon-ui child when [icon] is set.
-    // Mirrors button-ui's pattern (button.js:29) — author code never
-    // hand-rolls an icon-ui inside a segment.
-    if (this.icon) {
-      const existing = this.querySelector(':scope > icon-ui');
-      if (!existing || existing.getAttribute('name') !== this.icon) {
-        existing?.remove();
-        const iconEl = document.createElement('icon-ui');
-        iconEl.setAttribute('name', this.icon);
-        iconEl.setAttribute('aria-hidden', 'true');
-        this.prepend(iconEl);
-      }
-    } else {
-      this.querySelector(':scope > icon-ui')?.remove();
-    }
-  }
-}
-customElements.define('segment-ui', UISegment);
+defineIfFree('segment-ui', UISegment);
 
 export { UISegment };

package/components/segmented/class.js

@@ -0,0 +1,165 @@
+/**
+ * Non-side-effect class export for `<segmented-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/segmented`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <segmented-ui value="tab1">
+ *   <segment-ui value="tab1" text="Tab 1"></segment-ui>
+ *   <segment-ui value="tab2" text="Tab 2"></segment-ui>
+ *   <segment-ui value="tab3" text="Tab 3"></segment-ui>
+ * </segmented-ui>
+ *
+ * Mutually exclusive toggle group with animated indicator pill.
+ * Indicator uses CSS transform (GPU-accelerated).
+ */
+
+import { UIFormElement } from '../../core/form.js';
+import '../segment/segment.js';
+
+export class UISegmented extends UIFormElement {
+  static properties = {
+    ...UIFormElement.properties,
+    value: { type: String, default: '', reflect: true },
+  };
+
+  static template = () => null;
+
+  #indicator = null;
+  #bound = false;
+  #transitionRaf = null;
+
+  connected() {
+    super.connected();
+    this.setAttribute('role', 'radiogroup');
+
+    if (!this.#bound) {
+      this.#bound = true;
+      this.addEventListener('click', this.#handleClick);
+      this.addEventListener('keydown', this.#handleKeydown);
+    }
+
+    // Default to first segment if no value
+    if (!this.value) {
+      const first = this.querySelector('segment-ui:not([disabled])');
+      if (first) this.value = first.value || first.getAttribute('value') || '';
+    }
+  }
+
+  disconnected() {
+    super.disconnected();
+    if (this.#transitionRaf != null) {
+      cancelAnimationFrame(this.#transitionRaf);
+      this.#transitionRaf = null;
+    }
+    this.removeEventListener('click', this.#handleClick);
+    this.removeEventListener('keydown', this.#handleKeydown);
+    this.#indicator = null;
+    this.#bound = false;
+  }
+
+  get #segments() {
+    return [...this.querySelectorAll('segment-ui')];
+  }
+
+  get #enabledSegments() {
+    return this.#segments.filter(s => !s.disabled);
+  }
+
+  render() {
+    const segs = this.#segments;
+    if (!segs.length) return;
+
+    // Sync selection state
+    for (const seg of segs) {
+      const segVal = seg.value || seg.getAttribute('value') || '';
+      const isActive = segVal === this.value;
+      if (isActive) {
+        seg.setAttribute('selected', '');
+      } else {
+        seg.removeAttribute('selected');
+      }
+      seg.setAttribute('tabindex', isActive ? '0' : '-1');
+    }
+
+    if (this.label) this.setAttribute('aria-label', this.label);
+
+    this.#updateIndicator(segs);
+  }
+
+  #updateIndicator(segs) {
+    const selectedIdx = segs.findIndex(s => (s.value || s.getAttribute('value') || '') === this.value);
+
+    if (selectedIdx < 0) {
+      this.removeAttribute('data-indicator-ready');
+      return;
+    }
+
+    // Lazy-create indicator (prepend so it's behind segments in paint order)
+    const isNew = !this.#indicator;
+    if (isNew) {
+      this.#indicator = document.createElement('span');
+      this.#indicator.setAttribute('data-indicator', '');
+      this.prepend(this.#indicator);
+    }
+
+    this.style.setProperty('--_segment-count', `${segs.length}`);
+
+    if (isNew) {
+      // First render: position instantly, then enable transition next frame
+      this.#indicator.style.transition = 'none';
+      this.#indicator.style.transform = `translateX(${selectedIdx * 100}%)`;
+      this.setAttribute('data-indicator-ready', '');
+      this.#transitionRaf = requestAnimationFrame(() => {
+        this.#transitionRaf = null;
+        if (this.#indicator) this.#indicator.style.transition = '';
+      });
+    } else {
+      this.#indicator.style.transform = `translateX(${selectedIdx * 100}%)`;
+      this.setAttribute('data-indicator-ready', '');
+    }
+  }
+
+  #select(seg) {
+    if (seg.disabled) return;
+    this.value = seg.value;
+    this.syncValue();
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
+  }
+
+  #handleClick = (e) => {
+    const seg = e.target.closest('segment-ui');
+    if (seg && this.contains(seg)) this.#select(seg);
+  };
+
+  #handleKeydown = (e) => {
+    const target = e.target;
+    if (target.tagName !== 'SEGMENT-UI') return;
+    const segs = this.#enabledSegments;
+    const idx = segs.indexOf(target);
+    if (idx < 0) return;
+
+    let next;
+    switch (e.key) {
+      case 'ArrowRight': case 'ArrowDown':
+        next = idx < segs.length - 1 ? idx + 1 : 0; break;
+      case 'ArrowLeft': case 'ArrowUp':
+        next = idx > 0 ? idx - 1 : segs.length - 1; break;
+      case 'Home': next = 0; break;
+      case 'End': next = segs.length - 1; break;
+      default: return;
+    }
+
+    e.preventDefault();
+    segs[next].focus();
+    this.#select(segs[next]);
+  };
+}

package/components/segmented/segmented.a2ui.json

@@ -92,6 +92,10 @@
         "panel",
         "segmented"
       ],
+      "tags": [
+        "SegmentedControl",
+        "Segmented"
+      ],
       "toggle": [
         "segmented",
         "radio",