@adia-ai/web-components 0.4.5 → 0.4.7

package/components/field/field.js

@@ -1,256 +1,17 @@
 /**
- * field-ui — Labeled field wrapper.
+ * `<field-ui>` — auto-registers the tag on import.
  *
- *   <field-ui label="Email" hint="We'll never share" required>
- *     <input-ui value="you@example.com" type="email"></input-ui>
- *     <span slot="trailing">Optional</span>
- *     <button-ui slot="action" icon="x" aria-label="Clear"></button-ui>
- *   </field-ui>
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Wraps a form control with its label + optional hint, error, trailing,
- * and action regions. The host renders a real `<label for="…">` bound
- * to the slotted control's id (auto-minted when missing) so clicking
- * the label focuses the control — an affordance the previous
- * `<input-ui label="…">` pattern lacked.
+ *   import { UIField } from '@adia-ai/web-components/components/field/class';
  *
- * ### Layout — single grid, slot-positioned
- *
- * field-ui is a CSS grid; children are placed by `[slot]` attribute:
- *
- *   slot="label"    → label cell      (mounted by field-ui)
- *   slot="trailing" → row 1, right
- *   (no slot)       → control cell
- *   slot="action"   → adjacent to control
- *   slot="hint"     → message row     (mounted by field-ui)
- *   slot="error"    → message row     (mounted by field-ui)
- *
- * The template adapts (via `:has()`) to which slots are present so empty
- * tracks don't leak column-gap. Inline mode flattens the content slots
- * onto a single row by retuning columns; message stays below.
- *
- * No DOM reparenting; CSS positions children directly. A small
- * MutationObserver watches childList so a swapped-in control gets its
- * `for=` and `aria-describedby` rebound.
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
-import { UIElement } from '../../core/element.js';
-
-class UIField extends UIElement {
-  static properties = {
-    label:    { type: String,  default: '',    reflect: true },
-    hint:     { type: String,  default: '',    reflect: true },
-    required: { type: Boolean, default: false, reflect: true },
-    inline:   { type: Boolean, default: false, reflect: true },
-  };
-
-  // The validation message lives on the child control (UIFormElement.error
-  // is the single source of truth — validity is a property of the value, not
-  // of the layout wrapper). field-ui mirrors the child's error string into
-  // its own [data-field-error] slot so the validation message renders below
-  // the control. See docs/specs/component-token-contract.md "Toggle state
-  // naming" / open decisions resolution log.
-  get error() {
-    const ctrl = this.#findControl();
-    return ctrl?.error ?? '';
-  }
-
-  static template = () => null;
-
-  #labelEl = null;
-  #labelMark = null;
-  #hintEl = null;
-  #errorEl = null;
-  #mo = null;
-
-  // Label click → focus the first focusable descendant of the slotted
-  // control. The native `<label for="x">` affordance focuses the host
-  // by id, which for a custom-element control falls through to body
-  // (host typically tabindex=-1).
-  #onLabelClick = (e) => {
-    const ctrl = this.#findControl();
-    if (!ctrl) return;
-    const focusable = this.#firstFocusable(ctrl);
-    if (!focusable) return;
-    e.preventDefault();
-    focusable.focus();
-  };
-
-  connected() {
-    this.#ensureLabelElement();
-    this.#ensureHintElement();
-    this.#ensureErrorElement();
-    this.#bindForToControl();
-    this.#bindErrorListener();
-    this.#labelEl?.addEventListener('click', this.#onLabelClick);
-    this.#mo = new MutationObserver(() => {
-      this.#bindForToControl();
-      this.#bindErrorListener();
-      this.#wireAriaDescribedBy();
-      this.#syncErrorMessage();
-    });
-    this.#mo.observe(this, { childList: true });
-    this.#syncErrorMessage();
-  }
-
-  disconnected() {
-    this.#mo?.disconnect();
-    this.#mo = null;
-    this.#unbindErrorListener();
-    this.#labelEl?.removeEventListener('click', this.#onLabelClick);
-    this.#labelEl = null;
-    this.#labelMark = null;
-    this.#hintEl = null;
-    this.#errorEl = null;
-  }
-
-  render() {
-    if (this.#labelEl) {
-      this.#labelEl.childNodes[0] && (this.#labelEl.childNodes[0].nodeValue = this.label || '');
-    }
-    if (this.#labelMark) this.#labelMark.hidden = !this.required;
-    if (this.#hintEl) {
-      this.#hintEl.textContent = this.hint || '';
-      this.#hintEl.hidden = !this.hint || Boolean(this.error);
-    }
-    this.#syncErrorMessage();
-    this.#wireAriaDescribedBy();
-  }
-
-  // Mirror child.error → #errorEl. Called on render, MutationObserver
-  // changes, and the child's `invalid`/`change`/`input` events.
-  #syncErrorMessage() {
-    if (!this.#errorEl) return;
-    const msg = this.error;
-    this.#errorEl.textContent = msg || '';
-    this.#errorEl.hidden = !msg;
-  }
-
-  #onChildEvent = () => {
-    this.#syncErrorMessage();
-    this.#wireAriaDescribedBy();
-  };
-
-  #boundErrorTarget = null;
-
-  #bindErrorListener() {
-    const ctrl = this.#findControl();
-    if (ctrl === this.#boundErrorTarget) return;
-    this.#unbindErrorListener();
-    if (!ctrl) return;
-    this.#boundErrorTarget = ctrl;
-    ctrl.addEventListener('invalid', this.#onChildEvent, true);
-    ctrl.addEventListener('change',  this.#onChildEvent);
-    ctrl.addEventListener('input',   this.#onChildEvent);
-  }
-
-  #unbindErrorListener() {
-    const ctrl = this.#boundErrorTarget;
-    if (!ctrl) return;
-    ctrl.removeEventListener('invalid', this.#onChildEvent, true);
-    ctrl.removeEventListener('change',  this.#onChildEvent);
-    ctrl.removeEventListener('input',   this.#onChildEvent);
-    this.#boundErrorTarget = null;
-  }
-
-  // ── Private ───────────────────────────────────────────────────────
-
-  #ensureLabelElement() {
-    this.#labelEl = this.querySelector(':scope > [data-field-label]');
-    if (!this.#labelEl) {
-      const el = document.createElement('label');
-      el.setAttribute('slot', 'label');
-      el.setAttribute('data-field-label', '');
-      el.appendChild(document.createTextNode(this.label || ''));
-      // Prepend so source-order matches visual order (label before
-      // control). Not strictly required since CSS uses grid-area, but
-      // it keeps DevTools / a11y tree readings sensible.
-      this.prepend(el);
-      this.#labelEl = el;
-    }
-    this.#labelMark = this.#labelEl.querySelector('[data-field-required]');
-    if (!this.#labelMark) {
-      const mark = document.createElement('span');
-      mark.setAttribute('data-field-required', '');
-      mark.setAttribute('aria-hidden', 'true');
-      mark.textContent = '*';
-      mark.hidden = true;
-      this.#labelEl.appendChild(mark);
-      this.#labelMark = mark;
-    }
-  }
-
-  #ensureHintElement() {
-    this.#hintEl = this.querySelector(':scope > [data-field-hint]');
-    if (this.#hintEl) return;
-    const el = document.createElement('div');
-    el.setAttribute('slot', 'hint');
-    el.setAttribute('data-field-hint', '');
-    el.setAttribute('id', UIField.#nextMsgId('hint'));
-    el.hidden = true;
-    this.appendChild(el);
-    this.#hintEl = el;
-  }
-
-  #ensureErrorElement() {
-    this.#errorEl = this.querySelector(':scope > [data-field-error]');
-    if (this.#errorEl) return;
-    const el = document.createElement('div');
-    el.setAttribute('slot', 'error');
-    el.setAttribute('data-field-error', '');
-    el.setAttribute('id', UIField.#nextMsgId('err'));
-    el.setAttribute('role', 'alert');
-    el.hidden = true;
-    this.appendChild(el);
-    this.#errorEl = el;
-  }
-
-  #bindForToControl() {
-    if (!this.#labelEl) return;
-    const control = this.#findControl();
-    if (!control) {
-      this.#labelEl.removeAttribute('for');
-      return;
-    }
-    if (!control.id) control.id = UIField.#nextId();
-    this.#labelEl.setAttribute('for', control.id);
-  }
-
-  /** Wire `aria-describedby` on the slotted control to the hint/error
-   *  ids. Keeps any consumer-set describedby ids; appends ours. */
-  #wireAriaDescribedBy() {
-    const ctrl = this.#findControl();
-    if (!ctrl) return;
-    const ours = new Set();
-    if (this.#hintEl && !this.#hintEl.hidden) ours.add(this.#hintEl.id);
-    if (this.#errorEl && !this.#errorEl.hidden) ours.add(this.#errorEl.id);
-    const existing = (ctrl.getAttribute('aria-describedby') || '')
-      .split(/\s+/).filter((s) => s && !s.startsWith('field-hint-') && !s.startsWith('field-err-'));
-    const merged = [...existing, ...ours].join(' ').trim();
-    if (merged) ctrl.setAttribute('aria-describedby', merged);
-    else ctrl.removeAttribute('aria-describedby');
-  }
-
-  /** The default-slot control — first child without a `slot` attribute. */
-  #findControl() {
-    for (const ch of this.children) {
-      if (!ch.hasAttribute('slot')) return ch;
-    }
-    return null;
-  }
 
-  /** First focusable descendant (or self) of `root`. Looks for native
-   *  `<input>`, `<textarea>`, `<select>`, `<button>`, `[contenteditable]`,
-   *  and any `[tabindex]` ≥ 0. Light DOM only. */
-  #firstFocusable(root) {
-    const SEL = 'input, textarea, select, button, [contenteditable], [tabindex]:not([tabindex="-1"])';
-    if (root.matches?.(SEL)) return root;
-    return root.querySelector?.(SEL) ?? null;
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIField } from './class.js';
 
-  static #idSeq = 0;
-  static #nextId() { return `field-ctl-${++UIField.#idSeq}`; }
-  static #msgSeq = 0;
-  static #nextMsgId(kind) { return `field-${kind}-${++UIField.#msgSeq}`; }
-}
+defineIfFree('field-ui', UIField);
 
-customElements.define('field-ui', UIField);
 export { UIField };

package/components/fields/class.js

@@ -0,0 +1,106 @@
+/**
+ * Non-side-effect class export for `<fields-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/fields`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * fields-ui — Container for a group of <field-ui> children laid out
+ * on a shared grid.
+ *
+ *   <fields-ui>                                      <!-- 6-col grid -->
+ *     <field-ui label="Title">…</field-ui>           <!-- rows=6 (full row) -->
+ *     <field-ui label="Status"   rows="2">…</field-ui>
+ *     <field-ui label="Priority" rows="2">…</field-ui>
+ *     <field-ui label="Group"    rows="2">…</field-ui>
+ *   </fields-ui>
+ *
+ *   <fields-ui inline>            <!-- propagate inline to every child -->
+ *     <field-ui label="Search">…</field-ui>
+ *     <field-ui label="Kind">…</field-ui>
+ *   </fields-ui>
+ *
+ * The shared grid keeps siblings on the same row aligned. The [inline]
+ * attribute is mirrored onto every direct <field-ui> child so a whole
+ * sub-form switches layout mode from one host attribute. A small
+ * MutationObserver re-syncs when children are added/removed.
+ *
+ * Per-field column span is driven by the child's [rows="1..6"]
+ * attribute — pure CSS via attribute selectors in fields.css. The
+ * default span (no attr) is the full row.
+ */
+import { UIElement } from '../../core/element.js';
+
+export class UIFields extends UIElement {
+  static properties = {
+    inline:  { type: Boolean, default: false, reflect: true },
+    columns: { type: Number,  default: 6,     reflect: true },
+  };
+
+  static template = () => null;
+
+  /** @type {MutationObserver | null} */
+  #mo = null;
+
+  connected() {
+    this.#syncInline();
+    this.#mo = new MutationObserver((records) => {
+      // Only re-sync on childList changes that involve direct <field-ui>
+      // children — attribute mutations on grandchildren aren't ours to
+      // care about.
+      for (const r of records) {
+        if (r.type !== 'childList') continue;
+        if (this.#hasFieldChild(r.addedNodes) || this.#hasFieldChild(r.removedNodes)) {
+          this.#syncInline();
+          return;
+        }
+      }
+    });
+    this.#mo.observe(this, { childList: true });
+  }
+
+  disconnected() {
+    this.#mo?.disconnect();
+    this.#mo = null;
+  }
+
+  render() {
+    // UIElement calls render() on attribute → property reflection. The
+    // inline attr's effect is propagation-to-children, not host markup.
+    this.#syncInline();
+  }
+
+  // ── Private ────────────────────────────────────────────────────
+
+  #syncInline() {
+    const inline = this.hasAttribute('inline');
+    for (const child of this.children) {
+      if (child.localName !== 'field-ui') continue;
+      if (inline) {
+        if (!child.hasAttribute('inline')) child.setAttribute('inline', '');
+      } else {
+        // Only remove if WE set it. We can't tell, so we always remove —
+        // that's the documented contract: <fields-ui inline> is the
+        // single source of truth for child inline-mode within the group.
+        if (child.hasAttribute('inline')) child.removeAttribute('inline');
+      }
+    }
+  }
+
+  /** @param {NodeList} nodes */
+  #hasFieldChild(nodes) {
+    for (const n of nodes) {
+      if (n.nodeType === 1 && /** @type {Element} */ (n).localName === 'field-ui') {
+        return true;
+      }
+    }
+    return false;
+  }
+}

package/components/fields/fields.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `<fields-ui>` — Container for a group of <field-ui> children, laid out on a shared 6-column grid. Each <field-ui> spans the full row by default; opt into a narrower span via [rows="1..6"]. Setting [inline] on the host propagates the inline mode to every direct <field-ui> child so a whole sub-form can switch label-position without per-field edits. The grid alignment lets siblings on the same row line up cleanly — consistent label columns + consistent control columns — without the wrap-flex jitter of <row-ui wrap>.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/fields
+ *
+ * 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 UIFields extends UIElement {
+  /** Number of grid columns the row uses. Defaults to 6 — common multiples (1/2/3/6) divide cleanly. <field-ui rows="N"> spans `N` of these columns. Override per-instance for tighter 4-column or wider 12-column compositions. */
+  columns: number;
+  /** Propagate the inline layout mode to every direct <field-ui> child. Equivalent to authoring `inline` on each child but drives the whole group from one place. Toggle is reactive — flipping the attribute on the host re-syncs all children. */
+  inline: boolean;
+}

package/components/fields/fields.js

@@ -1,96 +1,17 @@
 /**
- * fields-ui — Container for a group of <field-ui> children laid out
- * on a shared grid.
+ * `<fields-ui>` — auto-registers the tag on import.
  *
- *   <fields-ui>                                      <!-- 6-col grid -->
- *     <field-ui label="Title">…</field-ui>           <!-- rows=6 (full row) -->
- *     <field-ui label="Status"   rows="2">…</field-ui>
- *     <field-ui label="Priority" rows="2">…</field-ui>
- *     <field-ui label="Group"    rows="2">…</field-ui>
- *   </fields-ui>
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- *   <fields-ui inline>            <!-- propagate inline to every child -->
- *     <field-ui label="Search">…</field-ui>
- *     <field-ui label="Kind">…</field-ui>
- *   </fields-ui>
+ *   import { UIFields } from '@adia-ai/web-components/components/fields/class';
  *
- * The shared grid keeps siblings on the same row aligned. The [inline]
- * attribute is mirrored onto every direct <field-ui> child so a whole
- * sub-form switches layout mode from one host attribute. A small
- * MutationObserver re-syncs when children are added/removed.
- *
- * Per-field column span is driven by the child's [rows="1..6"]
- * attribute — pure CSS via attribute selectors in fields.css. The
- * default span (no attr) is the full row.
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
-import { UIElement } from '../../core/element.js';
-
-class UIFields extends UIElement {
-  static properties = {
-    inline:  { type: Boolean, default: false, reflect: true },
-    columns: { type: Number,  default: 6,     reflect: true },
-  };
-
-  static template = () => null;
-
-  /** @type {MutationObserver | null} */
-  #mo = null;
-
-  connected() {
-    this.#syncInline();
-    this.#mo = new MutationObserver((records) => {
-      // Only re-sync on childList changes that involve direct <field-ui>
-      // children — attribute mutations on grandchildren aren't ours to
-      // care about.
-      for (const r of records) {
-        if (r.type !== 'childList') continue;
-        if (this.#hasFieldChild(r.addedNodes) || this.#hasFieldChild(r.removedNodes)) {
-          this.#syncInline();
-          return;
-        }
-      }
-    });
-    this.#mo.observe(this, { childList: true });
-  }
-
-  disconnected() {
-    this.#mo?.disconnect();
-    this.#mo = null;
-  }
-
-  render() {
-    // UIElement calls render() on attribute → property reflection. The
-    // inline attr's effect is propagation-to-children, not host markup.
-    this.#syncInline();
-  }
-
-  // ── Private ────────────────────────────────────────────────────
 
-  #syncInline() {
-    const inline = this.hasAttribute('inline');
-    for (const child of this.children) {
-      if (child.localName !== 'field-ui') continue;
-      if (inline) {
-        if (!child.hasAttribute('inline')) child.setAttribute('inline', '');
-      } else {
-        // Only remove if WE set it. We can't tell, so we always remove —
-        // that's the documented contract: <fields-ui inline> is the
-        // single source of truth for child inline-mode within the group.
-        if (child.hasAttribute('inline')) child.removeAttribute('inline');
-      }
-    }
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIFields } from './class.js';
 
-  /** @param {NodeList} nodes */
-  #hasFieldChild(nodes) {
-    for (const n of nodes) {
-      if (n.nodeType === 1 && /** @type {Element} */ (n).localName === 'field-ui') {
-        return true;
-      }
-    }
-    return false;
-  }
-}
+defineIfFree('fields-ui', UIFields);
 
-customElements.define('fields-ui', UIFields);
 export { UIFields };

package/components/grid/class.js

@@ -0,0 +1,31 @@
+/**
+ * Non-side-effect class export for `<grid-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/grid`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * grid-ui — CSS grid layout primitive.
+ *
+ * <grid-ui columns="3" gap="lg">...</grid-ui>
+ * <grid-ui columns="2" column-gap="2" row-gap="4">...</grid-ui>
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UIGrid extends UIElement {
+  static properties = {
+    columns:   { type: String, default: '3',  reflect: true },
+    gap:       { type: String, default: 'md', reflect: true },
+    columnGap: { type: String, default: '',   reflect: true, attribute: 'column-gap' },
+    rowGap:    { type: String, default: '',   reflect: true, attribute: 'row-gap' },
+  };
+  static template = () => null;
+}

package/components/grid/grid.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `<grid-ui>` — CSS grid layout primitive. Supports [columns="1..6"] for equal columns, [columns="auto-fill"|"auto-fit"] for responsive density, and a per-child [span="2..6"|"full"] attribute for asymmetric layouts. Compose a 2:1 split as columns="3" + the wide child span="2"; compose a 3:2 split as columns="5" + span="3" + span="2". Never set grid-template-columns via inline style — use the span attribute on children instead.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/grid
+ *
+ * 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 UIGrid extends UIElement {
+  /** Column gap override */
+  columnGap: string;
+  /** Number of columns or grid-template-columns */
+  columns: string;
+  /** Grid gap */
+  gap: string;
+  /** Row gap override */
+  rowGap: string;
+}

package/components/grid/grid.js

@@ -1,21 +1,17 @@
 /**
- * grid-ui — CSS grid layout primitive.
+ * `<grid-ui>` — auto-registers the tag on import.
  *
- * <grid-ui columns="3" gap="lg">...</grid-ui>
- * <grid-ui columns="2" column-gap="2" row-gap="4">...</grid-ui>
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIGrid } from '@adia-ai/web-components/components/grid/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+import { UIGrid } from './class.js';
 
-class UIGrid extends UIElement {
-  static properties = {
-    columns:   { type: String, default: '3',  reflect: true },
-    gap:       { type: String, default: 'md', reflect: true },
-    columnGap: { type: String, default: '',   reflect: true, attribute: 'column-gap' },
-    rowGap:    { type: String, default: '',   reflect: true, attribute: 'row-gap' },
-  };
-  static template = () => null;
-}
-customElements.define('grid-ui', UIGrid);
+defineIfFree('grid-ui', UIGrid);
 
 export { UIGrid };