formstand 0.15.2 → 0.16.0

package/dist/index.d.cts

@@ -61,6 +61,7 @@ type UseFieldReturn<TValue> = Readonly<{
     initialValue: TValue;
     emptyValue: null | undefined;
     error: readonly string[] | undefined;
+    firstError: string | undefined;
     touched: boolean;
     dirty: boolean;
     isValidating: boolean;
@@ -92,7 +93,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 `${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;
@@ -212,6 +213,22 @@ declare function useIsValid<TSchema extends z.ZodType, P extends FieldPath<z.inp
 declare const useIsSubmitting: (form: FormStateApi) => boolean;
 declare const useSubmitCount: (form: FormStateApi) => number;
 
+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 PathsOf<F extends FieldFormApi> = F extends Form<infer TSchema extends z.ZodType, infer D extends PathDepth> ? FieldPath<z.input<TSchema>, D> : string;
 type FieldRef<T> = ((instance: T | null) => void) | Readonly<{
     current: T | null;
@@ -341,4 +358,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, 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, useNumberInput, useSubmitCount, useVariantField };

package/dist/index.d.ts

@@ -61,6 +61,7 @@ type UseFieldReturn<TValue> = Readonly<{
     initialValue: TValue;
     emptyValue: null | undefined;
     error: readonly string[] | undefined;
+    firstError: string | undefined;
     touched: boolean;
     dirty: boolean;
     isValidating: boolean;
@@ -92,7 +93,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 `${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;
@@ -212,6 +213,22 @@ declare function useIsValid<TSchema extends z.ZodType, P extends FieldPath<z.inp
 declare const useIsSubmitting: (form: FormStateApi) => boolean;
 declare const useSubmitCount: (form: FormStateApi) => number;
 
+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 PathsOf<F extends FieldFormApi> = F extends Form<infer TSchema extends z.ZodType, infer D extends PathDepth> ? FieldPath<z.input<TSchema>, D> : string;
 type FieldRef<T> = ((instance: T | null) => void) | Readonly<{
     current: T | null;
@@ -341,4 +358,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, 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, useNumberInput, useSubmitCount, useVariantField };

package/dist/index.js

@@ -1256,6 +1256,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,
@@ -1529,6 +1531,30 @@ 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();
+      });
+    }
+  };
+}
+
 // src/react/inputProps.ts
 var hasFieldError = (error) => error !== void 0 && error.length > 0;
 var ariaInvalid = (field) => hasFieldError(field.error) ? true : void 0;
@@ -1917,6 +1943,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, useNumberInput, useSubmitCount, useVariantField, validateAsync, validateSync };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map