@tanstack/form-core 1.14.2 → 1.15.1

package/src/types.ts

@@ -1,4 +1,6 @@
-import type { DeepKeys } from './util-types'
+import type { AnyFieldMeta, AnyFieldMetaBase } from './FieldApi'
+import type { DeepKeys, DeepKeysOfType, DeepValue } from './util-types'
+import type { Updater } from './utils'
 
 export type ValidationError = unknown
 
@@ -117,3 +119,152 @@ export interface UpdateMetaOptions {
    */
   dontUpdateMeta?: boolean
 }
+
+/**
+ * @private
+ * A list of field manipulation methods that a form-like API must implement.
+ */
+export interface FieldManipulator<TFormData, TSubmitMeta> {
+  /**
+   * Validates all fields using the correct handlers for a given validation cause.
+   */
+  validateAllFields: (cause: ValidationCause) => Promise<unknown[]>
+
+  /**
+   * Validates the children of a specified array in the form starting from a given index until the end using the correct handlers for a given validation type.
+   */
+  validateArrayFieldsStartingFrom: <
+    TField extends DeepKeysOfType<TFormData, any[]>,
+  >(
+    field: TField,
+    index: number,
+    cause: ValidationCause,
+  ) => Promise<unknown[]>
+
+  /**
+   * Validates a specified field in the form using the correct handlers for a given validation type.
+   */
+  validateField: <TField extends DeepKeys<TFormData>>(
+    field: TField,
+    cause: ValidationCause,
+  ) => unknown[] | Promise<unknown[]>
+
+  /**
+   * Handles the form submission, performs validation, and calls the appropriate onSubmit or onSubmitInvalid callbacks.
+   */
+  handleSubmit(): Promise<void>
+  handleSubmit(submitMeta: TSubmitMeta): Promise<void>
+
+  /**
+   * Gets the value of the specified field.
+   */
+  getFieldValue: <TField extends DeepKeys<TFormData>>(
+    field: TField,
+  ) => DeepValue<TFormData, TField>
+
+  /**
+   * Gets the metadata of the specified field.
+   */
+  getFieldMeta: <TField extends DeepKeys<TFormData>>(
+    field: TField,
+  ) => AnyFieldMeta | undefined
+
+  /**
+   * Updates the metadata of the specified field.
+   */
+  setFieldMeta: <TField extends DeepKeys<TFormData>>(
+    field: TField,
+    updater: Updater<AnyFieldMetaBase>,
+  ) => void
+
+  /**
+   * Sets the value of the specified field and optionally updates the touched state.
+   */
+  setFieldValue: <TField extends DeepKeys<TFormData>>(
+    field: TField,
+    updater: Updater<DeepValue<TFormData, TField>>,
+    opts?: UpdateMetaOptions,
+  ) => void
+
+  /**
+   * Delete the specified field. Also deletes all subfields if there are any.
+   */
+  deleteField: <TField extends DeepKeys<TFormData>>(field: TField) => void
+
+  /**
+   * Pushes a value into an array field.
+   */
+  pushFieldValue: <TField extends DeepKeysOfType<TFormData, any[]>>(
+    field: TField,
+    value: DeepValue<TFormData, TField> extends any[]
+      ? DeepValue<TFormData, TField>[number]
+      : never,
+    opts?: UpdateMetaOptions,
+  ) => void
+
+  /**
+   * Insert a value into an array field at the specified index.
+   */
+  insertFieldValue: <TField extends DeepKeysOfType<TFormData, any[]>>(
+    field: TField,
+    index: number,
+    value: DeepValue<TFormData, TField> extends any[]
+      ? DeepValue<TFormData, TField>[number]
+      : never,
+    opts?: UpdateMetaOptions,
+  ) => Promise<void>
+
+  /**
+   * Replaces a value into an array field at the specified index.
+   */
+  replaceFieldValue: <TField extends DeepKeysOfType<TFormData, any[]>>(
+    field: TField,
+    index: number,
+    value: DeepValue<TFormData, TField> extends any[]
+      ? DeepValue<TFormData, TField>[number]
+      : never,
+    opts?: UpdateMetaOptions,
+  ) => Promise<void>
+
+  /**
+   * Removes a value from an array field at the specified index.
+   */
+  removeFieldValue: <TField extends DeepKeysOfType<TFormData, any[]>>(
+    field: TField,
+    index: number,
+    opts?: UpdateMetaOptions,
+  ) => Promise<void>
+
+  /**
+   * Swaps the values at the specified indices within an array field.
+   */
+  swapFieldValues: <TField extends DeepKeysOfType<TFormData, any[]>>(
+    field: TField,
+    index1: number,
+    index2: number,
+    opts?: UpdateMetaOptions,
+  ) => void
+
+  /**
+   * Moves the value at the first specified index to the second specified index within an array field.
+   */
+  moveFieldValues: <TField extends DeepKeysOfType<TFormData, any[]>>(
+    field: TField,
+    index1: number,
+    index2: number,
+    opts?: UpdateMetaOptions,
+  ) => void
+
+  /**
+   * Clear all values within an array field.
+   */
+  clearFieldValues: <TField extends DeepKeysOfType<TFormData, any[]>>(
+    field: TField,
+    opts?: UpdateMetaOptions,
+  ) => void
+
+  /**
+   * Resets the field value and meta to default state
+   */
+  resetField: <TField extends DeepKeys<TFormData>>(field: TField) => void
+}

package/src/util-types.ts

@@ -177,3 +177,19 @@ export type DeepKeysOfType<TData, TValue> = Extract<
   DeepKeysAndValues<TData>,
   AnyDeepKeyAndValue<string, TValue>
 >['key']
+
+/**
+ * Maps the deep keys of TFormData to the shallow keys of TFieldGroupData.
+ *  Since using template strings as keys is impractical, it relies on shallow keys only.
+ */
+export type FieldsMap<TFormData, TFieldGroupData> =
+  TFieldGroupData extends any[]
+    ? never
+    : string extends keyof TFieldGroupData
+      ? never
+      : {
+          [K in keyof TFieldGroupData]: DeepKeysOfType<
+            TFormData,
+            TFieldGroupData[K]
+          >
+        }

package/src/utils.ts

@@ -185,6 +185,25 @@ export function makePathArray(str: string | Array<string | number>) {
   )
 }
 
+/**
+ * @private
+ */
+export function concatenatePaths(path1: string, path2: string): string {
+  if (path1.length === 0) return path2
+  if (path2.length === 0) return path1
+
+  if (path2.startsWith('[')) {
+    return path1 + path2
+  }
+
+  // In cases where parent and child withFieldGroup forms are both nested
+  if (path2.startsWith('.')) {
+    return path1 + path2
+  }
+
+  return `${path1}.${path2}`
+}
+
 /**
  * @private
  */
@@ -460,3 +479,13 @@ export const determineFieldLevelErrorSourceAndValue = ({
 
   return { newErrorValue: undefined, newSource: undefined }
 }
+
+export function createFieldMap<T>(values: Readonly<T>): { [K in keyof T]: K } {
+  const output: { [K in keyof T]: K } = {} as any
+
+  for (const key in values) {
+    output[key] = key
+  }
+
+  return output
+}