@tanstack/form-core 0.44.1 → 0.45.1

package/dist/esm/mergeForm.js.map

@@ -1 +1 @@
-{"version":3,"file":"mergeForm.js","sources":["../../src/mergeForm.ts"],"sourcesContent":["import type { FormApi } from './FormApi'\nimport type { NoInfer } from './util-types'\n\nfunction isValidKey(key: string | number | symbol): boolean {\n  const dangerousProps = ['__proto__', 'constructor', 'prototype']\n  return !dangerousProps.includes(String(key))\n}\n\n/**\n * @private\n */\nexport function mutateMergeDeep(\n  target: object | null | undefined,\n  source: object | null | undefined,\n): object {\n  // Early return if either is not an object\n  if (target === null || target === undefined || typeof target !== 'object')\n    return {} as object\n  if (source === null || source === undefined || typeof source !== 'object')\n    return target\n\n  const targetKeys = Object.keys(target)\n  const sourceKeys = Object.keys(source)\n  const keySet = new Set([...targetKeys, ...sourceKeys])\n\n  for (const key of keySet) {\n    if (!isValidKey(key)) continue\n\n    const targetKey = key as keyof typeof target\n    const sourceKey = key as keyof typeof source\n\n    if (!Object.hasOwn(source, sourceKey)) continue\n\n    const sourceValue = source[sourceKey] as unknown\n    const targetValue = target[targetKey] as unknown\n\n    // Handle arrays\n    if (Array.isArray(targetValue) && Array.isArray(sourceValue)) {\n      Object.defineProperty(target, key, {\n        value: [...sourceValue],\n        enumerable: true,\n        writable: true,\n        configurable: true,\n      })\n      continue\n    }\n\n    // Handle nested objects (type assertion to satisfy ESLint)\n    const isTargetObj = typeof targetValue === 'object' && targetValue !== null\n    const isSourceObj = typeof sourceValue === 'object' && sourceValue !== null\n    const areObjects =\n      isTargetObj &&\n      isSourceObj &&\n      !Array.isArray(targetValue) &&\n      !Array.isArray(sourceValue)\n\n    if (areObjects) {\n      mutateMergeDeep(targetValue as object, sourceValue as object)\n      continue\n    }\n\n    // Handle all other cases\n    Object.defineProperty(target, key, {\n      value: sourceValue,\n      enumerable: true,\n      writable: true,\n      configurable: true,\n    })\n  }\n\n  return target\n}\n\nexport function mergeForm<TFormData>(\n  baseForm: FormApi<NoInfer<TFormData>, any, any, any, any, any, any, any, any>,\n  state: Partial<\n    FormApi<TFormData, any, any, any, any, any, any, any, any>['state']\n  >,\n) {\n  mutateMergeDeep(baseForm.state, state)\n  return baseForm\n}\n"],"names":[],"mappings":"AAGA,SAAS,WAAW,KAAwC;AAC1D,QAAM,iBAAiB,CAAC,aAAa,eAAe,WAAW;AAC/D,SAAO,CAAC,eAAe,SAAS,OAAO,GAAG,CAAC;AAC7C;AAKgB,SAAA,gBACd,QACA,QACQ;AAER,MAAI,WAAW,QAAQ,WAAW,UAAa,OAAO,WAAW;AAC/D,WAAO,CAAC;AACV,MAAI,WAAW,QAAQ,WAAW,UAAa,OAAO,WAAW;AACxD,WAAA;AAEH,QAAA,aAAa,OAAO,KAAK,MAAM;AAC/B,QAAA,aAAa,OAAO,KAAK,MAAM;AAC/B,QAAA,6BAAa,IAAI,CAAC,GAAG,YAAY,GAAG,UAAU,CAAC;AAErD,aAAW,OAAO,QAAQ;AACpB,QAAA,CAAC,WAAW,GAAG,EAAG;AAEtB,UAAM,YAAY;AAClB,UAAM,YAAY;AAElB,QAAI,CAAC,OAAO,OAAO,QAAQ,SAAS,EAAG;AAEjC,UAAA,cAAc,OAAO,SAAS;AAC9B,UAAA,cAAc,OAAO,SAAS;AAGpC,QAAI,MAAM,QAAQ,WAAW,KAAK,MAAM,QAAQ,WAAW,GAAG;AACrD,aAAA,eAAe,QAAQ,KAAK;AAAA,QACjC,OAAO,CAAC,GAAG,WAAW;AAAA,QACtB,YAAY;AAAA,QACZ,UAAU;AAAA,QACV,cAAc;AAAA,MAAA,CACf;AACD;AAAA,IAAA;AAIF,UAAM,cAAc,OAAO,gBAAgB,YAAY,gBAAgB;AACvE,UAAM,cAAc,OAAO,gBAAgB,YAAY,gBAAgB;AACjE,UAAA,aACJ,eACA,eACA,CAAC,MAAM,QAAQ,WAAW,KAC1B,CAAC,MAAM,QAAQ,WAAW;AAE5B,QAAI,YAAY;AACd,sBAAgB,aAAuB,WAAqB;AAC5D;AAAA,IAAA;AAIK,WAAA,eAAe,QAAQ,KAAK;AAAA,MACjC,OAAO;AAAA,MACP,YAAY;AAAA,MACZ,UAAU;AAAA,MACV,cAAc;AAAA,IAAA,CACf;AAAA,EAAA;AAGI,SAAA;AACT;AAEgB,SAAA,UACd,UACA,OAGA;AACgB,kBAAA,SAAS,OAAO,KAAK;AAC9B,SAAA;AACT;"}
+{"version":3,"file":"mergeForm.js","sources":["../../src/mergeForm.ts"],"sourcesContent":["import type { FormApi } from './FormApi'\nimport type { NoInfer } from './util-types'\n\nfunction isValidKey(key: string | number | symbol): boolean {\n  const dangerousProps = ['__proto__', 'constructor', 'prototype']\n  return !dangerousProps.includes(String(key))\n}\n\n/**\n * @private\n */\nexport function mutateMergeDeep(\n  target: object | null | undefined,\n  source: object | null | undefined,\n): object {\n  // Early return if either is not an object\n  if (target === null || target === undefined || typeof target !== 'object')\n    return {} as object\n  if (source === null || source === undefined || typeof source !== 'object')\n    return target\n\n  const targetKeys = Object.keys(target)\n  const sourceKeys = Object.keys(source)\n  const keySet = new Set([...targetKeys, ...sourceKeys])\n\n  for (const key of keySet) {\n    if (!isValidKey(key)) continue\n\n    const targetKey = key as keyof typeof target\n    const sourceKey = key as keyof typeof source\n\n    if (!Object.hasOwn(source, sourceKey)) continue\n\n    const sourceValue = source[sourceKey] as unknown\n    const targetValue = target[targetKey] as unknown\n\n    // Handle arrays\n    if (Array.isArray(targetValue) && Array.isArray(sourceValue)) {\n      Object.defineProperty(target, key, {\n        value: [...sourceValue],\n        enumerable: true,\n        writable: true,\n        configurable: true,\n      })\n      continue\n    }\n\n    // Handle nested objects (type assertion to satisfy ESLint)\n    const isTargetObj = typeof targetValue === 'object' && targetValue !== null\n    const isSourceObj = typeof sourceValue === 'object' && sourceValue !== null\n    const areObjects =\n      isTargetObj &&\n      isSourceObj &&\n      !Array.isArray(targetValue) &&\n      !Array.isArray(sourceValue)\n\n    if (areObjects) {\n      mutateMergeDeep(targetValue as object, sourceValue as object)\n      continue\n    }\n\n    // Handle all other cases\n    Object.defineProperty(target, key, {\n      value: sourceValue,\n      enumerable: true,\n      writable: true,\n      configurable: true,\n    })\n  }\n\n  return target\n}\n\nexport function mergeForm<TFormData>(\n  baseForm: FormApi<\n    NoInfer<TFormData>,\n    any,\n    any,\n    any,\n    any,\n    any,\n    any,\n    any,\n    any,\n    any\n  >,\n  state: Partial<\n    FormApi<TFormData, any, any, any, any, any, any, any, any, any>['state']\n  >,\n) {\n  mutateMergeDeep(baseForm.state, state)\n  return baseForm\n}\n"],"names":[],"mappings":"AAGA,SAAS,WAAW,KAAwC;AAC1D,QAAM,iBAAiB,CAAC,aAAa,eAAe,WAAW;AAC/D,SAAO,CAAC,eAAe,SAAS,OAAO,GAAG,CAAC;AAC7C;AAKgB,SAAA,gBACd,QACA,QACQ;AAER,MAAI,WAAW,QAAQ,WAAW,UAAa,OAAO,WAAW;AAC/D,WAAO,CAAC;AACV,MAAI,WAAW,QAAQ,WAAW,UAAa,OAAO,WAAW;AACxD,WAAA;AAEH,QAAA,aAAa,OAAO,KAAK,MAAM;AAC/B,QAAA,aAAa,OAAO,KAAK,MAAM;AAC/B,QAAA,6BAAa,IAAI,CAAC,GAAG,YAAY,GAAG,UAAU,CAAC;AAErD,aAAW,OAAO,QAAQ;AACpB,QAAA,CAAC,WAAW,GAAG,EAAG;AAEtB,UAAM,YAAY;AAClB,UAAM,YAAY;AAElB,QAAI,CAAC,OAAO,OAAO,QAAQ,SAAS,EAAG;AAEjC,UAAA,cAAc,OAAO,SAAS;AAC9B,UAAA,cAAc,OAAO,SAAS;AAGpC,QAAI,MAAM,QAAQ,WAAW,KAAK,MAAM,QAAQ,WAAW,GAAG;AACrD,aAAA,eAAe,QAAQ,KAAK;AAAA,QACjC,OAAO,CAAC,GAAG,WAAW;AAAA,QACtB,YAAY;AAAA,QACZ,UAAU;AAAA,QACV,cAAc;AAAA,MAAA,CACf;AACD;AAAA,IAAA;AAIF,UAAM,cAAc,OAAO,gBAAgB,YAAY,gBAAgB;AACvE,UAAM,cAAc,OAAO,gBAAgB,YAAY,gBAAgB;AACjE,UAAA,aACJ,eACA,eACA,CAAC,MAAM,QAAQ,WAAW,KAC1B,CAAC,MAAM,QAAQ,WAAW;AAE5B,QAAI,YAAY;AACd,sBAAgB,aAAuB,WAAqB;AAC5D;AAAA,IAAA;AAIK,WAAA,eAAe,QAAQ,KAAK;AAAA,MACjC,OAAO;AAAA,MACP,YAAY;AAAA,MACZ,UAAU;AAAA,MACV,cAAc;AAAA,IAAA,CACf;AAAA,EAAA;AAGI,SAAA;AACT;AAEgB,SAAA,UACd,UAYA,OAGA;AACgB,kBAAA,SAAS,OAAO,KAAK;AAC9B,SAAA;AACT;"}

package/dist/esm/metaHelper.d.ts

@@ -1,7 +1,7 @@
 import { FormApi, FormAsyncValidateOrFn, FormValidateOrFn } from './FormApi.js';
 import { DeepKeys } from './util-types.js';
 type ArrayFieldMode = 'insert' | 'remove' | 'swap' | 'move';
-export declare function metaHelper<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>>(formApi: FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnServer>): {
+export declare function metaHelper<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>(formApi: FormApi<TFormData, TOnMount, TOnChange, TOnChangeAsync, TOnBlur, TOnBlurAsync, TOnSubmit, TOnSubmitAsync, TOnServer, TSubmitMeta>): {
     handleArrayFieldMetaShift: (field: DeepKeys<TFormData>, index: number, mode: ArrayFieldMode, secondIndex?: number) => void;
 };
 export {};

package/dist/esm/metaHelper.js.map

@@ -1 +1 @@
-{"version":3,"file":"metaHelper.js","sources":["../../src/metaHelper.ts"],"sourcesContent":["import type {\n  FormApi,\n  FormAsyncValidateOrFn,\n  FormValidateOrFn,\n} from './FormApi'\nimport type { AnyFieldMeta } from './FieldApi'\nimport type { DeepKeys } from './util-types'\n\ntype ArrayFieldMode = 'insert' | 'remove' | 'swap' | 'move'\n\nexport function metaHelper<\n  TFormData,\n  TOnMount extends undefined | FormValidateOrFn<TFormData>,\n  TOnChange extends undefined | FormValidateOrFn<TFormData>,\n  TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,\n  TOnBlur extends undefined | FormValidateOrFn<TFormData>,\n  TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,\n  TOnSubmit extends undefined | FormValidateOrFn<TFormData>,\n  TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,\n  TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,\n>(\n  formApi: FormApi<\n    TFormData,\n    TOnMount,\n    TOnChange,\n    TOnChangeAsync,\n    TOnBlur,\n    TOnBlurAsync,\n    TOnSubmit,\n    TOnSubmitAsync,\n    TOnServer\n  >,\n) {\n  function handleArrayFieldMetaShift(\n    field: DeepKeys<TFormData>,\n    index: number,\n    mode: ArrayFieldMode,\n    secondIndex?: number,\n  ) {\n    const affectedFields = getAffectedFields(field, index, mode, secondIndex)\n\n    const handlers = {\n      insert: () => handleInsertMode(affectedFields, field, index),\n      remove: () => handleRemoveMode(affectedFields),\n      swap: () =>\n        secondIndex !== undefined &&\n        handleSwapMode(affectedFields, field, index, secondIndex),\n      move: () =>\n        secondIndex !== undefined &&\n        handleMoveMode(affectedFields, field, index, secondIndex),\n    }\n\n    handlers[mode]()\n  }\n\n  function getFieldPath(field: DeepKeys<TFormData>, index: number): string {\n    return `${field}[${index}]`\n  }\n\n  function getAffectedFields(\n    field: DeepKeys<TFormData>,\n    index: number,\n    mode: ArrayFieldMode,\n    secondIndex?: number,\n  ): DeepKeys<TFormData>[] {\n    const affectedFieldKeys = [getFieldPath(field, index)]\n\n    if (mode === 'swap') {\n      affectedFieldKeys.push(getFieldPath(field, secondIndex!))\n    } else if (mode === 'move') {\n      const [startIndex, endIndex] = [\n        Math.min(index, secondIndex!),\n        Math.max(index, secondIndex!),\n      ]\n      for (let i = startIndex; i <= endIndex; i++) {\n        affectedFieldKeys.push(getFieldPath(field, i))\n      }\n    } else {\n      const currentValue = formApi.getFieldValue(field)\n      const fieldItems = Array.isArray(currentValue) ? currentValue.length : 0\n      for (let i = index + 1; i < fieldItems; i++) {\n        affectedFieldKeys.push(getFieldPath(field, i))\n      }\n    }\n\n    return Object.keys(formApi.fieldInfo).filter((fieldKey) =>\n      affectedFieldKeys.some((key) => fieldKey.startsWith(key)),\n    ) as DeepKeys<TFormData>[]\n  }\n\n  function updateIndex(\n    fieldKey: string,\n    direction: 'up' | 'down',\n  ): DeepKeys<TFormData> {\n    return fieldKey.replace(/\\[(\\d+)\\]/, (_, num) => {\n      const currIndex = parseInt(num, 10)\n      const newIndex =\n        direction === 'up' ? currIndex + 1 : Math.max(0, currIndex - 1)\n      return `[${newIndex}]`\n    }) as DeepKeys<TFormData>\n  }\n\n  function shiftMeta(fields: DeepKeys<TFormData>[], direction: 'up' | 'down') {\n    const sortedFields = direction === 'up' ? fields : [...fields].reverse()\n\n    sortedFields.forEach((fieldKey) => {\n      const nextFieldKey = updateIndex(fieldKey.toString(), direction)\n      const nextFieldMeta = formApi.getFieldMeta(nextFieldKey)\n      if (nextFieldMeta) {\n        formApi.setFieldMeta(fieldKey, nextFieldMeta)\n      }\n    })\n  }\n\n  const getEmptyFieldMeta = (): AnyFieldMeta => ({\n    isValidating: false,\n    isTouched: false,\n    isBlurred: false,\n    isDirty: false,\n    isPristine: true,\n    errors: [],\n    errorMap: {},\n  })\n\n  const handleInsertMode = (\n    fields: DeepKeys<TFormData>[],\n    field: DeepKeys<TFormData>,\n    insertIndex: number,\n  ) => {\n    shiftMeta(fields, 'down')\n\n    fields.forEach((fieldKey) => {\n      if (fieldKey.toString().startsWith(getFieldPath(field, insertIndex))) {\n        formApi.setFieldMeta(fieldKey, getEmptyFieldMeta())\n      }\n    })\n  }\n\n  const handleRemoveMode = (fields: DeepKeys<TFormData>[]) => {\n    shiftMeta(fields, 'up')\n  }\n\n  const handleMoveMode = (\n    fields: DeepKeys<TFormData>[],\n    field: DeepKeys<TFormData>,\n    fromIndex: number,\n    toIndex: number,\n  ) => {\n    // Store the original field meta that will be reapplied at the destination index\n    const fromFields = new Map(\n      Object.keys(formApi.fieldInfo)\n        .filter((fieldKey) =>\n          fieldKey.startsWith(getFieldPath(field, fromIndex)),\n        )\n        .map((fieldKey) => [\n          fieldKey as DeepKeys<TFormData>,\n          formApi.getFieldMeta(fieldKey as DeepKeys<TFormData>),\n        ]),\n    )\n\n    shiftMeta(fields, fromIndex < toIndex ? 'up' : 'down')\n\n    // Reapply the stored field meta at the destination index\n    Object.keys(formApi.fieldInfo)\n      .filter((fieldKey) => fieldKey.startsWith(getFieldPath(field, toIndex)))\n      .forEach((fieldKey) => {\n        const fromKey = fieldKey.replace(\n          getFieldPath(field, toIndex),\n          getFieldPath(field, fromIndex),\n        ) as DeepKeys<TFormData>\n\n        const fromMeta = fromFields.get(fromKey)\n        if (fromMeta) {\n          formApi.setFieldMeta(fieldKey as DeepKeys<TFormData>, fromMeta)\n        }\n      })\n  }\n\n  const handleSwapMode = (\n    fields: DeepKeys<TFormData>[],\n    field: DeepKeys<TFormData>,\n    index: number,\n    secondIndex: number,\n  ) => {\n    fields.forEach((fieldKey) => {\n      if (!fieldKey.toString().startsWith(getFieldPath(field, index))) return\n\n      const swappedKey = fieldKey\n        .toString()\n        .replace(\n          getFieldPath(field, index),\n          getFieldPath(field, secondIndex),\n        ) as DeepKeys<TFormData>\n\n      const [meta1, meta2] = [\n        formApi.getFieldMeta(fieldKey),\n        formApi.getFieldMeta(swappedKey),\n      ]\n\n      if (meta1) formApi.setFieldMeta(swappedKey, meta1)\n      if (meta2) formApi.setFieldMeta(fieldKey, meta2)\n    })\n  }\n\n  return { handleArrayFieldMetaShift }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"metaHelper.js","sources":["../../src/metaHelper.ts"],"sourcesContent":["import type {\n  FormApi,\n  FormAsyncValidateOrFn,\n  FormValidateOrFn,\n} from './FormApi'\nimport type { AnyFieldMeta } from './FieldApi'\nimport type { DeepKeys } from './util-types'\n\ntype ArrayFieldMode = 'insert' | 'remove' | 'swap' | 'move'\n\nexport function metaHelper<\n  TFormData,\n  TOnMount extends undefined | FormValidateOrFn<TFormData>,\n  TOnChange extends undefined | FormValidateOrFn<TFormData>,\n  TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,\n  TOnBlur extends undefined | FormValidateOrFn<TFormData>,\n  TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,\n  TOnSubmit extends undefined | FormValidateOrFn<TFormData>,\n  TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,\n  TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,\n  TSubmitMeta,\n>(\n  formApi: FormApi<\n    TFormData,\n    TOnMount,\n    TOnChange,\n    TOnChangeAsync,\n    TOnBlur,\n    TOnBlurAsync,\n    TOnSubmit,\n    TOnSubmitAsync,\n    TOnServer,\n    TSubmitMeta\n  >,\n) {\n  function handleArrayFieldMetaShift(\n    field: DeepKeys<TFormData>,\n    index: number,\n    mode: ArrayFieldMode,\n    secondIndex?: number,\n  ) {\n    const affectedFields = getAffectedFields(field, index, mode, secondIndex)\n\n    const handlers = {\n      insert: () => handleInsertMode(affectedFields, field, index),\n      remove: () => handleRemoveMode(affectedFields),\n      swap: () =>\n        secondIndex !== undefined &&\n        handleSwapMode(affectedFields, field, index, secondIndex),\n      move: () =>\n        secondIndex !== undefined &&\n        handleMoveMode(affectedFields, field, index, secondIndex),\n    }\n\n    handlers[mode]()\n  }\n\n  function getFieldPath(field: DeepKeys<TFormData>, index: number): string {\n    return `${field}[${index}]`\n  }\n\n  function getAffectedFields(\n    field: DeepKeys<TFormData>,\n    index: number,\n    mode: ArrayFieldMode,\n    secondIndex?: number,\n  ): DeepKeys<TFormData>[] {\n    const affectedFieldKeys = [getFieldPath(field, index)]\n\n    if (mode === 'swap') {\n      affectedFieldKeys.push(getFieldPath(field, secondIndex!))\n    } else if (mode === 'move') {\n      const [startIndex, endIndex] = [\n        Math.min(index, secondIndex!),\n        Math.max(index, secondIndex!),\n      ]\n      for (let i = startIndex; i <= endIndex; i++) {\n        affectedFieldKeys.push(getFieldPath(field, i))\n      }\n    } else {\n      const currentValue = formApi.getFieldValue(field)\n      const fieldItems = Array.isArray(currentValue) ? currentValue.length : 0\n      for (let i = index + 1; i < fieldItems; i++) {\n        affectedFieldKeys.push(getFieldPath(field, i))\n      }\n    }\n\n    return Object.keys(formApi.fieldInfo).filter((fieldKey) =>\n      affectedFieldKeys.some((key) => fieldKey.startsWith(key)),\n    ) as DeepKeys<TFormData>[]\n  }\n\n  function updateIndex(\n    fieldKey: string,\n    direction: 'up' | 'down',\n  ): DeepKeys<TFormData> {\n    return fieldKey.replace(/\\[(\\d+)\\]/, (_, num) => {\n      const currIndex = parseInt(num, 10)\n      const newIndex =\n        direction === 'up' ? currIndex + 1 : Math.max(0, currIndex - 1)\n      return `[${newIndex}]`\n    }) as DeepKeys<TFormData>\n  }\n\n  function shiftMeta(fields: DeepKeys<TFormData>[], direction: 'up' | 'down') {\n    const sortedFields = direction === 'up' ? fields : [...fields].reverse()\n\n    sortedFields.forEach((fieldKey) => {\n      const nextFieldKey = updateIndex(fieldKey.toString(), direction)\n      const nextFieldMeta = formApi.getFieldMeta(nextFieldKey)\n      if (nextFieldMeta) {\n        formApi.setFieldMeta(fieldKey, nextFieldMeta)\n      }\n    })\n  }\n\n  const getEmptyFieldMeta = (): AnyFieldMeta => ({\n    isValidating: false,\n    isTouched: false,\n    isBlurred: false,\n    isDirty: false,\n    isPristine: true,\n    errors: [],\n    errorMap: {},\n  })\n\n  const handleInsertMode = (\n    fields: DeepKeys<TFormData>[],\n    field: DeepKeys<TFormData>,\n    insertIndex: number,\n  ) => {\n    shiftMeta(fields, 'down')\n\n    fields.forEach((fieldKey) => {\n      if (fieldKey.toString().startsWith(getFieldPath(field, insertIndex))) {\n        formApi.setFieldMeta(fieldKey, getEmptyFieldMeta())\n      }\n    })\n  }\n\n  const handleRemoveMode = (fields: DeepKeys<TFormData>[]) => {\n    shiftMeta(fields, 'up')\n  }\n\n  const handleMoveMode = (\n    fields: DeepKeys<TFormData>[],\n    field: DeepKeys<TFormData>,\n    fromIndex: number,\n    toIndex: number,\n  ) => {\n    // Store the original field meta that will be reapplied at the destination index\n    const fromFields = new Map(\n      Object.keys(formApi.fieldInfo)\n        .filter((fieldKey) =>\n          fieldKey.startsWith(getFieldPath(field, fromIndex)),\n        )\n        .map((fieldKey) => [\n          fieldKey as DeepKeys<TFormData>,\n          formApi.getFieldMeta(fieldKey as DeepKeys<TFormData>),\n        ]),\n    )\n\n    shiftMeta(fields, fromIndex < toIndex ? 'up' : 'down')\n\n    // Reapply the stored field meta at the destination index\n    Object.keys(formApi.fieldInfo)\n      .filter((fieldKey) => fieldKey.startsWith(getFieldPath(field, toIndex)))\n      .forEach((fieldKey) => {\n        const fromKey = fieldKey.replace(\n          getFieldPath(field, toIndex),\n          getFieldPath(field, fromIndex),\n        ) as DeepKeys<TFormData>\n\n        const fromMeta = fromFields.get(fromKey)\n        if (fromMeta) {\n          formApi.setFieldMeta(fieldKey as DeepKeys<TFormData>, fromMeta)\n        }\n      })\n  }\n\n  const handleSwapMode = (\n    fields: DeepKeys<TFormData>[],\n    field: DeepKeys<TFormData>,\n    index: number,\n    secondIndex: number,\n  ) => {\n    fields.forEach((fieldKey) => {\n      if (!fieldKey.toString().startsWith(getFieldPath(field, index))) return\n\n      const swappedKey = fieldKey\n        .toString()\n        .replace(\n          getFieldPath(field, index),\n          getFieldPath(field, secondIndex),\n        ) as DeepKeys<TFormData>\n\n      const [meta1, meta2] = [\n        formApi.getFieldMeta(fieldKey),\n        formApi.getFieldMeta(swappedKey),\n      ]\n\n      if (meta1) formApi.setFieldMeta(swappedKey, meta1)\n      if (meta2) formApi.setFieldMeta(fieldKey, meta2)\n    })\n  }\n\n  return { handleArrayFieldMetaShift }\n}\n"],"names":[],"mappings":"AAUO,SAAS,WAYd,SAYA;AACA,WAAS,0BACP,OACA,OACA,MACA,aACA;AACA,UAAM,iBAAiB,kBAAkB,OAAO,OAAO,MAAM,WAAW;AAExE,UAAM,WAAW;AAAA,MACf,QAAQ,MAAM,iBAAiB,gBAAgB,OAAO,KAAK;AAAA,MAC3D,QAAQ,MAAM,iBAAiB,cAAc;AAAA,MAC7C,MAAM,MACJ,gBAAgB,UAChB,eAAe,gBAAgB,OAAO,OAAO,WAAW;AAAA,MAC1D,MAAM,MACJ,gBAAgB,UAChB,eAAe,gBAAgB,OAAO,OAAO,WAAW;AAAA,IAC5D;AAEA,aAAS,IAAI,EAAE;AAAA,EAAA;AAGR,WAAA,aAAa,OAA4B,OAAuB;AAChE,WAAA,GAAG,KAAK,IAAI,KAAK;AAAA,EAAA;AAG1B,WAAS,kBACP,OACA,OACA,MACA,aACuB;AACvB,UAAM,oBAAoB,CAAC,aAAa,OAAO,KAAK,CAAC;AAErD,QAAI,SAAS,QAAQ;AACnB,wBAAkB,KAAK,aAAa,OAAO,WAAY,CAAC;AAAA,IAAA,WAC/C,SAAS,QAAQ;AACpB,YAAA,CAAC,YAAY,QAAQ,IAAI;AAAA,QAC7B,KAAK,IAAI,OAAO,WAAY;AAAA,QAC5B,KAAK,IAAI,OAAO,WAAY;AAAA,MAC9B;AACA,eAAS,IAAI,YAAY,KAAK,UAAU,KAAK;AAC3C,0BAAkB,KAAK,aAAa,OAAO,CAAC,CAAC;AAAA,MAAA;AAAA,IAC/C,OACK;AACC,YAAA,eAAe,QAAQ,cAAc,KAAK;AAChD,YAAM,aAAa,MAAM,QAAQ,YAAY,IAAI,aAAa,SAAS;AACvE,eAAS,IAAI,QAAQ,GAAG,IAAI,YAAY,KAAK;AAC3C,0BAAkB,KAAK,aAAa,OAAO,CAAC,CAAC;AAAA,MAAA;AAAA,IAC/C;AAGF,WAAO,OAAO,KAAK,QAAQ,SAAS,EAAE;AAAA,MAAO,CAAC,aAC5C,kBAAkB,KAAK,CAAC,QAAQ,SAAS,WAAW,GAAG,CAAC;AAAA,IAC1D;AAAA,EAAA;AAGO,WAAA,YACP,UACA,WACqB;AACrB,WAAO,SAAS,QAAQ,aAAa,CAAC,GAAG,QAAQ;AACzC,YAAA,YAAY,SAAS,KAAK,EAAE;AAC5B,YAAA,WACJ,cAAc,OAAO,YAAY,IAAI,KAAK,IAAI,GAAG,YAAY,CAAC;AAChE,aAAO,IAAI,QAAQ;AAAA,IAAA,CACpB;AAAA,EAAA;AAGM,WAAA,UAAU,QAA+B,WAA0B;AACpE,UAAA,eAAe,cAAc,OAAO,SAAS,CAAC,GAAG,MAAM,EAAE,QAAQ;AAE1D,iBAAA,QAAQ,CAAC,aAAa;AACjC,YAAM,eAAe,YAAY,SAAS,SAAA,GAAY,SAAS;AACzD,YAAA,gBAAgB,QAAQ,aAAa,YAAY;AACvD,UAAI,eAAe;AACT,gBAAA,aAAa,UAAU,aAAa;AAAA,MAAA;AAAA,IAC9C,CACD;AAAA,EAAA;AAGH,QAAM,oBAAoB,OAAqB;AAAA,IAC7C,cAAc;AAAA,IACd,WAAW;AAAA,IACX,WAAW;AAAA,IACX,SAAS;AAAA,IACT,YAAY;AAAA,IACZ,QAAQ,CAAC;AAAA,IACT,UAAU,CAAA;AAAA,EAAC;AAGb,QAAM,mBAAmB,CACvB,QACA,OACA,gBACG;AACH,cAAU,QAAQ,MAAM;AAEjB,WAAA,QAAQ,CAAC,aAAa;AACvB,UAAA,SAAS,WAAW,WAAW,aAAa,OAAO,WAAW,CAAC,GAAG;AAC5D,gBAAA,aAAa,UAAU,mBAAmB;AAAA,MAAA;AAAA,IACpD,CACD;AAAA,EACH;AAEM,QAAA,mBAAmB,CAAC,WAAkC;AAC1D,cAAU,QAAQ,IAAI;AAAA,EACxB;AAEA,QAAM,iBAAiB,CACrB,QACA,OACA,WACA,YACG;AAEH,UAAM,aAAa,IAAI;AAAA,MACrB,OAAO,KAAK,QAAQ,SAAS,EAC1B;AAAA,QAAO,CAAC,aACP,SAAS,WAAW,aAAa,OAAO,SAAS,CAAC;AAAA,MAAA,EAEnD,IAAI,CAAC,aAAa;AAAA,QACjB;AAAA,QACA,QAAQ,aAAa,QAA+B;AAAA,MACrD,CAAA;AAAA,IACL;AAEA,cAAU,QAAQ,YAAY,UAAU,OAAO,MAAM;AAGrD,WAAO,KAAK,QAAQ,SAAS,EAC1B,OAAO,CAAC,aAAa,SAAS,WAAW,aAAa,OAAO,OAAO,CAAC,CAAC,EACtE,QAAQ,CAAC,aAAa;AACrB,YAAM,UAAU,SAAS;AAAA,QACvB,aAAa,OAAO,OAAO;AAAA,QAC3B,aAAa,OAAO,SAAS;AAAA,MAC/B;AAEM,YAAA,WAAW,WAAW,IAAI,OAAO;AACvC,UAAI,UAAU;AACJ,gBAAA,aAAa,UAAiC,QAAQ;AAAA,MAAA;AAAA,IAChE,CACD;AAAA,EACL;AAEA,QAAM,iBAAiB,CACrB,QACA,OACA,OACA,gBACG;AACI,WAAA,QAAQ,CAAC,aAAa;AACvB,UAAA,CAAC,SAAS,WAAW,WAAW,aAAa,OAAO,KAAK,CAAC,EAAG;AAE3D,YAAA,aAAa,SAChB,SAAA,EACA;AAAA,QACC,aAAa,OAAO,KAAK;AAAA,QACzB,aAAa,OAAO,WAAW;AAAA,MACjC;AAEI,YAAA,CAAC,OAAO,KAAK,IAAI;AAAA,QACrB,QAAQ,aAAa,QAAQ;AAAA,QAC7B,QAAQ,aAAa,UAAU;AAAA,MACjC;AAEA,UAAI,MAAO,SAAQ,aAAa,YAAY,KAAK;AACjD,UAAI,MAAO,SAAQ,aAAa,UAAU,KAAK;AAAA,IAAA,CAChD;AAAA,EACH;AAEA,SAAO,EAAE,0BAA0B;AACrC;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/form-core",
-  "version": "0.44.1",
+  "version": "0.45.1",
   "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<
@@ -685,6 +715,20 @@ export class FormApi<
    */
   prevTransformArray: unknown[] = []
 
+  /**
+   * @private map of errors originated from form level validators
+   */
+  prevFieldsErrorMap: FormErrorMapFromValidator<
+    TFormData,
+    TOnMount,
+    TOnChange,
+    TOnChangeAsync,
+    TOnBlur,
+    TOnBlurAsync,
+    TOnSubmit,
+    TOnSubmitAsync
+  > = {}
+
   /**
    * Constructs a new `FormApi` instance with the given form options.
    */
@@ -698,7 +742,8 @@ export class FormApi<
       TOnBlurAsync,
       TOnSubmit,
       TOnSubmitAsync,
-      TOnServer
+      TOnServer,
+      TSubmitMeta
     >,
   ) {
     this.baseStore = new Store(
@@ -868,7 +913,7 @@ export class FormApi<
             >
           >((prev, curr) => {
             if (curr === undefined) return prev
-            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+
             if (curr && isGlobalFormValidationError(curr)) {
               prev.push(curr.form as never)
               return prev
@@ -958,6 +1003,8 @@ export class FormApi<
       },
     })
 
+    this.handleSubmit = this.handleSubmit.bind(this)
+
     this.update(opts || {})
   }
 
@@ -1013,7 +1060,8 @@ export class FormApi<
       TOnBlurAsync,
       TOnSubmit,
       TOnSubmitAsync,
-      TOnServer
+      TOnServer,
+      TSubmitMeta
     >,
   ) => {
     if (!options) return
@@ -1195,7 +1243,7 @@ export class FormApi<
     const validates = getSyncValidatorArray(cause, this.options)
     let hasErrored = false as boolean
 
-    const fieldsErrorMap: FormErrorMapFromValidator<
+    const newFieldsErrorMap: FormErrorMapFromValidator<
       TFormData,
       TOnMount,
       TOnChange,
@@ -1227,12 +1275,12 @@ export class FormApi<
         if (fieldErrors) {
           for (const [field, fieldError] of Object.entries(fieldErrors)) {
             const oldErrorMap =
-              fieldsErrorMap[field as DeepKeys<TFormData>] || {}
+              newFieldsErrorMap[field as DeepKeys<TFormData>] || {}
             const newErrorMap = {
               ...oldErrorMap,
               [errorMapKey]: fieldError,
             }
-            fieldsErrorMap[field as DeepKeys<TFormData>] = newErrorMap
+            newFieldsErrorMap[field as DeepKeys<TFormData>] = newErrorMap
 
             const fieldMeta = this.getFieldMeta(field as DeepKeys<TFormData>)
             if (fieldMeta && fieldMeta.errorMap[errorMapKey] !== fieldError) {
@@ -1247,6 +1295,24 @@ export class FormApi<
           }
         }
 
+        for (const field of Object.keys(this.prevFieldsErrorMap) as Array<
+          DeepKeys<TFormData>
+        >) {
+          const fieldMeta = this.getFieldMeta(field)
+          if (
+            fieldMeta?.errorMap[errorMapKey] &&
+            !newFieldsErrorMap[field]?.[errorMapKey]
+          ) {
+            this.setFieldMeta(field, (prev) => ({
+              ...prev,
+              errorMap: {
+                ...prev.errorMap,
+                [errorMapKey]: undefined,
+              },
+            }))
+          }
+        }
+
         if (this.state.errorMap[errorMapKey] !== formError) {
           this.baseStore.setState((prev) => ({
             ...prev,
@@ -1261,28 +1327,30 @@ export class FormApi<
           hasErrored = true
         }
       }
+
+      /**
+       *  when we have an error for onSubmit in the state, we want
+       *  to clear the error as soon as the user enters a valid value in the field
+       */
+      const submitErrKey = getErrorMapKey('submit')
+      if (
+        this.state.errorMap[submitErrKey] &&
+        cause !== 'submit' &&
+        !hasErrored
+      ) {
+        this.baseStore.setState((prev) => ({
+          ...prev,
+          errorMap: {
+            ...prev.errorMap,
+            [submitErrKey]: undefined,
+          },
+        }))
+      }
     })
 
-    /**
-     *  when we have an error for onSubmit in the state, we want
-     *  to clear the error as soon as the user enters a valid value in the field
-     */
-    const submitErrKey = getErrorMapKey('submit')
-    if (
-      this.state.errorMap[submitErrKey] &&
-      cause !== 'submit' &&
-      !hasErrored
-    ) {
-      this.baseStore.setState((prev) => ({
-        ...prev,
-        errorMap: {
-          ...prev.errorMap,
-          [submitErrKey]: undefined,
-        },
-      }))
-    }
+    this.prevFieldsErrorMap = newFieldsErrorMap
 
-    return { hasErrored, fieldsErrorMap }
+    return { hasErrored, fieldsErrorMap: newFieldsErrorMap }
   }
 
   /**
@@ -1319,7 +1387,6 @@ export class FormApi<
       | undefined
 
     for (const validateObj of validates) {
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
       if (!validateObj.validate) continue
       const key = getErrorMapKey(validateObj.cause)
       const fieldValidatorMeta = this.state.validationMetaMap[key]
@@ -1482,7 +1549,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 +1605,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(