react-f0rm 1.3.0 → 1.5.0

package/dist/index.d.cts

@@ -0,0 +1,1253 @@
+import { a as FieldRules, f as FieldError, F as Form$1, P as Path, A as AnyPath, g as PathValueOf, N as Name, h as ValidationMode, R as RegisterOptions, i as RegisterProps, b as FieldErrorEntry, V as Validator, S as StandardSchemaV1, j as FieldPath, k as FieldErrors, l as FieldErrorsTree, O as Options, m as FormEvents } from './standard-schema-BAaTmAHh.js';
+export { e as ArrayItemOf, D as DottedPath, n as FORM_ERROR, o as FormMessages, p as FormValidateFn, q as FormValidateMeta, r as FormValidateMode, s as FormValidationError, I as InferSchemaValues, t as OpaqueTypes, u as PathSegments, v as PathValue, w as ReValidateMode, x as SetErrorOptions, y as SetFocusOptions, z as SetServerErrorsOptions, B as SyncValidator, T as TriggerOptions, c as VALIDATION_OUTCOME, C as ValidateResult, d as ValidationOutcome, E as ValidatorOutput, G as ValidatorRegistration, H as clearErrors, J as clearServerErrors, K as createForm, L as dottedKeyToFieldPath, M as ensureValidate, Q as fieldPathToDottedKey, U as getError, W as getErrorByPath, X as getErrors, Y as getErrorsRecord, Z as getErrorsTree, _ as getFieldErrors, $ as getFieldErrorsByPath, a0 as getFirstError, a1 as hasErrors, a2 as registerFieldValidateDeps, a3 as registerValidatorByPath, a4 as revalidateDependentsOnChange, a5 as revalidateFormOnChange, a6 as runFormValidate, a7 as setError, a8 as setErrorByPath, a9 as setFocus, aa as setServerErrors, ab as setValidatingByPath, ac as shouldKick, ad as trigger, ae as unregisterFieldValidateDeps, af as unsetValidatingByPath, ag as validate } from './standard-schema-BAaTmAHh.js';
+import { EventEmitter } from '@for-fun/event-emitter';
+export { EventEmitter } from '@for-fun/event-emitter';
+import * as React from 'react';
+import { Context, Provider, ReactNode } from 'react';
+export { a as appendValue, c as appendValueByPath, i as insertValue, d as insertValueByPath, m as moveValue, e as moveValueByPath, p as prependValue, f as prependValueByPath, r as removeValue, g as removeValueByPath, b as replaceValues, h as replaceValuesByPath, s as swapValues, j as swapValuesByPath, u as updateValue, k as updateValueByPath } from './array-Bu7W8BSz.js';
+
+/** Option spellings shared across the field, field-array and validator
+ * hooks — private to the hooks slice, never part of the public facade. */
+type FieldOptionBase = {
+    /** Declarative rules compiled into a sync validator. */
+    rules?: FieldRules;
+    /** Whether unmounting removes the branch; defaults to the form-level
+     * `shouldUnregister` (tombstone). `false` keeps the values. */
+    shouldUnregister?: boolean;
+    /** 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. */
+    asyncAlways?: boolean;
+    /** Validate once on mount (overrides the form-level flag in either
+     * direction). Deferred while async `initialValues` is pending. */
+    validateOnMount?: boolean;
+};
+
+/** Get form values: the values Map layered over parsedValues (when a
+ * schema validation produced them) over initialValues. Merged with
+ * copy-on-write ownership tracking ({@link setOwned}), so untouched
+ * branches share references with the baseline. Memoized per form via a
+ * version-bump/read counter ({@link bumpValuesVersion}): consecutive reads
+ * hand back the same reference; treat it as read-only. parsedValues never
+ * affects dirty state — dirty compares live edits against initialValues. */
+declare function getValues<T extends Record<string, any> = any>(form: Form$1<T>): T;
+/** Get a field's value. */
+declare function getValue<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form$1<T>, name: P): PathValueOf<T, P>;
+/** Get a field's value by path. */
+declare function getValueByPath({ initialValues, parsedValues, values, deleted }: Form$1, path: Path): any;
+/** Options accepted by {@link setValue} / {@link setValueByPath} / {@link
+ * changeValue} / {@link changeValueByPath}. `shouldValidate`/`shouldTouch`
+ * default to `false`. */
+type SetFieldOptions = {
+    /** Run the field's registered validator (if any) after the value lands.
+     * 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: it becomes the field's
+     * dirty-comparison baseline. `true` (or omitting) keeps the default
+     * derived behavior — dirty while the live value differs from
+     * initialValues. */
+    shouldDirty?: boolean;
+};
+/** Set a field's value. `value` may be an updater function receiving the
+ * current value and returning the next (TanStack Form's `setFieldValue`
+ * contract) — so a function can never itself be stored as a value. */
+declare function setValue<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form$1<T>, name: P, value: PathValueOf<T, P> | ((prev: PathValueOf<T, P>) => PathValueOf<T, P>), options?: SetFieldOptions): void;
+/** Set a field's value by path. `value` may be an updater function (see
+ * {@link setValue}). */
+declare function setValueByPath(form: Form$1, path: Path, value: any | ((prev: any) => any), options?: SetFieldOptions): void;
+/** The write of {@link setValueByPath} minus the `'change'` emit: the
+ * render-time `useField` `initialValue` seed. The field's first paint
+ * (SSR included) must already carry the value, so the write happens during
+ * render where emitting is illegal; the field announces it post-commit via
+ * {@link emitChangeByPath}. */
+declare function seedValueByPath(form: Form$1, 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 runs post-commit where emitting is safe. */
+declare function emitChangeByPath({ emitter }: Form$1, path: Path): void;
+/** One field's aggregated state, as {@link getFieldState} returns it.
+ * `errors` is the stored array shared with the form — treat it read-only. */
+type FieldState<T = any> = {
+    value: T;
+    error: FieldError | undefined;
+    errors: FieldError[];
+    isDirty: boolean;
+    isTouched: boolean;
+    isValidating: boolean;
+};
+/** Get one field's aggregated state: layered value, first/every error,
+ * dirtiness, touched flag, and validating flag. `isDirty` applies the same
+ * per-field rule as {@link getDirtyFields}. */
+declare function getFieldState<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form$1<T>, name: P): FieldState<PathValueOf<T, P>>;
+/** Options accepted by {@link removeField}. All flags default to `false` —
+ * the historical remove semantics (value dropped, path tombstoned, dirty
+ * baseline/touched/errors cleared). */
+type RemoveFieldOptions = {
+    /** Keep the field's live value and dirty baseline instead of
+     * tombstoning: reads, `getValues()`, and submit keep the value. */
+    keepValue?: boolean;
+    /** Keep the field's dirty baseline. Implies `keepValue`. */
+    keepDirty?: boolean;
+    /** Keep the field's touched flag instead of clearing it. */
+    keepTouched?: boolean;
+    /** Keep the field's errors instead of clearing them. */
+    keepError?: boolean;
+};
+declare function removeField(form: Form$1, name: Name, options?: RemoveFieldOptions): void;
+/** Remove a field by path; the keep-flags preserve slices of state. */
+declare function removeFieldByPath(form: Form$1, path: Path, options?: RemoveFieldOptions): void;
+/** Set form initialValues. Content-based early return: a new reference with
+ * equal content is a no-op (committed edits survive); genuinely changed
+ * content swaps the baseline and re-seeds — live values and tombstones are
+ * cleared, touched flags and errors survive. */
+declare function setInitialValues(form: Form$1, initialValues: any): void;
+/** Options accepted by {@link reset}. Every flag defaults to `false`. */
+type ResetOptions = {
+    /** Keep the current values of fields that are dirty — differ from the
+     * pre-reset initialValues (the same rule {@link getDirtyFields} applies). */
+    keepDirtyValues?: boolean;
+    /** Keep every field's current live value instead of returning to the
+     * baseline (a superset of `keepDirtyValues`). Dirtiness is recomputed
+     * against the post-reset baseline. */
+    keepValues?: boolean;
+    /** Ignore a newly provided `initialValues` and keep the current baseline. */
+    keepDefaultValues?: boolean;
+    /** Keep the touched set instead of clearing it. */
+    keepTouched?: boolean;
+    /** Keep field errors instead of clearing them. */
+    keepErrors?: boolean;
+    /** Keep the submitted flag (`isSubmitted`) instead of clearing it. */
+    keepIsSubmitted?: boolean;
+    /** Keep the last submit's success flag (`isSubmitSuccessful`). */
+    keepIsSubmitSuccessful?: boolean;
+    /** Keep `submitCount` instead of resetting it to 0. */
+    keepSubmitCount?: boolean;
+    /** Keep `isSubmitting` instead of resetting it to false. */
+    keepIsSubmitting?: boolean;
+};
+/** Reset the form. Omitted (or undefined) `initialValues` keeps the current
+ * baseline — fields simply return to it (react-hook-form's
+ * reset-without-values semantics). */
+declare function reset(form: Form$1, initialValues?: any, options?: ResetOptions): void;
+/** Options accepted by {@link resetField}. Flags default to `false`;
+ * `value` has no default — omitted, the field falls back to initialValues. */
+type 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 — never falls back to initialValues. */
+    value?: any;
+};
+/** Reset a single field: drop its live value (reads fall back to the
+ * baseline), clear touched/errors, and revive the path's tombstones — the
+ * inverse of {@link removeFieldByPath}. Other fields are untouched. */
+declare function resetField<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form$1<T>, name: P, options?: ResetFieldOptions): void;
+
+/** Set a field's touched state. */
+declare function setTouched(form: Form$1, name: Name): void;
+/** Set a field's touched state by path. */
+declare function setTouchedByPath({ emitter, touched }: Form$1, path: Path): void;
+/** Check if a field has been touched. */
+declare function hasTouched<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form$1<T>, name: P): boolean;
+/** Check if a field has been touched by path. */
+declare function hasTouchedByPath({ touched }: Form$1, path: Path): boolean;
+/** Get touched fields as user-facing dotted paths ('a.b', 'a.0.c'). */
+declare function getTouchedFields({ touched }: Form$1): string[];
+/** Is touched — any field has been touched. */
+declare function isTouched({ touched }: Form$1): boolean;
+
+/** Is one field dirty — the per-field rule behind `getFieldState`'s
+ * `isDirty`: a live value exists at the path and differs from the field's
+ * effective baseline (committed `shouldDirty: false` baselines included).
+ * A leaf under a wholesale ancestor write reports clean — dirtiness
+ * belongs to the branch that actually diverged. */
+declare function isFieldDirtyByPath(form: Form$1, path: Path): boolean;
+/** Is dirty — any value differs from initialValues. */
+declare function isDirty(form: Form$1): boolean;
+/** Get dirty fields — fields whose current value differs from
+ * initialValues. Keys are user-facing dotted paths ('a.b', 'a.0.c'); the
+ * same reference is returned until the dirty set actually changes. */
+declare function getDirtyFields(form: Form$1): Record<string, boolean>;
+
+/** Set a field's value as a user change. When a field is mounted on the
+ * path it rides the gated user-change pipeline (the field's effective
+ * `mode` and the form's `reValidateMode` drive validation, as in
+ * {@link userChangeByPath}); with no mounted field it degrades to a plain
+ * {@link setValue}. Contrast {@link setValue}, whose `shouldValidate`
+ * kicks the validator unconditionally. */
+declare function changeValue<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form$1<T>, name: P, value: PathValueOf<T, P>, options?: SetFieldOptions): void;
+/** Set a field's value as a user change, by parsed path. */
+declare function changeValueByPath(form: Form$1, path: Path, value: any, options?: SetFieldOptions): void;
+/** Register a mounted field's `mode` override at `path` for user-change
+ * gating. Returns the registration token for {@link unregisterFieldMode}
+ * plus whether the slot was already occupied — two fields at one path is
+ * almost always a bug (the latest mount's mode governs). */
+declare function registerFieldMode(form: Form$1, path: Path, mode: ValidationMode | undefined): {
+    token: object;
+    displaced: boolean;
+};
+/** Drop a {@link registerFieldMode} registration; only the entry owned by
+ * `token` is removed, so a later mount keeps its slot. */
+declare function unregisterFieldMode(form: Form$1, path: Path, token: object): void;
+/** First key in the mounted-field registry that is a strict descendant of
+ * `ancestor`, in registration order — undefined when none is mounted.
+ * Same descendant rule as `onPathEvent` ('['+','+segment keeps sibling
+ * lookalike keys from matching). */
+declare function firstMountedDescendantKey(form: Form$1, ancestor: Path): string | undefined;
+/** Write a bound field's user change by path: the write plus the
+ * mode/reValidateMode-gated validation pipeline. Reads the effective mode
+ * from the field-mode registry, so a plain write happens when no field is
+ * registered at `path`. Framework adapters forward their change events
+ * here. */
+declare function userChangeByPath(form: Form$1, path: Path, value: any): void;
+/** A bound field's blur: mark the path touched (unconditional), then kick
+ * its validator under the blur-side gate. Framework adapters forward blur
+ * events here. */
+declare function userBlur(form: Form$1, path: Path): void;
+
+/**
+ * Create a non-hook field binding — react-hook-form's `register`
+ * contract, wired onto this library's store: the bound element never
+ * re-renders, every change still lands in the store through the gated
+ * user-change pipeline, and `trigger`/submit/`getValues` read it like
+ * any other field. `useField({uncontrolled: true})` already covers the
+ * hook case; `register` exists for the call sites a hook cannot serve —
+ * dynamic lists, conditional fields, non-React adapters — and for RHF
+ * migration (`{...register('name')}` spreads unchanged).
+ *
+ * Lifecycle rides the returned `ref` callback, exactly like React's own
+ * ref semantics guarantee attach/detach:
+ * - **attach** (element handed over): restore a StrictMode-detached
+ *   snapshot (React 19 detaches refs on the dev remount), seed the
+ *   element's initial DOM content into the store when the path has no
+ *   live value yet (an uncontrolled element's `defaultValue`/`checked`
+ *   is invisible to React state, so the DOM is the source), register the
+ *   field-mode entry (the "mounted field" signal routing `changeValue`
+ *   into the gated pipeline), wire declarative `rules` through
+ *   `registerValidatorByPath`, and subscribe the `'focusError'` channel
+ *   (`setFocus`, failed-submit auto-focus) plus the bulk-reset DOM sync
+ *   (payload-less `'change'` rewrites the element, register-style);
+ * - **detach** (`null`): unregister mode entry and validator, drop the
+ *   subscriptions, and tombstone the path unless
+ *   `shouldUnregister: false` — the library's historical unmount
+ *   default, snapshot/restore-safe under StrictMode.
+ *
+ * Event extraction defaults to the element's own protocol (files →
+ * `target.files`, checkbox → `target.checked`, `valueAsNumber`/
+ * `valueAsDate` under their flags, else `target.value`), overridable
+ * with `eventToValue` — the same extraction `<Field>` performs.
+ *
+ * @param form
+ * @param name path or segment array
+ * @param options {@link RegisterOptions}
+ * @return spreadable props {@link RegisterProps}
+ */
+declare function registerField(form: Form$1, name: Name, options?: RegisterOptions): RegisterProps;
+
+declare function setIsSubmitting(form: Form$1, value: boolean): void;
+declare function incrementSubmitCount(form: Form$1): void;
+declare function setSubmitSuccessful(form: Form$1, value: boolean): void;
+/** Set the form-level disabled flag and emit a payload-less 'disabled'
+ * event — subscribed fields re-render with the merged state (form flag ||
+ * their own `disabled` option). */
+declare function setDisabled(form: Form$1, value: boolean): void;
+/** Set the form's user-owned metadata slot (Formik's `status` role): the
+ * payload-less 'status' event wakes {@link useStatus} and imperative
+ * `subscribe` listeners. Nothing else interprets the value. */
+declare function setStatus(form: Form$1, value: any): void;
+/** A submit callback: the submitted values plus the triggering event. */
+type SubmitCallback<T> = (values: T, e?: any) => void | Promise<void>;
+/** Submit callbacks for {@link handleSubmit}. All optional — a missing
+ * callback is simply skipped, matching the <Form> component semantics. */
+type HandleSubmitOptions<T extends Record<string, any> = any> = {
+    /** Called after validation passes, before onValidSubmit. */
+    onSubmit?: SubmitCallback<T>;
+    /** Called after validation passes, following a successful onSubmit. */
+    onValidSubmit?: SubmitCallback<T>;
+    /** Called when validation fails, with the flattened error entries and
+     * current values. */
+    onInvalidSubmit?: (errors: FieldErrorEntry[], values: T) => void;
+    /** Called after validation passes with the final (schema-coerced)
+     * values — the slot <Form>'s `action` prop uses to dispatch React 19
+     * server actions. May return an {@link ActionErrorResult}: its `errors`
+     * record lands as `type: 'server'` errors and the submit counts
+     * unsuccessful; any other return means success. */
+    onAction?: (values: T, e?: any) => void | Promise<void | ActionErrorResult>;
+    /** Focus the first error field after a failed submit. Defaults to true. */
+    shouldFocusError?: boolean;
+    /** Whether native constraint validation gates this attempt. Defaults to
+     * the form's {@link Form.shouldUseNativeValidation} flag. Targets
+     * without checkValidity never gate. */
+    shouldUseNativeValidation?: boolean;
+};
+/** What a server action / onAction callback returns when the server
+ * rejected the payload: a field-path → message(s) record, landed as
+ * `type: 'server'` errors. Undefined (or anything else) means success. */
+type ActionErrorResult = {
+    errors?: Record<string, string | string[]>;
+};
+/** Create an async submit handler for `form` — the headless counterpart of
+ * the <Form> component's onSubmit wiring. Runs the submit state machine
+ * around native constraint validation (skipped for targets without
+ * checkValidity) and custom validators; failed validation fires
+ * onInvalidSubmit, a passing submit runs onSubmit then onValidSubmit.
+ * Errors thrown by either are swallowed into isSubmitSuccessful=false.
+ * A new attempt while one is in flight is ignored outright (no state
+ * changes at all) — including handleSubmit calls nested inside onSubmit. */
+declare function handleSubmit<T extends Record<string, any> = any>(form: Form$1<T>, options?: HandleSubmitOptions<T>): (e?: {
+    preventDefault?: () => void;
+    currentTarget?: any;
+}) => Promise<void>;
+
+type UseFieldOptions$1<TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>> = {
+    form?: Form$1<TValues>;
+    name: TPath;
+    initialValue?: any;
+    shouldUnregister?: boolean;
+    /**
+     * Field-level validator. The value argument follows the path: with a
+     * typed form the callback receives `PathValueOf<TValues, TPath>` (the
+     * TanStack-parity inference — `name: 'age'` on a `{age: number}` shape
+     * types `value` as `number`), and falls back to `any` for untyped call
+     * sites (segment arrays, dynamic names). The return shape mirrors
+     * {@link Validator} — an error (string / FieldError / mixed array) or
+     * undefined when valid, possibly a Promise for async validation. The
+     * second argument carries the validation context (`meta.signal` aborts
+     * when the round is superseded).
+     */
+    validate?: ((value: PathValueOf<TValues, TPath>, meta: {
+        form: Form$1<TValues>;
+        path: Path;
+        signal: AbortSignal;
+    }) => ReturnType<Validator>) | StandardSchemaV1<PathValueOf<TValues, TPath>>;
+    /**
+     * Declarative rules (required/min/max/minLength/maxLength/pattern),
+     * compiled into a synchronous validator. `required` is special: it runs
+     * immediately on every kick — never debounced — and while it fails,
+     * `validate` is skipped (the expensive check never sees an empty value).
+     * The other rules compose with `validate` — rules run first, then
+     * `validate` (awaited when async), merging both sources' errors with
+     * rules errors ahead. Failures land in the form's error state with the
+     * given or default messages.
+     */
+    rules?: FieldRules;
+    /**
+     * Milliseconds to debounce this field's validation kicks. Defaults to 0
+     * (validate immediately); while the timer is pending the field counts as
+     * validating, so `trigger`/`ensureValidate` wait out the window. Only the
+     * last kick inside the window runs the validator. The `required` rule is
+     * exempt: it runs synchronously on every kick, so a required failure
+     * shows immediately instead of waiting out the window.
+     */
+    validateDebounce?: number;
+    /**
+     * Run this field's debounced validator even when its `required` gate
+     * failed — TanStack Form's `asyncAlways`. The gate's errors land
+     * immediately (never debounced) and the validator's own result lands
+     * alongside them, per-source: a passing async round clears only its
+     * own errors while the gate's verdict stays. Falls back to the
+     * form-level `createForm({asyncAlways})` flag when omitted, so a field
+     * opts out with `asyncAlways: false`. The use case: the cheap format
+     * check fails (gate) but the expensive backend check should still run
+     * ("not in the right shape — and the backend says taken, too").
+     */
+    asyncAlways?: boolean;
+    /**
+     * Milliseconds to delay showing a newly appearing error in the render
+     * layer (`error`/`errorObject`/`errors` stay undefined/empty until the
+     * window passes). The form's error state is never delayed — trigger,
+     * submit and `getError` read it immediately. An error that clears inside
+     * the window never shows; once an error is visible, later changes apply
+     * immediately. Only the none → some transition waits.
+     */
+    delayError?: number;
+    /**
+     * Disable this field: merged into the result's `disabled` as
+     * `form.disabled || own === true || (own !== false && an ancestor
+     * declared disabled)`. `disabled: true` on a parent path disables every
+     * descendant field too (react-hook-form subtree semantics), and a
+     * descendant declares `disabled: false` to opt back out of that
+     * ancestor. The form-level flag (`createForm({disabled})` /
+     * `setDisabled`) cannot be opted out of.
+     */
+    disabled?: boolean;
+    /**
+     * Uncontrolled mode: the field never subscribes to its own value, so
+     * typing re-renders nothing — the store still carries every write
+     * (getValues/submit/validation read it), and errors/touched/disabled/
+     * validating still re-render the field like react-hook-form's
+     * `register`. The result's `value` is the mount-time snapshot (initial
+     * value seed or baseline); it never refreshes, and bulk operations
+     * (reset/setInitialValues) sync the DOM element directly through the
+     * `focusRef`-held element instead of a render — the register-style
+     * contract, RHF's reset clears the input the same way. Attach the
+     * result with `<input defaultValue={field.value} ref={field.focusRef}>`
+     * -style binding (no `value` prop), exactly like <Field uncontrolled />
+     * does. The DOM sync writes the raw stored value (file inputs are
+     * skipped); read live values with useValue/getValues.
+     */
+    uncontrolled?: boolean;
+    /**
+     * Field-level validation mode override: when given, this field validates
+     * on its own schedule instead of `form.mode` — every other field keeps
+     * the form-level timing (e.g. a form that defaults to `'onSubmit'` with
+     * one field declared `'onBlur'` shows that field's error on blur while
+     * the rest wait for submit). `reValidateMode` stays form-level: once any
+     * field has an error (after a failed submit, say), re-validation follows
+     * the form's `reValidateMode` for every field, overriding this one too.
+     * See {@link ValidationMode}.
+     */
+    mode?: ValidationMode;
+    /**
+     * Field paths whose **user changes re-run this field's validator** —
+     * the field-level counterpart of the form-level `validateDeps` option
+     * (cross-field linkage: `password` changed → re-check
+     * `passwordConfirm`). TanStack Form's `onChangeListenTo` / RHF trigger
+     * chains are the ecosystem analogues.
+     *
+     * The re-run rides the changed field's own onChange pipeline, so typing
+     * and `changeValue` both fire it while programmatic `setValue` does
+     * not, and its timing is gated by the same mode matrix as the form
+     * level: the changed field's effective `mode` (per-field override
+     * included) and the form's `reValidateMode` — under the default
+     * `'onSubmit'`/`'onChange'` pair, a dep change re-validates this field
+     * once this field already shows an error (the submit-then-fix flow: the
+     * mismatch lands on submit, editing the password re-checks the confirm
+     * and a passing round clears the error, because a field validator owns
+     * its whole key).
+     *
+     * `validateDebounce` applies to the re-run like to any kick. Declaring
+     * the field's own path is a no-op (its own change already validates it).
+     */
+    validateDeps?: FieldPath<TValues>[];
+    /**
+     * Validate this field once on mount instead of waiting for the first
+     * submit/change — errors show immediately for an untouched field.
+     * Overrides the form-level `createForm({validateOnMount})` flag in
+     * either direction (`false` opts a field out of a validating form).
+     * While an async `initialValues` source is still pending the kick waits
+     * for the resolved baseline; a field unmounted in between never kicks.
+     */
+    validateOnMount?: boolean;
+    /**
+     * DOM event → value extractor for the result's {@link
+     * UseFieldResult.inputProps} binding. Defaults to the element's own
+     * protocol (files → `target.files`, checkbox → `target.checked`,
+     * `valueAsNumber`/`valueAsDate` under their flags, else
+     * `target.value`); a non-DOM event passes through unchanged, so custom
+     * controls can hand raw values. Only consumed by `inputProps` — the
+     * headless `onChange` keeps taking raw values.
+     */
+    eventToValue?: (e: any) => any;
+    /** `inputProps` stores `e.target.valueAsNumber` instead of the string
+     * value (number inputs, RHF's `register({valueAsNumber})`). An
+     * explicit `eventToValue` takes precedence. */
+    valueAsNumber?: boolean;
+    /** `inputProps` stores `e.target.valueAsDate` instead of the string
+     * value (date/time inputs, RHF's `register({valueAsDate})`). An
+     * explicit `eventToValue` takes precedence; combining with
+     * `valueAsNumber` is a TypeError (`valueAsNumber` wins). */
+    valueAsDate?: boolean;
+    /**
+     * Element type hint for {@link UseFieldResult.inputProps} only:
+     * `'checkbox'` renders `checked` instead of `value`, `'file'` renders
+     * neither (file inputs cannot be value-controlled). The extraction
+     * itself already auto-detects both types from the event's target.
+     */
+    type?: string;
+};
+/**
+ * The result of {@link useField}. Deliberately a closed shape: no index
+ * signature, so a typo'd property access (`field.vlaue`) is a type error
+ * instead of silently reading `undefined`.
+ */
+type UseFieldResult<TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>> = {
+    /** The form instance this field is bound to (explicit prop or context) —
+     * handy for consumers that need direct access to the headless API. */
+    form: Form$1<TValues>;
+    value: PathValueOf<TValues, TPath>;
+    /** Error message string (FieldError#message) for display, or undefined */
+    error: string | undefined;
+    /** Full FieldError object ({type, message}), or undefined */
+    errorObject: FieldError | undefined;
+    /** Every error registered for the field, in insertion order — `error`
+     * and `errorObject` are its first entry. Empty (and reference-stable)
+     * when the field has no errors. */
+    errors: FieldError[];
+    /**
+     * Whether the field is dirty: its live value exists and differs from
+     * the field's effective baseline (the same per-field rule
+     * `getFieldState(form, name).isDirty` applies — committed
+     * `shouldDirty: false` baselines included). Live in controlled mode;
+     * pinned at mount in uncontrolled mode (like `value`) so typing never
+     * re-renders the field — {@link useIsFieldDirty} is the live scoped
+     * channel for either mode.
+     */
+    isDirty: boolean;
+    /**
+     * Whether a validator round for this field is currently in flight —
+     * a pending debounce window or an unresolved async validator (the
+     * `getFieldState(form, name).isValidating` reading, made reactive).
+     */
+    validating: boolean;
+    onChange: (v: any) => void;
+    onBlur: () => void;
+    name: string;
+    /** Merged disabled flag: the form-level flag (`createForm({disabled})`
+     * toggled by `setDisabled`) OR-ed with this field's own `disabled`
+     * option, updated live through the form's event core. */
+    disabled: boolean;
+    /**
+     * Callback ref carrying the focus channel: attach it to your input
+     * element (`<input ref={field.focusRef} />`) so `setFocus` and a failed
+     * submit's first-error auto-focus (`shouldFocusError`) can focus this
+     * headless field — the same 'focusError' wiring `<Field>` performs for
+     * its own input. Without it, focus requests aimed at this field are
+     * silent no-ops, matching `setFocus`'s contract: focusing a field
+     * whose element is not bound neither throws nor focuses anything.
+     */
+    focusRef: (el: any) => void;
+    /**
+     * DOM-ready props for an `<input>`: `<input {...field.inputProps} />`
+     * binds the element to the field without hand-wiring value/onChange/
+     * onBlur/ref/a11y. `onChange` takes the DOM event (extraction per
+     * {@link UseFieldOptions}' `eventToValue`/`valueAsNumber`/`valueAsDate`
+     * /`type`), `ref` is the focus channel, `aria-invalid`/`aria-describedby`
+     * complete the {@link errorIdFromKey} chain — render the error element
+     * with `fieldErrorId(name)` to finish it. The headless `value`/
+     * `onChange`/`onBlur`/`focusRef` stay available for custom controls
+     * that hand raw values (design systems) — `inputProps` is the DOM
+     * boundary adapter, never a replacement.
+     */
+    inputProps: UseFieldInputProps;
+};
+/**
+ * The spreadable DOM props {@link UseFieldResult.inputProps} carries:
+ * `name`, `onChange` (event-based), `onBlur`, `ref`, `disabled`, the
+ * error a11y wiring, and exactly one of `value` (controlled),
+ * `defaultValue` (uncontrolled) or `checked` (`type: 'checkbox'`) —
+ * `type: 'file'` carries none. Always spread `inputProps` FIRST, so the
+ * caller's own props (placeholder, className, an explicit `ref` they
+ * merge themselves) win.
+ */
+type UseFieldInputProps = {
+    name: string;
+    value?: any;
+    defaultValue?: any;
+    checked?: boolean;
+    onChange: (e: any) => void;
+    onBlur: () => void;
+    ref: (el: any) => void;
+    disabled: boolean;
+    'aria-invalid'?: boolean;
+    'aria-describedby'?: string;
+};
+declare function useField<TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>>(options: UseFieldOptions$1<TValues, TPath>): UseFieldResult<TValues, TPath>;
+
+type FieldArrayItem<K extends string> = {
+    id: string;
+    index: number;
+} & Record<K, string>;
+/** Options accepted by {@link useFieldArray} and the per-instance hook
+ * returned by `createFormContext()`. */
+type UseFieldArrayOptions<K extends string = 'id'> = Pick<FieldOptionBase, 'rules' | 'shouldUnregister'> & {
+    name: Name;
+    form?: Form$1;
+    /**
+     * Property name the stable row key is exposed under on each `fields`
+     * entry (react-hook-form's `keyName`): defaults to `'id'`, a custom
+     * name (e.g. `'key'`) avoids clashing with a row data field of the
+     * same name. The underlying id is unchanged.
+     */
+    keyName?: K;
+};
+/** Second argument of the row-adding movers: `focus` decides whether the
+ * new row takes focus once it commits — `true` targets its first mounted
+ * child field, a string names the child field. */
+type FieldArrayFocusOptions = {
+    focus?: boolean | string;
+};
+type UseFieldArrayResult<TItem = any, K extends string = 'id'> = {
+    fields: FieldArrayItem<K>[];
+    /** Append one row. With the item type declared —
+     * `useFieldArray<Item>({name: 'items'})` — the value is checked
+     * against the array's element type. */
+    append: (value: TItem, options?: FieldArrayFocusOptions) => void;
+    prepend: (value: TItem, options?: FieldArrayFocusOptions) => void;
+    insert: (index: number, value: TItem, options?: FieldArrayFocusOptions) => void;
+    /** Remove one row, or several in a single write (`remove([0, 2])` —
+     * order-insensitive, duplicates ignored, out-of-range indices are
+     * silent no-ops). */
+    remove: (indices: number | number[]) => void;
+    swap: (from: number, to: number) => void;
+    move: (from: number, to: number) => void;
+    replace: (values: TItem[]) => void;
+    update: (index: number, value: TItem) => void;
+};
+declare function useFieldArray<TItem = any, K extends string = 'id'>(options: UseFieldArrayOptions<K>): UseFieldArrayResult<TItem, K>;
+/**
+ * The result of {@link useFieldArrayItem}. Mirrors the {@link useField}
+ * return shape (`value`/`errors`/`error`) plus the row's `index` and
+ * `name` (path key) so nested fields can build on it —
+ * `useField({name: ['tags', item.index, 'label']})`.
+ */
+type UseFieldArrayItemResult<TValue = any> = {
+    value: TValue;
+    /** Overwrite this row's value in place (same array-layer write as
+     * `update(index, value)`: the row's id and position are kept). */
+    setValue: (value: TValue) => void;
+    /** Every error registered for the row's path, insertion order; the
+     * shared empty constant while clean, so consumers can memo on it. */
+    errors: FieldError[];
+    /** First error's message — the display text — or undefined. */
+    error: string | undefined;
+    /** The row's current path key (JSON-stringified segments, e.g.
+     * `["tags",0]`); moves with the row across reorder/remove. */
+    name: string;
+    /** The row's current position in the array. `-1` while the row is being
+     * removed (or when no useFieldArray is mounted at `name`): reads return
+     * undefined and nothing writes the dangling path. */
+    index: number;
+    form: Form$1;
+};
+/** Options for {@link useFieldArrayItem} and its per-instance core: the
+ * array's `name`, the row's stable `id` (from `fields[i].id`), and an
+ * optional explicit `form`. */
+type UseFieldArrayItemOptions = {
+    name: Name;
+    id: string;
+    form?: Form$1;
+};
+/**
+ * Subscribe to a single row of a {@link useFieldArray} field — the
+ * per-item counterpart `useFieldArray` alone cannot offer. `useFieldArray`
+ * subscribes to the whole branch, so any row's edit re-renders the
+ * component holding the array (and, without memoization, every row);
+ * `useFieldArrayItem` scopes what re-renders to one row identified by its
+ * stable id: editing row K re-renders only row K's component, and a
+ * whole-array rewrite re-renders only rows whose value reference actually
+ * changed. Pair it with a `React.memo` row component that takes stable
+ * props (`form`, `id`) so the array component's own re-render cannot drag
+ * the rows along.
+ *
+ * Rows whose index migrates — remove/move/swap/insert reshuffles —
+ * re-render by design: the row's path contains the index, exactly like
+ * TanStack Form's per-field api. The win is single-row edits staying
+ * single-row.
+ *
+ * Value reads and writes live on the array layer — the same layer every
+ * `useFieldArray` operation touches — so `value`, `setValue` and
+ * `update`/`append`/… always agree with each other.
+ *
+ * @param options `name` of the array (a useFieldArray must be mounted at
+ * the same path — it publishes the id table), the row's `id` from
+ * `fields[i].id`, and optionally an explicit `form`
+ */
+declare function useFieldArrayItem<TValue = any>(options: UseFieldArrayItemOptions): UseFieldArrayItemResult<TValue>;
+
+declare const FormContext: Context<Form$1<any> | null>;
+declare const FormProvider: Provider<Form$1<any> | null>;
+/**
+ * Read the form from the module-level {@link FormContext}; pass the values
+ * shape (`useFormContext<Values>()`) for a typed `Form<Values>`. Use
+ * {@link createFormContext} for multiple forms in one subtree.
+ * @throws when no `<FormProvider>` is mounted above the call site.
+ */
+declare function useFormContext<T extends Record<string, any> = any>(): Form$1<T>;
+/** Options the bundle's pre-bound hooks take: the underlying hook's
+ * options minus `form` — this factory's own context supplies it. For
+ * `useField`, `{name: TPath}` keeps `name` a direct TPath inference site. */
+type BoundFieldOptions<TValues extends Record<string, any>, TPath extends AnyPath<TValues>> = {
+    name: TPath;
+} & Omit<UseFieldOptions$1<TValues, TPath>, 'form'>;
+type BoundFieldArrayOptions<TValues extends Record<string, any>, K extends string = 'id'> = {
+    name: FieldPath<TValues> | Name;
+    keyName?: K;
+    rules?: FieldRules;
+    shouldUnregister?: boolean;
+};
+type BoundFieldArrayItemOptions<TValues extends Record<string, any>> = {
+    name: FieldPath<TValues> | Name;
+    id: string;
+};
+/** The bundle {@link createFormContext} returns: a private React context
+ * plus the hooks pre-bound to it, all typed against `TValues`. */
+type FormContextBundle<TValues extends Record<string, any> = any> = {
+    /** The raw React context, for `<Form context={...}>`: the component
+     * keeps its submit machinery while providing into this instance's
+     * private context. */
+    context: Context<Form$1<TValues> | null>;
+    FormProvider: (props: {
+        form: Form$1<TValues>;
+        children: ReactNode;
+    }) => ReactNode;
+    useFormContext: () => Form$1<TValues>;
+    useField: <TPath extends AnyPath<TValues> = AnyPath<TValues>>(options: BoundFieldOptions<TValues, TPath>) => UseFieldResult<TValues, TPath>;
+    useFieldArray: <TItem = any, K extends string = 'id'>(options: BoundFieldArrayOptions<TValues, K>) => UseFieldArrayResult<TItem, K>;
+    useFieldArrayItem: <TValue = any>(options: BoundFieldArrayItemOptions<TValues>) => UseFieldArrayItemResult<TValue>;
+};
+/**
+ * Create an isolated bundle of form-context bindings: its own React context
+ * plus `useField`/`useFieldArray`/`useFieldArrayItem`/`useFormContext`
+ * hooks resolving from it. One factory per app area scopes a separate
+ * form and fixes the value shape (`Ctx.useField` gets typed `name`/`value`);
+ * `Ctx.context` lets `<Form context={Ctx.context}>` provide into it.
+ */
+declare function createFormContext<TValues extends Record<string, any> = any>(): FormContextBundle<TValues>;
+declare const CheckboxGroupContext: Context<any>;
+declare const CheckboxGroupProvider: Provider<any>;
+declare function useCheckboxGroupContext(): any;
+
+/** Subscription granularity for {@link onPathEvent}: `'leaf'` reads one
+ * key (only writes at it or above matter); `'branch'` aggregates a whole
+ * subtree (descendant writes matter too). */
+type WatchScope = 'leaf' | 'branch';
+/** Events {@link subscribe} can watch. `'errors'`/`'touched'` match exact
+ * keys ({@link onKeyEvent}); `'change'`/`'validating'` match by path
+ * ({@link onPathEvent}); the rest are payload-less broadcasts every
+ * subscriber hears. */
+type SubscribeEvent = 'change' | 'errors' | 'touched' | 'validating' | 'submitting' | 'submitCount' | 'submitSuccessful' | 'disabled' | 'status' | 'loading';
+type SubscribeOptions = {
+    /** Path or paths to watch; omit to receive every emission. A segments
+     * path vs a name list is told apart by `trigger`'s rule: only segments
+     * hold a number. */
+    name?: Name | Name[];
+    /** Event to watch. Defaults to `'change'`. */
+    event?: SubscribeEvent;
+    /** Which writes around `name` are relevant. Only meaningful for the
+     * path-carrying events; defaults to `'branch'` (subscribing to `'tags'`
+     * means the whole branch). */
+    scope?: WatchScope;
+    /** Invoked after each matching emission; read fresh state through the
+     * `get*` readers inside it. */
+    callback: () => void;
+};
+/**
+ * Subscribe to form events imperatively — the non-render counterpart of
+ * the `use*` hooks. Without `name`, `callback` fires on every emission;
+ * with `name`, matching follows the event's shape (`'errors'`/`'touched'`
+ * match exact keys, the rest match by path or broadcast). A name array
+ * builds one subscription per path.
+ */
+declare function subscribe(form: Form$1, options: SubscribeOptions): () => void;
+/** The handle {@link watch} returns: a subscribe/getSnapshot pair any
+ * reactive runtime can bind to. One internal listener stays alive from
+ * creation, so `getSnapshot()` is always fresh; `dispose` ends it. */
+type WatchHandle<T> = {
+    /** Read the current snapshot, cached between events; repeated reads
+     * share one reference until state changes. */
+    getSnapshot: () => T;
+    /** Register a change listener; fires only when the projection changed.
+     * With `isEqual`, an equal verdict skips the callback; without one,
+     * every event wakes it. */
+    subscribe: (invalidate: () => void) => () => void;
+    /** Remove the internal listener and every consumer callback; the handle
+     * is dead afterwards. */
+    dispose: () => void;
+};
+/**
+ * Watch a projection of form state without React — the framework-free
+ * {@link useWatch} (same `isEqual` bailout), tree-shaken when unused.
+ * Returns a {@link WatchHandle}: read `getSnapshot()`, re-read/re-render
+ * when `subscribe`'s listener fires. The handle subscribes eagerly, so
+ * reads are never stale; `getter`/`isEqual` are captured at creation.
+ */
+declare function watch<T>(form: Form$1, event: SubscribeEvent, getter: () => T, isEqual?: (prev: T, next: T) => boolean): WatchHandle<T>;
+
+/**
+ * Create a form instance bound to this component.
+ *
+ * Beyond {@link Options}, the optional `values` object enables controlled
+ * usage: when it genuinely changes it is re-synced into the form with
+ * setInitialValues semantics -- uncommitted user edits are discarded
+ * (master-detail semantics: selecting another record replaces the draft),
+ * while touched flags and errors survive. Change detection is
+ * reference-first with a structural fallback, so re-renders that pass an
+ * inline literal with equal content never re-sync -- the user's
+ * in-progress typing is never clobbered. Passing `resetOptions` reroutes
+ * those changed-content syncs through {@link reset} instead, so its keep*
+ * flags govern what survives (`keepDirtyValues: true` keeps the user's
+ * uncommitted edits on dirty fields); the reference/structural guard
+ * applies to both routes.
+ */
+declare function useForm<T extends Record<string, any> = any>(options?: Options<T> & {
+    values?: T;
+    resetOptions?: ResetOptions;
+}): Form$1<T>;
+/** Snapshot equality comparator — the `isEqual` contract {@link
+ * useWatchCore} documents. */
+type SnapshotComparator<T> = (prev: T, next: T) => boolean;
+/**
+ * Shared core of {@link useWatch} and the path-scoped hooks: a
+ * useSyncExternalStore binding over a custom event subscription.
+ * `subscribeFactory` receives the invalidate callback (drop the snapshot
+ * cache, then notify React) and returns its unsubscribe function, so the
+ * core stays identical whether the subscription is global or scoped to
+ * one path.
+ *
+ * The optional `isEqual` comparator redirects `invalidate`: instead of
+ * dropping the cache and waking React unconditionally, an event first
+ * recomputes the getter and asks `isEqual` whether anything observable
+ * changed — an equal verdict keeps the cached snapshot and skips the
+ * notify entirely (no render at all), an unequal one stores the fresh
+ * snapshot and notifies. Omitted, the historical drop-and-notify pipeline
+ * runs byte-for-byte unchanged.
+ */
+declare function useWatchCore<T>(subscribeFactory: (invalidate: () => void) => () => void, getter: () => T, isEqual?: SnapshotComparator<T>): T;
+/**
+ * Subscribe to a form event and keep the component's snapshot of `getter()`
+ * in sync with the form state.
+ *
+ * Built on useSyncExternalStore, so snapshots taken while React renders are
+ * guaranteed consistent (no tearing under concurrent rendering) and changes
+ * emitted before the subscription effect runs are still picked up.
+ *
+ * The first argument is the form for the unified `fn(form, ...)` context
+ * shape every hook shares; the raw emitter form remains accepted for
+ * back-compat and for subscription sources that are not a full form.
+ *
+ * Framework-free counterpart: {@link watch} — the same event/getter/
+ * `isEqual` contract exposed as a named export returning a
+ * subscribe/getSnapshot handle any reactive runtime can bind to
+ * (useWatch is its React binding; the ref-based cache here keeps inline
+ * getters from re-subscribing per render).
+ *
+ * By default the re-render surface is the event's own scope: every emit
+ * the subscription hears drops the snapshot cache and wakes React, which
+ * then bails out when the recomputed snapshot is reference-identical
+ * (Object.is) — the path/leaf scoping every built-in reader relies on.
+ * The optional `isEqual` comparator exists for wide-scope getters that
+ * return a fresh reference per call (a whole-values selector, say): each
+ * event recomputes the getter and asks `isEqual` whether the result is
+ * observably the same, and an equal verdict skips notifying React
+ * altogether — no render, not even a bailed-out one. An unequal verdict
+ * stores the new snapshot and re-renders. Same contract as TanStack's
+ * `useSelector` compare. Omitted, behavior is unchanged.
+ */
+declare function useWatch<T>(formOrEmitter: Form$1 | EventEmitter<FormEvents>, event: SubscribeEvent, getter: () => T, isEqual?: SnapshotComparator<T>): T;
+/** Options for {@link useValue} and {@link useValueByPath}. */
+type UseValueOptions<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>> = {
+    /** Value to return while the field reads undefined — react-hook-form's
+     * `useWatch` `defaultValue`: an untouched, never-seeded field reads
+     * this instead of `undefined`. */
+    defaultValue?: PathValueOf<T, P>;
+    /** Watch descendants too (react-hook-form's `exact: false`): a write
+     * to `a.b` invalidates a `useValue(form, 'a')` read, and the read
+     * resolves the merged subtree (the copy-on-write `getValues` tree) so
+     * descendant edits show up in the result. Defaults to true — the leaf
+     * scope, where only the exact key and its ancestors invalidate (the
+     * long-standing behavior). */
+    exact?: boolean;
+};
+/**
+ * Get field value state
+ */
+declare function useValue<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form$1<T>, name: P, options?: UseValueOptions<T, P>): PathValueOf<T, P>;
+/**
+ * Get field value state by path
+ */
+declare function useValueByPath(form: Form$1, path: Path, options?: {
+    defaultValue?: any;
+    exact?: boolean;
+}): any;
+/**
+ * Subscribe to the whole values tree: re-renders the calling component
+ * whenever any 'change' event lands — react-hook-form's `watch()` with no
+ * arguments. The snapshot is the memoized `getValues(form)` result, so
+ * repeated reads during one render share one reference and, under
+ * `__DEV__`, one frozen copy.
+ *
+ * Broad scope by design: read it in components that must stay cheap and
+ * need the full tree; per-field readers should reach for {@link useValue}
+ * instead so a keystroke re-renders exactly the affected field.
+ */
+declare function useValues<T extends Record<string, any> = any>(form: Form$1<T>): T;
+/**
+ * Get field touched state
+ */
+declare function useTouched<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form$1<T>, name: P): boolean;
+/**
+ * Get field touched state by path
+ */
+declare function useTouchedByPath(form: Form$1, path: Path): boolean;
+/**
+ * Get field error message state
+ * @return current error's message string (display text), or undefined
+ */
+declare function useError<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form$1<T>, name: P): string | undefined;
+/**
+ * Get field error state by path
+ * @return current FieldError object ({type, message}), or undefined
+ */
+declare function useErrorByPath(form: Form$1, path: Path): FieldError | undefined;
+/**
+ * Get all field errors
+ * @return every error registered for the field (insertion order); an empty
+ *         array when the field has none
+ */
+declare function useFieldErrors<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form$1<T>, name: P): FieldError[];
+/**
+ * Get all field errors by path
+ * @return every error registered for the field (insertion order); an empty
+ *         array when the field has none
+ */
+declare function useFieldErrorsByPath(form: Form$1, path: Path): FieldError[];
+declare function useIsDirty(form: Form$1): boolean;
+/**
+ * Get whether one field is dirty: its live value exists and differs from
+ * the field's effective baseline — the same per-field rule
+ * `getFieldState(form, name).isDirty` applies (committed
+ * `shouldDirty: false` baselines included). Subscribes to 'change' at
+ * leaf scope like {@link useValue}: own-key and ancestor writes re-check
+ * the flag, payload-less broadcasts (reset, setInitialValues) always
+ * sync, and writes elsewhere never re-render it.
+ */
+declare function useIsFieldDirty<T extends Record<string, any> = any, P extends AnyPath<T> = AnyPath<T>>(form: Form$1<T>, name: P): boolean;
+/**
+ * Get whether one field is dirty, by parsed path. See {@link
+ * useIsFieldDirty}.
+ */
+declare function useIsFieldDirtyByPath(form: Form$1, path: Path): boolean;
+/**
+ * Get dirty fields state -- object mapping each dirty field's user-facing
+ * dotted path ('a.b', 'a.0.c') to true; recalculated after 'change' events
+ */
+declare function useDirtyFields(form: Form$1): Record<string, boolean>;
+/**
+ * Get touched fields state -- array of touched fields' user-facing dotted
+ * paths ('a.b', 'a.0.c'); recalculated after 'touched' events
+ */
+declare function useTouchedFields(form: Form$1): string[];
+/**
+ * Aggregate snapshot of the whole form's state flags — the one-subscription
+ * counterpart of react-hook-form's `formState` object (no errors object;
+ * per-field error state stays with `useError`/`useFieldErrors`, and
+ * `hasErrors`/`isValid` cover the whole-form questions).
+ *
+ * Recomputed on every state-bearing event; the field-wise comparator keeps
+ * the returned reference stable while nothing observably changed, so
+ * `useFormState(form).isDirty` re-renders no more often than the dedicated
+ * {@link useIsDirty}. Cheaper than calling the granular hooks one by one
+ * (one subscription and one snapshot instead of one per flag).
+ */
+type FormState<T extends Record<string, any> = any> = {
+    /** Any live value differs from its baseline (see {@link isDirty}). */
+    isDirty: boolean;
+    /** Dirty fields keyed by user-facing dotted path ('a.b', 'a.0.c'). */
+    dirtyFields: Record<string, boolean>;
+    /** At least one field is touched. */
+    isTouched: boolean;
+    /** Touched fields' user-facing dotted paths. */
+    touchedFields: string[];
+    /** Any error registered (field or form level). */
+    hasErrors: boolean;
+    /** No errors are registered — react-hook-form's `isValid` semantics.
+     * In-flight validation is NOT factored in ({@link isValidating} is the
+     * separate signal; async rounds temporarily pass this flag like RHF's). */
+    isValid: boolean;
+    /** Every error as one record keyed by user-facing dotted path
+     * ('a.b', 'list.0') — react-hook-form's `formState.errors` shape,
+     * typed as {@link FieldErrors} (per-key values optional). Memoized
+     * (see {@link getErrorsRecord}): the reference is stable between error
+     * writes, so the snapshot comparator can bail on it. */
+    errors: FieldErrors<T>;
+    isSubmitting: boolean;
+    /**
+     * Whether a submit has been attempted on this form — set on the first
+     * `handleSubmit` call (validation outcome aside) and cleared by
+     * `reset`, react-hook-form's `formState.isSubmitted` semantics. Read
+     * after a failed submit to render a "fix the errors below" panel.
+     */
+    isSubmitted: boolean;
+    /** Any validation round is running (field, form-level, or a pending
+     * debounce window). */
+    isValidating: boolean;
+    isSubmitSuccessful: boolean | undefined;
+    submitCount: number;
+    /** Async initialValues still pending ({@link Form.isLoading}). */
+    isLoading: boolean;
+    /** The form-level disabled flag (fields OR their own `disabled`). */
+    disabled: boolean;
+};
+declare function useFormState<T extends Record<string, any> = any>(form: Form$1<T>): FormState<T>;
+/**
+ * The official selector primitive — TanStack Form's
+ * `useStore(store, selector)` counterpart. Subscribes to every
+ * state-bearing form event and keeps `selector()`'s result as the
+ * snapshot; the selector itself is a plain closure (read the form through
+ * any getter — `getValue`, `getValues`, `form.errors.size`, …).
+ *
+ * Without `isEqual` the subscription is object-identity based: each event
+ * recomputes the selector and React bails out when the result is
+ * reference-identical (the contract every `useWatch` reader relies on).
+ * The optional `isEqual(prev, next)` comparator is for wide-scope
+ * selectors that return a fresh reference per call (a whole-values
+ * projection, say): an equal verdict skips notifying React altogether —
+ * no render, not even a bailed-out one (TanStack `useSelector` compare
+ * contract).
+ *
+ * `useFormState` is the built-in aggregate selector; {@link useWatch} is
+ * the single-event version. Reach for `useStore` when the projection is
+ * yours and spans state events — e.g. `form.validating.size > 0 &&
+ * form.isSubmitting` as one flag.
+ */
+declare function useStore<T>(form: Form$1, selector: () => T, isEqual?: SnapshotComparator<T>): T;
+declare function useHasErrors(form: Form$1): boolean;
+/**
+ * Get every error as one record keyed by user-facing dotted path
+ * ('a.b', 'list.0') — react-hook-form's `formState.errors` shape, for
+ * error-summary panels and a11y announcements. Values are the stored
+ * FieldError[] arrays shared with the form (treat as read-only). The
+ * record is memoized per form (see {@link getErrorsRecord}): the hook
+ * re-renders only when an error write actually changed the record's
+ * content.
+ */
+declare function useErrors<T extends Record<string, any> = any>(form: Form$1<T>): FieldErrors<T>;
+/**
+ * Get every error as one nested object following the values tree
+ * (`errors.items?.[0]?.name` reads) — the typed optional-chaining
+ * counterpart of {@link useErrors}' flat dotted record. Leaves hold the
+ * stored FieldError[] arrays shared with the form (treat as read-only).
+ * Memoized alongside the record (see {@link getErrorsTree}): the hook
+ * re-renders only when an error write actually changed the tree's
+ * content.
+ */
+declare function useErrorsTree<T extends Record<string, any> = any>(form: Form$1<T>): FieldErrorsTree<T>;
+/**
+ * Get whether the form currently has no errors — react-hook-form's
+ * `formState.isValid` counterpart. Subscribes to the `'errors'` event only;
+ * in-flight validation does not flip it (see {@link useIsValidating}).
+ */
+declare function useIsValid(form: Form$1): boolean;
+declare function useIsSubmitting(form: Form$1): boolean;
+/**
+ * Get whether an async {@link Options.initialValues} source is still
+ * pending — the flag a loading skeleton or a disabled submit button gates
+ * on until the resolved baseline lands. Subscribes to the 'loading' event
+ * the core emits around the resolution cycle.
+ */
+declare function useIsLoading(form: Form$1): boolean;
+/**
+ * Get the form's user-owned metadata slot reactively (Formik's `status`
+ * counterpart): any value the app stores through {@link setStatus} —
+ * server session flags, wizard step state, non-field errors. Subscribes
+ * to the payload-less 'status' event, so unrelated events never re-render
+ * the caller, and the returned reference is stable between writes that
+ * store an equal value (useSyncExternalStore's Object.is bailout).
+ */
+declare function useStatus<T = any>(form: Form$1): T;
+/**
+ * Get whether the form accepts a submit right now:
+ * `!isSubmitting && !hasErrors`. This is the single flag a submit
+ * button's `disabled` prop wants — it is `false` for the whole async
+ * `onSubmit` span (not just the validation pass) and whenever any field
+ * holds an error (client validation or server backfill), replacing the
+ * hand-rolled `useHasErrors(form) || useIsSubmitting(form)` pair.
+ * Deliberately no dirty or validating semantics: an untouched-but-clean
+ * form can submit.
+ */
+declare function useCanSubmit(form: Form$1): boolean;
+declare function useSubmitCount(form: Form$1): number;
+/**
+ * Get whether any validation round is currently running: a field
+ * validator's pending `validateDebounce` window, an async field validator
+ * still in flight, or the form-level validate's debounce window / in-flight
+ * round — every one of them holds a key in `form.validating`, and the
+ * 'validating' events they emit (field rounds with a path payload, the
+ * form-level round as a payload-less broadcast) are what this subscribes
+ * to. The boolean snapshot is Object.is-stable, so churn among the marks
+ * (a second field opening while the first settles) costs no render while
+ * the flag holds. This is the flag a submit button disables itself on, or
+ * spins a spinner with, through the pre-submit validation pass — it flips
+ * true the moment the first round opens and back false when the last one
+ * settles.
+ */
+declare function useIsValidating(form: Form$1): boolean;
+/**
+ * Get whether the last submit succeeded: `true` once a submit's validation
+ * and `onSubmit` completed without throwing, `false` after a failed submit
+ * (validation rejection or a thrown callback) and before any submit ran —
+ * the falsy reading of the undefined initial/reset state. Subscribes to
+ * the 'submitSuccessful' event the core's setSubmitSuccessful emits, so
+ * the flag flips in the same tick the outcome lands: the usual consumers
+ * are a success banner and a redirect-on-success effect.
+ */
+declare function useIsSubmitSuccessful(form: Form$1): boolean;
+/**
+ * Get the form-level error message: the first error stored under the
+ * reserved {@link FORM_ERROR} key, as display text — or undefined while
+ * the slot is clean. That key is where a form-level `validate` record's
+ * `_form` entry lands and where the Standard Schema adapter drops
+ * path-less issues, so errors that belong to no single field still have a
+ * reader. The classic usage renders it once above the submit button —
+ * `useFormError(form) || null` — and the imperative twin is
+ * `getError(form, FORM_ERROR)`.
+ */
+declare function useFormError(form: Form$1): string | undefined;
+/**
+ * Get every form-level error: all errors stored under the reserved
+ * {@link FORM_ERROR} key (insertion order), an empty array when the slot
+ * is clean. The plural twin of {@link useFormError} for forms that stack
+ * several form-level issues — each path-less Standard Schema issue lands
+ * in this slot. The array reference is stable between unrelated events
+ * (the stored array or a shared empty constant), so consumers can memo on
+ * it; the imperative counterpart is `getFieldErrors(form, FORM_ERROR)`.
+ */
+declare function useFormErrors(form: Form$1): FieldError[];
+
+type UseTransformOptions<TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>, TDisplay = PathValueOf<TValues, TPath>> = {
+    /** Map the stored (raw) value to the display value (read direction);
+     * omitted = identity. */
+    toDisplay?: (raw: PathValueOf<TValues, TPath>) => TDisplay;
+    /** Map a display value back to the raw value (write direction);
+     * omitted = identity. May return a Promise — only the latest write
+     * commits (stale resolutions drop). The round trip should be an
+     * identity; non-invertible store values must be handled by
+     * `toDisplay`, which runs first. */
+    fromDisplay?: (display: TDisplay) => PathValueOf<TValues, TPath> | Promise<PathValueOf<TValues, TPath>>;
+    /** Debounce the display→raw commit; only the last write in the window
+     * commits (TanStack `asyncDebounceMs`). `0`/omitted commits
+     * immediately; validation fires at commit time through the
+     * user-change pipeline. */
+    asyncDebounceMs?: number;
+};
+/**
+ * Bind a control whose display value differs from the stored raw value
+ * (TanStack `useTransform`): `toDisplay` maps store→display,
+ * `fromDisplay` maps display→store. The store always carries the raw
+ * value. `value` subscribes to 'change' at leaf scope; `onChange` writes
+ * through the user-change channel, so mode-gated validation fires as if
+ * the user typed. Transform functions are read fresh each render.
+ */
+declare function useTransform<TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>, TDisplay = PathValueOf<TValues, TPath>>(form: Form$1<TValues>, name: TPath, options?: UseTransformOptions<TValues, TPath, TDisplay>): {
+    value: TDisplay;
+    onChange: (display: TDisplay) => void;
+};
+
+/** Props for <Form>. Native constraint validation gates submission: the
+ * form always sets noValidate, but checkValidity() runs before custom
+ * validators and a failure stops submission (onInvalidSubmit fires).
+ * `shouldUseNativeValidation={false}` skips the gate (targets without
+ * checkValidity are always exempt). The flow itself lives in the headless
+ * `handleSubmit`; this is a thin wrapper binding it to the <form>. */
+type FormProps<T extends Record<string, any> = any> = Omit<React.FormHTMLAttributes<HTMLFormElement>, 'onSubmit'> & {
+    form?: Form$1<T>;
+    /** Isolated context from `createFormContext()`: its bound hooks see this
+     * form, the module-level ones do not. Defaults to FormContext. */
+    context?: React.Context<Form$1<any> | null>;
+    /** Values baseline — sync object, Promise, or thunk; async sources gate on `isLoading`. */
+    initialValues?: T | Promise<T> | (() => T | Promise<T>);
+    /** Default unmount behavior: `true` tombstones unmounted fields, `false` keeps values. */
+    shouldUnregister?: boolean;
+    /** Validate on mount: each validator kicks once; a field's own prop overrides. */
+    validateOnMount?: boolean;
+    /** Disable every bound field (fields OR with their own option); undefined leaves the flag untouched. */
+    disabled?: boolean;
+    /** Form-level default for `asyncAlways`; a field's own prop overrides. */
+    asyncAlways?: boolean;
+    /** Controlled external values: a new reference syncs via setInitialValues
+     * (draft discarded, touched/errors kept); same reference never clobbers. */
+    values?: T;
+    /** May be async; `isSubmitting` covers the flight. */
+    onSubmit?: (values: T, e: React.FormEvent) => void | Promise<void>;
+    /** May be async, same as onSubmit. */
+    onValidSubmit?: (values: T, e: React.FormEvent) => void | Promise<void>;
+    /** Server Action target: after validation, schema-coerced values become
+     * FormData and dispatch here. Returning {@link ActionErrorResult} lands
+     * `type: 'server'` per-field errors (unsuccessful submit); a URL string
+     * renders the native `action` for no-JS progressive enhancement. */
+    action?: string | ((formData: FormData) => void | Promise<void | ActionErrorResult>);
+    /** Called when validation fails; errors are {path, type, message} entries
+     * (type: 'custom' | 'native'). */
+    onInvalidSubmit?: (errors: {
+        path: string;
+        type: string;
+        message: string;
+    }[], values: T) => void;
+    /** Focus the first errored field (or first ':invalid' control) after a failed submit. Default true. */
+    shouldFocusError?: boolean;
+    /** Whether native constraint validation gates submission (pass false for
+     * custom-validator-only forms). Seeds the created form's flag and this
+     * form's submit wiring. */
+    shouldUseNativeValidation?: boolean;
+};
+declare function Form<T extends Record<string, any> = any>({ form: f1, context, initialValues, values, shouldUnregister, validateOnMount, disabled, asyncAlways, onSubmit, onValidSubmit, onInvalidSubmit, action, shouldFocusError, shouldUseNativeValidation, ...props }: FormProps<T>): React.JSX.Element;
+
+/** Every {@link UseFieldOptions} option plus a render-prop `children`
+ * receiving the bound field result. */
+type FormFieldProps<TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>> = UseFieldOptions$1<TValues, TPath> & {
+    children: (field: UseFieldResult<TValues, TPath>) => React.ReactNode;
+};
+/** Headless field via a render prop — the non-hook {@link useField} for
+ * class components/callback consumers. The child receives the full
+ * {@link UseFieldResult}; resolves its form from FormContext or the
+ * `form` option. */
+declare function FormField<TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>>({ children, ...options }: FormFieldProps<TValues, TPath>): React.ReactNode;
+
+/** The error-message element id a field's `aria-describedby` points at
+ * (same id `<Field>`'s renderError span carries). A custom error
+ * component completes the accessible-name chain with
+ * `<span id={fieldErrorId(name)} role="alert">`. */
+declare function fieldErrorId(name: Name): string;
+
+/** Props shared by Field/Checkbox/Select: the hook options minus the
+ * required `name` (the components type it optional) and `validateDeps`
+ * (the components do not forward it), plus the index signature that lets
+ * DOM props flow through. */
+type UseFieldOptions<TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>> = Omit<UseFieldOptions$1<TValues, TPath>, 'name' | 'validateDeps'> & {
+    name?: TPath;
+    [key: string]: any;
+};
+type FieldProps<TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>> = UseFieldOptions<TValues, TPath> & {
+    as?: React.ComponentType<any>;
+    asProps?: Record<string, any>;
+    valueToProps?: (value: any) => Record<string, any>;
+    /** Error renderer: renders `<span id role="alert">` beside the input;
+     * `aria-describedby` always points at that id (`fieldErrorId`). */
+    renderError?: (error: string, id: string) => React.ReactNode;
+};
+/** Callable shape of {@link Field}; a named interface because the inline
+ * `as <TValues,...>() => ...` form trips no-use-before-define. */
+type FieldComponent = {
+    <TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>>(props: FieldProps<TValues, TPath> & React.RefAttributes<HTMLInputElement>): React.ReactElement | null;
+};
+declare const Field: FieldComponent;
+/** Callable shape of {@link Checkbox}: same form-typed `validate` contract
+ * as {@link FieldComponent}. */
+type CheckboxComponent = {
+    <TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>>(props: UseFieldOptions<TValues, TPath> & React.RefAttributes<HTMLInputElement>): React.ReactElement | null;
+};
+declare const Checkbox: CheckboxComponent;
+type SelectProps<TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>> = UseFieldOptions<TValues, TPath> & {
+    multiple?: boolean;
+    children?: React.ReactNode;
+};
+/** Callable shape of {@link Select}: same form-typed `validate` contract
+ * as {@link FieldComponent}. */
+type SelectComponent = {
+    <TValues extends Record<string, any> = any, TPath extends AnyPath<TValues> = AnyPath<TValues>>(props: SelectProps<TValues, TPath> & React.RefAttributes<HTMLSelectElement>): React.ReactElement | null;
+};
+declare const Select: SelectComponent;
+
+/** Props for <ErrorSummary>: same form/context resolution <Form> itself
+ * uses — an explicit `form` wins, otherwise the (optionally isolated)
+ * context form. */
+type ErrorSummaryProps<T extends Record<string, any> = any> = {
+    form?: Form$1<T>;
+    context?: React.Context<Form$1<any> | null>;
+    heading?: string;
+};
+/** A GOV.UK-style error summary: one `role='alert'` box listing every
+ * field error, each linking to the field's error element id. Clicking a
+ * link focuses the field through the same `focusError` channel a failed
+ * submit uses; after a failed submit the box itself takes focus (pair it
+ * with `shouldFocusError={false}`, whose field focus lands later and
+ * would otherwise win). {@link FORM_ERROR} entries have no field to focus
+ * and render as plain list items. */
+declare function ErrorSummary<T extends Record<string, any> = any>({ form: formProp, context, heading }: ErrorSummaryProps<T>): React.ReactElement | null;
+
+export { AnyPath, Checkbox, CheckboxGroupContext, CheckboxGroupProvider, ErrorSummary, Field, FieldError, FieldErrorEntry, FieldErrors, FieldErrorsTree, FieldPath, FieldRules, Form, FormContext, FormEvents, FormField, Form$1 as FormInstance, FormProvider, Name, Options, Path, PathValueOf, RegisterOptions, RegisterProps, Select, StandardSchemaV1, ValidationMode, Validator, changeValue, changeValueByPath, createFormContext, emitChangeByPath, fieldErrorId, firstMountedDescendantKey, getDirtyFields, getFieldState, getTouchedFields, getValue, getValueByPath, getValues, handleSubmit, hasTouched, hasTouchedByPath, incrementSubmitCount, isDirty, isFieldDirtyByPath, isTouched, registerField, registerFieldMode, removeField, removeFieldByPath, reset, resetField, seedValueByPath, setDisabled, setInitialValues, setIsSubmitting, setStatus, setSubmitSuccessful, setTouched, setTouchedByPath, setValue, setValueByPath, subscribe, unregisterFieldMode, useCanSubmit, useCheckboxGroupContext, useDirtyFields, useError, useErrorByPath, useErrors, useErrorsTree, useField, useFieldArray, useFieldArrayItem, useFieldErrors, useFieldErrorsByPath, useForm, useFormContext, useFormError, useFormErrors, useFormState, useHasErrors, useIsDirty, useIsFieldDirty, useIsFieldDirtyByPath, useIsLoading, useIsSubmitSuccessful, useIsSubmitting, useIsValid, useIsValidating, useStatus, useStore, useSubmitCount, useTouched, useTouchedByPath, useTouchedFields, useTransform, useValue, useValueByPath, useValues, useWatch, useWatchCore, userBlur, userChangeByPath, watch };
+export type { ActionErrorResult, FieldArrayFocusOptions, FieldState, FormContextBundle, FormState, HandleSubmitOptions, RemoveFieldOptions, ResetFieldOptions, ResetOptions, SetFieldOptions, SubscribeEvent, SubscribeOptions, UseTransformOptions, UseValueOptions, WatchHandle, WatchScope };