formstand 0.3.0 → 0.4.1

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<{
@@ -337,4 +335,4 @@ declare const numberInputProps: <T extends number | null | undefined>(field: Use
 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 ParsedNumberText, 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, numberToInputText, parseNumberText, 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<{
@@ -337,4 +335,4 @@ declare const numberInputProps: <T extends number | null | undefined>(field: Use
 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 ParsedNumberText, 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, numberToInputText, parseNumberText, 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,17 +260,19 @@ 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];
 };
 var FORM_SEQ_KEY = "__form__";
+var SUBMIT_SEQ_KEY = "__submit__";
 var stringArraysEqual = (a, b) => a === b || a.length === b.length && a.every((v, i) => v === b[i]);
 var reuseErrorRefs = (next, prev) => {
   if (next === prev) return prev;
@@ -357,6 +392,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 +439,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,18 +465,18 @@ var createForm = (schema, options) => {
     };
   };
   const sequences = /* @__PURE__ */ new Map();
-  const nextSeq = (key) => {
-    const next = (sequences.get(key) ?? 0) + 1;
-    sequences.set(key, next);
-    return next;
+  const claimPass = (key) => {
+    const pass = Symbol(key);
+    sequences.set(key, pass);
+    return pass;
   };
   const validateAsyncOnForm = async () => {
-    const seq = nextSeq(FORM_SEQ_KEY);
+    const pass = claimPass(FORM_SEQ_KEY);
     const valuesAtStart = store.getState().values;
     store.setState((state) => ({ ...state, isValidatingForm: true }));
     const result = await validateAsync(schema, valuesAtStart);
     const live = store.getState();
-    const stillOwns = sequences.get(FORM_SEQ_KEY) === seq;
+    const stillOwns = sequences.get(FORM_SEQ_KEY) === pass;
     if (!stillOwns || live.values !== valuesAtStart) {
       if (stillOwns) {
         store.setState((state) => ({ ...state, isValidatingForm: false }));
@@ -453,7 +499,7 @@ var createForm = (schema, options) => {
       const result2 = await validateAsyncOnForm();
       return result2.kind === "valid";
     }
-    const seqs = new Map(paths.map((p) => [p, nextSeq(p)]));
+    const passes = new Map(paths.map((p) => [p, claimPass(p)]));
     const valuesAtStart = store.getState().values;
     store.setState((state) => ({
       ...state,
@@ -468,7 +514,9 @@ var createForm = (schema, options) => {
       (k) => !inScopeOfAny(k, paths)
     );
     const live = store.getState();
-    const stillCurrent = paths.filter((p) => sequences.get(p) === seqs.get(p));
+    const stillCurrent = paths.filter(
+      (p) => sequences.get(p) === passes.get(p)
+    );
     if (live.values !== valuesAtStart) {
       if (stillCurrent.length > 0) {
         store.setState((state) => ({
@@ -502,7 +550,14 @@ var createForm = (schema, options) => {
     return requestedValid;
   };
   const validateFieldAsync = async (path) => {
-    const seq = nextSeq(path);
+    warnMissingSchemaPath("validateFieldAsync", path);
+    if (path === "") {
+      const result = await validateAsyncOnForm();
+      return fieldResult(
+        result.kind === "invalid" ? result.errors : emptyErrors
+      );
+    }
+    const pass = claimPass(path);
     const valuesAtStart = store.getState().values;
     store.setState((state) => ({
       ...state,
@@ -510,7 +565,7 @@ var createForm = (schema, options) => {
     }));
     const scoped = await scopedFieldErrorsAsync(path, valuesAtStart);
     const live = store.getState();
-    const stillOwns = sequences.get(path) === seq;
+    const stillOwns = sequences.get(path) === pass;
     if (!stillOwns || live.values !== valuesAtStart) {
       if (stillOwns) {
         store.setState((state) => ({
@@ -561,7 +616,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 +644,44 @@ var createForm = (schema, options) => {
       submitCount: state.submitCount + 1
     }));
     try {
-      const result = await validateAsync(schema, store.getState().values);
+      const pass = claimPass(SUBMIT_SEQ_KEY);
+      const valuesAtStart = store.getState().values;
+      const result = await validateAsync(schema, valuesAtStart);
+      const stale = sequences.get(SUBMIT_SEQ_KEY) !== pass || 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 (!stale) {
+          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 = stale ? result.errors : store.getState().errors;
         onInvalid?.(merged);
         return { kind: "invalid", errors: merged };
       }
-      store.setState((state) => ({
-        ...state,
-        ...commitFullPass(state, emptyErrors)
-      }));
-      await onValid(result.data);
+      if (!stale) {
+        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 +813,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) => {
@@ -847,7 +924,13 @@ var createForm = (schema, options) => {
         errors: reuseErrorRefs(
           mergeErrorChannels(schemaErrors, serverErrors),
           snap.errors ?? emptyErrors
-        )
+        ),
+        // In-flight state is owned by live passes, never by snapshots: a
+        // snapshotted flag has no pass left to clear it (the pass that set
+        // it cleared its ORIGINAL entry when it settled), so restoring one
+        // would stick it forever.
+        isValidating: emptyBools,
+        isValidatingForm: false
       };
     })
   });
@@ -906,8 +989,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[""])
@@ -1005,7 +1086,10 @@ function useField(form, pathArg, options) {
     [form, path]
   );
   const setError = useCallback(
-    (errors) => form.setError(path, errors),
+    // Normalize the string shorthand HERE, before forwarding: custom
+    // FieldFormApi implementations written against the pre-0.4 surface are
+    // typed for readonly string[] and must never receive a bare string.
+    (errors) => form.setError(path, typeof errors === "string" ? [errors] : errors),
     [form, path]
   );
   const clearError = useCallback(
@@ -1204,7 +1288,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 +1337,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,24 +1351,43 @@ 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 holdsFocus = (el) => {
+  const rootNode = el.getRootNode();
+  const active = rootNode instanceof Document || rootNode instanceof ShadowRoot ? rootNode.activeElement : document.activeElement;
+  return active === el;
+};
+var focusFirstOf = (candidates) => candidates.some((el) => {
+  el.focus();
+  return holdsFocus(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) => {
+  const controls = focusableControls(root ?? document);
+  return path === "" ? (root !== void 0 || document.querySelectorAll("form").length <= 1) && focusFirstOf(controls) : focusFirstOf(controls.filter((el) => nameMatchesAny(el, [path])));
 };
 var EMPTY_ID_STATE = { items: [], ids: [], counter: 0 };
 var EMPTY_ITEMS = [];
@@ -1381,6 +1494,6 @@ var useFieldArray = (form, pathArg) => {
   );
 };
 
-export { CheckboxField, NumberField, SelectField, TextField, checkboxProps, createForm, createFormContext, flattenIssues, focusFirstError, getAtPath, isAsyncRequiredError, numberInputProps, numberToInputText, parseNumberText, 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