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

useField.tsx

781 lines23.1 KB

1'use client'
2​
3import { useMemo, useRef, useState } from 'react'
4import { useStore } from '@tanstack/react-store'
5import { FieldApi, functionalUpdate } from '@tanstack/form-core'
6import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'
7import type {
8 AnyFieldApi,
9 AnyFieldMeta,
10 DeepKeys,
11 DeepValue,
12 FieldAsyncValidateOrFn,
13 FieldValidateOrFn,
14 FieldValidators,
15 FormAsyncValidateOrFn,
16 FormValidateOrFn,
17} from '@tanstack/form-core'
18import type { FunctionComponent, ReactElement, ReactNode } from 'react'
19import type { UseFieldOptions, UseFieldOptionsBound } from './types'
20​
21interface ReactFieldApi<
22 TParentData,
23 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
24 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
25 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
26 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
27 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
28 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
29 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
30 TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
31 TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
32 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
33 TPatentSubmitMeta,
34> {
35 /**
36 * A pre-bound and type-safe sub-field component using this field as a root.
37 */
38 Field: FieldComponent<
39 TParentData,
40 TFormOnMount,
41 TFormOnChange,
42 TFormOnChangeAsync,
43 TFormOnBlur,
44 TFormOnBlurAsync,
45 TFormOnSubmit,
46 TFormOnSubmitAsync,
47 TFormOnDynamic,
48 TFormOnDynamicAsync,
49 TFormOnServer,
50 TPatentSubmitMeta
51 >
53​
54/**
55 * A type representing a hook for using a field in a form with the given form data type.
56 *
57 * A function that takes an optional object with a `name` property and field options, and returns a `FieldApi` instance for the specified field.
58 */
59export type UseField<
60 TParentData,
61 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
62 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
63 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
64 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
65 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
66 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
67 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
68 TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
69 TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
70 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
71 TPatentSubmitMeta,
72> = <
73 TName extends DeepKeys<TParentData>,
74 TData extends DeepValue<TParentData, TName>,
75 TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
76 TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
77 TOnChangeAsync extends
78 | undefined
79 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
80 TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
81 TOnBlurAsync extends
82 | undefined
83 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
84 TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
85 TOnSubmitAsync extends
86 | undefined
87 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
88 TOnDynamic extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
89 TOnDynamicAsync extends
90 | undefined
91 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
92>(
93 opts: UseFieldOptionsBound<
94 TParentData,
95 TName,
96 TData,
97 TOnMount,
98 TOnChange,
99 TOnChangeAsync,
100 TOnBlur,
101 TOnBlurAsync,
102 TOnSubmit,
103 TOnSubmitAsync,
104 TOnDynamic,
105 TOnDynamicAsync
106 >,
107) => FieldApi<
108 TParentData,
109 TName,
110 TData,
111 TOnMount,
112 TOnChange,
113 TOnChangeAsync,
114 TOnBlur,
115 TOnBlurAsync,
116 TOnSubmit,
117 TOnSubmitAsync,
118 TOnDynamic,
119 TOnDynamicAsync,
120 TFormOnMount,
121 TFormOnChange,
122 TFormOnChangeAsync,
123 TFormOnBlur,
124 TFormOnBlurAsync,
125 TFormOnSubmit,
126 TFormOnSubmitAsync,
127 TFormOnDynamic,
128 TFormOnDynamicAsync,
129 TFormOnServer,
130 TPatentSubmitMeta
132​
133/**
134 * A hook for managing a field in a form.
135 * @param opts An object with field options.
136 *
137 * @returns The `FieldApi` instance for the specified field.
138 */
139export function useField<
140 TParentData,
141 TName extends DeepKeys<TParentData>,
142 TData extends DeepValue<TParentData, TName>,
143 TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
144 TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
145 TOnChangeAsync extends
146 | undefined
147 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
148 TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
149 TOnBlurAsync extends
150 | undefined
151 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
152 TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
153 TOnSubmitAsync extends
154 | undefined
155 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
156 TOnDynamic extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
157 TOnDynamicAsync extends
158 | undefined
159 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
160 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
161 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
162 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
163 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
164 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
165 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
166 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
167 TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
168 TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
169 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
170 TPatentSubmitMeta,
171>(
172 opts: UseFieldOptions<
173 TParentData,
174 TName,
175 TData,
176 TOnMount,
177 TOnChange,
178 TOnChangeAsync,
179 TOnBlur,
180 TOnBlurAsync,
181 TOnSubmit,
182 TOnSubmitAsync,
183 TOnDynamic,
184 TOnDynamicAsync,
185 TFormOnMount,
186 TFormOnChange,
187 TFormOnChangeAsync,
188 TFormOnBlur,
189 TFormOnBlurAsync,
190 TFormOnSubmit,
191 TFormOnSubmitAsync,
192 TFormOnDynamic,
193 TFormOnDynamicAsync,
194 TFormOnServer,
195 TPatentSubmitMeta
196 >,
197) {
198 // Keep a snapshot of options so that React Compiler doesn't
199 // wrongly optimize fieldApi.
200 const [prevOptions, setPrevOptions] = useState(() => ({
201 form: opts.form,
202 name: opts.name,
203 }))
204​
205 const [fieldApi, setFieldApi] = useState(() => {
206 return new FieldApi({
207 ...opts,
208 })
209 })
210​
211 // We only want to
212 // update on name changes since those are at risk of becoming stale. The field
213 // state must be up to date for the internal JSX render.
214 // The other options can freely be in `fieldApi.update`
215 if (prevOptions.form !== opts.form || prevOptions.name !== opts.name) {
216 setFieldApi(
217 new FieldApi({
218 ...opts,
219 }),
220 )
221 setPrevOptions({ form: opts.form, name: opts.name })
222 }
223​
224 // For array mode, only track length changes to avoid re-renders when child properties change
225 // See: https://github.com/TanStack/form/issues/1925
226 const reactiveStateValue = useStore(
227 fieldApi.store,
228 (opts.mode === 'array'
229 ? (state) => Object.keys((state.value as unknown) ?? []).length
230 : (state) => state.value) as (
231 state: typeof fieldApi.state,
232 ) => TData | number,
233 )
234 const reactiveMetaIsTouched = useStore(
235 fieldApi.store,
236 (state) => state.meta.isTouched,
237 )
238 const reactiveMetaIsBlurred = useStore(
239 fieldApi.store,
240 (state) => state.meta.isBlurred,
241 )
242 const reactiveMetaIsDirty = useStore(
243 fieldApi.store,
244 (state) => state.meta.isDirty,
245 )
246 const reactiveMetaErrorMap = useStore(
247 fieldApi.store,
248 (state) => state.meta.errorMap,
249 )
250 const reactiveMetaErrorSourceMap = useStore(
251 fieldApi.store,
252 (state) => state.meta.errorSourceMap,
253 )
254 const reactiveMetaIsValidating = useStore(
255 fieldApi.store,
256 (state) => state.meta.isValidating,
257 )
258​
259 // This makes me sad, but if I understand correctly, this is what we have to do for reactivity to work properly with React compiler.
260 const extendedFieldApi = useMemo(() => {
261 const reactiveFieldApi = {
262 ...fieldApi,
263 get state() {
264 return {
265 // For array mode, reactiveStateValue is the length (for reactivity tracking),
266 // so we need to get the actual value from fieldApi
267 value:
268 opts.mode === 'array' ? fieldApi.state.value : reactiveStateValue,
269 get meta() {
270 return {
271 ...fieldApi.state.meta,
272 isTouched: reactiveMetaIsTouched,
273 isBlurred: reactiveMetaIsBlurred,
274 isDirty: reactiveMetaIsDirty,
275 errorMap: reactiveMetaErrorMap,
276 errorSourceMap: reactiveMetaErrorSourceMap,
277 isValidating: reactiveMetaIsValidating,
278 } satisfies AnyFieldMeta
279 },
280 } satisfies AnyFieldApi['state']
281 },
282 }
283​
284 const extendedApi: FieldApi<
285 TParentData,
286 TName,
287 TData,
288 TOnMount,
289 TOnChange,
290 TOnChangeAsync,
291 TOnBlur,
292 TOnBlurAsync,
293 TOnSubmit,
294 TOnSubmitAsync,
295 TOnDynamic,
296 TOnDynamicAsync,
297 TFormOnMount,
298 TFormOnChange,
299 TFormOnChangeAsync,
300 TFormOnBlur,
301 TFormOnBlurAsync,
302 TFormOnSubmit,
303 TFormOnSubmitAsync,
304 TFormOnDynamic,
305 TFormOnDynamicAsync,
306 TFormOnServer,
307 TPatentSubmitMeta
308 > &
309 ReactFieldApi<
310 TParentData,
311 TFormOnMount,
312 TFormOnChange,
313 TFormOnChangeAsync,
314 TFormOnBlur,
315 TFormOnBlurAsync,
316 TFormOnSubmit,
317 TFormOnSubmitAsync,
318 TFormOnDynamic,
319 TFormOnDynamicAsync,
320 TFormOnServer,
321 TPatentSubmitMeta
322 > = reactiveFieldApi as never
323​
324 extendedApi.Field = Field as never
325​
326 return extendedApi
327 }, [
328 fieldApi,
329 opts.mode,
330 reactiveStateValue,
331 reactiveMetaIsTouched,
332 reactiveMetaIsBlurred,
333 reactiveMetaIsDirty,
334 reactiveMetaErrorMap,
335 reactiveMetaErrorSourceMap,
336 reactiveMetaIsValidating,
337 ])
338​
339 useIsomorphicLayoutEffect(fieldApi.mount, [fieldApi])
340​
341 /**
342 * fieldApi.update should not have any side effects. Think of it like a `useRef`
343 * that we need to keep updated every render with the most up-to-date information.
344 */
345 useIsomorphicLayoutEffect(() => {
346 fieldApi.update(opts)
347 })
348​
349 return extendedFieldApi
351​
352/**
353 * @param children A render function that takes a field API instance and returns a React element.
354 */
355interface FieldComponentProps<
356 TParentData,
357 TName extends DeepKeys<TParentData>,
358 TData extends DeepValue<TParentData, TName>,
359 TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
360 TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
361 TOnChangeAsync extends
362 | undefined
363 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
364 TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
365 TOnBlurAsync extends
366 | undefined
367 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
368 TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
369 TOnSubmitAsync extends
370 | undefined
371 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
372 TOnDynamic extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
373 TOnDynamicAsync extends
374 | undefined
375 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
376 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
377 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
378 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
379 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
380 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
381 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
382 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
383 TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
384 TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
385 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
386 TPatentSubmitMeta,
387 ExtendedApi = {},
388> extends UseFieldOptions<
389 TParentData,
390 TName,
391 TData,
392 TOnMount,
393 TOnChange,
394 TOnChangeAsync,
395 TOnBlur,
396 TOnBlurAsync,
397 TOnSubmit,
398 TOnSubmitAsync,
399 TOnDynamic,
400 TOnDynamicAsync,
401 TFormOnMount,
402 TFormOnChange,
403 TFormOnChangeAsync,
404 TFormOnBlur,
405 TFormOnBlurAsync,
406 TFormOnSubmit,
407 TFormOnSubmitAsync,
408 TFormOnDynamic,
409 TFormOnDynamicAsync,
410 TFormOnServer,
411 TPatentSubmitMeta
412> {
413 children: (
414 fieldApi: FieldApi<
415 TParentData,
416 TName,
417 TData,
418 TOnMount,
419 TOnChange,
420 TOnChangeAsync,
421 TOnBlur,
422 TOnBlurAsync,
423 TOnSubmit,
424 TOnSubmitAsync,
425 TOnDynamic,
426 TOnDynamicAsync,
427 TFormOnMount,
428 TFormOnChange,
429 TFormOnChangeAsync,
430 TFormOnBlur,
431 TFormOnBlurAsync,
432 TFormOnSubmit,
433 TFormOnSubmitAsync,
434 TFormOnDynamic,
435 TFormOnDynamicAsync,
436 TFormOnServer,
437 TPatentSubmitMeta
438 > &
439 ExtendedApi,
440 ) => ReactNode
442​
443interface FieldComponentBoundProps<
444 TParentData,
445 TName extends DeepKeys<TParentData>,
446 TData extends DeepValue<TParentData, TName>,
447 TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
448 TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
449 TOnChangeAsync extends
450 | undefined
451 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
452 TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
453 TOnBlurAsync extends
454 | undefined
455 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
456 TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
457 TOnSubmitAsync extends
458 | undefined
459 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
460 TOnDynamic extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
461 TOnDynamicAsync extends
462 | undefined
463 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
464 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
465 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
466 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
467 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
468 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
469 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
470 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
471 TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
472 TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
473 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
474 TPatentSubmitMeta,
475 ExtendedApi = {},
476> extends UseFieldOptionsBound<
477 TParentData,
478 TName,
479 TData,
480 TOnMount,
481 TOnChange,
482 TOnChangeAsync,
483 TOnBlur,
484 TOnBlurAsync,
485 TOnSubmit,
486 TOnSubmitAsync,
487 TOnDynamic,
488 TOnDynamicAsync
489> {
490 children: (
491 fieldApi: FieldApi<
492 TParentData,
493 TName,
494 TData,
495 TOnMount,
496 TOnChange,
497 TOnChangeAsync,
498 TOnBlur,
499 TOnBlurAsync,
500 TOnSubmit,
501 TOnSubmitAsync,
502 TOnDynamic,
503 TOnDynamicAsync,
504 TFormOnMount,
505 TFormOnChange,
506 TFormOnChangeAsync,
507 TFormOnBlur,
508 TFormOnBlurAsync,
509 TFormOnSubmit,
510 TFormOnSubmitAsync,
511 TFormOnDynamic,
512 TFormOnDynamicAsync,
513 TFormOnServer,
514 TPatentSubmitMeta
515 > &
516 ExtendedApi,
517 ) => ReactNode
519​
520/**
521 * A type alias representing a field component for a specific form data type.
522 */
523export type FieldComponent<
524 in out TParentData,
525 in out TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
526 in out TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
527 in out TFormOnChangeAsync extends
528 | undefined
529 | FormAsyncValidateOrFn<TParentData>,
530 in out TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
531 in out TFormOnBlurAsync extends
532 | undefined
533 | FormAsyncValidateOrFn<TParentData>,
534 in out TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
535 in out TFormOnSubmitAsync extends
536 | undefined
537 | FormAsyncValidateOrFn<TParentData>,
538 in out TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
539 in out TFormOnDynamicAsync extends
540 | undefined
541 | FormAsyncValidateOrFn<TParentData>,
542 in out TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
543 in out TPatentSubmitMeta,
544 in out ExtendedApi = {},
545> = <
546 const TName extends DeepKeys<TParentData>,
547 TData extends DeepValue<TParentData, TName>,
548 TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
549 TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
550 TOnChangeAsync extends
551 | undefined
552 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
553 TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
554 TOnBlurAsync extends
555 | undefined
556 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
557 TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
558 TOnSubmitAsync extends
559 | undefined
560 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
561 TOnDynamic extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
562 TOnDynamicAsync extends
563 | undefined
564 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
565>({
566 children,
567 ...fieldOptions
568}: FieldComponentBoundProps<
569 TParentData,
570 TName,
571 TData,
572 TOnMount,
573 TOnChange,
574 TOnChangeAsync,
575 TOnBlur,
576 TOnBlurAsync,
577 TOnSubmit,
578 TOnSubmitAsync,
579 TOnDynamic,
580 TOnDynamicAsync,
581 TFormOnMount,
582 TFormOnChange,
583 TFormOnChangeAsync,
584 TFormOnBlur,
585 TFormOnBlurAsync,
586 TFormOnSubmit,
587 TFormOnSubmitAsync,
588 TFormOnDynamic,
589 TFormOnDynamicAsync,
590 TFormOnServer,
591 TPatentSubmitMeta,
592 ExtendedApi
593>) => ReturnType<FunctionComponent>
594​
595/**
596 * A type alias representing a field component for a form lens data type.
597 */
598export type LensFieldComponent<
599 in out TLensData,
600 in out TParentSubmitMeta,
601 in out ExtendedApi = {},
602> = <
603 const TName extends DeepKeys<TLensData>,
604 TData extends DeepValue<TLensData, TName>,
605 TOnMount extends undefined | FieldValidateOrFn<unknown, string, TData>,
606 TOnChange extends undefined | FieldValidateOrFn<unknown, string, TData>,
607 TOnChangeAsync extends
608 | undefined
609 | FieldAsyncValidateOrFn<unknown, string, TData>,
610 TOnBlur extends undefined | FieldValidateOrFn<unknown, string, TData>,
611 TOnBlurAsync extends
612 | undefined
613 | FieldAsyncValidateOrFn<unknown, string, TData>,
614 TOnSubmit extends undefined | FieldValidateOrFn<unknown, string, TData>,
615 TOnSubmitAsync extends
616 | undefined
617 | FieldAsyncValidateOrFn<unknown, string, TData>,
618 TOnDynamic extends undefined | FieldValidateOrFn<unknown, string, TData>,
619 TOnDynamicAsync extends
620 | undefined
621 | FieldAsyncValidateOrFn<unknown, string, TData>,
622>({
623 children,
624 ...fieldOptions
625}: Omit<
626 FieldComponentBoundProps<
627 unknown,
628 string,
629 TData,
630 TOnMount,
631 TOnChange,
632 TOnChangeAsync,
633 TOnBlur,
634 TOnBlurAsync,
635 TOnSubmit,
636 TOnSubmitAsync,
637 TOnDynamic,
638 TOnDynamicAsync,
639 undefined | FormValidateOrFn<unknown>,
640 undefined | FormValidateOrFn<unknown>,
641 undefined | FormAsyncValidateOrFn<unknown>,
642 undefined | FormValidateOrFn<unknown>,
643 undefined | FormAsyncValidateOrFn<unknown>,
644 undefined | FormValidateOrFn<unknown>,
645 undefined | FormAsyncValidateOrFn<unknown>,
646 undefined | FormValidateOrFn<unknown>,
647 undefined | FormAsyncValidateOrFn<unknown>,
648 undefined | FormAsyncValidateOrFn<unknown>,
649 TParentSubmitMeta,
650 ExtendedApi
651 >,
652 'name' | 'validators'
653> & {
654 name: TName
655 validators?: Omit<
656 FieldValidators<
657 unknown,
658 string,
659 TData,
660 TOnMount,
661 TOnChange,
662 TOnChangeAsync,
663 TOnBlur,
664 TOnBlurAsync,
665 TOnSubmit,
666 TOnSubmitAsync,
667 TOnDynamic,
668 TOnDynamicAsync
669 >,
670 'onChangeListenTo' | 'onBlurListenTo'
671 > & {
672 /**
673 * An optional list of field names that should trigger this field's `onChange` and `onChangeAsync` events when its value changes
674 */
675 onChangeListenTo?: DeepKeys<TLensData>[]
676 /**
677 * An optional list of field names that should trigger this field's `onBlur` and `onBlurAsync` events when its value changes
678 */
679 onBlurListenTo?: DeepKeys<TLensData>[]
680 }
681}) => ReturnType<FunctionComponent>
682​
683/**
684 * A function component that takes field options and a render function as children and returns a React component.
685 *
686 * The `Field` component uses the `useField` hook internally to manage the field instance.
687 */
688export const Field = (<
689 TParentData,
690 TName extends DeepKeys<TParentData>,
691 TData extends DeepValue<TParentData, TName>,
692 TOnMount extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
693 TOnChange extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
694 TOnChangeAsync extends
695 | undefined
696 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
697 TOnBlur extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
698 TOnBlurAsync extends
699 | undefined
700 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
701 TOnSubmit extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
702 TOnSubmitAsync extends
703 | undefined
704 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
705 TOnDynamic extends undefined | FieldValidateOrFn<TParentData, TName, TData>,
706 TOnDynamicAsync extends
707 | undefined
708 | FieldAsyncValidateOrFn<TParentData, TName, TData>,
709 TFormOnMount extends undefined | FormValidateOrFn<TParentData>,
710 TFormOnChange extends undefined | FormValidateOrFn<TParentData>,
711 TFormOnChangeAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
712 TFormOnBlur extends undefined | FormValidateOrFn<TParentData>,
713 TFormOnBlurAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
714 TFormOnSubmit extends undefined | FormValidateOrFn<TParentData>,
715 TFormOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
716 TFormOnDynamic extends undefined | FormValidateOrFn<TParentData>,
717 TFormOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TParentData>,
718 TFormOnServer extends undefined | FormAsyncValidateOrFn<TParentData>,
719 TPatentSubmitMeta,
720>({
721 children,
722 ...fieldOptions
723}: FieldComponentProps<
724 TParentData,
725 TName,
726 TData,
727 TOnMount,
728 TOnChange,
729 TOnChangeAsync,
730 TOnBlur,
731 TOnBlurAsync,
732 TOnSubmit,
733 TOnSubmitAsync,
734 TOnDynamic,
735 TOnDynamicAsync,
736 TFormOnMount,
737 TFormOnChange,
738 TFormOnChangeAsync,
739 TFormOnBlur,
740 TFormOnBlurAsync,
741 TFormOnSubmit,
742 TFormOnSubmitAsync,
743 TFormOnDynamic,
744 TFormOnDynamicAsync,
745 TFormOnServer,
746 TPatentSubmitMeta
747>): ReturnType<FunctionComponent> => {
748 const fieldApi = useField(fieldOptions as any)
749​
750 const jsxToDisplay = useMemo(
751 () => functionalUpdate(children, fieldApi as any),
752 [children, fieldApi],
753 )
754 return (<>{jsxToDisplay}</>) as never
755}) satisfies FunctionComponent<
756 FieldComponentProps<
757 any,
758 any,
759 any,
760 any,
761 any,
762 any,
763 any,
764 any,
765 any,
766 any,
767 any,
768 any,
769 any,
770 any,
771 any,
772 any,
773 any,
774 any,
775 any,
776 any,
777 any,
778 any,
779 any
780 >