import { FieldErrorMapFromValidator, FieldInfo, FieldLikeAPI, FieldLikeApiOptions, FieldLikeMetaBase, FieldLikeOptions, FieldLikeState, ListenerCause, UnwrapFieldAsyncValidateOrFn, UnwrapFieldValidateOrFn, UpdateMetaOptions, ValidationCause, ValidationError, ValidationErrorMap } from './types.js'; import { ReadonlyStore } from '@tanstack/store'; import { DeepKeys, DeepValue, RejectPromiseValidator } from './util-types.js'; import { StandardSchemaV1, TStandardSchemaValidatorValue } from './standardSchemaValidator.js'; import { FormAsyncValidateOrFn, FormValidateOrFn } from './FormApi.js'; import { Updater } from './utils.js'; /** * @private */ export type FieldValidateFn, TData extends DeepValue = DeepValue> = (props: { value: TData; fieldApi: FieldApi; }) => unknown; /** * @private */ export type FieldValidateAsyncFn, TData extends DeepValue = DeepValue> = (options: { value: TData; fieldApi: FieldApi; signal: AbortSignal; }) => unknown | Promise; /** * @private */ export type FieldListenerFn, TData extends DeepValue = DeepValue> = (props: { value: TData; fieldApi: FieldApi; }) => void; /** * @private */ export type FieldValidateOrFn, TData extends DeepValue = DeepValue> = FieldValidateFn | StandardSchemaV1; /** * @private */ export type FieldAsyncValidateOrFn, TData extends DeepValue = DeepValue> = FieldValidateAsyncFn | StandardSchemaV1; export interface FieldValidators, TData extends DeepValue, TOnMount extends undefined | FieldValidateOrFn, TOnChange extends undefined | FieldValidateOrFn, TOnChangeAsync extends undefined | FieldAsyncValidateOrFn, TOnBlur extends undefined | FieldValidateOrFn, TOnBlurAsync extends undefined | FieldAsyncValidateOrFn, TOnSubmit extends undefined | FieldValidateOrFn, TOnSubmitAsync extends undefined | FieldAsyncValidateOrFn, TOnDynamic extends undefined | FieldValidateOrFn, TOnDynamicAsync extends undefined | FieldAsyncValidateOrFn> { /** * An optional function, that runs on the mount event of input. */ onMount?: RejectPromiseValidator; /** * An optional function, that runs on the change event of input. * * @example z.string().min(1) */ onChange?: RejectPromiseValidator; /** * An optional property similar to `onChange` but async validation * * @example z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' }) */ onChangeAsync?: TOnChangeAsync; /** * 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[]; /** * An optional function, that runs on the blur event of input. * * @example z.string().min(1) */ onBlur?: RejectPromiseValidator; /** * An optional property similar to `onBlur` but async validation. * * @example z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' }) */ onBlurAsync?: TOnBlurAsync; /** * 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[]; /** * An optional function, that runs on the submit event of form. * * @example z.string().min(1) */ onSubmit?: RejectPromiseValidator; /** * An optional property similar to `onSubmit` but async validation. * * @example z.string().refine(async (val) => val.length > 3, { message: 'Testing 123' }) */ onSubmitAsync?: TOnSubmitAsync; onDynamic?: RejectPromiseValidator; onDynamicAsync?: TOnDynamicAsync; onDynamicAsyncDebounceMs?: number; } export interface FieldListeners, TData extends DeepValue = DeepValue> { onChange?: FieldListenerFn; onChangeDebounceMs?: number; onBlur?: FieldListenerFn; onBlurDebounceMs?: number; onMount?: FieldListenerFn; onUnmount?: FieldListenerFn; onSubmit?: FieldListenerFn; onGroupSubmit?: FieldListenerFn; } interface FieldExtraOptions, TData extends DeepValue, TOnMount extends undefined | FieldValidateOrFn, TOnChange extends undefined | FieldValidateOrFn, TOnChangeAsync extends undefined | FieldAsyncValidateOrFn, TOnBlur extends undefined | FieldValidateOrFn, TOnBlurAsync extends undefined | FieldAsyncValidateOrFn, TOnSubmit extends undefined | FieldValidateOrFn, TOnSubmitAsync extends undefined | FieldAsyncValidateOrFn, TOnDynamic extends undefined | FieldValidateOrFn, TOnDynamicAsync extends undefined | FieldAsyncValidateOrFn> { /** * A list of validators to pass to the field */ validators?: FieldValidators; /** * A list of listeners which attach to the corresponding events */ listeners?: FieldListeners; } /** * An object type representing the options for a field in a form. */ export interface FieldOptions, TData extends DeepValue, TOnMount extends undefined | FieldValidateOrFn, TOnChange extends undefined | FieldValidateOrFn, TOnChangeAsync extends undefined | FieldAsyncValidateOrFn, TOnBlur extends undefined | FieldValidateOrFn, TOnBlurAsync extends undefined | FieldAsyncValidateOrFn, TOnSubmit extends undefined | FieldValidateOrFn, TOnSubmitAsync extends undefined | FieldAsyncValidateOrFn, TOnDynamic extends undefined | FieldValidateOrFn, TOnDynamicAsync extends undefined | FieldAsyncValidateOrFn> extends FieldExtraOptions, FieldLikeOptions { } export interface FieldApiOptions, in out TData extends DeepValue, in out TOnMount extends undefined | FieldValidateOrFn, in out TOnChange extends undefined | FieldValidateOrFn, in out TOnChangeAsync extends undefined | FieldAsyncValidateOrFn, in out TOnBlur extends undefined | FieldValidateOrFn, in out TOnBlurAsync extends undefined | FieldAsyncValidateOrFn, in out TOnSubmit extends undefined | FieldValidateOrFn, in out TOnSubmitAsync extends undefined | FieldAsyncValidateOrFn, in out TOnDynamic extends undefined | FieldValidateOrFn, in out TOnDynamicAsync extends undefined | FieldAsyncValidateOrFn, in out TFormOnMount extends undefined | FormValidateOrFn, in out TFormOnChange extends undefined | FormValidateOrFn, in out TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn, in out TFormOnBlur extends undefined | FormValidateOrFn, in out TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn, in out TFormOnSubmit extends undefined | FormValidateOrFn, in out TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn, in out TFormOnDynamic extends undefined | FormValidateOrFn, in out TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn, in out TFormOnServer extends undefined | FormAsyncValidateOrFn, in out TParentSubmitMeta> extends FieldLikeApiOptions, FieldExtraOptions { } /** * @public * * A type representing the Field API with all generics set to `any` for convenience. */ export type AnyFieldApi = FieldApi; /** * We cannot use methods and must use arrow functions. Otherwise, our React adapters * will break due to loss of the method when using spread. */ /** * 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 declare class FieldApi, in out TData extends DeepValue, in out TOnMount extends undefined | FieldValidateOrFn, in out TOnChange extends undefined | FieldValidateOrFn, in out TOnChangeAsync extends undefined | FieldAsyncValidateOrFn, in out TOnBlur extends undefined | FieldValidateOrFn, in out TOnBlurAsync extends undefined | FieldAsyncValidateOrFn, in out TOnSubmit extends undefined | FieldValidateOrFn, in out TOnSubmitAsync extends undefined | FieldAsyncValidateOrFn, in out TOnDynamic extends undefined | FieldValidateOrFn, in out TOnDynamicAsync extends undefined | FieldAsyncValidateOrFn, in out TFormOnMount extends undefined | FormValidateOrFn, in out TFormOnChange extends undefined | FormValidateOrFn, in out TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn, in out TFormOnBlur extends undefined | FormValidateOrFn, in out TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn, in out TFormOnSubmit extends undefined | FormValidateOrFn, in out TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn, in out TFormOnDynamic extends undefined | FormValidateOrFn, in out TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn, in out TFormOnServer extends undefined | FormAsyncValidateOrFn, in out TParentSubmitMeta> implements FieldLikeAPI> { /** * A reference to the form API instance. */ form: FieldApiOptions['form']; /** * The field name. */ name: TName; /** * The field options. */ options: FieldApiOptions; /** * The field state store. */ store: ReadonlyStore>; /** * The current field state. */ get state(): FieldLikeState; timeoutIds: { validations: Record | null>; listeners: Record | null>; formListeners: Record | null>; }; /** * Initializes a new `FieldApi` instance. */ constructor(opts: FieldApiOptions); /** * @private */ runValidator & { fieldApi: AnyFieldApi; }, TType extends 'validate' | 'validateAsync'>(props: { validate: TType extends 'validate' ? FieldValidateOrFn : FieldAsyncValidateOrFn; value: TValue; type: TType; }): unknown; /** * Mounts the field instance to the form. * @returns A function to unmount the field instance. */ mount: () => () => void; /** * Updates the field instance with new options. */ update: (opts: FieldApiOptions) => void; /** * Gets the current field value. * @deprecated Use `field.state.value` instead. */ getValue: () => TData; /** * Sets the field value and run the `change` validator. */ setValue: (updater: Updater, options?: UpdateMetaOptions) => void; getMeta: () => import('./types.js').FieldLikeMeta; /** * Sets the field metadata. */ setMeta: (updater: Updater>) => void; /** * Gets the field information object. */ getInfo: () => FieldInfo; /** * Pushes a new value to the field. */ pushValue: (value: TData extends any[] ? TData[number] : never, options?: UpdateMetaOptions) => void; /** * Inserts a value at the specified index, shifting the subsequent values to the right. */ insertValue: (index: number, value: TData extends any[] ? TData[number] : never, options?: UpdateMetaOptions) => void; /** * Replaces a value at the specified index. */ replaceValue: (index: number, value: TData extends any[] ? TData[number] : never, options?: UpdateMetaOptions) => void; /** * Removes a value at the specified index. */ removeValue: (index: number, options?: UpdateMetaOptions) => void; /** * Swaps the values at the specified indices. */ swapValues: (aIndex: number, bIndex: number, options?: UpdateMetaOptions) => void; /** * Moves the value at the first specified index to the second specified index. */ moveValue: (aIndex: number, bIndex: number, options?: UpdateMetaOptions) => void; /** * Clear all values from the array. */ clearValues: (options?: UpdateMetaOptions) => void; /** * @private */ getLinkedFields: (cause: ValidationCause) => AnyFieldApi[]; /** * @private */ validateSync: (cause: ValidationCause, errorFromForm: ValidationErrorMap) => { hasErrored: boolean; }; /** * `@private` * Starts tracking an async validation, incrementing the counter and setting isValidating if needed. */ private startValidation; /** * `@private` * Ends tracking an async validation, decrementing the counter and clearing isValidating if no validations remain. */ private endValidation; /** * @private */ validateAsync: (cause: ValidationCause, formValidationResultPromise: Promise>) => Promise; /** * Validates the field value. */ validate: (cause: ValidationCause, opts?: { skipFormValidation?: boolean; skipGroupValidation?: boolean; }) => ValidationError[] | Promise; /** * Handles the change event. */ handleChange: (updater: Updater) => void; /** * Handles the blur event. */ handleBlur: () => void; /** * Updates the field's errorMap */ setErrorMap: (errorMap: ValidationErrorMap, UnwrapFieldValidateOrFn, UnwrapFieldAsyncValidateOrFn, UnwrapFieldValidateOrFn, UnwrapFieldAsyncValidateOrFn, UnwrapFieldValidateOrFn, UnwrapFieldAsyncValidateOrFn, UnwrapFieldValidateOrFn, UnwrapFieldAsyncValidateOrFn>) => void; /** * Parses the field's value with the given schema and returns * issues (if any). This method does NOT set any internal errors. * @param schema The standard schema to parse this field's value with. */ parseValueWithSchema: (schema: StandardSchemaV1) => import('./standardSchemaValidator.js').StandardSchemaV1Issue[] | undefined; /** * Parses the field's value with the given schema and returns * issues (if any). This method does NOT set any internal errors. * @param schema The standard schema to parse this field's value with. */ parseValueWithSchemaAsync: (schema: StandardSchemaV1) => Promise; private triggerOnBlurListener; /** * @private */ triggerOnChangeListener: () => void; /** * @private */ triggerOnSubmitListener: () => void; } export {};