@adia-ai/web-components 0.4.6 → 0.4.7

package/components/feed/feed.js

@@ -1,377 +1,19 @@
 /**
- * <feed-ui> + <feed-item-ui> — Shared top-layer feed channel.
+ * `<feed-ui>` — auto-registers the tag on import.
  *
- * Per docs/specs/feed-channel.md (SPEC-FEED-CHANNEL-001).
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Phase 1 (skeleton) ships here:
- *   - Per-position singletons (`<feed-ui position="bottom-right">`)
- *     resolving OD-FEED-1; mounted lazily into document.body via
- *     Popover API for top-layer placement.
- *   - Auto-fade `<feed-item-ui>` policy. Sticky-dismissible and
- *     action-required policies are stubs that respect the contract
- *     (no auto-dismiss when `duration` is null/0; close button
- *     surfaces when `dismissible` is set) but the action-required
- *     focus-trap is deferred.
- *   - Static API:  UIFeed.post() / .get() / .clear() / .purge()
- *     — `purge()` directly addresses the audit's L-B4 container-leak
- *     finding by giving consumers a tear-down hook.
- *   - Global event channel:  window.dispatchEvent(new CustomEvent(
- *       'feed', { detail: { text, position, ... } })) — same shape as
- *     UIFeed.post() so any code can post without importing the
- *     module directly. Idempotent listener install (HMR-safe).
+ *   import { UIFeedContainer, UIFeedItem } from '@adia-ai/web-components/components/feed/class';
  *
- * Toast migration (spec § 2.5) is deferred — toast-ui keeps its own
- * container + API for now; the migration happens once the feed-ui
- * surface has soaked.
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement, html } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+import { UIFeedContainer, UIFeedItem, UIFeed } from './class.js';
 
-/* ── Container — one per position, mounted into document.body ── */
-
-class UIFeedContainer extends UIElement {
-  static properties = {
-    position: { type: String, default: 'bottom-right', reflect: true },
-    max:      { type: Number, default: 5,              reflect: true },
-  };
-  static template = () => html``;
-
-  connected() {
-    if (!this.hasAttribute('role')) this.setAttribute('role', 'region');
-    if (!this.hasAttribute('aria-label')) this.setAttribute('aria-label', 'Feed');
-  }
-}
-
-customElements.define('feed-ui', UIFeedContainer);
-
-/* ── Item — one per posted message ── */
-
-class UIFeedItem extends UIElement {
-  #timer = null;
-  #removing = false;
-  #closeTimer = null;
-  #openRaf = null;
-
-  static properties = {
-    text:        { type: String,  default: '',           reflect: true },
-    heading:     { type: String,  default: '',           reflect: true },
-    icon:        { type: String,  default: '',           reflect: true },
-    variant:     { type: String,  default: 'default',    reflect: true },
-    duration:    { type: Number,  default: 4000,         reflect: true },
-    dismissible: { type: Boolean, default: false,        reflect: true },
-    // Phase 2: action-required policy. When set, the item carries an
-    // action button that the user MUST click (or dismiss) before the
-    // item goes away. Spec §2.3 — action-required role=alertdialog,
-    // focus is trapped until choice is made.
-    action:      { type: String,  default: '',           reflect: true },
-  };
-
-  static parts = {
-    body: '<div slot="body"></div>',
-  };
-  static template = () => html``;
-
-  #onPress = (e) => {
-    if (e.target.closest('[data-feed-close]')) { this.dismiss(); return; }
-    // Phase 2: action button — fires the action callback (if registered
-    // via FeedHandle.update with onAction) then dismisses. The handle's
-    // .update({onAction: fn}) populates this.#onAction below.
-    if (e.target.closest('[data-feed-action]')) {
-      try { this.#onAction?.(); } catch (err) { console.warn('[feed-item] action handler threw:', err); }
-      this.dismiss();
-    }
-  };
-
-  // Phase 2 focus-trap state — only used when the policy is action-required.
-  #onAction = null;
-  #focusTrapPrev = null;
-  #onTrapKeydown = null;
-
-  connected() {
-    this.addEventListener('press', this.#onPress);
-  }
-
-  #getDuration() {
-    const raw = getComputedStyle(this).getPropertyValue('--feed-item-duration').trim();
-    return parseFloat(raw) || 200;
-  }
-
-  render() {
-    const body = this.ensure('body');
-    body.textContent = '';
-    if (this.heading) {
-      const h = document.createElement('strong');
-      h.textContent = this.heading;
-      h.style.display = 'block';
-      body.appendChild(h);
-    }
-    if (this.text) {
-      const t = document.createElement('span');
-      t.textContent = this.text;
-      body.appendChild(t);
-    }
-
-    /* Inferred policy roles per spec §2.4. Auto-fade gets `status`;
-       sticky danger/warning gets `alert`; action-required (sticky +
-       has [action]) gets `alertdialog` and a focus trap. */
-    const isSticky = !this.duration || this.duration <= 0;
-    const isLoud   = this.variant === 'danger' || this.variant === 'warning';
-    const isActionRequired = isSticky && !!this.action;
-    let role = 'status';
-    if (isActionRequired) role = 'alertdialog';
-    else if (isSticky && isLoud) role = 'alert';
-    this.setAttribute('role', role);
-    this.setAttribute('aria-live', role === 'alert' || role === 'alertdialog' ? 'assertive' : 'polite');
-    if (isActionRequired) this.setAttribute('aria-modal', 'false'); // not page-blocking; focus-trap only
-
-    /* Render dismiss button for sticky items (spec §2.2 — default true
-       for sticky, false for auto-fade). Action-required items still
-       allow Escape to dismiss for safety; the action button is not the
-       only escape. */
-    const wantsClose = this.dismissible || isSticky;
-    let close = this.querySelector(':scope > [data-feed-close]');
-    if (wantsClose && !close) {
-      close = document.createElement('button-ui');
-      close.setAttribute('data-feed-close', '');
-      close.setAttribute('icon', 'x');
-      close.setAttribute('variant', 'ghost');
-      close.setAttribute('size', 'sm');
-      close.setAttribute('aria-label', 'Dismiss');
-      this.appendChild(close);
-    } else if (!wantsClose && close) {
-      close.remove();
-    }
-
-    /* Phase 2 — render the action button when [action] is set. Sits
-       between the body and the close button. */
-    let actionBtn = this.querySelector(':scope > [data-feed-action]');
-    if (this.action) {
-      if (!actionBtn) {
-        actionBtn = document.createElement('button-ui');
-        actionBtn.setAttribute('data-feed-action', '');
-        actionBtn.setAttribute('variant', 'ghost');
-        actionBtn.setAttribute('size', 'sm');
-        if (close && close.parentElement === this) this.insertBefore(actionBtn, close);
-        else                                       this.appendChild(actionBtn);
-      }
-      actionBtn.setAttribute('text', this.action);
-    } else if (actionBtn) {
-      actionBtn.remove();
-    }
-
-    /* Focus-trap activation for action-required. */
-    if (isActionRequired) this.#installFocusTrap();
-    else                  this.#uninstallFocusTrap();
-
-    if (!this.hasAttribute('data-open') && !this.#removing) {
-      this.#openRaf = requestAnimationFrame(() => {
-        this.#openRaf = null;
-        this.setAttribute('data-open', '');
-      });
-    }
-    this.#scheduleAutoDismiss();
-  }
-
-  #scheduleAutoDismiss() {
-    if (this.#timer) clearTimeout(this.#timer);
-    if (this.duration && this.duration > 0) {
-      this.#timer = setTimeout(() => this.dismiss(), this.duration);
-    }
-  }
-
-  dismiss() {
-    if (this.#removing) return;
-    this.#removing = true;
-    if (this.#timer) { clearTimeout(this.#timer); this.#timer = null; }
-    this.removeAttribute('data-open');
-    this.setAttribute('data-closing', '');
-    this.#closeTimer = setTimeout(() => {
-      this.#closeTimer = null;
-      const container = this.parentElement;
-      this.dispatchEvent(new Event('close', { bubbles: true }));
-      this.remove();
-      if (container?.matches?.('feed-ui')) UIFeed.releaseContainerIfEmpty(container);
-    }, this.#getDuration());
-  }
-
-  update(patch) {
-    if (!patch || typeof patch !== 'object') return;
-    for (const k of Object.keys(patch)) {
-      if (k in UIFeedItem.properties) this[k] = patch[k];
-    }
-    // Phase 2: handle is set via the FeedHandle's update(); not a
-    // reflected attribute, so it lives outside the property loop.
-    if (typeof patch.onAction === 'function') this.#onAction = patch.onAction;
-    this.#scheduleAutoDismiss();
-  }
-
-  // Phase 2 focus-trap. Installs on action-required items; saves the
-  // previously-focused element so we can return focus on dismiss; cycles
-  // Tab/Shift-Tab between focusable descendants; Escape dismisses.
-  #installFocusTrap() {
-    if (this.#onTrapKeydown) return; // already installed
-    this.#focusTrapPrev = document.activeElement;
-    const focusables = () => [...this.querySelectorAll('button, button-ui, [tabindex]:not([tabindex="-1"]), input, [data-feed-action], [data-feed-close]')]
-      .filter((el) => !el.hasAttribute('disabled') && el.offsetParent !== null);
-    this.#onTrapKeydown = (e) => {
-      if (e.key === 'Escape') { e.stopPropagation(); this.dismiss(); return; }
-      if (e.key !== 'Tab') return;
-      const els = focusables();
-      if (!els.length) return;
-      const first = els[0];
-      const last  = els[els.length - 1];
-      const active = document.activeElement;
-      if (e.shiftKey && active === first) { e.preventDefault(); last.focus(); }
-      else if (!e.shiftKey && active === last) { e.preventDefault(); first.focus(); }
-    };
-    this.addEventListener('keydown', this.#onTrapKeydown, true);
-    // Move focus into the item — prefer the action button.
-    queueMicrotask(() => {
-      const els = focusables();
-      const action = this.querySelector('[data-feed-action]');
-      (action || els[0])?.focus?.();
-    });
-  }
-
-  #uninstallFocusTrap() {
-    if (!this.#onTrapKeydown) return;
-    this.removeEventListener('keydown', this.#onTrapKeydown, true);
-    this.#onTrapKeydown = null;
-    // Restore focus to whatever had it before the trap engaged.
-    try { this.#focusTrapPrev?.focus?.(); } catch { /* element may have been removed */ }
-    this.#focusTrapPrev = null;
-  }
-
-  disconnected() {
-    this.removeEventListener('press', this.#onPress);
-    if (this.#timer) { clearTimeout(this.#timer); this.#timer = null; }
-    if (this.#closeTimer) { clearTimeout(this.#closeTimer); this.#closeTimer = null; }
-    if (this.#openRaf != null) { cancelAnimationFrame(this.#openRaf); this.#openRaf = null; }
-    this.#uninstallFocusTrap();
-  }
-}
-
-customElements.define('feed-item-ui', UIFeedItem);
-
-/* ── Static API — UIFeed ── */
-
-class UIFeed {
-  static #containers = new Map();
-
-  /**
-   * Get (or lazily create) the per-position lane. Each lane is a
-   * manual Popover-API container — `[popover="manual"]` puts it in
-   * the browser's top-layer with no z-index wars and the native
-   * popover stack lets multiple lanes coexist (e.g. one feed in
-   * top-right + another in bottom-center) without collision.
-   */
-  static get(position = 'bottom-right') {
-    let el = UIFeed.#containers.get(position);
-    if (el && el.isConnected) return el;
-    el = document.createElement('feed-ui');
-    el.setAttribute('position', position);
-    if ('popover' in HTMLElement.prototype) el.setAttribute('popover', 'manual');
-    document.body.appendChild(el);
-    try { el.showPopover?.(); } catch { /* graceful fallback */ }
-    UIFeed.#containers.set(position, el);
-    return el;
-  }
-
-  /**
-   * Post a feed item. Returns a `FeedHandle` (`{id, dismiss, update}`).
-   *
-   * @param {Object} opts
-   * @param {string} [opts.text]
-   * @param {string} [opts.heading]
-   * @param {string} [opts.icon]
-   * @param {string} [opts.variant='default']  default | info | success | warning | danger
-   * @param {number|null} [opts.duration=4000]  ms; null/0 = sticky (requires close click)
-   * @param {string} [opts.position='bottom-right']
-   * @param {boolean} [opts.dismissible]  override default (true for sticky, false for auto)
-   * @param {string} [opts.id]
-   * @param {string} [opts.action]  Phase 2 — action button label. When set,
-   *                                duration is forced to null (sticky); the
-   *                                item gets role=alertdialog + focus trap.
-   * @param {function} [opts.onAction]  Phase 2 — callback invoked when the
-   *                                action button is pressed. Item dismisses
-   *                                after the callback returns.
-   */
-  static post(opts = {}) {
-    const {
-      text = '',
-      heading = '',
-      icon = '',
-      variant = 'default',
-      duration = 4000,
-      position = 'bottom-right',
-      dismissible,
-      id,
-      action = '',
-      onAction,
-    } = opts;
-    const v = variant === 'error' ? 'danger' : variant;  // documented alias
-    const container = UIFeed.get(position);
-    // Phase 2 max-queue: items above [max] queue with [data-queued] and
-    // become visible as visible items dismiss.
-    const max = parseInt(container.getAttribute('max') || '5', 10);
-    const visibleCount = [...container.children].filter((c) =>
-      c.tagName === 'FEED-ITEM-UI' && !c.hasAttribute('data-queued')
-    ).length;
-    const item = document.createElement('feed-item-ui');
-    if (id) item.setAttribute('data-id', id);
-    item.text = text;
-    item.heading = heading;
-    item.icon = icon;
-    item.variant = v;
-    // Action-required forces sticky.
-    item.duration = action ? 0 : duration;
-    if (dismissible != null) item.dismissible = !!dismissible;
-    if (action) item.action = action;
-    if (visibleCount >= max) item.setAttribute('data-queued', '');
-    container.appendChild(item);
-    if (typeof onAction === 'function') item.update({ onAction });
-    return {
-      id: id ?? null,
-      dismiss: () => item.dismiss(),
-      update:  (patch) => item.update(patch),
-    };
-  }
-
-  /** Clear all items in a single lane. */
-  static clear(position = 'bottom-right') {
-    const el = UIFeed.#containers.get(position);
-    if (!el) return;
-    for (const item of [...el.children]) {
-      if (item.tagName === 'FEED-ITEM-UI') item.dismiss?.();
-    }
-  }
-
-  /** Tear down ALL containers. Test cleanup; addresses audit L-B4. */
-  static purge() {
-    for (const el of UIFeed.#containers.values()) {
-      try { el.hidePopover?.(); } catch { /* noop */ }
-      el.remove();
-    }
-    UIFeed.#containers.clear();
-  }
-
-  /** Internal: drop a lane when its last item exits. Also rotates the
-   *  Phase 2 max-queue: when a visible item leaves, promote the oldest
-   *  queued sibling so the visible-count returns to [max]. */
-  static releaseContainerIfEmpty(container) {
-    if (!container) return;
-    // Promote the oldest queued sibling (if any) before deciding whether
-    // to release. The queue is FIFO; queued items live at the tail.
-    const queued = container.querySelector('feed-item-ui[data-queued]');
-    if (queued) queued.removeAttribute('data-queued');
-    if (container.children.length > 0) return;
-    try { container.hidePopover?.(); } catch { /* noop */ }
-    container.remove();
-    for (const [pos, el] of UIFeed.#containers) {
-      if (el === container) UIFeed.#containers.delete(pos);
-    }
-  }
-}
+defineIfFree('feed-ui', UIFeedContainer);
+defineIfFree('feed-item-ui', UIFeedItem);
 
 /* Global 'feed' CustomEvent listener — same shape as UIFeed.post().
    Idempotent (HMR-safe via window flag). */

package/components/field/class.js

@@ -0,0 +1,266 @@
+/**
+ * Non-side-effect class export for `<field-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/field`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * field-ui — Labeled field wrapper.
+ *
+ *   <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>
+ *
+ * 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.
+ *
+ * ### 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.
+ */
+import { UIElement } from '../../core/element.js';
+
+export 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;
+  }
+
+  static #idSeq = 0;
+  static #nextId() { return `field-ctl-${++UIField.#idSeq}`; }
+  static #msgSeq = 0;
+  static #nextMsgId(kind) { return `field-${kind}-${++UIField.#msgSeq}`; }
+}

package/components/field/field.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `<field-ui>` — Labeled field wrapper. Composes a <label for="…"> with a form control (input-ui, select-ui, textarea-ui, etc.) placed in the default slot, plus optional [slot="trailing"] and [slot="action"] regions. Auto-mints an id on the slotted control when missing so clicking the label focuses the control — an accessibility upgrade over setting label="…" on the control directly, which has no [for] binding. Two layouts — stacked (default) and inline (the `inline` mode attribute collapses everything to a single row).
+ *
+ * @see https://ui-kit.exe.xyz/site/components/field
+ *
+ * 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 UIField extends UIElement {
+  /** Renders a "*" marker on the label. Does not itself enforce validation — the slotted control's own `required` attr does that; this is a visual signal only. */
+  required: boolean;
+  /** Help text rendered below the control in caption style. Wired into the slotted control's aria-describedby so screen readers announce it. Suppressed when `error` is set. */
+  hint: string;
+  /** Lay out label, trailing, control, and action on a single row instead of the stacked default (mode attribute — changes grid geometry, not tokens). Hint/error still render on their own row below. */
+  inline: boolean;
+  /** Label text rendered in the label row. */
+  label: string;
+}