@tanstack/form-core 0.44.0 → 0.45.0

package/package.json

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

package/src/FieldApi.ts

@@ -19,9 +19,9 @@ import type {
   FieldInfo,
   FormApi,
   FormAsyncValidateOrFn,
+  FormValidateAsyncFn,
+  FormValidateFn,
   FormValidateOrFn,
-  UnwrapFormAsyncValidateOrFn,
-  UnwrapFormValidateOrFn,
 } from './FormApi'
 import type {
   UpdateMetaOptions,
@@ -96,6 +96,7 @@ export type FieldValidateFn<
     any,
     any,
     any,
+    any,
     any
   >
 }) => unknown
@@ -111,6 +112,16 @@ export type FieldValidateOrFn<
   | FieldValidateFn<TParentData, TName, TData>
   | StandardSchemaV1<TData, unknown>
 
+type StandardBrandedSchemaV1<T> = T & { __standardSchemaV1: true }
+
+type UnwrapFormValidateOrFnForInner<
+  TValidateOrFn extends undefined | FormValidateOrFn<any>,
+> = [TValidateOrFn] extends [FormValidateFn<any>]
+  ? ReturnType<TValidateOrFn>
+  : [TValidateOrFn] extends [StandardSchemaV1<infer TOut, any>]
+    ? StandardBrandedSchemaV1<TOut>
+    : undefined
+
 export type UnwrapFieldValidateOrFn<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -122,12 +133,16 @@ export type UnwrapFieldValidateOrFn<
         ? StandardSchemaV1Issue[]
         : undefined
       : undefined)
-  | (UnwrapFormValidateOrFn<TFormValidateOrFn> extends infer TFormValidateVal
-      ? TFormValidateVal extends { fields: any }
-        ? TName extends keyof TFormValidateVal['fields']
-          ? TFormValidateVal['fields'][TName]
+  | (UnwrapFormValidateOrFnForInner<TFormValidateOrFn> extends infer TFormValidateVal
+      ? TFormValidateVal extends { __standardSchemaV1: true }
+        ? [DeepValue<TFormValidateVal, TName>] extends [never]
+          ? undefined
+          : StandardSchemaV1Issue[]
+        : TFormValidateVal extends { fields: any }
+          ? TName extends keyof TFormValidateVal['fields']
+            ? TFormValidateVal['fields'][TName]
+            : undefined
           : undefined
-        : undefined
       : never)
   | ([TValidateOrFn] extends [FieldValidateFn<any, any, any>]
       ? ReturnType<TValidateOrFn>
@@ -165,6 +180,7 @@ export type FieldValidateAsyncFn<
     any,
     any,
     any,
+    any,
     any
   >
   signal: AbortSignal
@@ -181,6 +197,14 @@ export type FieldAsyncValidateOrFn<
   | FieldValidateAsyncFn<TParentData, TName, TData>
   | StandardSchemaV1<TData, unknown>
 
+type UnwrapFormAsyncValidateOrFnForInner<
+  TValidateOrFn extends undefined | FormAsyncValidateOrFn<any>,
+> = [TValidateOrFn] extends [FormValidateAsyncFn<any>]
+  ? Awaited<ReturnType<TValidateOrFn>>
+  : [TValidateOrFn] extends [StandardSchemaV1<infer TOut, any>]
+    ? StandardBrandedSchemaV1<TOut>
+    : undefined
+
 export type UnwrapFieldAsyncValidateOrFn<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -192,12 +216,16 @@ export type UnwrapFieldAsyncValidateOrFn<
         ? StandardSchemaV1Issue[]
         : undefined
       : undefined)
-  | (UnwrapFormAsyncValidateOrFn<TFormValidateOrFn> extends infer TFormValidateVal
-      ? TFormValidateVal extends { fields: any }
-        ? TName extends keyof TFormValidateVal['fields']
-          ? TFormValidateVal['fields'][TName]
+  | (UnwrapFormAsyncValidateOrFnForInner<TFormValidateOrFn> extends infer TFormValidateVal
+      ? TFormValidateVal extends { __standardSchemaV1: true }
+        ? [DeepValue<TFormValidateVal, TName>] extends [never]
+          ? undefined
+          : StandardSchemaV1Issue[]
+        : TFormValidateVal extends { fields: any }
+          ? TName extends keyof TFormValidateVal['fields']
+            ? TFormValidateVal['fields'][TName]
+            : undefined
           : undefined
-        : undefined
       : never)
   | ([TValidateOrFn] extends [FieldValidateAsyncFn<any, any, any>]
       ? Awaited<ReturnType<TValidateOrFn>>
@@ -235,6 +263,7 @@ export type FieldListenerFn<
     any,
     any,
     any,
+    any,
     any
   >
 }) => void
@@ -445,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,
@@ -466,7 +496,8 @@ export interface FieldApiOptions<
     TFormOnBlurAsync,
     TFormOnSubmit,
     TFormOnSubmitAsync,
-    TFormOnServer
+    TFormOnServer,
+    TParentSubmitMeta
   >
 }
 
@@ -817,6 +848,7 @@ export type AnyFieldApi = FieldApi<
   any,
   any,
   any,
+  any,
   any
 >
 
@@ -854,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.
@@ -876,7 +909,8 @@ export class FieldApi<
     TFormOnBlurAsync,
     TFormOnSubmit,
     TFormOnSubmitAsync,
-    TFormOnServer
+    TFormOnServer,
+    TParentSubmitMeta
   >['form']
   /**
    * The field name.
@@ -903,7 +937,8 @@ export class FieldApi<
     TFormOnBlurAsync,
     TFormOnSubmit,
     TFormOnSubmitAsync,
-    TFormOnServer
+    TFormOnServer,
+    TParentSubmitMeta
   > = {} as any
   /**
    * The field state store.
@@ -959,7 +994,8 @@ export class FieldApi<
       TFormOnBlurAsync,
       TFormOnSubmit,
       TFormOnSubmitAsync,
-      TFormOnServer
+      TFormOnServer,
+      TParentSubmitMeta
     >,
   ) {
     this.form = opts.form as never
@@ -1104,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(