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

useField.tsx

454 lines13.2 KB

1import React, { useMemo, useState } from 'react'
2import { useStore } from '@tanstack/react-store'
3import { FieldApi, functionalUpdate } from '@tanstack/form-core'
4import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'
5import type {
6 DeepKeys,
7 DeepValue,
8 FieldAsyncValidateOrFn,
9 FieldValidateOrFn,
10 FormAsyncValidateOrFn,
11 FormValidateOrFn,
12} from '@tanstack/form-core'
13import type { FunctionComponent, ReactNode } from 'react'
14import type { UseFieldOptions } from './types'
15​
16interface ReactFieldApi<
17 TParentData,
18 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
19 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
20 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
21 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
22 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
23 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
24 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
25 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
26 TPatentSubmitMeta,
27> {
28 /**
29 * A pre-bound and type-safe sub-field component using this field as a root.
30 */
31 Field: FieldComponent<
32 TParentData,
33 TFormOnMount,
34 TFormOnChange,
35 TFormOnChangeAsync,
36 TFormOnBlur,
37 TFormOnBlurAsync,
38 TFormOnSubmit,
39 TFormOnSubmitAsync,
40 TFormOnServer,
41 TPatentSubmitMeta
42 >
44​
45/**
46 * A type representing a hook for using a field in a form with the given form data type.
47 *
48 * A function that takes an optional object with a `name` property and field options, and returns a `FieldApi` instance for the specified field.
49 */
50export type UseField<
51 TParentData,
52 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
53 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
54 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
55 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
56 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
57 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
58 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
59 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
60 TPatentSubmitMeta,
61> = <
62 TName extends DeepKeys<TParentData>,
63 TData extends DeepValue<TParentData, TName>,
64 TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
65 TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
66 TOnChangeAsync extends
67 | undefined
68 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
69 TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
70 TOnBlurAsync extends
71 | undefined
72 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
73 TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
74 TOnSubmitAsync extends
75 | undefined
76 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
77>(
78 opts: Omit<
79 UseFieldOptions<
80 TParentData,
81 TName,
82 TData,
83 TOnMount,
84 TOnChange,
85 TOnChangeAsync,
86 TOnBlur,
87 TOnBlurAsync,
88 TOnSubmit,
89 TOnSubmitAsync,
90 TFormOnMount,
91 TFormOnChange,
92 TFormOnChangeAsync,
93 TFormOnBlur,
94 TFormOnBlurAsync,
95 TFormOnSubmit,
96 TFormOnSubmitAsync,
97 TFormOnServer,
98 TPatentSubmitMeta
99 >,
100 'form'
101 >,
102) => FieldApi<
103 TParentData,
104 TName,
105 TData,
106 TOnMount,
107 TOnChange,
108 TOnChangeAsync,
109 TOnBlur,
110 TOnBlurAsync,
111 TOnSubmit,
112 TOnSubmitAsync,
113 TFormOnMount,
114 TFormOnChange,
115 TFormOnChangeAsync,
116 TFormOnBlur,
117 TFormOnBlurAsync,
118 TFormOnSubmit,
119 TFormOnSubmitAsync,
120 TFormOnServer,
121 TPatentSubmitMeta
123​
124/**
125 * A hook for managing a field in a form.
126 * @param opts An object with field options.
127 *
128 * @returns The `FieldApi` instance for the specified field.
129 */
130export function useField<
131 TParentData,
132 TName extends DeepKeys<TParentData>,
133 TData extends DeepValue<TParentData, TName>,
134 TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
135 TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
136 TOnChangeAsync extends
137 | undefined
138 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
139 TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
140 TOnBlurAsync extends
141 | undefined
142 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
143 TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
144 TOnSubmitAsync extends
145 | undefined
146 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
147 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
148 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
149 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
150 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
151 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
152 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
153 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
154 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
155 TPatentSubmitMeta,
156>(
157 opts: UseFieldOptions<
158 TParentData,
159 TName,
160 TData,
161 TOnMount,
162 TOnChange,
163 TOnChangeAsync,
164 TOnBlur,
165 TOnBlurAsync,
166 TOnSubmit,
167 TOnSubmitAsync,
168 TFormOnMount,
169 TFormOnChange,
170 TFormOnChangeAsync,
171 TFormOnBlur,
172 TFormOnBlurAsync,
173 TFormOnSubmit,
174 TFormOnSubmitAsync,
175 TFormOnServer,
176 TPatentSubmitMeta
177 >,
178) {
179 const [fieldApi] = useState(() => {
180 const api = new FieldApi({
181 ...opts,
182 form: opts.form,
183 name: opts.name,
184 })
185​
186 const extendedApi: typeof api &
187 ReactFieldApi<
188 TParentData,
189 TFormOnMount,
190 TFormOnChange,
191 TFormOnChangeAsync,
192 TFormOnBlur,
193 TFormOnBlurAsync,
194 TFormOnSubmit,
195 TFormOnSubmitAsync,
196 TFormOnServer,
197 TPatentSubmitMeta
198 > = api as never
199​
200 extendedApi.Field = Field as never
201​
202 return extendedApi
203 })
204​
205 useIsomorphicLayoutEffect(fieldApi.mount, [fieldApi])
206​
207 /**
208 * fieldApi.update should not have any side effects. Think of it like a `useRef`
209 * that we need to keep updated every render with the most up-to-date information.
210 */
211 useIsomorphicLayoutEffect(() => {
212 fieldApi.update(opts)
213 })
214​
215 useStore(
216 fieldApi.store,
217 opts.mode === 'array'
218 ? (state) => {
219 return [state.meta, Object.keys(state.value ?? []).length]
220 }
221 : undefined,
222 )
223​
224 return fieldApi
226​
227/**
228 * @param children A render function that takes a field API instance and returns a React element.
229 */
230type FieldComponentProps<
231 TParentData,
232 TName extends DeepKeys<TParentData>,
233 TData extends DeepValue<TParentData, TName>,
234 TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
235 TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
236 TOnChangeAsync extends
237 | undefined
238 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
239 TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
240 TOnBlurAsync extends
241 | undefined
242 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
243 TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
244 TOnSubmitAsync extends
245 | undefined
246 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
247 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
248 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
249 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
250 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
251 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
252 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
253 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
254 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
255 TPatentSubmitMeta,
256 ExtendedApi = {},
257> = {
258 children: (
259 fieldApi: FieldApi<
260 TParentData,
261 TName,
262 TData,
263 TOnMount,
264 TOnChange,
265 TOnChangeAsync,
266 TOnBlur,
267 TOnBlurAsync,
268 TOnSubmit,
269 TOnSubmitAsync,
270 TFormOnMount,
271 TFormOnChange,
272 TFormOnChangeAsync,
273 TFormOnBlur,
274 TFormOnBlurAsync,
275 TFormOnSubmit,
276 TFormOnSubmitAsync,
277 TFormOnServer,
278 TPatentSubmitMeta
279 > &
280 ExtendedApi,
281 ) => ReactNode
282} & UseFieldOptions<
283 TParentData,
284 TName,
285 TData,
286 TOnMount,
287 TOnChange,
288 TOnChangeAsync,
289 TOnBlur,
290 TOnBlurAsync,
291 TOnSubmit,
292 TOnSubmitAsync,
293 TFormOnMount,
294 TFormOnChange,
295 TFormOnChangeAsync,
296 TFormOnBlur,
297 TFormOnBlurAsync,
298 TFormOnSubmit,
299 TFormOnSubmitAsync,
300 TFormOnServer,
301 TPatentSubmitMeta
303​
304/**
305 * A type alias representing a field component for a specific form data type.
306 */
307export type FieldComponent<
308 TParentData,
309 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
310 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
311 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
312 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
313 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
314 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
315 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
316 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
317 TPatentSubmitMeta,
318 ExtendedApi = {},
319> = <
320 const TName extends DeepKeys<TParentData>,
321 TData extends DeepValue<TParentData, TName>,
322 TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
323 TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
324 TOnChangeAsync extends
325 | undefined
326 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
327 TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
328 TOnBlurAsync extends
329 | undefined
330 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
331 TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
332 TOnSubmitAsync extends
333 | undefined
334 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
335>({
336 children,
337 ...fieldOptions
338}: Omit<
339 FieldComponentProps<
340 TParentData,
341 TName,
342 TData,
343 TOnMount,
344 TOnChange,
345 TOnChangeAsync,
346 TOnBlur,
347 TOnBlurAsync,
348 TOnSubmit,
349 TOnSubmitAsync,
350 TFormOnMount,
351 TFormOnChange,
352 TFormOnChangeAsync,
353 TFormOnBlur,
354 TFormOnBlurAsync,
355 TFormOnSubmit,
356 TFormOnSubmitAsync,
357 TFormOnServer,
358 TPatentSubmitMeta,
359 ExtendedApi
360 >,
361 'form'
362>) => ReactNode
363​
364/**
365 * A function component that takes field options and a render function as children and returns a React component.
366 *
367 * The `Field` component uses the `useField` hook internally to manage the field instance.
368 */
369export const Field = (<
370 TParentData,
371 TName extends DeepKeys<TParentData>,
372 TData extends DeepValue<TParentData, TName>,
373 TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
374 TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
375 TOnChangeAsync extends
376 | undefined
377 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
378 TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
379 TOnBlurAsync extends
380 | undefined
381 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
382 TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
383 TOnSubmitAsync extends
384 | undefined
385 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
386 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
387 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
388 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
389 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
390 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
391 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
392 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
393 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
394 TPatentSubmitMeta,
395>({
396 children,
397 ...fieldOptions
398}: FieldComponentProps<
399 TParentData,
400 TName,
401 TData,
402 TOnMount,
403 TOnChange,
404 TOnChangeAsync,
405 TOnBlur,
406 TOnBlurAsync,
407 TOnSubmit,
408 TOnSubmitAsync,
409 TFormOnMount,
410 TFormOnChange,
411 TFormOnChangeAsync,
412 TFormOnBlur,
413 TFormOnBlurAsync,
414 TFormOnSubmit,
415 TFormOnSubmitAsync,
416 TFormOnServer,
417 TPatentSubmitMeta
418>): ReactNode => {
419 const fieldApi = useField(fieldOptions as any)
420​
421 const jsxToDisplay = useMemo(
422 () => functionalUpdate(children, fieldApi as any),
423 /**
424 * The reason this exists is to fix an issue with the React Compiler.
425 * Namely, functionalUpdate is memoized where it checks for `fieldApi`, which is a static type.
426 * This means that when `state.value` changes, it does not trigger a re-render. The useMemo explicitly fixes this problem
427 */
428 // eslint-disable-next-line react-hooks/exhaustive-deps
429 [children, fieldApi, fieldApi.state.value, fieldApi.state.meta],
430 )
431 return (<>{jsxToDisplay}</>) as never
432}) satisfies FunctionComponent<
433 FieldComponentProps<
434 any,
435 any,
436 any,
437 any,
438 any,
439 any,
440 any,
441 any,
442 any,
443 any,
444 any,
445 any,
446 any,
447 any,
448 any,
449 any,
450 any,
451 any,
452 any
453 >