react-f0rm 1.3.0 → 1.5.0

package/dist/standard-schema-BAaTmAHh.d.ts

@@ -0,0 +1,682 @@
+import { EventEmitter } from '@for-fun/event-emitter';
+
+/** A single Standard Schema issue. */
+type StandardSchemaIssue = {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | {
+        readonly key: PropertyKey;
+    }> | undefined;
+};
+/** The union Standard Schema's `validate` resolves to. */
+type StandardSchemaResult<Output = unknown> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+} | {
+    readonly issues: ReadonlyArray<StandardSchemaIssue>;
+};
+/** Structural Standard Schema v1. `types` (optional in the spec) is what
+ * {@link InferSchemaValues} and `createForm`'s inference read. */
+type StandardSchemaV1<Input = unknown, Output = Input> = {
+    readonly '~standard': {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: Input) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+        readonly types?: {
+            readonly input: Input;
+            readonly output: Output;
+        };
+    };
+};
+/** The values type a Standard Schema produces: the `Output` of its
+ * `~standard.types` (coercions/transforms included). `never` when the
+ * schema lacks `types` — pass an explicit `TValues`. */
+type InferSchemaValues<S> = S extends {
+    readonly '~standard': {
+        readonly types: {
+            readonly output: infer Out;
+        };
+    };
+} ? Out : never;
+/** Implements Standard Schema v1 props? A boolean predicate, not a type
+ * guard — narrowing the union through a guard fails either way, so call
+ * sites cast after the check. */
+declare function hasStandardProps(schema: any): boolean;
+/** Field-level adapter: validate one value with a schema and map every
+ * issue to a FieldError (all issues surface; readers see the first). The
+ * parsed output is validation-only — field validators never rewrite. */
+declare function schemaToFieldValidator(schema: StandardSchemaV1<any, any>): Validator;
+/** Form-level adapter: validate the whole values object and return a
+ * ValidationOutcome. Failure nests errors ({a: {b: FieldError[]}});
+ * pathless issues land on FORM_ERROR. Success exposes the schema's parsed
+ * output as the parsedValues baseline. `createForm({validate: schema})`
+ * wraps through this automatically. */
+declare function schemaToFormValidator<T extends Record<string, any>>(schema: StandardSchemaV1<any, T>): (values: T) => Promise<ValidationOutcome<T>>;
+
+type PathSegments = (string | number)[];
+type Name = string | PathSegments;
+type Path = {
+    value: PathSegments;
+    key: string;
+};
+
+/** Compile-time field path utilities: `FieldPath<T>` enumerates valid
+ * path strings, `PathValue<T, P>` resolves the leaf type. Grammar mirrors
+ * `normalizePath`: numeric segments are bracket-only ('a[0]', never
+ * 'a.0' — dotted numerics throw at runtime). */
+
+/** `true` only for the `any` type (`0 extends 1 & any`). */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+/** Opt-in registry of value types the path types treat as opaque leaves:
+ * `FieldPath<T>` stops descending into them, `PathValue` resolves the
+ * field itself to that type. Merge via declaration merging
+ * (`interface OpaqueTypes { date: Date }`). Empty by default, so every
+ * object leaf stays navigable. */
+interface OpaqueTypes {
+}
+/** Union of every registered leaf type — `never` until an app merges entries. */
+type OpaqueLeaf = OpaqueTypes[keyof OpaqueTypes];
+/** Depth countdown: Prev[9] = 8 ... Prev[1] = 0, Prev[0] = never stops recursion. */
+type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+/** Paths are capped at 10 segments to keep instantiation depth bounded. */
+type MaxDepth = 9;
+/** Valid path continuations after a segment: `.k` / `[k]` / `[0]`, then
+ * deeper continuations. Numeric segments are bracket-only; numeric-string
+ * keys likewise enumerate just the bracket subscript. */
+type Continue<T, D extends number> = [D] extends [never] ? never : IsAny<T> extends true ? string : T extends OpaqueLeaf | Primitive | Function ? never : T extends readonly (infer U)[] ? `[${number}]` | `[${number}]${Continue<U, Prev[D]>}` : {
+    [K in Extract<keyof T, string>]: (K extends `${number}` ? never : `.${K}`) | `[${K}]` | (K extends `${number}` ? never : `.${K}${Continue<T[K], Prev[D]>}`) | `[${K}]${Continue<T[K], Prev[D]>}`;
+}[Extract<keyof T, string>];
+/** Every valid field path string for a values shape `T`. Capped at 10
+ * segments ({@link MaxDepth}); beyond the cap call sites fall back to
+ * `any`. {@link OpaqueTypes} entries stop recursion entirely.
+ * @example FieldPath<{a: {b: string}}> // 'a' | 'a.b' | 'a[b]' */
+type FieldPath<T> = IsAny<T> extends true ? string : T extends OpaqueLeaf | Primitive | Function ? never : T extends readonly (infer U)[] ? `[${number}]` | `[${number}]${Continue<U, MaxDepth>}` : {
+    [K in Extract<keyof T, string>]: K extends `${number}` ? never : K | `${K}${Continue<T[K], MaxDepth>}`;
+}[Extract<keyof T, string>];
+/** Field address as the hooks and components accept it: a typed path
+ * string or a raw segments array ({@link PathSegments}). */
+type AnyPath<T> = FieldPath<T> | PathSegments;
+/** Resolve `T[K]` for one bare segment: array index -> element, object key -> value. */
+type Lookup<T, K extends string> = K extends `${number}` ? T extends readonly (infer U)[] ? U : never : K extends keyof T ? T[K] : never;
+/** One dot-separated chunk: a bare segment plus any `[k]` / `[0]` suffixes. */
+type ChunkValue<T, C extends string> = C extends `${infer Key}[${infer Tail}` ? ChunkSuffix<Lookup<T, Key>, `[${Tail}`> : Lookup<T, C>;
+type ChunkSuffix<T, S extends string> = S extends `[${infer Key}]${infer Rest}` ? Rest extends '' ? Lookup<T, Key> : PathOf<Lookup<T, Key>, Rest> : never;
+/** Resolve the value type the path string `P` points at inside `T`. */
+type PathOf<T, P extends string> = P extends '' ? never : P extends `[${infer Key}]${infer Rest}` ? Rest extends '' ? Lookup<T, Key> : PathOf<Lookup<T, Key>, Rest> : P extends `.${infer Rest}` ? PathOf<T, Rest> : P extends `${infer Chunk}.${infer Rest}` ? PathOf<ChunkValue<T, Chunk>, Rest> : ChunkValue<T, P>;
+/** The value type at path `P` of a values shape `T`.
+ * @example PathValue<{a: {b: string}}, 'a.b'> // string */
+type PathValue<T, P extends FieldPath<T>> = PathOf<T, P & string>;
+type ResolvedPathValue<T, P> = PathValue<T, Extract<P, FieldPath<T>>>;
+/** The value type at `P`, or `any` when `P` is not a known field path
+ * (plain `string` / segment-array calls keep their old behavior). */
+type PathValueOf<T, P> = P extends FieldPath<T> ? ResolvedPathValue<T, P> : any;
+/** Element type of the array a path points at; non-array leaves resolve
+ * to themselves, unknown paths fall back to `any`. */
+type ArrayItemOf<T, P> = P extends FieldPath<T> ? ResolvedPathValue<T, P> extends readonly (infer U)[] ? U : ResolvedPathValue<T, P> : any;
+
+/** Type tag of a failed rule, as stored on the resulting FieldError. */
+type RuleType = 'required' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern';
+/** Form-level default rule messages — the `createForm({messages})` table
+ * overriding the built-in English defaults for every field (i18n in one
+ * place). A string may carry a `{bound}` placeholder (replaced with the
+ * rule's bound); a function receives the bound. A field's own message
+ * (the `required` string, `rules.messages`, `pattern.message`) still
+ * wins. */
+type FormMessages = Partial<Record<RuleType, string | ((bound?: number) => string)>>;
+/** Declarative field rules — a subset of react-hook-form's `register`
+ * rules. Failures land in the error state as FieldErrors (`type` = rule
+ * name), so any design system can render them. */
+type FieldRules = {
+    /** Fails on `''`, `undefined`, `null` or an empty array (`0`/`false`
+     * count as filled). A string is the message, `true` the default; failing
+     * skips the remaining rules. */
+    required?: string | true;
+    /** Fails when `Number(value)` is below this bound; `NaN` values skip. */
+    min?: number;
+    /** Fails when `Number(value)` is above this bound; `NaN` values skip. */
+    max?: number;
+    /** Fails when a string/array is shorter than this; other values skip. */
+    minLength?: number;
+    /** Fails when a string/array is longer than this; other values skip. */
+    maxLength?: number;
+    /** Fails when the value does not match `pattern.value`. */
+    pattern?: {
+        value: RegExp;
+        message: string;
+    };
+    /** Custom rule callbacks (one function or a named record), run after the
+     * declarative checks pass. A returned error keeps its message; `type`
+     * becomes the record key (`'validate'` for the single-function form).
+     * Sync-only. */
+    validate?: SyncValidator | Record<string, SyncValidator>;
+    /** Per-rule-type message override (defaults and pattern's inline message). */
+    messages?: Partial<Record<Exclude<RuleType, 'required'>, string>>;
+};
+
+/** Options accepted by {@link setFocus}. All flags default to `false`. */
+type SetFocusOptions = {
+    /** Select the field's text after focusing it. */
+    shouldSelect?: boolean;
+};
+/** Programmatically focus a bound field's element. Rides the same
+ * 'focusError' event channel a failed handleSubmit uses; being
+ * event-driven, it is a silent no-op when the field is unmounted or
+ * nothing subscribes. */
+declare function setFocus(form: Form, name: Name, options?: SetFocusOptions): void;
+
+/** An error value as validators yield it and the error setters
+ * accept it: one error, or a mixed list of them. */
+type ValidatorOutput = string | FieldError | (string | FieldError)[];
+/** Reserved top-level path segment for form-level errors: the Standard
+ * Schema adapter lands path-less issues under this key, read via
+ * getError(form, FORM_ERROR) / getFieldErrors(form, FORM_ERROR). */
+declare const FORM_ERROR = "_form";
+/** Brand marking a form-level validate result as a structured
+ * {@link ValidationOutcome} rather than a plain nested error record.
+ * Symbols can't collide with user records, so detection is
+ * `VALIDATION_OUTCOME in result`. */
+declare const VALIDATION_OUTCOME: unique symbol;
+/** Get a field's first error, or undefined. */
+declare function getError<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form<T>, name: P): FieldError | undefined;
+/** Get a field's first error by path, or undefined. */
+declare function getErrorByPath({ errors }: Form, path: Path): FieldError | undefined;
+/** Get all errors of a field (insertion order; empty array when none). */
+declare function getFieldErrors<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form<T>, name: P): FieldError[];
+/** Get all errors of a field by path (insertion order; empty when none). */
+declare function getFieldErrorsByPath({ errors }: Form, path: Path): FieldError[];
+/** Get all errors as {path, type, message} entries in insertion order;
+ * `path` is the dotted field path ('a.b', 'list.0'), one entry per error. */
+declare function getErrors({ errors }: Form): FieldErrorEntry[];
+/** A {@link FieldPath} string converted to the dotted key error records use
+ * at runtime ('items[0].name' → 'items.0.name'); quoted segments drop
+ * their quotes. Public so consumers can name the key style in their types. */
+type DottedPath<P extends string> = P extends `${infer H}[${infer N}]${infer R}` ? `${H extends '' ? '' : `${H}.`}${N extends `"${infer K}"` | `'${infer K}'` ? K : N}${DottedPath<R>}` : P;
+/** Every error as one record keyed by dotted path — react-hook-form's
+ * `FieldErrors<T>` shape — plus the {@link FORM_ERROR} slot. Values are
+ * the stored FieldError[] arrays shared with the form (read-only). */
+type FieldErrors<T extends Record<string, any> = any> = Partial<Record<DottedPath<Extract<FieldPath<T>, string>>, FieldError[]>> & {
+    [FORM_ERROR]?: FieldError[];
+};
+/** `true` only for the `any` type (the same probe {@link FieldPath}
+ * uses), so the tree of an untyped form degrades to `any` instead of an
+ * infinite mapped-type expansion. */
+type IsAnyTree<T> = 0 extends 1 & T ? true : false;
+type TreePrimitive = null | undefined | string | number | boolean | symbol | bigint;
+/** One level of the nested error tree: arrays become arrays of the item's
+ * tree, objects recurse per key, everything else is a leaf holding the
+ * stored FieldError[] (shared with the form — read-only). */
+type FieldErrorsTreeNode<T> = IsAnyTree<T> extends true ? any : T extends OpaqueTypes[keyof OpaqueTypes] ? FieldError[] : T extends TreePrimitive | Function | Date | File | FileList | Map<any, any> | Set<any> ? FieldError[] : T extends ReadonlyArray<infer E> ? FieldErrorsTreeNode<E>[] : {
+    [K in keyof T]?: FieldErrorsTreeNode<T[K]>;
+};
+/** Every error as one nested object following the values tree — the typed
+ * optional-chain counterpart of {@link FieldErrors}' flat dotted keys.
+ * Leaves hold the stored FieldError[] arrays (read-only); {@link
+ * FORM_ERROR} sits at the top level. A row-level error at `items[0]` and a
+ * field error at `items[0].name` cannot both occupy the `items[0]` slot:
+ * whichever landed later owns it (insertion order). The flat record never
+ * conflicts — read it when both coexist. */
+type FieldErrorsTree<T = any> = FieldErrorsTreeNode<T> & {
+    [FORM_ERROR]?: FieldError[];
+};
+/** Get every error as one record keyed by dotted path ('a.b', 'list.0') —
+ * react-hook-form's `formState.errors` shape. Values are the stored
+ * FieldError[] arrays (read-only). Memoized per form with the same
+ * version-bump/read pattern {@link getValues} uses, so consecutive reads
+ * hand back one stable reference until an error actually changes. */
+declare function getErrorsRecord<T extends Record<string, any> = any>(form: Form<T>): FieldErrors<T>;
+/** Get every error as one nested object following the values tree
+ * (`errors.items[0].name`), the optional-chaining counterpart of
+ * {@link getErrorsRecord}. Leaves hold the stored FieldError[] arrays
+ * (read-only); memoized via the same version-bump/read pattern. */
+declare function getErrorsTree<T extends Record<string, any> = any>(form: Form<T>): FieldErrorsTree<T>;
+/** Convert a field path (bracket spelling, the `name` every API takes)
+ * into the dotted key error records use: `'items[0].name'` →
+ * `'items.0.name'`. */
+declare function fieldPathToDottedKey(name: Name): string;
+/** Convert a dotted errors-record key back into bracket path spelling
+ * (`'items.0.name'` → `'items[0].name'`). Inherently lossy: the dotted key
+ * cannot distinguish a segment containing a literal dot, so for such paths
+ * keep the bracket spelling and read the record via
+ * {@link fieldPathToDottedKey}. */
+declare function dottedKeyToFieldPath(key: string): string;
+/** Get the first error's message, or undefined when there are no errors. */
+declare function getFirstError({ errors }: Form): string | undefined;
+/** Options accepted by {@link setError}. */
+type SetErrorOptions = {
+    /** Focus the field's element after the error lands (react-hook-form's
+     * `setError` `shouldFocus`); unmounted fields are silent no-ops. */
+    shouldFocus?: boolean;
+};
+/** Set a field's error. A string is normalized to {type: 'custom',
+ * message}; a FieldError is stored as-is; an array holds several (falsy
+ * items dropped); undefined clears. */
+declare function setError<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form<T>, name: P, error: ValidatorOutput | undefined, options?: SetErrorOptions): void;
+/** Set a field's error by path. See {@link setError} for the input shapes. */
+declare function setErrorByPath(form: Form, path: Path, error: ValidatorOutput | undefined, options?: SetErrorOptions): void;
+/** Clear errors: a single path, a list of paths, or (omitted) every error. */
+declare function clearErrors(form: Form, name?: Name | Name[]): void;
+/** Options accepted by {@link setServerErrors}. */
+type SetServerErrorsOptions = {
+    /** Keep existing field errors instead of clearing them first. Defaults
+     * to `false`: a fresh response replaces the prior error state. */
+    keepExisting?: boolean;
+};
+/** Land a server-side error response: each entry becomes the named field's
+ * error(s) with `type: 'server'`. A string lands as one error, an array as
+ * several, an empty array clears the field. By default existing errors are
+ * cleared first; pass `keepExisting: true` to layer instead. */
+declare function setServerErrors(form: Form, errors: Record<string, string | string[]>, options?: SetServerErrorsOptions): void;
+/** Drop every `type: 'server'` error — the round-trip state a previous
+ * submit landed. {@link handleSubmit} runs this before its validation
+ * round so a retry is judged fresh; client errors are untouched. Emits
+ * payload-less 'errors' when anything changed. */
+declare function clearServerErrors(form: Form): void;
+declare function hasErrors({ errors }: Form): boolean;
+
+/** The meta bag passed to a validator's second argument. */
+type ValidatorMeta = {
+    form: Form;
+    path: Path;
+};
+declare function unsetValidatingByPath({ emitter, validating }: Form, path: Path): void;
+declare function setValidatingByPath({ emitter, validating }: Form, path: Path): void;
+/** Field validator: an error (string, FieldError, or an array mixing
+ * both) or undefined — synchronously or as a Promise. `meta.signal`
+ * aborts when the round is superseded, so async work can be cancelled;
+ * stale results are dropped by the round lock either way. Older
+ * two-argument signatures keep working. */
+type Validator = (value: any, meta: ValidatorMeta & {
+    signal: AbortSignal;
+}) => ValidatorOutput | undefined | Promise<ValidatorOutput | undefined>;
+/** Synchronous pre-validator (declarative `required` gates in practice):
+ * runs on every kick, never debounced; its errors land immediately and
+ * short-circuit the debounced validator while present. No Promise, no
+ * `signal` — nothing to abort. */
+type SyncValidator = (value: any, meta: ValidatorMeta) => ValidatorOutput | undefined;
+/** Live options for {@link registerValidatorByPath}: accessors, read at
+ * every kick, so `useValidate` can swap them per render without
+ * re-subscribing mid-flight. */
+type ValidatorRegistration = {
+    validate: () => Validator | undefined;
+    /** Debounce delay in milliseconds; 0 (default) runs immediately. */
+    debounce: () => number;
+    /** Runs on every kick, never debounced. */
+    sync: () => SyncValidator | undefined;
+    /** Keep the debounced validator running when the sync gate failed
+     * (TanStack `asyncAlways`): gate errors land immediately, the
+     * validator's result lands alongside them per-source. Absent = false
+     * (gate owns the outcome). */
+    asyncAlways?: () => boolean;
+};
+/**
+ * Register a field validator's kick at `path` ({@link Form.validators})
+ * — the framework-free machinery behind `useValidate`. Returns a
+ * disposer that drops the registration and cancels pending work.
+ *
+ * Contract (what `trigger`/`ensureValidate`/the user-change gate rely
+ * on): the `sync` gate runs on every kick, never debounced, and
+ * short-circuits the debounced validator while failing — unless
+ * `asyncAlways`, which lands the validator's result alongside the
+ * gate's (per-source); a positive `debounce` merges kicks, and the
+ * field counts as validating while the window is pending; async results
+ * land under a round lock — superseded outcomes drop, only the owning
+ * round releases the mark; a synchronous throw propagates. Registering
+ * at an occupied path replaces the entry (last-wins).
+ */
+declare function registerValidatorByPath(form: Form, path: Path, registration: ValidatorRegistration): () => void;
+/** Options accepted by {@link trigger}. `shouldTouch` defaults to `false`;
+ * omitting the options object entirely keeps the plain validate-only
+ * behavior, so the historical two-argument calls are untouched. */
+type TriggerOptions = {
+    /** Mark the triggered scope touched once the round settles, pass or
+     * fail (RHF trigger `shouldTouch`). Defaults to `false`. */
+    shouldTouch?: boolean;
+    /** Focus the first errored field in the triggered scope once the round
+     * settles (RHF trigger `shouldFocus`). Rides the 'focusError' channel
+     * like failed-submit auto-focus; unmounted paths are silent no-ops.
+     * Defaults to `false`. */
+    shouldFocus?: boolean;
+};
+/**
+ * Trigger validation. Without `name`: every registered field validator,
+ * then the form-level `validate` (after fields settle, same pipeline as
+ * {@link ensureValidate}). One name runs that field only; a name array
+ * runs each in order; `[]` is a no-op. A segments array mixes in numbers
+ * (`['items', 0]`); pure string arrays are name lists (`['a', 'b']`
+ * triggers fields `a` and `b`, not the nested path).
+ *
+ * The promise waits for the round to settle (async validators included)
+ * and never rejects — it resolves whether the triggered scope is
+ * error-free. With `name`, only those fields' errors count and
+ * form-level `validate` is skipped (RHF semantics). Fire-and-forget
+ * callers may ignore it: the kicks still run synchronously.
+ */
+declare function trigger(form: Form, name?: Name | Name[], options?: TriggerOptions): Promise<boolean>;
+/**
+ * Run the form-level `validate` and land its result, honoring
+ * `validateDebounce`. Undebounced: the caller's await is the call — no
+ * mark, no gating, rejection propagates. Debounced: kicks merge into a
+ * window (the form counts as validating), the round reads then-current
+ * values and supersedes in-flight rounds, and every merged caller's
+ * promise settles with the final round's outcome. Form-level-only round:
+ * `useForm`'s validateOnMount and cross-cutting re-checks; `trigger` /
+ * `ensureValidate` compose it after fields settle.
+ */
+declare function runFormValidate(form: Form): Promise<void>;
+/** The mode/reValidateMode gate shared by change/blur kicks and both
+ * validateDeps re-runs: fires for `cadence` and `'all'`, for
+ * `'onTouched'` once touched, else when `reValidateMode` matches
+ * `cadence` and an error is still live. `hasError` reads lazily. */
+declare function shouldKick(mode: ValidationMode, cadence: 'onChange' | 'onBlur', touched: boolean, hasError: () => boolean, reValidateMode: ReValidateMode): boolean;
+/**
+ * Form-level twin of the gated change kick: re-run `validate` after a
+ * user change to a field in `validateDeps`. Rides the changed field's
+ * onChange pipeline, so programmatic setValue writes never fire it. The
+ * gate uses the changed field's effective `mode` and the form-level
+ * `reValidateMode` against the last round's error footprint:
+ * onChange/all — every dep change; onTouched — once touched; otherwise
+ * while the round's error is still live under reValidateMode onChange
+ * (the submit-then-fix flow). Fire-and-forget: async rejections are
+ * swallowed, sync throws propagate. A no-op (one property check) unless
+ * `validateDeps` lists `path`.
+ */
+declare function revalidateFormOnChange(form: Form, path: Path, mode: ValidationMode): void;
+/** Register one field's deps: `key` re-validates when any path in
+ * `depKeys` changes. Idempotent per pair — StrictMode's double effect is
+ * harmless. */
+declare function registerFieldValidateDeps(form: Form, key: string, depKeys: string[]): void;
+/** Drop one field's deps registration; empty entries are removed so the
+ * registry never outlives its fields. */
+declare function unregisterFieldValidateDeps(form: Form, key: string, depKeys: string[]): void;
+/**
+ * Field-level twin: after a user change to `path`, re-run every field
+ * validator that declared it as a dep. Same channel and gate as
+ * {@link revalidateFormOnChange} — the dependent's own error arms
+ * reValidateMode, and a passing re-run replaces it (a field validator
+ * owns its whole key). Ordinary validator kicks: the dependent's
+ * debounce applies, sync throws propagate. A no-op unless some field
+ * declared `path` as a dep.
+ */
+declare function revalidateDependentsOnChange(form: Form, path: Path, mode: ValidationMode): void;
+/** {@link ensureValidate}'s rejection: `message` is the first error's
+ * display text; `.errors` carries the full flattened list ({@link
+ * getErrors}) for branching without re-reading the form. */
+type FormValidationError = Error & {
+    errors: FieldErrorEntry[];
+};
+/**
+ * Validate and throw if any field error.
+ * @param form
+ * @return resolve if no error; reject and stop validate if has an error
+ */
+declare function ensureValidate(form: Form): Promise<void>;
+/**
+ * Validate and return if any field error.
+ * @param form
+ * @return error message string or void
+ */
+declare function validate(form: Form): Promise<void | string>;
+
+/** A field error: `type` is the error kind, `message` the display text. */
+type FieldError = {
+    type: string;
+    message: string;
+};
+/** A flattened entry from {@link getErrors}. */
+type FieldErrorEntry = {
+    path: string;
+    type: string;
+    message: string;
+};
+/** When a field is validated:
+ * - `'onSubmit'` (default): only on submit
+ * - `'onBlur'`: when the field loses focus
+ * - `'onChange'`: on every change
+ * - `'onTouched'`: on first blur, then on every change
+ * - `'all'`: on both change and blur
+ */
+type ValidationMode = 'onSubmit' | 'onBlur' | 'onChange' | 'onTouched' | 'all';
+/** When a field is re-validated after it already has an error:
+ * - `'onChange'` (default): on every change
+ * - `'onBlur'`: when the field loses focus
+ * - `'onSubmit'`: only on submit (no live re-validation)
+ */
+type ReValidateMode = 'onChange' | 'onBlur' | 'onSubmit';
+/** When the form-level {@link Options.validate} re-runs outside
+ * submit/`trigger`/`validateOnMount`:
+ * - `'onSubmit'` (default): submit/trigger only — cross-field linkage via
+ *   {@link Options.validateDeps}
+ * - `'onChange'`: every user change to a bound field
+ * - `'onBlur'`: every user blur of a bound field
+ */
+type FormValidateMode = 'onSubmit' | 'onChange' | 'onBlur';
+/**
+ * Options accepted by {@link Form.register} — the non-hook binding for
+ * uncontrolled fields (react-hook-form's `register` contract: the bound
+ * element never re-renders; the store carries every write).
+ */
+type RegisterOptions = {
+    /** Field-level validation mode for this binding; defaults to the form's
+     * `mode`. */
+    mode?: ValidationMode;
+    /** Unmount behavior: `true` (the library's historical default) tombstones
+     * the path, `false` keeps the value. Falls back to the form-level
+     * `createForm({shouldUnregister})` when omitted. */
+    shouldUnregister?: boolean;
+    /** DOM event → value extractor for the returned `onChange`. Defaults to
+     * the element's protocol (`target.files`/`target.checked`/
+     * `target.valueAsNumber`/`target.valueAsDate`, else `target.value`) —
+     * the same extraction `<Field>` performs. */
+    eventToValue?: (e: any) => any;
+    /** Store `e.target.valueAsNumber` instead of the string value. An
+     * explicit `eventToValue` takes precedence. */
+    valueAsNumber?: boolean;
+    /** Store `e.target.valueAsDate` instead of the string value. An explicit
+     * `eventToValue` takes precedence; combining with `valueAsNumber` is a
+     * TypeError. */
+    valueAsDate?: boolean;
+    /** Declarative rules for this binding — the same {@link FieldRules}
+     * `useField`/`<Field>` take (`required` runs as the synchronous gate).
+     * Wired through `registerValidatorByPath`, so `trigger`/submit/`mode`
+     * gating see it like a hook-registered validator; `validateDebounce` is
+     * fixed at 0. */
+    rules?: FieldRules;
+};
+/** What {@link Form.register} returns: spread these onto an uncontrolled
+ * DOM element (`<input {...form.register('name')} />`). `name` is the
+ * store's path key; `onChange` writes through the gated user-change
+ * pipeline; `ref` attach seeds the element's DOM content and detach
+ * tombstones unless `shouldUnregister: false`. */
+type RegisterProps = {
+    name: string;
+    onChange: (e: any) => void;
+    onBlur: () => void;
+    ref: (el: any) => void;
+};
+/** Structured form-level validate result: `errors` uses the same nested
+ * shape a plain error record uses, `values` is the schema's parsed output
+ * (coerce/transform included). Either side may be omitted. The brand
+ * constant lives in the errors module and is re-exported below. */
+type ValidationOutcome<T> = {
+    [VALIDATION_OUTCOME]: true;
+    errors?: Record<string, any>;
+    values?: T;
+};
+/** What a form-level validate function may return: a plain nested error
+ * record (flattened into field errors — the long-standing shape), or a
+ * branded {@link ValidationOutcome} whose `values` become the form's
+ * parsedValues baseline. */
+type ValidateResult<T> = Record<string, any> | ValidationOutcome<T> | Promise<Record<string, any> | ValidationOutcome<T>>;
+/** Context passed to a form-level `validate`'s second argument. `signal`
+ * aborts when the round is superseded (only under a positive
+ * `validateDebounce`, where kicks merge), so async work can be cancelled;
+ * stale results are dropped by the round gate either way. */
+type FormValidateMeta<T extends Record<string, any> = any> = {
+    form: Form<T>;
+    signal: AbortSignal;
+};
+/** Form-level validator: receives all values (plus an optional {@link
+ * FormValidateMeta}) and returns a {@link ValidateResult} — sync or async
+ * — or `undefined` when valid (falsy results are skipped). */
+type FormValidateFn<T extends Record<string, any> = any> = (values: T, meta: FormValidateMeta<T>) => ValidateResult<T> | undefined;
+/** The emitter event table for {@link Form.emitter}: path-carrying events
+ * declare an optional single `Path` payload (sent for single-field
+ * mutations, omitted for bulk payload-less broadcasts); `focusError`
+ * carries the path key plus optional {@link SetFocusOptions}. */
+type FormEvents = ['change', [path?: Path]] | ['errors', [path?: Path]] | ['touched', [path?: Path]] | ['validating', [path?: Path]] | ['submitting', []] | ['submitCount', []] | ['submitSuccessful', []] | ['reset', []] | ['disabled', [path?: Path]] | ['status', []] | ['loading', []] | ['focusError', [key: string, options?: SetFocusOptions]];
+type Form<T extends Record<string, any> = any> = {
+    emitter: EventEmitter<FormEvents>;
+    mode: ValidationMode;
+    reValidateMode: ReValidateMode;
+    initialValues: T;
+    values: Map<string, any>;
+    /** Tombstones of unregistered field paths (JSON path keys): reading or
+     * merging values must not fall back to initialValues for these paths. */
+    deleted: Set<string>;
+    /** Every error registered for a field, as a non-empty array (the
+     * write-side {@link setErrorByPath} normalizes to this invariant).
+     * First entry via {@link getError}, all of them via
+     * {@link getFieldErrors}. */
+    errors: Map<string, FieldError[]>;
+    touched: Set<string>;
+    /** Per-field validation kicks registered by {@link
+     * registerValidatorByPath}: invoking one validates the field's current
+     * value. `trigger`/`ensureValidate` run every entry; the user-change
+     * gate runs the entry at the changed path. */
+    validators: Map<string, () => void>;
+    validating: Set<string>;
+    /** Parsed values from the last successful schema validation: layered
+     * between initialValues and the values Map in {@link getValues}, cleared
+     * by `reset`/`setInitialValues`. Never affects dirty state. */
+    parsedValues: T | undefined;
+    /** Form-level validator, seeded from {@link Options.validate}. */
+    validate?: FormValidateFn<T>;
+    /** Delay in ms before the form-level `validate` runs; seeded from
+     * {@link Options.validateDebounce} and fixed at create time. */
+    validateDebounce?: number;
+    /** Path keys whose user changes re-run the form-level `validate`;
+     * normalized from {@link Options.validateDeps} at create time. */
+    validateDeps?: ReadonlySet<string>;
+    /** When the form-level `validate` re-runs outside submit/trigger — the
+     * cadence from {@link Options.validateMode}, seeded at create time. */
+    validateMode: FormValidateMode;
+    /** Form-level default messages for declarative rules, seeded from
+     * {@link Options.messages}: one table overriding every field's built-in
+     * English rule message (i18n in one place). Per-field messages still
+     * win. */
+    messages?: FormMessages;
+    isSubmitting: boolean;
+    /** Whether a submit has been attempted — set by `handleSubmit` on every
+     * attempt, cleared by `reset` (react-hook-form's `isSubmitted`). */
+    isSubmitted: boolean;
+    submitCount: number;
+    isSubmitSuccessful: boolean | undefined;
+    /** True while an async {@link Options.initialValues} source is pending —
+     * the form starts empty and the resolved values land as the baseline.
+     * Flips through the payload-less 'loading' event. */
+    isLoading: boolean;
+    /** Form-level default for a bound field's unmount behavior: `true` (the
+     * default) tombstones an unmounted field, `false` keeps its value. A
+     * field's own `shouldUnregister` option overrides this. */
+    shouldUnregister?: boolean;
+    /** Form-level disabled flag, OR-ed into every bound field's `disabled`
+     * (form flag || the field's own option). Toggled at runtime with
+     * {@link setDisabled}, which emits a payload-less 'disabled' event. */
+    disabled: boolean;
+    /** Form-level default for mount validation: `true` kicks every mounted
+     * field's validator once after mount (deferred until an async
+     * {@link Options.initialValues} source lands) and runs the form-level
+     * `validate` once. A field's own option overrides this. */
+    validateOnMount: boolean;
+    /** Form-level default for `asyncAlways`: whether a field's debounced
+     * validator still runs when its `required` gate failed. A field's own
+     * option overrides this flag. */
+    asyncAlways: boolean;
+    /** Whether native constraint validation gates submission and skips a
+     * bound `<Field>`'s custom validators on a native-failing kick. Seeded
+     * from {@link Options.shouldUseNativeValidation} (default `true`); a
+     * submit may override per attempt. */
+    shouldUseNativeValidation: boolean;
+    /** User-owned metadata slot for non-field state (Formik's `status`
+     * role). Written with {@link setStatus}, which emits the payload-less
+     * 'status' event; read via {@link useStatus}. Starts `undefined`. */
+    status: any;
+    /** Non-hook field binding — react-hook-form's `register` contract:
+     * spread the returned props onto an uncontrolled DOM element and the
+     * element never re-renders while the store carries every write. No
+     * React state involved, so it works anywhere. See {@link
+     * RegisterOptions} / {@link RegisterProps}. */
+    register: (name: Name, options?: RegisterOptions) => RegisterProps;
+};
+type Options<T extends Record<string, any> = any> = {
+    /** The values baseline. Sync objects seed immediately; async sources (a
+     * Promise, or a thunk returning a value/Promise) start the form empty
+     * with `isLoading: true` and land the resolved values as the baseline
+     * via setInitialValues. A rejected source keeps the form empty and logs
+     * in DEV. The thunk runs at create time. */
+    initialValues?: T | Promise<T> | (() => T | Promise<T>);
+    /** When fields are validated. Defaults to `'onSubmit'`. See
+     * {@link ValidationMode}. */
+    mode?: ValidationMode;
+    /** When a field is re-validated after it already has an error. Defaults
+     * to `'onChange'`. See {@link ReValidateMode}. */
+    reValidateMode?: ReValidateMode;
+    /** Form-level validator: returns a record of errors keyed by field path
+     * (nested objects flattened 'a.b' style, array values contribute each
+     * non-empty string). A branded {@link ValidationOutcome} adds parsed
+     * `values` as the parsedValues baseline. Alternatively pass a Standard
+     * Schema v1 object directly — it is wrapped into a validator
+     * automatically. */
+    validate?: FormValidateFn<T> | StandardSchemaV1<unknown, T>;
+    /** Milliseconds to debounce the form-level `validate`: kicks inside the
+     * window merge into one run, and while the timer is pending the form
+     * counts as validating. Defaults to `0` (runs immediately). */
+    validateDebounce?: number;
+    /** Fields whose user changes re-run the form-level `validate` — the
+     * cross-field dependency list. A re-run only clears errors the previous
+     * round wrote; errors the round never wrote are untouched. Omit it and
+     * the form-level `validate` only runs on `trigger`/submit. */
+    validateDeps?: FieldPath<T>[];
+    /** When the form-level `validate` re-runs outside submit/`trigger`/
+     * `validateOnMount` — a cadence declaration instead of enumerating
+     * {@link Options.validateDeps}. See {@link FormValidateMode}. */
+    validateMode?: FormValidateMode;
+    /** Form-level default messages for declarative rules, keyed by rule
+     * type — one table overriding the built-in English defaults for every
+     * field (i18n in one place). A string may carry a `{bound}`
+     * placeholder; a function receives the bound. A field's own message
+     * (the `required` string, `rules.messages`, `pattern.message`) still
+     * wins. See {@link FormMessages}. */
+    messages?: FormMessages;
+    /** Form-level default for a bound field's unmount behavior. `true` (the
+     * default) tombstones an unmounted field; `false` keeps the value
+     * (react-hook-form's `shouldUnregister`). A field's own option
+     * overrides this. */
+    shouldUnregister?: boolean;
+    /** Start the form with every bound field disabled — bound fields OR this
+     * flag with their own `disabled` option (a field cannot opt out).
+     * Toggle later with {@link setDisabled}. Defaults to `false`. */
+    disabled?: boolean;
+    /** Form-level default for `asyncAlways`: when true, a field whose
+     * `required` gate failed still runs its debounced validator (the gate's
+     * errors land immediately, the validator's result lands alongside
+     * them per-source). A field's own option overrides this. Defaults to
+     * `false`. */
+    asyncAlways?: boolean;
+    /** Whether native constraint validation gates submission and skips a
+     * bound `<Field>`'s custom validators on a native-failing kick
+     * (react-hook-form's `shouldUseNativeValidation`). Defaults to `true`.
+     * Fixed at create time; a single submit may override it. */
+    shouldUseNativeValidation?: boolean;
+    /** Validate on mount: `true` makes every mounted field's validator run
+     * once after mount (errors show for an untouched form) and runs the
+     * form-level `validate` once. Mount kicks are deferred while an async
+     * `initialValues` source is pending. A field's own option overrides
+     * this. Defaults to `false`. */
+    validateOnMount?: boolean;
+};
+/** Create a form instance. */
+declare function create<T extends Record<string, any> = any>(options?: Options<T>): Form<T>;
+
+export { getFieldErrorsByPath as $, clearErrors as H, clearServerErrors as J, create as K, dottedKeyToFieldPath as L, ensureValidate as M, fieldPathToDottedKey as Q, getError as U, getErrorByPath as W, getErrors as X, getErrorsRecord as Y, getErrorsTree as Z, getFieldErrors as _, getFirstError as a0, hasErrors as a1, registerFieldValidateDeps as a2, registerValidatorByPath as a3, revalidateDependentsOnChange as a4, revalidateFormOnChange as a5, runFormValidate as a6, setError as a7, setErrorByPath as a8, setFocus as a9, setServerErrors as aa, setValidatingByPath as ab, shouldKick as ac, trigger as ad, unregisterFieldValidateDeps as ae, unsetValidatingByPath as af, validate as ag, hasStandardProps as ai, schemaToFormValidator as aj, schemaToFieldValidator as ak, VALIDATION_OUTCOME as c, FORM_ERROR as n };
+export type { AnyPath as A, SyncValidator as B, ValidateResult as C, DottedPath as D, ValidatorOutput as E, Form as F, ValidatorRegistration as G, InferSchemaValues as I, Name as N, Options as O, Path as P, RegisterOptions as R, StandardSchemaV1 as S, TriggerOptions as T, Validator as V, FieldRules as a, StandardSchemaIssue as ah, FieldErrorEntry as b, ValidationOutcome as d, ArrayItemOf as e, FieldError as f, PathValueOf as g, ValidationMode as h, RegisterProps as i, FieldPath as j, FieldErrors as k, FieldErrorsTree as l, FormEvents as m, FormMessages as o, FormValidateFn as p, FormValidateMeta as q, FormValidateMode as r, FormValidationError as s, OpaqueTypes as t, PathSegments as u, PathValue as v, ReValidateMode as w, SetErrorOptions as x, SetFocusOptions as y, SetServerErrorsOptions as z };