@tanstack/form-core 0.23.2 → 0.24.0

package/src/FieldApi.ts

@@ -10,6 +10,9 @@ import type {
 import type { AsyncValidator, SyncValidator, Updater } from './utils'
 import type { DeepKeys, DeepValue, NoInfer } from './util-types'
 
+/**
+ * @private
+ */
 export type FieldValidateFn<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -25,6 +28,9 @@ export type FieldValidateFn<
   fieldApi: FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>
 }) => ValidationError
 
+/**
+ * @private
+ */
 export type FieldValidateOrFn<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -63,6 +69,9 @@ export type FieldValidateOrFn<
         TData
       >
 
+/**
+ * @private
+ */
 export type FieldValidateAsyncFn<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -79,6 +88,9 @@ export type FieldValidateAsyncFn<
   signal: AbortSignal
 }) => ValidationError | Promise<ValidationError>
 
+/**
+ * @private
+ */
 export type FieldAsyncValidateOrFn<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -128,6 +140,9 @@ export interface FieldValidators<
     | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > {
+  /**
+   * An optional function that takes a param of `formApi` which is a generic type of `TData` and `TParentData`
+   */
   onMount?: FieldValidateOrFn<
     TParentData,
     TName,
@@ -135,6 +150,12 @@ export interface FieldValidators<
     TFormValidator,
     TData
   >
+  /**
+   * An optional property that takes a `ValidateFn` which is a generic of `TData` and `TParentData`.
+   * If `validatorAdapter` is passed, this may also accept a property from the respective adapter
+   *
+   * @example `z.string().min(1)` if `zodAdapter` is passed
+   */
   onChange?: FieldValidateOrFn<
     TParentData,
     TName,
@@ -142,6 +163,12 @@ export interface FieldValidators<
     TFormValidator,
     TData
   >
+  /**
+   * An optional property similar to `onChange` but async validation. If `validatorAdapter`
+   * is passed, this may also accept a property from the respective adapter
+   *
+   * @example `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed
+   */
   onChangeAsync?: FieldAsyncValidateOrFn<
     TParentData,
     TName,
@@ -149,8 +176,22 @@ export interface FieldValidators<
     TFormValidator,
     TData
   >
+  /**
+   * An optional number to represent how long the `onChangeAsync` should wait before running
+   *
+   * If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
+   */
   onChangeAsyncDebounceMs?: number
+  /**
+   * An optional list of field names that should trigger this field's `onChange` and `onChangeAsync` events when its value changes
+   */
   onChangeListenTo?: DeepKeys<TParentData>[]
+  /**
+   * An optional function, that when run when subscribing to blur event of input.
+   * If `validatorAdapter` is passed, this may also accept a property from the respective adapter
+   *
+   * @example `z.string().min(1)` if `zodAdapter` is passed
+   */
   onBlur?: FieldValidateOrFn<
     TParentData,
     TName,
@@ -158,6 +199,12 @@ export interface FieldValidators<
     TFormValidator,
     TData
   >
+  /**
+   * An optional property similar to `onBlur` but async validation. If `validatorAdapter`
+   * is passed, this may also accept a property from the respective adapter
+   *
+   * @example `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed
+   */
   onBlurAsync?: FieldAsyncValidateOrFn<
     TParentData,
     TName,
@@ -165,8 +212,23 @@ export interface FieldValidators<
     TFormValidator,
     TData
   >
+
+  /**
+   * An optional number to represent how long the `onBlurAsync` should wait before running
+   *
+   * If set to a number larger than 0, will debounce the async validation event by this length of time in milliseconds
+   */
   onBlurAsyncDebounceMs?: number
+  /**
+   * An optional list of field names that should trigger this field's `onBlur` and `onBlurAsync` events when its value changes
+   */
   onBlurListenTo?: DeepKeys<TParentData>[]
+  /**
+   * An optional function, that when run when subscribing to submit event of input.
+   * If `validatorAdapter` is passed, this may also accept a property from the respective adapter
+   *
+   * @example `z.string().min(1)` if `zodAdapter` is passed
+   */
   onSubmit?: FieldValidateOrFn<
     TParentData,
     TName,
@@ -174,6 +236,12 @@ export interface FieldValidators<
     TFormValidator,
     TData
   >
+  /**
+   * An optional property similar to `onSubmit` but async validation. If `validatorAdapter`
+   * is passed, this may also accept a property from the respective adapter
+   *
+   * @example `z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' })` if `zodAdapter` is passed
+   */
   onSubmitAsync?: FieldAsyncValidateOrFn<
     TParentData,
     TName,
@@ -183,6 +251,9 @@ export interface FieldValidators<
   >
 }
 
+/**
+ * An object type representing the options for a field in a form.
+ */
 export interface FieldOptions<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -194,12 +265,29 @@ export interface FieldOptions<
     | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > {
+  /**
+   * The field name. The type will be `DeepKeys<TParentData>` to ensure your name is a deep key of the parent dataset.
+   */
   name: TName
+  /**
+   * An optional default value for the field.
+   */
   defaultValue?: NoInfer<TData>
+  /**
+   * The default time to debounce async validation if there is not a more specific debounce time passed.
+   */
   asyncDebounceMs?: number
+  /**
+   * If `true`, always run async validation, even if there are errors emitted during synchronous validation.
+   */
   asyncAlways?: boolean
-  preserveValue?: boolean
+  /**
+   * A validator provided by an extension, like `yupValidator` from `@tanstack/yup-form-adapter`
+   */
   validatorAdapter?: TFieldValidator
+  /**
+   * A list of validators to pass to the field
+   */
   validators?: FieldValidators<
     TParentData,
     TName,
@@ -207,9 +295,15 @@ export interface FieldOptions<
     TFormValidator,
     TData
   >
+  /**
+   * An optional object with default metadata for the field.
+   */
   defaultMeta?: Partial<FieldMeta>
 }
 
+/**
+ * An object type representing the required options for the FieldApi class.
+ */
 export interface FieldApiOptions<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -230,25 +324,63 @@ export interface FieldApiOptions<
   form: FormApi<TParentData, TFormValidator>
 }
 
+/**
+ * An object type representing the metadata of a field in a form.
+ */
 export type FieldMeta = {
+  /**
+   * A flag indicating whether the field has been touched.
+   */
   isTouched: boolean
+  /**
+   * A flag that is `true` if the field's value has not been modified by the user. Opposite of `isDirty`.
+   */
   isPristine: boolean
+  /**
+   * A flag that is `true` if the field's value has been modified by the user. Opposite of `isPristine`.
+   */
   isDirty: boolean
+  /**
+   * An array of errors related to the touched state of the field.
+   */
   touchedErrors: ValidationError[]
+  /**
+   * An array of errors related to the field value.
+   */
   errors: ValidationError[]
+  /**
+   * A map of errors related to the field value.
+   */
   errorMap: ValidationErrorMap
+  /**
+   * A flag indicating whether the field is currently being validated.
+   */
   isValidating: boolean
 }
 
+/**
+ * An object type representing the state of a field.
+ */
 export type FieldState<TData> = {
+  /**
+   * The current value of the field.
+   */
   value: TData
+  /**
+   * The current metadata of the field.
+   */
   meta: FieldMeta
 }
 
-export type ResolveName<TParentData> = unknown extends TParentData
-  ? string
-  : DeepKeys<TParentData>
-
+/**
+ * A class representing the API for managing a form field.
+ *
+ * Normally, you will not need to create a new `FieldApi` instance directly.
+ * Instead, you will use a framework hook/function like `useField` or `createField`
+ * to create a new instance for you that uses your framework's reactivity model.
+ * However, if you need to create a new instance manually, you can do so by calling
+ * the `new FieldApi` constructor.
+ */
 export class FieldApi<
   TParentData,
   TName extends DeepKeys<TParentData>,
@@ -260,6 +392,9 @@ export class FieldApi<
     | undefined = undefined,
   TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
 > {
+  /**
+   * A reference to the form API instance.
+   */
   form: FieldApiOptions<
     TParentData,
     TName,
@@ -267,7 +402,13 @@ export class FieldApi<
     TFormValidator,
     TData
   >['form']
+  /**
+   * The field name.
+   */
   name!: DeepKeys<TParentData>
+  /**
+   * The field options.
+   */
   options: FieldApiOptions<
     TParentData,
     TName,
@@ -275,10 +416,22 @@ export class FieldApi<
     TFormValidator,
     TData
   > = {} as any
+  /**
+   * The field state store.
+   */
   store!: Store<FieldState<TData>>
+  /**
+   * The current field state.
+   */
   state!: FieldState<TData>
+  /**
+   * @private
+   */
   prevState!: FieldState<TData>
 
+  /**
+   * Initializes a new `FieldApi` instance.
+   */
   constructor(
     opts: FieldApiOptions<
       TParentData,
@@ -335,6 +488,9 @@ export class FieldApi<
     this.options = opts as never
   }
 
+  /**
+   * @private
+   */
   runValidator<
     TValue extends { value: TData; fieldApi: FieldApi<any, any, any, any> },
     TType extends 'validate' | 'validateAsync',
@@ -361,6 +517,9 @@ export class FieldApi<
     return (props.validate as FieldValidateFn<any, any>)(props.value) as never
   }
 
+  /**
+   * Mounts the field instance to the form.
+   */
   mount = () => {
     const info = this.getInfo()
     info.instance = this as never
@@ -401,14 +560,13 @@ export class FieldApi<
     }
 
     return () => {
-      const preserveValue = this.options.preserveValue
       unsubscribe()
-      if (!preserveValue) {
-        this.form.deleteField(this.name)
-      }
     }
   }
 
+  /**
+   * Updates the field instance with new options.
+   */
   update = (
     opts: FieldApiOptions<
       TParentData,
@@ -438,10 +596,16 @@ export class FieldApi<
     this.options = opts as never
   }
 
+  /**
+   * Gets the current field value.
+   */
   getValue = (): TData => {
     return this.form.getFieldValue(this.name) as TData
   }
 
+  /**
+   * Sets the field value and run the `change` validator.
+   */
   setValue = (
     updater: Updater<TData>,
     options?: { touch?: boolean; notify?: boolean },
@@ -450,7 +614,14 @@ export class FieldApi<
     this.validate('change')
   }
 
+  /**
+   * @private
+   */
   _getMeta = () => this.form.getFieldMeta(this.name)
+
+  /**
+   * Gets the current field metadata.
+   */
   getMeta = () =>
     this._getMeta() ??
     ({
@@ -464,37 +635,64 @@ export class FieldApi<
       ...this.options.defaultMeta,
     } as FieldMeta)
 
+  /**
+   * Sets the field metadata.
+   */
   setMeta = (updater: Updater<FieldMeta>) =>
     this.form.setFieldMeta(this.name, updater)
 
+  /**
+   * Gets the field information object.
+   */
   getInfo = () => this.form.getFieldInfo(this.name)
 
+  /**
+   * Pushes a new value to the field.
+   */
   pushValue = (
     value: TData extends any[] ? TData[number] : never,
     opts?: { touch?: boolean },
   ) => this.form.pushFieldValue(this.name, value as any, opts)
 
+  /**
+   * Inserts a value at the specified index, shifting the subsequent values to the right.
+   */
   insertValue = (
     index: number,
     value: TData extends any[] ? TData[number] : never,
     opts?: { touch?: boolean },
   ) => this.form.insertFieldValue(this.name, index, value as any, opts)
 
+  /**
+   * Replaces a value at the specified index.
+   */
   replaceValue = (
     index: number,
     value: TData extends any[] ? TData[number] : never,
     opts?: { touch?: boolean },
   ) => this.form.replaceFieldValue(this.name, index, value as any, opts)
 
+  /**
+   * Removes a value at the specified index.
+   */
   removeValue = (index: number, opts?: { touch: boolean }) =>
     this.form.removeFieldValue(this.name, index, opts)
 
+  /**
+   * Swaps the values at the specified indices.
+   */
   swapValues = (aIndex: number, bIndex: number, opts?: { touch?: boolean }) =>
     this.form.swapFieldValues(this.name, aIndex, bIndex, opts)
 
+  /**
+   * Moves the value at the first specified index to the second specified index.
+   */
   moveValue = (aIndex: number, bIndex: number, opts?: { touch?: boolean }) =>
     this.form.moveFieldValues(this.name, aIndex, bIndex, opts)
 
+  /**
+   * @private
+   */
   getLinkedFields = (cause: ValidationCause) => {
     const fields = Object.values(this.form.fieldInfo) as FieldInfo<
       any,
@@ -520,6 +718,9 @@ export class FieldApi<
     return linkedFields
   }
 
+  /**
+   * @private
+   */
   validateSync = (cause: ValidationCause) => {
     const validates = getSyncValidatorArray(cause, this.options)
 
@@ -597,6 +798,9 @@ export class FieldApi<
     return { hasErrored }
   }
 
+  /**
+   * @private
+   */
   validateAsync = async (cause: ValidationCause) => {
     const validates = getAsyncValidatorArray(cause, this.options)
 
@@ -717,6 +921,9 @@ export class FieldApi<
     return results.filter(Boolean)
   }
 
+  /**
+   * Validates the field value.
+   */
   validate = (
     cause: ValidationCause,
   ): ValidationError[] | Promise<ValidationError[]> => {
@@ -737,10 +944,16 @@ export class FieldApi<
     return this.validateAsync(cause)
   }
 
+  /**
+   * Handles the change event.
+   */
   handleChange = (updater: Updater<TData>) => {
     this.setValue(updater, { touch: true })
   }
 
+  /**
+   * Handles the blur event.
+   */
   handleBlur = () => {
     const prevTouched = this.state.meta.isTouched
     if (!prevTouched) {