react-f0rm 1.1.0 → 1.2.0

package/dist/form-BiDaJLjD.d.ts

@@ -1,826 +0,0 @@
-import { EventEmitter } from '@for-fun/event-emitter';
-
-type PathSegments = (string | number)[];
-type Name = string | PathSegments;
-type Path = {
-    value: PathSegments;
-    key: string;
-};
-
-/**
- * Compile-time field path utilities: `FieldPath<T>` enumerates the valid
- * path strings for a values shape `T` ('a', 'a.b', 'a[0]', 'a[b]', ...),
- * and `PathValue<T, P>` resolves the leaf type a path points at.
- * The grammar mirrors the paths accepted at runtime by `normalizePath`:
- * numeric segments are bracket-only ('a[0]', never 'a.0' — dotted
- * numerics throw a TypeError 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;
-/** 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]`,
- * optionally followed by deeper continuations into the child node.
- * Numeric segments are bracket-only (`.0` throws at runtime); object
- * keys that are themselves numeric strings likewise enumerate just the
- * bracket subscript.
- */
-type Continue<T, D extends number> = [D] extends [never] ? never : IsAny<T> extends true ? string : T extends 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`.
- * @example FieldPath<{a: {b: string}}> // 'a' | 'a.b' | 'a[b]'
- */
-type FieldPath<T> = IsAny<T> extends true ? string : T extends 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>];
-/** 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>;
-/**
- * The value type at path `P` of `T`, 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> ? PathValue<T, Extract<P, FieldPath<T>>> : any;
-
-/** A field error: `type` identifies the error kind ('custom' for plain
- * string errors), `message` is the display text. */
-interface 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';
-/** Brand marking a form-level validate result as a structured
- * {@link ValidationOutcome} (parsed values and/or errors) rather than a
- * plain nested error record. Symbols cannot collide with user error
- * records, so detection is an exact `VALIDATION_OUTCOME in result`. */
-declare const VALIDATION_OUTCOME: unique symbol;
-/** 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 results included). Either side may be omitted. */
-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` function's second argument.
- * `signal` aborts as soon as the round is superseded — a newer round
- * started (which only happens under a positive `validateDebounce`, where
- * kicks merge into windows) — so async validators can cancel their
- * underlying work instead of racing a stale result home. Stale results
- * are dropped independently by the round gate, so validators that ignore
- * the signal stay correct too; the same contract field-level validators
- * get through their own `meta`. */
-type FormValidateMeta<T extends Record<string, any> = any> = {
-    form: Form<T>;
-    signal: AbortSignal;
-};
-/** Form-level validator: receives all values (plus {@link
- * FormValidateMeta} as an optional second argument) and returns a
- * {@link ValidateResult} — sync or async — or `undefined`/nothing when
- * valid (the runtime skips falsy results, so implicit-return callbacks
- * type-check). */
-type FormValidateFn<T extends Record<string, any> = any> = (values: T, meta: FormValidateMeta<T>) => ValidateResult<T> | undefined;
-interface Form<T extends Record<string, any> = any> {
-    emitter: EventEmitter;
-    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, so
-     * readers never need to guard against an empty list). Readers wanting
-     * the display error take the first entry ({@link getError}); readers
-     * wanting all of them use {@link getFieldErrors}. */
-    errors: Map<string, FieldError[]>;
-    touched: Set<string>;
-    validators: Map<string, () => void>;
-    /** Change handlers published by mounted fields (`useField`): each is the
-     * field's own onChange — the write plus its mode/reValidateMode-gated
-     * validation kick. Path-based writes with user-change semantics
-     * ({@link changeValueByPath}) route through the registered handler; the
-     * effective per-field mode and live-error view live inside the field's
-     * closure, so this map is the only channel that can reproduce them.
-     * Multiple fields mounted at the same path compete for the slot
-     * last-wins — the latest mount's handler answers every user-change
-     * write; the unmount guard in `useField` keeps a later owner's
-     * registration intact when the earlier field goes away. */
-    changeHandlers: Map<string, (value: any) => void>;
-    validating: Set<string>;
-    /** Parsed values from the last successful schema validation: the
-     * schema's complete output tree (coerced/transformed values included).
-     * Sits between initialValues and the values Map in {@link getValues}
-     * until `reset`/`setInitialValues` clears it. Never affects dirty
-     * state — that compares live edits against initialValues only. */
-    parsedValues: T | undefined;
-    /** Form-level validator, seeded from {@link Options.validate}. May
-     * receive a second {@link FormValidateMeta} argument. */
-    validate?: FormValidateFn<T>;
-    /** Delay in milliseconds before the form-level `validate` runs; seeded
-     * from {@link Options.validateDebounce} and fixed at create time. */
-    validateDebounce?: number;
-    /** Path keys (JSON-stringified segments) of the fields whose user
-     * changes re-run the form-level `validate`; normalized from {@link
-     * Options.validateDeps} at create time and fixed thereafter. */
-    validateDeps?: ReadonlySet<string>;
-    isSubmitting: boolean;
-    submitCount: number;
-    isSubmitSuccessful: boolean | undefined;
-    /** Form-level disabled flag, OR-ed into every bound field's `disabled`
-     * (form flag || the field's own option). Seeded from
-     * {@link Options}.disabled at create time and toggled at runtime with
-     * {@link setDisabled}, which emits a payload-less 'disabled' event so
-     * subscribed fields re-render. */
-    disabled: boolean;
-}
-type Options<T extends Record<string, any> = any> = {
-    initialValues?: 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 — it only
-     * takes effect once the field 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 are flattened ('a.b' style) and array values contribute
-     * every non-empty string they hold as separate errors (zod `flatten()`
-     * formErrors style). Schema adapters instead return a branded
-     * {@link ValidationOutcome}: `errors` flattens the same way, `values`
-     * (the schema's parsed output) becomes the form's parsedValues baseline
-     * that {@link getValues} layers over initialValues.
-     */
-    validate?: FormValidateFn<T>;
-    /**
-     * Milliseconds to debounce the form-level `validate`: kicks from
-     * `trigger`/`ensureValidate`/submit inside the window merge into one
-     * run, and while the timer is pending the form counts as validating,
-     * so `trigger` and submit wait the window out — the same contract the
-     * per-field `validateDebounce` gives field validators. The merged run
-     * reads the values current when its timer fires. Defaults to `0`
-     * (validate runs immediately, exactly as before this option existed).
-     */
-    validateDebounce?: number;
-    /** Fields whose user changes re-run the form-level `validate` — the
-     * cross-field dependency list (password-confirm mismatch and friends).
-     * Each entry is a field path ('password', 'user.email', 'items.0.qty');
-     * a user change to a listed field re-runs the form-level `validate`
-     * under the same mode/`reValidateMode` gating the field's own
-     * validator gets. Omit it and the form-level `validate` only runs on
-     * `trigger`/submit, exactly as before this option existed.
-     *
-     * Opting in also changes what a re-run may clear: each round first
-     * drops the errors the previous round wrote (paths it flattened onto),
-     * so a dep change that fixes the cross-field error makes it disappear.
-     * Errors the round never wrote — field validators', `setServerErrors`,
-     * manual `setError` — are never touched. TanStack Form's counterpart is
-     * `onChangeListenTo` (v1) / validator `triggers` (v2 alpha). */
-    validateDeps?: FieldPath<T>[];
-    /** Start the form with every bound field disabled — the flag bound
-     * fields OR with their own `disabled` option (a field cannot opt out
-     * of a disabled form). Toggle later with {@link setDisabled}.
-     * Defaults to `false`. */
-    disabled?: boolean;
-};
-/**
- * Create form instance
- * @param options
- * @return form instance
- */
-declare function create<T extends Record<string, any> = any>(options?: Options<T>): Form<T>;
-/**
- * Get form values: the values Map layered over parsedValues (when a schema
- * validation produced them) layered over initialValues.
- *
- * Merged with copy-on-write ownership tracking ({@link setOwned}): every
- * distinct container on a written path is allocated once and shared by all
- * paths through it, instead of re-copying the whole branch for every key.
- * One owned set spans the whole merge, so containers borrowed from the
- * parsedValues tree are copied before mutation exactly like initialValues
- * ones. The result is a freshly merged tree per mutation, with untouched
- * branches sharing references with the baseline exactly like chained
- * `set` did.
- *
- * Memoized per form like {@link getDirtyFields}: every value write bumps a
- * `version` counter ({@link bumpValuesVersion}) while reads reset it, so
- * consecutive reads hand back the same reference (submit, changeValue and
- * form-level validate all read the whole tree, often several times per
- * interaction). Treat the result as read-only — the next read after a
- * write returns a fresh tree, but between writes the cached one is shared
- * with every other reader.
- *
- * parsedValues is the schema's complete output tree: once validation
- * succeeds it replaces the initialValues baseline (fields the schema
- * dropped disappear), while live edits in the values Map still win over
- * both. It never affects dirty state — {@link isDirty} and
- * {@link getDirtyFields} compare live edits against initialValues only,
- * because parsing is not a user edit.
- *
- * @param form
- */
-declare function getValues<T extends Record<string, any> = any>(form: Form<T>): T;
-/**
- * Get field value
- * @param form
- * @param name
- */
-declare function getValue<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form<T>, name: P): PathValueOf<T, P>;
-/**
- * Get field value by path
- * @param form
- * @param path
- */
-declare function getValueByPath({ initialValues, parsedValues, values, deleted }: Form, path: Path): any;
-/** Options accepted by {@link setValue} / {@link setValueByPath} / {@link
- * changeValue} / {@link changeValueByPath}. `shouldValidate`/`shouldTouch`
- * default to `false`; omitting the options object entirely keeps the plain
- * set-value behavior (no validation, no touched marking, dirty stays
- * derived). */
-interface SetFieldOptions {
-    /** Run the field's registered validator (if any) after the value lands,
-     * same as triggering that single field. Defaults to `false`. */
-    shouldValidate?: boolean;
-    /** Mark the field as touched. Defaults to `false`. */
-    shouldTouch?: boolean;
-    /** Land the value as a commit instead of an edit: the value becomes the
-     * field's dirty-comparison baseline, so `getDirtyFields`/`isDirty`/
-     * `getFieldState().isDirty` read the field as clean, and a later write
-     * dirties it only by differing from the new baseline. `true` (or
-     * omitting the flag) keeps the default derived behavior — dirty while
-     * the live value differs from initialValues. */
-    shouldDirty?: boolean;
-}
-/**
- * Set field value
- * @param form
- * @param name
- * @param value
- * @param options
- */
-declare function setValue<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form<T>, name: P, value: PathValueOf<T, P>, options?: SetFieldOptions): void;
-/**
- * Set field value
- * @param form
- * @param path
- * @param value
- * @param options
- */
-declare function setValueByPath(form: Form, path: Path, value: any, options?: SetFieldOptions): void;
-/**
- * The write of {@link setValueByPath} minus the `'change'` emit: the
- * render-time {@link useField} `initialValue` seed. The field's first
- * paint (SSR included — effects never run on the server) must already
- * carry the value, so the write happens during render where emitting is
- * illegal; the seeding field announces it from its post-commit effect
- * through {@link emitChangeByPath} instead.
- *
- * Everything else matches a plain write: descendant keys of the seeded
- * path are pruned, the branch's tombstones and committed baselines are
- * revived/dropped, and both memo caches are invalidated. Like the effect
- * seed it replaces, the caller guards it to paths with no value yet.
- */
-declare function seedValueByPath(form: Form, path: Path, value: any): void;
-/** Announce a {@link seedValueByPath} that happened during render: the
- * payload-carrying `'change'` emit {@link setValueByPath} would have
- * fired, split out so it can run post-commit where emitting is safe.
- * Subscribers that rendered after the seed re-read an unchanged snapshot
- * and bail; subscribers from earlier commits resync. */
-declare function emitChangeByPath({ emitter }: Form, path: Path): void;
-/**
- * Set a field value as a user change.
- *
- * The write routes through the field's own onChange when one is mounted
- * (registered by `useField`), so it fires exactly the validation a user
- * typing into the field would fire: the field's effective `mode`
- * (per-field override included) and the form's `reValidateMode`. With no
- * mounted field on the path it degrades to a plain value set
- * ({@link setValue}).
- *
- * This is the channel for component-library bridges that hand a control a
- * plain setter bound to a field — they cannot rebuild the gating from
- * public form state, because the per-field mode override and the
- * live-error view that gates `reValidateMode` live inside the field's
- * onChange closure.
- *
- * Contrast {@link setValue}: that is the imperative channel — its
- * `shouldValidate` option kicks the field's validator unconditionally,
- * ignoring any mode. Functional updaters are the caller's to evaluate
- * ({@link getValue}).
- *
- * `options` carries the same {@link SetFieldOptions}: on the fallback path
- * (no mounted field) they forward to {@link setValueByPath} wholesale,
- * while on the mounted-field path only `shouldDirty: false` applies — the
- * write lands as a commit while the field's own mode gating keeps driving
- * validation, which is the point of this channel.
- *
- * @param form
- * @param name
- * @param value
- * @param options
- */
-declare function changeValue<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form<T>, name: P, value: PathValueOf<T, P>, options?: SetFieldOptions): void;
-/**
- * Set a field value as a user change, by parsed path
- * @param form
- * @param path
- * @param value
- * @param options
- */
-declare function changeValueByPath(form: Form, path: Path, value: any, options?: SetFieldOptions): void;
-/**
- * Get field error
- * @param form
- * @param name
- * @return FieldError object or undefined
- */
-declare function getError<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form<T>, name: P): FieldError | undefined;
-/**
- * Get field error by path
- * @param form
- * @param path
- * @return first FieldError of the field, or undefined
- */
-declare function getErrorByPath({ errors }: Form, path: Path): FieldError | undefined;
-/**
- * Get all errors of a field
- * @param form
- * @param name
- * @return every error registered for the field (insertion order); an empty
- *         array when the field has none
- */
-declare function getFieldErrors<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form<T>, name: P): FieldError[];
-/**
- * Get all errors of a field by path
- * @param form
- * @param path
- * @return every error registered for the field (insertion order); an empty
- *         array when the field has none
- */
-declare function getFieldErrorsByPath({ errors }: Form, path: Path): FieldError[];
-/**
- * Get all errors
- * @param form
- * @return array of {path, type, message} entries, in insertion order; path
- *         is the user-facing dotted field path ('a.b', 'list.0'), and a
- *         field holding several errors contributes one entry per error
- */
-declare function getErrors({ errors }: Form): FieldErrorEntry[];
-/**
- * Get first error message
- * @param form
- * @return first error's message string, or undefined when there are no errors
- */
-declare function getFirstError({ errors }: Form): string | undefined;
-/** Snapshot of one field's aggregated state, as {@link getFieldState}
- * returns it. `errors` is the stored array shared with the form — treat it
- * as read-only, like every {@link getFieldErrors} result. */
-interface FieldState<T = any> {
-    value: T;
-    error: FieldError | undefined;
-    errors: FieldError[];
-    isDirty: boolean;
-    isTouched: boolean;
-    isValidating: boolean;
-}
-/**
- * Get one field's aggregated state: the layered value ({@link getValue}),
- * the first error ({@link getError}) and every error ({@link
- * getFieldErrors}), dirtiness, the touched flag, and whether a validator
- * is in flight. `isDirty` applies the same per-field rule as {@link
- * getDirtyFields}: a live value exists and differs from initialValues at
- * that path (parsedValues never counts — parsing is not an edit).
- *
- * @param form
- * @param name
- */
-declare function getFieldState<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form<T>, name: P): FieldState<PathValueOf<T, P>>;
-declare function unsetValidatingByPath({ emitter, validating }: Form, path: Path): void;
-declare function setValidatingByPath({ emitter, validating }: Form, path: Path): void;
-/**
- * Set field error
- * @param form
- * @param name
- * @param error string is normalized to {type: 'custom', message}; a
- *        FieldError object is stored as-is; an array holds several errors
- *        (falsy items dropped, strings normalized); undefined clears
- */
-declare function setError<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form<T>, name: P, error: string | FieldError | (string | FieldError)[] | undefined): void;
-/**
- * Set field error
- * @param form
- * @param path
- * @param error string is normalized to {type: 'custom', message}; a
- *        FieldError object is stored as-is; an array holds several errors
- *        (falsy items dropped, strings normalized); undefined clears
- */
-declare function setErrorByPath({ emitter, errors }: Form, path: Path, error: string | FieldError | (string | FieldError)[] | undefined): void;
-/**
- * Clear errors
- * @param form
- * @param name a single path or a list of paths; omit to clear every error
- */
-declare function clearErrors(form: Form, name?: Name | Name[]): void;
-/** Options accepted by {@link setServerErrors}. */
-interface SetServerErrorsOptions {
-    /** Keep existing field errors instead of clearing them first. Defaults
-     * to `false`: a fresh server response replaces the prior error state. */
-    keepExisting?: boolean;
-}
-/**
- * Land a server-side error response on the form: each entry becomes the
- * named field's error(s) with `type: 'server'`, ready for the same
- * renderError/`useError` channel client-side validation uses. Takes the
- * flat `Record<string, string | string[]>` shape REST APIs commonly
- * return (RealWorld: `422 {errors: {email: ['has already been taken']}}`)
- * without a hand-rolled `Object.entries` + `setError` loop.
- *
- * A string value lands as one error, a string array as several (first one
- * is what `getError`/`error` expose); an empty array clears that field's
- * errors. By default every existing error is cleared first — a fresh
- * response describes the current state, not a patch onto stale client
- * errors; pass `keepExisting: true` to layer instead.
- * @param form
- * @param errors field errors keyed by name
- * @param options
- */
-declare function setServerErrors(form: Form, errors: Record<string, string | string[]>, options?: SetServerErrorsOptions): void;
-/**
- * Set field touched state
- * @param form
- * @param name
- */
-declare function setTouched(form: Form, name: Name): void;
-/**
- * Set field touched state
- * @param form
- * @param path
- */
-declare function setTouchedByPath({ emitter, touched }: Form, path: Path): void;
-/**
- * Check if field has been touched
- * @param form
- * @param name
- */
-declare function hasTouched<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form<T>, name: P): boolean;
-/**
- * Check if field has been touched
- * @param form
- * @param path
- */
-declare function hasTouchedByPath({ touched }: Form, path: Path): boolean;
-/**
- * Is dirty -- any value differs from initialValues
- * @param form
- */
-declare function isDirty(form: Form): boolean;
-/**
- * Get dirty fields -- fields whose current value differs from initialValues.
- * Keys are user-facing dotted paths ('a.b', 'a.0.c'), unlike the JSON array
- * keys stored in the values Map.
- * @param form
- * @return object mapping each dirty field's dotted path to true; the same
- * reference is returned until the dirty set actually changes
- */
-declare function getDirtyFields(form: Form): Record<string, boolean>;
-/**
- * Get touched fields as user-facing dotted paths ('a.b', 'a.0.c'), unlike
- * the JSON array keys stored in the touched Set.
- * @param form
- * @return array of touched fields' dotted paths
- */
-declare function getTouchedFields({ touched }: Form): string[];
-/**
- * Is touched -- any field has been touched
- * @param form
- */
-declare function isTouched({ touched }: Form): boolean;
-/**
- * Remove field
- * @param form
- * @param name
- */
-declare function removeField(form: Form, name: Name): void;
-/**
- * Remove field
- * @param form
- * @param path
- */
-declare function removeFieldByPath(form: Form, path: Path): void;
-/**
- * Set form initialValues
- *
- * Content-based early return: a new reference with equal content (the
- * re-rendered inline literal) is a no-op, so committed edits survive, while
- * genuinely changed content swaps the baseline and re-seeds — live values
- * and tombstones are cleared, touched flags and errors survive.
- * @param form
- * @param initialValues
- */
-declare function setInitialValues(form: Form, initialValues: any): void;
-/** Options accepted by {@link reset}. Every flag defaults to `false` —
- * omitting the object (or any flag) keeps the plain full-reset behavior.
- * Names mirror react-hook-form's reset options to ease migration. */
-interface ResetOptions {
-    /** Keep the current values of fields that are dirty — differ from the
-     * pre-reset initialValues (the same rule {@link getDirtyFields} applies).
-     * Clean fields fall back to the new initialValues as usual. */
-    keepDirtyValues?: boolean;
-    /** Keep the touched set instead of clearing it. */
-    keepTouched?: boolean;
-    /** Keep field errors instead of clearing them. */
-    keepErrors?: boolean;
-    /** Keep the submitted flag (`isSubmitSuccessful`) instead of clearing
-     * it. */
-    keepIsSubmitted?: boolean;
-    /** Keep `submitCount` instead of resetting it to 0. */
-    keepSubmitCount?: boolean;
-    /** Keep `isSubmitting` instead of resetting it to false. */
-    keepIsSubmitting?: boolean;
-}
-/**
- * Reset form
- * @param form
- * @param initialValues
- * @param options keep-flags to preserve slices of state through the reset
- */
-declare function reset(form: Form, initialValues?: any, options?: ResetOptions): void;
-/** Options accepted by {@link resetField}. The flags default to `false`;
- * `value` has no default — omitted, the field falls back to initialValues;
- * provided, the explicit value becomes the live value with no fallback at
- * all. Mirrors react-hook-form's resetField options (`value` plays their
- * `defaultValue`'s role) to ease migration. */
-interface ResetFieldOptions {
-    /** Keep the field's touched flag instead of clearing it. */
-    keepTouched?: boolean;
-    /** Keep the field's errors instead of clearing them. */
-    keepErrors?: boolean;
-    /** Explicit post-reset value for the field — never falls back to
-     * initialValues. */
-    value?: any;
-}
-/**
- * Reset a single field: drop its live value (reads fall back to the
- * baseline — initialValues, or the schema's parsed output when one
- * exists, in which case the path is removed from parsedValues and the
- * initial value pinned back so the field reads initialValues again),
- * clear its touched flag and errors, and revive the path's removal
- * tombstones — the inverse of {@link removeFieldByPath}. Other fields
- * and the submission flags are untouched; see {@link reset} for the
- * form-wide counterpart.
- *
- * @param form
- * @param name
- * @param options
- */
-declare function resetField<T extends Record<string, any> = any, P extends FieldPath<T> | Name = Name>(form: Form<T>, name: P, options?: ResetFieldOptions): void;
-/**
- * @param form
- */
-declare function hasErrors({ errors }: Form): boolean;
-/**
- * Trigger field validation.
- *
- * Without `name` every registered field validator runs. A single `name` —
- * dotted string or segments array — runs only that field's validator, and
- * an array of names runs each one in order. An empty array is a no-op, as
- * is any name with no registered validator. An array argument counts as
- * one segments path only when it mixes in numbers (`['items', 0]`); pure
- * string arrays are name lists, so `['a', 'b']` triggers fields `a` and
- * `b`, not the nested path `a.b`.
- *
- * The returned promise waits for the triggered validation to settle —
- * async validators included — so their errors have already landed in
- * `form.errors` when it resolves. It never rejects: landing errors is the
- * expected outcome here, not a failure. Resolves `true` when the triggered
- * scope is error-free, `false` otherwise. Without `name` the scope is all
- * fields plus the form-level `validate` result (which runs after field
- * validators settle, same pipeline as {@link ensureValidate}); with `name`
- * only those fields' own errors count and form-level `validate` is
- * skipped (RHF semantics).
- *
- * Fire-and-forget callers may ignore the promise: the validator kicks
- * still happen synchronously, matching the pre-promise behavior.
- *
- * @param form
- * @param name field name(s) to trigger, or all fields when omitted
- * @return whether the triggered scope is error-free once validation settles
- */
-declare function trigger(form: Form, name?: Name | Name[]): Promise<boolean>;
-/**
- * Form-level twin of the gated validator kick in `useField`'s onChange:
- * re-run the form-level `validate` after a user change to a field listed
- * in `validateDeps`. Called from the field's own change pipeline (typing
- * and `changeValue` alike — both route through the mounted field's
- * onChange), so programmatic `setValue` writes do not re-run it, exactly
- * like they do not re-run field validators.
- *
- * The gate mirrors the per-field matrix with the *changed field's*
- * effective `mode` (a per-field override governs when its changes may
- * fire validation) and the form-level `reValidateMode` against the last
- * round's error footprint ({@link hasFormValidateErrors} — field
- * validators' errors never arm this kick):
- * - `mode` `'onChange'`/`'all'` — every dep change re-runs;
- * - `mode` `'onTouched'` — dep changes re-run once the field was touched;
- * - otherwise the re-run waits for `reValidateMode: 'onChange'` (the
- *   default) while the last round's error is still live — the
- *   submit-then-fix flow: the mismatch lands on submit, editing the
- *   dependency re-runs the validate and clears it.
- * `reValidateMode: 'onBlur'`/`'onSubmit'` never re-run on a change (a
- * change is not a blur; submit re-runs are the submit pipeline's job).
- *
- * The kick is fire-and-forget: async round rejections are swallowed
- * (nothing in an event handler can await them), while a synchronous
- * throw inside the validate callback propagates to the caller exactly
- * like a field validator's does.
- *
- * A no-op unless the form set `validateDeps` listing `path` — forms
- * without the option pay one property check here.
- */
-declare function revalidateFormOnChange(form: Form, path: Path, mode: ValidationMode): void;
-/** Register one field's validateDeps declaration: `key` re-validates when
- * any path in `depKeys` takes a user change. Idempotent per (key, dep)
- * pair, so StrictMode's double effect is harmless. */
-declare function registerFieldValidateDeps(form: Form, key: string, depKeys: string[]): void;
-/** Drop one field's validateDeps registration ({@link
- * registerFieldValidateDeps}). Entries nobody lists anymore are removed so
- * the registry never outlives its fields. */
-declare function unregisterFieldValidateDeps(form: Form, key: string, depKeys: string[]): void;
-/**
- * Field-level twin of {@link revalidateFormOnChange}: after a user change
- * to `path`, re-run every field validator that declared `path` in its
- * `validateDeps` (useField option). Same channel, same gate: the kick
- * rides the changed field's own onChange pipeline (typing and
- * `changeValue` alike), so programmatic `setValue` writes never fire it —
- * exactly like field validators and the form-level `validateDeps`.
- *
- * The gate mirrors the form-level matrix with the *changed field's*
- * effective `mode` and the form-level `reValidateMode` against each
- * dependent's live error:
- * - `mode` `'onChange'`/`'all'` — every dep change re-runs the dependent;
- * - `mode` `'onTouched'` — once the changed field was touched;
- * - otherwise the re-run waits for `reValidateMode: 'onChange'` (the
- *   default) while the dependent still shows an error — the
- *   submit-then-fix flow: the mismatch lands on submit, editing the
- *   dependency re-validates the dependent and a passing round clears it
- *   (a field validator owns its whole key, so the re-run's result
- *   replaces whatever the previous round wrote — the field-level shape
- *   of the form-level footprint reclaim).
- *
- * The kick is an ordinary validator kick: the dependent's own
- * `validateDebounce` window applies, and a synchronous throw inside its
- * validate propagates to the caller like any field validator's would.
- *
- * A no-op unless some field declared `path` as a dep — forms without any
- * field-level `validateDeps` pay one property check here.
- */
-declare function revalidateDependentsOnChange(form: Form, path: Path, mode: ValidationMode): void;
-/** The Error {@link ensureValidate} rejects with: `message` is the first
- * error's display text ({@link getFirstError}) — the long-standing shape
- * — and `.errors` carries the complete flattened error list ({@link
- * getErrors}: `{path, type, message}` entries, dotted display paths) so
- * catchers can branch on types and locate fields 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>;
-declare function setIsSubmitting(form: Form, value: boolean): void;
-declare function incrementSubmitCount(form: Form): void;
-declare function setSubmitSuccessful(form: Form, value: boolean): void;
-/**
- * Set the form-level disabled flag and emit a payload-less 'disabled'
- * event — subscribed fields (useField and the components built on it)
- * re-render with the merged disabled state: form flag || their own
- * `disabled` option.
- * @param form
- * @param value
- */
-declare function setDisabled(form: Form, value: boolean): void;
-/** Submit callbacks for {@link handleSubmit}. All optional — a missing
- * callback is simply skipped, matching the <Form> component semantics. */
-interface HandleSubmitOptions<T extends Record<string, any> = any> {
-    /** Called after validation passes, before onValidSubmit. */
-    onSubmit?: (values: T, e?: any) => void | Promise<void>;
-    /** Called after validation passes, following a successful onSubmit. */
-    onValidSubmit?: (values: T, e?: any) => void | Promise<void>;
-    /**
-     * Called when validation fails.
-     * @param errors array of {path, type, message} entries in insertion
-     *        order; path is the dotted field path ('a.b', 'list.0'), type is
-     *        the error kind ('custom' for plain string errors, 'native' for
-     *        failed DOM constraint validation), message is the display text
-     * @param values current form values
-     */
-    onInvalidSubmit?: (errors: FieldErrorEntry[], values: T) => void;
-    /**
-     * Focus the first error field after a failed submit. Defaults to true —
-     * only an explicit `false` disables it. When custom validation fails,
-     * a 'focusError' event carrying the first error's path key is emitted
-     * on the form (bound fields such as <Field> subscribe and focus their
-     * input); when native constraint validation fails, the submitted
-     * form's first ':invalid' control is focused directly.
-     */
-    shouldFocusError?: boolean;
-}
-/**
- * Create an async submit handler for `form` — the headless counterpart of
- * the <Form> component's onSubmit wiring.
- *
- * Behavior mirrors <Form> exactly: preventDefault when present, then the
- * submit state machine (isSubmitting/submitCount/isSubmitSuccessful) runs
- * around native constraint validation (via `e.currentTarget.checkValidity`,
- * skipped when the target has no checkValidity — e.g. React Native or
- * toolbar-button submits) and custom validators. Failed validation fires
- * onInvalidSubmit with the flattened error entries; a passing submit runs
- * onSubmit then onValidSubmit. Errors thrown by either are swallowed into
- * isSubmitSuccessful=false rather than rejecting the returned promise.
- * Failed validation also focuses the offending field (see
- * {@link HandleSubmitOptions.shouldFocusError}).
- *
- * @param form form instance
- * @param options submit callbacks
- * @return async event handler, callable without an event object
- */
-declare function handleSubmit<T extends Record<string, any> = any>(form: Form<T>, options?: HandleSubmitOptions<T>): (e?: {
-    preventDefault?: () => void;
-    currentTarget?: any;
-}) => Promise<void>;
-/** Options accepted by {@link setFocus}. All flags default to `false`. */
-interface SetFocusOptions {
-    /** Select the field's text after focusing it. Bound fields call
-     * `select()` on their element; elements without one (custom `as`
-     * components) just focus. */
-    shouldSelect?: boolean;
-}
-/**
- * Programmatically focus a bound field's element (e.g. the <Field>'s
- * input).
- *
- * Rides the same 'focusError' event channel a failed handleSubmit uses to
- * focus the first errored field: the payload is the target's path key,
- * with the focus options as a second, backward-compatible argument (older
- * subscribers declared with a single `key` parameter simply ignore it).
- * Being event-driven, it is a silent no-op when the field is unmounted or
- * nothing subscribes — unknown names never throw.
- *
- * @param form form instance
- * @param name field name (dot path or segments path)
- * @param options focus options
- */
-declare function setFocus(form: Form, name: Name, options?: SetFocusOptions): void;
-
-export { resetField as $, getFieldErrors as A, getFieldErrorsByPath as B, getFieldState as C, getFirstError as D, getTouchedFields as E, getValue as G, getValueByPath as I, getValues as J, handleSubmit as K, hasErrors as L, hasTouched as M, hasTouchedByPath as Q, incrementSubmitCount as T, isDirty as U, isTouched as W, registerFieldValidateDeps as X, removeField as Y, removeFieldByPath as Z, reset as _, revalidateDependentsOnChange as a0, revalidateFormOnChange as a1, seedValueByPath as a2, setDisabled as a3, setError as a4, setErrorByPath as a5, setFocus as a6, setInitialValues as a7, setIsSubmitting as a8, setServerErrors as a9, setSubmitSuccessful as aa, setTouched as ab, setTouchedByPath as ac, setValidatingByPath as ad, setValue as ae, setValueByPath as af, trigger as ag, unregisterFieldValidateDeps as ah, unsetValidatingByPath as ai, validate as aj, VALIDATION_OUTCOME as n, changeValue as q, changeValueByPath as r, clearErrors as s, create as t, emitChangeByPath as u, ensureValidate as v, getDirtyFields as w, getError as x, getErrorByPath as y, getErrors as z };
-export type { Form as F, HandleSubmitOptions as H, Name as N, Options as O, PathValueOf as P, ReValidateMode as R, SetFieldOptions as S, ValidationMode as V, FieldPath as a, FieldError as b, Path as c, FieldErrorEntry as d, FieldState as e, FormValidateFn as f, FormValidateMeta as g, FormValidationError as h, PathValue as i, ResetFieldOptions as j, ResetOptions as k, SetFocusOptions as l, SetServerErrorsOptions as m, ValidateResult as o, ValidationOutcome as p };