@typed/ui 1.0.0-beta.5 → 1.0.0-beta.7

package/dist/Form.js

@@ -1,9 +1,22 @@
+/**
+ * Schema-bound native controls, decoded values, field errors, and submit lifetime.
+ * Start with make for application forms; explicit-state controls support library boundaries.
+ * Browser FormData conversion and structured input codecs are separate APIs.
+ *
+ * Read the [Form guide](/explore/ui-form) for a complete example.
+ *
+ * [Platform reference](https://html.spec.whatwg.org/multipage/forms.html#the-form-element).
+ * @since 1.0.0
+ * @category Overview
+ * @packageDocumentation
+ */
 import * as Effect from "effect/Effect";
 import * as Context from "effect/Context";
 import * as Schema from "effect/Schema";
 import * as SchemaIssue from "effect/SchemaIssue";
 import * as SchemaTransformation from "effect/SchemaTransformation";
-import { Fx as FxApi, RefSubject } from "@typed/fx";
+import { Fx as FxApi, RefSubject, Subject } from "@typed/fx";
+import * as Scope from "effect/Scope";
 import { EventHandler, html, } from "@typed/template";
 import * as Dom from "./Dom.js";
 let nextFormId = 0;
@@ -11,16 +24,13 @@ let nextFormId = 0;
  * Effect context service used by schema-bound form controls.
  *
  * @remarks
- * ## Why
  * Bound controls avoid threading `state` through every call while their
  * service requirement remains visible in the Fx type.
  *
- * ## Ownership and lifetime
  * `Form` provides the service for its child render lifetime; use outside that
  * boundary fails with the ordinary Effect missing-service defect.
- *
  * @since 1.0.0
- * @category services
+ * @category Form context
  */
 export const CurrentForm = Context.Service("@typed/ui/Form/CurrentForm");
 function withCurrentForm() {
@@ -43,10 +53,8 @@ function emptyOptionalFields() {
  * Builds the serializable schema for a form's hydrated state.
  *
  * @remarks
- * ## Why
  * The hydration payload needs validation independent from runtime-only field codecs.
  *
- * ## Ownership and lifetime
  * Pure schema construction; the returned Schema acquires no Scope or subscription.
  *
  * @example
@@ -57,9 +65,8 @@ function emptyOptionalFields() {
  * const codec = Schema.Struct({ email: Schema.String })
  * const stateCodec = StateSchema(codec)
  * ```
- *
  * @since 1.0.0
- * @category schemas
+ * @category Hydration schemas
  */
 export function StateSchema(codec) {
     return Schema.Struct({
@@ -74,11 +81,9 @@ export function StateSchema(codec) {
  * Creates a Scope-owned hydrated form RefSubject from a Struct codec.
  *
  * @remarks
- * ## Why
  * One constructor establishes values, defaults, validation state, field codecs,
  * and hydration identity consistently.
  *
- * ## Ownership and lifetime
  * Requires `Scope.Scope`. Provide an explicit `id` during SSR; the counter-based
  * fallback is process/order dependent. Only state data hydrates—`codec` and
  * `fields` are reattached from the live Struct on each runtime.
@@ -94,9 +99,8 @@ export function StateSchema(codec) {
  *   return state
  * })
  * ```
- *
  * @since 1.0.0
- * @category constructors
+ * @category State construction
  */
 export function makeState(codec, initial) {
     const id = initial.id ?? `typed-form-${++nextFormId}`;
@@ -128,6 +132,9 @@ function decodeUpdatedField(state, name, encoded) {
     return Schema.decodeUnknownEffect(state.fields[name])(encoded).pipe(Effect.flatMap((decoded) => Effect.andThen(updateDecodedValue(state, name, decoded), () => setFieldError(state, name, undefined))), Effect.catch((error) => setFieldError(state, name, error.message)));
 }
 function inputProps(options, type, codec) {
+    const parts = maskParts.get(codec);
+    if (parts !== undefined)
+        return maskedInputProps(options, type, codec, parts);
     return () => ({
         type,
         name: options.name,
@@ -141,7 +148,7 @@ function inputProps(options, type, codec) {
 }
 function renderInput(options, host, type, defaultCodec) {
     const codec = options.codec ?? defaultCodec;
-    return Dom.renderHost()(options, host, inputProps(options, type, codec), "", (props) => html `<input ...${props} />`);
+    return FxApi.suspend(() => Dom.renderHost()(options, host, inputProps(options, type, codec), "", (props) => html `<input ...${props} />`));
 }
 function makeInput(type, codec) {
     return function (options, host) {
@@ -161,11 +168,9 @@ function makeSchemaBoundInput(formCodec, type) {
  * Binds a native `input[type=text]` to a string field.
  *
  * @remarks
- * ## Why
  * The control uses the browser's real input event and a Schema codec while
  * keeping state independently testable.
  *
- * ## Ownership and lifetime
  * The control Scope owns DOM listeners/subscriptions; the supplied `FormState`
  * may outlive the rendered input. A custom host must apply all merged props.
  *
@@ -180,173 +185,124 @@ function makeSchemaBoundInput(formCodec, type) {
  *   return TextInput({ state, name: "name" })
  * })
  * ```
- *
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const TextInput = makeInput("text", Schema.String);
 /**
  * Binds a native search input to a string field.
  * @remarks
- * ## Why
  * Preserves the platform's search-input semantics while sharing Typed validation.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const SearchInput = makeInput("search", Schema.String);
 /**
  * Binds a native email input to a string field.
  * @remarks
- * ## Why
  * Keeps browser email affordances and constraints available alongside Schema validation.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const EmailInput = makeInput("email", Schema.String);
 /**
  * Binds a native URL input to a string field.
  * @remarks
- * ## Why
  * Keeps browser URL affordances while the schema remains the decoded state contract.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const UrlInput = makeInput("url", Schema.String);
 /**
  * Binds a native telephone input to a string field.
  * @remarks
- * ## Why
  * Preserves platform telephone keyboards and autocomplete behavior.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const TelInput = makeInput("tel", Schema.String);
 /**
  * Binds a native password input to a string field.
  * @remarks
- * ## Why
  * Uses browser password handling instead of recreating sensitive-input behavior.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const PasswordInput = makeInput("password", Schema.String);
 /**
  * Binds a native hidden input to a string field.
  * @remarks
- * ## Why
  * Allows standards-based form serialization for non-visible values.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const HiddenInput = makeInput("hidden", Schema.String);
 /**
  * Binds a native color input to a string field.
  * @remarks
- * ## Why
  * Retains the browser's color picker while state receives its string value.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const ColorInput = makeInput("color", Schema.String);
 /**
  * Binds a native time input to a string field.
  * @remarks
- * ## Why
  * Preserves browser locale and time-entry behavior without inventing a picker.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const TimeInput = makeInput("time", Schema.String);
 /**
  * Binds a native local date-time input to a string field.
  * @remarks
- * ## Why
  * Keeps the platform's local date-time UI and its standard encoded value.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const DateTimeLocalInput = makeInput("datetime-local", Schema.String);
 /**
  * Binds a native month input to a string field.
  * @remarks
- * ## Why
  * Preserves the browser month picker and standardized string encoding.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const MonthInput = makeInput("month", Schema.String);
 /**
  * Binds a native week input to a string field.
  * @remarks
- * ## Why
  * Preserves platform week-entry behavior and standardized string encoding.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const WeekInput = makeInput("week", Schema.String);
 /**
  * Binds a native number input to a finite number field.
  * @remarks
- * ## Why
  * `FiniteFromString` makes the browser's string value an explicit typed decode.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const NumberInput = makeInput("number", Schema.FiniteFromString);
 /**
  * Binds a native range input to a finite number field.
  * @remarks
- * ## Why
  * Retains native slider interaction while exposing a decoded numeric value.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const RangeInput = makeInput("range", Schema.FiniteFromString);
 /**
  * Binds a native date input to a `Date` field.
  * @remarks
- * ## Why
  * `DateFromString` makes the native encoded value's conversion explicit and fallible.
- * ## Ownership and lifetime
- * DOM work is control-Scope-owned; form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export const DateInput = makeInput("date", Schema.DateFromString);
 /**
- * Converts native FormData to a record and preserves repeated fields as arrays.
- * @remarks
- * ## Why
- * `Object.fromEntries` silently loses repeated names, which breaks checkbox,
- * multiselect, and multi-file submissions.
- * ## Ownership and lifetime
- * The function is synchronous and resource-free; File values are not cloned.
+ * Converts native form data to a record, preserving repeated names as arrays.
  * @example
  * ```ts
  * import { formDataToRecord } from "@typed/ui/Form"
@@ -357,7 +313,7 @@ export const DateInput = makeInput("date", Schema.DateFromString);
  * const record = formDataToRecord(data)
  * ```
  * @since 1.0.0
- * @category conversions
+ * @category Browser form data
  */
 export function formDataToRecord(data) {
     const result = {};
@@ -375,10 +331,8 @@ export function formDataToRecord(data) {
 /**
  * Decodes native FormData through an Effect Schema codec.
  * @remarks
- * ## Why
  * Browser serialization, repeated values, Files, and typed validation meet at
  * one explicit fallible boundary.
- * ## Ownership and lifetime
  * The returned Effect is lazy and owns no browser resource; it references File
  * objects present in the supplied FormData.
  * @example
@@ -389,21 +343,21 @@ export function formDataToRecord(data) {
  * const decode = decodeFormData(Schema.Struct({ name: Schema.String }), new FormData())
  * ```
  * @since 1.0.0
- * @category conversions
+ * @category Browser form data
  */
 export function decodeFormData(codec, data) {
     return Schema.decodeEffect(codec)(formDataToRecord(data));
 }
 /**
- * Validates current form values and synchronizes decoded values or field errors.
+ * Checks retained decoded values against the form codec Type.
+ *
  * @remarks
- * ## Why
- * Submission needs one whole-form schema check in addition to incremental field decoding.
- * ## Ownership and lifetime
- * The returned Effect updates the supplied state when run. On success it clears
- * errors; on failure it records messages and re-fails with `SchemaError`.
+ * Success replaces values and clears errors. Failure copies the aggregate schema message across
+ * fields and re-fails with SchemaError; this is not per-field issue-path mapping. A prior input
+ * decode error does not independently block success when the retained decoded value still
+ * validates.
  * @since 1.0.0
- * @category validation
+ * @category Validation
  */
 export function validate(state) {
     return Effect.flatMap(state, (current) => Schema.decodeUnknownEffect(Schema.toType(state.codec))(current.values)).pipe(Effect.flatMap((values) => Effect.as(RefSubject.update(state, (current) => ({
@@ -424,9 +378,7 @@ function formErrors(values, errors, error) {
 /**
  * Creates a named, Schema-decoded mask slot.
  * @remarks
- * ## Why
  * Length and character constraints are expressed beside the codec that owns conversion.
- * ## Ownership and lifetime
  * Pure constructor; the returned descriptor retains the codec but acquires no Scope.
  * @example
  * ```ts
@@ -436,19 +388,21 @@ function formErrors(values, errors, error) {
  * const areaCode = slot("area", Schema.String, { length: 3, charset: /[0-9]/ })
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Input codecs
  */
 export function slot(name, codec, options = {}) {
     return { _tag: "MaskSlot", name, codec, ...options };
 }
+const maskParts = new WeakMap();
+const maskedInputResets = new WeakMap();
 /**
  * Builds a bidirectional Schema codec from literal text and named slots.
  * @remarks
- * ## Why
- * Display formatting and decoding share one ordered specification and produce
- * ordinary Schema issues on invalid length, characters, literals, or slot values.
- * ## Ownership and lifetime
- * Pure codec construction. Decode/encode Effects are lazy and Scope-free.
+ * Strict encoding and decoding share the same parts and reject invalid length,
+ * characters, literals, or slot values. MaskedInput also uses these parts to
+ * retain drafts and format fixed-width slots with explicit charsets. Literal
+ * characters must be distinguishable from editable characters for auto-formatting;
+ * ambiguous or variable-width masks retain ordinary strict text entry.
  * @example
  * ```ts
  * import { mask, slot } from "@typed/ui/Form"
@@ -458,16 +412,223 @@ export function slot(name, codec, options = {}) {
  *   slot("number", Schema.String, { length: 7 }))
  * ```
  * @since 1.0.0
- * @category schemas
+ * @category Input codecs
  */
 export function mask(...parts) {
     const valueSchema = Schema.declare((value) => typeof value === "object" &&
         value !== null &&
         parts.every((part) => typeof part === "string" || Reflect.has(value, part.name)));
-    return Schema.String.pipe(Schema.decodeTo(valueSchema, SchemaTransformation.transformOrFail({
+    const codec = Schema.String.pipe(Schema.decodeTo(valueSchema, SchemaTransformation.transformOrFail({
         decode: (display, options) => decodeMask(parts, display, options),
         encode: (value, options) => encodeMask(parts, value, options),
     })));
+    maskParts.set(codec, parts);
+    return codec;
+}
+function maskedInputProps(options, type, codec, parts) {
+    return () => {
+        let draft;
+        let lastValue;
+        let composing = false;
+        let invalidDraft = false;
+        let editRevision = 0;
+        let pending;
+        let input;
+        const format = maskDraftFormatter(parts);
+        const message = `Enter a complete value in the format ${parts
+            .map((part) => (typeof part === "string" ? part : "_".repeat(part.length ?? 3)))
+            .join("")}.`;
+        const commit = Effect.fn(function* (element) {
+            const revision = ++editRevision;
+            const snapshot = yield* options.state;
+            pending = snapshot;
+            input = element;
+            const formatted = format?.(element.value, element.selectionStart ?? element.value.length);
+            if (formatted !== undefined) {
+                element.value = formatted.value;
+                element.setSelectionRange(formatted.cursor, formatted.cursor);
+            }
+            draft = element.value;
+            return yield* Schema.decodeEffect(codec)(draft).pipe(Effect.matchEffect({
+                onSuccess: Effect.fn(function* (decoded) {
+                    if (revision !== editRevision ||
+                        (yield* options.state).values[options.name] !== snapshot.values[options.name])
+                        return;
+                    pending = undefined;
+                    lastValue = decoded;
+                    invalidDraft = false;
+                    element.setCustomValidity("");
+                    yield* updateDecodedValue(options.state, options.name, decoded);
+                    yield* setFieldError(options.state, options.name, undefined);
+                }),
+                onFailure: Effect.fn(function* () {
+                    if (revision !== editRevision ||
+                        (yield* options.state).values[options.name] !== snapshot.values[options.name])
+                        return;
+                    pending = undefined;
+                    invalidDraft = true;
+                    element.setCustomValidity(message);
+                    yield* setFieldError(options.state, options.name, message);
+                }),
+            }));
+        });
+        return {
+            type,
+            name: options.name,
+            "aria-describedby": RefSubject.map(options.state, (state) => state.errors[options.name] === undefined
+                ? undefined
+                : fieldErrorId(options.state, options.name)),
+            "aria-invalid": RefSubject.map(options.state, (state) => state.errors[options.name] === undefined ? undefined : true),
+            ".value": Effect.flatMap(options.state, (state) => Schema.encodeUnknownEffect(codec)(state.values[options.name])),
+            ref: Effect.fn(function* (element) {
+                input = element;
+                const initial = yield* options.state;
+                lastValue = initial.values[options.name];
+                const resetInput = Effect.gen(function* () {
+                    const revision = ++editRevision;
+                    pending = undefined;
+                    draft = undefined;
+                    invalidDraft = false;
+                    composing = false;
+                    const value = (yield* options.state).values[options.name];
+                    lastValue = value;
+                    element.setCustomValidity("");
+                    const encoded = yield* Schema.encodeUnknownEffect(codec)(value);
+                    if (revision === editRevision && (yield* options.state).values[options.name] === value) {
+                        element.value = encoded;
+                    }
+                });
+                let resets = maskedInputResets.get(options.state);
+                if (resets === undefined) {
+                    resets = { signal: Subject.unsafeMake(), users: 0 };
+                    maskedInputResets.set(options.state, resets);
+                }
+                const resetSignal = resets;
+                resetSignal.users++;
+                yield* Scope.addFinalizer(yield* Effect.scope, Effect.suspend(() => {
+                    if (--resetSignal.users > 0)
+                        return Effect.void;
+                    maskedInputResets.delete(options.state);
+                    return resetSignal.signal.interrupt;
+                }));
+                yield* Effect.forkScoped(FxApi.observe(resetSignal.signal, () => resetInput));
+                yield* Effect.forkScoped(FxApi.observe(options.state, Effect.fn(function* (state) {
+                    if (pending !== undefined &&
+                        state.values[options.name] !== pending.values[options.name]) {
+                        pending = undefined;
+                        editRevision++;
+                        draft = undefined;
+                        invalidDraft = false;
+                    }
+                    const value = state.values[options.name];
+                    if (value === lastValue &&
+                        (composing ||
+                            (draft !== undefined &&
+                                (!invalidDraft || state.errors[options.name] !== undefined))))
+                        return;
+                    lastValue = value;
+                    draft = undefined;
+                    invalidDraft = false;
+                    element.setCustomValidity("");
+                    const revision = editRevision;
+                    const encoded = yield* Schema.encodeUnknownEffect(codec)(value);
+                    if (revision === editRevision &&
+                        (yield* options.state).values[options.name] === value &&
+                        element.value !== encoded) {
+                        element.value = encoded;
+                    }
+                })));
+            }),
+            onbeforeinput: EventHandler.make(Effect.fn(function* (event) {
+                if (event.isComposing || composing || !event.cancelable || format === undefined)
+                    return;
+                if (event.inputType !== "deleteContentBackward" &&
+                    event.inputType !== "deleteContentForward")
+                    return;
+                const element = Dom.currentTarget(event);
+                const start = element.selectionStart;
+                if (start === null || start !== element.selectionEnd)
+                    return;
+                const backwards = event.inputType === "deleteContentBackward";
+                const separators = parts
+                    .filter((part) => typeof part === "string")
+                    .join("");
+                let index = backwards ? start - 1 : start;
+                if (!separators.includes(element.value[index] ?? "\u0000"))
+                    return;
+                while (index >= 0 &&
+                    index < element.value.length &&
+                    separators.includes(element.value[index])) {
+                    index += backwards ? -1 : 1;
+                }
+                if (index < 0 || index >= element.value.length)
+                    return;
+                event.preventDefault();
+                element.setRangeText("", index, index + 1, "start");
+                return yield* commit(element);
+            })),
+            oninput: EventHandler.make(Effect.fn(function* (event) {
+                input = Dom.currentTarget(event);
+                if (composing || event.isComposing)
+                    return;
+                return yield* commit(input);
+            })),
+            oncompositionstart: EventHandler.make(() => Effect.sync(() => {
+                composing = true;
+            })),
+            oncompositionend: EventHandler.make(Effect.fn(function* (event) {
+                composing = false;
+                return yield* commit(Dom.currentTarget(event));
+            })),
+        };
+    };
+}
+// Only auto-format when fixed-width slots explicitly distinguish editable
+// characters from literals. Ambiguous/variable-width codecs still retain drafts
+// and validate, without guessing which characters the user meant to enter.
+function maskDraftFormatter(parts) {
+    const slots = parts.filter((part) => typeof part !== "string");
+    const literals = parts.filter((part) => typeof part === "string").join("");
+    if (slots.length === 0 ||
+        slots.some((slot) => slot.length === undefined || slot.charset === undefined || slot.length < 1) ||
+        [...literals].some((character) => slots.some((slot) => matchesCharset(slot, character))))
+        return undefined;
+    return (text, cursor) => {
+        const characters = [];
+        let beforeCursor = 0;
+        for (let index = 0; index < text.length; index++) {
+            const character = text[index];
+            if (literals.includes(character))
+                continue;
+            characters.push(character);
+            if (index < cursor)
+                beforeCursor++;
+        }
+        let offset = 0;
+        let value = "";
+        let nextCursor = 0;
+        for (const [index, part] of parts.entries()) {
+            if (typeof part === "string") {
+                const complete = characters.length === slots.reduce((sum, slot) => sum + slot.length, 0);
+                const suffix = parts.slice(index + 1).every((remaining) => typeof remaining === "string");
+                if (offset < characters.length || (complete && suffix))
+                    value += part;
+                continue;
+            }
+            const segment = characters.slice(offset, offset + part.length);
+            if (segment.some((character) => !matchesCharset(part, character)))
+                return undefined;
+            for (const character of segment) {
+                value += character;
+                offset++;
+                if (offset <= beforeCursor)
+                    nextCursor = value.length;
+            }
+        }
+        if (offset !== characters.length)
+            return undefined;
+        return { value, cursor: beforeCursor === characters.length ? value.length : nextCursor };
+    };
 }
 function decodeMask(parts, display, options) {
     return Effect.gen(function* () {
@@ -541,14 +702,15 @@ function invalidMask(input, options) {
 /**
  * Binds a native text input to a structured mask value.
  * @remarks
- * ## Why
- * The supplied Schema codec controls both display encoding and input decoding;
- * failed edits update field errors rather than corrupting decoded state.
- * ## Ownership and lifetime
- * DOM listeners and reactive value binding live in the control Scope. The
- * supplied state can be tested and retained without mounting this control.
+ * A codec created by mask supplies the editable format. Fixed-width slots with
+ * explicit charsets receive literal insertion and caret-aware deletion; other
+ * codecs retain strict text entry. Incomplete drafts remain visible while decoded
+ * state keeps its previous value. Native custom validity and field error text
+ * prevent native submission of an incomplete mask. Composition is committed only
+ * after compositionend. New edits and resets supersede pending slot decoders.
+ * Each mounted input owns its draft observer and reset registration in Scope.
  * @since 1.0.0
- * @category components
+ * @category Input codecs
  */
 export function MaskedInput(options, host) {
     const { mask, ...inputOptions } = options;
@@ -571,14 +733,12 @@ function checkboxProps(options) {
 /**
  * Binds a native checkbox to a boolean form field.
  * @remarks
- * ## Why
  * Both the checked attribute and live property follow state, while the browser's
  * real change event is decoded through the field codec.
- * ## Ownership and lifetime
  * The rendered Scope owns the input, listener, and subscriptions. A custom host
  * must apply merged name, ARIA, checked, and change props.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export function Checkbox(options, host) {
     return Dom.renderHost()(options, host, checkboxProps(options), "", (props) => html `<input ...${props} />`);
@@ -597,13 +757,11 @@ function selectProps(options) {
 /**
  * Binds a native select element to a string form field.
  * @remarks
- * ## Why
  * Native keyboard, accessibility, option, and form semantics remain browser-owned.
- * ## Ownership and lifetime
  * The rendered Scope owns the select/content subscriptions. A custom host must
  * preserve supplied name, ARIA, value, and change props.
  * @since 1.0.0
- * @category components
+ * @category Native controls
  */
 export function Select(options, host) {
     return Dom.renderHost()(options, host, selectProps(options), options.content, (props, content) => html `<select ...${props}>
@@ -616,12 +774,10 @@ function labelProps(options) {
 /**
  * Renders a native label with an explicit control relationship.
  * @remarks
- * ## Why
  * The browser supplies click-to-focus and accessible-name behavior with no synthetic layer.
- * ## Ownership and lifetime
  * The Scope owns label output/content; the referenced element remains separately owned.
  * @since 1.0.0
- * @category components
+ * @category Field relationships
  */
 export function Label(options, host) {
     return Dom.renderHost()(options, host, labelProps(options), options.content, (props, content) => html `<label ...${props}>${content}</label>`);
@@ -630,14 +786,13 @@ function descriptionProps() {
     return () => ({});
 }
 /**
- * Renders form description content in a neutral native div by default.
+ * Renders visible explanatory content in a neutral div.
+ *
  * @remarks
- * ## Why
- * Consumers can connect the resulting element with ordinary ARIA props where needed.
- * ## Ownership and lifetime
- * The Scope owns the description host/content and no external control.
+ * No control relationship is created automatically. The current input binding owns its generated
+ * error aria-describedby; do not assume consumer description IDs are merged into it.
  * @since 1.0.0
- * @category components
+ * @category Field relationships
  */
 export function Description(options, host) {
     return Dom.renderHost()(options, host, descriptionProps(), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
@@ -649,15 +804,14 @@ function errorProps(options) {
     });
 }
 /**
- * Renders the current field error as a native ARIA alert region.
+ * Renders the named field message with a generated ID and alert role.
+ *
  * @remarks
- * ## Why
- * The same derived ID is placed on the error and in the control's
- * `aria-describedby`, keeping validation messaging coherent.
- * ## Ownership and lifetime
- * The Scope owns the alert and state subscription; removing it does not remove form state.
+ * Bound inputs refer to this ID through aria-describedby and expose aria-invalid when an error
+ * exists. Keep the form ID stable and render one matching error host per field. Alert timing
+ * still depends on the browser and assistive technology; this is not an announcement queue.
  * @since 1.0.0
- * @category components
+ * @category Field relationships
  */
 export function Error(options, host) {
     const content = RefSubject.map(options.state, (state) => state.errors[options.name] ?? "");
@@ -669,12 +823,10 @@ function submitProps() {
 /**
  * Renders a native `type=submit` button.
  * @remarks
- * ## Why
  * Keyboard activation, form association, and accessibility stay browser-standard.
- * ## Ownership and lifetime
  * The Scope owns the button/content; the surrounding Form owns submission sequencing.
  * @since 1.0.0
- * @category components
+ * @category Form actions
  */
 export function Submit(options, host) {
     return Dom.renderHost()(options, host, submitProps(), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
@@ -688,13 +840,11 @@ function resetProps(options) {
 /**
  * Renders a native reset button that restores Typed form defaults.
  * @remarks
- * ## Why
  * It prevents the browser's independent control mutation and resets the single
  * RefSubject source of truth, clearing errors, metadata, and submitting state.
- * ## Ownership and lifetime
  * The Scope owns the click handler/content. The supplied form state remains independently owned.
  * @since 1.0.0
- * @category components
+ * @category Form actions
  */
 export function Reset(options, host) {
     return Dom.renderHost()(options, host, resetProps(options), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
@@ -705,12 +855,10 @@ function groupProps(options) {
 /**
  * Renders an ARIA group with an optional accessible name.
  * @remarks
- * ## Why
  * Related controls can expose their relationship without a framework-specific wrapper.
- * ## Ownership and lifetime
  * The Scope owns host/content; child controls retain their own DOM/state contracts.
  * @since 1.0.0
- * @category components
+ * @category Field relationships
  */
 export function Group(options, host) {
     return Dom.renderHost()(options, host, groupProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
@@ -724,12 +872,10 @@ function pushProps(options) {
 /**
  * Renders a button that appends one item to an array field.
  * @remarks
- * ## Why
  * Array mutation is immutable, typed, and marks the field dirty/touched.
- * ## Ownership and lifetime
  * The Scope owns the button handler/content; state may outlive the button.
  * @since 1.0.0
- * @category components
+ * @category Form actions
  */
 export function Push(options, host) {
     return Dom.renderHost()(options, host, pushProps(options), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
@@ -743,25 +889,23 @@ function removeProps(options) {
 /**
  * Renders a button that removes one array item by index.
  * @remarks
- * ## Why
  * Array mutation is immutable, typed, and marks the field dirty/touched.
- * ## Ownership and lifetime
  * The Scope owns the button handler/content; state may outlive the button.
  * @since 1.0.0
- * @category components
+ * @category Form actions
  */
 export function Remove(options, host) {
     return Dom.renderHost()(options, host, removeProps(options), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
 }
 /**
- * Sets one decoded field value and updates dirty/touched metadata.
+ * Assigns one decoded field value and updates dirty/touched metadata.
+ *
  * @remarks
- * ## Why
- * Programmatic updates use the same renderer-independent state transition as controls.
- * ## Ownership and lifetime
- * The returned Effect mutates only the supplied RefSubject when run.
+ * The helper does not decode or validate the supplied value and does not clear an existing field
+ * error. Use validate for an explicit whole-form check. Dirty tracking compares against the
+ * default field with !==; updates replace the top-level values record.
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export function setValue(state, key, value) {
     return updateDecodedValue(state, key, value);
@@ -782,15 +926,13 @@ function updateRecord(values, key, value) {
     return updated;
 }
 /**
- * Restores default values and clears errors, interaction metadata, and submission state.
+ * Restores default values and clears errors, metadata, and submitting.
+ *
  * @remarks
- * ## Why
- * Resetting the RefSubject, rather than only DOM controls, keeps every renderer
- * and test observer consistent with the source of truth.
- * ## Ownership and lifetime
- * The returned Effect performs one update when run and requires the same services as `state`.
+ * The defaultValues object is reused rather than deep-cloned. This state operation does not
+ * cancel a running submission Effect or reset independently owned result state.
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export function reset(state) {
     return RefSubject.update(state, (current) => ({
@@ -799,17 +941,15 @@ export function reset(state) {
         errors: {},
         meta: {},
         submitting: false,
-    }));
+    })).pipe(Effect.tap(() => Effect.suspend(() => maskedInputResets.get(state)?.signal.onSuccess(undefined) ?? Effect.void)));
 }
 /**
  * Appends one item to an array field and marks it dirty and touched.
  * @remarks
- * ## Why
  * The immutable state transition is usable in tests, commands, or any renderer.
- * ## Ownership and lifetime
  * The returned Effect performs one RefSubject update when run.
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export function pushValue(state, name, value) {
     return RefSubject.update(state, (current) => {
@@ -825,12 +965,10 @@ export function pushValue(state, name, value) {
 /**
  * Removes one item by index from an array field and marks it dirty and touched.
  * @remarks
- * ## Why
  * The transition is explicit and renderer-independent; an out-of-range index leaves values unchanged.
- * ## Ownership and lifetime
  * The returned Effect performs one RefSubject update when run.
  * @since 1.0.0
- * @category state
+ * @category State transitions
  */
 export function removeValue(state, name, index) {
     return RefSubject.update(state, (current) => {
@@ -860,16 +998,14 @@ function formProps(options) {
     });
 }
 /**
- * Renders a native form and provides its state to schema-bound descendants.
+ * Renders a native form and provides its state to bound descendants.
+ *
  * @remarks
- * ## Why
- * Native submission is intercepted once, whole-form Schema validation runs,
- * then `onValidSubmit` receives decoded values. Reset updates the RefSubject so
- * all renderers stay coherent.
- * ## Ownership and lifetime
- * The root Scope owns its listeners/content and `CurrentForm` service. A valid
- * submit Effect runs in that lifetime; `submitting` is cleared in finalization
- * even on failure or interruption. Hydration does not itself attach client UI.
+ * The submit listener synchronously prevents browser navigation, marks submitting, validates
+ * decoded state, and runs onValidSubmit on success. Finalization clears submitting. Native
+ * constraint validation can prevent submit dispatch before this handler runs. The root does not
+ * read FormData, serialize a request, cancel duplicate submissions, or infer server errors.
+ *
  * @example
  * ```ts
  * import { Form, Submit, TextInput, makeState } from "@typed/ui/Form"
@@ -887,7 +1023,7 @@ function formProps(options) {
  * })
  * ```
  * @since 1.0.0
- * @category components
+ * @category Form roots
  */
 export function Form(options, host) {
     const rendered = Dom.renderHost()(options, host, formProps(options), options.content, (props, content) => html `<form ...${props}>${content}</form>`);
@@ -896,32 +1032,51 @@ export function Form(options, host) {
     });
 }
 /**
- * Creates a schema-bound form component family from one Struct codec.
+ * Binds a native form component family to one Struct codec.
+ *
  * @remarks
- * ## Why
- * Defining the schema once removes repeated state/codec arguments and makes
- * incompatible field/component combinations compile-time errors.
- * ## Ownership and lifetime
- * Factory creation is pure and retains the codec. `state` requires Scope and
- * returns a hydrated RefSubject. `Root` provides that state through Effect
- * context only for its render lifetime; controls borrow it.
+ * state accepts decoded defaults and allocates a Scope-owned hydrated subject. Root provides
+ * that form through CurrentForm. Bound controls select compatible field names from both decoded
+ * and encoded schema types; their context requirement remains in the Fx until Root provides it.
+ * Use explicit stable IDs when server rendering and hydrating.
+ *
  * @example
  * ```ts
- * import { make } from "@typed/ui/Form"
- * import { Effect, Schema } from "effect"
- * import { html } from "@typed/template"
+ * import { Schema } from "effect";
+ * import { html } from "@typed/template";
+ * import { RefSubject } from "@typed/fx";
+ * import { component } from "@typed/ui/Component";
+ * import * as Form from "@typed/ui/Form";
  *
- * const Signup = make(Schema.Struct({ email: Schema.String, accepted: Schema.Boolean }))
- * const view = Effect.gen(function* () {
- *   const form = yield* Signup.state({ email: "", accepted: false }, { id: "signup" })
- *   return Signup.Root({
+ * const Order = Form.make(Schema.Struct({
+ *   copies: Schema.FiniteFromString.pipe(Schema.check(Schema.isGreaterThan(0))),
+ *   includeNotes: Schema.Boolean,
+ * }));
+ *
+ * export const PrintOrder = component(function* () {
+ *   const form = yield* Order.state({ copies: 1, includeNotes: false }, { id: "print-order" });
+ *   const submitting = RefSubject.map(form, (state) => state.submitting);
+ *   const preview = yield* RefSubject.make("No print request preview yet.");
+ *   return html`<section>${Order.Root({
  *     form,
- *     content: html`${Signup.EmailInput({ name: "email" })}${Signup.Checkbox({ name: "accepted" })}`
- *   })
- * })
+ *     content: [
+ *       Order.Label({ for: "order-copies", content: "Copies" }),
+ *       Order.NumberInput({ name: "copies", props: { id: "order-copies", min: 1, required: true } }),
+ *       Order.Error({ name: "copies" }),
+ *       Order.Checkbox({ name: "includeNotes", props: { id: "order-notes" } }),
+ *       Order.Label({ for: "order-notes", content: "Include speaker notes" }),
+ *       Order.Submit({ content: "Preview print request", props: { "?disabled": submitting } }),
+ *       Order.Reset({ content: "Restore defaults" }),
+ *     ],
+ *     onValidSubmit: (values) => RefSubject.set(
+ *       preview,
+ *       `${values.copies} copies; notes ${values.includeNotes ? "included" : "excluded"}.`,
+ *     ),
+ *   })}<p role="status">${preview}</p></section>`;
+ * });
  * ```
  * @since 1.0.0
- * @category constructors
+ * @category Schema-bound components
  */
 export function make(codec) {
     const state = (values, options = {}) => makeState(codec, { ...options, values });