@adia-ai/web-components 0.4.6 → 0.4.7

package/components/demo-toggle/class.js

@@ -0,0 +1,153 @@
+/**
+ * Non-side-effect class export for `<demo-toggle-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/demo-toggle`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <demo-toggle-ui>
+ *   <section slot="off">…without trait…</section>
+ *   <section slot="on">…with trait…</section>
+ * </demo-toggle-ui>
+ *
+ * Side-by-side "with trait / without trait" comparison primitive.
+ * Renders a header bar with a switch-ui that flips which child slot is
+ * visible. Reflects [data-state="on"|"off"] on the host so consumer CSS
+ * can theme the bar around the active variant.
+ *
+ * Two layout modes:
+ *   default — only the active slot is in the layout (the other is `display: none`).
+ *   data-mode="overlay" — both slots stack on the same coordinates; inactive
+ *     slot is `visibility: hidden` so layout never shifts.
+ *
+ * Authoring API:
+ *   [label-on]  — header label when state=on   (default: "On")
+ *   [label-off] — header label when state=off  (default: "Off")
+ *   [initial]   — "on" | "off"; only consulted when [state] is unset on connect
+ *   [state]     — "on" | "off"; reflected; the live state attribute
+ *
+ * Events:
+ *   change — { detail: { state: "on" | "off" } }
+ *
+ * Keyboard:
+ *   The embedded <switch-ui> handles space + enter via its own keydown wiring.
+ */
+
+import { UIElement } from '../../core/element.js';
+import '../switch/switch.js';
+import '../row/row.js';
+import '../text/text.js';
+
+export class UIDemoToggle extends UIElement {
+  static properties = {
+    labelOn:  { type: String, default: 'On',  attribute: 'label-on',  reflect: true },
+    labelOff: { type: String, default: 'Off', attribute: 'label-off', reflect: true },
+    initial:  { type: String, default: 'off', reflect: true },
+    state:    { type: String, default: '',    reflect: true },
+  };
+
+  // Header bar with a switch + active label. Stamped once per class via
+  // static parts; live label text is updated in render() so the same
+  // template covers every (label-on, label-off, state) tuple.
+  static parts = {
+    bar: `
+      <row-ui slot="bar" gap="3" align="center" data-demo-toggle-bar>
+        <text-ui slot="label" data-demo-toggle-label></text-ui>
+        <switch-ui slot="switch" data-demo-toggle-switch></switch-ui>
+      </row-ui>
+    `,
+  };
+
+  static template = () => null;
+
+  #bar = null;
+  #switch = null;
+  #label = null;
+  #bound = false;
+
+  connected() {
+    // Resolve the initial state. Honor [state] if explicitly authored;
+    // otherwise fall back to [initial] (default "off"). Anything other
+    // than the literal "on" coerces to "off" so authors can't poison
+    // the data-state attribute with arbitrary values.
+    if (!this.state) {
+      const seed = (this.initial === 'on') ? 'on' : 'off';
+      this.state = seed;
+    } else {
+      this.state = (this.state === 'on') ? 'on' : 'off';
+    }
+
+    // Stamp the header bar lazily — `this.ensure('bar')` clones the
+    // blueprint into the light DOM the first time it's called.
+    this.#bar = this.ensure('bar');
+    this.#switch = this.#bar.querySelector('[data-demo-toggle-switch]');
+    this.#label = this.#bar.querySelector('[data-demo-toggle-label]');
+
+    if (!this.#bound) {
+      this.#bound = true;
+      this.#switch.addEventListener('change', this.#onSwitchChange);
+    }
+  }
+
+  disconnected() {
+    if (this.#switch) {
+      this.#switch.removeEventListener('change', this.#onSwitchChange);
+    }
+    this.#bar = null;
+    this.#switch = null;
+    this.#label = null;
+    this.#bound = false;
+  }
+
+  render() {
+    if (!this.#bar) return;
+    const on = this.state === 'on';
+
+    // Sync the embedded switch to the host's state. checked is a
+    // reflected property; the assignment fires no event because
+    // syncValue() short-circuits when the next state matches.
+    if (this.#switch.checked !== on) {
+      this.#switch.checked = on;
+    }
+
+    if (this.#label) {
+      this.#label.textContent = on ? this.labelOn : this.labelOff;
+    }
+  }
+
+  /**
+   * Public toggle method — flips the host between on and off and emits
+   * a `change` event. Mirrors the click-on-switch path so consumers
+   * can drive the state from outside without touching the embedded
+   * switch directly.
+   */
+  toggle() {
+    this.state = (this.state === 'on') ? 'off' : 'on';
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { state: this.state },
+    }));
+  }
+
+  #onSwitchChange = (e) => {
+    // The embedded <switch-ui> fires a bubbling `change`. Stop it at the
+    // host boundary — we re-dispatch our own `change` with detail.state
+    // so consumers see exactly one event per toggle, not the inner
+    // switch's bare event AND our annotated one.
+    e.stopPropagation();
+    const next = this.#switch.checked ? 'on' : 'off';
+    if (next === this.state) return;
+    this.state = next;
+    this.dispatchEvent(new CustomEvent('change', {
+      bubbles: true,
+      detail: { state: this.state },
+    }));
+  };
+}

package/components/demo-toggle/demo-toggle.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `<demo-toggle-ui>` — Side-by-side comparison primitive — header bar with a switch + two child slots ("on" / "off"); toggling the switch swaps which slot is visible. Used on trait detail pages to show "with trait" vs "without trait" on the same chrome. data-mode="overlay" stacks the slots on the same coordinates so layout never shifts.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/demo-toggle
+ *
+ * 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 UIDemoToggle extends UIElement {
+  /** Initial state when [state] is not set on connect ("on" | "off"). */
+  initial: 'on' | 'off';
+  /** Header label rendered when state is "off". */
+  labelOff: string;
+  /** Header label rendered when state is "on". */
+  labelOn: string;
+  /** Current toggle state ("on" | "off"). Reflected as data-state on the host. */
+  state: '' | 'on' | 'off';
+}

package/components/demo-toggle/demo-toggle.js

@@ -1,144 +1,17 @@
 /**
- * <demo-toggle-ui>
- *   <section slot="off">…without trait…</section>
- *   <section slot="on">…with trait…</section>
- * </demo-toggle-ui>
+ * `<demo-toggle-ui>` — auto-registers the tag on import.
  *
- * Side-by-side "with trait / without trait" comparison primitive.
- * Renders a header bar with a switch-ui that flips which child slot is
- * visible. Reflects [data-state="on"|"off"] on the host so consumer CSS
- * can theme the bar around the active variant.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Two layout modes:
- *   default — only the active slot is in the layout (the other is `display: none`).
- *   data-mode="overlay" — both slots stack on the same coordinates; inactive
- *     slot is `visibility: hidden` so layout never shifts.
+ *   import { UIDemoToggle } from '@adia-ai/web-components/components/demo-toggle/class';
  *
- * Authoring API:
- *   [label-on]  — header label when state=on   (default: "On")
- *   [label-off] — header label when state=off  (default: "Off")
- *   [initial]   — "on" | "off"; only consulted when [state] is unset on connect
- *   [state]     — "on" | "off"; reflected; the live state attribute
- *
- * Events:
- *   change — { detail: { state: "on" | "off" } }
- *
- * Keyboard:
- *   The embedded <switch-ui> handles space + enter via its own keydown wiring.
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-import '../switch/switch.js';
-import '../row/row.js';
-import '../text/text.js';
-
-class UIDemoToggle extends UIElement {
-  static properties = {
-    labelOn:  { type: String, default: 'On',  attribute: 'label-on',  reflect: true },
-    labelOff: { type: String, default: 'Off', attribute: 'label-off', reflect: true },
-    initial:  { type: String, default: 'off', reflect: true },
-    state:    { type: String, default: '',    reflect: true },
-  };
-
-  // Header bar with a switch + active label. Stamped once per class via
-  // static parts; live label text is updated in render() so the same
-  // template covers every (label-on, label-off, state) tuple.
-  static parts = {
-    bar: `
-      <row-ui slot="bar" gap="3" align="center" data-demo-toggle-bar>
-        <text-ui slot="label" data-demo-toggle-label></text-ui>
-        <switch-ui slot="switch" data-demo-toggle-switch></switch-ui>
-      </row-ui>
-    `,
-  };
-
-  static template = () => null;
-
-  #bar = null;
-  #switch = null;
-  #label = null;
-  #bound = false;
-
-  connected() {
-    // Resolve the initial state. Honor [state] if explicitly authored;
-    // otherwise fall back to [initial] (default "off"). Anything other
-    // than the literal "on" coerces to "off" so authors can't poison
-    // the data-state attribute with arbitrary values.
-    if (!this.state) {
-      const seed = (this.initial === 'on') ? 'on' : 'off';
-      this.state = seed;
-    } else {
-      this.state = (this.state === 'on') ? 'on' : 'off';
-    }
-
-    // Stamp the header bar lazily — `this.ensure('bar')` clones the
-    // blueprint into the light DOM the first time it's called.
-    this.#bar = this.ensure('bar');
-    this.#switch = this.#bar.querySelector('[data-demo-toggle-switch]');
-    this.#label = this.#bar.querySelector('[data-demo-toggle-label]');
-
-    if (!this.#bound) {
-      this.#bound = true;
-      this.#switch.addEventListener('change', this.#onSwitchChange);
-    }
-  }
-
-  disconnected() {
-    if (this.#switch) {
-      this.#switch.removeEventListener('change', this.#onSwitchChange);
-    }
-    this.#bar = null;
-    this.#switch = null;
-    this.#label = null;
-    this.#bound = false;
-  }
-
-  render() {
-    if (!this.#bar) return;
-    const on = this.state === 'on';
-
-    // Sync the embedded switch to the host's state. checked is a
-    // reflected property; the assignment fires no event because
-    // syncValue() short-circuits when the next state matches.
-    if (this.#switch.checked !== on) {
-      this.#switch.checked = on;
-    }
-
-    if (this.#label) {
-      this.#label.textContent = on ? this.labelOn : this.labelOff;
-    }
-  }
-
-  /**
-   * Public toggle method — flips the host between on and off and emits
-   * a `change` event. Mirrors the click-on-switch path so consumers
-   * can drive the state from outside without touching the embedded
-   * switch directly.
-   */
-  toggle() {
-    this.state = (this.state === 'on') ? 'off' : 'on';
-    this.dispatchEvent(new CustomEvent('change', {
-      bubbles: true,
-      detail: { state: this.state },
-    }));
-  }
-
-  #onSwitchChange = (e) => {
-    // The embedded <switch-ui> fires a bubbling `change`. Stop it at the
-    // host boundary — we re-dispatch our own `change` with detail.state
-    // so consumers see exactly one event per toggle, not the inner
-    // switch's bare event AND our annotated one.
-    e.stopPropagation();
-    const next = this.#switch.checked ? 'on' : 'off';
-    if (next === this.state) return;
-    this.state = next;
-    this.dispatchEvent(new CustomEvent('change', {
-      bubbles: true,
-      detail: { state: this.state },
-    }));
-  };
-}
+import { defineIfFree } from '../../core/register.js';
+import { UIDemoToggle } from './class.js';
 
-customElements.define('demo-toggle-ui', UIDemoToggle);
+defineIfFree('demo-toggle-ui', UIDemoToggle);
 
 export { UIDemoToggle };

package/components/description-list/class.js

@@ -0,0 +1,86 @@
+/**
+ * Non-side-effect class export for `<description-list-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/description-list`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <description-list-ui> — Semantic dl/dt/dd wrapper for key-value metadata.
+ *
+ * Pure layout component. Renders terms and descriptions in a grid.
+ *
+ * Declarative use (recommended — preserves semantics for SSR + AT):
+ *   <description-list-ui>
+ *     <dt>Status</dt><dd>Active</dd>
+ *     <dt>Plan</dt><dd>Pro</dd>
+ *   </description-list-ui>
+ *
+ * Programmatic use:
+ *   <description-list-ui
+ *     items='[{"term":"Status","description":"Active"}]'></description-list-ui>
+ *
+ * Props:
+ *   layout    — "stacked" (term above, default) | "inline" (term : value on one row)
+ *   align     — "start" (default) | "between" (space-between for inline layout)
+ *   items     — optional JSON array of {term, description} pairs
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIDescriptionList extends UIElement {
+  static properties = {
+    layout: { type: String, default: 'stacked', reflect: true },
+    align:  { type: String, default: 'start', reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    // ARIA 1.2: list role requires listitem children, but <dt>/<dd>
+    // aren't listitems. group role is the accurate fit for a
+    // labeled-pairs grouping.
+    this.setAttribute('role', 'group');
+  }
+
+  render() {
+    const items = this.#resolveItems();
+    if (!items.length) return; // preserve declarative children
+
+    this.innerHTML = items.map(({ term, description }) => `
+      <dt data-dl-term>${this.#escape(term)}</dt>
+      <dd data-dl-desc>${this.#escape(description)}</dd>
+    `).join('');
+  }
+
+  #resolveItems() {
+    if (Array.isArray(this._items) && this._items.length) return this._items;
+    const attr = this.getAttribute('items');
+    if (attr) {
+      try {
+        const parsed = JSON.parse(attr);
+        if (Array.isArray(parsed)) return parsed;
+      } catch { /* fall through */ }
+    }
+    return [];
+  }
+
+  set items(v) {
+    this._items = Array.isArray(v) ? v : [];
+    this.render();
+  }
+
+  get items() {
+    return this._items || [];
+  }
+
+  #escape(s) {
+    return String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+  }
+}

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

@@ -0,0 +1,21 @@
+/**
+ * `<description-list-ui>` — Semantic key-value list (dl/dt/dd). Preserves native HTML semantics for screen readers and SSR. Layout supports stacked (default) or inline.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/description-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 UIDescriptionList extends UIElement {
+  /** Optional JSON array of {term, description} — alternative to declarative <dt>/<dd> children */
+  items: unknown[];
+  /** Alignment for inline layout — between = term left, value right. */
+  align: 'start' | 'between';
+  /** stacked: term above description. inline: term and description on one row. */
+  layout: 'stacked' | 'inline';
+}

package/components/description-list/description-list.js

@@ -1,76 +1,17 @@
 /**
- * <description-list-ui> — Semantic dl/dt/dd wrapper for key-value metadata.
+ * `<description-list-ui>` — auto-registers the tag on import.
  *
- * Pure layout component. Renders terms and descriptions in a grid.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Declarative use (recommended — preserves semantics for SSR + AT):
- *   <description-list-ui>
- *     <dt>Status</dt><dd>Active</dd>
- *     <dt>Plan</dt><dd>Pro</dd>
- *   </description-list-ui>
+ *   import { UIDescriptionList } from '@adia-ai/web-components/components/description-list/class';
  *
- * Programmatic use:
- *   <description-list-ui
- *     items='[{"term":"Status","description":"Active"}]'></description-list-ui>
- *
- * Props:
- *   layout    — "stacked" (term above, default) | "inline" (term : value on one row)
- *   align     — "start" (default) | "between" (space-between for inline layout)
- *   items     — optional JSON array of {term, description} pairs
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIDescriptionList extends UIElement {
-  static properties = {
-    layout: { type: String, default: 'stacked', reflect: true },
-    align:  { type: String, default: 'start', reflect: true },
-  };
-
-  static template = () => null;
-
-  connected() {
-    // ARIA 1.2: list role requires listitem children, but <dt>/<dd>
-    // aren't listitems. group role is the accurate fit for a
-    // labeled-pairs grouping.
-    this.setAttribute('role', 'group');
-  }
-
-  render() {
-    const items = this.#resolveItems();
-    if (!items.length) return; // preserve declarative children
-
-    this.innerHTML = items.map(({ term, description }) => `
-      <dt data-dl-term>${this.#escape(term)}</dt>
-      <dd data-dl-desc>${this.#escape(description)}</dd>
-    `).join('');
-  }
-
-  #resolveItems() {
-    if (Array.isArray(this._items) && this._items.length) return this._items;
-    const attr = this.getAttribute('items');
-    if (attr) {
-      try {
-        const parsed = JSON.parse(attr);
-        if (Array.isArray(parsed)) return parsed;
-      } catch { /* fall through */ }
-    }
-    return [];
-  }
-
-  set items(v) {
-    this._items = Array.isArray(v) ? v : [];
-    this.render();
-  }
-
-  get items() {
-    return this._items || [];
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIDescriptionList } from './class.js';
 
-  #escape(s) {
-    return String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-  }
-}
+defineIfFree('description-list-ui', UIDescriptionList);
 
-customElements.define('description-list-ui', UIDescriptionList);
 export { UIDescriptionList };

package/components/divider/class.js

@@ -0,0 +1,57 @@
+/**
+ * Non-side-effect class export for `<divider-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/divider`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <divider-ui></divider-ui>
+ * <divider-ui label="or"></divider-ui>
+ * <divider-ui vertical></divider-ui>
+ *
+ * Horizontal or vertical divider with optional label.
+ * Renders as a simple line, or a line broken by centered text.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIDivider extends UIElement {
+  static properties = {
+    label:    { type: String,  default: '', reflect: true },
+    vertical: { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    this.setAttribute('role', 'separator');
+  }
+
+  render() {
+    if (this.vertical) {
+      this.setAttribute('aria-orientation', 'vertical');
+    } else {
+      this.removeAttribute('aria-orientation');
+    }
+
+    if (this.label) {
+      let span = this.querySelector('[slot="label"]');
+      if (!span) {
+        span = document.createElement('span');
+        span.setAttribute('slot', 'label');
+        this.appendChild(span);
+      }
+      span.textContent = this.label;
+    } else {
+      const span = this.querySelector('[slot="label"]');
+      if (span) span.remove();
+    }
+  }
+}

package/components/divider/divider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `<divider-ui>` — Horizontal or vertical divider with optional label.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/divider
+ *
+ * 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 UIDivider extends UIElement {
+  /** Center label text */
+  label: string;
+  /** Vertical orientation */
+  vertical: boolean;
+}

package/components/divider/divider.js

@@ -1,47 +1,17 @@
 /**
- * <divider-ui></divider-ui>
- * <divider-ui label="or"></divider-ui>
- * <divider-ui vertical></divider-ui>
+ * `<divider-ui>` — auto-registers the tag on import.
  *
- * Horizontal or vertical divider with optional label.
- * Renders as a simple line, or a line broken by centered text.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIDivider } from '@adia-ai/web-components/components/divider/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIDivider extends UIElement {
-  static properties = {
-    label:    { type: String,  default: '', reflect: true },
-    vertical: { type: Boolean, default: false, reflect: true },
-  };
-
-  static template = () => null;
-
-  connected() {
-    this.setAttribute('role', 'separator');
-  }
-
-  render() {
-    if (this.vertical) {
-      this.setAttribute('aria-orientation', 'vertical');
-    } else {
-      this.removeAttribute('aria-orientation');
-    }
+import { defineIfFree } from '../../core/register.js';
+import { UIDivider } from './class.js';
 
-    if (this.label) {
-      let span = this.querySelector('[slot="label"]');
-      if (!span) {
-        span = document.createElement('span');
-        span.setAttribute('slot', 'label');
-        this.appendChild(span);
-      }
-      span.textContent = this.label;
-    } else {
-      const span = this.querySelector('[slot="label"]');
-      if (span) span.remove();
-    }
-  }
-}
-customElements.define('divider-ui', UIDivider);
+defineIfFree('divider-ui', UIDivider);
 
 export { UIDivider };