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

package/dist/Form.js

@@ -0,0 +1,987 @@
+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 { EventHandler, html, } from "@typed/template";
+import * as Dom from "./Dom.js";
+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
+ */
+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
+ * ## 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
+ * ```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 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
+ * ## 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.
+ *
+ * @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 constructors
+ */
+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) {
+    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 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
+ * ## 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.
+ *
+ * @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 components
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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
+ */
+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.
+ * @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 conversions
+ */
+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
+ * ## 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
+ * ```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 conversions
+ */
+export function decodeFormData(codec, data) {
+    return Schema.decodeEffect(codec)(formDataToRecord(data));
+}
+/**
+ * Validates current form values and synchronizes decoded values or field errors.
+ * @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`.
+ * @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
+ * ## 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
+ * 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 constructors
+ */
+export function slot(name, codec, options = {}) {
+    return { _tag: "MaskSlot", name, codec, ...options };
+}
+/**
+ * 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.
+ * @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 schemas
+ */
+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({
+        decode: (display, options) => decodeMask(parts, display, options),
+        encode: (value, options) => encodeMask(parts, value, options),
+    })));
+}
+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
+ * ## 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.
+ * @since 1.0.0
+ * @category components
+ */
+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
+ * ## 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
+ */
+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
+ * ## 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
+ */
+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
+ * ## 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
+ */
+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 form description content in a neutral native div by default.
+ * @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.
+ * @since 1.0.0
+ * @category components
+ */
+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 current field error as a native ARIA alert region.
+ * @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.
+ * @since 1.0.0
+ * @category components
+ */
+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
+ * ## 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
+ */
+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
+ * ## 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
+ */
+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
+ * ## 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
+ */
+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
+ * ## 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
+ */
+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
+ * ## 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
+ */
+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.
+ * @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.
+ * @since 1.0.0
+ * @category state
+ */
+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, interaction metadata, and submission state.
+ * @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`.
+ * @since 1.0.0
+ * @category state
+ */
+export function reset(state) {
+    return RefSubject.update(state, (current) => ({
+        ...current,
+        values: current.defaultValues,
+        errors: {},
+        meta: {},
+        submitting: false,
+    }));
+}
+/**
+ * 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
+ */
+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
+ * ## 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
+ */
+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 schema-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.
+ * @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 components
+ */
+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,
+    });
+}
+/**
+ * Creates a schema-bound form component family from 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.
+ * @example
+ * ```ts
+ * import { make } from "@typed/ui/Form"
+ * import { Effect, Schema } from "effect"
+ * import { html } from "@typed/template"
+ *
+ * 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({
+ *     form,
+ *     content: html`${Signup.EmailInput({ name: "email" })}${Signup.Checkbox({ name: "accepted" })}`
+ *   })
+ * })
+ * ```
+ * @since 1.0.0
+ * @category constructors
+ */
+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,
+    };
+}