[v2] Refactor formOptions to allow context-based callbacks

.changeset/clear-turtles-play.md

@@ -0,0 +1,21 @@
+---
+'@tanstack/angular-form': minor
+'@tanstack/form-core': minor
+'@tanstack/form-devtools': minor
+'@tanstack/lit-form': minor
+'@tanstack/preact-form': minor
+'@tanstack/react-form': minor
+'@tanstack/react-form-nextjs': minor
+'@tanstack/react-form-start': minor
+'@tanstack/solid-form': minor
+'@tanstack/svelte-form': minor
+'@tanstack/vue-form': minor
+---
+
+BREAKING: Schemas no longer automatically send copies of field errors to the form. Use `fieldErrorTarget: 'field-and-self'` on form or group validators.
+
+`fieldErrorTarget` can now control where schemas process errors. It has three modes:
+
+- `'field'` (default) - Field errors are only sent to the field it targets.
+- `'field-and-self'` - Field errors are sent to the field it targets, and a copy is sent to the form array.
+- `'self'` - Fields do not receive errors, only the form.

examples/angular/field-groups/src/bound-field.component.ts

@@ -50,9 +50,9 @@ export class BoundFieldComponent {
       watchFields: this.fields().lowerBound
         ? [this.fields().lowerBound!]
         : undefined,
-      run: ({ value, parseIssues }: any) => {
+      run: ({ value }: any) => {
         const valueResult = boundsSchema.safeParse(value)
-        if (!valueResult.success) return parseIssues(valueResult.error.issues)
+        if (!valueResult.success) return valueResult.error.issues
         const lowerName = this.fields().lowerBound
         if (!lowerName) return
         const lowerResult = boundsSchema.safeParse(
@@ -61,6 +61,7 @@ export class BoundFieldComponent {
         if (lowerResult.success && valueResult.data < lowerResult.data) {
           return 'Upper bound must be greater than lower bound'
         }
+        return undefined
       },
     },
   ])

examples/angular/large-form/src/shared-form.ts

@@ -13,15 +13,23 @@ export const peopleFormOptions = formOptions({
       triggers: ['change'],
       run: async ({ value, createErrorMap }) => {
         const errors = createErrorMap()
-        if (!value.fullName) errors.fields.fullName = 'Full name is required'
-        if (!value.phone) errors.fields.phone = 'Phone is required'
+        if (!value.fullName) {
+          errors.addFieldError('fullName', 'Full name is required')
+        }
+        if (!value.phone) {
+          errors.addFieldError('phone', 'Phone is required')
+        }
         if (!value.emergencyContact.fullName) {
-          errors.fields['emergencyContact.fullName'] =
-            'Emergency contact full name is required'
+          errors.addFieldError(
+            'emergencyContact.fullName',
+            'Emergency contact full name is required',
+          )
         }
         if (!value.emergencyContact.phone) {
-          errors.fields['emergencyContact.phone'] =
-            'Emergency contact phone is required'
+          errors.addFieldError(
+            'emergencyContact.phone',
+            'Emergency contact phone is required',
+          )
         }
         return errors
       },

examples/lit/field-groups/src/field-bounds.ts

@@ -55,9 +55,9 @@ function upperBoundField(props: {
         {
           triggers: ['change'],
           watchFields: ['lowerBound'],
-          run: ({ value, parseIssues }) => {
+          run: ({ value }) => {
             const upper = boundsSchema.safeParse(value)
-            if (!upper.success) return parseIssues(upper.error.issues)
+            if (!upper.success) return upper.error.issues
             const lower = boundsSchema.safeParse(
               props.fields.getFieldValue('lowerBound'),
             )

examples/lit/large-form/src/shared-form.ts

@@ -22,15 +22,23 @@ export const peopleFormOptions = formOptions({
       triggers: ['change'],
       run: ({ value, createErrorMap }) => {
         const errors = createErrorMap()
-        if (!value.fullName) errors.fields.fullName = 'Full name is required'
-        if (!value.phone) errors.fields.phone = 'Phone is required'
+        if (!value.fullName) {
+          errors.addFieldError('fullName', 'Full name is required')
+        }
+        if (!value.phone) {
+          errors.addFieldError('phone', 'Phone is required')
+        }
         if (!value.emergencyContact.fullName) {
-          errors.fields['emergencyContact.fullName'] =
-            'Emergency contact full name is required'
+          errors.addFieldError(
+            'emergencyContact.fullName',
+            'Emergency contact full name is required',
+          )
         }
         if (!value.emergencyContact.phone) {
-          errors.fields['emergencyContact.phone'] =
-            'Emergency contact phone is required'
+          errors.addFieldError(
+            'emergencyContact.phone',
+            'Emergency contact phone is required',
+          )
         }
         return errors
       },

examples/preact/field-groups/src/fieldGroups/fieldBounds.tsx

@@ -78,11 +78,11 @@ function UpperBoundFieldComponent(props: UpperBoundFieldProps) {
           // `watchFields` also uses virtual names. The wrapper rewrites
           // `lowerBound` to the caller's concrete path, such as `minPrice`.
           watchFields: ['lowerBound'],
-          run: ({ value, parseIssues }) => {
+          run: ({ value }) => {
             const upperBoundResult = boundsSchema.safeParse(value)
 
             if (!upperBoundResult.success) {
-              return parseIssues(upperBoundResult.error.issues)
+              return upperBoundResult.error.issues
             }
 
             const lowerBoundResult = boundsSchema.safeParse(

examples/preact/large-form/src/features/people/shared-form.tsx

@@ -24,18 +24,22 @@ export const peopleFormOpts = appFormOptions({
         const errors = createErrorMap()
 
         if (!value.fullName) {
-          errors.fields.fullName = 'Full name is required'
+          errors.addFieldError('fullName', 'Full name is required')
         }
         if (!value.phone) {
-          errors.fields.phone = 'Phone is required'
+          errors.addFieldError('phone', 'Phone is required')
         }
         if (!value.emergencyContact.fullName) {
-          errors.fields['emergencyContact.fullName'] =
-            'Emergency contact full name is required'
+          errors.addFieldError(
+            'emergencyContact.fullName',
+            'Emergency contact full name is required',
+          )
         }
         if (!value.emergencyContact.phone) {
-          errors.fields['emergencyContact.phone'] =
-            'Emergency contact phone is required'
+          errors.addFieldError(
+            'emergencyContact.phone',
+            'Emergency contact phone is required',
+          )
         }
 
         return errors

examples/react/basic/src/index.tsx

@@ -22,12 +22,12 @@ function App() {
       firstName: '',
       lastName: '',
     },
-    onSubmit: ({ value, createValidationError }) => {
+    onSubmit: ({ value, createErrorMap }) => {
       // Do something with form data
       console.log(value)
 
       // If your endpoint returned validation errors, pass them on
-      return createValidationError({
+      return createErrorMap({
         fields: {
           // Set field-specific errors from the form!
           firstName: 'Name already exists',

examples/react/field-groups/src/fieldGroups/fieldBounds.tsx

@@ -78,11 +78,11 @@ function UpperBoundFieldComponent(props: UpperBoundFieldProps) {
           // `watchFields` also uses virtual names. The wrapper rewrites
           // `lowerBound` to the caller's concrete path, such as `minPrice`.
           watchFields: ['lowerBound'],
-          run: ({ value, parseIssues }) => {
+          run: ({ value }) => {
             const upperBoundResult = boundsSchema.safeParse(value)
 
             if (!upperBoundResult.success) {
-              return parseIssues(upperBoundResult.error.issues)
+              return upperBoundResult.error.issues
             }
 
             const lowerBoundResult = boundsSchema.safeParse(

examples/react/large-form/src/features/people/shared-form.tsx

@@ -24,18 +24,22 @@ export const peopleFormOpts = appFormOptions({
         const errors = createErrorMap()
 
         if (!value.fullName) {
-          errors.fields.fullName = 'Full name is required'
+          errors.addFieldError('fullName', 'Full name is required')
         }
         if (!value.phone) {
-          errors.fields.phone = 'Phone is required'
+          errors.addFieldError('phone', 'Phone is required')
         }
         if (!value.emergencyContact.fullName) {
-          errors.fields['emergencyContact.fullName'] =
-            'Emergency contact full name is required'
+          errors.addFieldError(
+            'emergencyContact.fullName',
+            'Emergency contact full name is required',
+          )
         }
         if (!value.emergencyContact.phone) {
-          errors.fields['emergencyContact.phone'] =
-            'Emergency contact phone is required'
+          errors.addFieldError(
+            'emergencyContact.phone',
+            'Emergency contact phone is required',
+          )
         }
 
         return errors

examples/react/next-server-actions-zod/src/app/action.ts

@@ -1,18 +1,13 @@
 'use server'
 
-import {
-  initialServerFormState,
-  serverValidateHelper,
-} from '@tanstack/react-form'
+import { initialServerFormState } from '@tanstack/react-form'
 import { next } from '@tanstack/react-form-nextjs'
 import { formOpts } from './shared-code'
 
-const { createServerValidate } = serverValidateHelper({
-  framework: next({
-    info: {
-      numbers: ['age'],
-    },
-  }),
+const { createServerValidate } = next({
+  info: {
+    numbers: ['age'],
+  },
 })
 
 const serverValidate = createServerValidate(formOpts)

examples/react/next-server-actions/src/app/action.ts

@@ -1,18 +1,13 @@
 'use server'
 
-import {
-  initialServerFormState,
-  serverValidateHelper,
-} from '@tanstack/react-form'
+import { initialServerFormState } from '@tanstack/react-form'
 import { next } from '@tanstack/react-form-nextjs'
 import { formOpts } from './shared-code'
 
-const { createServerValidate } = serverValidateHelper({
-  framework: next({
-    info: {
-      numbers: ['age'],
-    },
-  }),
+const { createServerValidate } = next({
+  info: {
+    numbers: ['age'],
+  },
 })
 
 const serverValidate = createServerValidate(formOpts)

examples/react/next-server-actions/src/app/shared-code.ts

@@ -12,7 +12,10 @@ export const formOpts = formOptions({
         const errors = createErrorMap()
 
         if (value.age < 8) {
-          errors.fields.age = 'Client validation: You must be at least 8'
+          errors.addFieldError(
+            'age',
+            'Client validation: You must be at least 8',
+          )
         }
 
         return errors
@@ -25,8 +28,10 @@ export const formOpts = formOptions({
         const errors = createErrorMap()
 
         if (value.age < 12) {
-          errors.fields.age =
-            'Server validation: You must be at least 12 to sign up'
+          errors.addFieldError(
+            'age',
+            'Server validation: You must be at least 12 to sign up',
+          )
         }
 
         return errors

examples/react/nextjs/app/action.ts

@@ -1,18 +1,13 @@
 'use server'
 
-import {
-  initialServerFormState,
-  serverValidateHelper,
-} from '@tanstack/react-form'
+import { initialServerFormState } from '@tanstack/react-form'
 import { next } from '@tanstack/react-form-nextjs'
 import { formOpts } from './shared-code'
 
-const { createServerValidate } = serverValidateHelper({
-  framework: next({
-    info: {
-      numbers: ['age'],
-    },
-  }),
+const { createServerValidate } = next({
+  info: {
+    numbers: ['age'],
+  },
 })
 
 const serverValidate = createServerValidate(formOpts)

examples/react/nextjs/app/shared-code.ts

@@ -12,7 +12,10 @@ export const formOpts = formOptions({
         const errors = createErrorMap()
 
         if (value.age < 8) {
-          errors.fields.age = 'Client validation: You must be at least 8'
+          errors.addFieldError(
+            'age',
+            'Client validation: You must be at least 8',
+          )
         }
 
         return errors
@@ -26,11 +29,17 @@ export const formOpts = formOptions({
         const errors = createErrorMap()
 
         if (!value.firstName.trim()) {
-          errors.fields.firstName = 'Server validation: First name is required'
+          errors.addFieldError(
+            'firstName',
+            'Server validation: First name is required',
+          )
         }
 
         if (value.age < 13) {
-          errors.fields.age = 'Server validation: You must be at least 13'
+          errors.addFieldError(
+            'age',
+            'Server validation: You must be at least 13',
+          )
         }
 
         return errors

examples/react/tanstack-start/src/utils/form-isomorphic.ts

@@ -12,7 +12,10 @@ export const formOpts = formOptions({
         const errors = createErrorMap()
 
         if (value.age < 8) {
-          errors.fields.age = 'Client validation: You must be at least 8'
+          errors.addFieldError(
+            'age',
+            'Client validation: You must be at least 8',
+          )
         }
 
         return errors
@@ -26,11 +29,17 @@ export const formOpts = formOptions({
         const errors = createErrorMap()
 
         if (!value.firstName.trim()) {
-          errors.fields.firstName = 'Server validation: First name is required'
+          errors.addFieldError(
+            'firstName',
+            'Server validation: First name is required',
+          )
         }
 
         if (value.age < 13) {
-          errors.fields.age = 'Server validation: You must be at least 13'
+          errors.addFieldError(
+            'age',
+            'Server validation: You must be at least 13',
+          )
         }
 
         return errors

examples/react/tanstack-start/src/utils/form-validator.ts

@@ -1,6 +1,3 @@
-import { serverValidateHelper } from '@tanstack/react-form'
 import { start } from '@tanstack/react-form-start'
 
-export const { createServerValidate } = serverValidateHelper({
-  framework: start(),
-})
+export const { createServerValidate } = start()

examples/react/ui-integration-shadcn/src/app/booking/shared-form.tsx

@@ -1,7 +1,7 @@
 import { createValidator } from '@tanstack/react-form'
 import { bookingFormSchema } from './schema'
-import type { ReactNode } from 'react'
 import type { ReactFormType } from '@tanstack/react-form'
+import type { ReactNode } from 'react'
 import { appFormOptions } from '@/components/form/app-form'
 import { FieldGroup } from '@/components/ui/field'