@tanstack/form-core 0.44.1 → 0.45.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/form-core",
-  "version": "0.44.1",
+  "version": "0.45.0",
   "description": "Powerful, type-safe, framework agnostic forms.",
   "author": "tannerlinsley",
   "license": "MIT",

package/src/FieldApi.ts

@@ -96,6 +96,7 @@ export type FieldValidateFn<
     any,
     any,
     any,
+    any,
     any
   >
 }) => unknown
@@ -179,6 +180,7 @@ export type FieldValidateAsyncFn<
     any,
     any,
     any,
+    any,
     any
   >
   signal: AbortSignal
@@ -261,6 +263,7 @@ export type FieldListenerFn<
     any,
     any,
     any,
+    any,
     any
   >
 }) => void
@@ -471,6 +474,7 @@ export interface FieldApiOptions<
   TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
   TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
+  TParentSubmitMeta,
 > extends FieldOptions<
     TParentData,
     TName,
@@ -492,7 +496,8 @@ export interface FieldApiOptions<
     TFormOnBlurAsync,
     TFormOnSubmit,
     TFormOnSubmitAsync,
-    TFormOnServer
+    TFormOnServer,
+    TParentSubmitMeta
   >
 }
 
@@ -843,6 +848,7 @@ export type AnyFieldApi = FieldApi<
   any,
   any,
   any,
+  any,
   any
 >
 
@@ -880,6 +886,7 @@ export class FieldApi<
   TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
   TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
   TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
+  TParentSubmitMeta,
 > {
   /**
    * A reference to the form API instance.
@@ -902,7 +909,8 @@ export class FieldApi<
     TFormOnBlurAsync,
     TFormOnSubmit,
     TFormOnSubmitAsync,
-    TFormOnServer
+    TFormOnServer,
+    TParentSubmitMeta
   >['form']
   /**
    * The field name.
@@ -929,7 +937,8 @@ export class FieldApi<
     TFormOnBlurAsync,
     TFormOnSubmit,
     TFormOnSubmitAsync,
-    TFormOnServer
+    TFormOnServer,
+    TParentSubmitMeta
   > = {} as any
   /**
    * The field state store.
@@ -985,7 +994,8 @@ export class FieldApi<
       TFormOnBlurAsync,
       TFormOnSubmit,
       TFormOnSubmitAsync,
-      TFormOnServer
+      TFormOnServer,
+      TParentSubmitMeta
     >,
   ) {
     this.form = opts.form as never
@@ -1130,7 +1140,8 @@ export class FieldApi<
       TFormOnBlurAsync,
       TFormOnSubmit,
       TFormOnSubmitAsync,
-      TFormOnServer
+      TFormOnServer,
+      TParentSubmitMeta
     >,
   ) => {
     // Default Value

package/src/FormApi.test-d.ts

@@ -0,0 +1,31 @@
+import { assertType, it } from 'vitest'
+import { FormApi } from '../src/index'
+
+it('should type handleSubmit as never when onSubmitMeta is not passed', () => {
+  const form = new FormApi({
+    defaultValues: {
+      name: 'test',
+    },
+  } as const)
+
+  assertType<() => Promise<void>>(form.handleSubmit)
+})
+
+type OnSubmitMeta = {
+  group: string
+}
+
+it('should type handleChange correctly', () => {
+  const form = new FormApi({
+    defaultValues: {
+      name: 'test',
+    },
+    onSubmitMeta: {} as OnSubmitMeta,
+  } as const)
+
+  form.handleSubmit({ group: 'track' })
+
+  assertType<(submitMeta: { group: string }) => Promise<void>>(
+    form.handleSubmit,
+  )
+})

package/src/FormApi.ts

@@ -74,6 +74,7 @@ export type FormValidateFn<TFormData> = (props: {
     any,
     any,
     any,
+    any,
     any
   >
 }) => unknown
@@ -109,6 +110,7 @@ export type FormValidateAsyncFn<TFormData> = (props: {
     any,
     any,
     any,
+    any,
     any
   >
   signal: AbortSignal
@@ -199,6 +201,7 @@ export interface FormTransform<
   TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
   TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
   TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TSubmitMeta = never,
 > {
   fn: (
     formBase: FormApi<
@@ -210,7 +213,8 @@ export interface FormTransform<
       TOnBlurAsync,
       TOnSubmit,
       TOnSubmitAsync,
-      TOnServer
+      TOnServer,
+      TSubmitMeta
     >,
   ) => FormApi<
     TFormData,
@@ -221,7 +225,8 @@ export interface FormTransform<
     TOnBlurAsync,
     TOnSubmit,
     TOnSubmitAsync,
-    TOnServer
+    TOnServer,
+    TSubmitMeta
   >
   deps: unknown[]
 }
@@ -239,6 +244,7 @@ export interface FormOptions<
   TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
   TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
   TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TSubmitMeta = never,
 > {
   /**
    * Set initial values for your form.
@@ -281,6 +287,12 @@ export interface FormOptions<
     TOnSubmit,
     TOnSubmitAsync
   >
+
+  /**
+   * onSubmitMeta, the data passed from the handleSubmit handler, to the onSubmit function props
+   */
+  onSubmitMeta?: 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>`
    */
@@ -295,8 +307,10 @@ export interface FormOptions<
       TOnBlurAsync,
       TOnSubmit,
       TOnSubmitAsync,
-      TOnServer
+      TOnServer,
+      TSubmitMeta
     >
+    meta: TSubmitMeta
   }) => any | Promise<any>
   /**
    * Specify an action for scenarios where the user tries to submit an invalid form.
@@ -312,7 +326,8 @@ export interface FormOptions<
       TOnBlurAsync,
       TOnSubmit,
       TOnSubmitAsync,
-      TOnServer
+      TOnServer,
+      TSubmitMeta
     >
   }) => void
   transform?: FormTransform<
@@ -324,7 +339,8 @@ export interface FormOptions<
     TOnBlurAsync,
     TOnSubmit,
     TOnSubmitAsync,
-    TOnServer
+    TOnServer,
+    TSubmitMeta
   >
 }
 
@@ -363,6 +379,7 @@ export type FieldInfo<TFormData> = {
     any,
     any,
     any,
+    any,
     any
   > | null
   /**
@@ -610,7 +627,18 @@ function getDefaultFormState<
  *
  * A type representing the Form API with all generics set to `any` for convenience.
  */
-export type AnyFormApi = FormApi<any, any, any, any, any, any, any, any, any>
+export type AnyFormApi = FormApi<
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any,
+  any
+>
 
 /**
  * A class representing the Form API. It handles the logic and interactions with the form state.
@@ -629,6 +657,7 @@ export class FormApi<
   TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
   TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
   TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TSubmitMeta = never,
 > {
   /**
    * The options for the form.
@@ -642,7 +671,8 @@ export class FormApi<
     TOnBlurAsync,
     TOnSubmit,
     TOnSubmitAsync,
-    TOnServer
+    TOnServer,
+    TSubmitMeta
   > = {}
   baseStore!: Store<
     BaseFormState<
@@ -698,7 +728,8 @@ export class FormApi<
       TOnBlurAsync,
       TOnSubmit,
       TOnSubmitAsync,
-      TOnServer
+      TOnServer,
+      TSubmitMeta
     >,
   ) {
     this.baseStore = new Store(
@@ -958,6 +989,8 @@ export class FormApi<
       },
     })
 
+    this.handleSubmit = this.handleSubmit.bind(this)
+
     this.update(opts || {})
   }
 
@@ -1013,7 +1046,8 @@ export class FormApi<
       TOnBlurAsync,
       TOnSubmit,
       TOnSubmitAsync,
-      TOnServer
+      TOnServer,
+      TSubmitMeta
     >,
   ) => {
     if (!options) return
@@ -1482,7 +1516,9 @@ export class FormApi<
   /**
    * Handles the form submission, performs validation, and calls the appropriate onSubmit or onInvalidSubmit callbacks.
    */
-  handleSubmit = async () => {
+  handleSubmit(): Promise<void>
+  handleSubmit(submitMeta: TSubmitMeta): Promise<void>
+  async handleSubmit(submitMeta?: TSubmitMeta): Promise<void> {
     this.baseStore.setState((old) => ({
       ...old,
       // Submission attempts mark the form as not submitted
@@ -1536,7 +1572,11 @@ export class FormApi<
 
     try {
       // Run the submit code
-      await this.options.onSubmit?.({ value: this.state.values, formApi: this })
+      await this.options.onSubmit?.({
+        value: this.state.values,
+        formApi: this,
+        meta: submitMeta ?? this.options.onSubmitMeta,
+      } as any)
 
       batch(() => {
         this.baseStore.setState((prev) => ({ ...prev, isSubmitted: true }))

package/src/formOptions.ts

@@ -14,6 +14,7 @@ export function formOptions<
   TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
   TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
   TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TSubmitMeta,
 >(
   defaultOpts?: FormOptions<
     TFormData,
@@ -24,7 +25,8 @@ export function formOptions<
     TOnBlurAsync,
     TOnSubmit,
     TOnSubmitAsync,
-    TOnServer
+    TOnServer,
+    TSubmitMeta
   >,
 ) {
   return defaultOpts

package/src/mergeForm.ts

@@ -72,9 +72,20 @@ export function mutateMergeDeep(
 }
 
 export function mergeForm<TFormData>(
-  baseForm: FormApi<NoInfer<TFormData>, any, any, any, any, any, any, any, any>,
+  baseForm: FormApi<
+    NoInfer<TFormData>,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any,
+    any
+  >,
   state: Partial<
-    FormApi<TFormData, any, any, any, any, any, any, any, any>['state']
+    FormApi<TFormData, any, any, any, any, any, any, any, any, any>['state']
   >,
 ) {
   mutateMergeDeep(baseForm.state, state)

package/src/metaHelper.ts

@@ -18,6 +18,7 @@ export function metaHelper<
   TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
   TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
   TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
+  TSubmitMeta,
 >(
   formApi: FormApi<
     TFormData,
@@ -28,7 +29,8 @@ export function metaHelper<
     TOnBlurAsync,
     TOnSubmit,
     TOnSubmitAsync,
-    TOnServer
+    TOnServer,
+    TSubmitMeta
   >,
 ) {
   function handleArrayFieldMetaShift(