@tanstack/form-core 0.29.2 → 0.32.0

package/src/FieldApi.ts

@@ -1,5 +1,6 @@
 import { Store } from '@tanstack/store'
 import { getAsyncValidatorArray, getBy, getSyncValidatorArray } from './utils'
+import type { FieldInfo, FieldsErrorMapFromValidator, FormApi } from './FormApi'
 import type {
   UpdateMetaOptions,
   ValidationCause,
@@ -7,7 +8,6 @@ import type {
   ValidationErrorMap,
   Validator,
 } from './types'
-import type { FieldInfo, FormApi } from './FormApi'
 import type { AsyncValidator, SyncValidator, Updater } from './utils'
 import type { DeepKeys, DeepValue, NoInfer } from './util-types'
 
@@ -157,7 +157,7 @@ export interface FieldValidators<
    * An optional property that takes a `ValidateFn` which is a generic of `TData` and `TParentData`.
    * If `validatorAdapter` is passed, this may also accept a property from the respective adapter
    *
-   * @example `z.string().min(1)` if `zodAdapter` is passed
+   * @example z.string().min(1) // if `zodAdapter` is passed
    */
   onChange?: FieldValidateOrFn<
     TParentData,
@@ -170,7 +170,7 @@ export interface FieldValidators<
    * An optional property similar to `onChange` but async validation. If `validatorAdapter`
    * is passed, this may also accept a property from the respective adapter
    *
-   * @example `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed
+   * @example z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' }) // if `zodAdapter` is passed
    */
   onChangeAsync?: FieldAsyncValidateOrFn<
     TParentData,
@@ -190,10 +190,10 @@ export interface FieldValidators<
    */
   onChangeListenTo?: DeepKeys<TParentData>[]
   /**
-   * An optional function, that when run when subscribing to blur event of input.
+   * An optional function, that runs on the blur event of input.
    * If `validatorAdapter` is passed, this may also accept a property from the respective adapter
    *
-   * @example `z.string().min(1)` if `zodAdapter` is passed
+   * @example z.string().min(1) // if `zodAdapter` is passed
    */
   onBlur?: FieldValidateOrFn<
     TParentData,
@@ -206,7 +206,7 @@ export interface FieldValidators<
    * An optional property similar to `onBlur` but async validation. If `validatorAdapter`
    * is passed, this may also accept a property from the respective adapter
    *
-   * @example `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed
+   * @example z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' }) // if `zodAdapter` is passed
    */
   onBlurAsync?: FieldAsyncValidateOrFn<
     TParentData,
@@ -227,10 +227,10 @@ export interface FieldValidators<
    */
   onBlurListenTo?: DeepKeys<TParentData>[]
   /**
-   * An optional function, that when run when subscribing to submit event of input.
+   * An optional function, that runs on the submit event of form.
    * If `validatorAdapter` is passed, this may also accept a property from the respective adapter
    *
-   * @example `z.string().min(1)` if `zodAdapter` is passed
+   * @example z.string().min(1) // if `zodAdapter` is passed
    */
   onSubmit?: FieldValidateOrFn<
     TParentData,
@@ -243,7 +243,7 @@ export interface FieldValidators<
    * An optional property similar to `onSubmit` but async validation. If `validatorAdapter`
    * is passed, this may also accept a property from the respective adapter
    *
-   * @example `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed
+   * @example z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' }) // if `zodAdapter` is passed
    */
   onSubmitAsync?: FieldAsyncValidateOrFn<
     TParentData,
@@ -335,6 +335,10 @@ export type FieldMeta = {
    * A flag indicating whether the field has been touched.
    */
   isTouched: boolean
+  /**
+   * A flag indicating whether the field has been blurred.
+   */
+  isBlurred: boolean
   /**
    * A flag that is `true` if the field's value has not been modified by the user. Opposite of `isDirty`.
    */
@@ -456,6 +460,7 @@ export class FieldApi<
         meta: this._getMeta() ?? {
           isValidating: false,
           isTouched: false,
+          isBlurred: false,
           isDirty: false,
           isPristine: true,
           errors: [],
@@ -625,6 +630,7 @@ export class FieldApi<
     ({
       isValidating: false,
       isTouched: false,
+      isBlurred: false,
       isDirty: false,
       isPristine: true,
       errors: [],
@@ -718,7 +724,10 @@ export class FieldApi<
   /**
    * @private
    */
-  validateSync = (cause: ValidationCause) => {
+  validateSync = (
+    cause: ValidationCause,
+    errorFromForm: ValidationErrorMap,
+  ) => {
     const validates = getSyncValidatorArray(cause, this.options)
 
     const linkedFields = this.getLinkedFields(cause)
@@ -741,30 +750,42 @@ export class FieldApi<
         field: FieldApi<any, any, any, any>,
         validateObj: SyncValidator<any>,
       ) => {
-        const error = normalizeError(
-          field.runValidator({
-            validate: validateObj.validate,
-            value: { value: field.getValue(), fieldApi: field },
-            type: 'validate',
-          }),
-        )
         const errorMapKey = getErrorMapKey(validateObj.cause)
+
+        const error =
+          /*
+            If `validateObj.validate` is `undefined`, then the field doesn't have
+            a validator for this event, but there still could be an error that
+            needs to be cleaned up related to the current event left by the
+            form's validator.
+          */
+          validateObj.validate
+            ? normalizeError(
+                field.runValidator({
+                  validate: validateObj.validate,
+                  value: { value: field.getValue(), fieldApi: field },
+                  type: 'validate',
+                }),
+              )
+            : errorFromForm[errorMapKey]
+
         if (field.state.meta.errorMap[errorMapKey] !== error) {
           field.setMeta((prev) => ({
             ...prev,
             errorMap: {
               ...prev.errorMap,
-              [getErrorMapKey(validateObj.cause)]: error,
+              [getErrorMapKey(validateObj.cause)]:
+                // Prefer the error message from the field validators if they exist
+                error ? error : errorFromForm[errorMapKey],
             },
           }))
         }
-        if (error) {
+        if (error || errorFromForm[errorMapKey]) {
           hasErrored = true
         }
       }
 
       for (const validateObj of validates) {
-        if (!validateObj.validate) continue
         validateFieldFn(this, validateObj)
       }
       for (const fieldValitateObj of linkedFieldValidates) {
@@ -778,6 +799,7 @@ export class FieldApi<
      *  to clear the error as soon as the user enters a valid value in the field
      */
     const submitErrKey = getErrorMapKey('submit')
+
     if (
       this.state.meta.errorMap[submitErrKey] &&
       cause !== 'submit' &&
@@ -798,9 +820,17 @@ export class FieldApi<
   /**
    * @private
    */
-  validateAsync = async (cause: ValidationCause) => {
+  validateAsync = async (
+    cause: ValidationCause,
+    formValidationResultPromise: Promise<
+      FieldsErrorMapFromValidator<TParentData>
+    >,
+  ) => {
     const validates = getAsyncValidatorArray(cause, this.options)
 
+    // Get the field-specific error messages that are coming from the form's validator
+    const asyncFormValidationResults = await formValidationResultPromise
+
     const linkedFields = this.getLinkedFields(cause)
     const linkedFieldValidates = linkedFields.reduce(
       (acc, field) => {
@@ -835,13 +865,13 @@ export class FieldApi<
       validateObj: AsyncValidator<any>,
       promises: Promise<ValidationError | undefined>[],
     ) => {
-      const key = getErrorMapKey(validateObj.cause)
-      const fieldValidatorMeta = field.getInfo().validationMetaMap[key]
+      const errorMapKey = getErrorMapKey(validateObj.cause)
+      const fieldValidatorMeta = field.getInfo().validationMetaMap[errorMapKey]
 
       fieldValidatorMeta?.lastAbortController.abort()
       const controller = new AbortController()
 
-      this.getInfo().validationMetaMap[key] = {
+      this.getInfo().validationMetaMap[errorMapKey] = {
         lastAbortController: controller,
       }
 
@@ -874,18 +904,21 @@ export class FieldApi<
           }
           if (controller.signal.aborted) return resolve(undefined)
           const error = normalizeError(rawError)
+          const fieldErrorFromForm =
+            asyncFormValidationResults[this.name]?.[errorMapKey]
+          const fieldError = error || fieldErrorFromForm
           field.setMeta((prev) => {
             return {
               ...prev,
               errorMap: {
                 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
                 ...prev?.errorMap,
-                [getErrorMapKey(cause)]: error,
+                [errorMapKey]: fieldError,
               },
             }
           })
 
-          resolve(error)
+          resolve(fieldError)
         }),
       )
     }
@@ -925,15 +958,28 @@ export class FieldApi<
   validate = (
     cause: ValidationCause,
   ): ValidationError[] | Promise<ValidationError[]> => {
-    // If the field is pristine and validatePristine is false, do not validate
+    // If the field is pristine, do not validate
     if (!this.state.meta.isTouched) return []
 
+    let validationErrorFromForm: ValidationErrorMap = {}
+    let formValidationResultPromise: Promise<
+      FieldsErrorMapFromValidator<TParentData>
+    > = Promise.resolve({})
+
     try {
-      this.form.validate(cause)
+      const formValidationResult = this.form.validate(cause)
+      if (formValidationResult instanceof Promise) {
+        formValidationResultPromise = formValidationResult
+      } else {
+        const fieldErrorFromForm = formValidationResult[this.name]
+        if (fieldErrorFromForm) {
+          validationErrorFromForm = fieldErrorFromForm
+        }
+      }
     } catch (_) {}
 
     // Attempt to sync validate first
-    const { hasErrored } = this.validateSync(cause)
+    const { hasErrored } = this.validateSync(cause, validationErrorFromForm)
 
     if (hasErrored && !this.options.asyncAlways) {
       this.getInfo().validationMetaMap[
@@ -942,7 +988,7 @@ export class FieldApi<
       return this.state.meta.errors
     }
     // No error? Attempt async validation
-    return this.validateAsync(cause)
+    return this.validateAsync(cause, formValidationResultPromise)
   }
 
   /**
@@ -961,6 +1007,9 @@ export class FieldApi<
       this.setMeta((prev) => ({ ...prev, isTouched: true }))
       this.validate('change')
     }
+    if (!this.state.meta.isBlurred) {
+      this.setMeta((prev) => ({ ...prev, isBlurred: true }))
+    }
     this.validate('blur')
   }
 

package/src/FormApi.ts

@@ -12,6 +12,7 @@ import type { Updater } from './utils'
 import type { DeepKeys, DeepValue } from './util-types'
 import type { FieldApi, FieldMeta } from './FieldApi'
 import type {
+  FormValidationError,
   UpdateMetaOptions,
   ValidationCause,
   ValidationError,
@@ -20,16 +21,17 @@ import type {
   Validator,
 } from './types'
 
-/**
- * @private
- */
+export type FieldsErrorMapFromValidator<TFormData> = Partial<
+  Record<DeepKeys<TFormData>, ValidationErrorMap>
+>
+
 export type FormValidateFn<
   TFormData,
   TFormValidator extends Validator<TFormData, unknown> | undefined = undefined,
 > = (props: {
   value: TFormData
   formApi: FormApi<TFormData, TFormValidator>
-}) => ValidationError
+}) => FormValidationError<TFormData>
 
 /**
  * @private
@@ -52,7 +54,22 @@ export type FormValidateAsyncFn<
   value: TFormData
   formApi: FormApi<TFormData, TFormValidator>
   signal: AbortSignal
-}) => ValidationError | Promise<ValidationError>
+}) => FormValidationError<TFormData> | Promise<FormValidationError<TFormData>>
+
+export type FormValidator<TFormData, TType, TFn = unknown> = {
+  validate(options: { value: TType }, fn: TFn): ValidationError
+  validateAsync(
+    options: { value: TType },
+    fn: TFn,
+  ): Promise<FormValidationError<TFormData>>
+}
+
+type ValidationPromiseResult<TFormData> =
+  | {
+      fieldErrors: Partial<Record<DeepKeys<TFormData>, ValidationError>>
+      errorMapKey: ValidationErrorMapKeys
+    }
+  | undefined
 
 /**
  * @private
@@ -86,11 +103,11 @@ export interface FormValidators<
    */
   onChangeAsyncDebounceMs?: number
   /**
-   * Optional function that validates the form data when a field loses focus, returns a ValidationError
+   * Optional function that validates the form data when a field loses focus, returns a `FormValidationError`
    */
   onBlur?: FormValidateOrFn<TFormData, TFormValidator>
   /**
-   * Optional onBlur asynchronous validation method for when a field loses focus return a `ValidationError` or a promise of `Promise<ValidationError>`
+   * Optional onBlur asynchronous validation method for when a field loses focus returns a ` FormValidationError` or a promise of `Promise<FormValidationError>`
    */
   onBlurAsync?: FormAsyncValidateOrFn<TFormData, TFormValidator>
   /**
@@ -242,6 +259,10 @@ export type FormState<TFormData> = {
    * A boolean indicating if any of the form fields have been touched.
    */
   isTouched: boolean
+  /**
+   * A boolean indicating if any of the form fields have been blurred.
+   */
+  isBlurred: boolean
   /**
    * A boolean indicating if any of the form's fields' values have been modified by the user. `True` if the user have modified at least one of the fields. Opposite of `isPristine`.
    */
@@ -288,6 +309,7 @@ function getDefaultFormState<TFormData>(
     isSubmitted: defaultState.isSubmitted ?? false,
     isSubmitting: defaultState.isSubmitting ?? false,
     isTouched: defaultState.isTouched ?? false,
+    isBlurred: defaultState.isBlurred ?? false,
     isPristine: defaultState.isPristine ?? true,
     isDirty: defaultState.isDirty ?? false,
     isValid: defaultState.isValid ?? false,
@@ -371,6 +393,7 @@ export class FormApi<
           )
 
           const isTouched = fieldMetaValues.some((field) => field?.isTouched)
+          const isBlurred = fieldMetaValues.some((field) => field?.isBlurred)
 
           const isDirty = fieldMetaValues.some((field) => field?.isDirty)
           const isPristine = !isDirty
@@ -393,6 +416,7 @@ export class FormApi<
             isValid,
             canSubmit,
             isTouched,
+            isBlurred,
             isPristine,
             isDirty,
           }
@@ -536,6 +560,12 @@ export class FormApi<
           // Mark them as touched
           field.instance.setMeta((prev) => ({ ...prev, isTouched: true }))
         }
+
+        // If any fields are not blurred
+        if (!field.instance.state.meta.isBlurred) {
+          // Mark them as blurred
+          field.instance.setMeta((prev) => ({ ...prev, isBlurred: true }))
+        }
       })
     })
 
@@ -599,6 +629,12 @@ export class FormApi<
       fieldInstance.setMeta((prev) => ({ ...prev, isTouched: true }))
     }
 
+    // If the field is not blurred (same logic as in validateAllFields)
+    if (!fieldInstance.state.meta.isBlurred) {
+      // Mark it as blurred
+      fieldInstance.setMeta((prev) => ({ ...prev, isBlurred: true }))
+    }
+
     return fieldInstance.validate(cause)
   }
 
@@ -606,35 +642,68 @@ export class FormApi<
    * TODO: This code is copied from FieldApi, we should refactor to share
    * @private
    */
-  validateSync = (cause: ValidationCause) => {
+  validateSync = (
+    cause: ValidationCause,
+  ): {
+    hasErrored: boolean
+    fieldsErrorMap: FieldsErrorMapFromValidator<TFormData>
+  } => {
     const validates = getSyncValidatorArray(cause, this.options)
     let hasErrored = false as boolean
 
+    const fieldsErrorMap: FieldsErrorMapFromValidator<TFormData> = {}
+
     this.store.batch(() => {
       for (const validateObj of validates) {
         if (!validateObj.validate) continue
 
-        const error = normalizeError(
-          this.runValidator({
-            validate: validateObj.validate,
-            value: {
-              value: this.state.values,
-              formApi: this,
-            },
-            type: 'validate',
-          }),
-        )
+        const rawError = this.runValidator({
+          validate: validateObj.validate,
+          value: {
+            value: this.state.values,
+            formApi: this,
+          },
+          type: 'validate',
+        })
+
+        const { formError, fieldErrors } = normalizeError<TFormData>(rawError)
+
         const errorMapKey = getErrorMapKey(validateObj.cause)
-        if (this.state.errorMap[errorMapKey] !== error) {
+
+        if (fieldErrors) {
+          for (const [field, fieldError] of Object.entries(fieldErrors)) {
+            const oldErrorMap =
+              fieldsErrorMap[field as DeepKeys<TFormData>] || {}
+            const newErrorMap = {
+              ...oldErrorMap,
+              [errorMapKey]: fieldError,
+            }
+            fieldsErrorMap[field as DeepKeys<TFormData>] = newErrorMap
+
+            const fieldMeta = this.getFieldMeta(field as DeepKeys<TFormData>)
+            if (fieldMeta && fieldMeta.errorMap[errorMapKey] !== fieldError) {
+              this.setFieldMeta(field as DeepKeys<TFormData>, (prev) => ({
+                ...prev,
+                errorMap: {
+                  ...prev.errorMap,
+                  [errorMapKey]: fieldError,
+                },
+              }))
+            }
+          }
+        }
+
+        if (this.state.errorMap[errorMapKey] !== formError) {
           this.store.setState((prev) => ({
             ...prev,
             errorMap: {
               ...prev.errorMap,
-              [errorMapKey]: error,
+              [errorMapKey]: formError,
             },
           }))
         }
-        if (error) {
+
+        if (formError || fieldErrors) {
           hasErrored = true
         }
       }
@@ -659,7 +728,7 @@ export class FormApi<
       }))
     }
 
-    return { hasErrored }
+    return { hasErrored, fieldsErrorMap }
   }
 
   /**
@@ -667,7 +736,7 @@ export class FormApi<
    */
   validateAsync = async (
     cause: ValidationCause,
-  ): Promise<ValidationError[]> => {
+  ): Promise<FieldsErrorMapFromValidator<TFormData>> => {
     const validates = getAsyncValidatorArray(cause, this.options)
 
     if (!this.state.isFormValidating) {
@@ -678,7 +747,11 @@ export class FormApi<
      * We have to use a for loop and generate our promises this way, otherwise it won't be sync
      * when there are no validators needed to be run
      */
-    const promises: Promise<ValidationError | undefined>[] = []
+    const promises: Promise<ValidationPromiseResult<TFormData>>[] = []
+
+    let fieldErrors:
+      | Partial<Record<DeepKeys<TFormData>, ValidationError>>
+      | undefined
 
     for (const validateObj of validates) {
       if (!validateObj.validate) continue
@@ -693,7 +766,7 @@ export class FormApi<
       }
 
       promises.push(
-        new Promise<ValidationError | undefined>(async (resolve) => {
+        new Promise<ValidationPromiseResult<TFormData>>(async (resolve) => {
           let rawError!: ValidationError | undefined
           try {
             rawError = await new Promise((rawResolve, rawReject) => {
@@ -719,23 +792,65 @@ export class FormApi<
           } catch (e: unknown) {
             rawError = e as ValidationError
           }
-          const error = normalizeError(rawError)
+          const { formError, fieldErrors: fieldErrorsFromNormalizeError } =
+            normalizeError<TFormData>(rawError)
+
+          if (fieldErrorsFromNormalizeError) {
+            fieldErrors = fieldErrors
+              ? { ...fieldErrors, ...fieldErrorsFromNormalizeError }
+              : fieldErrorsFromNormalizeError
+          }
+          const errorMapKey = getErrorMapKey(validateObj.cause)
+
+          if (fieldErrors) {
+            for (const [field, fieldError] of Object.entries(fieldErrors)) {
+              const fieldMeta = this.getFieldMeta(field as DeepKeys<TFormData>)
+              if (fieldMeta && fieldMeta.errorMap[errorMapKey] !== fieldError) {
+                this.setFieldMeta(field as DeepKeys<TFormData>, (prev) => ({
+                  ...prev,
+                  errorMap: {
+                    ...prev.errorMap,
+                    [errorMapKey]: fieldError,
+                  },
+                }))
+              }
+            }
+          }
           this.store.setState((prev) => ({
             ...prev,
             errorMap: {
               ...prev.errorMap,
-              [getErrorMapKey(cause)]: error,
+              [errorMapKey]: formError,
             },
           }))
 
-          resolve(error)
+          resolve(fieldErrors ? { fieldErrors, errorMapKey } : undefined)
         }),
       )
     }
 
-    let results: ValidationError[] = []
+    let results: ValidationPromiseResult<TFormData>[] = []
+
+    const fieldsErrorMap: FieldsErrorMapFromValidator<TFormData> = {}
     if (promises.length) {
       results = await Promise.all(promises)
+      for (const fieldValidationResult of results) {
+        if (fieldValidationResult?.fieldErrors) {
+          const { errorMapKey } = fieldValidationResult
+
+          for (const [field, fieldError] of Object.entries(
+            fieldValidationResult.fieldErrors,
+          )) {
+            const oldErrorMap =
+              fieldsErrorMap[field as DeepKeys<TFormData>] || {}
+            const newErrorMap = {
+              ...oldErrorMap,
+              [errorMapKey]: fieldError,
+            }
+            fieldsErrorMap[field as DeepKeys<TFormData>] = newErrorMap
+          }
+        }
+      }
     }
 
     this.store.setState((prev) => ({
@@ -743,7 +858,7 @@ export class FormApi<
       isFormValidating: false,
     }))
 
-    return results.filter(Boolean)
+    return fieldsErrorMap
   }
 
   /**
@@ -751,12 +866,14 @@ export class FormApi<
    */
   validate = (
     cause: ValidationCause,
-  ): ValidationError[] | Promise<ValidationError[]> => {
+  ):
+    | FieldsErrorMapFromValidator<TFormData>
+    | Promise<FieldsErrorMapFromValidator<TFormData>> => {
     // Attempt to sync validate first
-    const { hasErrored } = this.validateSync(cause)
+    const { hasErrored, fieldsErrorMap } = this.validateSync(cause)
 
     if (hasErrored && !this.options.asyncAlways) {
-      return this.state.errors
+      return fieldsErrorMap
     }
 
     // No error? Attempt async validation
@@ -885,6 +1002,7 @@ export class FormApi<
         acc[fieldKey] = {
           isValidating: false,
           isTouched: false,
+          isBlurred: false,
           isDirty: false,
           isPristine: true,
           errors: [],
@@ -911,6 +1029,7 @@ export class FormApi<
         this.setFieldMeta(field, (prev) => ({
           ...prev,
           isTouched: true,
+          isBlurred: true,
           isDirty: true,
         }))
       }
@@ -1109,16 +1228,25 @@ export class FormApi<
   }
 }
 
-function normalizeError(rawError?: ValidationError) {
+function normalizeError<TFormData>(rawError?: FormValidationError<TFormData>): {
+  formError: ValidationError
+  fieldErrors?: Partial<Record<DeepKeys<TFormData>, ValidationError>>
+} {
   if (rawError) {
+    if (typeof rawError === 'object') {
+      const formError = normalizeError(rawError.form).formError
+      const fieldErrors = rawError.fields
+      return { formError, fieldErrors }
+    }
+
     if (typeof rawError !== 'string') {
-      return 'Invalid Form Values'
+      return { formError: 'Invalid Form Values' }
     }
 
-    return rawError
+    return { formError: rawError }
   }
 
-  return undefined
+  return { formError: undefined }
 }
 
 function getErrorMapKey(cause: ValidationCause) {