Skip to content
Source
Sign inSign up
TanStack/form
Open History to see the last commit

FieldApi.public.ts

249 lines6.9 KB

1import type { TryGetArrayElementType } from '../deep-keys.public'
2import type { FieldUpdateOptions, Updater } from '../types.public'
3import type { FormApi } from '../FormApi/FormApi.public'
4import type {
5 ErrorVisibility,
6 FieldValidators,
7 FormErrorTypes,
8 ToFieldError,
9 FieldErrors as ValidationFieldErrors,
10} from '../validation.public'
11import type { FieldListeners } from '../listeners.public'
12import type { ReadonlyAtom } from '@tanstack/store'
13​
14export interface BaseFieldMeta {
15 isTouched: boolean
16 isDirty: boolean
17 isBlurred: boolean
18 isValidating: boolean
20​
21export interface SubfieldsMeta {
22 isEveryValid: boolean
23 isAnyInvalid: boolean
24 isEveryPristine: boolean
25 isSomeDirty: boolean
26 isSomeTouched: boolean
27 isSomeValidating: boolean
29​
30export interface OriginalFieldMeta<in out TFieldError> {
31 errors: ValidationFieldErrors<TFieldError>
32 isValid: boolean
33 isInvalid: boolean
35​
36export type AnyFieldMeta = FieldMeta<any>
37​
38export interface FieldMeta<in out TFieldError> extends BaseFieldMeta {
39 isPristine: boolean
40 isDefaultValue: boolean
41 isSelfTouched: boolean
42 isSelfDirty: boolean
43 isInvalid: boolean
44 isSelfValid: boolean
45 isSelfValidating: boolean
46 isValid: boolean
47 subfields: SubfieldsMeta
48 errors: ValidationFieldErrors<TFieldError>
49 original: OriginalFieldMeta<TFieldError>
51​
52export interface FieldState<out TFieldValue, in out TFieldError> {
53 value: TFieldValue
54 meta: FieldMeta<TFieldError>
56​
57/**
58 * A field API whose field name, value, error, and owning form types are erased.
59 *
60 * Use it for reusable helpers that only need members shared by every field,
61 * such as a generic error display. Because value and update types are erased,
62 * prefer `FieldWithValue<TFieldValue>` when a helper reads or changes a field
63 * value.
64 *
65 * @example
66 * ```ts
67 * function getFieldErrorText(field: AnyFieldApi) {
68 * if (field.meta.isValid) return ''
69 *
70 * return field.errors.map((error) => error.message).join(', ')
71 * }
72 * ```
73 */
74export type AnyFieldApi = FieldApi<any, any, any, any, any>
75​
76type FieldArrayElement<TFieldValue> = TryGetArrayElementType<TFieldValue>
77​
78type FieldArrayPredicate<in out TFieldValue> = (
79 value: FieldArrayElement<TFieldValue>,
80 index: number,
81 array: TFieldValue,
82) => boolean
83​
84type FieldPushValueFn<in out TFieldValue> = (
85 value: FieldArrayElement<TFieldValue>,
86 options?: FieldUpdateOptions,
87) => void
88​
89type FieldInsertValueFn<in out TFieldValue> = (
90 index: number,
91 value: FieldArrayElement<TFieldValue>,
92 options?: FieldUpdateOptions,
93) => void
94​
95type FieldClearValuesFn = (options?: FieldUpdateOptions) => void
96​
97type FieldReplaceValueFn<in out TFieldValue> = (
98 index: number,
99 value: FieldArrayElement<TFieldValue>,
100 options?: FieldUpdateOptions,
101) => void
102​
103type FieldRemoveValueFn = (index: number, options?: FieldUpdateOptions) => void
104​
105type FieldMoveValueFn = (
106 fromIndex: number,
107 toIndex: number,
108 options?: FieldUpdateOptions,
109) => void
110​
111type FieldFilterValuesFn<in out TFieldValue> = (
112 predicate: FieldArrayPredicate<TFieldValue>,
113 options?: FieldUpdateOptions & { thisArg?: any },
114) => void
115​
116type FieldHandleChangeFn<in out TFieldValue> = (
117 value: Updater<TFieldValue>,
118 options?: FieldUpdateOptions,
119) => void
120​
121type FieldVoidFn = () => void
122​
123export interface FieldApi<
124 out TFieldName,
125 in out TFieldValue,
126 in out TFieldError,
127 in out TFormData,
128 in out TFormErrorTypes extends FormErrorTypes,
129> {
130 /**
131 * The form that owns this field.
132 */
133 form: FormApi<TFormData, TFormErrorTypes>
134​
135 /**
136 * The name of the field.
137 */
138 get name(): TFieldName
139​
140 /**
141 * Swap two elements in this field's array.
142 * If this field is not an array, this method will be ignored.
143 * @param indexA - The index of the first element to swap
144 * @param indexB - The index of the second element to swap
145 */
146 swapValues: (indexA: number, indexB: number) => void
147​
148 /**
149 * Move an element in this field's array from one index to another.
150 * If this field is not an array, this method will be ignored.
151 * @param fromIndex - The current index of the element to move
152 * @param toIndex - The index to move the element to
153 * @param options - Optional update options
154 */
155 moveValue: FieldMoveValueFn
156​
157 /**
158 * Push a new value into this field's array.
159 * If this field is not an array, this method will be ignored.
160 * @param value - The value to push into the array
161 * @param options - Optional update options
162 */
163 pushValue: FieldPushValueFn<TFieldValue>
164​
165 /**
166 * Insert a new value into this field's array at the specified index.
167 * If this field is not an array, this method will be ignored.
168 * @param index - The index at which to insert the value
169 * @param value - The value to insert
170 * @param options - Optional update options
171 */
172 insertValue: FieldInsertValueFn<TFieldValue>
173​
174 /**
175 * Clear all values from this field's array.
176 * If this field is not an array, this method will be ignored.
177 * @param options - Optional update options
178 */
179 clearValues: FieldClearValuesFn
180​
181 /**
182 * Replace the value at the specified index in this field's array.
183 * If this field is not an array, this method will be ignored.
184 * @param index - The index of the value to replace
185 * @param value - The new value
186 * @param options - Optional update options
187 */
188 replaceValue: FieldReplaceValueFn<TFieldValue>
189​
190 /**
191 * Remove a value from this field's array at the specified index.
192 * If this field is not an array, this method will be ignored.
193 * @param index - The index of the value to remove
194 * @param options - Optional update options
195 */
196 removeValue: FieldRemoveValueFn
197​
198 /**
199 * Filter the values in this field's array using a predicate function.
200 * If this field is not an array, this method will be ignored.
201 * @param predicate - The predicate function to filter values. Returns true to keep the value, false to remove it.
202 * @param options - Optional update options including a custom `thisArg` for the predicate
203 */
204 filterValues: FieldFilterValuesFn<TFieldValue>
205​
206 atom: ReadonlyAtom<FieldState<TFieldValue, TFieldError>>
207​
208 value: TFieldValue
209​
210 meta: FieldMeta<TFieldError>
211​
212 errors: ValidationFieldErrors<TFieldError>
213​
214 handleChange: FieldHandleChangeFn<TFieldValue>
215​
216 handleBlur: FieldVoidFn
217​
218 reset: FieldVoidFn
220​
221export interface FieldApiOptions<
222 in out TFieldData,
223 in out TFieldName,
224 in out TFieldValue,
225 in out TFieldValidators extends FieldValidators<
226 TFieldData,
227 TFieldName,
228 TFieldValue
229 >,
230 in out TGroupFieldError,
231 in out TFormData,
232 in out TFormErrorTypes extends FormErrorTypes,
233> {
234 name: TFieldName
235 errorVisibility?: ErrorVisibility<TFormData, TFormErrorTypes>
236 /**
237 * Route descendant field errors from form and form group validators to this field.
238 */
239 errorBoundary?: boolean
240 validators?: TFieldValidators
241 listeners?: FieldListeners<
242 TFieldData,
243 TFieldName,
244 TFieldValue,
245 ToFieldError<NoInfer<TFieldValidators>, TGroupFieldError, TFormErrorTypes>,
246 TFormData,
247 TFormErrorTypes
248 >