[v2] Fix: Move mounted fields onto the current field API after array mutations

.changeset/olive-moons-repeat.md

@@ -0,0 +1,9 @@
+---
+'@tanstack/react-form': patch
+'@tanstack/form-core': patch
+'@tanstack/vue-form': patch
+---
+
+Fix: Move mounted fields onto the current field API after array mutations
+
+Removing or swapping array items kills and moves field APIs while the components rendering them stay mounted under the same name. Those components kept the field API they resolved on mount, so a value or error that shifted to their index never rendered. The form now tracks field API identity changes and adapters resolve their name again when it changes.

packages/form-core/src/FieldApi/FieldApi.lib.ts

@@ -1215,6 +1215,7 @@ export class InternalFieldApi<
     const previousPath = this.name
     moveFieldToSegment(this, newSegment)
     if (this.name !== previousPath) {
+      this.form._bumpFieldTreeVersion()
       devtools().moveField?.(this, previousPath)
     }
   }
@@ -1230,6 +1231,7 @@ export class InternalFieldApi<
     } = {},
   ) {
     killField(this, options)
+    this.form._bumpFieldTreeVersion()
   }
 
   _pruneIfUnused(): void {

packages/form-core/src/FormApi/FormApi.lib.ts

@@ -122,6 +122,13 @@ export interface FormAtoms<in out TFormData> {
   meta: FormMetaAtoms
   resetVersion: Atom<number>
   defaultValuesVersion: Atom<number>
+  /**
+   * Bumped whenever a field API changes the name it is reachable by, either
+   * because it was killed or because an array mutation moved it to another
+   * index. Adapters watch this to move mounted components onto the field API
+   * the form now uses for their name.
+   */
+  fieldTreeVersion: Atom<number>
 }
 
 function createInitialFormErrorMeta(): FormErrorMeta {
@@ -320,6 +327,7 @@ export class InternalFormApi<
       meta: createInitialFormMetaAtoms(),
       resetVersion: createAtom(0),
       defaultValuesVersion: createAtom(0),
+      fieldTreeVersion: createAtom(0),
     }
     this._fieldRootNode = new InternalRootFieldApi(this)
     this._onSubmitSource = new InternalValidationSourceInstance({
@@ -747,6 +755,15 @@ export class InternalFormApi<
     })
   }
 
+  /**
+   * @private
+   * Signals that the name a field API is reachable by has changed, so mounted
+   * adapter components can resolve their name to the current field API.
+   */
+  _bumpFieldTreeVersion(): void {
+    this._atoms.fieldTreeVersion.set((version) => version + 1)
+  }
+
   _tryGetFieldApi(
     nameOrSegments: string | Array<string>,
   ): AnyInternalFieldApi | null {

packages/react-form/src/ReactForm/useField.lib.ts

@@ -28,9 +28,14 @@ export function useField(
   optionsRef.current = options
 
   const resetVersion = useSelector(options.form._atoms.resetVersion)
+  // Array mutations kill or move field APIs while the components rendering
+  // them stay mounted under the same name. Resolve the name again so the
+  // component follows the field API the form now uses for it.
+  const fieldTreeVersion = useSelector(options.form._atoms.fieldTreeVersion)
 
   const fieldApi = useMemo(() => {
     void resetVersion
+    void fieldTreeVersion
     const field = options.form._getOrCreateFieldApi(
       {
         ...optionsRef.current,
@@ -39,7 +44,7 @@ export function useField(
       scope,
     )
     return field
-  }, [options.name, options.form, resetVersion, scope])
+  }, [options.name, options.form, resetVersion, fieldTreeVersion, scope])
 
   useEffect(() => fieldApi._update(options, scope))
 

packages/react-form/tests/FormField.spec.tsx

@@ -1,5 +1,5 @@
 import { describe, expect, it, vi } from 'vitest'
-import { fireEvent, render } from '@testing-library/react'
+import { fireEvent, render, waitFor } from '@testing-library/react'
 import React, { useEffect, useState } from 'react'
 import { userEvent } from '@testing-library/user-event'
 import { useForm } from '../src'
@@ -416,6 +416,77 @@ describe('Form fields', () => {
     expect(input).toHaveValue('after-reset')
   })
 
+  it('moves mounted fields onto the current field api after array mutations', async () => {
+    function Component() {
+      const form = useForm({
+        defaultValues: { issues: [{ title: 'A' }, { title: '' }] },
+        validators: [
+          {
+            triggers: ['change'],
+            run: ({ value }) => ({
+              fields: Object.fromEntries(
+                value.issues.map((issue, index) => [
+                  `issues[${index}].title`,
+                  issue.title ? undefined : 'Required',
+                ]),
+              ),
+            }),
+          },
+        ],
+      })
+
+      return (
+        <>
+          <button
+            data-testid="validate"
+            onClick={() => void form.handleSubmit()}
+          />
+          <form.ArrayField name="issues">
+            {(array) => (
+              <>
+                {array.value.map((_, index) => (
+                  <form.Field key={index} name={`issues[${index}].title`}>
+                    {(field) => (
+                      <>
+                        <input
+                          data-testid={`input-${index}`}
+                          value={field.value}
+                          onChange={(event) =>
+                            field.handleChange(event.target.value)
+                          }
+                        />
+                        <output data-testid={`errors-${index}`}>
+                          {field.errors.map((error) => error.message).join(',')}
+                        </output>
+                      </>
+                    )}
+                  </form.Field>
+                ))}
+                <button
+                  data-testid="remove-first"
+                  onClick={() => array.removeValue(0)}
+                />
+              </>
+            )}
+          </form.ArrayField>
+        </>
+      )
+    }
+
+    const { getByTestId, queryByTestId } = render(<Component />)
+
+    fireEvent.click(getByTestId('validate'))
+    await waitFor(() =>
+      expect(getByTestId('errors-1')).toHaveTextContent('Required'),
+    )
+
+    fireEvent.click(getByTestId('remove-first'))
+
+    await waitFor(() => expect(queryByTestId('input-1')).toBeNull())
+    expect(getByTestId('input-0')).toHaveValue('')
+    expect(getByTestId('errors-0')).toHaveTextContent('Required')
+  })
+
   it('should remove unused field nodes', async () => {
     const formApi = { current: null as AnyInternalFormApi | null }
 

packages/vue-form/src/VueForm/useField.lib.ts

@@ -18,18 +18,26 @@ export function useField(
 ): ShallowRef<AnyInternalFieldApi> {
   const initialOptions = options()
   const resetVersion = useSelector(initialOptions.form._atoms.resetVersion)
+  const fieldTreeVersion = useSelector(
+    initialOptions.form._atoms.fieldTreeVersion,
+  )
+
+  const adoptField = (field: AnyInternalFieldApi) => {
+    if (fieldComponents !== null) Object.assign(field, fieldComponents)
+    return field
+  }
 
   const createField = () => {
     const current = options()
-    const field = current.form._getOrCreateFieldApi(
-      {
-        ...current,
-        name: current.name,
-      } as never,
-      'field',
+    return adoptField(
+      current.form._getOrCreateFieldApi(
+        {
+          ...current,
+          name: current.name,
+        } as never,
+        'field',
+      ),
     )
-    if (fieldComponents !== null) Object.assign(field, fieldComponents)
-    return field
   }
 
   const fieldApi = shallowRef(createField())
@@ -42,6 +50,20 @@ export function useField(
     { flush: 'sync' },
   )
 
+  // Array mutations kill or move field APIs while the components rendering
+  // them stay mounted under the same name. Follow the field API the form now
+  // uses for this name instead of holding on to a killed one.
+  watch(
+    fieldTreeVersion,
+    () => {
+      const current = options().form._tryGetFieldApi(options().name)
+      if (current && current !== fieldApi.value) {
+        fieldApi.value = adoptField(current)
+      }
+    },
+    { flush: 'sync' },
+  )
+
   watchEffect(() => {
     fieldApi.value._update(options() as never, 'field')
   })

packages/vue-form/tests/adapter.spec.tsx

@@ -188,6 +188,126 @@ describe('Vue adapter parity', () => {
     expect(renders).toBeGreaterThan(initialRenders)
   })
 
+  it('moves mounted fields onto the current field api after array mutations', async () => {
+    let form!: any
+    const Component = defineComponent(() => {
+      form = useForm({
+        defaultValues: { issues: [{ title: 'A' }, { title: '' }] },
+        validators: [
+          {
+            triggers: ['change'],
+            run: ({ value }: { value: { issues: Array<{ title: string }> } }) => ({
+              fields: Object.fromEntries(
+                value.issues.map((issue, index) => [
+                  `issues[${index}].title`,
+                  issue.title ? undefined : 'Required',
+                ]),
+              ),
+            }),
+          },
+        ],
+      })
+
+      return () => (
+        <form.ArrayField name="issues">
+          {({ field: array }: { field: AnyFieldApi }) => (
+            <>
+              {array.value.map((_: unknown, index: number) => (
+                <form.Field key={index} name={`issues[${index}].title`}>
+                  {({ field }: { field: AnyFieldApi }) => (
+                    <>
+                      <input
+                        data-testid={`input-${index}`}
+                        value={field.value}
+                        onInput={(event: Event) =>
+                          field.handleChange(
+                            (event.target as HTMLInputElement).value,
+                          )
+                        }
+                      />
+                      <output data-testid={`errors-${index}`}>
+                        {field.errors
+                          .map((error: { message: string }) => error.message)
+                          .join(',')}
+                      </output>
+                    </>
+                  )}
+                </form.Field>
+              ))}
+            </>
+          )}
+        </form.ArrayField>
+      )
+    })
+
+    const view = render(Component)
+    await form.handleSubmit()
+    await waitFor(() =>
+      expect(view.getByTestId('errors-1')).toHaveTextContent('Required'),
+    )
+
+    form.removeFieldValue('issues', 0)
+
+    await waitFor(() => expect(view.queryByTestId('input-1')).toBeNull())
+    expect(view.getByTestId('input-0')).toHaveValue('')
+    expect(view.getByTestId('errors-0')).toHaveTextContent('Required')
+  })
+
+  it('moves mounted fields onto the current field api after a swap', async () => {
+    let form!: any
+    const Component = defineComponent(() => {
+      form = useForm({
+        defaultValues: { issues: [{ title: 'A' }, { title: '' }] },
+        validators: [
+          {
+            triggers: ['change'],
+            run: ({ value }: { value: { issues: Array<{ title: string }> } }) => ({
+              fields: Object.fromEntries(
+                value.issues.map((issue, index) => [
+                  `issues[${index}].title`,
+                  issue.title ? undefined : 'Required',
+                ]),
+              ),
+            }),
+          },
+        ],
+      })
+
+      return () => (
+        <form.ArrayField name="issues">
+          {({ field: array }: { field: AnyFieldApi }) => (
+            <>
+              {array.value.map((_: unknown, index: number) => (
+                <form.Field key={index} name={`issues[${index}].title`}>
+                  {({ field }: { field: AnyFieldApi }) => (
+                    <output data-testid={`errors-${index}`}>
+                      {field.errors
+                        .map((error: { message: string }) => error.message)
+                        .join(',')}
+                    </output>
+                  )}
+                </form.Field>
+              ))}
+            </>
+          )}
+        </form.ArrayField>
+      )
+    })
+
+    const view = render(Component)
+    await form.handleSubmit()
+    await waitFor(() =>
+      expect(view.getByTestId('errors-1')).toHaveTextContent('Required'),
+    )
+
+    form.swapFieldValues('issues', 0, 1)
+
+    await waitFor(() =>
+      expect(view.getByTestId('errors-0')).toHaveTextContent('Required'),
+    )
+    expect(view.getByTestId('errors-1')).toHaveTextContent('')
+  })
+
   it('prefixes FormGroup fields and keeps group state reactive', async () => {
     const Component = defineComponent(() => {
       const form = useForm({