react-f0rm 0.2.2 → 0.4.0

package/dist/form-61297bc0.d.ts

@@ -0,0 +1,578 @@
+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.0.b', 'a[b]',
+ * ...), and `PathValue<T, P>` resolves the leaf type a path points at.
+ * The grammar mirrors the paths accepted at runtime by `normalizePath`.
+ */
+/** `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` / `.0` / `[k]` / `[0]`,
+ * optionally followed by deeper continuations into the child node.
+ */
+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}]` | `.${number}${Continue<U, Prev[D]>}` | `[${number}]${Continue<U, Prev[D]>}` : {
+    [K in Extract<keyof T, string>]: `.${K}` | `[${K}]` | `.${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 | `${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>>;
+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>;
+    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;
+    validate?: (values: T) => ValidateResult<T>;
+    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?: (values: T) => ValidateResult<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 still a freshly merged tree per call, with untouched
+ * branches sharing references with the baseline exactly like chained
+ * `set` did -- callers may treat it as their own copy.
+ *
+ * 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}. Every flag
+ * defaults to `false`; omitting the options object entirely keeps the plain
+ * set-value behavior (no validation, no touched marking). */
+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;
+    /** Reserved for a future manual dirty marker. Dirty state is currently
+     * derived from comparing values against initialValues, so this flag is
+     * accepted but does nothing. Defaults to `false`. */
+    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;
+/**
+ * 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;
+/**
+ * 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, { key, value: segments }: Path): void;
+/**
+ * Set form initialValues
+ * @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>;
+/**
+ * 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 { setIsSubmitting as $, clearErrors as A, setTouched as B, setTouchedByPath as C, hasTouched as D, hasTouchedByPath as E, isDirty as G, getDirtyFields as H, getTouchedFields as I, isTouched as J, removeField as K, removeFieldByPath as L, setInitialValues as M, reset as T, resetField as W, hasErrors as X, trigger as Y, ensureValidate as Z, validate as _, incrementSubmitCount as a0, setSubmitSuccessful as a1, setDisabled as a2, handleSubmit as a4, setFocus as a6, create as d, VALIDATION_OUTCOME as g, getValues as j, getValue as k, getValueByPath as l, setValueByPath as m, getError as n, getErrorByPath as o, getFieldErrors as p, getFieldErrorsByPath as q, getErrors as r, setValue as s, getFirstError as t, getFieldState as v, unsetValidatingByPath as w, setValidatingByPath as x, setError as y, setErrorByPath as z };
+export type { FieldPath as F, Name as N, Options as O, PathValueOf as P, ResetOptions as Q, ReValidateMode as R, SetFieldOptions as S, ResetFieldOptions as U, ValidationMode as V, Form as a, HandleSubmitOptions as a3, SetFocusOptions as a5, FieldError as b, Path as c, PathValue as e, FieldErrorEntry as f, ValidationOutcome as h, ValidateResult as i, FieldState as u };