react-f0rm 1.3.0 → 1.4.0

package/dist/index.d.ts

@@ -1,11 +1,10 @@
-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 { f as FieldError, F as Form$1, e as Path, d as FieldPath, P as PathSegments, g as PathValueOf, N as Name, h as ValidationMode, R as RegisterOptions, i as RegisterProps, a as FieldErrorEntry, V as Validator, S as StandardSchemaV1, j as FieldRules, k as FieldErrors, l as FieldErrorsTree, O as Options, m as FormEvents } from './standard-schema-CYbnugL7.js';
+export { A as ArrayItemOf, D as DottedPath, n as FORM_ERROR, o as FormValidateFn, p as FormValidateMeta, q as FormValidateMode, r as FormValidationError, I as InferSchemaValues, s as OpaqueTypes, t as PathValue, u as ReValidateMode, v as SetErrorOptions, w as SetFocusOptions, x as SetServerErrorsOptions, y as SyncValidator, T as TriggerOptions, b as VALIDATION_OUTCOME, z as ValidateResult, c as ValidationOutcome, B as ValidatorRegistration, C as clearErrors, E as clearServerErrors, G as createForm, H as dottedKeyToFieldPath, J as ensureValidate, K as fieldPathToDottedKey, L as getError, M as getErrorByPath, Q as getErrors, U as getErrorsRecord, W as getErrorsTree, X as getFieldErrors, Y as getFieldErrorsByPath, Z as getFirstError, _ as hasErrors, $ as registerFieldValidateDeps, a0 as registerValidatorByPath, a1 as revalidateDependentsOnChange, a2 as revalidateFormOnChange, a3 as runFormValidate, a4 as setError, a5 as setErrorByPath, a6 as setFocus, a7 as setServerErrors, a8 as setValidatingByPath, a9 as trigger, aa as unregisterFieldValidateDeps, ab as unsetValidatingByPath, ac as validate } from './standard-schema-CYbnugL7.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 { 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';
+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-3hAjl6Bz.js';
 
 /**
  * Get form values: the values Map layered over parsedValues (when a schema
@@ -419,6 +418,45 @@ declare function userChangeByPath(form: Form$1, path: Path, value: any): void;
  */
 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;
@@ -462,8 +500,16 @@ type HandleSubmitOptions<T extends Record<string, any> = any> = {
      * final (schema-coerced) values — the slot <Form>'s `action` prop uses
      * to dispatch React 19 server actions with FormData. Runs inside the
      * same isSubmitting window and is awaited like onSubmit/onValidSubmit.
+     *
+     * The callback may return an {@link ActionErrorResult}: its `errors`
+     * record (field path → message or messages) lands on the form through
+     * {@link setServerErrors} (`type: 'server'`, cleared existing server
+     * errors replaced), and the submit counts as unsuccessful — a rejected
+     * server round trip is an invalid submit, exactly like failed client
+     * validation. Any other return value (including `undefined`) means the
+     * submit succeeded.
      */
-    onAction?: (values: T, e?: any) => void | Promise<void>;
+    onAction?: (values: T, e?: any) => void | Promise<void | ActionErrorResult>;
     /**
      * Focus the first error field after a failed submit. Defaults to true —
      * only an explicit `false` disables it. When custom validation fails,
@@ -473,6 +519,22 @@ type HandleSubmitOptions<T extends Record<string, any> = any> = {
      * form's first ':invalid' control is focused directly.
      */
     shouldFocusError?: boolean;
+    /**
+     * Whether native constraint validation (the submitted element's
+     * checkValidity) gates this attempt. Defaults to the form's
+     * {@link Form.shouldUseNativeValidation} flag — pass `false` to skip
+     * the native gate for one submit (a save-draft button, say) while
+     * custom validators still run; pass `true` to reinstate it on a form
+     * that disabled it. 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 on the
+ * form 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
@@ -498,58 +560,6 @@ declare function handleSubmit<T extends Record<string, any> = any>(form: Form$1<
     currentTarget?: any;
 }) => Promise<void>;
 
-/** Type tag of a failed rule, as stored on the resulting FieldError. */
-type RuleType = 'required' | 'min' | 'max' | 'minLength' | 'maxLength' | 'pattern';
-/**
- * Declarative field rules — a subset of react-hook-form's `register` rules.
- *
- * Failed rules land in the form's error state as FieldErrors (`type` is the
- * rule name) instead of only surfacing through the browser's validity
- * bubble, so any design system can render the messages uniformly.
- */
-type FieldRules = {
-    /**
-     * 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, or an array has
-     * fewer entries; other values skip. */
-    minLength?: number;
-    /** 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
-     * centralizing or localizing messages.
-     */
-    messages?: Partial<Record<Exclude<RuleType, 'required'>, string>>;
-};
-
 type UseFieldOptions$1<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | PathSegments = FieldPath<TValues> | PathSegments> = {
     form?: Form$1<TValues>;
     name: TPath;
@@ -566,11 +576,11 @@ type UseFieldOptions$1<TValues extends Record<string, any> = any, TPath extends
      * second argument carries the validation context (`meta.signal` aborts
      * when the round is superseded).
      */
-    validate?: (value: PathValueOf<TValues, TPath>, meta: {
+    validate?: ((value: PathValueOf<TValues, TPath>, meta: {
         form: Form$1<TValues>;
         path: Path;
         signal: AbortSignal;
-    }) => ReturnType<Validator>;
+    }) => ReturnType<Validator>) | StandardSchemaV1<PathValueOf<TValues, TPath>>;
     /**
      * Declarative rules (required/min/max/minLength/maxLength/pattern),
      * compiled into a synchronous validator. `required` is special: it runs
@@ -613,9 +623,13 @@ type UseFieldOptions$1<TValues extends Record<string, any> = any, TPath extends
      */
     delayError?: number;
     /**
-     * Disable this field: OR-ed with the form-level flag
-     * (`createForm({disabled})` / `setDisabled`) into the result's
-     * `disabled`. A field cannot opt out of a disabled form.
+     * 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;
     /**
@@ -676,6 +690,32 @@ type UseFieldOptions$1<TValues extends Record<string, any> = any, TPath extends
      * 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
@@ -728,6 +768,40 @@ type UseFieldResult<TValues extends Record<string, any> = any, TPath extends Fie
      * 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 FieldPath<TValues> | PathSegments = FieldPath<TValues> | PathSegments>(options: UseFieldOptions$1<TValues, TPath>): UseFieldResult<TValues, TPath>;
 
@@ -761,18 +835,24 @@ type UseFieldArrayOptions<K extends string = 'id'> = {
      */
     shouldUnregister?: boolean;
 };
-type UseFieldArrayResult<K extends string = 'id'> = {
+type UseFieldArrayResult<TItem = any, K extends string = 'id'> = {
     fields: FieldArrayItem<K>[];
-    append: (value: any) => void;
-    prepend: (value: any) => void;
-    insert: (index: number, value: any) => void;
-    remove: (index: number) => void;
+    /** 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) => void;
+    prepend: (value: TItem) => void;
+    insert: (index: number, value: TItem) => 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: any[]) => void;
-    update: (index: number, value: any) => void;
+    replace: (values: TItem[]) => void;
+    update: (index: number, value: TItem) => void;
 };
-declare function useFieldArray<K extends string = 'id'>(options: UseFieldArrayOptions<K>): UseFieldArrayResult<K>;
+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
@@ -829,8 +909,8 @@ declare function useFieldArrayItem<TValue = any>(options: {
     form?: Form$1;
 }): UseFieldArrayItemResult<TValue>;
 
-declare const FormContext: React.Context<Form$1<any> | null>;
-declare const FormProvider: React.Provider<Form$1<any> | null>;
+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>()` — to get a fully typed `Form<Values>`
@@ -841,44 +921,50 @@ declare const FormProvider: React.Provider<Form$1<any> | null>;
  * @throws when no `<FormProvider>` is mounted above the call site.
  */
 declare function useFormContext<T extends Record<string, any> = any>(): Form$1<T>;
-/**
- * Create an isolated bundle of form-context bindings: its own React context
- * plus `useField` / `useFieldArray` / `useFieldArrayItem` /
- * `useFormContext` hooks that resolve their form from it.
- *
- * Why: the module-level {@link FormContext} works fine for a single form per
- * subtree, but nesting two forms (or reusing a component inside a different
- * form) makes them fight over one context. Calling this factory once per app
- * area — `const Ctx = createFormContext<Values>()` — fixes the value shape
- * (`Ctx.useField({name: 'user.name'})` gets its `name` constrained by
- * `FieldPath<Values>` and its `value` typed accordingly), so call sites stop
- * hand-writing generics, and each instance's Provider scopes a strictly
- * separate form. The bundle also carries its raw React context
- * (`Ctx.context`) so `<Form context={Ctx.context}>` can provide into it.
- */
-declare function createFormContext<TValues extends Record<string, any> = any>(): {
-    context: React.Context<Form$1<TValues> | null>;
-    FormProvider: ({ form, children }: {
+/** 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 FieldPath<TValues> | PathSegments = FieldPath<TValues> | PathSegments>(options: {
         name: TPath;
-    } & Omit<UseFieldOptions$1<TValues, TPath>, "form">) => UseFieldResult<TValues, TPath>;
-    useFieldArray: <K extends string = "id">(options: {
+    } & Omit<UseFieldOptions$1<TValues, TPath>, 'form'>) => UseFieldResult<TValues, TPath>;
+    useFieldArray: <TItem = any, K extends string = 'id'>(options: {
         name: FieldPath<TValues> | Name;
         keyName?: K;
         rules?: FieldRules;
         shouldUnregister?: boolean;
-    }) => UseFieldArrayResult<K>;
+    }) => UseFieldArrayResult<TItem, K>;
     useFieldArrayItem: <TValue = any>(options: {
         name: FieldPath<TValues> | Name;
         id: string;
     }) => UseFieldArrayItemResult<TValue>;
 };
-declare const CheckboxGroupContext: React.Context<any>;
-declare const CheckboxGroupProvider: React.Provider<any>;
+/**
+ * Create an isolated bundle of form-context bindings: its own React context
+ * plus `useField` / `useFieldArray` / `useFieldArrayItem` /
+ * `useFormContext` hooks that resolve their form from it.
+ *
+ * Why: the module-level {@link FormContext} works fine for a single form per
+ * subtree, but nesting two forms (or reusing a component inside a different
+ * form) makes them fight over one context. Calling this factory once per app
+ * area — `const Ctx = createFormContext<Values>()` — fixes the value shape
+ * (`Ctx.useField({name: 'user.name'})` gets its `name` constrained by
+ * `FieldPath<Values>` and its `value` typed accordingly), so call sites stop
+ * hand-writing generics, and each instance's Provider scopes a strictly
+ * separate form. The bundle also carries its raw React context
+ * (`Ctx.context`) so `<Form context={Ctx.context}>` can 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}.
@@ -944,6 +1030,66 @@ type SubscribeOptions = {
  * @return unsubscribe function
  */
 declare function subscribe(form: Form$1, options: SubscribeOptions): () => void;
+/** The handle {@link watch} returns: a subscribe/getSnapshot pair any
+ * reactive runtime can bind to — React's `useSyncExternalStore(subscribe,
+ * getSnapshot)`, a Solid signal, a Vue ref, a Svelte store. The handle
+ * keeps one internal listener alive from creation, so `getSnapshot()` is
+ * always fresh (a read never returns a pre-write value even with no
+ * consumer subscribed); `subscribe` adds a consumer callback and returns
+ * its own unsubscribe. Call {@link WatchHandle.dispose} when the handle's
+ * lifetime ends (adapter teardown, effect cleanup). */
+type WatchHandle<T> = {
+    /** Read the current snapshot. Recomputed on every heard event (and on
+     * first read), cached in between — repeated reads share one reference
+     * until the watched state actually changes. */
+    getSnapshot: () => T;
+    /** Register a change listener; returns the unsubscribe function. The
+     * listener fires only when the projection observably changed: with an
+     * `isEqual` comparator the getter is re-run per event and an equal
+     * verdict skips the callback entirely (TanStack's `useSelector`
+     * contract); without one, every heard event wakes the listener. */
+    subscribe: (invalidate: () => void) => () => void;
+    /** Remove the internal listener and every consumer callback. The handle
+     * is dead afterwards — reads return the last cached value and no
+     * callback ever fires again. */
+    dispose: () => void;
+};
+/**
+ * Watch a projection of form state without React — the framework-free
+ * counterpart of {@link useWatch} (same signature, same `isEqual`
+ * bailout), exported as a named top-level function so it is tree-shaken
+ * when unused. Headless adapters (Solid/Vue/Svelte bridges, imperative
+ * autosave/analytics code) consume the returned
+ * {@link WatchHandle}: read the current snapshot through `getSnapshot()`
+ * and re-read (or re-render) whenever `subscribe`'s listener fires.
+ *
+ * The handle subscribes eagerly at creation, so `getSnapshot()` never
+ * returns a stale value — including reads with no consumer subscribed.
+ * `getter` and `isEqual` are captured when `watch` is called: call it at
+ * setup time, like a subscription, and {@link WatchHandle.dispose} it at
+ * teardown. Every emission of `event` wakes the listener (payload-less
+ * broadcasts included) — the wide surface `useWatch` uses; path-scoped
+ * variants are the `useValue`-family hooks on the React side and
+ * {@link subscribe} with a `name` on this side.
+ *
+ * ```js
+ * const handle = watch(form, 'change', () => getValue(form, 'email'));
+ * // imperative consumer:
+ * const off = handle.subscribe(() => save(handle.getSnapshot()));
+ * // React adapter (useWatch is this composition):
+ * useSyncExternalStore(handle.subscribe, handle.getSnapshot, handle.getSnapshot);
+ * handle.dispose(); // teardown
+ * ```
+ *
+ * @param form the form to watch
+ * @param event the event whose emissions invalidate the snapshot
+ * @param getter the projection — read fresh state through the `get*`
+ *        readers inside it
+ * @param isEqual optional equality check; an equal verdict after an event
+ *        skips the listeners entirely (wide getters returning fresh
+ *        references per call stop churning subscribers)
+ */
+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.
@@ -989,6 +1135,12 @@ declare function useWatchCore<T>(subscribeFactory: (invalidate: () => void) => (
  * 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
@@ -1027,6 +1179,18 @@ 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
  */
@@ -1095,7 +1259,7 @@ declare function useTouchedFields(form: Form$1): string[];
  * {@link useIsDirty}. Cheaper than calling the granular hooks one by one
  * (one subscription and one snapshot instead of one per flag).
  */
-type FormState = {
+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'). */
@@ -1110,6 +1274,12 @@ type FormState = {
      * 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
@@ -1128,8 +1298,50 @@ type FormState = {
     /** The form-level disabled flag (fields OR their own `disabled`). */
     disabled: boolean;
 };
-declare function useFormState(form: Form$1): FormState;
+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?: (prev: T, next: T) => boolean): 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;
@@ -1225,12 +1437,26 @@ type UseTransformOptions<TValues extends Record<string, any> = any, TPath extend
     /**
      * 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
+     * (identity). May return a Promise: the resolved raw value commits
+     * when it settles (async transforms, e.g. server-side formatting),
+     * with stale resolutions dropped — only the latest write commits.
+     * 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>;
+    fromDisplay?: (display: TDisplay) => PathValueOf<TValues, TPath> | Promise<PathValueOf<TValues, TPath>>;
+    /**
+     * Debounce the display→raw commit: a write inside the window supersedes
+     * the pending one, and only the last write commits when the window
+     * elapses — the async-transforms counterpart of the field validator's
+     * `validateDebounce` (TanStack Form's `asyncDebounceMs`). `0`/omitted
+     * commits immediately (an async `fromDisplay` still resolves before
+     * the commit lands). The store value stays unchanged until the commit:
+     * `value` keeps deriving from it, and validation fires at commit time
+     * through the user-change pipeline.
+     */
+    asyncDebounceMs?: number;
 };
 /**
  * Bind a control to a field whose stored value and display value differ
@@ -1282,6 +1508,10 @@ declare function useTransform<TValues extends Record<string, any> = any, TPath e
  * reportValidity() surfaces the offending constraints as native bubbles and
  * submission stops (onInvalidSubmit fires). onSubmit/onValidSubmit only run
  * once every native constraint (required, type=email, minLength, ...) passes.
+ * Pass `shouldUseNativeValidation={false}` (or `createForm({shouldUseNativeValidation:
+ * false})`) to skip the native gate entirely for custom-validator-only
+ * forms — targets without checkValidity (React Native, toolbar buttons)
+ * are always exempt.
  *
  * The submit flow itself lives in the headless `handleSubmit` (see form.ts);
  * this component is a thin wrapper that binds it to the rendered <form>.
@@ -1353,8 +1583,22 @@ type FormProps<T extends Record<string, any> = any> = Omit<React.FormHTMLAttribu
      * `action={createUser}` for a server action or
      * `action={formData => startTransition(() => dispatch(formData))}` in a
      * useActionState bridge. `isSubmitting` covers the whole flight.
+     *
+     * The callback may return an {@link ActionErrorResult}: its `errors`
+     * record lands on the form as per-field `type: 'server'` errors and the
+     * submit counts as unsuccessful — a server action rejecting the payload
+     * (422-style) hydrates the fields exactly like failed client
+     * validation. Return anything else to report success.
+     *
+     * Alternatively pass a URL string: it renders as the form's native
+     * `action` attribute, giving progressive enhancement — without
+     * JavaScript the browser posts the raw FormData to it (native
+     * constraint attributes from declarative `rules` still gate invalid
+     * submits), and with JavaScript the validated pipeline runs instead
+     * (pair the URL with `method="post"` and perform the network call in
+     * `onValidSubmit`; `handleSubmit` preventDefaults the native post).
      */
-    action?: (formData: FormData) => void | Promise<void>;
+    action?: string | ((formData: FormData) => void | Promise<void | ActionErrorResult>);
     /**
      * Called when validation fails.
      * @param errors array of {path, type, message} entries in insertion
@@ -1375,8 +1619,17 @@ type FormProps<T extends Record<string, any> = any> = Omit<React.FormHTMLAttribu
      * false to disable.
      */
     shouldFocusError?: boolean;
+    /**
+     * Whether native constraint validation gates submission — pass false
+     * for custom-validator-only forms (react-hook-form's
+     * `shouldUseNativeValidation`). Seeds the internally created form's
+     * flag (`useForm` create-time option) and overrides it for this form's
+     * submit wiring; with an external `form` prop only the submit wiring is
+     * affected. Defaults to the form's flag (`true`).
+     */
+    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, ...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, shouldUseNativeValidation, ...props }: FormProps<T>): React.JSX.Element;
 
 /**
  * Props for {@link FormField}: every {@link UseFieldOptions} option plus a
@@ -1401,6 +1654,19 @@ type FormFieldProps<TValues extends Record<string, any> = any, TPath extends Fie
  */
 declare function FormField<TValues extends Record<string, any> = any, TPath extends FieldPath<TValues> | PathSegments = FieldPath<TValues> | PathSegments>({ children, ...options }: FormFieldProps<TValues, TPath>): React.ReactNode;
 
+/**
+ * The error-message element id a field's `aria-describedby` points at —
+ * `fieldErrorId('a[0].b')` is `'a-0-b'`, the same id `<Field>`'s built-in
+ * `renderError` span carries. This is the library-level wiring convention:
+ * whenever a bound field (Field/Checkbox/Select, `useField`'s `inputProps`)
+ * has an error it sets `aria-invalid` and describes the element with this
+ * id, so a custom error component only needs
+ * `<span id={fieldErrorId(name)} role="alert">` to complete the
+ * accessible-name chain for screen readers.
+ * @param name the same field name passed to the bound component
+ */
+declare function fieldErrorId(name: Name): string;
+
 /**
  * Props shared by Field/Checkbox/Select. Generic so a typed form flows into
  * the `validate` callback: with `form` (a `Form<Values>`) and `name`
@@ -1422,11 +1688,11 @@ type UseFieldOptions<TValues extends Record<string, any> = any, TPath extends Fi
      * second argument carries the validation context (`meta.signal` aborts
      * when the round is superseded).
      */
-    validate?: (value: PathValueOf<TValues, TPath>, meta: {
+    validate?: ((value: PathValueOf<TValues, TPath>, meta: {
         form: Form$1;
         path: Path;
         signal: AbortSignal;
-    }) => ReturnType<Validator>;
+    }) => ReturnType<Validator>) | StandardSchemaV1<PathValueOf<TValues, TPath>>;
     /**
      * Declarative rules (required/min/max/minLength/maxLength/pattern,
      * plus custom `validate` callbacks), compiled into a validator that
@@ -1530,17 +1796,6 @@ type FieldProps<TValues extends Record<string, any> = any, TPath extends FieldPa
      */
     valueAsDate?: boolean;
 };
-/**
- * The error-message element id a field's `aria-describedby` points at —
- * `fieldErrorId('a[0].b')` is `'a-0-b'`, the same id `Field`'s built-in
- * `renderError` span carries. This is the library-level wiring convention:
- * whenever a bound field (Field/Checkbox/Select) has an error it sets
- * `aria-invalid` and describes the element with this id, so a custom error
- * component only needs `<span id={fieldErrorId(name)} role="alert">` to
- * complete the accessible-name chain for screen readers.
- * @param name the same field name passed to the bound component
- */
-declare function fieldErrorId(name: Name): string;
 /**
  * The callable shape of {@link Field}: `form` + `name` flow their generics
  * into `validate`'s value argument (`PathValueOf<TValues, TPath>`). A named
@@ -1574,5 +1829,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, 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 };
+export { Checkbox, CheckboxGroupContext, CheckboxGroupProvider, Field, FieldError, FieldErrorEntry, FieldErrors, FieldErrorsTree, FieldPath, FieldRules, Form, FormContext, FormEvents, FormField, Form$1 as FormInstance, FormProvider, Name, Options, Path, PathSegments, PathValueOf, RegisterOptions, RegisterProps, Select, StandardSchemaV1, ValidationMode, Validator, changeValue, changeValueByPath, createFormContext, emitChangeByPath, fieldErrorId, 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, FieldState, FormContextBundle, FormState, HandleSubmitOptions, RemoveFieldOptions, ResetFieldOptions, ResetOptions, SetFieldOptions, SubscribeEvent, SubscribeOptions, UseTransformOptions, UseValueOptions, WatchHandle, WatchScope };