react-f0rm 1.2.0 → 1.3.0

package/dist/index.d.ts

@@ -1,10 +1,11 @@
-import { a as FieldError, F as Form$1, P as Path, b as FieldPath, c as PathSegments, d as PathValueOf, N as Name, V as ValidationMode, e as FieldErrorEntry, O as Options, f as FormEvents } from './form-CvmWHUrd.js';
-export { g as FORM_ERROR, h as FormValidateFn, i as FormValidateMeta, j as PathValue, R as ReValidateMode, S as SetFocusOptions, k as SetServerErrorsOptions, l as VALIDATION_OUTCOME, m as ValidateResult, n as ValidationOutcome, o as clearErrors, p as createForm, q as getError, r as getErrorByPath, s as getErrors, t as getFieldErrors, u as getFieldErrorsByPath, v as getFirstError, w as hasErrors, x as setError, y as setErrorByPath, z as setFocus, A as setServerErrors } from './form-CvmWHUrd.js';
+import { a as FieldError, F as Form$1, P as Path, b as FieldPath, c as PathSegments, d as PathValueOf, N as Name, V as ValidationMode, e as FieldErrorEntry, O as Options, f as FormEvents } from './form-CeKSBs31.js';
+export { g as FORM_ERROR, h as FormValidateFn, i as FormValidateMeta, j as PathValue, R as ReValidateMode, S as SetErrorOptions, k as SetFocusOptions, l as SetServerErrorsOptions, m as VALIDATION_OUTCOME, n as ValidateResult, o as ValidationOutcome, p as clearErrors, q as createForm, r as getError, s as getErrorByPath, t as getErrors, u as getFieldErrors, v as getFieldErrorsByPath, w as getFirstError, x as hasErrors, y as setError, z as setErrorByPath, A as setFocus, B as setServerErrors } from './form-CeKSBs31.js';
+import { EventEmitter } from '@for-fun/event-emitter';
+export { EventEmitter } from '@for-fun/event-emitter';
 import * as React from 'react';
 import { ReactNode } from 'react';
-import { V as Validator } from './validate-CUmNZqg6.js';
-export { F as FormValidationError, S as SyncValidator, T as TriggerOptions, a as ValidatorRegistration, e as ensureValidate, r as registerFieldValidateDeps, b as registerValidatorByPath, c as revalidateDependentsOnChange, d as revalidateFormOnChange, s as setValidatingByPath, t as trigger, u as unregisterFieldValidateDeps, f as unsetValidatingByPath, v as validate } from './validate-CUmNZqg6.js';
-import { EventEmitter } from '@for-fun/event-emitter';
+import { S as SyncValidator, V as Validator } from './validate-nksgv1pR.js';
+export { F as FormValidationError, T as TriggerOptions, a as ValidatorRegistration, e as ensureValidate, r as registerFieldValidateDeps, b as registerValidatorByPath, c as revalidateDependentsOnChange, d as revalidateFormOnChange, f as runFormValidate, s as setValidatingByPath, t as trigger, u as unregisterFieldValidateDeps, g as unsetValidatingByPath, v as validate } from './validate-nksgv1pR.js';
 
 /**
  * Get form values: the values Map layered over parsedValues (when a schema
@@ -69,21 +70,28 @@ type SetFieldOptions = {
     shouldDirty?: boolean;
 };
 /**
- * Set field value
+ * Set field value. The value may also be an updater function receiving
+ * the field's current value and returning the next one (TanStack Form's
+ * `setFieldValue` contract) — handy for increments and array transforms:
+ * `setValue(form, 'count', c => c + 1)`. The tradeoff: a function can
+ * never itself be stored as a field value through this function.
  * @param form
  * @param name
  * @param value
  * @param options
  */
-declare function setValue<T extends Record<string, any> = any, P extends FieldPath<T> | PathSegments = FieldPath<T> | PathSegments>(form: Form$1<T>, name: P, value: PathValueOf<T, P>, options?: SetFieldOptions): void;
+declare function setValue<T extends Record<string, any> = any, P extends FieldPath<T> | PathSegments = FieldPath<T> | PathSegments>(form: Form$1<T>, name: P, value: PathValueOf<T, P> | ((prev: PathValueOf<T, P>) => PathValueOf<T, P>), options?: SetFieldOptions): void;
 /**
- * Set field value
+ * Set field value. The value may also be an updater function receiving
+ * the field's current value and returning the next one (TanStack Form's
+ * `setFieldValue` contract) — note that a function can therefore never
+ * itself be stored as a field value through this function.
  * @param form
  * @param path
  * @param value
  * @param options
  */
-declare function setValueByPath(form: Form$1, path: Path, value: any, options?: SetFieldOptions): void;
+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 {@link useField} `initialValue` seed. The field's first
@@ -205,9 +213,12 @@ type ResetOptions = {
     keepTouched?: boolean;
     /** Keep field errors instead of clearing them. */
     keepErrors?: boolean;
-    /** Keep the submitted flag (`isSubmitSuccessful`) instead of clearing
-     * it. */
+    /** Keep the submitted flag (`isSubmitted`) instead of clearing it —
+     * react-hook-form's `keepIsSubmitted`. */
     keepIsSubmitted?: boolean;
+    /** Keep the last submit's success flag (`isSubmitSuccessful`) instead of
+     * clearing it. */
+    keepIsSubmitSuccessful?: boolean;
     /** Keep `submitCount` instead of resetting it to 0. */
     keepSubmitCount?: boolean;
     /** Keep `isSubmitting` instead of resetting it to false. */
@@ -293,6 +304,15 @@ declare function getTouchedFields({ touched }: Form$1): string[];
  */
 declare function isTouched({ touched }: Form$1): boolean;
 
+/**
+ * Is one field dirty — the per-field rule behind `getFieldState`'s
+ * `isDirty` and {@link useIsFieldDirty}: 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, the same attribution {@link getDirtyFields} applies.
+ */
+declare function isFieldDirtyByPath(form: Form$1, path: Path): boolean;
 /**
  * Is dirty -- any value differs from initialValues
  * @param form
@@ -411,6 +431,16 @@ declare function setSubmitSuccessful(form: Form$1, value: boolean): void;
  * @param value
  */
 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 any imperative
+ * `subscribe(form, {event: 'status'})` listeners. Nothing else reads or
+ * interprets the value — server session flags, step state, non-field
+ * errors of any shape are all fair game. Starts `undefined`.
+ * @param form
+ * @param value
+ */
+declare function setStatus(form: Form$1, value: any): 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> = {
@@ -479,25 +509,39 @@ type RuleType = 'required' | 'min' | 'max' | 'minLength' | 'maxLength' | 'patter
  */
 type FieldRules = {
     /**
-     * Fails on empty values: `''`, `undefined` or `null` (`0` and `false`
-     * count as filled). A string is the error message; `true` uses the
-     * default. When it fails, the remaining rules are skipped — an empty
-     * value reports only its required error.
+     * Fails on empty values: `''`, `undefined`, `null` or an empty array
+     * (`0` and `false` count as filled) — react-hook-form's `required`
+     * semantics. A string is the error message; `true` uses the default.
+     * When it fails, the remaining rules are skipped — an empty value
+     * reports only its required error.
      */
     required?: string | true;
     /** Fails when `Number(value)` is below this bound; `NaN` values skip. */
     min?: number;
     /** Fails when `Number(value)` is above this bound; `NaN` values skip. */
     max?: number;
-    /** Fails when a string value is shorter than this; non-strings skip. */
+    /** Fails when a string value is shorter than this, or an array has
+     * fewer entries; other values skip. */
     minLength?: number;
-    /** Fails when a string value is longer than this; non-strings skip. */
+    /** Fails when a string value is longer than this, or an array has more
+     * entries; other values skip. */
     maxLength?: number;
     /** Fails when the value does not match `pattern.value`. */
     pattern?: {
         value: RegExp;
         message: string;
     };
+    /**
+     * Custom rule callbacks — react-hook-form's `register({validate})`
+     * shape: one function, or a record of named functions. Each runs after
+     * the declarative checks, and only when they passed (`required` failing
+     * short-circuits the rest, RHF's first-error semantics). A returned
+     * error keeps its message; its `type` becomes the record key
+     * (`'validate'` for the single-function form) so consumers can switch
+     * on `error.type`. Sync-only — async checks belong in the field's
+     * `validate` option.
+     */
+    validate?: SyncValidator | Record<string, SyncValidator>;
     /**
      * Overrides the message per rule type — `min`, `max`, `minLength`,
      * `maxLength` defaults and pattern's inline `message` alike — e.g. for
@@ -511,7 +555,22 @@ type UseFieldOptions$1<TValues extends Record<string, any> = any, TPath extends
     name: TPath;
     initialValue?: any;
     shouldUnregister?: boolean;
-    validate?: Validator;
+    /**
+     * 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>;
     /**
      * Declarative rules (required/min/max/minLength/maxLength/pattern),
      * compiled into a synchronous validator. `required` is special: it runs
@@ -532,6 +591,18 @@ type UseFieldOptions$1<TValues extends Record<string, any> = any, TPath extends
      * 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
@@ -553,10 +624,14 @@ type UseFieldOptions$1<TValues extends Record<string, any> = any, TPath extends
      * (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); reset/setInitialValues do not push into it
-     * or into the DOM — read live values with useValue/getValues instead.
-     * Attach the result with `<input defaultValue={field.value}>`-style
-     * binding (no `value` prop), exactly like <Field uncontrolled /> does.
+     * 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;
     /**
@@ -592,6 +667,15 @@ type UseFieldOptions$1<TValues extends Record<string, any> = any, TPath extends
      * 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;
 };
 /**
  * The result of {@link useField}. Deliberately a closed shape: no index
@@ -611,6 +695,22 @@ type UseFieldResult<TValues extends Record<string, any> = any, TPath extends Fie
      * 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;
@@ -631,12 +731,38 @@ type UseFieldResult<TValues extends Record<string, any> = any, TPath extends Fie
 };
 declare function useField<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | PathSegments = FieldPath<TValues> | PathSegments>(options: UseFieldOptions$1<TValues, TPath>): UseFieldResult<TValues, TPath>;
 
-type FieldArrayItem = {
+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'> = {
+    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;
+    /**
+     * Declarative rules validated against the whole array value
+     * (react-hook-form's `useFieldArray` `rules`): `required` fails on an
+     * empty array, `minLength`/`maxLength` read the array's length. Checked
+     * on submit and `trigger`, like every registered validator.
+     */
+    rules?: FieldRules;
+    /**
+     * Whether unmounting this array removes its branch. Defaults to the
+     * form-level `shouldUnregister` — tombstone (drop values) like a bound
+     * field's unmount; pass `false` to keep the values.
+     */
+    shouldUnregister?: boolean;
 };
-type UseFieldArrayResult = {
-    fields: FieldArrayItem[];
+type UseFieldArrayResult<K extends string = 'id'> = {
+    fields: FieldArrayItem<K>[];
     append: (value: any) => void;
     prepend: (value: any) => void;
     insert: (index: number, value: any) => void;
@@ -646,10 +772,7 @@ type UseFieldArrayResult = {
     replace: (values: any[]) => void;
     update: (index: number, value: any) => void;
 };
-declare function useFieldArray(options: {
-    name: Name;
-    form?: Form$1;
-}): UseFieldArrayResult;
+declare function useFieldArray<K extends string = 'id'>(options: UseFieldArrayOptions<K>): UseFieldArrayResult<K>;
 /**
  * The result of {@link useFieldArrayItem}. Mirrors the {@link useField}
  * return shape (`value`/`errors`/`error`) plus the row's `index` and
@@ -743,9 +866,12 @@ declare function createFormContext<TValues extends Record<string, any> = any>():
     useField: <TPath extends FieldPath<TValues> | PathSegments = FieldPath<TValues> | PathSegments>(options: {
         name: TPath;
     } & Omit<UseFieldOptions$1<TValues, TPath>, "form">) => UseFieldResult<TValues, TPath>;
-    useFieldArray: (options: {
+    useFieldArray: <K extends string = "id">(options: {
         name: FieldPath<TValues> | Name;
-    }) => UseFieldArrayResult;
+        keyName?: K;
+        rules?: FieldRules;
+        shouldUnregister?: boolean;
+    }) => UseFieldArrayResult<K>;
     useFieldArrayItem: <TValue = any>(options: {
         name: FieldPath<TValues> | Name;
         id: string;
@@ -765,13 +891,13 @@ type WatchScope = 'leaf' | 'branch';
 /** Events {@link subscribe} can watch. `'errors'` and `'touched'` are
  * stored per exact key, so they match exact keys ({@link onKeyEvent});
  * `'change'`, `'validating'`, `'submitting'`, `'submitCount'`,
- * `'disabled'` and `'submitSuccessful'` go through
+ * `'disabled'`, `'status'` and `'submitSuccessful'` go through
  * {@link onPathEvent}. `'validating'` carries paths (one per async
  * validator round) and matches by path exactly like `'change'`;
- * `'submitting'`, `'submitCount'`, `'disabled'` and
+ * `'submitting'`, `'submitCount'`, `'disabled'`, `'status'` and
  * `'submitSuccessful'` are payload-less broadcasts, so `name` never
  * narrows them — every subscriber hears every emission. */
-type SubscribeEvent = 'change' | 'errors' | 'touched' | 'validating' | 'submitting' | 'submitCount' | 'submitSuccessful' | 'disabled' | 'loading';
+type SubscribeEvent = 'change' | 'errors' | 'touched' | 'validating' | 'submitting' | 'submitCount' | 'submitSuccessful' | 'disabled' | 'status' | 'loading';
 /** Options accepted by {@link subscribe}. */
 type SubscribeOptions = {
     /** Path (or list of paths) to watch. Omit to receive every emission of
@@ -785,9 +911,10 @@ type SubscribeOptions = {
     /** Which writes around `name` are relevant — `'leaf'` or `'branch'`.
      * Only meaningful for the path-carrying events `'change'` and
      * `'validating'`: `'errors'`/`'touched'` match exact keys and
-     * `'submitting'`/`'submitCount'`/`'disabled'`/`'submitSuccessful'`
-     * are payload-less. Defaults to `'branch'` — the intuitive linkage
-     * semantics, where subscribing to `'tags'` means the whole branch. */
+     * `'submitting'`/`'submitCount'`/`'disabled'`/`'status'`/
+     * `'submitSuccessful'` are payload-less. Defaults to `'branch'` — the
+     * intuitive linkage semantics, where subscribing to `'tags'` means the
+     * whole branch. */
     scope?: WatchScope;
     /** Invoked with no arguments after each matching emission. Read fresh
      * state through the `get*` readers inside it. */
@@ -875,14 +1002,31 @@ declare function useWatchCore<T>(subscribeFactory: (invalidate: () => void) => (
  * `useSelector` compare. Omitted, behavior is unchanged.
  */
 declare function useWatch<T>(formOrEmitter: Form$1 | EventEmitter<FormEvents>, event: SubscribeEvent, getter: () => T, isEqual?: (prev: T, next: T) => boolean): T;
+/** Options for {@link useValue} and {@link useValueByPath}. */
+type UseValueOptions<T extends Record<string, any> = any, P extends FieldPath<T> | PathSegments = FieldPath<T> | PathSegments> = {
+    /** 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 FieldPath<T> | PathSegments = FieldPath<T> | PathSegments>(form: Form$1<T>, name: P): PathValueOf<T, P>;
+declare function useValue<T extends Record<string, any> = any, P extends FieldPath<T> | PathSegments = FieldPath<T> | PathSegments>(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): any;
+declare function useValueByPath(form: Form$1, path: Path, options?: {
+    defaultValue?: any;
+    exact?: boolean;
+}): any;
 /**
  * Get field touched state
  */
@@ -914,6 +1058,21 @@ declare function useFieldErrors<T extends Record<string, any> = any, P extends F
  */
 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 FieldPath<T> | PathSegments = FieldPath<T> | PathSegments>(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
@@ -952,6 +1111,13 @@ type FormState = {
      * separate signal; async rounds temporarily pass this flag like RHF's). */
     isValid: boolean;
     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;
@@ -978,6 +1144,15 @@ declare function useIsSubmitting(form: Form$1): boolean;
  * 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
@@ -1037,6 +1212,66 @@ declare function useFormError(form: Form$1): string | undefined;
  */
 declare function useFormErrors(form: Form$1): FieldError[];
 
+/**
+ * Options accepted by {@link useTransform}.
+ */
+type UseTransformOptions<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | PathSegments = FieldPath<TValues> | PathSegments, TDisplay = PathValueOf<TValues, TPath>> = {
+    /**
+     * Map the form's stored (raw) value to the display value the control
+     * renders — the read direction. Omitted: the raw value is displayed
+     * as-is (identity).
+     */
+    toDisplay?: (raw: PathValueOf<TValues, TPath>) => TDisplay;
+    /**
+     * Map a display value back to the raw value written into the form —
+     * the write direction. Omitted: the display value is written as-is
+     * (identity). The round trip should be an identity
+     * (`toDisplay(fromDisplay(x)) === x`); a store value the transform
+     * cannot invert (e.g. `undefined` for a not-yet-edited field) must be
+     * handled by `toDisplay`, since it runs first.
+     */
+    fromDisplay?: (display: TDisplay) => PathValueOf<TValues, TPath>;
+};
+/**
+ * Bind a control to a field whose stored value and display value differ
+ * — TanStack Form's `useTransform` counterpart, with the round trip made
+ * explicit: `toDisplay` maps the store value to what the control shows,
+ * `fromDisplay` maps the control's display value back to what the store
+ * holds. The store always carries the raw typed value, so
+ * `getValues`/submit/validation never see display representations.
+ *
+ * ```jsx
+ * const age = useTransform(form, 'age', {
+ *   toDisplay: (raw: number) => String(raw),
+ *   fromDisplay: (display: string) => Number(display)
+ * });
+ * <input value={age.value} onChange={e => age.onChange(e.target.value)} />
+ * ```
+ *
+ * `value` subscribes to 'change' at leaf scope exactly like a controlled
+ * `useField` value — typing, programmatic `setValue` and ancestor writes
+ * all re-derive it, writes elsewhere never re-render it. `onChange`
+ * writes through `userChangeByPath` (the user-change channel): with a
+ * field mounted at the same path the mode/reValidateMode-gated
+ * validation fires exactly as if the user typed into a bound field; with
+ * no mounted field it degrades to a plain value write. Touched marking
+ * stays a blur concern — pair this with `useField` at the same path, or
+ * call `setTouched`, when blur semantics matter.
+ *
+ * The transform functions are read fresh on every render (inline
+ * closures work), and `value` is recomputed per render — keep display
+ * values primitive (string/number) so React's equal-state bailout holds.
+ *
+ * @param form the form instance (explicit; the hook is headless — no
+ *        context read, no provider required)
+ * @param name the field's path (dotted string or segments)
+ * @param options the two mapping directions; both optional (identity)
+ */
+declare function useTransform<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | PathSegments = FieldPath<TValues> | PathSegments, TDisplay = PathValueOf<TValues, TPath>>(form: Form$1<TValues>, name: TPath, options?: UseTransformOptions<TValues, TPath, TDisplay>): {
+    value: TDisplay;
+    onChange: (display: TDisplay) => void;
+};
+
 /**
  * Props for <Form>.
  *
@@ -1075,6 +1310,27 @@ type FormProps<T extends Record<string, any> = any> = Omit<React.FormHTMLAttribu
      * unmounted fields, `false` keeps their values.
      */
     shouldUnregister?: boolean;
+    /**
+     * Validate on mount (see {@link Options.validateOnMount}): every
+     * mounted field with a validator kicks once after mount and the
+     * form-level `validate` (if any) runs once. A field's own
+     * `validateOnMount` prop overrides this flag.
+     */
+    validateOnMount?: boolean;
+    /**
+     * Disable every bound field: the form-level flag fields OR with their
+     * own `disabled` option (a field cannot opt out). Seeded at create and
+     * kept in sync while this prop changes (undefined leaves the current
+     * flag untouched — toggle at runtime with `setDisabled`).
+     */
+    disabled?: boolean;
+    /**
+     * Form-level default for field validation's `asyncAlways`: a field
+     * whose `required` gate failed still runs its debounced validator, its
+     * result landing per-source alongside the gate's errors. A field's own
+     * `asyncAlways` prop overrides this flag.
+     */
+    asyncAlways?: boolean;
     /**
      * Controlled external values. When the `values` reference changes, the
      * new object is synced into the form (via setInitialValues semantics):
@@ -1120,7 +1376,7 @@ type FormProps<T extends Record<string, any> = any> = Omit<React.FormHTMLAttribu
      */
     shouldFocusError?: boolean;
 };
-declare function Form<T extends Record<string, any> = any>({ form: f1, context, initialValues, values, shouldUnregister, onSubmit, onValidSubmit, onInvalidSubmit, action, shouldFocusError, ...props }: FormProps<T>): React.JSX.Element;
+declare function Form<T extends Record<string, any> = any>({ form: f1, context, initialValues, values, shouldUnregister, validateOnMount, disabled, asyncAlways, onSubmit, onValidSubmit, onInvalidSubmit, action, shouldFocusError, ...props }: FormProps<T>): React.JSX.Element;
 
 /**
  * Props for {@link FormField}: every {@link UseFieldOptions} option plus a
@@ -1172,10 +1428,17 @@ type UseFieldOptions<TValues extends Record<string, any> = any, TPath extends Fi
         signal: AbortSignal;
     }) => ReturnType<Validator>;
     /**
-     * Declarative rules (required/min/max/minLength/maxLength/pattern),
-     * compiled into a validator that runs before `validate`; failures land
-     * in the form's error state. Passed through to useField — like
-     * validateDebounce it is never spread onto the DOM element.
+     * Declarative rules (required/min/max/minLength/maxLength/pattern,
+     * plus custom `validate` callbacks), compiled into a validator that
+     * runs before `validate`; failures land in the form's error state.
+     * The declarative subset is also rendered as native constraint
+     * attributes (`required`, `minLength`, `pattern`, …) onto the element
+     * for browser/AT hints — `:invalid` styling, screen-reader
+     * announcements — while the store pipeline stays the source of truth
+     * for messages (`renderError`/`aria-invalid` keep working; a user-passed
+     * `required`/`pattern`/… prop overrides the derived attribute). Passed
+     * through to useField — like validateDebounce it is never spread onto
+     * the DOM element.
      */
     rules?: FieldRules;
     /**
@@ -1185,6 +1448,21 @@ type UseFieldOptions<TValues extends Record<string, any> = any, TPath extends Fi
      * useField/useValidate.
      */
     validateDebounce?: number;
+    /**
+     * Run this field's debounced validator even when its `required` gate
+     * failed (TanStack Form's `asyncAlways`): the gate's errors land
+     * immediately, the validator's own result lands alongside them
+     * per-source. Falls back to the form-level `createForm({asyncAlways})`.
+     * Passed through to useField.
+     */
+    asyncAlways?: boolean;
+    /**
+     * Validate this field once on mount (see {@link
+     * UseFieldOptions}' `validateOnMount`): overrides the form-level
+     * `createForm({validateOnMount})` / `<Form validateOnMount>` flag in
+     * either direction. Passed through to useField.
+     */
+    validateOnMount?: boolean;
     /**
      * Disable this field's control: OR-ed with the form-level flag
      * (`createForm({disabled})` / `setDisabled`) — a field cannot opt out
@@ -1212,9 +1490,10 @@ type UseFieldOptions<TValues extends Record<string, any> = any, TPath extends Fi
      * Uncontrolled mode: render the element with `defaultValue` instead of
      * `value` — typing re-renders nothing (the store still carries every
      * write; errors/touched/disabled still re-render the field). The
-     * snapshot is pinned at mount; reset does not clear the DOM element
-     * (read live values with useValue/getValues). Passed through to
-     * useField, never spread onto the DOM element.
+     * snapshot is pinned at mount; bulk operations (reset/setInitialValues)
+     * sync the DOM element directly without a render — RHF-register
+     * behavior (read live values with useValue/getValues). Passed through
+     * to useField, never spread onto the DOM element.
      */
     uncontrolled?: boolean;
     [key: string]: any;
@@ -1234,6 +1513,22 @@ type FieldProps<TValues extends Record<string, any> = any, TPath extends FieldPa
      * wiring for free.
      */
     renderError?: (error: string, id: string) => React.ReactNode;
+    /**
+     * Store `e.target.valueAsNumber` instead of the string value —
+     * react-hook-form's `register({valueAsNumber})` counterpart for number
+     * inputs (`<input type="number">`). `NaN` passes through as-is when the
+     * input cannot be parsed, matching RHF. An explicit `eventToValue`
+     * takes precedence.
+     */
+    valueAsNumber?: boolean;
+    /**
+     * Store `e.target.valueAsDate` instead of the string value — RHF's
+     * `register({valueAsDate})` counterpart for date/time inputs. `null`
+     * passes through when the input cannot be parsed. An explicit
+     * `eventToValue` takes precedence; combining with `valueAsNumber` is a
+     * TypeError.
+     */
+    valueAsDate?: boolean;
 };
 /**
  * The error-message element id a field's `aria-describedby` points at —
@@ -1279,5 +1574,5 @@ type SelectComponent = {
 };
 declare const Select: SelectComponent;
 
-export { Checkbox, CheckboxGroupContext, CheckboxGroupProvider, Field, FieldError, FieldErrorEntry, FieldPath, Form, FormContext, FormEvents, FormField, Form$1 as FormInstance, FormProvider, Name, Options, Path, PathSegments, PathValueOf, Select, ValidationMode, Validator, changeValue, changeValueByPath, createFormContext, emitChangeByPath, fieldErrorId, getDirtyFields, getFieldState, getTouchedFields, getValue, getValueByPath, getValues, handleSubmit, hasTouched, hasTouchedByPath, incrementSubmitCount, isDirty, isTouched, registerFieldMode, removeField, removeFieldByPath, reset, resetField, seedValueByPath, setDisabled, setInitialValues, setIsSubmitting, setSubmitSuccessful, setTouched, setTouchedByPath, setValue, setValueByPath, subscribe, unregisterFieldMode, useCanSubmit, useCheckboxGroupContext, useDirtyFields, useError, useErrorByPath, useField, useFieldArray, useFieldArrayItem, useFieldErrors, useFieldErrorsByPath, useForm, useFormContext, useFormError, useFormErrors, useFormState, useHasErrors, useIsDirty, useIsLoading, useIsSubmitSuccessful, useIsSubmitting, useIsValid, useIsValidating, useSubmitCount, useTouched, useTouchedByPath, useTouchedFields, useValue, useValueByPath, useWatch, useWatchCore, userBlur, userChangeByPath };
-export type { FieldRules, FieldState, FormState, HandleSubmitOptions, RemoveFieldOptions, ResetFieldOptions, ResetOptions, SetFieldOptions, SubscribeEvent, SubscribeOptions, WatchScope };
+export { Checkbox, CheckboxGroupContext, CheckboxGroupProvider, Field, FieldError, FieldErrorEntry, FieldPath, Form, FormContext, FormEvents, FormField, Form$1 as FormInstance, FormProvider, Name, Options, Path, PathSegments, PathValueOf, Select, SyncValidator, ValidationMode, Validator, changeValue, changeValueByPath, createFormContext, emitChangeByPath, fieldErrorId, getDirtyFields, getFieldState, getTouchedFields, getValue, getValueByPath, getValues, handleSubmit, hasTouched, hasTouchedByPath, incrementSubmitCount, isDirty, isFieldDirtyByPath, isTouched, registerFieldMode, removeField, removeFieldByPath, reset, resetField, seedValueByPath, setDisabled, setInitialValues, setIsSubmitting, setStatus, setSubmitSuccessful, setTouched, setTouchedByPath, setValue, setValueByPath, subscribe, unregisterFieldMode, useCanSubmit, useCheckboxGroupContext, useDirtyFields, useError, useErrorByPath, useField, useFieldArray, useFieldArrayItem, useFieldErrors, useFieldErrorsByPath, useForm, useFormContext, useFormError, useFormErrors, useFormState, useHasErrors, useIsDirty, useIsFieldDirty, useIsFieldDirtyByPath, useIsLoading, useIsSubmitSuccessful, useIsSubmitting, useIsValid, useIsValidating, useStatus, useSubmitCount, useTouched, useTouchedByPath, useTouchedFields, useTransform, useValue, useValueByPath, useWatch, useWatchCore, userBlur, userChangeByPath };
+export type { FieldRules, FieldState, FormState, HandleSubmitOptions, RemoveFieldOptions, ResetFieldOptions, ResetOptions, SetFieldOptions, SubscribeEvent, SubscribeOptions, UseTransformOptions, UseValueOptions, WatchScope };