[v2] Fix: Keep ArrayField in sync after array replacement (#2356)

* fix(react-form): Keep ArrayField in sync after replacement

Replacing an array with another array of the same length updated form state without rerendering ArrayField.

Bump the shared array version for direct replacements while keeping nested field updates isolated.

Co-Authored-By: OpenAI Codex <noreply@openai.com>

* ci: apply automated fixes and generate docs

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

---------

Co-authored-by: OpenAI Codex <noreply@openai.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: LeCarbonator <18158911+LeCarbonator@users.noreply.github.com>

Author: 4 people

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

@@ -507,7 +507,22 @@ export class InternalFormApi<
     updateOptions.fieldApiOverride = field
 
     batch(() => {
-      this._atoms.values.set((prev) => setBy(prev, fieldName, updater))
+      const previousValue = this.getFieldValue(fieldName)
+      const nextValue = callUpdater(updater, previousValue)
+      const replacedSameLengthArray =
+        Array.isArray(previousValue) &&
+        Array.isArray(nextValue) &&
+        previousValue !== nextValue &&
+        previousValue.length === nextValue.length
+
+      this._atoms.values.set((prev) => setBy(prev, fieldName, () => nextValue))
+
+      if (field && replacedSameLengthArray) {
+        field._setMeta((prev) => ({
+          ...prev,
+          _arrayVersion: prev._arrayVersion + 1,
+        }))
+      }
 
       this._notifyFieldChange(field, updateOptions)
     })

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

@@ -203,12 +203,6 @@ function swapFieldValues({
 
     if (!arrayField) return
 
-    // Since the length wasn't changed, we need to notify manually
-    arrayField._setMeta((prev) => ({
-      ...prev,
-      _arrayVersion: prev._arrayVersion + 1,
-    }))
-
     const fieldA = tryGetFieldApi(arrayField, [indexA])
 
     const fieldB = tryGetFieldApi(arrayField, [indexB])
@@ -266,11 +260,6 @@ function moveFieldValue({
 
     if (!arrayField) return
 
-    arrayField._setMeta((prev) => ({
-      ...prev,
-      _arrayVersion: prev._arrayVersion + 1,
-    }))
-
     const movingChild = tryGetFieldApi(arrayField, [fromIndex])
 
     for (const child of arrayField._children) {
@@ -312,11 +301,6 @@ function clearFieldValues({
 
     if (!arrayField) return
 
-    arrayField._setMeta((prev) => ({
-      ...prev,
-      _arrayVersion: prev._arrayVersion + 1,
-    }))
-
     // Kill all child fields since the array is now empty
     // _kill() will remove each child from the parent's children
     for (const child of arrayField._children) {

packages/form-core/tests/FormApi/field-state.spec.ts

@@ -55,6 +55,59 @@ describe('form - field state', () => {
       expect(form.getFieldValue('count')).toBe(2)
     })
 
+    it('increments the array version for a same-length array replacement', () => {
+      const form = new InternalFormApi({ defaultValues: { items: ['a'] } })
+      const field = form._getOrCreateFieldApi({ name: 'items' })
+
+      form.setFieldValue('items', ['b'])
+
+      expect(form.getFieldValue('items')).toEqual(['b'])
+      expect(field.meta._arrayVersion).toBe(1)
+    })
+
+    it('increments the array version for an updater replacement', () => {
+      const form = new InternalFormApi({ defaultValues: { items: ['a'] } })
+      const field = form._getOrCreateFieldApi({ name: 'items' })
+
+      form.setFieldValue('items', (items: Array<string>) =>
+        items.map((item) => item.toUpperCase()),
+      )
+
+      expect(form.getFieldValue('items')).toEqual(['A'])
+      expect(field.meta._arrayVersion).toBe(1)
+    })
+
+    it('does not increment a parent array version for a nested field update', () => {
+      const form = new InternalFormApi({
+        defaultValues: { items: [{ label: 'a' }] },
+      })
+      const field = form._getOrCreateFieldApi({ name: 'items' })
+
+      form.setFieldValue('items[0].label', 'b')
+
+      expect(form.getFieldValue('items')).toEqual([{ label: 'b' }])
+      expect(field.meta._arrayVersion).toBe(0)
+    })
+
+    it('increments the array version only once for array helpers', () => {
+      const form = new InternalFormApi({
+        defaultValues: { items: ['a', 'b', 'c'] },
+      })
+      const field = form._getOrCreateFieldApi({ name: 'items' })
+
+      form.swapFieldValues('items', 0, 1)
+      expect(field.meta._arrayVersion).toBe(1)
+
+      form.moveFieldValue('items', 0, 2)
+      expect(field.meta._arrayVersion).toBe(2)
+
+      form.clearFieldValues('items')
+      expect(field.meta._arrayVersion).toBe(2)
+
+      form.clearFieldValues('items')
+      expect(field.meta._arrayVersion).toBe(3)
+    })
+
     it('marks form isTouched and isDirty after a change', () => {
       const form = new InternalFormApi({ defaultValues: { name: '' } })
       const field = form._getOrCreateFieldApi({ name: 'name' })

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

@@ -101,6 +101,51 @@ describe('Form fields', () => {
     expect(input).toHaveValue('new-value')
   })
 
+  it('rerenders an ArrayField for a same-length replacement', () => {
+    let renders = 0
+
+    function Component() {
+      const form = useForm({
+        defaultValues: { items: [{ label: 'A' }] },
+      })
+
+      return (
+        <>
+          <button
+            data-testid="replace-array"
+            onClick={() => form.setFieldValue('items', [{ label: 'B' }])}
+          />
+          <button
+            data-testid="update-child"
+            onClick={() => form.setFieldValue('items[0].label', 'C')}
+          />
+          <form.ArrayField name="items">
+            {(field) => {
+              renders++
+              return (
+                <output data-testid="array">{field.value[0]!.label}</output>
+              )
+            }}
+          </form.ArrayField>
+        </>
+      )
+    }
+
+    const { getByTestId } = render(<Component />)
+    const initialRenders = renders
+
+    fireEvent.click(getByTestId('replace-array'))
+
+    expect(getByTestId('array')).toHaveTextContent('B')
+    expect(renders).toBeGreaterThan(initialRenders)
+
+    const replacementRenders = renders
+
+    fireEvent.click(getByTestId('update-child'))
+
+    expect(renders).toBe(replacementRenders)
+  })
+
   it('should have the correct meta when changing the field', async () => {
     function Component() {
       const form = useForm({ defaultValues: { name: 'tony-hawk' } })