@adia-ai/web-components 0.4.6 → 0.4.8

package/README.md

@@ -175,6 +175,45 @@ Authoring rules (enforced by `ui-audit-coherence`):
 5. **Light DOM only.** No `::part()`, `::slotted()`, shadow roots. Use
    attribute selectors on children: `:scope > [slot="icon"]`.
 
+### `static template` is a closure — import what it references
+
+The `static template` property is a regular JavaScript closure (typically a tagged template literal — `() => html` followed by the template body). Any signal, variable, or function it references must be **lexically in scope** at the file where the class is defined. This is JavaScript scoping, not anything AdiaUI-specific — but it surprises authors coming from frameworks where templates magically receive props.
+
+```js
+// ❌ WRONG — ReferenceError at runtime: minL is not defined
+//   (no import; the template function can't see minL just because
+//    it's exported elsewhere in the monorepo)
+class MyPanel extends UIElement {
+  static template = () => html`<div>L: ${minL.value}</div>`;
+}
+
+// ✅ RIGHT — import the signal locally
+import { minL } from './state.js';
+
+class MyPanel extends UIElement {
+  static template = () => html`<div>L: ${minL.value}</div>`;
+}
+```
+
+The error surfaces in the browser console as `ReferenceError: minL is not defined` at first render — not at module load, not at `tsc --noEmit`. **The trace points at the template function body**, not at the missing import, which is the disorienting part.
+
+If your primitive needs external reactive state that varies per-instance, **expose it as a property** rather than reaching for module-scoped signals:
+
+```js
+// ✅ Best — per-instance reactive prop
+class MyPanel extends UIElement {
+  static properties = {
+    minL: { type: Number, default: 0 },
+  };
+  static template = el => html`<div>L: ${el.minL}</div>`;
+}
+
+// Consumer:
+<my-panel .minL=${minL}></my-panel>  // signal binds reactively per ADR-template-binding
+```
+
+The `el` parameter is the element instance — every signal-backed property is reactively read.
+
 Full authoring contract: [`docs/specs/component-token-contract.md`](../../docs/specs/component-token-contract.md).
 The `adia-ui-author` skill encodes the 20 non-negotiable rules.
 

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.a2ui.json

@@ -29,6 +29,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "change": {
         "description": "Fired when the set of open panels changes"

package/components/accordion/accordion.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `<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 build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export type AccordionChangeEvent = CustomEvent<unknown>;
+
+export class UIAccordion extends UIElement {
+  /** Allow multiple panels to be open simultaneously */
+  multiple: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAccordion, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: AccordionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

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/accordion.yaml

@@ -7,6 +7,10 @@ component: Accordion
 category: container
 version: 1
 description: Accordion container managing single/multiple open states.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
 props:
   multiple:
     description: Allow multiple panels to be open simultaneously

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.a2ui.json

@@ -24,6 +24,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "navigation",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "action": {
         "description": "Fired on action."

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

@@ -0,0 +1,25 @@
+/**
+ * `<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 build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export type ActionListActionEvent = CustomEvent<unknown>;
+
+export class UIActionList extends UIElement {
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIActionList, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'action', listener: (ev: ActionListActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

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/action-list.yaml

@@ -8,6 +8,10 @@ category: navigation
 version: 1
 description: Inline list of command actions with keyboard navigation. Fires action event when an
   item is clicked or activated via keyboard.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
 props: {}
 events:
   action: