@orkestrel/form 0.0.1

package/dist/src/core/index.d.ts

@@ -0,0 +1,1160 @@
+import { EmitterErrorHandler } from '@orkestrel/emitter';
+import { EmitterHooks } from '@orkestrel/emitter';
+import { EmitterInterface } from '@orkestrel/emitter';
+import { JSONRecord } from '@orkestrel/contract';
+import { Result } from '@orkestrel/contract';
+
+/** One or more ASCII letters or digits. */
+export declare const ALPHANUMERIC_PATTERN: Readonly<RegExp>;
+
+/**
+ * Check whether a named rule applies to one field control.
+ *
+ * @remarks
+ * The runtime control-membership check keeps this boundary total for JavaScript callers that
+ * bypass the declared {@link FieldControl} contract.
+ *
+ * @param control - The field control to inspect.
+ * @param rule - The named rule to inspect.
+ * @returns Whether the control evaluates that rule.
+ */
+export declare function appliesRule(control: FieldControl, rule: FieldRuleName): boolean;
+
+/**
+ * Audit a structurally valid schema for domain invariants.
+ *
+ * @param schema - The form schema to audit.
+ * @returns Human-readable invariant violations, or an empty list when the schema is sound.
+ */
+export declare function auditSchema(schema: FormSchema): readonly string[];
+
+/**
+ * Any number of choices out of a list, holding the checked values.
+ *
+ * @remarks
+ * A field offering one box that means yes or no is a {@link ConfirmField}, not a one-choice
+ * checkbox.
+ */
+export declare interface CheckboxField extends FieldBase {
+    readonly control: 'checkbox';
+    readonly choices: readonly FieldChoice[];
+    readonly default?: readonly string[];
+}
+
+/** The maximum number of choices one `select` or `checkbox` field may offer. */
+export declare const CHOICE_LIMIT = 1024;
+
+/**
+ * Clone a field's choices into an owned frozen snapshot.
+ *
+ * @param choices - The choices to own.
+ * @returns A frozen list of frozen choice records.
+ */
+export declare function cloneChoices(choices: readonly FieldChoice[]): readonly FieldChoice[];
+
+/**
+ * Clone one form field into an owned frozen snapshot.
+ *
+ * @param field - The field to own.
+ * @returns A frozen field with every nested collection owned.
+ * @throws A {@link FormError} coded `SCHEMA` when accessor-bearing metadata cannot be owned.
+ */
+export declare function cloneFormField(field: FormField): FormField;
+
+/**
+ * Clone a form schema into an owned frozen snapshot.
+ *
+ * @param schema - The schema to own.
+ * @returns A frozen schema with every nested record and list owned.
+ */
+export declare function cloneFormSchema(schema: FormSchema): FormSchema;
+
+/**
+ * Clone one form value into an owned frozen snapshot.
+ *
+ * @param value - The field value to own.
+ * @returns The scalar unchanged, or a frozen copy of the list.
+ */
+export declare function cloneValue(value: readonly string[]): readonly string[];
+
+export declare function cloneValue(value: FieldValue): FieldValue;
+
+/** A six-digit hexadecimal color string. */
+export declare const COLOR_PATTERN: Readonly<RegExp>;
+
+/** A color, held as the control's own string. */
+export declare interface ColorField extends FieldBase {
+    readonly control: 'color';
+    readonly default?: string;
+}
+
+/**
+ * Compute the values explicitly seeded by a schema.
+ *
+ * @param schema - The schema whose defaults to collect.
+ * @returns A value record containing only fields with defaults.
+ */
+export declare function computeDefaults(schema: FormSchema): FormValues;
+
+/** A single on/off box, holding a boolean. */
+export declare interface ConfirmField extends FieldBase {
+    readonly control: 'confirm';
+    readonly default?: boolean;
+}
+
+/**
+ * Open a form against a schema.
+ *
+ * @param schema - The form to ask. It is copied, and the copy is what the form asks.
+ * @param options - The form's settings.
+ * @returns A form open for answers.
+ * @remarks
+ * Prefer this at a call site that only needs {@link FormInterface}. `new Form(...)` is the same
+ * construction and is what a class holding a form as its own field reaches for.
+ * @throws A {@link FormError} coded `SCHEMA` when the schema is malformed, `FIELD` when
+ *   `options.values` names a field the schema does not declare, and `CONTROL` when a seeded value
+ *   is one its field's control cannot hold.
+ * @example
+ * ```ts
+ * const form = createForm({
+ * 	label: 'Sign up',
+ * 	fields: [
+ * 		{ control: 'text', name: 'email', label: 'Email', rule: { required: true, email: true } },
+ * 		{ control: 'confirm', name: 'terms', label: 'I accept the terms', rule: { required: true } },
+ * 	],
+ * })
+ *
+ * form.fill({ email: 'ada@example.com', terms: true })
+ * form.submit() // { success: true, value: { email: 'ada@example.com', terms: true } }
+ * ```
+ */
+export declare function createForm(schema: FormSchema, options?: FormOptions): FormInterface;
+
+/** An ISO calendar date string in `YYYY-MM-DD` form. */
+export declare const DATE_PATTERN: Readonly<RegExp>;
+
+/** A calendar date, held as the control's own string. */
+export declare interface DateField extends FieldBase {
+    readonly control: 'date';
+    readonly default?: string;
+}
+
+/** An ISO local date and time string with optional seconds. */
+export declare const DATETIME_PATTERN: Readonly<RegExp>;
+
+/** A date and a time of day together, with no zone, held as the control's own string. */
+export declare interface DatetimeField extends FieldBase {
+    readonly control: 'datetime';
+    readonly default?: string;
+}
+
+/** Text over many lines. */
+export declare interface EditorField extends FieldBase {
+    readonly control: 'editor';
+    readonly default?: string;
+    readonly placeholder?: string;
+}
+
+/** A practical whole-address email shape. */
+export declare const EMAIL_PATTERN: Readonly<RegExp>;
+
+/**
+ * Evaluate one field rule against its current value.
+ *
+ * @param field - The field and rule to evaluate.
+ * @param value - The current value, or absence.
+ * @param values - Every value available to a custom rule.
+ * @param messages - Optional rule-specific message replacements.
+ * @returns Every failure in rule order.
+ */
+export declare function evaluateField(field: FormField, value: FieldValue | undefined, values: FormValues, messages?: Readonly<Partial<Record<FieldRuleName, string>>>): readonly FieldError[];
+
+/**
+ * Evaluate every active field in schema order.
+ *
+ * @param schema - The form schema to evaluate.
+ * @param values - The values keyed by field name.
+ * @param options - Optional message replacements and the effective disabled field set.
+ * @returns Every field failure in schema and rule order.
+ */
+export declare function evaluateForm(schema: FormSchema, values: FormValues, options?: EvaluationOptions): readonly FieldError[];
+
+/**
+ * How to check a schema against a set of answers.
+ *
+ * @param options - The evaluation's settings.
+ * @remarks
+ * `messages` replaces the default message of a rule, keyed by {@link FieldRuleName}.
+ *
+ * `disabled` names the fields to leave out of the check. It replaces the schema's own
+ * {@link FieldBase.disabled} declarations rather than adding to them, because a live form's
+ * answer to which fields are in play is {@link FormInterface.disabled}, and a form always
+ * supplies that set.
+ *
+ * @example
+ * ```ts
+ * const options: EvaluationOptions = {
+ * 	messages: { required: 'This one is needed' },
+ * 	disabled: new Set(['nickname']),
+ * }
+ * ```
+ */
+export declare interface EvaluationOptions {
+    readonly messages?: Readonly<Partial<Record<FieldRuleName, string>>>;
+    readonly disabled?: ReadonlySet<string>;
+}
+
+/**
+ * Extract the names whose answers differ between two form value records.
+ *
+ * @remarks
+ * Presence is compared in both directions before present values are compared through
+ * {@link matchesValue}. The returned set is a new snapshot, exposed as readonly because later
+ * changes to either input never alter its membership.
+ *
+ * @param current - The values held now.
+ * @param opened - The values held when the form opened.
+ * @returns A readonly snapshot of changed field names.
+ */
+export declare function extractChanges(current: FormValues, opened: FormValues): ReadonlySet<string>;
+
+/**
+ * Select referenced groups in first-reference field order.
+ *
+ * @param schema - The schema whose group references to resolve.
+ * @returns The referenced schema groups without duplicates.
+ */
+export declare function extractGroups(schema: FormSchema): readonly FormGroup[];
+
+/** Every field control, in the order declared by the public contract. */
+export declare const FIELD_CONTROLS: readonly FieldControl[];
+
+/** The maximum number of fields one schema may declare. */
+export declare const FIELD_LIMIT = 512;
+
+/**
+ * What every field carries, whatever its control.
+ *
+ * @remarks
+ * `name` keys the field in {@link FormValues} and `group` names a {@link FormGroup}.
+ *
+ * The three visibility switches differ in what they remove. `hidden` keeps the field out of
+ * the rendered form, `locked` renders it unwritable, and both are still validated and still
+ * submitted. `disabled` takes the field out of the form entirely: it is neither validated nor
+ * submitted. It is the field's declared, opening state; {@link FormInterface.disabled} is the
+ * current fact, because a live form can move a field either way.
+ *
+ * `meta` is a bounded JSON carrier for whatever the schema declines to model. Evaluation never
+ * reads it, no rule sees it, and it round-trips verbatim through serialization. This package
+ * defines no key in it, so every key belongs to the host.
+ */
+export declare interface FieldBase {
+    readonly name: string;
+    readonly label?: string;
+    readonly help?: string;
+    readonly group?: string;
+    readonly hidden?: boolean;
+    readonly disabled?: boolean;
+    readonly locked?: boolean;
+    readonly rule?: FieldRule;
+    readonly meta?: JSONRecord;
+}
+
+/**
+ * One option a `select` or `checkbox` field offers.
+ *
+ * @remarks
+ * `value` is what the form stores and `label` is what the person reads. `help` explains the
+ * option, and `disabled` shows it while refusing its value at every input door, including
+ * seeded values.
+ */
+export declare interface FieldChoice {
+    readonly value: string;
+    readonly label: string;
+    readonly help?: string;
+    readonly disabled?: boolean;
+}
+
+/**
+ * The control a field presents to the person answering it.
+ *
+ * @remarks
+ * The control is the discriminant of every {@link FormField} variant, so choosing it fixes
+ * which options that field accepts and which {@link FieldValue} it holds.
+ *
+ * Three members need saying out loud. `confirm` is a single on/off box holding a boolean, so
+ * a lone browser checkbox is a `confirm`. `checkbox` is the multi-choice group holding the
+ * checked values as a list, never a single box. `datetime` is the browser's `datetime-local`:
+ * a wall-clock date and time carrying no zone.
+ *
+ * @example
+ * ```ts
+ * const control: FieldControl = 'select'
+ * ```
+ */
+export declare type FieldControl = 'text' | 'editor' | 'password' | 'number' | 'date' | 'time' | 'datetime' | 'color' | 'confirm' | 'select' | 'checkbox' | 'file';
+
+/**
+ * One failed check against one field.
+ *
+ * @remarks
+ * `rule` names the constraint that failed. It is absent when the message came from a
+ * {@link FieldRule.custom} validator or from {@link FormInterface.invalidate}, because
+ * neither failure belongs to a named rule.
+ */
+export declare interface FieldError {
+    readonly field: string;
+    readonly message: string;
+    readonly rule?: FieldRuleName;
+}
+
+/**
+ * The constraints one field's value must satisfy.
+ *
+ * @remarks
+ * `minimum` and `maximum` measure whatever the control makes countable: characters for
+ * `text`, `editor`, and `password`; magnitude for `number`; chronology for `date`, `time`,
+ * and `datetime`, whose operand is a string written in that control's own format; and the
+ * number of selections for `checkbox` and `file`.
+ *
+ * `step` is the interval a numeric value must land on. `pattern` is regular-expression
+ * source. `email`, `url`, `integer`, and `alphanumeric` each assert one shape over the whole
+ * value. `custom` runs last and is the only rule that sees the rest of the form.
+ *
+ * @example
+ * ```ts
+ * const rule: FieldRule = { required: true, minimum: 8, pattern: '\\d' }
+ * ```
+ */
+export declare interface FieldRule {
+    readonly required?: boolean;
+    readonly minimum?: number | string;
+    readonly maximum?: number | string;
+    readonly step?: number;
+    readonly pattern?: string;
+    readonly email?: boolean;
+    readonly url?: boolean;
+    readonly integer?: boolean;
+    readonly alphanumeric?: boolean;
+    readonly custom?: FieldValidator;
+}
+
+/**
+ * Every rule that reports its failure by name.
+ *
+ * @remarks
+ * `custom` is excluded because it supplies its own message, so nothing keyed by a rule name
+ * would ever be read for it. {@link FormOptions.messages} is keyed by this name.
+ */
+export declare type FieldRuleName = Exclude<keyof FieldRule, 'custom'>;
+
+/**
+ * Check one value against the whole form.
+ *
+ * @remarks
+ * It runs after every named rule, and it runs on an absent value as well as a present one. That
+ * is what makes a rule such as "required once the sibling says yes" expressible, and it means an
+ * unanswered field can carry both a `required` message and this validator's own.
+ *
+ * @param value - The value the field currently holds, or `undefined` when nobody has answered it.
+ * @param values - Every answer the form holds, so a rule can read its siblings.
+ * @returns `true` when the value passes, or the message explaining why it failed.
+ * @throws The validator's own thrown value escapes the mutation call unchanged. When a form
+ *   mutation has already changed state, the throw leaves those changes beside the error list
+ *   from before that mutation. An invalidation can therefore be recorded without appearing in
+ *   `errors`, and a clear can reset state without emitting `clear`. Form-owned refusals use
+ *   {@link FormError} instead.
+ * @example
+ * ```ts
+ * const matches: FieldValidator = (value, values) =>
+ * 	value === values.password ? true : 'Both passwords must match'
+ * ```
+ */
+export declare type FieldValidator = (value: FieldValue | undefined, values: FormValues) => true | string;
+
+/**
+ * Every value a field can hold.
+ *
+ * @remarks
+ * The variant follows the control: text-like controls hold a `string`, `number` holds a
+ * `number`, `confirm` holds a `boolean`, and `checkbox` holds its checked values as a
+ * `readonly string[]`.
+ */
+export declare type FieldValue = string | number | boolean | readonly string[];
+
+/**
+ * One or more files.
+ *
+ * @remarks
+ * `accept` lists the media types and extensions the control offers, in the form the host
+ * expects.
+ */
+export declare interface FileField extends FieldBase {
+    readonly control: 'file';
+    readonly accept?: readonly string[];
+    readonly multiple?: boolean;
+}
+
+/**
+ * A form: a schema, the answers given against it, and the errors they carry.
+ *
+ * @remarks
+ * The form owns its schema, so a later edit to the schema the caller passed changes nothing here.
+ *
+ * `errors` is recomputed at construction and after every mutation whose evaluation completes,
+ * and the `validate` event fires exactly when that list's content changes. A throwing custom
+ * validator escapes after any preceding state changes and leaves the prior error list in place.
+ * There is no separate check.
+ *
+ * `valid` and `dirty` are derived on read from the error list and answers respectively, never
+ * stored.
+ *
+ * @example
+ * ```ts
+ * const form = new Form({
+ * 	fields: [{ control: 'text', name: 'email', rule: { required: true, email: true } }],
+ * })
+ *
+ * form.fill('email', 'ada@example.com')
+ * const result = form.submit()
+ * if (result.success) await form.answer
+ * ```
+ */
+export declare class Form implements FormInterface {
+    #private;
+    /**
+     * Open a form against a schema.
+     *
+     * @param schema - The form to ask. It is copied, and the copy is what the form asks.
+     * @param options - The form's settings.
+     * @throws A {@link FormError} coded `SCHEMA` when the schema is malformed, `FIELD` when
+     *   `options.values` names a field the schema does not declare, and `CONTROL` when a seeded
+     *   value is one its field's control cannot hold.
+     */
+    constructor(schema: FormSchema, options?: FormOptions);
+    /** The form's event emitter. */
+    get emitter(): EmitterInterface<FormEventMap>;
+    /** The schema this form asks, owned and frozen. */
+    get schema(): FormSchema;
+    /** The answers held right now. */
+    get values(): FormValues;
+    /** The answers the form opened with. */
+    get baseline(): FormValues;
+    /** Every error the last completed evaluation produced. */
+    get errors(): readonly FieldError[];
+    /** The names of the fields somebody has visited. */
+    get touched(): ReadonlySet<string>;
+    /** The names of the fields currently out of the form. */
+    get disabled(): ReadonlySet<string>;
+    /** Where the form sits in its life. */
+    get status(): FormStatus;
+    /** Whether the last completed evaluation found no error. */
+    get valid(): boolean;
+    /** Whether any answer has moved since the form opened. */
+    get dirty(): boolean;
+    /**
+     * The answers, once the form settles.
+     *
+     * @remarks
+     * It resolves with the submitted values on the first valid submit, and rejects with a
+     * {@link FormError} coded `ABANDONED` when teardown abandons the form before it settles.
+     */
+    get answer(): Promise<FormValues>;
+    /**
+     * Find one field by name.
+     *
+     * @param name - The field's name.
+     * @returns The field, or `undefined` when the schema declares no such name.
+     */
+    field(name: string): FormField | undefined;
+    /**
+     * Answer several fields at once.
+     *
+     * @param values - The answers to write, each keyed by its field name.
+     */
+    fill(values: FormValues): void;
+    /**
+     * Answer one field.
+     *
+     * @param name - The field's name.
+     * @param value - The answer to write, or `undefined` to clear it.
+     */
+    fill(name: string, value: FieldValue | undefined): void;
+    /**
+     * Record that somebody has visited a field.
+     *
+     * @param name - The field's name.
+     * @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
+     *   `FIELD` when the schema declares no such name.
+     */
+    touch(name: string): void;
+    /**
+     * Fail a field from outside, for what the rules cannot see.
+     *
+     * @param name - The field's name.
+     * @param message - What to tell the person.
+     * @remarks
+     * One field holds one external failure: a second call replaces the first. The failure lasts
+     * until that field is filled again or the form is cleared.
+     * @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended, and
+     *   `FIELD` when the schema declares no such name.
+     */
+    invalidate(name: string, message: string): void;
+    /** Take every field out of the form. */
+    disable(): void;
+    /**
+     * Take one field out of the form.
+     *
+     * @param name - The field's name.
+     */
+    disable(name: string): void;
+    /**
+     * Take several fields out of the form.
+     *
+     * @param names - The field names.
+     */
+    disable(names: readonly string[]): void;
+    /** Put every field back into the form. */
+    enable(): void;
+    /**
+     * Put one field back into the form.
+     *
+     * @param name - The field's name.
+     */
+    enable(name: string): void;
+    /**
+     * Put several fields back into the form.
+     *
+     * @param names - The field names.
+     */
+    enable(names: readonly string[]): void;
+    /**
+     * Check every answer and settle the form when they all pass.
+     *
+     * @returns The values on success, or every error that stopped them.
+     * @remarks
+     * A failed submit marks every enabled field touched, so a renderer can show the errors the
+     * person has not reached yet. A disabled field is neither checked nor submitted. When a changed
+     * evaluation notifies listeners and a listener writes, submit evaluates once more after those
+     * listeners return and decides from that state. Listener work that settled the form wins: that
+     * settlement is what this call returns, with no further evaluation, resolution, or `submit`
+     * emission. An evaluation that already failed refuses with the list it checked, even when a
+     * listener repaired or disabled the field that failed. An evaluation that passed decides from the
+     * state the drain left, which is why one further evaluation bounds the drain rather than a
+     * fixpoint loop.
+     * @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended.
+     */
+    submit(): FormResult;
+    /**
+     * Return every answer to the ones the form opened with: the schema's defaults, overlaid with
+     * any seeded `values`. Reset the runtime disabled state to the schema's declarations.
+     *
+     * @throws A {@link FormError} coded `SETTLED` or `ABANDONED` when the form has ended.
+     */
+    clear(): void;
+    /**
+     * Tear the form down, abandoning it when it has not settled.
+     *
+     * @remarks
+     * Destroying twice does nothing the second time. A settled form keeps its `settled` status and
+     * announces nothing. A request from inside a listener defers teardown until the outermost
+     * mutation batch closes, so an in-flight settlement can win and leave the form `settled` rather
+     * than `abandoned`. Every getter keeps answering afterwards; every write is refused.
+     */
+    destroy(): void;
+}
+
+/** Every form lifecycle status. */
+export declare const FORM_STATUSES: readonly FormStatus[];
+
+/**
+ * Resolve and interpolate one rule message.
+ *
+ * @param rule - The rule whose message to resolve.
+ * @param limit - The optional operand substituted for `{limit}`.
+ * @param messages - Optional rule-specific message replacements.
+ * @returns The resolved failure text.
+ */
+export declare function formatMessage(rule: FieldRuleName, limit?: number | string, messages?: Readonly<Partial<Record<FieldRuleName, string>>>): string;
+
+/** An error raised by the form domain. */
+export declare class FormError extends Error {
+    /** The machine-readable reason for this failure. */
+    readonly code: FormErrorCode;
+    /** Structured values that locate or explain this failure. */
+    readonly context?: JSONRecord;
+    /**
+     * Create a form error.
+     *
+     * @param code - The machine-readable reason.
+     * @param message - The human-readable failure text.
+     * @param context - Optional structured failure details.
+     */
+    constructor(code: FormErrorCode, message: string, context?: JSONRecord);
+}
+
+/**
+ * The machine-readable code a form error carries.
+ *
+ * @remarks
+ * `SCHEMA` rejects a malformed schema. `FIELD` names a field the schema does not declare.
+ * `CONTROL` reports a value the field's control cannot hold. `SETTLED` and `ABANDONED`
+ * refuse a write to a form that has already ended.
+ */
+export declare type FormErrorCode = 'SCHEMA' | 'FIELD' | 'CONTROL' | 'SETTLED' | 'ABANDONED';
+
+/**
+ * Everything a form announces.
+ *
+ * @remarks
+ * `fill` carries the field that changed and its new value, where `undefined` is the value
+ * being cleared. `validate` carries the errors a check produced, empty when it found none.
+ * `disable` and `enable` each carry one field, and fire once per field whose state actually
+ * moved, in the order the schema declares them. `submit` fires only on a submit that passed.
+ * `clear` and `abandon` are signals.
+ */
+export declare type FormEventMap = {
+    readonly fill: readonly [name: string, value: FieldValue | undefined];
+    readonly validate: readonly [errors: readonly FieldError[]];
+    readonly disable: readonly [name: string];
+    readonly enable: readonly [name: string];
+    readonly submit: readonly [values: FormValues];
+    readonly clear: readonly [];
+    readonly abandon: readonly [];
+};
+
+/**
+ * Any field a schema can declare.
+ *
+ * @remarks
+ * The union discriminates on `control`, so narrowing on that member reaches each variant's
+ * own options.
+ *
+ * @example
+ * ```ts
+ * function choices(field: FormField): readonly FieldChoice[] {
+ * 	return field.control === 'select' || field.control === 'checkbox' ? field.choices : []
+ * }
+ * ```
+ */
+export declare type FormField = TextField | EditorField | PasswordField | NumberField | DateField | TimeField | DatetimeField | ColorField | ConfirmField | SelectField | CheckboxField | FileField;
+
+/**
+ * A named section of a form.
+ *
+ * @remarks
+ * A field joins a group through {@link FieldBase.group}. Grouping arranges the form and
+ * changes no answer.
+ */
+export declare interface FormGroup {
+    readonly name: string;
+    readonly label: string;
+    readonly help?: string;
+}
+
+/**
+ * A form: a schema, the answers given against it, and the errors they carry.
+ *
+ * @remarks
+ * `valid` is true when the last completed evaluation found no error, and `dirty` is true once
+ * an answer differs from the one the form opened with. Both are derived, never stored.
+ *
+ * `touched` holds the fields somebody has visited, which is what lets a renderer withhold an
+ * error until the person has had their turn at it.
+ *
+ * @example
+ * ```ts
+ * form.fill('email', 'ada@example.com')
+ * const result = form.submit()
+ * if (result.success) await form.answer
+ * ```
+ */
+export declare interface FormInterface {
+    /** The form's event emitter. */
+    readonly emitter: EmitterInterface<FormEventMap>;
+    /** The schema this form asks. */
+    readonly schema: FormSchema;
+    /** The answers held right now. */
+    readonly values: FormValues;
+    /**
+     * The answers the form opened with: the schema's defaults, overlaid with any seeded values.
+     *
+     * @remarks
+     * It is fixed when the form opens and never moves again, so it is what `dirty` measures
+     * against and what {@link FormInterface.clear} returns to.
+     */
+    readonly baseline: FormValues;
+    /** Every error the last check produced. */
+    readonly errors: readonly FieldError[];
+    /** The names of the fields somebody has visited. */
+    readonly touched: ReadonlySet<string>;
+    /**
+     * The names of the fields currently out of the form.
+     *
+     * @remarks
+     * It opens as the set the schema declares through {@link FieldBase.disabled} and moves with
+     * every {@link FormInterface.disable} and {@link FormInterface.enable} call, so the schema
+     * holds the declaration and this holds the current fact.
+     */
+    readonly disabled: ReadonlySet<string>;
+    /** Where the form sits in its life. */
+    readonly status: FormStatus;
+    /** Whether the last completed evaluation found no error. */
+    readonly valid: boolean;
+    /** Whether any answer has moved since the form opened. */
+    readonly dirty: boolean;
+    /**
+     * The answers, once the form settles.
+     *
+     * @remarks
+     * It resolves with the submitted values on the first valid submit, and rejects when teardown
+     * abandons the form before it settles.
+     */
+    readonly answer: Promise<FormValues>;
+    /**
+     * Find one field by name.
+     *
+     * @param name - The field's name.
+     * @returns The field, or `undefined` when the schema declares no such name.
+     */
+    field(name: string): FormField | undefined;
+    /**
+     * Answer several fields at once.
+     *
+     * @param values - The answers to write, each keyed by its field name.
+     */
+    fill(values: FormValues): void;
+    /**
+     * Answer one field.
+     *
+     * @param name - The field's name.
+     * @param value - The answer to write, or `undefined` to clear it.
+     */
+    fill(name: string, value: FieldValue | undefined): void;
+    /**
+     * Record that somebody has visited a field.
+     *
+     * @param name - The field's name.
+     */
+    touch(name: string): void;
+    /**
+     * Fail a field from outside, for what the rules cannot see.
+     *
+     * @param name - The field's name.
+     * @param message - What to tell the person.
+     */
+    invalidate(name: string, message: string): void;
+    /**
+     * Take every field out of the form.
+     *
+     * @remarks
+     * A disabled field is neither evaluated nor submitted. Its answer is kept, and so is any
+     * {@link FormInterface.invalidate} failure it carries, which is withheld from `errors` while
+     * the field is out and restored when it comes back. The form emits `disable` once per field
+     * whose state actually moved, in schema order, so a call that moves nothing announces
+     * nothing. Disabling is a write, so a settled or abandoned form refuses it.
+     */
+    disable(): void;
+    /**
+     * Take one field out of the form.
+     *
+     * @param name - The field's name.
+     * @throws A {@link FormError} coded `FIELD` when the schema declares no such name.
+     */
+    disable(name: string): void;
+    /**
+     * Take several fields out of the form.
+     *
+     * @param names - The field names.
+     * @throws A {@link FormError} coded `FIELD` when the schema declares no such name. Every name
+     *   is checked before any field moves, so one bad name leaves the whole call undone.
+     */
+    disable(names: readonly string[]): void;
+    /**
+     * Put every field back into the form.
+     *
+     * @remarks
+     * An enabled field is evaluated and submitted again, and any invalidation held while it was
+     * out reappears in `errors`. The form emits `enable` once per field whose state actually
+     * moved, in schema order. Enabling is a write, so a settled or abandoned form refuses it.
+     */
+    enable(): void;
+    /**
+     * Put one field back into the form.
+     *
+     * @param name - The field's name.
+     * @throws A {@link FormError} coded `FIELD` when the schema declares no such name.
+     */
+    enable(name: string): void;
+    /**
+     * Put several fields back into the form.
+     *
+     * @param names - The field names.
+     * @throws A {@link FormError} coded `FIELD` when the schema declares no such name. Every name
+     *   is checked before any field moves, so one bad name leaves the whole call undone.
+     */
+    enable(names: readonly string[]): void;
+    /**
+     * Check every answer and settle the form when they all pass.
+     *
+     * @returns The values on success, or every error that stopped them.
+     */
+    submit(): FormResult;
+    /**
+     * Return every answer to {@link FormInterface.baseline}, the answers the form opened with.
+     *
+     * @remarks
+     * The runtime disabled overlay resets with them, so {@link FormInterface.disabled} reads the
+     * schema's declarations again.
+     */
+    clear(): void;
+    /**
+     * Tear the form down, abandoning it when it has not settled.
+     *
+     * @remarks
+     * A request from inside a listener defers teardown until the outermost mutation batch closes,
+     * so an in-flight settlement can win and leave the form `settled` rather than `abandoned`.
+     */
+    destroy(): void;
+}
+
+/**
+ * How to open a form.
+ *
+ * @param options - The form's settings.
+ * @remarks
+ * `on` wires listeners at construction and `error` receives any throw from one of them.
+ * `values` seeds the answers, overriding each field's declared default. `messages` replaces
+ * the default message of a rule, keyed by {@link FieldRuleName}.
+ *
+ * @example
+ * ```ts
+ * const options: FormOptions = {
+ * 	values: { email: 'ada@example.com' },
+ * 	messages: { required: 'This one is needed' },
+ * 	on: { submit: (values) => save(values) },
+ * }
+ * ```
+ */
+export declare interface FormOptions {
+    readonly on?: EmitterHooks<FormEventMap>;
+    readonly error?: EmitterErrorHandler;
+    readonly values?: FormValues;
+    readonly messages?: Readonly<Partial<Record<FieldRuleName, string>>>;
+}
+
+/**
+ * What a submit answers with: the values, or every error that stopped them.
+ *
+ * @example
+ * ```ts
+ * const result: FormResult = form.submit()
+ * const email = result.success ? result.value.email : undefined
+ * ```
+ */
+export declare type FormResult = Result<FormValues, readonly FieldError[]>;
+
+/**
+ * Everything a form asks.
+ *
+ * @remarks
+ * `fields` is the schema's only required member, and the order it declares is the order the
+ * form presents. `name`, `label`, and `help` describe the form itself.
+ *
+ * @example
+ * ```ts
+ * const schema: FormSchema = {
+ * 	label: 'Sign up',
+ * 	fields: [
+ * 		{ control: 'text', name: 'email', label: 'Email', rule: { required: true, email: true } },
+ * 		{ control: 'confirm', name: 'terms', label: 'I accept the terms' },
+ * 	],
+ * }
+ * ```
+ */
+export declare interface FormSchema {
+    readonly name?: string;
+    readonly label?: string;
+    readonly help?: string;
+    readonly groups?: readonly FormGroup[];
+    readonly fields: readonly FormField[];
+}
+
+/**
+ * Where a form sits in its life.
+ *
+ * @remarks
+ * A form opens `editing`, turns `settled` on its first valid submit, and turns `abandoned`
+ * when it is destroyed before settling. Both end states are terminal, and a write to a form
+ * in either one is refused. A destroy requested while a mutation batch is open is recorded,
+ * refuses every subsequent write immediately, and defers teardown until the outermost batch
+ * closes. The batch outcome wins: a batch that settles the form leaves it `settled`, resolves
+ * `answer`, and emits no `abandon`. Teardown never advances into, aborts, or rolls back the
+ * batch. The pending request is private, unnamed state and adds no fourth status.
+ */
+export declare type FormStatus = 'editing' | 'settled' | 'abandoned';
+
+/**
+ * A form's answers, keyed by field name.
+ *
+ * @remarks
+ * A name with no key is a field nobody has answered. A disabled field's value may appear so a
+ * renderer can show it, but the value is never evaluated or submitted.
+ *
+ * @example
+ * ```ts
+ * const values: FormValues = { email: 'ada@example.com', terms: true }
+ * ```
+ */
+export declare type FormValues = Readonly<Record<string, FieldValue>>;
+
+/** The maximum number of groups one schema may declare. */
+export declare const GROUP_LIMIT = 64;
+
+/** A signed or unsigned base-ten integer string. */
+export declare const INTEGER_PATTERN: Readonly<RegExp>;
+
+/**
+ * Determine whether an unknown value is one exact field choice record.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a field choice.
+ */
+export declare function isFieldChoice(input: unknown): input is FieldChoice;
+
+/**
+ * Determine whether an unknown value is a declared field control.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a field control.
+ */
+export declare function isFieldControl(input: unknown): input is FieldControl;
+
+/**
+ * Determine whether an unknown value is one exact field error record.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a field error.
+ */
+export declare function isFieldError(input: unknown): input is FieldError;
+
+/**
+ * Determine whether an unknown value is one exact field rule record.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a structurally valid field rule.
+ */
+export declare function isFieldRule(input: unknown): input is FieldRule;
+
+/**
+ * Determine whether an unknown value has a form field value shape.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a field value.
+ */
+export declare function isFieldValue(input: unknown): input is FieldValue;
+
+/**
+ * Determine whether an unknown value is a form error.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a {@link FormError} instance.
+ */
+export declare function isFormError(input: unknown): input is FormError;
+
+/**
+ * Determine whether an unknown value is one exact discriminated form field.
+ *
+ * @remarks
+ * Metadata is admitted structurally as bounded JSON. An accessor-bearing metadata record is
+ * refused later when {@link cloneFormField} takes ownership, because ownership accepts enumerable
+ * data properties only.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a structurally valid form field.
+ */
+export declare function isFormField(input: unknown): input is FormField;
+
+/**
+ * Determine whether an unknown value is one exact form group record.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a form group.
+ */
+export declare function isFormGroup(input: unknown): input is FormGroup;
+
+/**
+ * Determine whether an unknown value is one exact structural form schema.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a structurally valid form schema.
+ */
+export declare function isFormSchema(input: unknown): input is FormSchema;
+
+/**
+ * Determine whether an unknown value is a form lifecycle status.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a form status.
+ */
+export declare function isFormStatus(input: unknown): input is FormStatus;
+
+/**
+ * Determine whether an unknown value is a record of field values.
+ *
+ * @param input - The value to inspect.
+ * @returns Whether the value is a form values record.
+ */
+export declare function isFormValues(input: unknown): input is FormValues;
+
+/** The maximum number of entries one list-valued answer may hold. */
+export declare const LIST_LIMIT = 1024;
+
+/**
+ * Decide whether a raw binding value projects to an answered field.
+ *
+ * @remarks
+ * Bind with `fill(name, matchesAnswer(raw) ? raw : undefined)`. This projection treats an absent
+ * value and a string containing only whitespace as unanswered. Every other field value is an
+ * answer, including an empty list, `false`, and zero. Core evaluation does not use this projection:
+ * its `required` rule remains presence-only.
+ *
+ * @param value - The raw field value, or absence.
+ * @returns Whether the binding should preserve the value as an answer.
+ */
+export declare function matchesAnswer(value: FieldValue | undefined): boolean;
+
+/**
+ * Check whether a value has the shape required by one field control.
+ *
+ * @param field - The field that owns the value.
+ * @param value - The unknown value to inspect.
+ * @returns Whether the control can hold the value.
+ */
+export declare function matchesField(field: FormField, value: unknown): value is FieldValue;
+
+/**
+ * Compare two field values by scalar identity or ordered list content.
+ *
+ * @param a - The first field value.
+ * @param b - The second field value.
+ * @returns Whether both values contain the same answer.
+ */
+export declare function matchesValue(a: FieldValue, b: FieldValue): boolean;
+
+/**
+ * Compare two form value records by keys and value content.
+ *
+ * @param a - The first value record.
+ * @param b - The second value record.
+ * @returns Whether both records contain the same answers.
+ */
+export declare function matchesValues(a: FormValues, b: FormValues): boolean;
+
+/** The maximum length, in UTF-16 code units, of a schema, group, or field name. */
+export declare const NAME_LIMIT = 128;
+
+/** The maximum total number of records, arrays, and leaves one schema retains. */
+export declare const NODE_LIMIT = 16384;
+
+/** A number. */
+export declare interface NumberField extends FieldBase {
+    readonly control: 'number';
+    readonly default?: number;
+    readonly placeholder?: string;
+}
+
+/**
+ * Parse unknown wire data into an owned, semantically sound form schema.
+ *
+ * @param input - The unknown schema value to parse.
+ * @returns An owned schema with custom rules removed, or `undefined` on refusal.
+ */
+export declare function parseForm(input: unknown): FormSchema | undefined;
+
+/**
+ * Parse one answer against its field control.
+ *
+ * @param field - The field that defines the accepted value.
+ * @param input - The unknown value to parse.
+ * @returns The typed or lexically coerced field value, or `undefined` on refusal.
+ */
+export declare function parseValue(field: FormField, input: unknown): FieldValue | undefined;
+
+/**
+ * Parse a strict answer record against the fields declared by a schema.
+ *
+ * @param schema - The schema that owns the accepted field names and controls.
+ * @param input - The unknown answer record to parse.
+ * @returns An owned answer record, or `undefined` when any key or value is refused.
+ */
+export declare function parseValues(schema: FormSchema, input: unknown): FormValues | undefined;
+
+/**
+ * A secret, obscured as it is typed.
+ *
+ * @remarks
+ * It carries no `default` deliberately: a seeded secret is a secret written down. `mask` is
+ * the character the control repeats in place of the text.
+ */
+export declare interface PasswordField extends FieldBase {
+    readonly control: 'password';
+    readonly mask?: string;
+}
+
+/** The maximum accepted source length for an authored regular expression. */
+export declare const PATTERN_LIMIT = 256;
+
+/** Default failure copy for every named field rule. */
+export declare const RULE_MESSAGES: Readonly<Record<FieldRuleName, string>>;
+
+/**
+ * One choice out of a list.
+ *
+ * @remarks
+ * `open` admits a value the list does not offer, which is what turns a closed menu into a
+ * suggestion list.
+ */
+export declare interface SelectField extends FieldBase {
+    readonly control: 'select';
+    readonly choices: readonly FieldChoice[];
+    readonly default?: string;
+    readonly open?: boolean;
+}
+
+/**
+ * Project a schema into JSON while removing custom validators and absent values.
+ *
+ * @param schema - The schema to project.
+ * @returns A deep JSON copy of the serializable schema.
+ * @throws A {@link FormError} coded `SCHEMA` when accessor-bearing metadata cannot be owned. A
+ *   non-contract throw while reading metadata escapes unchanged.
+ */
+export declare function serializeForm(schema: FormSchema): JSONRecord;
+
+/** The maximum length, in UTF-16 code units, of any single retained string. */
+export declare const STRING_LIMIT = 65536;
+
+/** The maximum total length, in UTF-16 code units, of every string one schema retains. */
+export declare const TEXT_LIMIT = 1048576;
+
+/** A single line of text. */
+export declare interface TextField extends FieldBase {
+    readonly control: 'text';
+    readonly default?: string;
+    readonly placeholder?: string;
+}
+
+/** A 24-hour time string with optional seconds. */
+export declare const TIME_PATTERN: Readonly<RegExp>;
+
+/** A time of day, held as the control's own string. */
+export declare interface TimeField extends FieldBase {
+    readonly control: 'time';
+    readonly default?: string;
+}
+
+/** An absolute HTTP or HTTPS URL shape. */
+export declare const URL_PATTERN: Readonly<RegExp>;
+
+export { }