fix(core): field unmount (#2068)

* fix: make field unmount

* more tests

* ref: prefer object.entries

* jsdoc

* Fix field unmount issue in core

Fixes the issue with field unmount in core.

* ci: apply automated fixes and generate docs

* fix: update fieldInfo type to be partial and handle unmounted fields

* fix: cleanupFieldsOnUnmount flag

* fix: eslint

* fix: coderabbit findings

* fix: ensure async validation cancellation on field unmount

* more tests

* chore: remove default

* feat: listeners

* ci: apply automated fixes and generate docs

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Harry Whorlow <79278353+harry-whorlow@users.noreply.github.com>
Co-authored-by: Harry Whorlow <whorlowharry@gmail.com>

Author: 3 people

.changeset/red-hats-jam.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/form-core': patch
+'@tanstack/react-form': patch
+---
+
+fix(core): field unmount

docs/framework/angular/guides/listeners.md

@@ -15,10 +15,11 @@ In this example, when the user changes the country, the selected province needs
 
 Events that can be "listened" to are:
 
-- onChange
-- onBlur
-- onMount
-- onSubmit
+- `onChange`
+- `onBlur`
+- `onMount`
+- `onSubmit`
+- `onUnmount`
 
 ```angular-ts
 @Component({

docs/framework/react/guides/listeners.md

@@ -19,6 +19,7 @@ Events that can be "listened" to are:
 - `onBlur`
 - `onMount`
 - `onSubmit`
+- `onUnmount`
 
 ```tsx
 function App() {

docs/framework/vue/guides/listeners.md

@@ -15,10 +15,11 @@ In this example, when the user changes the country, the selected province needs
 
 Events that can be "listened" to are:
 
-- onChange
-- onBlur
-- onMount
-- onSubmit
+- `onChange`
+- `onBlur`
+- `onMount`
+- `onSubmit`
+- `onUnmount`
 
 ```vue
 <script setup>

packages/form-core/src/FieldApi.ts

@@ -382,6 +382,7 @@ export interface FieldListeners<
   onBlur?: FieldListenerFn<TParentData, TName, TData>
   onBlurDebounceMs?: number
   onMount?: FieldListenerFn<TParentData, TName, TData>
+  onUnmount?: FieldListenerFn<TParentData, TName, TData>
   onSubmit?: FieldListenerFn<TParentData, TName, TData>
 }
 
@@ -1275,6 +1276,7 @@ export class FieldApi<
 
   /**
    * Mounts the field instance to the form.
+   * @returns A function to unmount the field instance.
    */
   mount = () => {
     if (this.options.defaultValue !== undefined && !this.getMeta().isTouched) {
@@ -1322,8 +1324,86 @@ export class FieldApi<
       fieldApi: this,
     })
 
-    // TODO: Remove
-    return () => {}
+    return () => {
+      // Stop any in-flight async validation or listener work tied to this instance.
+      for (const [key, timeout] of Object.entries(
+        this.timeoutIds.validations,
+      )) {
+        if (timeout) {
+          clearTimeout(timeout)
+          this.timeoutIds.validations[
+            key as keyof typeof this.timeoutIds.validations
+          ] = null
+        }
+      }
+      for (const [key, timeout] of Object.entries(this.timeoutIds.listeners)) {
+        if (timeout) {
+          clearTimeout(timeout)
+          this.timeoutIds.listeners[
+            key as keyof typeof this.timeoutIds.listeners
+          ] = null
+        }
+      }
+      for (const [key, timeout] of Object.entries(
+        this.timeoutIds.formListeners,
+      )) {
+        if (timeout) {
+          clearTimeout(timeout)
+          this.timeoutIds.formListeners[
+            key as keyof typeof this.timeoutIds.formListeners
+          ] = null
+        }
+      }
+
+      const fieldInfo = this.form.fieldInfo[this.name]
+      if (!fieldInfo) return
+
+      // If a newer field instance has already been mounted for this name,
+      // avoid touching its shared validation state during teardown.
+      if (fieldInfo.instance !== this) return
+
+      for (const [key, validationMeta] of Object.entries(
+        fieldInfo.validationMetaMap,
+      )) {
+        validationMeta?.lastAbortController.abort()
+        fieldInfo.validationMetaMap[
+          key as keyof typeof fieldInfo.validationMetaMap
+        ] = undefined
+      }
+
+      this.form.baseStore.setState((prev) => ({
+        // Preserve interaction flags so field-level defaultValue does not
+        // reseed user-entered values on remount.
+        ...prev,
+        fieldMetaBase: {
+          ...prev.fieldMetaBase,
+          [this.name]: {
+            ...defaultFieldMeta,
+            isTouched:
+              prev.fieldMetaBase[this.name]?.isTouched ??
+              defaultFieldMeta.isTouched,
+            isBlurred:
+              prev.fieldMetaBase[this.name]?.isBlurred ??
+              defaultFieldMeta.isBlurred,
+            isDirty:
+              prev.fieldMetaBase[this.name]?.isDirty ??
+              defaultFieldMeta.isDirty,
+          },
+        },
+      }))
+
+      fieldInfo.instance = null
+
+      this.options.listeners?.onUnmount?.({
+        value: this.state.value,
+        fieldApi: this,
+      })
+
+      this.form.options.listeners?.onFieldUnmount?.({
+        formApi: this.form,
+        fieldApi: this,
+      })
+    }
   }
 
   /**
@@ -1790,12 +1870,13 @@ export class FieldApi<
       promises: Promise<ValidationError | undefined>[],
     ) => {
       const errorMapKey = getErrorMapKey(validateObj.cause)
-      const fieldValidatorMeta = field.getInfo().validationMetaMap[errorMapKey]
+      const fieldInfo = field.getInfo()
+      const fieldValidatorMeta = fieldInfo.validationMetaMap[errorMapKey]
 
       fieldValidatorMeta?.lastAbortController.abort()
       const controller = new AbortController()
 
-      this.getInfo().validationMetaMap[errorMapKey] = {
+      fieldInfo.validationMetaMap[errorMapKey] = {
         lastAbortController: controller,
       }
 
@@ -1804,11 +1885,11 @@ export class FieldApi<
           let rawError!: ValidationError | undefined
           try {
             rawError = await new Promise((rawResolve, rawReject) => {
-              if (this.timeoutIds.validations[validateObj.cause]) {
-                clearTimeout(this.timeoutIds.validations[validateObj.cause]!)
+              if (field.timeoutIds.validations[validateObj.cause]) {
+                clearTimeout(field.timeoutIds.validations[validateObj.cause]!)
               }
 
-              this.timeoutIds.validations[validateObj.cause] = setTimeout(
+              field.timeoutIds.validations[validateObj.cause] = setTimeout(
                 async () => {
                   if (controller.signal.aborted) return rawResolve(undefined)
                   try {
@@ -1838,14 +1919,20 @@ export class FieldApi<
 
           const fieldLevelError = normalizeError(rawError)
           const formLevelError =
-            asyncFormValidationResults[this.name]?.[errorMapKey]
+            asyncFormValidationResults[
+              field.name as keyof typeof asyncFormValidationResults
+            ]?.[errorMapKey]
 
           const { newErrorValue, newSource } =
             determineFieldLevelErrorSourceAndValue({
               formLevelError,
               fieldLevelError,
             })
 
+          if (field.getInfo().instance !== field) {
+            return resolve(undefined)
+          }
+
           field.setMeta((prev) => {
             return {
               ...prev,

packages/form-core/src/FormApi.ts

@@ -306,6 +306,24 @@ export interface FormListeners<
     >
     meta: TSubmitMeta
   }) => void
+
+  onFieldUnmount?: (props: {
+    formApi: FormApi<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnDynamic,
+      TOnDynamicAsync,
+      TOnServer,
+      TSubmitMeta
+    >
+    fieldApi: AnyFieldApi
+  }) => void
 }
 
 /**
@@ -925,7 +943,7 @@ export class FormApi<
   /**
    * A record of field information for each field in the form.
    */
-  fieldInfo: Record<DeepKeys<TFormData>, FieldInfo<TFormData>> = {} as any
+  fieldInfo: Partial<Record<DeepKeys<TFormData>, FieldInfo<TFormData>>> = {}
 
   get state() {
     return this.store.state
@@ -1603,7 +1621,6 @@ export class FormApi<
     field: TField,
     cause: ValidationCause,
   ) => {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     const fieldInstance = this.fieldInfo[field]?.instance
 
     if (!fieldInstance) {
@@ -2222,7 +2239,6 @@ export class FormApi<
   getFieldInfo = <TField extends DeepKeys<TFormData>>(
     field: TField,
   ): FieldInfo<TFormData> => {
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     return (this.fieldInfo[field] ||= {
       instance: null,
       validationMetaMap: {