feat(form-core): Change from touched error message and error message to error map and array of errors (#442)

* feature(FieldAPI): Change from touched error message and  error message to error map and array of errors

BREAKING CHANGE: The touched Error and error field has been removed will be replaced with touched errors array and errors map.

* feat: update documentation for updated fields

* chore: update Vue adapter as well

* fix: update getErrorMapKey to return onChange when change is the validation cause

* chore: remove console.log

---------

Co-authored-by: Corbin Crutchley <git@crutchcorn.dev>

Author: CheRayLiu

docs/reference/fieldApi.md

@@ -83,7 +83,7 @@ An object type representing the options for a field in a form.
 
 A type representing the cause of a validation event.
 
-- 'change' | 'blur' | 'submit'
+- 'change' | 'blur' | 'submit' | 'mount'
 
 ### `FieldMeta`
 
@@ -94,13 +94,17 @@ An object type representing the metadata of a field in a form.
   ```
   - A flag indicating whether the field has been touched.
 - ```tsx
-  touchedError?: ValidationError
+  touchedErrors: ValidationError[]
   ```
-  - An optional error related to the touched state of the field.
+  - An array of errors related to the touched state of the field.
 - ```tsx
-  error?: ValidationError
+  errors: ValidationError[]
   ```
-  - An optional error related to the field value.
+  - An array of errors related related to the field value.
+- ```tsx
+  errorMap: ValidationErrorMap
+  ```
+  - A map of errors related related to the field value.
 - ```tsx
   isValidating: boolean
   ```

docs/reference/formApi.md

@@ -262,3 +262,11 @@ An object representing the validation metadata for a field.
 ### `ValidationError`
 
 A type representing a validation error. Possible values are `undefined`, `false`, `null`, or a `string` with an error message.
+
+### `ValidationErrorMapKeys`
+A type representing the keys used to map to `ValidationError` in `ValidationErrorMap`. It is defined with `on${Capitalize<ValidationCause>}`
+
+
+### `ValidationErrorMap`
+
+A type that represents a map with the keys as `ValidationErrorMapKeys` and the values as `ValidationError`

package.json

@@ -92,7 +92,7 @@
     "fs-extra": "^11.1.1",
     "solid-js": "^1.6.13",
     "stream-to-array": "^2.3.0",
-    "tsup": "^7.1.0",
+    "tsup": "^7.2.0",
     "type-fest": "^3.11.0",
     "typescript": "^5.2.2",
     "vitest": "^0.34.3",

packages/form-core/src/FieldApi.ts

@@ -1,8 +1,8 @@
-import type { DeepKeys, DeepValue, Updater } from './utils'
-import type { FormApi, ValidationError } from './FormApi'
+import { type DeepKeys, type DeepValue, type Updater } from './utils'
+import type { FormApi, ValidationError, ValidationErrorMap } from './FormApi'
 import { Store } from '@tanstack/store'
 
-export type ValidationCause = 'change' | 'blur' | 'submit'
+export type ValidationCause = 'change' | 'blur' | 'submit' | 'mount'
 
 type ValidateFn<TData, TFormData> = (
   value: TData,
@@ -52,8 +52,9 @@ export type FieldApiOptions<TData, TFormData> = FieldOptions<
 
 export type FieldMeta = {
   isTouched: boolean
-  touchedError?: ValidationError
-  error?: ValidationError
+  touchedErrors: ValidationError[]
+  errors: ValidationError[]
+  errorMap: ValidationErrorMap
   isValidating: boolean
 }
 
@@ -110,16 +111,19 @@ export class FieldApi<TData, TFormData> {
         meta: this._getMeta() ?? {
           isValidating: false,
           isTouched: false,
+          touchedErrors: [],
+          errors: [],
+          errorMap: {},
           ...opts.defaultMeta,
         },
       },
       {
         onUpdate: () => {
           const state = this.store.state
 
-          state.meta.touchedError = state.meta.isTouched
-            ? state.meta.error
-            : undefined
+          state.meta.touchedErrors = state.meta.isTouched
+            ? state.meta.errors
+            : []
 
           this.prevState = state
           this.state = state
@@ -203,6 +207,9 @@ export class FieldApi<TData, TFormData> {
     ({
       isValidating: false,
       isTouched: false,
+      touchedErrors: [],
+      errors: [],
+      errorMap: {},
       ...this.options.defaultMeta,
     } as FieldMeta)
 
@@ -239,24 +246,27 @@ export class FieldApi<TData, TFormData> {
     const { onChange, onBlur } = this.options
     const validate =
       cause === 'submit' ? undefined : cause === 'change' ? onChange : onBlur
-
     if (!validate) return
 
     // Use the validationCount for all field instances to
     // track freshness of the validation
     const validationCount = (this.getInfo().validationCount || 0) + 1
     this.getInfo().validationCount = validationCount
     const error = normalizeError(validate(value as never, this as never))
-
-    if (this.state.meta.error !== error) {
+    const errorMapKey = getErrorMapKey(cause)
+    if (error && this.state.meta.errorMap[errorMapKey] !== error) {
       this.setMeta((prev) => ({
         ...prev,
-        error,
+        errors: [...prev.errors, error],
+        errorMap: {
+          ...prev.errorMap,
+          [getErrorMapKey(cause)]: error,
+        },
       }))
     }
 
-    // If a sync error is encountered, cancel any async validation
-    if (this.state.meta.error) {
+    // If a sync error is encountered for the errorMapKey (eg. onChange), cancel any async validation
+    if (this.state.meta.errorMap[errorMapKey]) {
       this.cancelValidateAsync()
     }
   }
@@ -293,9 +303,7 @@ export class FieldApi<TData, TFormData> {
         : cause === 'submit'
         ? onSubmitAsync
         : onBlurAsync
-
-    if (!validate) return
-
+    if (!validate) return []
     const debounceMs =
       cause === 'submit'
         ? 0
@@ -328,21 +336,25 @@ export class FieldApi<TData, TFormData> {
 
     // Only kick off validation if this validation is the latest attempt
     if (checkLatest()) {
+      const prevErrors = this.getMeta().errors
       try {
         const rawError = await validate(value as never, this as never)
-
         if (checkLatest()) {
           const error = normalizeError(rawError)
           this.setMeta((prev) => ({
             ...prev,
             isValidating: false,
-            error,
+            errors: [...prev.errors, error],
+            errorMap: {
+              ...prev.errorMap,
+              [getErrorMapKey(cause)]: error,
+            },
           }))
-          this.getInfo().validationResolve?.(error)
+          this.getInfo().validationResolve?.([...prevErrors, error])
         }
       } catch (error) {
         if (checkLatest()) {
-          this.getInfo().validationReject?.(error)
+          this.getInfo().validationReject?.([...prevErrors, error])
           throw error
         }
       } finally {
@@ -354,26 +366,25 @@ export class FieldApi<TData, TFormData> {
     }
 
     // Always return the latest validation promise to the caller
-    return this.getInfo().validationPromise
+    return this.getInfo().validationPromise ?? []
   }
 
   validate = (
     cause: ValidationCause,
     value?: typeof this._tdata,
-  ): ValidationError | Promise<ValidationError> => {
+  ): ValidationError[] | Promise<ValidationError[]> => {
     // If the field is pristine and validatePristine is false, do not validate
-    if (!this.state.meta.isTouched) return
-
+    if (!this.state.meta.isTouched) return []
     // Attempt to sync validate first
     this.validateSync(value, cause)
 
-    // If there is an error, return it, do not attempt async validation
-    if (this.state.meta.error) {
+    const errorMapKey = getErrorMapKey(cause)
+    // If there is an error mapped to the errorMapKey (eg. onChange, onBlur, onSubmit), return the errors array, do not attempt async validation
+    if (this.getMeta().errorMap[errorMapKey]) {
       if (!this.options.asyncAlways) {
-        return this.state.meta.error
+        return this.state.meta.errors
       }
     }
-
     // No error? Attempt async validation
     return this.validateAsync(value, cause)
   }
@@ -403,3 +414,16 @@ function normalizeError(rawError?: ValidationError) {
 
   return undefined
 }
+
+function getErrorMapKey(cause: ValidationCause) {
+  switch (cause) {
+    case 'submit':
+      return 'onSubmit'
+    case 'change':
+      return 'onChange'
+    case 'blur':
+      return 'onBlur'
+    case 'mount':
+      return 'onMount'
+  }
+}

packages/form-core/src/FormApi.ts

@@ -1,7 +1,7 @@
 import { Store } from '@tanstack/store'
 //
 import type { DeepKeys, DeepValue, Updater } from './utils'
-import { functionalUpdate, getBy, setBy } from './utils'
+import { functionalUpdate, getBy, isNonEmptyArray, setBy } from './utils'
 import type { FieldApi, FieldMeta, ValidationCause } from './FieldApi'
 
 export type FormOptions<TData> = {
@@ -37,13 +37,19 @@ export type FieldInfo<TFormData> = {
 export type ValidationMeta = {
   validationCount?: number
   validationAsyncCount?: number
-  validationPromise?: Promise<ValidationError>
-  validationResolve?: (error: ValidationError) => void
-  validationReject?: (error: unknown) => void
+  validationPromise?: Promise<ValidationError[]>
+  validationResolve?: (errors: ValidationError[]) => void
+  validationReject?: (errors: unknown) => void
 }
 
 export type ValidationError = undefined | false | null | string
 
+export type ValidationErrorMapKeys = `on${Capitalize<ValidationCause>}`
+
+export type ValidationErrorMap = {
+  [K in ValidationErrorMapKeys]?: ValidationError
+}
+
 export type FormState<TData> = {
   values: TData
   // Form Validation
@@ -117,7 +123,9 @@ export class FormApi<TFormData> {
             (field) => field?.isValidating,
           )
 
-          const isFieldsValid = !fieldMetaValues.some((field) => field?.error)
+          const isFieldsValid = !fieldMetaValues.some((field) =>
+            isNonEmptyArray(field?.errors),
+          )
 
           const isTouched = fieldMetaValues.some((field) => field?.isTouched)
 
@@ -192,8 +200,7 @@ export class FormApi<TFormData> {
     )
 
   validateAllFields = async (cause: ValidationCause) => {
-    const fieldValidationPromises: Promise<ValidationError>[] = [] as any
-
+    const fieldValidationPromises: Promise<ValidationError[]>[] = [] as any
     this.store.batch(() => {
       void (Object.values(this.fieldInfo) as FieldInfo<any>[]).forEach(
         (field) => {