@orkestrel/form 0.0.9 → 0.0.11

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

@@ -0,0 +1,750 @@
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { JSONRecord } from '@orkestrel/contract';
+import type { Result } from '@orkestrel/contract';
+
+/**
+ * Represents 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.
+ */
+declare interface CheckboxField extends FieldBase {
+    readonly control: 'checkbox';
+    readonly choices: readonly FieldChoice[];
+    readonly default?: readonly string[];
+}
+
+/** Represents a color, held as the control's own six-digit `#rrggbb` string. */
+declare interface ColorField extends FieldBase {
+    readonly control: 'color';
+    readonly default?: string;
+}
+
+/** Represents a single on/off box, holding a boolean. */
+declare interface ConfirmField extends FieldBase {
+    readonly control: 'confirm';
+    readonly default?: boolean;
+}
+
+/**
+ * Creates a native form binding exposed through its lifecycle interface.
+ * @param element - The native form.
+ * @param document - The borrowed answer document.
+ * @param options - Feedback destinations and listeners.
+ * @returns The initialized native binding.
+ * @example
+ * ```ts
+ * const binding = createFormBinding(element, document)
+ * binding.refresh()
+ * ```
+ */
+export declare function createFormBinding(element: HTMLFormElement, document: FormInterface, options?: FormBindingOptions): FormBindingInterface;
+
+/** Represents a calendar date, held as the control's own `YYYY-MM-DD` string. */
+declare interface DateField extends FieldBase {
+    readonly control: 'date';
+    readonly default?: string;
+}
+
+/** Represents a date and a time of day together, with no zone, held as the control's own string. */
+declare interface DatetimeField extends FieldBase {
+    readonly control: 'datetime';
+    readonly default?: string;
+}
+
+/** Represents text over many lines. */
+declare interface EditorField extends FieldBase {
+    readonly control: 'editor';
+    readonly default?: string;
+    readonly placeholder?: string;
+}
+
+/**
+ * Declares what every field carries, whatever its control.
+ *
+ * @remarks
+ * `name` keys the field in {@link FormValues} and `group` names a {@link FormGroup}.
+ *
+ * `hidden`, `locked`, and `disabled` 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.
+ */
+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;
+}
+
+/**
+ * Represents 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.
+ */
+declare interface FieldChoice {
+    readonly value: string;
+    readonly label: string;
+    readonly help?: string;
+    readonly disabled?: boolean;
+}
+
+/**
+ * Represents 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.
+ */
+declare interface FieldError {
+    readonly field: string;
+    readonly message: string;
+    readonly rule?: FieldRuleName;
+}
+
+/**
+ * Represents 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' }
+ * ```
+ */
+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;
+}
+
+/**
+ * Lists 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.
+ */
+declare type FieldRuleName = Exclude<keyof FieldRule, 'custom'>;
+
+/**
+ * Checks 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 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 Thrown when a {@link FieldValidator} throws; its 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'
+ * ```
+ */
+declare type FieldValidator = (value: FieldValue | undefined, values: FormValues) => true | string;
+
+/**
+ * Represents 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[]`.
+ */
+declare type FieldValue = string | number | boolean | readonly string[];
+
+/**
+ * Represents one or more files, by name.
+ *
+ * @remarks
+ * A value is the names alone: bytes never enter the document. `accept` lists the media types
+ * and extensions the control offers, in the form the host expects.
+ */
+declare interface FileField extends FieldBase {
+    readonly control: 'file';
+    readonly accept?: readonly string[];
+    readonly multiple?: boolean;
+}
+
+/** Implements a controlled native form over a borrowed document. */
+export declare class FormBinding implements FormBindingInterface {
+    #private;
+    /**
+     * Binds existing controls to the supplied document's answers.
+     * @param element - The native form, including its externally associated controls.
+     * @param document - The borrowed answer document.
+     * @param options - Feedback destinations and listeners.
+     * @throws Thrown when controls contradict the schema or native initialization fails.
+     */
+    constructor(element: HTMLFormElement, document: FormInterface, options?: FormBindingOptions);
+    /** Holds the native form. */
+    get element(): HTMLFormElement;
+    /** Holds the borrowed answer document. */
+    get document(): FormInterface;
+    /** Reports whether the binding released its resources. */
+    get destroyed(): boolean;
+    /** Holds the binding's isolated event emitter. */
+    get emitter(): EmitterInterface<FormBindingEventMap>;
+    /** Imports mounted enabled controls without acknowledging their answers. */
+    read(): void;
+    /** Rediscovers controls and projects the document into the native form. */
+    refresh(): void;
+    /** Releases owned DOM effects and listeners without destroying the document. */
+    destroy(): void;
+}
+
+/** Records an attribute's authored value and the binding's last contribution. */
+export declare interface FormBindingAttribute {
+    readonly original: string | null;
+    readonly value: string | null;
+}
+
+/** Reports an incompatible control, overlapping submission, or native DOM failure. */
+export declare class FormBindingError extends Error {
+    readonly code: FormBindingErrorCode;
+    readonly context: Readonly<Record<string, unknown>> | undefined;
+    /**
+     * Creates a native binding refusal.
+     * @param code - The refusal category.
+     * @param message - The explanation.
+     * @param context - The associated field or cause.
+     */
+    constructor(code: FormBindingErrorCode, message: string, context?: Readonly<Record<string, unknown>>);
+}
+
+/** Names a native binding refusal. */
+export declare type FormBindingErrorCode = 'CONTROL' | 'PENDING' | 'DOM';
+
+/** Lists the native binding's notifications after their associated DOM effects. */
+export declare type FormBindingEventMap = {
+    readonly render: readonly [];
+    /** Reports a control after its native value changes during document projection. */
+    readonly write: readonly [control: FormControl];
+    readonly submit: readonly [submission: FormSubmission, submitter: HTMLElement | undefined];
+    readonly error: readonly [error: unknown];
+};
+
+/** Declares a native form's borrowed document and synchronization lifecycle. */
+export declare interface FormBindingInterface {
+    readonly element: HTMLFormElement;
+    readonly document: FormInterface;
+    readonly destroyed: boolean;
+    readonly emitter: EmitterInterface<FormBindingEventMap>;
+    /** Imports mounted enabled controls without acknowledging their answers. */
+    read(): void;
+    /** Rediscovers controls and projects the document into the native form. */
+    refresh(): void;
+    /** Releases owned DOM effects and listeners without destroying the document. */
+    destroy(): void;
+}
+
+/** Configures neutral feedback destinations and isolated event listeners. */
+export declare interface FormBindingOptions {
+    readonly feedback?: ReadonlyMap<string, HTMLElement>;
+    readonly summary?: HTMLElement;
+    /** Maps native controls to focus targets whose departure touches the represented field. */
+    readonly presentations?: ReadonlyMap<FormControl, HTMLElement>;
+    /** Defers blur touch until a same-form button's primary pointer press finishes. Default: false. */
+    readonly defer?: boolean;
+    readonly on?: EmitterHooks<FormBindingEventMap>;
+    readonly error?: EmitterErrorHandler;
+}
+
+/** Records the binding's custom-validity contribution beside the authored message. */
+export declare interface FormBindingValidity {
+    readonly original: string;
+    readonly value: string;
+}
+
+/** Represents a native answer control admitted by the binding. */
+export declare type FormControl = HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+
+/**
+ * Lists 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.
+ * `touch` announces the first visit since clear. `prepare`, `accept`, and `abort` carry the receipt
+ * after their state is committed. `clear` and `abandon` are signals.
+ */
+declare type FormEventMap = {
+    readonly fill: readonly [name: string, value: FieldValue | undefined];
+    readonly touch: readonly [name: string];
+    readonly validate: readonly [errors: readonly FieldError[]];
+    readonly disable: readonly [name: string];
+    readonly enable: readonly [name: string];
+    readonly submit: readonly [values: FormValues];
+    readonly prepare: readonly [submission: FormSubmission];
+    readonly accept: readonly [submission: FormSubmission];
+    readonly abort: readonly [submission: FormSubmission];
+    readonly clear: readonly [];
+    readonly abandon: readonly [];
+};
+
+/**
+ * Represents 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 : []
+ * }
+ * ```
+ */
+declare type FormField = TextField | EditorField | PasswordField | NumberField | DateField | TimeField | DatetimeField | ColorField | ConfirmField | SelectField | CheckboxField | FileField;
+
+/**
+ * Represents a named section of a form.
+ *
+ * @remarks
+ * A field joins a group through {@link FieldBase.group}. Grouping arranges the form and
+ * changes no answer.
+ */
+declare interface FormGroup {
+    readonly name: string;
+    readonly label: string;
+    readonly help?: string;
+}
+
+/**
+ * Declares the contract a form exposes: the state it holds and the calls that move it.
+ *
+ * @remarks
+ * `valid` is true when the last completed evaluation found no error, and `dirty` is true once
+ * an answer differs from its acknowledged baseline. 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
+ * ```
+ */
+declare interface FormInterface {
+    /** Holds the form's event emitter. */
+    readonly emitter: EmitterInterface<FormEventMap>;
+    /** Holds the schema this form asks. */
+    readonly schema: FormSchema;
+    /** Reports the answers the form holds. */
+    readonly values: FormValues;
+    /**
+     * Holds the acknowledged answers, initially the schema's defaults overlaid with seeded values.
+     *
+     * @remarks
+     * Acceptance advances only the enabled fields captured by the submission, including absence.
+     * It is what `dirty` measures against and what {@link FormInterface.clear} returns to.
+     */
+    readonly baseline: FormValues;
+    /** Holds the submission awaiting acknowledgement, or `undefined` when none is pending. */
+    readonly pending: FormSubmission | undefined;
+    /** Holds every error the last check produced. */
+    readonly errors: readonly FieldError[];
+    /** Lists the names of the fields somebody has visited. */
+    readonly touched: ReadonlySet<string>;
+    /**
+     * Lists the names of the fields that are 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>;
+    /** Reports where the form sits in its life. */
+    readonly status: FormStatus;
+    /** Reports whether the last completed evaluation found no error. */
+    readonly valid: boolean;
+    /** Reports whether any answer differs from its acknowledged baseline. */
+    readonly dirty: boolean;
+    /**
+     * Holds the answers after 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>;
+    /**
+     * Finds 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;
+    /**
+     * Answers one field, or several at once.
+     *
+     * @param values - The answers to write, each keyed by its field name.
+     */
+    fill(values: FormValues): void;
+    /**
+     * Answers 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;
+    /**
+     * Records that somebody has visited a field.
+     *
+     * @param name - The field's name.
+     */
+    touch(name: string): void;
+    /**
+     * Fails a field from outside, for what the rules cannot see.
+     *
+     * @remarks
+     * One field holds one external failure, so a second call replaces the first, and the failure
+     * lasts until that field is filled again or the form is cleared.
+     * A receipt admits only a captured enabled field whose fill revision still matches. Stale,
+     * foreign, copied, consumed, and teardown-invalidated receipts return `false`; unknown fields
+     * still throw `FIELD`.
+     *
+     * @param name - The field's name.
+     * @param message - What to tell the person.
+     * @param submission - The active receipt to check against the field's captured revision.
+     * @returns True if the failure was applied; false if the receipt or field revision is stale.
+     */
+    invalidate(name: string, message: string, submission?: FormSubmission): boolean;
+    /**
+     * Takes one field, several fields, or 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;
+    /**
+     * Takes 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;
+    /**
+     * Takes 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;
+    /**
+     * Puts one field, several fields, or 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;
+    /**
+     * Puts 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;
+    /**
+     * Puts 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;
+    /**
+     * Checks every answer and settles the form when they all pass.
+     *
+     * @returns The values on success, or every error that stopped them.
+     */
+    submit(): FormResult;
+    /**
+     * Prepares an owned enabled snapshot for acknowledgement while leaving the form editable.
+     *
+     * @returns The submission on success, or the errors that prevented preparation.
+     * @throws A {@link FormError} coded `PENDING` for an overlapping preparation or pending receipt,
+     *   or when clear interrupts preparation; terminal forms retain their terminal refusals.
+     */
+    prepare(): FormPreparationResult;
+    /**
+     * Adopts the active submission's captured answers into the baseline without changing live state.
+     *
+     * @param submission - The receipt returned by preparation.
+     * @returns True if this active receipt was accepted; false otherwise, including after teardown.
+     */
+    accept(submission: FormSubmission): boolean;
+    /**
+     * Consumes the active submission and aborts its signal without changing answers or baseline.
+     *
+     * @param submission - The receipt returned by preparation.
+     * @returns True if this active receipt was aborted; false otherwise, including after teardown.
+     */
+    abort(submission: FormSubmission): boolean;
+    /**
+     * Returns every answer to its acknowledged baseline and aborts pending acknowledgement.
+     *
+     * @remarks
+     * Those answers are {@link FormInterface.baseline}. The runtime disabled overlay resets with
+     * them, so {@link FormInterface.disabled} reads the schema's declarations again.
+     */
+    clear(): void;
+    /**
+     * Tears the form down, abandoning it when it has not settled.
+     *
+     * @remarks
+     * Tearing down twice does nothing the second time. 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;
+}
+
+/** Reports a prepared submission, or every error that prevented its preparation. */
+declare type FormPreparationResult = Result<FormSubmission, readonly FieldError[]>;
+
+/**
+ * Reports 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
+ * ```
+ */
+declare type FormResult = Result<FormValues, readonly FieldError[]>;
+
+/**
+ * Describes 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' },
+ * 	],
+ * }
+ * ```
+ */
+declare interface FormSchema {
+    readonly name?: string;
+    readonly label?: string;
+    readonly help?: string;
+    readonly groups?: readonly FormGroup[];
+    readonly fields: readonly FormField[];
+}
+
+/**
+ * Represents 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.
+ */
+declare type FormStatus = 'editing' | 'settled' | 'abandoned';
+
+/**
+ * Carries an owned, frozen answer snapshot and the signal for its pending acknowledgement.
+ *
+ * @remarks
+ * Only the producing form accepts this object's identity. Copying its members cannot create a
+ * receipt. The values and their lists are frozen; the native signal remains usable by transports.
+ */
+declare interface FormSubmission {
+    readonly values: FormValues;
+    readonly signal: AbortSignal;
+}
+
+/**
+ * Represents 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 }
+ * ```
+ */
+declare type FormValues = Readonly<Record<string, FieldValue>>;
+
+/**
+ * Checks whether a value is a native binding refusal.
+ * @param value - The value to inspect.
+ * @returns True if the value is a native binding refusal; false otherwise.
+ * @example
+ * ```ts
+ * isFormBindingError(new FormBindingError('CONTROL', 'Duplicate text controls')) // true
+ * ```
+ */
+export declare function isFormBindingError(value: unknown): value is FormBindingError;
+
+/**
+ * Checks whether a value is a native answer control.
+ * @param value - The value to inspect.
+ * @returns True if the value is an input, select, or textarea; false otherwise.
+ * @example
+ * ```ts
+ * isFormControl(document.createElement('input')) // true
+ * ```
+ */
+export declare function isFormControl(value: unknown): value is FormControl;
+
+/**
+ * Checks a native control population against a field's declared value shape.
+ * @param field - The declared field.
+ * @param controls - Associated controls sharing its name.
+ * @returns True if the population has an unambiguous compatible shape; false otherwise.
+ * @example
+ * ```ts
+ * matchesFormControls({ control: 'text', name: 'name' }, [document.createElement('input')]) // true
+ * ```
+ */
+export declare function matchesFormControls(field: FormField, controls: readonly FormControl[]): boolean;
+
+/** Represents a number. */
+declare interface NumberField extends FieldBase {
+    readonly control: 'number';
+    readonly default?: number;
+    readonly placeholder?: string;
+}
+
+/**
+ * Represents 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.
+ */
+declare interface PasswordField extends FieldBase {
+    readonly control: 'password';
+    readonly mask?: string;
+}
+
+/**
+ * Reads one compatible native population using the document's blank-to-absence semantics.
+ * @param field - The field declaring the answer shape.
+ * @param controls - Controls sharing the field's name, in native order.
+ * @returns The native answer, or undefined for an absent answer or empty population.
+ * @throws Thrown when the population or answer is incompatible, including numeric bad input.
+ * @example
+ * ```ts
+ * const input = document.createElement('input')
+ * input.value = 'Ada'
+ * readFormControls({ control: 'text', name: 'name' }, [input]) // 'Ada'
+ * ```
+ */
+export declare function readFormControls(field: FormField, controls: readonly FormControl[]): FieldValue | undefined;
+
+/**
+ * Reads native constraint messages not already reported by document rules.
+ * @param control - The native control with binding-owned custom validity removed.
+ * @param errors - The document's reported failures.
+ * @returns Uncovered constraint messages, preserving authored custom validity.
+ * @remarks
+ * A lone native failure retains platform copy. Competing failures use constraint-specific
+ * copy because the platform exposes only one message for the whole control.
+ * @example
+ * ```ts
+ * const input = document.createElement('input')
+ * input.name = 'name'
+ * input.required = true
+ * readNativeMessages(input, [{ field: 'name', rule: 'required', message: 'Enter a name' }]) // []
+ * ```
+ */
+export declare function readNativeMessages(control: FormControl, errors: readonly FieldError[]): readonly string[];
+
+/**
+ * Represents 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.
+ */
+declare interface SelectField extends FieldBase {
+    readonly control: 'select';
+    readonly choices: readonly FieldChoice[];
+    readonly default?: string;
+    readonly open?: boolean;
+}
+
+/** Represents a single line of text. */
+declare interface TextField extends FieldBase {
+    readonly control: 'text';
+    readonly default?: string;
+    readonly placeholder?: string;
+}
+
+/** Represents a time of day, held as the control's own `HH:MM` string, with seconds optional. */
+declare interface TimeField extends FieldBase {
+    readonly control: 'time';
+    readonly default?: string;
+}
+
+export { }