@orkestrel/form 0.0.12 → 0.0.13

package/README.md

@@ -20,7 +20,7 @@ npm install @orkestrel/form
 
 ## Requirements
 
-- Node.js >= 22.12
+- Node.js >= 22.18
 - Host-independent: no `node:*`, no DOM. Ships dual ESM+CJS builds.
 
 ## Usage

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

@@ -1,33 +1,11 @@
 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;
-}
+import type { FieldError } from '@orkestrel/form';
+import type { FieldValue } from '@orkestrel/form';
+import type { FormField } from '@orkestrel/form';
+import type { FormInterface } from '@orkestrel/form';
+import type { FormSubmission } from '@orkestrel/form';
 
 /**
  * Creates a native form binding exposed through its lifecycle interface.
@@ -43,171 +21,6 @@ declare interface ConfirmField extends FieldBase {
  */
 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 entries for `checkbox`, `list`, 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, or each entry of a `list`. `required` requires an entry for `list` and presence
- * for other controls. `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`, `list`, and `file` hold 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;
@@ -301,340 +114,6 @@ export declare interface FormBindingValidity {
 /** 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 | ListField | 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.
@@ -657,26 +136,6 @@ export declare function isFormBindingError(value: unknown): value is FormBinding
  */
 export declare function isFormControl(value: unknown): value is FormControl;
 
-/**
- * Represents an ordered list of free-text strings.
- *
- * @remarks
- * `required` requires at least one entry. `minimum` and `maximum` count entries.
- * `pattern`, `email`, `url`, `integer`, and `alphanumeric` check each entry and name
- * the failing value in its message. `custom` checks the whole list. Duplicates are retained.
- *
- * @example
- * ```ts
- * const to: ListField = {
- * 	control: 'list', name: 'to', rule: { required: true, email: true },
- * }
- * ```
- */
-declare interface ListField extends FieldBase {
-    readonly control: 'list';
-    readonly default?: readonly string[];
-}
-
 /**
  * Checks a native control population against a field's declared value shape.
  * @param field - The declared field.
@@ -689,25 +148,6 @@ declare interface ListField extends FieldBase {
  */
 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.
@@ -741,31 +181,4 @@ export declare function readFormControls(field: FormField, controls: readonly Fo
  */
 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 { }