formstand 0.15.2 → 0.17.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { P as PathDepth, D as DefaultPathDepth, F as Form, C as CreateFormOptions, a as FieldValidationResult, b as FormState, c as FieldPath, d as FieldValue, E as ErrorMap } from './createForm-jlzK2lCG.cjs';
-export { B as BoolMap, e as FieldSnapshot, f as FieldsValidationResult, I as InvalidSubmitHandler, R as ReadonlyStoreApi, g as ResetOptions, S as SettledFieldValidationResult, h as SettledFieldsValidationResult, i as SettledValidationResult, j as SubmitHandler, k as SubmitOptions, l as SubmitResult, V as ValidationMode, m as ValidationResult, n as ValidationTrigger, o as createForm, p as emptyValueForSchema, q as flattenIssues, r as isAsyncRequiredError, s as shouldValidateOn, v as validateAsync, t as validateSync } from './createForm-jlzK2lCG.cjs';
+import { P as PathDepth, D as DefaultPathDepth, F as Form, C as CreateFormOptions, a as FieldValidationResult, S as SettledFieldValidationResult, b as FormState, c as FieldPath, d as FieldValue, E as ErrorMap } from './createForm-D0xLZH-Q.cjs';
+export { B as BoolMap, e as FieldSnapshot, f as FieldsValidationResult, I as InvalidSubmitHandler, R as ReadonlyStoreApi, g as ResetOptions, h as SettledFieldsValidationResult, i as SettledValidationResult, j as SubmitHandler, k as SubmitOptions, l as SubmitResult, V as ValidationMode, m as ValidationResult, n as ValidationTrigger, o as createForm, p as emptyValueForSchema, q as flattenIssues, r as isAsyncRequiredError, s as shouldValidateOn, v as validateAsync, t as validateSync } from './createForm-D0xLZH-Q.cjs';
 import { z } from 'zod';
 import * as react from 'react';
 import { ReactNode, ChangeEvent } from 'react';
@@ -29,6 +29,8 @@ type PersistHandle = Readonly<{
 }>;
 declare const persistForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, options: PersistOptions<TSchema>) => PersistHandle;
 
+declare const usePersistForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, options: PersistOptions<TSchema>) => PersistHandle;
+
 declare const useForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(schema: TSchema, options: CreateFormOptions<TSchema, D>) => Form<TSchema, D>;
 
 type FormProviderProps<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = Readonly<{
@@ -49,7 +51,7 @@ type FieldFormApi = Readonly<{
     setError(path: string, errors: string | readonly string[]): void;
     clearErrors(path?: string): void;
     validateField(path: string): FieldValidationResult;
-    validateFieldAsync(path: string): Promise<FieldValidationResult>;
+    validateFieldAsync(path: string): Promise<SettledFieldValidationResult>;
 }>;
 type FieldPathArg<TValues> = string | ((state: FormState<TValues>) => string);
 type UseFieldOptions = Readonly<{
@@ -61,6 +63,7 @@ type UseFieldReturn<TValue> = Readonly<{
     initialValue: TValue;
     emptyValue: null | undefined;
     error: readonly string[] | undefined;
+    firstError: string | undefined;
     touched: boolean;
     dirty: boolean;
     isValidating: boolean;
@@ -69,7 +72,7 @@ type UseFieldReturn<TValue> = Readonly<{
     setError: (errors: string | readonly string[]) => void;
     clearError: () => void;
     validate: () => FieldValidationResult;
-    validateAsync: () => Promise<FieldValidationResult>;
+    validateAsync: () => Promise<SettledFieldValidationResult>;
     onBlur: () => void;
 }>;
 declare const inferredCallsOnly$2: unique symbol;
@@ -92,7 +95,7 @@ type VariantFieldValue<V, TField extends string> = V extends unknown ? TField ex
 type CommonKeys<V> = keyof V;
 type AllKeys<V> = V extends unknown ? keyof V : never;
 type VariantKeys<V> = Exclude<AllKeys<V>, CommonKeys<V>> & string;
-type UnionValueAt<TValues, P extends string> = P extends keyof TValues ? NonNullable<TValues[P]> : P extends `${infer Head}.${infer Tail}` ? Head extends keyof TValues ? UnionValueAt<NonNullable<TValues[Head]>, Tail> : never : never;
+type UnionValueAt<TValues, P extends string> = P extends keyof TValues ? NonNullable<TValues[P]> : TValues extends readonly (infer Item)[] ? P extends `${number}` ? NonNullable<Item> : P extends `${infer Head}.${infer Tail}` ? Head extends keyof TValues ? UnionValueAt<NonNullable<TValues[Head]>, Tail> : Head extends `${number}` ? UnionValueAt<NonNullable<Item>, Tail> : never : never : P extends `${infer Head}.${infer Tail}` ? Head extends keyof TValues ? UnionValueAt<NonNullable<TValues[Head]>, Tail> : never : never;
 declare const inferredCallsOnly$1: unique symbol;
 interface InferredTypeArg$1 {
     readonly [inferredCallsOnly$1]: typeof inferredCallsOnly$1;
@@ -114,16 +117,22 @@ type FieldArrayFormApi = Readonly<{
     arrayMove(path: string, from: number, to: number): void;
     arraySwap(path: string, a: number, b: number): void;
     validateField?(path: string): FieldValidationResult;
+    setError?(path: string, errors: string | readonly string[]): void;
+    clearErrors?(path?: string): void;
 }>;
 type FieldArrayEntry<TItem> = Readonly<{
     id: string;
     value: TItem;
 }>;
 type UseFieldArrayReturn<TItem> = Readonly<{
+    path: string;
     fields: readonly FieldArrayEntry<TItem>[];
     items: readonly TItem[];
     length: number;
     error: readonly string[] | undefined;
+    firstError: string | undefined;
+    setError: (errors: string | readonly string[]) => void;
+    clearError: () => void;
     push: (item: TItem) => void;
     remove: (index: number) => void;
     insert: (index: number, item: TItem) => void;
@@ -147,6 +156,22 @@ declare function useFieldArray<TItem = unknown>(form: FieldArrayFormApi & {
 }, path: FieldPathArg<unknown>): UseFieldArrayReturn<TItem>;
 declare function useFieldArray<TSchema extends z.ZodType, P extends FieldPath<z.input<TSchema>, D>, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, path: P): UseFieldArrayReturn<ArrayItemOf<FieldValue<z.input<TSchema>, P>>>;
 
+type UseFieldsReturn<TFields extends readonly unknown[]> = Readonly<{
+    fields: TFields;
+    error: readonly string[] | undefined;
+    firstError: string | undefined;
+    touched: boolean;
+    dirty: boolean;
+    isValidating: boolean;
+    onBlur: () => void;
+}>;
+declare function useFields(form: FieldFormApi & {
+    readonly schema?: undefined;
+}, paths: readonly string[]): UseFieldsReturn<readonly UseFieldReturn<unknown>[]>;
+declare function useFields<TSchema extends z.ZodType, const P extends readonly FieldPath<z.input<TSchema>, D>[], D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, paths: P): UseFieldsReturn<{
+    readonly [K in keyof P]: UseFieldReturn<FieldValue<z.input<TSchema>, P[K] & string>>;
+}>;
+
 type BoundUseField<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = {
     (pathSelector: (state: FormState<z.input<TSchema>>) => string, options?: UseFieldOptions): UseFieldReturn<unknown>;
     <P extends FieldPath<z.input<TSchema>, D>>(path: P, options?: UseFieldOptions): UseFieldReturn<FieldValue<z.input<TSchema>, P>>;
@@ -174,10 +199,19 @@ type FormHooks<TSchema extends z.ZodType, N extends string, D extends PathDepth
     [K in `use${Capitalize<N>}IsDirty`]: BoundUseFlag<TSchema, D>;
 } & {
     [K in `use${Capitalize<N>}IsValid`]: BoundUseFlag<TSchema, D>;
+} & {
+    [K in `use${Capitalize<N>}IsValidating`]: BoundUseFlag<TSchema, D>;
 } & {
     [K in `use${Capitalize<N>}IsSubmitting`]: () => boolean;
 } & {
     [K in `use${Capitalize<N>}SubmitCount`]: () => number;
+} & {
+    [K in `use${Capitalize<N>}Values`]: () => z.input<TSchema>;
+} & {
+    [K in `use${Capitalize<N>}Fields`]: BoundUseFields<TSchema, D>;
+}>;
+type BoundUseFields<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = <const P extends readonly FieldPath<z.input<TSchema>, D>[]>(paths: P) => UseFieldsReturn<{
+    readonly [K in keyof P]: UseFieldReturn<FieldValue<z.input<TSchema>, P[K] & string>>;
 }>;
 declare const createFormHooks: <TSchema extends z.ZodType, N extends string = "", D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, name?: N) => FormHooks<TSchema, N, D>;
 
@@ -209,6 +243,10 @@ declare function useIsValid(form: FormStateApi & {
     readonly schema?: undefined;
 }, path?: string): boolean;
 declare function useIsValid<TSchema extends z.ZodType, P extends FieldPath<z.input<TSchema>, D>, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, path?: P): boolean;
+declare function useIsValidating(form: FormStateApi & {
+    readonly schema?: undefined;
+}, path?: string): boolean;
+declare function useIsValidating<TSchema extends z.ZodType, P extends FieldPath<z.input<TSchema>, D>, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, path?: P): boolean;
 declare const useIsSubmitting: (form: FormStateApi) => boolean;
 declare const useSubmitCount: (form: FormStateApi) => number;
 
@@ -341,4 +379,4 @@ declare const dateInputProps: <T extends Date | null | undefined>(field: UseFiel
 declare const checkboxProps: <T extends boolean | null | undefined>(field: UseFieldReturn<T>) => CheckboxProps;
 declare const selectProps: <T extends string | null | undefined>(field: UseFieldReturn<T>) => SelectProps;
 
-export { type BoundUseField, type BoundUseFieldArray, type BoundUseFlag, type BoundUseSelector, CheckboxField, type CheckboxFieldProps, type CheckboxProps, CreateFormOptions, DateField, type DateFieldProps, type DateInputProps, DefaultPathDepth, ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, FieldPath, type FieldPathArg, type FieldRef, FieldValidationResult, FieldValue, Form, type FormContextApi, type FormHooks, type FormProviderProps, FormState, type FormStateApi, NumberField, type NumberFieldProps, type NumberInputBinding, type NumberInputProps, type ParsedDateText, type ParsedNumberText, PathDepth, type PathSegment, type PathsOf, type PersistHandle, type PersistOptions, type PersistStorage, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, checkboxProps, createFormContext, createFormHooks, dateInputProps, dateToInputText, focusField, focusFirstError, getAtPath, hasFieldError, numberInputProps, numberToInputText, parseDateText, parseNumberText, parsePath, persistForm, selectProps, setAtPath, textInputProps, useField, useFieldArray, useForm, useFormError, useFormSelector, useFormSelectorShallow, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useNumberInput, useSubmitCount, useVariantField };
+export { type BoundUseField, type BoundUseFieldArray, type BoundUseFlag, type BoundUseSelector, CheckboxField, type CheckboxFieldProps, type CheckboxProps, CreateFormOptions, DateField, type DateFieldProps, type DateInputProps, DefaultPathDepth, ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, FieldPath, type FieldPathArg, type FieldRef, FieldValidationResult, FieldValue, Form, type FormContextApi, type FormHooks, type FormProviderProps, FormState, type FormStateApi, NumberField, type NumberFieldProps, type NumberInputBinding, type NumberInputProps, type ParsedDateText, type ParsedNumberText, PathDepth, type PathSegment, type PathsOf, type PersistHandle, type PersistOptions, type PersistStorage, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, SettledFieldValidationResult, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, type UseFieldsReturn, checkboxProps, createFormContext, createFormHooks, dateInputProps, dateToInputText, focusField, focusFirstError, getAtPath, hasFieldError, numberInputProps, numberToInputText, parseDateText, parseNumberText, parsePath, persistForm, selectProps, setAtPath, textInputProps, useField, useFieldArray, useFields, useForm, useFormError, useFormSelector, useFormSelectorShallow, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useNumberInput, usePersistForm, useSubmitCount, useVariantField };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PathDepth, D as DefaultPathDepth, F as Form, C as CreateFormOptions, a as FieldValidationResult, b as FormState, c as FieldPath, d as FieldValue, E as ErrorMap } from './createForm-jlzK2lCG.js';
-export { B as BoolMap, e as FieldSnapshot, f as FieldsValidationResult, I as InvalidSubmitHandler, R as ReadonlyStoreApi, g as ResetOptions, S as SettledFieldValidationResult, h as SettledFieldsValidationResult, i as SettledValidationResult, j as SubmitHandler, k as SubmitOptions, l as SubmitResult, V as ValidationMode, m as ValidationResult, n as ValidationTrigger, o as createForm, p as emptyValueForSchema, q as flattenIssues, r as isAsyncRequiredError, s as shouldValidateOn, v as validateAsync, t as validateSync } from './createForm-jlzK2lCG.js';
+import { P as PathDepth, D as DefaultPathDepth, F as Form, C as CreateFormOptions, a as FieldValidationResult, S as SettledFieldValidationResult, b as FormState, c as FieldPath, d as FieldValue, E as ErrorMap } from './createForm-D0xLZH-Q.js';
+export { B as BoolMap, e as FieldSnapshot, f as FieldsValidationResult, I as InvalidSubmitHandler, R as ReadonlyStoreApi, g as ResetOptions, h as SettledFieldsValidationResult, i as SettledValidationResult, j as SubmitHandler, k as SubmitOptions, l as SubmitResult, V as ValidationMode, m as ValidationResult, n as ValidationTrigger, o as createForm, p as emptyValueForSchema, q as flattenIssues, r as isAsyncRequiredError, s as shouldValidateOn, v as validateAsync, t as validateSync } from './createForm-D0xLZH-Q.js';
 import { z } from 'zod';
 import * as react from 'react';
 import { ReactNode, ChangeEvent } from 'react';
@@ -29,6 +29,8 @@ type PersistHandle = Readonly<{
 }>;
 declare const persistForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, options: PersistOptions<TSchema>) => PersistHandle;
 
+declare const usePersistForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, options: PersistOptions<TSchema>) => PersistHandle;
+
 declare const useForm: <TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth>(schema: TSchema, options: CreateFormOptions<TSchema, D>) => Form<TSchema, D>;
 
 type FormProviderProps<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = Readonly<{
@@ -49,7 +51,7 @@ type FieldFormApi = Readonly<{
     setError(path: string, errors: string | readonly string[]): void;
     clearErrors(path?: string): void;
     validateField(path: string): FieldValidationResult;
-    validateFieldAsync(path: string): Promise<FieldValidationResult>;
+    validateFieldAsync(path: string): Promise<SettledFieldValidationResult>;
 }>;
 type FieldPathArg<TValues> = string | ((state: FormState<TValues>) => string);
 type UseFieldOptions = Readonly<{
@@ -61,6 +63,7 @@ type UseFieldReturn<TValue> = Readonly<{
     initialValue: TValue;
     emptyValue: null | undefined;
     error: readonly string[] | undefined;
+    firstError: string | undefined;
     touched: boolean;
     dirty: boolean;
     isValidating: boolean;
@@ -69,7 +72,7 @@ type UseFieldReturn<TValue> = Readonly<{
     setError: (errors: string | readonly string[]) => void;
     clearError: () => void;
     validate: () => FieldValidationResult;
-    validateAsync: () => Promise<FieldValidationResult>;
+    validateAsync: () => Promise<SettledFieldValidationResult>;
     onBlur: () => void;
 }>;
 declare const inferredCallsOnly$2: unique symbol;
@@ -92,7 +95,7 @@ type VariantFieldValue<V, TField extends string> = V extends unknown ? TField ex
 type CommonKeys<V> = keyof V;
 type AllKeys<V> = V extends unknown ? keyof V : never;
 type VariantKeys<V> = Exclude<AllKeys<V>, CommonKeys<V>> & string;
-type UnionValueAt<TValues, P extends string> = P extends keyof TValues ? NonNullable<TValues[P]> : P extends `${infer Head}.${infer Tail}` ? Head extends keyof TValues ? UnionValueAt<NonNullable<TValues[Head]>, Tail> : never : never;
+type UnionValueAt<TValues, P extends string> = P extends keyof TValues ? NonNullable<TValues[P]> : TValues extends readonly (infer Item)[] ? P extends `${number}` ? NonNullable<Item> : P extends `${infer Head}.${infer Tail}` ? Head extends keyof TValues ? UnionValueAt<NonNullable<TValues[Head]>, Tail> : Head extends `${number}` ? UnionValueAt<NonNullable<Item>, Tail> : never : never : P extends `${infer Head}.${infer Tail}` ? Head extends keyof TValues ? UnionValueAt<NonNullable<TValues[Head]>, Tail> : never : never;
 declare const inferredCallsOnly$1: unique symbol;
 interface InferredTypeArg$1 {
     readonly [inferredCallsOnly$1]: typeof inferredCallsOnly$1;
@@ -114,16 +117,22 @@ type FieldArrayFormApi = Readonly<{
     arrayMove(path: string, from: number, to: number): void;
     arraySwap(path: string, a: number, b: number): void;
     validateField?(path: string): FieldValidationResult;
+    setError?(path: string, errors: string | readonly string[]): void;
+    clearErrors?(path?: string): void;
 }>;
 type FieldArrayEntry<TItem> = Readonly<{
     id: string;
     value: TItem;
 }>;
 type UseFieldArrayReturn<TItem> = Readonly<{
+    path: string;
     fields: readonly FieldArrayEntry<TItem>[];
     items: readonly TItem[];
     length: number;
     error: readonly string[] | undefined;
+    firstError: string | undefined;
+    setError: (errors: string | readonly string[]) => void;
+    clearError: () => void;
     push: (item: TItem) => void;
     remove: (index: number) => void;
     insert: (index: number, item: TItem) => void;
@@ -147,6 +156,22 @@ declare function useFieldArray<TItem = unknown>(form: FieldArrayFormApi & {
 }, path: FieldPathArg<unknown>): UseFieldArrayReturn<TItem>;
 declare function useFieldArray<TSchema extends z.ZodType, P extends FieldPath<z.input<TSchema>, D>, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, path: P): UseFieldArrayReturn<ArrayItemOf<FieldValue<z.input<TSchema>, P>>>;
 
+type UseFieldsReturn<TFields extends readonly unknown[]> = Readonly<{
+    fields: TFields;
+    error: readonly string[] | undefined;
+    firstError: string | undefined;
+    touched: boolean;
+    dirty: boolean;
+    isValidating: boolean;
+    onBlur: () => void;
+}>;
+declare function useFields(form: FieldFormApi & {
+    readonly schema?: undefined;
+}, paths: readonly string[]): UseFieldsReturn<readonly UseFieldReturn<unknown>[]>;
+declare function useFields<TSchema extends z.ZodType, const P extends readonly FieldPath<z.input<TSchema>, D>[], D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, paths: P): UseFieldsReturn<{
+    readonly [K in keyof P]: UseFieldReturn<FieldValue<z.input<TSchema>, P[K] & string>>;
+}>;
+
 type BoundUseField<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = {
     (pathSelector: (state: FormState<z.input<TSchema>>) => string, options?: UseFieldOptions): UseFieldReturn<unknown>;
     <P extends FieldPath<z.input<TSchema>, D>>(path: P, options?: UseFieldOptions): UseFieldReturn<FieldValue<z.input<TSchema>, P>>;
@@ -174,10 +199,19 @@ type FormHooks<TSchema extends z.ZodType, N extends string, D extends PathDepth
     [K in `use${Capitalize<N>}IsDirty`]: BoundUseFlag<TSchema, D>;
 } & {
     [K in `use${Capitalize<N>}IsValid`]: BoundUseFlag<TSchema, D>;
+} & {
+    [K in `use${Capitalize<N>}IsValidating`]: BoundUseFlag<TSchema, D>;
 } & {
     [K in `use${Capitalize<N>}IsSubmitting`]: () => boolean;
 } & {
     [K in `use${Capitalize<N>}SubmitCount`]: () => number;
+} & {
+    [K in `use${Capitalize<N>}Values`]: () => z.input<TSchema>;
+} & {
+    [K in `use${Capitalize<N>}Fields`]: BoundUseFields<TSchema, D>;
+}>;
+type BoundUseFields<TSchema extends z.ZodType, D extends PathDepth = DefaultPathDepth> = <const P extends readonly FieldPath<z.input<TSchema>, D>[]>(paths: P) => UseFieldsReturn<{
+    readonly [K in keyof P]: UseFieldReturn<FieldValue<z.input<TSchema>, P[K] & string>>;
 }>;
 declare const createFormHooks: <TSchema extends z.ZodType, N extends string = "", D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, name?: N) => FormHooks<TSchema, N, D>;
 
@@ -209,6 +243,10 @@ declare function useIsValid(form: FormStateApi & {
     readonly schema?: undefined;
 }, path?: string): boolean;
 declare function useIsValid<TSchema extends z.ZodType, P extends FieldPath<z.input<TSchema>, D>, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, path?: P): boolean;
+declare function useIsValidating(form: FormStateApi & {
+    readonly schema?: undefined;
+}, path?: string): boolean;
+declare function useIsValidating<TSchema extends z.ZodType, P extends FieldPath<z.input<TSchema>, D>, D extends PathDepth = DefaultPathDepth>(form: Form<TSchema, D>, path?: P): boolean;
 declare const useIsSubmitting: (form: FormStateApi) => boolean;
 declare const useSubmitCount: (form: FormStateApi) => number;
 
@@ -341,4 +379,4 @@ declare const dateInputProps: <T extends Date | null | undefined>(field: UseFiel
 declare const checkboxProps: <T extends boolean | null | undefined>(field: UseFieldReturn<T>) => CheckboxProps;
 declare const selectProps: <T extends string | null | undefined>(field: UseFieldReturn<T>) => SelectProps;
 
-export { type BoundUseField, type BoundUseFieldArray, type BoundUseFlag, type BoundUseSelector, CheckboxField, type CheckboxFieldProps, type CheckboxProps, CreateFormOptions, DateField, type DateFieldProps, type DateInputProps, DefaultPathDepth, ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, FieldPath, type FieldPathArg, type FieldRef, FieldValidationResult, FieldValue, Form, type FormContextApi, type FormHooks, type FormProviderProps, FormState, type FormStateApi, NumberField, type NumberFieldProps, type NumberInputBinding, type NumberInputProps, type ParsedDateText, type ParsedNumberText, PathDepth, type PathSegment, type PathsOf, type PersistHandle, type PersistOptions, type PersistStorage, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, checkboxProps, createFormContext, createFormHooks, dateInputProps, dateToInputText, focusField, focusFirstError, getAtPath, hasFieldError, numberInputProps, numberToInputText, parseDateText, parseNumberText, parsePath, persistForm, selectProps, setAtPath, textInputProps, useField, useFieldArray, useForm, useFormError, useFormSelector, useFormSelectorShallow, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useNumberInput, useSubmitCount, useVariantField };
+export { type BoundUseField, type BoundUseFieldArray, type BoundUseFlag, type BoundUseSelector, CheckboxField, type CheckboxFieldProps, type CheckboxProps, CreateFormOptions, DateField, type DateFieldProps, type DateInputProps, DefaultPathDepth, ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, FieldPath, type FieldPathArg, type FieldRef, FieldValidationResult, FieldValue, Form, type FormContextApi, type FormHooks, type FormProviderProps, FormState, type FormStateApi, NumberField, type NumberFieldProps, type NumberInputBinding, type NumberInputProps, type ParsedDateText, type ParsedNumberText, PathDepth, type PathSegment, type PathsOf, type PersistHandle, type PersistOptions, type PersistStorage, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, SettledFieldValidationResult, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, type UseFieldsReturn, checkboxProps, createFormContext, createFormHooks, dateInputProps, dateToInputText, focusField, focusFirstError, getAtPath, hasFieldError, numberInputProps, numberToInputText, parseDateText, parseNumberText, parsePath, persistForm, selectProps, setAtPath, textInputProps, useField, useFieldArray, useFields, useForm, useFormError, useFormSelector, useFormSelectorShallow, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useNumberInput, usePersistForm, useSubmitCount, useVariantField };

package/dist/index.js

@@ -3,7 +3,7 @@ export { getAtPath, parsePath, setAtPath, useFormSelector, useFormSelectorShallo
 import { createStore } from 'zustand/vanilla';
 import { devtools } from 'zustand/middleware';
 import { z } from 'zod';
-import { useRef, useEffect, createContext, useMemo, useCallback, useState, useContext, useId } from 'react';
+import { useRef, useEffect, useMemo, createContext, useCallback, useState, useContext, useId } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 import { useStore } from 'zustand/react';
 import { useShallow } from 'zustand/react/shallow';
@@ -163,7 +163,7 @@ var schemaHasPath = (schema, path) => {
     if (head === void 0) return true;
     if (s instanceof z.ZodObject) {
       const shape = s.shape;
-      const child = shape[String(head)];
+      const child = Object.hasOwn(shape, String(head)) ? shape[String(head)] : void 0;
       if (child !== void 0) return walk(child, rest, budget - 1);
       const catchall = s.def.catchall;
       return catchall !== void 0 && !(catchall instanceof z.ZodNever);
@@ -183,7 +183,7 @@ var fieldSchemaAtPath = (schema, path) => parsePath(path).reduce((current, segme
   if (current === null || hasChecks(current)) return null;
   if (current instanceof z.ZodObject && typeof segment === "string") {
     const shape = current.shape;
-    return shape[segment] ?? null;
+    return Object.hasOwn(shape, segment) ? shape[segment] ?? null : null;
   }
   if (current instanceof z.ZodArray && typeof segment === "number") {
     return current.element;
@@ -588,7 +588,7 @@ var createForm = (schema, options) => {
   };
   const applyArrayOp = (path, nextArray, mapper, indexInBounds) => {
     const current = getAtPath(store.getState().values, path);
-    if (current !== void 0 && !Array.isArray(current)) {
+    if (current !== void 0 && current !== null && !Array.isArray(current)) {
       console.warn(
         `[formstand] array op on "${path}" but the value at that path is not an array (got ${typeof current}). Operation skipped.`
       );
@@ -697,6 +697,7 @@ var createForm = (schema, options) => {
       try {
         await onValid(result.data);
       } catch (error) {
+        submitOptions?.onError?.(error);
         return { kind: "error", error };
       }
       return { kind: "valid", data: result.data };
@@ -804,6 +805,17 @@ var createForm = (schema, options) => {
       ...state,
       ...errorChannels(state, { serverErrors: errors })
     })),
+    addErrors: (errors) => store.setState((state) => ({
+      ...state,
+      ...errorChannels(state, {
+        serverErrors: Object.entries(errors).reduce(
+          // Computed keys throughout, so a server field named
+          // "__proto__" lands as an own property like everywhere else.
+          (acc, [key, list]) => list === void 0 || list.length === 0 ? omitKey(acc, key) : { ...acc, [key]: list },
+          state.serverErrors
+        )
+      })
+    })),
     clearErrors: (path) => store.setState((state) => {
       const scrub = (map) => path === void 0 ? emptyErrors : omitScope(map, [path]);
       return {
@@ -943,7 +955,14 @@ var createForm = (schema, options) => {
     ),
     handleSubmit: (onValid, onInvalid, opts) => async (event) => {
       event?.preventDefault();
-      return submit(onValid, onInvalid, opts);
+      const result = await submit(onValid, onInvalid, opts);
+      if (result.kind === "error" && opts?.onError === void 0 && process.env.NODE_ENV !== "production") {
+        console.warn(
+          "[formstand] submit handler threw and nothing observed it \u2014 the form shows no feedback. Pass { onError } to handleSubmit (or setError inside your handler):",
+          result.error
+        );
+      }
+      return result;
     },
     diff: () => {
       const state = store.getState();
@@ -1051,6 +1070,9 @@ var persistForm = (form, options) => {
       const parsed = JSON.parse(raw);
       const versioned = options.version !== void 0 && typeof parsed === "object" && parsed !== null && "__v" in parsed;
       if (options.version !== void 0 && !versioned) return false;
+      if (options.version === void 0 && typeof parsed === "object" && parsed !== null && Object.hasOwn(parsed, "__v") && Object.hasOwn(parsed, "values")) {
+        return false;
+      }
       const wrapper = parsed;
       if (versioned && wrapper.__v !== options.version) return false;
       if (versioned && wrapper.values === void 0) return false;
@@ -1114,6 +1136,33 @@ var persistForm = (form, options) => {
     }
   });
 };
+var usePersistForm = (form, options) => {
+  const inner = useRef(null);
+  const latestOptions = useRef(options);
+  useEffect(() => {
+    latestOptions.current = options;
+  });
+  const key = options.key;
+  useEffect(() => {
+    const handle = persistForm(form, latestOptions.current);
+    inner.current = handle;
+    return () => {
+      inner.current = null;
+      handle.dispose();
+    };
+  }, [form, key]);
+  return useMemo(
+    () => ({
+      restore: () => inner.current?.restore() ?? false,
+      clear: () => inner.current?.clear(),
+      // dispose stops THIS component's watching early; the effect cleanup
+      // still runs its own dispose harmlessly (persistForm's dispose is
+      // idempotent by construction — it only cancels and unsubscribes).
+      dispose: () => inner.current?.dispose()
+    }),
+    []
+  );
+};
 var useForm = (schema, options) => {
   const formRef = useRef(null);
   if (formRef.current === null) {
@@ -1190,9 +1239,13 @@ function useField(form, pathArg, options) {
       if (debounceTimerRef.current !== null) {
         clearTimeout(debounceTimerRef.current);
       }
+      const scheduled = getAtPath(form.store.getState().values, path);
       debounceTimerRef.current = setTimeout(() => {
-        void form.validateFieldAsync(path);
         debounceTimerRef.current = null;
+        const state = form.store.getState();
+        if (state.values === state.initialValues) return;
+        if (!Object.is(getAtPath(state.values, path), scheduled)) return;
+        void form.validateFieldAsync(path);
       }, debounceMs);
       return;
     }
@@ -1256,6 +1309,8 @@ function useField(form, pathArg, options) {
       initialValue: slice.initialValue,
       emptyValue,
       error: slice.error,
+      // `?.[0]` covers both the undefined channel and an empty array.
+      firstError: slice.error?.[0],
       touched: slice.touched,
       dirty: slice.dirty,
       isValidating: slice.isValidating,
@@ -1451,25 +1506,64 @@ function useFieldArray(form, pathArg) {
     })),
     [items, ids]
   );
+  const setError = useCallback(
+    // Same string-shorthand normalization as useField.setError, so custom
+    // implementations typed for readonly string[] never receive a bare
+    // string.
+    (errors) => form.setError?.(path, typeof errors === "string" ? [errors] : errors),
+    [form, path]
+  );
+  const clearError = useCallback(() => form.clearErrors?.(path), [form, path]);
   return useMemo(
     () => ({
+      path,
       fields,
       items,
       length: items.length,
       error,
+      firstError: error?.[0],
+      setError,
+      clearError,
       push,
       remove,
       insert,
       move,
       swap
     }),
-    [fields, items, error, push, remove, insert, move, swap]
+    [path, fields, items, error, setError, clearError, push, remove, insert, move, swap]
   );
 }
 var useFormError = (form) => useStore(
   form.store,
   useShallow((state) => state.errors[""])
 );
+function useFormValues(form) {
+  return useStore(form.store, (state) => state.values);
+}
+
+// src/react/useFields.ts
+function useFields(form, paths) {
+  const fields = paths.map(
+    (path) => (
+      // eslint-disable-next-line react-hooks/rules-of-hooks -- a fixed hook count by the stable-arity contract above; each element must be a REAL UseFieldReturn so it spreads into the prop builders
+      useField(form, path)
+    )
+  );
+  const merged = [...new Set(fields.flatMap((field) => field.error ?? []))];
+  return {
+    fields,
+    error: merged.length > 0 ? merged : void 0,
+    firstError: merged[0],
+    touched: fields.some((field) => field.touched),
+    dirty: fields.some((field) => field.dirty),
+    isValidating: fields.some((field) => field.isValidating),
+    onBlur: () => {
+      fields.forEach((field) => {
+        field.onBlur();
+      });
+    }
+  };
+}
 function useIsDirty(form, path) {
   return useStore(
     form.store,
@@ -1490,6 +1584,19 @@ function useIsValid(form, path) {
     return true;
   });
 }
+function useIsValidating(form, path) {
+  return useStore(form.store, (state) => {
+    if (path === void 0 || path === "") {
+      if (state.isValidatingForm) return true;
+    }
+    for (const k in state.isValidating) {
+      if (state.isValidating[k] === true && (path === void 0 || path === "" || isPathOrChild(k, path))) {
+        return true;
+      }
+    }
+    return false;
+  });
+}
 var useIsSubmitting = (form) => useStore(form.store, (state) => state.isSubmitting);
 var useSubmitCount = (form) => useStore(form.store, (state) => state.submitCount);
 
@@ -1509,7 +1616,13 @@ var createFormHooks = (form, name) => {
   const useBoundError = () => useFormError(structural);
   const useBoundIsDirty = (path) => useIsDirty(structural, path);
   const useBoundIsValid = (path) => useIsValid(structural, path);
+  const useBoundIsValidating = (path) => useIsValidating(structural, path);
   const useBoundIsSubmitting = () => useIsSubmitting(structural);
+  const useBoundValues = () => useFormValues(structural);
+  const useBoundFields = (paths) => useFields(
+    structural,
+    paths
+  );
   const useBoundSubmitCount = () => useSubmitCount(structural);
   const prefix = capitalize(name ?? "");
   return {
@@ -1521,13 +1634,13 @@ var createFormHooks = (form, name) => {
     [`use${prefix}Error`]: useBoundError,
     [`use${prefix}IsDirty`]: useBoundIsDirty,
     [`use${prefix}IsValid`]: useBoundIsValid,
+    [`use${prefix}IsValidating`]: useBoundIsValidating,
     [`use${prefix}IsSubmitting`]: useBoundIsSubmitting,
-    [`use${prefix}SubmitCount`]: useBoundSubmitCount
+    [`use${prefix}SubmitCount`]: useBoundSubmitCount,
+    [`use${prefix}Values`]: useBoundValues,
+    [`use${prefix}Fields`]: useBoundFields
   };
 };
-function useFormValues(form) {
-  return useStore(form.store, (state) => state.values);
-}
 
 // src/react/inputProps.ts
 var hasFieldError = (error) => error !== void 0 && error.length > 0;
@@ -1557,6 +1670,7 @@ var numberInputProps = (field) => ({
   "aria-invalid": ariaInvalid(field),
   onChange: (e) => {
     const parsed = parseNumberText(e.target.value);
+    if (parsed.kind === "invalid") return;
     field.setValue(
       parsed.kind === "number" ? parsed.value : field.emptyValue
     );
@@ -1917,6 +2031,6 @@ var focusField = (path, root) => {
   return path === "" ? (root !== void 0 || document.querySelectorAll("form").length <= 1) && focusFirstOf(namedControls(scope).filter(isFocusCandidate)) : focusFirstOf(pathCandidates(scope, [path]).filter(isFocusCandidate));
 };
 
-export { CheckboxField, DateField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, createFormHooks, dateInputProps, dateToInputText, emptyValueForSchema, flattenIssues, focusField, focusFirstError, hasFieldError, isAsyncRequiredError, numberInputProps, numberToInputText, parseDateText, parseNumberText, persistForm, selectProps, shouldValidateOn, textInputProps, useField, useFieldArray, useForm, useFormError, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useNumberInput, useSubmitCount, useVariantField, validateAsync, validateSync };
+export { CheckboxField, DateField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, createFormHooks, dateInputProps, dateToInputText, emptyValueForSchema, flattenIssues, focusField, focusFirstError, hasFieldError, isAsyncRequiredError, numberInputProps, numberToInputText, parseDateText, parseNumberText, persistForm, selectProps, shouldValidateOn, textInputProps, useField, useFieldArray, useFields, useForm, useFormError, useFormValues, useIsDirty, useIsSubmitting, useIsValid, useIsValidating, useNumberInput, usePersistForm, useSubmitCount, useVariantField, validateAsync, validateSync };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map