feat(form-core): add array method field.clearValues and form.clearFieldValues

packages/form-core/src/FieldApi.ts

@@ -1288,6 +1288,15 @@ export class FieldApi<
     this.triggerOnChangeListener()
   }
 
+  /**
+   * Clear all values from the array.
+   */
+  clearValues = (opts?: UpdateMetaOptions) => {
+    this.form.clearFieldValues(this.name, opts)
+
+    this.triggerOnChangeListener()
+  }
+
   /**
    * @private
    */

packages/form-core/src/FormApi.ts

@@ -1962,6 +1962,32 @@ export class FormApi<
     this.validateField(`${field}[${index2}]` as DeepKeys<TFormData>, 'change')
   }
 
+  /**
+   * Clear all values within an array field.
+   */
+  clearFieldValues = <TField extends DeepKeys<TFormData>>(
+    field: TField,
+    opts?: UpdateMetaOptions,
+  ) => {
+    const fieldValue = this.getFieldValue(field)
+
+    const lastIndex = Array.isArray(fieldValue)
+      ? Math.max((fieldValue as unknown[]).length - 1, 0)
+      : null
+
+    this.setFieldValue(field, [] as any, opts)
+
+    if (lastIndex !== null) {
+      for (let i = 0; i <= lastIndex; i++) {
+        const fieldKey = `${field}[${i}]`
+        this.deleteField(fieldKey as never)
+      }
+    }
+
+    // validate array change
+    this.validateField(field, 'change')
+  }
+
   /**
    * Resets the field value and meta to default state
    */

packages/form-core/tests/FieldApi.spec.ts

@@ -1195,6 +1195,28 @@ describe('field api', () => {
 
     field.moveValue(0, 1)
     expect(arr).toStrictEqual(['middle', 'end', 'start'])
+
+    field.clearValues()
+    expect(arr).toStrictEqual([])
+  })
+
+  it('should not break when clearValues is called on a non-array field', () => {
+    const form = new FormApi({
+      defaultValues: {
+        name: 'foo',
+      },
+    })
+
+    form.mount()
+
+    const field = new FieldApi({
+      form,
+      name: 'name',
+    })
+
+    field.mount()
+
+    expect(() => field.clearValues()).not.toThrow()
   })
 
   it('should reset the form on a listener', () => {

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

@@ -3015,4 +3015,26 @@ describe('form api', () => {
       form.parseValuesWithSchemaAsync(z.any())
     }).not.toThrowError()
   })
+
+  it('should delete fields when resetting an array field to an empty array', () => {
+    const employees = [
+      {
+        firstName: 'Darcy',
+      },
+    ] as const
+
+    const form = new FormApi({
+      defaultValues: {
+        employees,
+      },
+    })
+    form.mount()
+
+    form.clearFieldValues('employees')
+
+    expect(form.getFieldValue('employees')).toEqual([])
+    expect(form.getFieldValue(`employees[0]`)).toBeUndefined()
+    expect(form.getFieldMeta(`employees[0]`)).toBeUndefined()
+    expect(form.state.values.employees).toStrictEqual([])
+  })
 })