@adia-ai/web-components 0.4.6 → 0.4.7

package/USAGE.md

@@ -445,33 +445,53 @@ register('my-slider', MySlider);
 
 The `slider-ui` import auto-registers, but that doesn't interfere — `my-slider` is a distinct tag that hosts your subclass.
 
-### Roadmap — non-side-effect class imports
+### Non-side-effect class imports (since v0.4.7)
 
-A future v0.4.x release will ship a non-side-effect `class` subpath per component:
+Every component ships a sibling `class` subpath that exports the class **without** running `customElements.define`. Use it when you need test isolation, tag-name override, or selective composition:
+
+```js
+// Auto-register (default; tag registered immediately):
+import '@adia-ai/web-components/components/slider';
+
+// Class import (no auto-register; you decide when to define):
+import { UISlider } from '@adia-ai/web-components/components/slider/class';
+
+// Subclass + register under a different tag
+class MySlider extends UISlider {
+  static properties = { ...UISlider.properties, custom: { type: String } };
+}
+customElements.define('my-slider', MySlider);
+```
+
+**Test isolation example** — register the class under a unique per-test tag so subclass tests don't clobber the global registration:
 
 ```js
-// FUTURE — not available yet (v0.4.7+)
 import { UISlider } from '@adia-ai/web-components/components/slider/class';
-// imports the class without running customElements.define
+import { defineIfFree } from '@adia-ai/web-components/core';
+
+beforeEach(() => {
+  const tag = `slider-ui-test-${Math.random().toString(36).slice(2, 8)}`;
+  defineIfFree(tag, class extends UISlider { /* test overrides */ });
+});
 ```
 
-This will enable test isolation (register the class under a different tag in unit tests without clobbering the global) + true tree-shaking elimination of un-used primitives. Until then, importing the auto-register subpath is the canonical path, and `defineIfFree` covers conflict avoidance.
+The class subpath is available for every component that has an `<x-ui>` tag (~95 primitives). TypeScript types are picked up from the same per-primitive `.d.ts` files used by the auto-register path — no separate `.d.ts` per subpath needed.
 
 ---
 
 ## TypeScript
 
-Since v0.4.6, the package ships hand-written `.d.ts` declarations. Adding the package to your dependencies automatically picks up:
+Since v0.4.6, the package ships `.d.ts` declarations. v0.4.6 covered the 17 form-bearing primitives (input/select/slider/etc.) with hand-authored rich event types; v0.4.7 codegen extended coverage to the remaining 73 non-form primitives (button/card/table/chart/etc.) from each component's `.a2ui.json` sidecar. **90 of 95** primitives that ship a JS class are now typed (the 5 CSS-only "elements" — `header`, `footer`, `section`, etc. — have no class). Adding the package to your dependencies automatically picks up:
 
 - Typed properties on every primitive (e.g. `el.value` is `number` on `<slider-ui>`, `boolean` on `<switch-ui>`)
 - Typed events — `addEventListener('change', e => e.detail.value)` infers the detail shape
-- `HTMLElementTagNameMap` augmentation — `document.querySelector('slider-ui')` returns `UISliderElement`
+- `HTMLElementTagNameMap` augmentation — `document.querySelector('slider-ui')` returns `UISlider`
 - Public types for `UIElement`, `UIFormElement`, signal, computed, effect, html, stamp
 
 ```ts
-import type { UISliderElement, SliderChangeEvent } from '@adia-ai/web-components';
+import type { UISlider, SliderChangeEvent } from '@adia-ai/web-components';
 
-const slider: UISliderElement = document.querySelector('slider-ui')!;
+const slider: UISlider = document.querySelector('slider-ui')!;
 slider.value = 75;                              // typed Number — string would error
 
 slider.addEventListener('change', (e: SliderChangeEvent) => {

package/components/accordion/accordion.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `<accordion-ui>` — Accordion container managing single/multiple open states.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/accordion
+ *
+ * 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 UIAccordion extends UIElement {
+  /** Allow multiple panels to be open simultaneously */
+  multiple: boolean;
+}

package/components/accordion/accordion.js

@@ -1,125 +1,18 @@
 /**
- * <accordion-ui>
- *   <accordion-item-ui text="Section 1">Content for section 1</accordion-item-ui>
- *   <accordion-item-ui text="Section 2">Content for section 2</accordion-item-ui>
- * </accordion-ui>
+ * `<accordion-ui>` — auto-registers the tag on import.
  *
- * Accordion container + item pair.
- * Container manages single/multiple open states.
- * Items handle their own expand/collapse toggle.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Events (on accordion-item-ui):
- *   toggle — { detail: { open } }
+ *   import { UIAccordion, UIAccordionItem } from '@adia-ai/web-components/components/accordion/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-// ── Accordion Container ────────────────────────────────────────
-
-class UIAccordion extends UIElement {
-  static properties = {
-    multiple: { type: Boolean, default: false, reflect: true },
-  };
-
-  static template = () => null;
-
-  connected() {
-    this.addEventListener('toggle', this.#onItemToggle);
-  }
-
-  disconnected() {
-    this.removeEventListener('toggle', this.#onItemToggle);
-  }
-
-  #onItemToggle = (e) => {
-    if (this.multiple) return;
-
-    const target = e.target;
-    if (!target.open) return;
-
-    // Close other items
-    const items = this.querySelectorAll('accordion-item-ui');
-    for (const item of items) {
-      if (item !== target && item.open) {
-        item.open = false;
-      }
-    }
-  };
-}
-customElements.define('accordion-ui', UIAccordion);
-
-// ── Accordion Item ─────────────────────────────────────────────
-
-class UIAccordionItem extends UIElement {
-  static properties = {
-    text: { type: String,  default: '', reflect: true },
-    open: { type: Boolean, default: false, reflect: true },
-  };
-
-  static template = () => null;
-
-  #bound = false;
-
-  connected() {
-    // Stamp header if not present
-    if (!this.querySelector('[slot="header"]')) {
-      const header = document.createElement('div');
-      header.setAttribute('slot', 'header');
-
-      const label = document.createElement('span');
-      label.setAttribute('slot', 'header-text');
-      header.appendChild(label);
-
-      const caret = document.createElement('icon-ui');
-      caret.setAttribute('name', 'caret-down');
-      caret.setAttribute('slot', 'caret');
-      header.appendChild(caret);
-
-      this.prepend(header);
-    }
-
-    // Stamp content wrapper if not present
-    if (!this.querySelector('[slot="body"]')) {
-      const body = document.createElement('div');
-      body.setAttribute('slot', 'body');
-
-      // Move non-slotted children into body
-      const children = [...this.childNodes].filter(n => {
-        if (n.nodeType === 1) return !n.hasAttribute('slot');
-        return n.nodeType === 3 && n.textContent.trim();
-      });
-      for (const child of children) body.appendChild(child);
-
-      this.appendChild(body);
-    }
-
-    if (!this.#bound) {
-      this.#bound = true;
-      this.addEventListener('click', this.#onClick);
-    }
-  }
-
-  disconnected() {
-    this.removeEventListener('click', this.#onClick);
-    this.#bound = false;
-  }
-
-  render() {
-    const label = this.querySelector('[slot="header-text"]');
-    if (label) label.textContent = this.text;
-  }
-
-  #onClick = (e) => {
-    const header = this.querySelector('[slot="header"]');
-    if (!header || !header.contains(e.target)) return;
+import { defineIfFree } from '../../core/register.js';
+import { UIAccordion, UIAccordionItem } from './class.js';
 
-    this.open = !this.open;
-    this.dispatchEvent(new CustomEvent('toggle', {
-      bubbles: true,
-      detail: { open: this.open },
-    }));
-  };
-}
-customElements.define('accordion-item-ui', UIAccordionItem);
+defineIfFree('accordion-ui', UIAccordion);
+defineIfFree('accordion-item-ui', UIAccordionItem);
 
 export { UIAccordion, UIAccordionItem };

package/components/accordion/class.js

@@ -0,0 +1,132 @@
+/**
+ * Non-side-effect class export for `<accordion-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/accordion`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <accordion-ui>
+ *   <accordion-item-ui text="Section 1">Content for section 1</accordion-item-ui>
+ *   <accordion-item-ui text="Section 2">Content for section 2</accordion-item-ui>
+ * </accordion-ui>
+ *
+ * Accordion container + item pair.
+ * Container manages single/multiple open states.
+ * Items handle their own expand/collapse toggle.
+ *
+ * Events (on accordion-item-ui):
+ *   toggle — { detail: { open } }
+ */
+
+import { UIElement } from '../../core/element.js';
+
+// ── Accordion Container ────────────────────────────────────────
+
+export class UIAccordion extends UIElement {
+  static properties = {
+    multiple: { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    this.addEventListener('toggle', this.#onItemToggle);
+  }
+
+  disconnected() {
+    this.removeEventListener('toggle', this.#onItemToggle);
+  }
+
+  #onItemToggle = (e) => {
+    if (this.multiple) return;
+
+    const target = e.target;
+    if (!target.open) return;
+
+    // Close other items
+    const items = this.querySelectorAll('accordion-item-ui');
+    for (const item of items) {
+      if (item !== target && item.open) {
+        item.open = false;
+      }
+    }
+  };
+}
+
+export class UIAccordionItem extends UIElement {
+  static properties = {
+    text: { type: String,  default: '', reflect: true },
+    open: { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  #bound = false;
+
+  connected() {
+    // Stamp header if not present
+    if (!this.querySelector('[slot="header"]')) {
+      const header = document.createElement('div');
+      header.setAttribute('slot', 'header');
+
+      const label = document.createElement('span');
+      label.setAttribute('slot', 'header-text');
+      header.appendChild(label);
+
+      const caret = document.createElement('icon-ui');
+      caret.setAttribute('name', 'caret-down');
+      caret.setAttribute('slot', 'caret');
+      header.appendChild(caret);
+
+      this.prepend(header);
+    }
+
+    // Stamp content wrapper if not present
+    if (!this.querySelector('[slot="body"]')) {
+      const body = document.createElement('div');
+      body.setAttribute('slot', 'body');
+
+      // Move non-slotted children into body
+      const children = [...this.childNodes].filter(n => {
+        if (n.nodeType === 1) return !n.hasAttribute('slot');
+        return n.nodeType === 3 && n.textContent.trim();
+      });
+      for (const child of children) body.appendChild(child);
+
+      this.appendChild(body);
+    }
+
+    if (!this.#bound) {
+      this.#bound = true;
+      this.addEventListener('click', this.#onClick);
+    }
+  }
+
+  disconnected() {
+    this.removeEventListener('click', this.#onClick);
+    this.#bound = false;
+  }
+
+  render() {
+    const label = this.querySelector('[slot="header-text"]');
+    if (label) label.textContent = this.text;
+  }
+
+  #onClick = (e) => {
+    const header = this.querySelector('[slot="header"]');
+    if (!header || !header.contains(e.target)) return;
+
+    this.open = !this.open;
+    this.dispatchEvent(new CustomEvent('toggle', {
+      bubbles: true,
+      detail: { open: this.open },
+    }));
+  };
+}

package/components/action-list/action-list.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `<action-list-ui>` — Inline list of command actions with keyboard navigation. Fires action event when an item is clicked or activated via keyboard.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/action-list
+ *
+ * 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 UIActionList extends UIElement {
+}

package/components/action-list/action-list.js

@@ -1,149 +1,18 @@
 /**
- * <action-list-ui>
- *   <action-item-ui icon="plus"     text="New Project" value="new"></action-item-ui>
- *   <action-item-ui icon="users"    text="Invite Team" value="invite"></action-item-ui>
- *   <action-item-ui icon="download" text="Export Data" value="export"></action-item-ui>
- * </action-list-ui>
+ * `<action-list-ui>` — auto-registers the tag on import.
  *
- * Inline (non-dropdown) list of command actions. Think of it as a menu that
- * stays open — useful for quick-actions cards, settings rails, sidebar shortcuts.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Differs from <menu-ui> (which renders in a popover) and <list-ui> (which is
- * passive — no hover/click semantics).
+ *   import { UIActionList, UIActionItem } from '@adia-ai/web-components/components/action-list/class';
  *
- * Fires `action` CustomEvent with { value, text, item } when an item is clicked
- * or activated via keyboard (Enter / Space). Keyboard nav: ArrowUp/Down, Home/End.
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+import { UIActionList, UIActionItem } from './class.js';
 
-class UIActionList extends UIElement {
-  static properties = {};
-  static template = () => null;
-
-  #bound = false;
-
-  connected() {
-    this.setAttribute('role', 'list');
-    if (!this.#bound) {
-      this.#bound = true;
-      this.addEventListener('click', this.#onClick);
-      this.addEventListener('keydown', this.#onKey);
-    }
-  }
-
-  disconnected() {
-    this.removeEventListener('click', this.#onClick);
-    this.removeEventListener('keydown', this.#onKey);
-    this.#bound = false;
-  }
-
-  #items() {
-    return Array.from(this.querySelectorAll(':scope > action-item-ui:not([disabled])'));
-  }
-
-  #onClick = (e) => {
-    const item = e.target.closest('action-item-ui');
-    if (!item || item.hasAttribute('disabled')) return;
-    if (!this.contains(item)) return;
-    this.dispatchEvent(new CustomEvent('action', {
-      bubbles: true,
-      detail: { value: item.getAttribute('value') || '', text: item.getAttribute('text') || item.textContent.trim(), item },
-    }));
-  };
-
-  #onKey = (e) => {
-    const items = this.#items();
-    if (!items.length) return;
-    const active = document.activeElement?.closest?.('action-item-ui');
-    const i = active ? items.indexOf(active) : -1;
-    const focus = (idx) => {
-      const next = items[(idx + items.length) % items.length];
-      next?.focus?.({ preventScroll: true });
-    };
-    switch (e.key) {
-      case 'ArrowDown': e.preventDefault(); focus(i + 1); break;
-      case 'ArrowUp':   e.preventDefault(); focus(i - 1); break;
-      case 'Home':      e.preventDefault(); focus(0); break;
-      case 'End':       e.preventDefault(); focus(items.length - 1); break;
-      case 'Enter':
-      case ' ': {
-        if (active) { e.preventDefault(); active.click(); }
-        break;
-      }
-    }
-  };
-}
-
-customElements.define('action-list-ui', UIActionList);
-
-class UIActionItem extends UIElement {
-  static properties = {
-    icon:     { type: String,  default: '', reflect: true },
-    text:     { type: String,  default: '', reflect: true },
-    value:    { type: String,  default: '', reflect: true },
-    variant:  { type: String,  default: 'default', reflect: true },
-    disabled: { type: Boolean, default: false, reflect: true },
-  };
-
-  static template = () => null;
-
-  connected() {
-    this.setAttribute('role', 'listitem');
-    if (!this.hasAttribute('tabindex')) this.setAttribute('tabindex', '0');
-    this.#stamp();
-    this.#syncAria();
-  }
-
-  #stamp() {
-    if (this.querySelector('[slot="text"]')) return;
-
-    if (this.icon) {
-      const iconEl = document.createElement('icon-ui');
-      iconEl.setAttribute('slot', 'icon');
-      iconEl.setAttribute('name', this.icon);
-      this.appendChild(iconEl);
-    }
-
-    if (this.text) {
-      const span = document.createElement('span');
-      span.setAttribute('slot', 'text');
-      span.textContent = this.text;
-      this.appendChild(span);
-    }
-  }
-
-  #syncAria() {
-    if (this.disabled) {
-      this.setAttribute('aria-disabled', 'true');
-      this.setAttribute('tabindex', '-1');
-    } else {
-      this.removeAttribute('aria-disabled');
-      this.setAttribute('tabindex', '0');
-    }
-  }
-
-  render() {
-    const iconEl = this.querySelector('[slot="icon"]');
-    if (this.icon) {
-      if (iconEl) iconEl.setAttribute('name', this.icon);
-      else {
-        const el = document.createElement('icon-ui');
-        el.setAttribute('slot', 'icon');
-        el.setAttribute('name', this.icon);
-        this.prepend(el);
-      }
-    } else if (iconEl) {
-      iconEl.remove();
-    }
-
-    const textEl = this.querySelector('[slot="text"]');
-    if (textEl) textEl.textContent = this.text;
-
-    this.#syncAria();
-  }
-}
-
-customElements.define('action-item-ui', UIActionItem);
+defineIfFree('action-list-ui', UIActionList);
+defineIfFree('action-item-ui', UIActionItem);
 
 export { UIActionList, UIActionItem };

package/components/action-list/class.js

@@ -0,0 +1,156 @@
+/**
+ * Non-side-effect class export for `<action-list-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/action-list`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <action-list-ui>
+ *   <action-item-ui icon="plus"     text="New Project" value="new"></action-item-ui>
+ *   <action-item-ui icon="users"    text="Invite Team" value="invite"></action-item-ui>
+ *   <action-item-ui icon="download" text="Export Data" value="export"></action-item-ui>
+ * </action-list-ui>
+ *
+ * Inline (non-dropdown) list of command actions. Think of it as a menu that
+ * stays open — useful for quick-actions cards, settings rails, sidebar shortcuts.
+ *
+ * Differs from <menu-ui> (which renders in a popover) and <list-ui> (which is
+ * passive — no hover/click semantics).
+ *
+ * Fires `action` CustomEvent with { value, text, item } when an item is clicked
+ * or activated via keyboard (Enter / Space). Keyboard nav: ArrowUp/Down, Home/End.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIActionList extends UIElement {
+  static properties = {};
+  static template = () => null;
+
+  #bound = false;
+
+  connected() {
+    this.setAttribute('role', 'list');
+    if (!this.#bound) {
+      this.#bound = true;
+      this.addEventListener('click', this.#onClick);
+      this.addEventListener('keydown', this.#onKey);
+    }
+  }
+
+  disconnected() {
+    this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('keydown', this.#onKey);
+    this.#bound = false;
+  }
+
+  #items() {
+    return Array.from(this.querySelectorAll(':scope > action-item-ui:not([disabled])'));
+  }
+
+  #onClick = (e) => {
+    const item = e.target.closest('action-item-ui');
+    if (!item || item.hasAttribute('disabled')) return;
+    if (!this.contains(item)) return;
+    this.dispatchEvent(new CustomEvent('action', {
+      bubbles: true,
+      detail: { value: item.getAttribute('value') || '', text: item.getAttribute('text') || item.textContent.trim(), item },
+    }));
+  };
+
+  #onKey = (e) => {
+    const items = this.#items();
+    if (!items.length) return;
+    const active = document.activeElement?.closest?.('action-item-ui');
+    const i = active ? items.indexOf(active) : -1;
+    const focus = (idx) => {
+      const next = items[(idx + items.length) % items.length];
+      next?.focus?.({ preventScroll: true });
+    };
+    switch (e.key) {
+      case 'ArrowDown': e.preventDefault(); focus(i + 1); break;
+      case 'ArrowUp':   e.preventDefault(); focus(i - 1); break;
+      case 'Home':      e.preventDefault(); focus(0); break;
+      case 'End':       e.preventDefault(); focus(items.length - 1); break;
+      case 'Enter':
+      case ' ': {
+        if (active) { e.preventDefault(); active.click(); }
+        break;
+      }
+    }
+  };
+}
+
+export class UIActionItem extends UIElement {
+  static properties = {
+    icon:     { type: String,  default: '', reflect: true },
+    text:     { type: String,  default: '', reflect: true },
+    value:    { type: String,  default: '', reflect: true },
+    variant:  { type: String,  default: 'default', reflect: true },
+    disabled: { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    this.setAttribute('role', 'listitem');
+    if (!this.hasAttribute('tabindex')) this.setAttribute('tabindex', '0');
+    this.#stamp();
+    this.#syncAria();
+  }
+
+  #stamp() {
+    if (this.querySelector('[slot="text"]')) return;
+
+    if (this.icon) {
+      const iconEl = document.createElement('icon-ui');
+      iconEl.setAttribute('slot', 'icon');
+      iconEl.setAttribute('name', this.icon);
+      this.appendChild(iconEl);
+    }
+
+    if (this.text) {
+      const span = document.createElement('span');
+      span.setAttribute('slot', 'text');
+      span.textContent = this.text;
+      this.appendChild(span);
+    }
+  }
+
+  #syncAria() {
+    if (this.disabled) {
+      this.setAttribute('aria-disabled', 'true');
+      this.setAttribute('tabindex', '-1');
+    } else {
+      this.removeAttribute('aria-disabled');
+      this.setAttribute('tabindex', '0');
+    }
+  }
+
+  render() {
+    const iconEl = this.querySelector('[slot="icon"]');
+    if (this.icon) {
+      if (iconEl) iconEl.setAttribute('name', this.icon);
+      else {
+        const el = document.createElement('icon-ui');
+        el.setAttribute('slot', 'icon');
+        el.setAttribute('name', this.icon);
+        this.prepend(el);
+      }
+    } else if (iconEl) {
+      iconEl.remove();
+    }
+
+    const textEl = this.querySelector('[slot="text"]');
+    if (textEl) textEl.textContent = this.text;
+
+    this.#syncAria();
+  }
+}