@typed/ui 1.0.0-beta.1 → 1.0.0-beta.11

package/dist/Form.js

@@ -0,0 +1,1142 @@
+/**
+ * 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, 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;
+/**
+ * Effect context service used by schema-bound form controls.
+ *
+ * @remarks
+ * Bound controls avoid threading `state` through every call while their
+ * service requirement remains visible in the Fx type.
+ *
+ * `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 Form context
+ */
+export const CurrentForm = Context.Service("@typed/ui/Form/CurrentForm");
+function withCurrentForm() {
+    return (f) => FxApi.gen(function* () {
+        const current = yield* CurrentForm;
+        return f(current.state);
+    });
+}
+const FieldMetaSchema = Schema.Struct({
+    dirty: Schema.Boolean,
+    touched: Schema.Boolean,
+});
+function optionalFields(fields, value) {
+    return Object.fromEntries(Object.keys(fields).map((key) => [key, Schema.optionalKey(value)]));
+}
+function emptyOptionalFields() {
+    return {};
+}
+/**
+ * Builds the serializable schema for a form's hydrated state.
+ *
+ * @remarks
+ * The hydration payload needs validation independent from runtime-only field codecs.
+ *
+ * Pure schema construction; the returned Schema acquires no Scope or subscription.
+ *
+ * @example
+ * ```ts
+ * import { StateSchema } from "@typed/ui/Form"
+ * import { Schema } from "effect"
+ *
+ * const codec = Schema.Struct({ email: Schema.String })
+ * const stateCodec = StateSchema(codec)
+ * ```
+ * @since 1.0.0
+ * @category Hydration schemas
+ */
+export function StateSchema(codec) {
+    return Schema.Struct({
+        values: codec,
+        defaultValues: codec,
+        errors: Schema.Struct(optionalFields(codec.fields, Schema.String)),
+        meta: Schema.Struct(optionalFields(codec.fields, FieldMetaSchema)),
+        submitting: Schema.Boolean,
+    });
+}
+/**
+ * Creates a Scope-owned hydrated form RefSubject from a Struct codec.
+ *
+ * @remarks
+ * One constructor establishes values, defaults, validation state, field codecs,
+ * and hydration identity consistently.
+ *
+ * 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.
+ *
+ * @example
+ * ```ts
+ * import { makeState } from "@typed/ui/Form"
+ * import { Effect, Schema } from "effect"
+ *
+ * const codec = Schema.Struct({ email: Schema.String })
+ * const program = Effect.gen(function* () {
+ *   const state = yield* makeState(codec, { id: "signup", values: { email: "" } })
+ *   return state
+ * })
+ * ```
+ * @since 1.0.0
+ * @category State construction
+ */
+export function makeState(codec, initial) {
+    const id = initial.id ?? `typed-form-${++nextFormId}`;
+    return Effect.map(RefSubject.hydrate(StateSchema(codec), {
+        values: initial.values,
+        defaultValues: initial.defaultValues ?? initial.values,
+        errors: initial.errors ?? emptyOptionalFields(),
+        meta: initial.meta ?? emptyOptionalFields(),
+        submitting: initial.submitting ?? false,
+    }), (state) => Object.assign(state, { codec, fields: codec.fields, id }));
+}
+function setFieldError(state, key, error) {
+    return RefSubject.update(state, (current) => {
+        const errors = { ...current.errors };
+        if (error === undefined)
+            delete errors[key];
+        else
+            errors[key] = error;
+        return { ...current, errors };
+    });
+}
+function fieldErrorId(state, name) {
+    return `${state.id}-${encodeURIComponent(name)}-error`;
+}
+function decodeField(state, name, codec, value) {
+    return Schema.decodeEffect(codec)(value).pipe(Effect.flatMap((decoded) => Effect.andThen(updateDecodedValue(state, name, decoded), () => setFieldError(state, name, undefined))), Effect.catch((error) => setFieldError(state, name, error.message)));
+}
+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,
+        "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": RefSubject.mapEffect(options.state, (state) => Schema.encodeUnknownEffect(codec)(state.values[options.name])),
+        oninput: EventHandler.make(Effect.fn((event) => decodeField(options.state, options.name, codec, Dom.currentTarget(event).value))),
+    });
+}
+function renderInput(options, host, type, defaultCodec) {
+    const codec = options.codec ?? defaultCodec;
+    return FxApi.suspend(() => Dom.renderHost()(options, host, inputProps(options, type, codec), "", (props) => html `<input ...${props} />`));
+}
+function makeInput(type, codec) {
+    return function (options, host) {
+        return renderInput(options, host, type, codec);
+    };
+}
+function makeSchemaBoundInput(formCodec, type) {
+    return function (options, host) {
+        return withCurrentForm()((state) => {
+            const inputOptions = { ...options, state };
+            const fieldCodec = formCodec.fields[options.name];
+            return renderInput(inputOptions, host, type, fieldCodec);
+        });
+    };
+}
+/**
+ * Binds a native `input[type=text]` to a string field.
+ *
+ * @remarks
+ * The control uses the browser's real input event and a Schema codec while
+ * keeping state independently testable.
+ *
+ * The control Scope owns DOM listeners/subscriptions; the supplied `FormState`
+ * may outlive the rendered input. A custom host must apply all merged props.
+ *
+ * @example
+ * ```ts
+ * import { TextInput, makeState } from "@typed/ui/Form"
+ * import { Effect, Schema } from "effect"
+ *
+ * const codec = Schema.Struct({ name: Schema.String })
+ * const input = Effect.gen(function* () {
+ *   const state = yield* makeState(codec, { values: { name: "" } })
+ *   return TextInput({ state, name: "name" })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const TextInput = makeInput("text", Schema.String);
+/**
+ * Binds a native search input to a string field.
+ * @remarks
+ * Preserves the platform's search-input semantics while sharing Typed validation.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const SearchInput = makeInput("search", Schema.String);
+/**
+ * Binds a native email input to a string field.
+ * @remarks
+ * Keeps browser email affordances and constraints available alongside Schema validation.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const EmailInput = makeInput("email", Schema.String);
+/**
+ * Binds a native URL input to a string field.
+ * @remarks
+ * Keeps browser URL affordances while the schema remains the decoded state contract.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const UrlInput = makeInput("url", Schema.String);
+/**
+ * Binds a native telephone input to a string field.
+ * @remarks
+ * Preserves platform telephone keyboards and autocomplete behavior.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const TelInput = makeInput("tel", Schema.String);
+/**
+ * Binds a native password input to a string field.
+ * @remarks
+ * Uses browser password handling instead of recreating sensitive-input behavior.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const PasswordInput = makeInput("password", Schema.String);
+/**
+ * Binds a native hidden input to a string field.
+ * @remarks
+ * Allows standards-based form serialization for non-visible values.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const HiddenInput = makeInput("hidden", Schema.String);
+/**
+ * Binds a native color input to a string field.
+ * @remarks
+ * Retains the browser's color picker while state receives its string value.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const ColorInput = makeInput("color", Schema.String);
+/**
+ * Binds a native time input to a string field.
+ * @remarks
+ * Preserves browser locale and time-entry behavior without inventing a picker.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const TimeInput = makeInput("time", Schema.String);
+/**
+ * Binds a native local date-time input to a string field.
+ * @remarks
+ * Keeps the platform's local date-time UI and its standard encoded value.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const DateTimeLocalInput = makeInput("datetime-local", Schema.String);
+/**
+ * Binds a native month input to a string field.
+ * @remarks
+ * Preserves the browser month picker and standardized string encoding.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const MonthInput = makeInput("month", Schema.String);
+/**
+ * Binds a native week input to a string field.
+ * @remarks
+ * Preserves platform week-entry behavior and standardized string encoding.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const WeekInput = makeInput("week", Schema.String);
+/**
+ * Binds a native number input to a finite number field.
+ * @remarks
+ * `FiniteFromString` makes the browser's string value an explicit typed decode.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const NumberInput = makeInput("number", Schema.FiniteFromString);
+/**
+ * Binds a native range input to a finite number field.
+ * @remarks
+ * Retains native slider interaction while exposing a decoded numeric value.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const RangeInput = makeInput("range", Schema.FiniteFromString);
+/**
+ * Binds a native date input to a `Date` field.
+ * @remarks
+ * `DateFromString` makes the native encoded value's conversion explicit and fallible.
+ * @since 1.0.0
+ * @category Native controls
+ */
+export const DateInput = makeInput("date", Schema.DateFromString);
+/**
+ * Converts native form data to a record, preserving repeated names as arrays.
+ * @example
+ * ```ts
+ * import { formDataToRecord } from "@typed/ui/Form"
+ *
+ * const data = new FormData()
+ * data.append("tag", "one")
+ * data.append("tag", "two")
+ * const record = formDataToRecord(data)
+ * ```
+ * @since 1.0.0
+ * @category Browser form data
+ */
+export function formDataToRecord(data) {
+    const result = {};
+    for (const [name, value] of data.entries()) {
+        const existing = result[name];
+        result[name] =
+            existing === undefined
+                ? value
+                : Array.isArray(existing)
+                    ? [...existing, value]
+                    : [existing, value];
+    }
+    return result;
+}
+/**
+ * Decodes native FormData through an Effect Schema codec.
+ * @remarks
+ * Browser serialization, repeated values, Files, and typed validation meet at
+ * one explicit fallible boundary.
+ * The returned Effect is lazy and owns no browser resource; it references File
+ * objects present in the supplied FormData.
+ * @example
+ * ```ts
+ * import { decodeFormData } from "@typed/ui/Form"
+ * import { Schema } from "effect"
+ *
+ * const decode = decodeFormData(Schema.Struct({ name: Schema.String }), new FormData())
+ * ```
+ * @since 1.0.0
+ * @category Browser form data
+ */
+export function decodeFormData(codec, data) {
+    return Schema.decodeEffect(codec)(formDataToRecord(data));
+}
+/**
+ * Checks retained decoded values against the form codec Type.
+ *
+ * @remarks
+ * 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
+ */
+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) => ({
+        ...current,
+        values,
+        errors: {},
+    })), values)), Effect.catch((error) => RefSubject.update(state, (current) => ({
+        ...current,
+        errors: formErrors(current.values, current.errors, error.message),
+    })).pipe(Effect.andThen(Effect.fail(error)))));
+}
+function formErrors(values, errors, error) {
+    const next = { ...errors };
+    for (const key of Object.keys(values))
+        Reflect.set(next, key, error);
+    return next;
+}
+/**
+ * Creates a named, Schema-decoded mask slot.
+ * @remarks
+ * Length and character constraints are expressed beside the codec that owns conversion.
+ * Pure constructor; the returned descriptor retains the codec but acquires no Scope.
+ * @example
+ * ```ts
+ * import { slot } from "@typed/ui/Form"
+ * import { Schema } from "effect"
+ *
+ * const areaCode = slot("area", Schema.String, { length: 3, charset: /[0-9]/ })
+ * ```
+ * @since 1.0.0
+ * @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
+ * 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"
+ * import { Schema } from "effect"
+ *
+ * const phone = mask("(", slot("area", Schema.String, { length: 3 }), ") ",
+ *   slot("number", Schema.String, { length: 7 }))
+ * ```
+ * @since 1.0.0
+ * @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)));
+    const codec = Schema.String.pipe(Schema.decodeTo(valueSchema, SchemaTransformation.transformEffect({
+        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* () {
+        const value = {};
+        let offset = 0;
+        for (let index = 0; index < parts.length; index++) {
+            const part = parts[index];
+            if (typeof part === "string") {
+                if (!display.startsWith(part, offset))
+                    return yield* invalidMask(display, options);
+                offset += part.length;
+                continue;
+            }
+            const nextLiteral = parts.slice(index + 1).find((next) => typeof next === "string");
+            const end = part.length === undefined
+                ? nextLiteral === undefined
+                    ? display.length
+                    : display.indexOf(nextLiteral, offset)
+                : offset + part.length;
+            if (end < offset)
+                return yield* invalidMask(display, options);
+            const encoded = display.slice(offset, end);
+            if (encoded.length === 0 ||
+                (part.length !== undefined && encoded.length !== part.length) ||
+                [...encoded].some((character) => !matchesCharset(part, character)))
+                return yield* invalidMask(display, options);
+            const decoded = yield* Schema.decodeEffect(part.codec)(encoded).pipe(Effect.mapError(() => new SchemaIssue.InvalidValue({ message: `Invalid ${part.name}` }, display, options)));
+            Reflect.set(value, part.name, decoded);
+            offset = end;
+        }
+        if (offset !== display.length || !isMaskValue(parts, value))
+            return yield* invalidMask(display, options);
+        return value;
+    });
+}
+function encodeMask(parts, value, options) {
+    return Effect.gen(function* () {
+        let display = "";
+        for (const part of parts) {
+            if (typeof part === "string") {
+                display += part;
+                continue;
+            }
+            const encoded = yield* Schema.encodeUnknownEffect(part.codec)(Reflect.get(value, part.name)).pipe(Effect.mapError(() => new SchemaIssue.InvalidValue({ message: `Invalid ${part.name}` }, value, options)));
+            if (encoded.length === 0 ||
+                (part.length !== undefined && encoded.length !== part.length) ||
+                [...encoded].some((character) => !matchesCharset(part, character)))
+                return yield* invalidMask(value, options);
+            display += encoded;
+        }
+        return display;
+    });
+}
+function isMaskValue(parts, value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        parts.every((part) => typeof part === "string" || Reflect.has(value, part.name)));
+}
+function matchesCharset(slot, character) {
+    if (slot.charset === undefined)
+        return true;
+    if (slot.charset instanceof RegExp) {
+        slot.charset.lastIndex = 0;
+        return slot.charset.test(character);
+    }
+    return slot.charset(character);
+}
+function invalidMask(input, options) {
+    return Effect.fail(new SchemaIssue.InvalidValue({ message: "Invalid mask" }, input, options));
+}
+/**
+ * Binds a native text input to a structured mask value.
+ * @remarks
+ * 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 Input codecs
+ */
+export function MaskedInput(options, host) {
+    const { mask, ...inputOptions } = options;
+    return renderInput(inputOptions, host, "text", mask);
+}
+function checkboxProps(options) {
+    const checked = RefSubject.map(options.state, (state) => state.values[options.name] === true);
+    return () => ({
+        type: "checkbox",
+        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),
+        "?checked": checked,
+        ".checked": checked,
+        onchange: EventHandler.make(Effect.fn((event) => decodeUpdatedField(options.state, options.name, Dom.currentTarget(event).checked))),
+    });
+}
+/**
+ * Binds a native checkbox to a boolean form field.
+ * @remarks
+ * Both the checked attribute and live property follow state, while the browser's
+ * real change event is decoded through the field codec.
+ * 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 Native controls
+ */
+export function Checkbox(options, host) {
+    return Dom.renderHost()(options, host, checkboxProps(options), "", (props) => html `<input ...${props} />`);
+}
+function selectProps(options) {
+    return () => ({
+        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": RefSubject.map(options.state, (state) => String(state.values[options.name])),
+        onchange: EventHandler.make(Effect.fn((event) => decodeUpdatedField(options.state, options.name, Dom.currentTarget(event).value))),
+    });
+}
+/**
+ * Binds a native select element to a string form field.
+ * @remarks
+ * Native keyboard, accessibility, option, and form semantics remain browser-owned.
+ * 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 Native controls
+ */
+export function Select(options, host) {
+    return Dom.renderHost()(options, host, selectProps(options), options.content, (props, content) => html `<select ...${props}>
+        ${content}
+      </select>`);
+}
+function labelProps(options) {
+    return () => ({ for: options.for });
+}
+/**
+ * Renders a native label with an explicit control relationship.
+ * @remarks
+ * The browser supplies click-to-focus and accessible-name behavior with no synthetic layer.
+ * The Scope owns label output/content; the referenced element remains separately owned.
+ * @since 1.0.0
+ * @category Field relationships
+ */
+export function Label(options, host) {
+    return Dom.renderHost()(options, host, labelProps(options), options.content, (props, content) => html `<label ...${props}>${content}</label>`);
+}
+function descriptionProps() {
+    return () => ({});
+}
+/**
+ * Renders visible explanatory content in a neutral div.
+ *
+ * @remarks
+ * 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 Field relationships
+ */
+export function Description(options, host) {
+    return Dom.renderHost()(options, host, descriptionProps(), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}
+function errorProps(options) {
+    return () => ({
+        id: fieldErrorId(options.state, options.name),
+        role: "alert",
+    });
+}
+/**
+ * Renders the named field message with a generated ID and alert role.
+ *
+ * @remarks
+ * 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 Field relationships
+ */
+export function Error(options, host) {
+    const content = RefSubject.map(options.state, (state) => state.errors[options.name] ?? "");
+    return Dom.renderHost()(options, host, errorProps(options), content, (props, value) => html `<div ...${props}>${value}</div>`);
+}
+function submitProps() {
+    return () => ({ type: "submit" });
+}
+/**
+ * Renders a native `type=submit` button.
+ * @remarks
+ * Keyboard activation, form association, and accessibility stay browser-standard.
+ * The Scope owns the button/content; the surrounding Form owns submission sequencing.
+ * @since 1.0.0
+ * @category Form actions
+ */
+export function Submit(options, host) {
+    return Dom.renderHost()(options, host, submitProps(), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
+}
+function resetProps(options) {
+    return () => ({
+        type: "reset",
+        onclick: EventHandler.preventDefault(EventHandler.fromEffectOrEventHandler(reset(options.state))),
+    });
+}
+/**
+ * Renders a native reset button that restores Typed form defaults.
+ * @remarks
+ * It prevents the browser's independent control mutation and resets the single
+ * RefSubject source of truth, clearing errors, metadata, and submitting state.
+ * The Scope owns the click handler/content. The supplied form state remains independently owned.
+ * @since 1.0.0
+ * @category Form actions
+ */
+export function Reset(options, host) {
+    return Dom.renderHost()(options, host, resetProps(options), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
+}
+function groupProps(options) {
+    return () => ({ role: "group", "aria-label": options.label });
+}
+/**
+ * Renders an ARIA group with an optional accessible name.
+ * @remarks
+ * Related controls can expose their relationship without a framework-specific wrapper.
+ * The Scope owns host/content; child controls retain their own DOM/state contracts.
+ * @since 1.0.0
+ * @category Field relationships
+ */
+export function Group(options, host) {
+    return Dom.renderHost()(options, host, groupProps(options), options.content, (props, content) => html `<div ...${props}>${content}</div>`);
+}
+function pushProps(options) {
+    return () => ({
+        type: "button",
+        onclick: pushValue(options.state, options.name, options.value),
+    });
+}
+/**
+ * Renders a button that appends one item to an array field.
+ * @remarks
+ * Array mutation is immutable, typed, and marks the field dirty/touched.
+ * The Scope owns the button handler/content; state may outlive the button.
+ * @since 1.0.0
+ * @category Form actions
+ */
+export function Push(options, host) {
+    return Dom.renderHost()(options, host, pushProps(options), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
+}
+function removeProps(options) {
+    return () => ({
+        type: "button",
+        onclick: removeValue(options.state, options.name, options.index),
+    });
+}
+/**
+ * Renders a button that removes one array item by index.
+ * @remarks
+ * Array mutation is immutable, typed, and marks the field dirty/touched.
+ * The Scope owns the button handler/content; state may outlive the button.
+ * @since 1.0.0
+ * @category Form actions
+ */
+export function Remove(options, host) {
+    return Dom.renderHost()(options, host, removeProps(options), options.content, (props, content) => html `<button ...${props}>${content}</button>`);
+}
+/**
+ * Assigns one decoded field value and updates dirty/touched metadata.
+ *
+ * @remarks
+ * 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 transitions
+ */
+export function setValue(state, key, value) {
+    return updateDecodedValue(state, key, value);
+}
+function updateDecodedValue(state, key, value) {
+    return RefSubject.update(state, (current) => ({
+        ...current,
+        values: updateRecord(current.values, key, value),
+        meta: {
+            ...current.meta,
+            [key]: { dirty: current.defaultValues[key] !== value, touched: true },
+        },
+    }));
+}
+function updateRecord(values, key, value) {
+    const updated = { ...values };
+    Reflect.set(updated, key, value);
+    return updated;
+}
+/**
+ * Restores default values and clears errors, metadata, and submitting.
+ *
+ * @remarks
+ * 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 transitions
+ */
+export function reset(state) {
+    return RefSubject.update(state, (current) => ({
+        ...current,
+        values: current.defaultValues,
+        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
+ * The immutable state transition is usable in tests, commands, or any renderer.
+ * The returned Effect performs one RefSubject update when run.
+ * @since 1.0.0
+ * @category State transitions
+ */
+export function pushValue(state, name, value) {
+    return RefSubject.update(state, (current) => {
+        const previous = Reflect.get(current.values, name);
+        const values = Array.isArray(previous) ? [...previous, value] : [value];
+        return {
+            ...current,
+            values: updateRecord(current.values, name, values),
+            meta: { ...current.meta, [name]: { dirty: true, touched: true } },
+        };
+    });
+}
+/**
+ * Removes one item by index from an array field and marks it dirty and touched.
+ * @remarks
+ * The transition is explicit and renderer-independent; an out-of-range index leaves values unchanged.
+ * The returned Effect performs one RefSubject update when run.
+ * @since 1.0.0
+ * @category State transitions
+ */
+export function removeValue(state, name, index) {
+    return RefSubject.update(state, (current) => {
+        const previous = Reflect.get(current.values, name);
+        const values = Array.isArray(previous)
+            ? previous.filter((_, currentIndex) => currentIndex !== index)
+            : [];
+        return {
+            ...current,
+            values: updateRecord(current.values, name, values),
+            meta: { ...current.meta, [name]: { dirty: true, touched: true } },
+        };
+    });
+}
+function formProps(options) {
+    const setSubmitting = Effect.fn((submitting) => RefSubject.update(options.state, (current) => ({ ...current, submitting })));
+    return () => ({
+        ref: options.state,
+        onsubmit: EventHandler.make(Effect.fn((event) => Effect.andThen(setSubmitting(true), Effect.matchEffect(validate(options.state), {
+            onFailure: Effect.fn(() => Effect.void),
+            onSuccess: Effect.fn((values) => {
+                const result = options.onValidSubmit?.(values, event);
+                return Effect.isEffect(result) ? result : Effect.void;
+            }),
+        })).pipe(Effect.ensuring(setSubmitting(false).pipe(Effect.catch(Effect.fn(() => Effect.void)))))), { preventDefault: true }),
+        onreset: EventHandler.preventDefault(EventHandler.fromEffectOrEventHandler(reset(options.state))),
+    });
+}
+/**
+ * Renders a native form and provides its state to bound descendants.
+ *
+ * @remarks
+ * 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"
+ * import { Effect, Schema } from "effect"
+ * import { html } from "@typed/template"
+ *
+ * const codec = Schema.Struct({ email: Schema.String })
+ * const view = Effect.gen(function* () {
+ *   const state = yield* makeState(codec, { id: "signup", values: { email: "" } })
+ *   return Form({
+ *     state,
+ *     content: html`${TextInput({ state, name: "email" })}${Submit({ content: "Join" })}`,
+ *     onValidSubmit: (values) => Effect.log(`Submitting ${values.email}`)
+ *   })
+ * })
+ * ```
+ * @since 1.0.0
+ * @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>`);
+    return FxApi.provideService(rendered, CurrentForm, {
+        state: options.state,
+    });
+}
+/**
+ * Binds a native form component family to one Struct codec.
+ *
+ * @remarks
+ * 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 { Schema } from "effect";
+ * import { html } from "@typed/template";
+ * import { RefSubject } from "@typed/fx";
+ * import { component } from "@typed/template";
+ * import * as Form from "@typed/ui/Form";
+ *
+ * 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: [
+ *       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 Schema-bound components
+ */
+export function make(codec) {
+    const state = (values, options = {}) => makeState(codec, { ...options, values });
+    const Root = (options, host) => {
+        const { form, ...rootOptions } = options;
+        return Form({ ...rootOptions, state: form }, host);
+    };
+    const BoundCheckbox = (options, host) => withCurrentForm()((state) => {
+        const inputOptions = { ...options, state };
+        return Checkbox(inputOptions, host);
+    });
+    const BoundSelect = (options, host) => withCurrentForm()((state) => {
+        const inputOptions = { ...options, state };
+        return Select(inputOptions, host);
+    });
+    const BoundError = (options, host) => withCurrentForm()((state) => {
+        const inputOptions = { ...options, state };
+        return Error(inputOptions, host);
+    });
+    const BoundReset = (options, host) => withCurrentForm()((state) => {
+        const inputOptions = { ...options, state };
+        return Reset(inputOptions, host);
+    });
+    const BoundPush = (options, host) => withCurrentForm()((state) => {
+        const inputOptions = { ...options, state };
+        return Push(inputOptions, host);
+    });
+    const BoundRemove = (options, host) => withCurrentForm()((state) => {
+        const inputOptions = { ...options, state };
+        return Remove(inputOptions, host);
+    });
+    return {
+        codec,
+        state,
+        Root,
+        TextInput: makeSchemaBoundInput(codec, "text"),
+        SearchInput: makeSchemaBoundInput(codec, "search"),
+        EmailInput: makeSchemaBoundInput(codec, "email"),
+        UrlInput: makeSchemaBoundInput(codec, "url"),
+        TelInput: makeSchemaBoundInput(codec, "tel"),
+        PasswordInput: makeSchemaBoundInput(codec, "password"),
+        HiddenInput: makeSchemaBoundInput(codec, "hidden"),
+        ColorInput: makeSchemaBoundInput(codec, "color"),
+        TimeInput: makeSchemaBoundInput(codec, "time"),
+        DateTimeLocalInput: makeSchemaBoundInput(codec, "datetime-local"),
+        MonthInput: makeSchemaBoundInput(codec, "month"),
+        WeekInput: makeSchemaBoundInput(codec, "week"),
+        NumberInput: makeSchemaBoundInput(codec, "number"),
+        RangeInput: makeSchemaBoundInput(codec, "range"),
+        DateInput: makeSchemaBoundInput(codec, "date"),
+        MaskedInput: makeSchemaBoundInput(codec, "text"),
+        Checkbox: BoundCheckbox,
+        Select: BoundSelect,
+        Error: BoundError,
+        Reset: BoundReset,
+        Push: BoundPush,
+        Remove: BoundRemove,
+        Label,
+        Description,
+        Submit,
+        Group,
+    };
+}