@tanstack/form-core 1.6.3 → 1.8.0

package/src/FormApi.ts

@@ -22,7 +22,12 @@ import type {
   StandardSchemaV1Issue,
   TStandardSchemaValidatorValue,
 } from './standardSchemaValidator'
-import type { AnyFieldMeta, AnyFieldMetaBase, FieldApi } from './FieldApi'
+import type {
+  AnyFieldApi,
+  AnyFieldMeta,
+  AnyFieldMetaBase,
+  FieldApi,
+} from './FieldApi'
 import type {
   FormValidationError,
   FormValidationErrorMap,
@@ -233,6 +238,83 @@ export interface FormTransform<
   deps: unknown[]
 }
 
+export interface FormListeners<
+  TFormData,
+  TOnMount extends undefined | FormValidateOrFn<TFormData>,
+  TOnChange extends undefined | FormValidateOrFn<TFormData>,
+  TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnBlur extends undefined | FormValidateOrFn<TFormData>,
+  TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
+  TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TSubmitMeta = never,
+> {
+  onChange?: (props: {
+    formApi: FormApi<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnServer,
+      TSubmitMeta
+    >
+    fieldApi: AnyFieldApi
+  }) => void
+  onChangeDebounceMs?: number
+
+  onBlur?: (props: {
+    formApi: FormApi<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnServer,
+      TSubmitMeta
+    >
+    fieldApi: AnyFieldApi
+  }) => void
+  onBlurDebounceMs?: number
+
+  onMount?: (props: {
+    formApi: FormApi<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnServer,
+      TSubmitMeta
+    >
+  }) => void
+
+  onSubmit?: (props: {
+    formApi: FormApi<
+      TFormData,
+      TOnMount,
+      TOnChange,
+      TOnChangeAsync,
+      TOnBlur,
+      TOnBlurAsync,
+      TOnSubmit,
+      TOnSubmitAsync,
+      TOnServer,
+      TSubmitMeta
+    >
+  }) => void
+}
+
 /**
  * An object representing the options for a form.
  */
@@ -299,6 +381,22 @@ export interface FormOptions<
    */
   onSubmitMeta?: TSubmitMeta
 
+  /**
+   * form level listeners
+   */
+  listeners?: FormListeners<
+    TFormData,
+    TOnMount,
+    TOnChange,
+    TOnChangeAsync,
+    TOnBlur,
+    TOnBlurAsync,
+    TOnSubmit,
+    TOnSubmitAsync,
+    TOnServer,
+    TSubmitMeta
+  >
+
   /**
    * A function to be called when the form is submitted, what should happen once the user submits a valid form returns `any` or a promise `Promise<any>`
    */
@@ -1049,6 +1147,9 @@ export class FormApi<
       cleanupFieldMetaDerived()
       cleanupStoreDerived()
     }
+
+    this.options.listeners?.onMount?.({ formApi: this })
+
     const { onMount } = this.options.validators || {}
     if (!onMount) return cleanup
     this.validateSync('mount')
@@ -1607,7 +1708,7 @@ export class FormApi<
   }
 
   /**
-   * Handles the form submission, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks.
+   * Handles the form submission, performs validation, and calls the appropriate onSubmit or onSubmitInvalid callbacks.
    */
   handleSubmit(): Promise<void>
   handleSubmit(submitMeta: TSubmitMeta): Promise<void>
@@ -1676,6 +1777,8 @@ export class FormApi<
       )
     })
 
+    this.options.listeners?.onSubmit?.({ formApi: this })
+
     try {
       // Run the submit code
       await this.options.onSubmit?.({