formstand 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -59,6 +59,7 @@ declare const flattenIssues: (issues: readonly z.core.$ZodIssue[]) => ErrorMap;
 declare const validateSync: <TSchema extends z.ZodType>(schema: TSchema, values: z.input<TSchema>) => SettledValidationResult<z.output<TSchema>>;
 declare const validateAsync: <TSchema extends z.ZodType>(schema: TSchema, values: z.input<TSchema>) => Promise<SettledValidationResult<z.output<TSchema>>>;
 declare const isAsyncRequiredError: (e: unknown) => boolean;
+declare const emptyValueForSchema: (schema: z.ZodType) => null | undefined;
 
 type ReadonlyStoreApi<T> = Pick<StoreApi<T>, "getState" | "getInitialState" | "subscribe">;
 type CreateFormOptions<TSchema extends z.ZodType> = Readonly<{
@@ -80,6 +81,9 @@ type SubmitResult<TOutput> = Readonly<{
     errors: ErrorMap;
 }> | Readonly<{
     kind: "skipped";
+}> | Readonly<{
+    kind: "error";
+    error: unknown;
 }>;
 type ArrayItemOf<T> = T extends readonly (infer U)[] ? U : never;
 type ErrorPath<TValues> = FieldPath<TValues> | "";
@@ -169,14 +173,6 @@ declare function useFormSelectorShallow<TSchema extends z.ZodType, U>(form: Form
 declare function useFormSelectorShallow<U>(form: FormStateApi & {
     readonly schema?: undefined;
 }, selector: (state: FormState<unknown>) => U): U;
-/**
- * @deprecated Renamed to `useFormSelector` — React DOM ships its own
- * (deprecated) `useFormState`, and auto-imports regularly grab the wrong one.
- * This alias will be removed before 1.0.
- */
-declare const useFormState: typeof useFormSelector;
-/** @deprecated Renamed to `useFormSelectorShallow`; see `useFormState`. */
-declare const useFormStateShallow: typeof useFormSelectorShallow;
 
 declare const useFormError: (form: FormStateApi) => readonly string[] | undefined;
 
@@ -190,7 +186,7 @@ type FieldFormApi = Readonly<{
     store: ReadonlyStore$1<FormState<unknown>>;
     setValue(path: string, value: unknown): void;
     setTouched(path: string, touched?: boolean): void;
-    setError(path: string, errors: readonly string[]): void;
+    setError(path: string, errors: string | readonly string[]): void;
     clearErrors(path?: string): void;
     validateField(path: string): FieldValidationResult;
     validateFieldAsync(path: string): Promise<FieldValidationResult>;
@@ -210,61 +206,63 @@ type UseFieldReturn<TValue> = Readonly<{
     isValidating: boolean;
     setValue: (value: TValue) => void;
     setTouched: (touched?: boolean) => void;
-    setError: (errors: readonly string[]) => void;
+    setError: (errors: string | readonly string[]) => void;
     clearError: () => void;
     validate: () => FieldValidationResult;
     validateAsync: () => Promise<FieldValidationResult>;
     onBlur: () => void;
 }>;
-declare function useField<TSchema extends z.ZodType, P extends FieldPath<z.input<TSchema>>>(form: Form<TSchema>, path: P, options?: UseFieldOptions): UseFieldReturn<FieldValue<z.input<TSchema>, P>>;
 declare function useField<TSchema extends z.ZodType>(form: Form<TSchema>, pathSelector: (state: FormState<z.input<TSchema>>) => string, options?: UseFieldOptions): UseFieldReturn<unknown>;
 declare function useField<TValue = unknown>(form: FieldFormApi & {
     readonly schema?: undefined;
 }, path: string | ((state: FormState<unknown>) => string), options?: UseFieldOptions): UseFieldReturn<TValue>;
+declare function useField<TSchema extends z.ZodType, P extends FieldPath<z.input<TSchema>>>(form: Form<TSchema>, path: P, options?: UseFieldOptions): UseFieldReturn<FieldValue<z.input<TSchema>, P>>;
 
+type PathsOf<F extends FieldFormApi> = F extends Form<infer TSchema extends z.ZodType> ? FieldPath<z.input<TSchema>> : string;
 type FieldRef<T> = ((instance: T | null) => void) | Readonly<{
     current: T | null;
 }> | null;
-type TextFieldProps = Readonly<{
-    form: FieldFormApi;
-    path: string;
+type TextFieldProps<F extends FieldFormApi = FieldFormApi> = Readonly<{
+    form: F;
+    path: PathsOf<F>;
     label?: ReactNode;
     placeholder?: string;
     type?: "text" | "password" | "email" | "url" | "tel";
     autoComplete?: string;
     ref?: FieldRef<HTMLInputElement>;
 }>;
-declare const TextField: ({ form, path, label, placeholder, type, autoComplete, ref, }: TextFieldProps) => react.JSX.Element;
-type NumberFieldProps = Readonly<{
-    form: FieldFormApi;
-    path: string;
+declare const TextField: <F extends FieldFormApi>({ form, path, label, placeholder, type, autoComplete, ref, }: TextFieldProps<F>) => react.JSX.Element;
+type NumberFieldProps<F extends FieldFormApi = FieldFormApi> = Readonly<{
+    form: F;
+    path: PathsOf<F>;
     label?: ReactNode;
     placeholder?: string;
     ref?: FieldRef<HTMLInputElement>;
 }>;
-declare const NumberField: ({ form, path, label, placeholder, ref, }: NumberFieldProps) => react.JSX.Element;
-type CheckboxFieldProps = Readonly<{
-    form: FieldFormApi;
-    path: string;
+declare const NumberField: <F extends FieldFormApi>({ form, path, label, placeholder, ref, }: NumberFieldProps<F>) => react.JSX.Element;
+type CheckboxFieldProps<F extends FieldFormApi = FieldFormApi> = Readonly<{
+    form: F;
+    path: PathsOf<F>;
     label?: ReactNode;
     ref?: FieldRef<HTMLInputElement>;
 }>;
-declare const CheckboxField: ({ form, path, label, ref }: CheckboxFieldProps) => react.JSX.Element;
+declare const CheckboxField: <F extends FieldFormApi>({ form, path, label, ref, }: CheckboxFieldProps<F>) => react.JSX.Element;
 type SelectFieldOption<T extends string> = Readonly<{
     value: T;
     label: ReactNode;
 }>;
-type SelectFieldProps<T extends string> = Readonly<{
-    form: FieldFormApi;
-    path: string;
+type SelectFieldProps<T extends string, F extends FieldFormApi = FieldFormApi> = Readonly<{
+    form: F;
+    path: PathsOf<F>;
     label?: ReactNode;
     options: readonly SelectFieldOption<T>[];
     placeholder?: string;
     ref?: FieldRef<HTMLSelectElement>;
 }>;
-declare const SelectField: <T extends string>({ form, path, label, options, placeholder, ref, }: SelectFieldProps<T>) => react.JSX.Element;
+declare const SelectField: <T extends string, F extends FieldFormApi>({ form, path, label, options, placeholder, ref, }: SelectFieldProps<T, F>) => react.JSX.Element;
 
 declare const focusFirstError: (errors: ErrorMap, root?: ParentNode) => boolean;
+declare const focusField: (path: string, root?: ParentNode) => boolean;
 
 type ReadonlyStore<T> = Pick<StoreApi<T>, "getState" | "getInitialState" | "subscribe">;
 type FieldArrayFormApi = Readonly<{
@@ -322,9 +320,19 @@ type SelectProps = Readonly<{
     onChange: (e: ChangeEvent<HTMLSelectElement>) => void;
     onBlur: () => void;
 }>;
+declare const numberToInputText: (value: number | null | undefined) => string;
+type ParsedNumberText = Readonly<{
+    kind: "empty";
+}> | Readonly<{
+    kind: "number";
+    value: number;
+}> | Readonly<{
+    kind: "invalid";
+}>;
+declare const parseNumberText: (text: string) => ParsedNumberText;
 declare const textInputProps: <T extends string | null | undefined>(field: UseFieldReturn<T>) => TextInputProps;
 declare const numberInputProps: <T extends number | null | undefined>(field: UseFieldReturn<T>) => NumberInputProps;
 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 BoolMap, CheckboxField, type CheckboxFieldProps, type CheckboxProps, type CreateFormOptions, type ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, type FieldPath, type FieldPathArg, type FieldRef, type FieldSnapshot, type FieldValidationResult, type FieldValue, type Form, type FormContextApi, type FormProviderProps, type FormState, type FormStateApi, type InvalidSubmitHandler, NumberField, type NumberFieldProps, type NumberInputProps, type PathSegment, type ReadonlyStoreApi, type ResetOptions, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, type SettledFieldValidationResult, type SettledValidationResult, type SubmitHandler, type SubmitOptions, type SubmitResult, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, type ValidationMode, type ValidationResult, type ValidationTrigger, checkboxProps, createForm, createFormContext, flattenIssues, focusFirstError, getAtPath, isAsyncRequiredError, numberInputProps, parsePath, selectProps, setAtPath, shouldValidateOn, textInputProps, useField, useFieldArray, useForm, useFormError, useFormSelector, useFormSelectorShallow, useFormState, useFormStateShallow, useIsDirty, useIsSubmitting, useIsValid, useSubmitCount, validateAsync, validateSync };
+export { type BoolMap, CheckboxField, type CheckboxFieldProps, type CheckboxProps, type CreateFormOptions, type ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, type FieldPath, type FieldPathArg, type FieldRef, type FieldSnapshot, type FieldValidationResult, type FieldValue, type Form, type FormContextApi, type FormProviderProps, type FormState, type FormStateApi, type InvalidSubmitHandler, NumberField, type NumberFieldProps, type NumberInputProps, type ParsedNumberText, type PathSegment, type PathsOf, type ReadonlyStoreApi, type ResetOptions, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, type SettledFieldValidationResult, type SettledValidationResult, type SubmitHandler, type SubmitOptions, type SubmitResult, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, type ValidationMode, type ValidationResult, type ValidationTrigger, checkboxProps, createForm, createFormContext, emptyValueForSchema, flattenIssues, focusField, focusFirstError, getAtPath, isAsyncRequiredError, numberInputProps, numberToInputText, parseNumberText, parsePath, selectProps, setAtPath, shouldValidateOn, textInputProps, useField, useFieldArray, useForm, useFormError, useFormSelector, useFormSelectorShallow, useIsDirty, useIsSubmitting, useIsValid, useSubmitCount, validateAsync, validateSync };

package/dist/index.d.ts

@@ -59,6 +59,7 @@ declare const flattenIssues: (issues: readonly z.core.$ZodIssue[]) => ErrorMap;
 declare const validateSync: <TSchema extends z.ZodType>(schema: TSchema, values: z.input<TSchema>) => SettledValidationResult<z.output<TSchema>>;
 declare const validateAsync: <TSchema extends z.ZodType>(schema: TSchema, values: z.input<TSchema>) => Promise<SettledValidationResult<z.output<TSchema>>>;
 declare const isAsyncRequiredError: (e: unknown) => boolean;
+declare const emptyValueForSchema: (schema: z.ZodType) => null | undefined;
 
 type ReadonlyStoreApi<T> = Pick<StoreApi<T>, "getState" | "getInitialState" | "subscribe">;
 type CreateFormOptions<TSchema extends z.ZodType> = Readonly<{
@@ -80,6 +81,9 @@ type SubmitResult<TOutput> = Readonly<{
     errors: ErrorMap;
 }> | Readonly<{
     kind: "skipped";
+}> | Readonly<{
+    kind: "error";
+    error: unknown;
 }>;
 type ArrayItemOf<T> = T extends readonly (infer U)[] ? U : never;
 type ErrorPath<TValues> = FieldPath<TValues> | "";
@@ -169,14 +173,6 @@ declare function useFormSelectorShallow<TSchema extends z.ZodType, U>(form: Form
 declare function useFormSelectorShallow<U>(form: FormStateApi & {
     readonly schema?: undefined;
 }, selector: (state: FormState<unknown>) => U): U;
-/**
- * @deprecated Renamed to `useFormSelector` — React DOM ships its own
- * (deprecated) `useFormState`, and auto-imports regularly grab the wrong one.
- * This alias will be removed before 1.0.
- */
-declare const useFormState: typeof useFormSelector;
-/** @deprecated Renamed to `useFormSelectorShallow`; see `useFormState`. */
-declare const useFormStateShallow: typeof useFormSelectorShallow;
 
 declare const useFormError: (form: FormStateApi) => readonly string[] | undefined;
 
@@ -190,7 +186,7 @@ type FieldFormApi = Readonly<{
     store: ReadonlyStore$1<FormState<unknown>>;
     setValue(path: string, value: unknown): void;
     setTouched(path: string, touched?: boolean): void;
-    setError(path: string, errors: readonly string[]): void;
+    setError(path: string, errors: string | readonly string[]): void;
     clearErrors(path?: string): void;
     validateField(path: string): FieldValidationResult;
     validateFieldAsync(path: string): Promise<FieldValidationResult>;
@@ -210,61 +206,63 @@ type UseFieldReturn<TValue> = Readonly<{
     isValidating: boolean;
     setValue: (value: TValue) => void;
     setTouched: (touched?: boolean) => void;
-    setError: (errors: readonly string[]) => void;
+    setError: (errors: string | readonly string[]) => void;
     clearError: () => void;
     validate: () => FieldValidationResult;
     validateAsync: () => Promise<FieldValidationResult>;
     onBlur: () => void;
 }>;
-declare function useField<TSchema extends z.ZodType, P extends FieldPath<z.input<TSchema>>>(form: Form<TSchema>, path: P, options?: UseFieldOptions): UseFieldReturn<FieldValue<z.input<TSchema>, P>>;
 declare function useField<TSchema extends z.ZodType>(form: Form<TSchema>, pathSelector: (state: FormState<z.input<TSchema>>) => string, options?: UseFieldOptions): UseFieldReturn<unknown>;
 declare function useField<TValue = unknown>(form: FieldFormApi & {
     readonly schema?: undefined;
 }, path: string | ((state: FormState<unknown>) => string), options?: UseFieldOptions): UseFieldReturn<TValue>;
+declare function useField<TSchema extends z.ZodType, P extends FieldPath<z.input<TSchema>>>(form: Form<TSchema>, path: P, options?: UseFieldOptions): UseFieldReturn<FieldValue<z.input<TSchema>, P>>;
 
+type PathsOf<F extends FieldFormApi> = F extends Form<infer TSchema extends z.ZodType> ? FieldPath<z.input<TSchema>> : string;
 type FieldRef<T> = ((instance: T | null) => void) | Readonly<{
     current: T | null;
 }> | null;
-type TextFieldProps = Readonly<{
-    form: FieldFormApi;
-    path: string;
+type TextFieldProps<F extends FieldFormApi = FieldFormApi> = Readonly<{
+    form: F;
+    path: PathsOf<F>;
     label?: ReactNode;
     placeholder?: string;
     type?: "text" | "password" | "email" | "url" | "tel";
     autoComplete?: string;
     ref?: FieldRef<HTMLInputElement>;
 }>;
-declare const TextField: ({ form, path, label, placeholder, type, autoComplete, ref, }: TextFieldProps) => react.JSX.Element;
-type NumberFieldProps = Readonly<{
-    form: FieldFormApi;
-    path: string;
+declare const TextField: <F extends FieldFormApi>({ form, path, label, placeholder, type, autoComplete, ref, }: TextFieldProps<F>) => react.JSX.Element;
+type NumberFieldProps<F extends FieldFormApi = FieldFormApi> = Readonly<{
+    form: F;
+    path: PathsOf<F>;
     label?: ReactNode;
     placeholder?: string;
     ref?: FieldRef<HTMLInputElement>;
 }>;
-declare const NumberField: ({ form, path, label, placeholder, ref, }: NumberFieldProps) => react.JSX.Element;
-type CheckboxFieldProps = Readonly<{
-    form: FieldFormApi;
-    path: string;
+declare const NumberField: <F extends FieldFormApi>({ form, path, label, placeholder, ref, }: NumberFieldProps<F>) => react.JSX.Element;
+type CheckboxFieldProps<F extends FieldFormApi = FieldFormApi> = Readonly<{
+    form: F;
+    path: PathsOf<F>;
     label?: ReactNode;
     ref?: FieldRef<HTMLInputElement>;
 }>;
-declare const CheckboxField: ({ form, path, label, ref }: CheckboxFieldProps) => react.JSX.Element;
+declare const CheckboxField: <F extends FieldFormApi>({ form, path, label, ref, }: CheckboxFieldProps<F>) => react.JSX.Element;
 type SelectFieldOption<T extends string> = Readonly<{
     value: T;
     label: ReactNode;
 }>;
-type SelectFieldProps<T extends string> = Readonly<{
-    form: FieldFormApi;
-    path: string;
+type SelectFieldProps<T extends string, F extends FieldFormApi = FieldFormApi> = Readonly<{
+    form: F;
+    path: PathsOf<F>;
     label?: ReactNode;
     options: readonly SelectFieldOption<T>[];
     placeholder?: string;
     ref?: FieldRef<HTMLSelectElement>;
 }>;
-declare const SelectField: <T extends string>({ form, path, label, options, placeholder, ref, }: SelectFieldProps<T>) => react.JSX.Element;
+declare const SelectField: <T extends string, F extends FieldFormApi>({ form, path, label, options, placeholder, ref, }: SelectFieldProps<T, F>) => react.JSX.Element;
 
 declare const focusFirstError: (errors: ErrorMap, root?: ParentNode) => boolean;
+declare const focusField: (path: string, root?: ParentNode) => boolean;
 
 type ReadonlyStore<T> = Pick<StoreApi<T>, "getState" | "getInitialState" | "subscribe">;
 type FieldArrayFormApi = Readonly<{
@@ -322,9 +320,19 @@ type SelectProps = Readonly<{
     onChange: (e: ChangeEvent<HTMLSelectElement>) => void;
     onBlur: () => void;
 }>;
+declare const numberToInputText: (value: number | null | undefined) => string;
+type ParsedNumberText = Readonly<{
+    kind: "empty";
+}> | Readonly<{
+    kind: "number";
+    value: number;
+}> | Readonly<{
+    kind: "invalid";
+}>;
+declare const parseNumberText: (text: string) => ParsedNumberText;
 declare const textInputProps: <T extends string | null | undefined>(field: UseFieldReturn<T>) => TextInputProps;
 declare const numberInputProps: <T extends number | null | undefined>(field: UseFieldReturn<T>) => NumberInputProps;
 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 BoolMap, CheckboxField, type CheckboxFieldProps, type CheckboxProps, type CreateFormOptions, type ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, type FieldPath, type FieldPathArg, type FieldRef, type FieldSnapshot, type FieldValidationResult, type FieldValue, type Form, type FormContextApi, type FormProviderProps, type FormState, type FormStateApi, type InvalidSubmitHandler, NumberField, type NumberFieldProps, type NumberInputProps, type PathSegment, type ReadonlyStoreApi, type ResetOptions, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, type SettledFieldValidationResult, type SettledValidationResult, type SubmitHandler, type SubmitOptions, type SubmitResult, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, type ValidationMode, type ValidationResult, type ValidationTrigger, checkboxProps, createForm, createFormContext, flattenIssues, focusFirstError, getAtPath, isAsyncRequiredError, numberInputProps, parsePath, selectProps, setAtPath, shouldValidateOn, textInputProps, useField, useFieldArray, useForm, useFormError, useFormSelector, useFormSelectorShallow, useFormState, useFormStateShallow, useIsDirty, useIsSubmitting, useIsValid, useSubmitCount, validateAsync, validateSync };
+export { type BoolMap, CheckboxField, type CheckboxFieldProps, type CheckboxProps, type CreateFormOptions, type ErrorMap, type FieldArrayEntry, type FieldArrayFormApi, type FieldFormApi, type FieldPath, type FieldPathArg, type FieldRef, type FieldSnapshot, type FieldValidationResult, type FieldValue, type Form, type FormContextApi, type FormProviderProps, type FormState, type FormStateApi, type InvalidSubmitHandler, NumberField, type NumberFieldProps, type NumberInputProps, type ParsedNumberText, type PathSegment, type PathsOf, type ReadonlyStoreApi, type ResetOptions, SelectField, type SelectFieldOption, type SelectFieldProps, type SelectProps, type SettledFieldValidationResult, type SettledValidationResult, type SubmitHandler, type SubmitOptions, type SubmitResult, TextField, type TextFieldProps, type TextInputProps, type UseFieldArrayReturn, type UseFieldOptions, type UseFieldReturn, type ValidationMode, type ValidationResult, type ValidationTrigger, checkboxProps, createForm, createFormContext, emptyValueForSchema, flattenIssues, focusField, focusFirstError, getAtPath, isAsyncRequiredError, numberInputProps, numberToInputText, parseNumberText, parsePath, selectProps, setAtPath, shouldValidateOn, textInputProps, useField, useFieldArray, useForm, useFormError, useFormSelector, useFormSelectorShallow, useIsDirty, useIsSubmitting, useIsValid, useSubmitCount, validateAsync, validateSync };

package/dist/index.js

@@ -186,6 +186,39 @@ var emptyValueForSchema = (schema) => {
   };
   return walk(schema, false);
 };
+var unwrapForWalk = (s) => {
+  if (s instanceof z.ZodOptional || s instanceof z.ZodNullable) {
+    return s.unwrap();
+  }
+  if (s instanceof z.ZodDefault || s instanceof z.ZodPrefault || s instanceof z.ZodCatch || s instanceof z.ZodReadonly || s instanceof z.ZodNonOptional) {
+    return s.def.innerType;
+  }
+  if (s instanceof z.ZodPipe) return s.def.in;
+  return null;
+};
+var isLeafSchema = (s) => s instanceof z.ZodString || s instanceof z.ZodNumber || s instanceof z.ZodBoolean || s instanceof z.ZodBigInt || s instanceof z.ZodDate || s instanceof z.ZodEnum || s instanceof z.ZodLiteral || s instanceof z.ZodNull || s instanceof z.ZodUndefined || s instanceof z.ZodVoid || s instanceof z.ZodNaN || s instanceof z.ZodSymbol;
+var SCHEMA_WALK_BUDGET = 64;
+var schemaHasPath = (schema, path) => {
+  const walk = (s, segments, budget) => {
+    if (budget <= 0) return true;
+    const inner = unwrapForWalk(s);
+    if (inner !== null) return walk(inner, segments, budget - 1);
+    const [head, ...rest] = segments;
+    if (head === void 0) return true;
+    if (s instanceof z.ZodObject) {
+      const shape = s.shape;
+      const child = shape[String(head)];
+      if (child !== void 0) return walk(child, rest, budget - 1);
+      const catchall = s.def.catchall;
+      return catchall !== void 0 && !(catchall instanceof z.ZodNever);
+    }
+    if (s instanceof z.ZodArray) {
+      return typeof head === "number" ? walk(s.element, rest, budget - 1) : false;
+    }
+    return !isLeafSchema(s);
+  };
+  return walk(schema, parsePath(path), SCHEMA_WALK_BUDGET);
+};
 var hasChecks = (s) => {
   const checks = s.def.checks;
   return checks !== void 0 && checks.length > 0;
@@ -227,13 +260,14 @@ var dirtyPathsOf = (values, initial, prefix) => {
   if (valuesEqual(values, initial)) return [];
   if (isPlainObject(values) && isPlainObject(initial)) {
     const keys = /* @__PURE__ */ new Set([...Object.keys(values), ...Object.keys(initial)]);
-    return [...keys].flatMap(
+    const childPaths = [...keys].flatMap(
       (k) => dirtyPathsOf(
         values[k],
         initial[k],
         prefix === "" ? k : `${prefix}.${k}`
       )
     );
+    return childPaths.length > 0 ? childPaths : [prefix];
   }
   return [prefix];
 };
@@ -357,6 +391,16 @@ var createForm = (schema, options) => {
     subschemaCache.set(path, sub);
     return sub;
   };
+  const checkedSchemaPaths = /* @__PURE__ */ new Set();
+  const warnMissingSchemaPath = (fn, path) => {
+    if (path === "" || checkedSchemaPaths.has(path)) return;
+    checkedSchemaPaths.add(path);
+    if (!schemaHasPath(schema, path)) {
+      console.warn(
+        `[formstand] ${fn}("${path}"): path does not exist in the schema \u2014 result will always be valid.`
+      );
+    }
+  };
   const fieldScopeFor = (path, values) => {
     const sub = path === "" ? null : subschemaAt(path);
     if (sub === null) {
@@ -394,6 +438,7 @@ var createForm = (schema, options) => {
     serverErrors: omitScope(state.serverErrors, [path])
   });
   const validateField = (path) => {
+    warnMissingSchemaPath("validateField", path);
     try {
       const scoped = scopedFieldErrors(path);
       store.setState((state) => ({
@@ -419,10 +464,11 @@ var createForm = (schema, options) => {
     };
   };
   const sequences = /* @__PURE__ */ new Map();
+  const seqRef = { current: 0 };
   const nextSeq = (key) => {
-    const next = (sequences.get(key) ?? 0) + 1;
-    sequences.set(key, next);
-    return next;
+    seqRef.current += 1;
+    sequences.set(key, seqRef.current);
+    return seqRef.current;
   };
   const validateAsyncOnForm = async () => {
     const seq = nextSeq(FORM_SEQ_KEY);
@@ -502,6 +548,13 @@ var createForm = (schema, options) => {
     return requestedValid;
   };
   const validateFieldAsync = async (path) => {
+    warnMissingSchemaPath("validateFieldAsync", path);
+    if (path === "") {
+      const result = await validateAsyncOnForm();
+      return fieldResult(
+        result.kind === "invalid" ? result.errors : emptyErrors
+      );
+    }
     const seq = nextSeq(path);
     const valuesAtStart = store.getState().values;
     store.setState((state) => ({
@@ -561,7 +614,13 @@ var createForm = (schema, options) => {
           )
         }),
         touched: reKeyByArrayPath(state.touched, path, mapper),
-        isValidating: reKeyByArrayPath(state.isValidating, path, mapper)
+        // Drop (don't re-key) in-flight flags under the array: the op changes
+        // `values`, so every pass they belong to fails its values-changed
+        // guard and never commits — but each pass's cleanup omits its
+        // ORIGINAL key, so a re-keyed entry would be orphaned and stick
+        // forever. Dropped, the flag is gone now and the cleanup is a
+        // harmless no-op.
+        isValidating: omitScope(state.isValidating, [path])
       };
     });
   };
@@ -583,33 +642,43 @@ var createForm = (schema, options) => {
       submitCount: state.submitCount + 1
     }));
     try {
-      const result = await validateAsync(schema, store.getState().values);
+      const valuesAtStart = store.getState().values;
+      const result = await validateAsync(schema, valuesAtStart);
+      const staleValues = store.getState().values !== valuesAtStart;
       if (result.kind === "invalid") {
-        store.setState((state) => {
-          const committed = commitFullPass(state, result.errors);
-          return {
-            ...state,
-            ...committed,
-            // Mark every errored field touched so touched-gated error UIs
-            // show something after the canonical first failed submit. The
-            // "" key (schema-level refine) has no field to touch.
-            touched: {
-              ...state.touched,
-              ...Object.fromEntries(
-                Object.keys(committed.errors).filter((k) => k !== "").map((k) => [k, true])
-              )
-            }
-          };
-        });
-        const merged = store.getState().errors;
+        if (!staleValues) {
+          store.setState((state) => {
+            const committed = commitFullPass(state, result.errors);
+            return {
+              ...state,
+              ...committed,
+              // Mark every errored field touched so touched-gated error UIs
+              // show something after the canonical first failed submit. The
+              // "" key (schema-level refine) has no field to touch.
+              touched: {
+                ...state.touched,
+                ...Object.fromEntries(
+                  Object.keys(committed.errors).filter((k) => k !== "").map((k) => [k, true])
+                )
+              }
+            };
+          });
+        }
+        const merged = staleValues ? result.errors : store.getState().errors;
         onInvalid?.(merged);
         return { kind: "invalid", errors: merged };
       }
-      store.setState((state) => ({
-        ...state,
-        ...commitFullPass(state, emptyErrors)
-      }));
-      await onValid(result.data);
+      if (!staleValues) {
+        store.setState((state) => ({
+          ...state,
+          ...commitFullPass(state, emptyErrors)
+        }));
+      }
+      try {
+        await onValid(result.data);
+      } catch (error) {
+        return { kind: "error", error };
+      }
       return { kind: "valid", data: result.data };
     } finally {
       inFlight.count -= 1;
@@ -741,7 +810,12 @@ var createForm = (schema, options) => {
         ...errorChannels(state, {
           schemaErrors: emptyErrors,
           serverErrors: emptyErrors
-        })
+        }),
+        // Clearing `sequences` disowns every in-flight pass, including its
+        // flag cleanup (the ownership check fails, so it never writes) —
+        // clear the flags here too, mirroring reset(), or they'd stick.
+        isValidating: emptyBools,
+        isValidatingForm: false
       }));
     },
     reset: (nextInitial, resetOptions) => {
@@ -906,8 +980,6 @@ function useFormSelector(form, selector) {
 function useFormSelectorShallow(form, selector) {
   return useStore(form.store, useShallow(selector));
 }
-var useFormState = useFormSelector;
-var useFormStateShallow = useFormSelectorShallow;
 var useFormError = (form) => useStore(
   form.store,
   useShallow((state) => state.errors[""])
@@ -1204,7 +1276,12 @@ var NumberField = ({
     /* @__PURE__ */ jsx(ErrorText, { id: errorId, error: field.error })
   ] });
 };
-var CheckboxField = ({ form, path, label, ref }) => {
+var CheckboxField = ({
+  form,
+  path,
+  label,
+  ref
+}) => {
   const id = useId();
   const errorId = `${id}-error`;
   const field = useField(form, path);
@@ -1248,7 +1325,12 @@ var SelectField = ({
         "aria-describedby": hasError(field.error) ? errorId : void 0,
         children: [
           showEmptyOption ? /* @__PURE__ */ jsx("option", { value: "", disabled: true, children: placeholder ?? "" }) : null,
-          options.map((opt) => /* @__PURE__ */ jsx("option", { value: opt.value, children: opt.label }, opt.value))
+          options.map((opt, index) => (
+            // Index-qualified: option lists may legitimately repeat a value
+            // (e.g. differently-labelled aliases), and bare value keys would
+            // collide.
+            /* @__PURE__ */ jsx("option", { value: opt.value, children: opt.label }, `${index}-${opt.value}`)
+          ))
         ]
       }
     ),
@@ -1257,25 +1339,40 @@ var SelectField = ({
 };
 
 // src/react/focusError.ts
+var focusableControls = (scope) => [
+  ...scope.querySelectorAll(
+    "input[name], select[name], textarea[name]"
+  )
+].filter(
+  (el) => !el.matches(':disabled, [type="hidden"]') && el.closest("dialog:not([open])") === null
+);
+var focusFirstOf = (candidates) => candidates.some((el) => {
+  el.focus();
+  return document.activeElement === el;
+});
+var nameMatchesAny = (el, paths) => {
+  const name = el.getAttribute("name");
+  return name !== null && paths.some((p) => isPathOrChild(name, p));
+};
 var focusFirstError = (errors, root) => {
   const scope = root ?? document;
   const erroredPaths = Object.keys(errors).filter(
     (k) => k !== "" && (errors[k]?.length ?? 0) > 0
   );
   const hasRootError = (errors[""]?.length ?? 0) > 0;
-  const controls = [
-    ...scope.querySelectorAll(
-      "input[name], select[name], textarea[name]"
-    )
-  ].filter((el) => !el.matches(':disabled, [type="hidden"]'));
-  const fieldMatch = controls.find((el) => {
-    const name = el.getAttribute("name");
-    return name !== null && erroredPaths.some((k) => isPathOrChild(name, k));
-  });
-  const target = fieldMatch ?? (hasRootError ? controls[0] : void 0);
-  target?.focus();
-  return target !== void 0;
+  const controls = focusableControls(scope);
+  const fieldMatches = controls.filter(
+    (el) => nameMatchesAny(el, erroredPaths)
+  );
+  const rootFallbackApplies = hasRootError && (root !== void 0 || document.querySelectorAll("form").length <= 1);
+  const candidates = fieldMatches.length > 0 ? fieldMatches : rootFallbackApplies ? controls : [];
+  return focusFirstOf(candidates);
 };
+var focusField = (path, root) => focusFirstOf(
+  focusableControls(root ?? document).filter(
+    (el) => nameMatchesAny(el, [path])
+  )
+);
 var EMPTY_ID_STATE = { items: [], ids: [], counter: 0 };
 var EMPTY_ITEMS = [];
 var reconcileIds = (prev, nextItems) => {
@@ -1381,6 +1478,6 @@ var useFieldArray = (form, pathArg) => {
   );
 };
 
-export { CheckboxField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, flattenIssues, focusFirstError, getAtPath, isAsyncRequiredError, numberInputProps, parsePath, selectProps, setAtPath, shouldValidateOn, textInputProps, useField, useFieldArray, useForm, useFormError, useFormSelector, useFormSelectorShallow, useFormState, useFormStateShallow, useIsDirty, useIsSubmitting, useIsValid, useSubmitCount, validateAsync, validateSync };
+export { CheckboxField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, emptyValueForSchema, flattenIssues, focusField, focusFirstError, getAtPath, isAsyncRequiredError, numberInputProps, numberToInputText, parseNumberText, parsePath, selectProps, setAtPath, shouldValidateOn, textInputProps, useField, useFieldArray, useForm, useFormError, useFormSelector, useFormSelectorShallow, useIsDirty, useIsSubmitting, useIsValid, useSubmitCount, validateAsync, validateSync };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map