@agent-ui-kit/components 0.0.3

package/dist/dom/form.js

@@ -0,0 +1,399 @@
+// form.ts — `UIFormElement`, the FACE form-associated base (ADR-0013; decomp g4-g6 slice s1).
+//
+// The base every value-carrying FACE control (`ui-text-field`, `ui-checkbox`, `ui-switch`, `ui-select`,
+// `ui-listbox`) extends. It turns a `UIElement` into a form participant: `static formAssociated = true`
+// activates the platform's form lifecycle, and the inherited `ElementInternals` — acquired ONCE in the
+// `UIElement` constructor, reused here and NEVER re-`attachInternals()`d (a second acquisition throws) —
+// carries the value + validity to the owning `<form>`. Two scope-owned effects publish the control's
+// `formValue()` / `formValidity()` hooks to `internals.setFormValue` / `setValidity`, so a control declares
+// WHAT its value + validity are and the base wires the reactive plumbing. The base owns the three universal
+// form attributes via the SPREADABLE `formProps` (props.ts has no static-props prototype merge — the
+// subclass folds them into its own `static props`); it deliberately does NOT own a typed `value` — the
+// value's type + codec are the subclass's (string for text-field; a `checked` boolean for checkbox; …).
+//
+// Super-wrapped wiring keeps subclass authoring identical to a plain `UIElement` control: a subclass still
+// overrides the clean, no-`super` `connected()` hook; this base wraps `connectedCallback` to add its own
+// scope-owned effects after `super` has opened the scope.
+//
+// G7 growth (ADR-0050 + ADR-0051, the fleet's first context/provider primitive + its labelling seam):
+//   • ADR-0050 — at the END of `connectedCallback` (scope + effects all live) the base dispatches the
+//     `ui-form-connect` protocol event: a composed, bubbling, NOT-cancelable event (`dispatchEvent`, not
+//     `this.emit` — `emit`'s cancelable/public shape is for consumer events) whose detail is the control's
+//     PUBLIC reactive surface, closing over `formValue()`/the merged validity/`formUserInvalid()`, plus the
+//     live connection `AbortSignal` (the teardown handle a registry subscribes `abort` on — a disconnected
+//     control cannot dispatch, so deregistration rides the handle, never a second event). `formResetCallback`
+//     grows a matching `ui-form-reset` dispatch (no detail — the target IS the resetting control).
+//   • ADR-0051 — a small signal-backed field-labelling seam: `setFieldLabelling`/`fieldLabelling` are the
+//     handoff surface a `ui-field` calls (elements, not id strings — the internals path consumes elements);
+//     a base scope-owned effect forwards the current labelling through the overridable `applyFieldLabelling`
+//     hook, whose GUARDED default reflects via `ElementInternals` ARIA-element accessors ONLY when
+//     `internals.role` is set (feature-detected — the tabs `reflectAriaElements` precedent) — a part-role
+//     control (text-field) overrides it. `formUserInvalid()` is the parallel hook feeding the connect
+//     detail's `userInvalid` read; a control composing `trackUserInvalid` overrides it with the tracker gate.
+//   Both are additive: provider-less/field-less usage shows ZERO behavioral drift (the events bubble to
+//   nobody; `fieldLabelling` stays `null`, so `applyFieldLabelling`'s default no-op — jsdom has no
+//   `internals.role` reflection surface either — never fires a visible change).
+//   • F1 (review-caught upgrade-order hole): the one connect dispatch above assumes a listening
+//     provider/field is ALREADY live — true for insertion order, but NOT custom-element UPGRADE order
+//     (pre-existing DOM whose control module upgrades before the provider/field module does ⇒ the dispatch
+//     fires into the void). `announceFormConnect()` (public) re-dispatches the SAME event with a fresh
+//     detail on demand — a provider/field's one-shot catch-up scan calls it per already-connected control
+//     it discovers late. Blanket-safe: the registry/field acceptance guards are already idempotent.
+//   • Nested-member guard (defect repair — A2UI patterns-page-caught): a `UIFormElement` never announces
+//     when it has a `UIFormElement` ANCESTOR — it is an INTERNAL PART (e.g. text-field type=date's own
+//     `<ui-calendar>`; a radio inside its radio-group), never a registry/field member. Both dispatch sites
+//     route through the one `#dispatchFormConnect` choke point so the guard can never be bypassed by one
+//     of the two. See `#dispatchFormConnect`'s own doc for the write-loop this closes.
+//
+// Imports only `../reactive` (the kernel) + same-layer `./element.ts` / `./props.ts` (the layering holds).
+// `ElementInternals` / `ValidityState` / `ValidityStateFlags` / `HTMLFormElement` / `HTMLElement` / `File` /
+// `FormData` / `AbortSignal` / `CustomEvent` are ambient DOM globals, not imports.
+var _a;
+import { signal } from "../reactive/index.js";
+import { UIElement } from "./element.js";
+import { prop } from "./props.js";
+// ── ADR-0050 — the protocol events ──────────────────────────────────────────────
+// The `ui-` namespace: base↔provider/field plumbing, OUTSIDE the public component-event vocab
+// (change·input·select·open·close·toggle). Both composed + bubbling, NOT cancelable (dispatched directly
+// with `dispatchEvent`, not `this.emit` — `emit`'s cancelable/public shape is for consumer events).
+/** Fired once, at the end of `connectedCallback` — the control announcing full connection to the nearest
+ *  provider/field ancestor. */
+export const FORM_CONNECT_EVENT = 'ui-form-connect';
+/** Fired from `formResetCallback`, after `formReset()` — detail: none (the target IS the resetting
+ *  control). Covers BOTH reset paths: native `form.reset()` and a provider's direct `formResetCallback()` call. */
+export const FORM_RESET_EVENT = 'ui-form-reset';
+// Reflect an ARIA element-list relation through `internals` (feature-detected — the reflection accessors
+// landed in modern Chromium/WebKit but NOT jsdom, so this is a no-op under the jsdom inner loop and live in
+// the real engines, verified by the s11 browser smokes; the tabs `reflectAriaElements` precedent — tab.ts /
+// tab-panel.ts carry their own local copies too, the folder ships no shared module for this one-liner).
+// `null` clears the relation.
+function reflectAriaElements(internals, name, elements) {
+    if (name in internals)
+        internals[name] = elements;
+}
+// The three universal form attributes every value-carrying control shares (clause 2). All three REFLECT:
+// `name` reflects for native parity (the HTML `name` IDL attribute reflects its content attribute) AND
+// because FACE submission keys the entry by the `name` CONTENT attribute — so the imperative `el.name = …`
+// path must update the attribute or the value submits unkeyed; `disabled` / `required` reflect so
+// attribute-selector styling (`[disabled]` / `[required]`) applies to JS-set values too. `value` is ABSENT —
+// its type/codec belong to the subclass. A subclass spreads this into its own `static props`:
+// `static props = { ...UIFormElement.formProps, value: prop.string(), … }`.
+const formProps = {
+    name: { ...prop.string(), reflect: true },
+    disabled: { ...prop.boolean(), reflect: true },
+    required: { ...prop.boolean(), reflect: true },
+};
+export class UIFormElement extends UIElement {
+    /** Activates platform form association — `setFormValue`/`setValidity` + the form lifecycle callbacks (clause 1). */
+    static formAssociated = true;
+    /** The spreadable universal form attributes — the no-static-props-inheritance workaround (clause 2). */
+    static formProps = formProps;
+    // Fieldset / `<form disabled>` state, pushed in by `formDisabledCallback`. A signal so `effectiveDisabled()`
+    // is reactive — a subclass effect reading it re-runs when an ancestor fieldset toggles disabled.
+    #formDisabled = signal(false);
+    // Renderer-driven custom validity (ADR-0029 §5 — the A2UI `checks` controller seam). A signal so the
+    // merged validity effect below re-runs when the renderer calls `setCustomValidity` (live validation).
+    // Empty string = no custom message = no custom-error contribution (native-parity clear, like `input.setCustomValidity('')`).
+    #customValidity = signal('');
+    // ADR-0051 — the field-labelling handoff, written by `setFieldLabelling`, read by the base's forwarding
+    // effect (below) + `fieldLabelling`. `null` = unassociated (the default; every existing control's behavior).
+    #fieldLabelling = signal(null);
+    /**
+     * Super-wrapped wiring (clause 4). `super.connectedCallback()` opens the connection scope + AbortController,
+     * runs the no-`super` `connected()` hook, and installs the render effect; the scope is now live, so the
+     * effects below are scope-owned and disposed on disconnect (zero residue). They install AFTER the render
+     * effect — harmless: the form family's `render()` is the inherited void. The subclass keeps the clean,
+     * no-`super` `connected()` hook — it never sees this wrapper.
+     */
+    connectedCallback() {
+        super.connectedCallback();
+        // Publish the control's value to the form, reactively: reading `formValue()` tracks whatever signals the
+        // subclass's hook reads (its `value` prop), so a value change re-runs ONLY this effect → one setFormValue.
+        this.effect(() => {
+            this.internals.setFormValue(this.formValue());
+        });
+        // Publish the control's MERGED validity verdict to the platform, reactively (same tracking discipline;
+        // `#mergedValidity` is the single source — also fed to the ADR-0050 connect detail below).
+        this.effect(() => {
+            this.#applyValidity(this.#mergedValidity());
+        });
+        // ADR-0051 — forward the current field labelling through the overridable hook. Base scope-owned, so
+        // association (a `ui-field`'s `setFieldLabelling` call) / clear re-apply reactively. Installed BEFORE
+        // the connect dispatch below (LLD-C2) — nothing can call `setFieldLabelling` before this control has
+        // even announced itself, so there is no real race, but the ordering is the documented contract.
+        this.effect(() => {
+            this.applyFieldLabelling(this.#fieldLabelling.value);
+        });
+        // ADR-0050 — announce full connection to the nearest provider/field ancestor. Dispatched LAST — the
+        // scope is open, `connected()` has run, and all three effects above are installed, so a listener sees
+        // a fully-wired control.
+        this.#dispatchFormConnect();
+    }
+    /**
+     * The ONE dispatch choke point — both the initial connect dispatch above and `announceFormConnect`
+     * (F1, below) route through this, so the nested-member guard (bug repair, below) and the dispatch shape
+     * itself never drift apart between the two call sites. `dispatchEvent` directly (not `this.emit`):
+     * composed + bubbling, NOT cancelable — this is base↔provider/field plumbing, not a consumer-facing
+     * semantic event.
+     *
+     * GUARD (defect repair — a nested `UIFormElement` is an INTERNAL PART, never a registry/field MEMBER):
+     * native form controls do not nest as members of each other (there is no such thing as an `<input>`
+     * inside an `<input>`'s own submission graph) — ADR-0050's intent was always to discover form-owning
+     * MEMBERS, not every `UIFormElement`-shaped node regardless of where it sits. `ui-text-field type=date`
+     * creates its OWN internal `<ui-calendar>` (itself a `UIFormElement`, for its own unrelated internal
+     * value-picking UI) and appends it inside itself — undetected, a wrapping `ui-form-provider`'s catch-up
+     * scan (`querySelectorAll('*')` + `instanceof`) discovers the calendar as a SECOND, phantom member,
+     * whose aggregate reads feed back into the field's own effects → an unbounded write-loop (the kernel's
+     * ~100-wave budget throws). The fix: a control with a `UIFormElement` ANCESTOR never announces at all —
+     * neither the initial dispatch nor a catch-up re-announce reaches a listener, so it can never register
+     * anywhere. `#hasFormElementAncestor` walks `parentElement` (O(depth), stops at the first hit) — cheap,
+     * connect-time-only, no observer. This also correctly covers `ui-radio` nested in `ui-radio-group`
+     * (`UIRadioGroupElement extends UIFormElement`) — the group is the aggregation owner of its own radios,
+     * which are internal parts of ITS submission graph the same way the calendar is the text-field's; each
+     * radio's own `formValidity()` was always trivially valid, so no outer aggregate observably changes.
+     */
+    #dispatchFormConnect() {
+        if (this.#hasFormElementAncestor())
+            return;
+        this.dispatchEvent(new CustomEvent(FORM_CONNECT_EVENT, {
+            bubbles: true,
+            composed: true,
+            detail: this.#connectDetail(),
+        }));
+    }
+    /** Walk the parentElement chain for the nearest `UIFormElement` ancestor (O(depth), stops at the first
+     *  hit) — the nested-member guard `#dispatchFormConnect` applies. Ancestors only: `this` itself is
+     *  always a `UIFormElement` and is deliberately excluded from the walk. */
+    #hasFormElementAncestor() {
+        let node = this.parentElement;
+        while (node !== null) {
+            if (node instanceof _a)
+                return true;
+            node = node.parentElement;
+        }
+        return false;
+    }
+    /**
+     * Mint a FRESH `FormConnectDetail` off the CURRENT connection signal — the single source
+     * `#dispatchFormConnect` constructs from (both the initial dispatch and `announceFormConnect` route
+     * through it), so the two never drift apart. Only meaningful while connected (`connectionSignal` is
+     * live); the non-null assertion holds because both call sites already guard on `connectionSignal !==
+     * null` before reaching here (not `isConnected` — see `announceFormConnect`'s doc for why that guard is
+     * the wrong one).
+     */
+    #connectDetail() {
+        return {
+            control: this,
+            signal: this.connectionSignal,
+            value: () => this.formValue(),
+            validity: () => this.#mergedValidity(),
+            userInvalid: () => this.formUserInvalid(),
+        };
+    }
+    /**
+     * Re-announce full connection (F1 — the review-caught upgrade-order hole). "Ancestors connect before
+     * descendants" holds for INSERTION order but NOT custom-element UPGRADE order: pre-existing DOM whose
+     * control module registers/upgrades before the provider/field module does means the ONE connect dispatch
+     * in `connectedCallback` fires into the void — no listener is live yet — and registration would be lost
+     * forever without a catch-up path. Public so a provider/field's one-shot catch-up scan (built at their
+     * own build slice) can call it on every already-connected `UIFormElement` it discovers late, re-dispatching
+     * `ui-form-connect` with a FRESH detail (the same minting `#connectDetail()` uses, so a reconnect since
+     * the original dispatch is reflected — a NEW connection signal, current prop values).
+     *
+     * Guard: `connectionSignal === null`, NOT `isConnected` (a real bug an s9 repro caught — the bulk-insert
+     * hazard). `isConnected` reflects DOM tree membership, set the instant a subtree is spliced in; a custom
+     * element's OWN `connectedCallback` (which opens the connection scope + mints `#ac`) fires ASYNC to that,
+     * in a separate reaction-queue pass, ancestor-first. So on a bulk insert of a pre-built offline subtree
+     * (assemble, then one `append()` — the house test idiom), every descendant is already `isConnected` the
+     * moment the PARENT's `connectedCallback` runs (and could catch-up-scan its already-`isConnected`
+     * children) even though THEIR OWN `connectedCallback` — and so `connectionSignal` — hasn't fired yet.
+     * NOT a jsdom accommodation: atomic-subtree-connect ordering (ancestor-`connectedCallback`-before-
+     * descendant, all descendants already `isConnected` throughout) is SPEC-MANDATED and holds identically in
+     * every real engine (s8 confirmed with a plain-HTMLElement probe) — this is a real-browser correctness
+     * fix, not a test-environment workaround. `connectionSignal === null` is the correct predicate for "has
+     * this control's OWN connect wiring run yet": it is null before that control's first `connectedCallback`
+     * (nothing to announce — that `connectedCallback` will dispatch for itself momentarily) AND after its
+     * `disconnectedCallback` (`#ac` is nulled there too, element.ts) — one guard covers both the not-yet-mine
+     * and no-longer-mine legs; `isConnected` is redundant once this holds and is dropped to avoid it masking
+     * the real invariant.
+     *
+     * This guard closes TWO bugs, not one. The obvious one: the pre-fix crash (a `null` `signal` in the
+     * minted detail, `detail.signal.aborted` throwing in a registry/field listener). The SILENT one (s8-found):
+     * in the same-cascade race, `ui-field`'s association still applies `aria-labelledby` (the labelling signal
+     * write does not ride the connection scope), but the affected control's OWN `connectedCallback` — and so
+     * its abort listener — had not yet run, so `this.listen(detail.signal, 'abort', …)` in `#associate` would
+     * have wired against a signal that was never live, and a later removal would never dissociate (stale
+     * labelling, forever). This guard skips the same-cascade announce entirely and lets the descendant's OWN
+     * end-of-`connectedCallback` dispatch (below the guard here — see that dispatch's own signal, always live
+     * by construction) carry the association instead, once the field/provider is already listening — so the
+     * abort listener installs correctly, every time.
+     *
+     * Also routes through `#dispatchFormConnect`'s nested-member guard — a catch-up scan's
+     * `querySelectorAll('*')` finds every `UIFormElement` descendant indiscriminately (it cannot itself
+     * distinguish an internal part like a text-field's calendar from a real member), so the guard MUST live
+     * here too, not only on the initial dispatch, or a late-discovered internal part would still register.
+     */
+    announceFormConnect() {
+        if (this.connectionSignal === null)
+            return;
+        this.#dispatchFormConnect();
+    }
+    /** Map a `ValidityResult` onto `internals.setValidity`: valid clears it; invalid sets flags + message (+ anchor). */
+    #applyValidity(result) {
+        if (result.valid)
+            this.internals.setValidity({});
+        else
+            this.internals.setValidity(result.flags, result.message, result.anchor);
+    }
+    /**
+     * The MERGED validity verdict — `formValidity()` ⊕ the renderer-driven `#customValidity` signal (ADR-0029
+     * §5): native wins when already invalid; a non-empty custom message produces `{valid:false,
+     * flags:{customError:true}, message}`; both empty → valid (clear). The SINGLE source feeding both the
+     * internals-publishing effect above and `FormConnectDetail.validity` (ADR-0050 — extracted so the two
+     * never drift apart).
+     */
+    #mergedValidity() {
+        const native = this.formValidity();
+        const custom = this.#customValidity.value;
+        if (!native.valid)
+            return native; // native wins (e.g. valueMissing overrides the custom message)
+        if (custom !== '')
+            return { valid: false, flags: { customError: true }, message: custom };
+        return native; // both valid: clear
+    }
+    /**
+     * Set a renderer-driven custom validity message (ADR-0029 §5 — the A2UI `checks` seam, native-parity name).
+     * An empty string clears the custom contribution (native parity: `el.setCustomValidity('')` = valid).
+     * A non-empty message drives `{valid:false, flags:{customError:true}, message}` unless `formValidity()`
+     * is already invalid (native wins — e.g. `valueMissing` takes the display slot over a custom message).
+     * The reactive effect in `connectedCallback` picks up the `#customValidity` signal change and re-publishes
+     * through `#applyValidity` without any direct caller → `internals.setValidity` call here.
+     */
+    setCustomValidity(message) {
+        this.#customValidity.value = message;
+    }
+    // ── overridable control hooks (clause 3) ──────────────────────────────────────
+    /** The value this control contributes to its form. Default: nothing (`null`); the subclass returns its value. */
+    formValue() {
+        return null;
+    }
+    /**
+     * This control's validity verdict, published to `internals.setValidity` by a scope-owned effect. Default:
+     * always valid; the subclass computes it from its props (e.g. `required && value === '' → valueMissing`).
+     *
+     * NAMED `formValidity`, NOT `validity` (parallel to `formValue`): the public IDL `validity` GETTER below
+     * returns the platform's `ValidityState`, so the verdict hook cannot share that name. ADR-0013 clauses 3/6
+     * both wrote `validity`; this base resolves the collision in favour of native IDL parity for `validity`.
+     */
+    formValidity() {
+        return { valid: true };
+    }
+    // ── effective-disabled (clause 5) ─────────────────────────────────────────────
+    /**
+     * The disabled state a control should obey: its OWN `disabled` prop OR an ancestor `<fieldset disabled>` /
+     * form-disabled state (`formDisabledCallback`). Reactive — read it inside an effect and it re-runs when
+     * either source flips. (The form-disabled channel is the ADR-0013 divergence from ADR-0010's `ariaDisabled`
+     * for non-form controls.)
+     */
+    effectiveDisabled() {
+        return this.disabled || this.#formDisabled.value;
+    }
+    // ── platform form lifecycle callbacks → overridable hooks (clause 5) ──────────
+    /**
+     * Platform reset → the `formReset()` hook (the subclass restores value ← its defaultValue; clause 2), THEN
+     * the ADR-0051 `ui-form-reset` protocol dispatch (composed, bubbling, no detail — the target IS the
+     * resetting control) so an observing `ui-field` re-suppresses its visible error. Covers BOTH reset paths:
+     * native `form.reset()` (the platform walks its FACE members' `formResetCallback`s) and a form-less
+     * provider's direct call to this same public platform callback.
+     */
+    formResetCallback() {
+        this.formReset();
+        this.dispatchEvent(new CustomEvent(FORM_RESET_EVENT, { bubbles: true, composed: true }));
+    }
+    /** Platform fieldset/form-disabled change → the reactive `#formDisabled` signal behind `effectiveDisabled()`. */
+    formDisabledCallback(disabled) {
+        this.#formDisabled.value = disabled;
+    }
+    /** Platform state restore (navigation/autofill) → the `formStateRestore(state)` hook. */
+    formStateRestoreCallback(state, _mode) {
+        this.formStateRestore(state);
+    }
+    /** Platform association change → the no-op `formAssociated(form)` hook (an extension point). */
+    formAssociatedCallback(form) {
+        this.formAssociated(form);
+    }
+    /** Restore value ← defaultValue on form reset. Default no-op — the subclass owns `value` + its defaultValue. */
+    formReset() { }
+    /** Restore value from a previously-submitted/autofilled form state. Default no-op — the subclass decodes `state`. */
+    formStateRestore(_state) { }
+    /** Called when the element associates with / disassociates from a form. Default no-op extension point. */
+    formAssociated(_form) { }
+    // ── IDL delegators (clause 6) — native form-control parity, via the inherited internals ───────
+    // `name` is NOT delegated here: it is the reactive `name` prop (spread from `formProps`), the same surface
+    // a consumer reads as `el.name` — and `internals` has no `name` member to delegate to.
+    /** The owning `<form>`, or null. */
+    get form() {
+        return this.internals.form;
+    }
+    /** The platform's live `ValidityState` (the IDL object; distinct from the `formValidity()` verdict hook). */
+    get validity() {
+        return this.internals.validity;
+    }
+    /** The platform validation message (the `setValidity` message; empty when valid). */
+    get validationMessage() {
+        return this.internals.validationMessage;
+    }
+    /** Whether this control is a candidate for constraint validation. */
+    get willValidate() {
+        return this.internals.willValidate;
+    }
+    /** Run constraint validation, firing an `invalid` event when invalid. */
+    checkValidity() {
+        return this.internals.checkValidity();
+    }
+    /** Like `checkValidity`, and additionally reports the problem to the user (focuses the anchor). */
+    reportValidity() {
+        return this.internals.reportValidity();
+    }
+    // ── ADR-0051 — the field-labelling seam ───────────────────────────────────────
+    /**
+     * Public — a `ui-field` calls this with its label/description/error part elements; `null` clears the
+     * association (control removed from its field, or the field itself torn down). Signal-backed (the
+     * `setCustomValidity` precedent, ADR-0029 §5) — deliberately NOT a prop: elements can't ride attributes,
+     * so this stays off the attributes-as-API descriptor surface. Safe on a disconnected control (a plain
+     * signal write); the base effect applies it on next connect.
+     */
+    setFieldLabelling(refs) {
+        this.#fieldLabelling.value = refs;
+    }
+    /** Protected reactive read — an override's forwarding effect (or a subclass's own label/message effects,
+     *  e.g. text-field's wire) re-runs on association/clear. */
+    get fieldLabelling() {
+        return this.#fieldLabelling.value;
+    }
+    /**
+     * Protected forwarding hook (ADR-0051 cl.2), applied by the base scope-owned effect installed in
+     * `connectedCallback`. Default: internals ARIA element reflection, GUARDED on `internals.role != null` —
+     * every internals-role control (checkbox/switch/radio/slider/calendar) wires for FREE, while a role-less
+     * host deliberately no-ops (a half-attached name on a role-less AX node is silent lossiness that can fool
+     * a probe — a part-role control, e.g. text-field, MUST override instead). Contract for an override:
+     * idempotent; handle `null` (clear); guard a not-yet-created part.
+     */
+    applyFieldLabelling(refs) {
+        if (this.internals.role == null)
+            return; // role-less host — a part-role control MUST override (ADR-0051)
+        reflectAriaElements(this.internals, 'ariaLabelledByElements', refs?.label ? [refs.label] : null);
+        const described = refs ? [refs.description, refs.error].filter((el) => el !== null) : null;
+        reflectAriaElements(this.internals, 'ariaDescribedByElements', described && described.length > 0 ? described : null);
+    }
+    /**
+     * Protected user-invalid gate, feeding `FormConnectDetail.userInvalid` (ADR-0050). Default `false`. A
+     * control composing `trackUserInvalid` overrides it with its tracker's gate (`() =>
+     * tracker.userInvalid()`), keeping ONE timing source — the field's error observation rides this read
+     * (jsdom cannot match `:state(user-invalid)`; the browser gate asserts the equivalence).
+     */
+    formUserInvalid() {
+        return false;
+    }
+}
+_a = UIFormElement;

package/dist/dom/index.d.ts

@@ -0,0 +1,10 @@
+export { UIElement } from './element.js';
+export { UIFormElement, FORM_CONNECT_EVENT, FORM_RESET_EVENT } from './form.js';
+export type { FormValue, ValidityResult, FormConnectDetail, FieldLabelling } from './form.js';
+export { UIContainerElement } from './container.js';
+export { prop, Types } from './props.js';
+export type { PropType, PropConfig, PropsSchema, ReactiveProps } from './props.js';
+export { repeat } from './repeat.js';
+export { watch } from './watch.js';
+export { Directive, directive, NO_COMMIT, mount } from './template.js';
+export type { RenderContext, DirectiveResult } from './template.js';

package/dist/dom/index.js

@@ -0,0 +1,31 @@
+// dom — the element hosts (UIElement, the FACE form base UIFormElement, and the FACE container surface base
+// UIContainerElement) + the typed-prop authoring API + the G3 child directives (repeat/watch). Imports only
+// ../reactive (and same-layer ./element.ts / ./props.ts / ./form.ts / ./container.ts / ./repeat.ts / ./watch.ts).
+//
+// The PUBLIC dom surface (rubric D7): the element hosts and the typed-prop schema API a control author uses,
+// the two child directives a template author drives, PLUS the directive-AUTHORING trio + the imperative
+// `mount` host (ADR-0023). The wiring seams that connect them stay module-private and are deliberately NOT
+// re-exported here:
+//   • props.ts/element.ts plumbing — `finalize`, `coerceAttribute`, `observedAttributesFor`, `propForAttribute`,
+//     and the codec factories behind `prop.*` (`enumType`/`jsonType`).
+//   • the template ENTRY — `render` / `html` / `svg` / `TemplateResult` / `ChildPart` / `prepare`. The template
+//     machinery is internal cross-module plumbing; a directive is the only PUBLIC render unit.
+// PUBLIC since ADR-0023: directive-AUTHORING (`Directive` / `directive` / `NO_COMMIT`, plus the `RenderContext`
+// and `DirectiveResult` types) and the imperative `mount(result, container, ctx?)` host that commits a kernel
+// directive (e.g. `repeat`) into a container WITHOUT the private `html\`\`` entry — what an imperative consumer
+// (the a2ui renderer) needs to invoke AND author directives. `repeat` / `watch` remain the shipped directives.
+export { UIElement } from "./element.js";
+// The ADR-0050/0051 protocol surface (G7): the `ui-form-connect`/`ui-form-reset` event names + the connect
+// detail shape are PUBLIC so a registry controller (traits/form-registry.ts) and a consuming control
+// (controls/field/) can listen/type against them without reaching into `./form.ts` directly.
+export { UIFormElement, FORM_CONNECT_EVENT, FORM_RESET_EVENT } from "./form.js";
+// The FACE container surface base (G9, ADR-0015/0016) — NOT form-associated. The shared spreadable surface +
+// flex prop schemas ride its statics (`UIContainerElement.surfaceProps` / `.flexProps`), the ADR-0013 formProps
+// precedent: a subclass folds them into its OWN `static props`, so there is no standalone schema value to
+// re-export — the class IS the surface (matching how `UIFormElement` carries `formProps`).
+export { UIContainerElement } from "./container.js";
+export { prop, Types } from "./props.js";
+export { repeat } from "./repeat.js";
+export { watch } from "./watch.js";
+// The directive-authoring trio + the imperative mount host (ADR-0023). `render`/`html`/`ChildPart` stay private.
+export { Directive, directive, NO_COMMIT, mount } from "./template.js";

package/dist/dom/props.d.ts

@@ -0,0 +1,56 @@
+export interface PropType<T> {
+    from(attr: string | null): T;
+    to(value: T): string | null;
+}
+/** A codec for a fixed string-literal set; `from` snaps an unknown attribute back to the first member. */
+export declare function enumType<T extends readonly string[]>(values: T): PropType<T[number]>;
+/** A codec for an arbitrary JSON-serializable value of type `T` (round-trips via JSON). */
+export declare function jsonType<T>(): PropType<T>;
+/** The three fixed codecs (the parametric `enumType`/`jsonType` are factories above). */
+export declare const Types: {
+    string: PropType<string>;
+    number: PropType<number | null>;
+    boolean: PropType<boolean>;
+};
+export interface PropConfig<T> {
+    type: PropType<T>;
+    default: T;
+    attribute?: string | false;
+    reflect?: boolean;
+}
+export declare const prop: {
+    string(def?: string): PropConfig<string>;
+    number(def?: number | null): PropConfig<number | null>;
+    boolean(def?: boolean): PropConfig<boolean>;
+    enum<const T extends readonly string[]>(values: T, def: T[number]): PropConfig<T[number]>;
+    json<T>(def: T): PropConfig<T>;
+};
+export type PropsSchema = Record<string, PropConfig<unknown>>;
+export type ReactiveProps<S extends PropsSchema> = {
+    [K in keyof S]: S[K] extends PropConfig<infer T> ? T : never;
+};
+/** A constructor-like with a `static props` schema — what `finalize` installs accessors onto. */
+export interface Finalizable {
+    prototype: object;
+    props?: PropsSchema;
+}
+/** Install signal-backed prototype accessors from `Ctor.props`. Idempotent (safe to call once per class). */
+export declare function finalize(ctor: Finalizable): void;
+/**
+ * Inbound seam (the first of the two boundary functions): cross an attribute STRING (or `null` for
+ * absence) into the typed prop signal via the prop's `PropType.from` codec, and return the coerced
+ * value. This is the primitive the element slice's `attributeChangedCallback` (e-attrs, later) composes
+ * on — p-install owns the per-instance store + the string→typed crossing; it does NOT own the platform
+ * callback. A no-op for an unknown prop name.
+ *
+ * Two directional-lock interactions (rubric D3): (1) if an outbound reflect for this prop is in flight,
+ * this call is that reflect's own platform echo — suppress it (return `undefined`) so it cannot loop.
+ * (2) Otherwise write through the installed accessor under the `inbound` lock, so the setter applies the
+ * value but does NOT reflect it straight back out. The write goes through the setter (not the raw signal)
+ * precisely so that symmetric guard is load-bearing: one write path, the lock decides whether it reflects.
+ */
+export declare function coerceAttribute(instance: object, ctor: Finalizable, name: string, attr: string | null): unknown;
+/** The attribute names to observe for a finalized ctor: each prop's attribute name, minus property-only props. */
+export declare function observedAttributesFor(ctor: Finalizable): string[];
+/** Reverse the mapping: the prop name owning a given attribute name (respecting `attribute` overrides), or `undefined`. */
+export declare function propForAttribute(ctor: Finalizable, attr: string): string | undefined;