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

createFormHook.tsx

627 lines17.6 KB

1'use client'
2/* eslint-disable @eslint-react/no-context-provider */
3import { createContext, useContext, useMemo } from 'react'
4import { useForm } from './useForm'
5import { useFieldGroup } from './useFieldGroup'
6import type {
7 AnyFieldApi,
8 AnyFormApi,
9 BaseFormOptions,
10 DeepKeysOfType,
11 FieldApi,
12 FieldsMap,
13 FormAsyncValidateOrFn,
14 FormOptions,
15 FormValidateOrFn,
16} from '@tanstack/form-core'
17import type {
18 ComponentType,
19 Context,
20 FunctionComponent,
21 PropsWithChildren,
22} from 'react'
23import type { FieldComponent } from './useField'
24import type { ReactFormExtendedApi } from './useForm'
25import type { AppFieldExtendedReactFieldGroupApi } from './useFieldGroup'
26​
27// We should never hit the `null` case here
28const fieldContext = createContext<AnyFieldApi>(null as never)
29const formContext = createContext<AnyFormApi>(null as never)
30​
31/**
32 * TypeScript inferencing is weird.
33 *
34 * If you have:
35 *
36 * @example
37 *
38 * interface Args<T> {
39 * arg?: T
40 * }
41 *
42 * function test<T>(arg?: Partial<Args<T>>): T {
43 * return 0 as any;
44 * }
45 *
46 * const a = test({});
47 *
48 * Then `T` will default to `unknown`.
49 *
50 * However, if we change `test` to be:
51 *
52 * @example
53 *
54 * function test<T extends undefined>(arg?: Partial<Args<T>>): T;
55 *
56 * Then `T` becomes `undefined`.
57 *
58 * Here, we are checking if the passed type `T` extends `DefaultT` and **only**
59 * `DefaultT`, as if that's the case we assume that inferencing has not occurred.
60 */
61type UnwrapOrAny<T> = [unknown] extends [T] ? any : T
62type UnwrapDefaultOrAny<DefaultT, T> = [DefaultT] extends [T]
63 ? [T] extends [DefaultT]
64 ? any
65 : T
66 : T
67​
68function useFormContext() {
69 const form = useContext(formContext)
70​
71 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
72 if (!form) {
73 throw new Error(
74 '`formContext` only works when within a `formComponent` passed to `createFormHook`',
75 )
76 }
77​
78 return form as ReactFormExtendedApi<
79 // If you need access to the form data, you need to use `withForm` instead
80 Record<string, never>,
81 any,
82 any,
83 any,
84 any,
85 any,
86 any,
87 any,
88 any,
89 any,
90 any,
91 any
92 >
94​
95export function createFormHookContexts() {
96 function useFieldContext<TData>() {
97 const field = useContext(fieldContext)
98​
99 // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
100 if (!field) {
101 throw new Error(
102 '`fieldContext` only works when within a `fieldComponent` passed to `createFormHook`',
103 )
104 }
105​
106 return field as FieldApi<
107 any,
108 string,
109 TData,
110 any,
111 any,
112 any,
113 any,
114 any,
115 any,
116 any,
117 any,
118 any,
119 any,
120 any,
121 any,
122 any,
123 any,
124 any,
125 any,
126 any,
127 any,
128 any,
129 any
130 >
131 }
132​
133 return { fieldContext, useFieldContext, useFormContext, formContext }
135​
136interface CreateFormHookProps<
137 TFieldComponents extends Record<string, ComponentType<any>>,
138 TFormComponents extends Record<string, ComponentType<any>>,
139> {
140 fieldComponents: TFieldComponents
141 fieldContext: Context<AnyFieldApi>
142 formComponents: TFormComponents
143 formContext: Context<AnyFormApi>
145​
146/**
147 * @private
148 */
149export type AppFieldExtendedReactFormApi<
150 TFormData,
151 TOnMount extends undefined | FormValidateOrFn<TFormData>,
152 TOnChange extends undefined | FormValidateOrFn<TFormData>,
153 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
154 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
155 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
156 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
157 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
158 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
159 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
160 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
161 TSubmitMeta,
162 TFieldComponents extends Record<string, ComponentType<any>>,
163 TFormComponents extends Record<string, ComponentType<any>>,
164> = ReactFormExtendedApi<
165 TFormData,
166 TOnMount,
167 TOnChange,
168 TOnChangeAsync,
169 TOnBlur,
170 TOnBlurAsync,
171 TOnSubmit,
172 TOnSubmitAsync,
173 TOnDynamic,
174 TOnDynamicAsync,
175 TOnServer,
176 TSubmitMeta
177> &
178 NoInfer<TFormComponents> & {
179 AppField: FieldComponent<
180 TFormData,
181 TOnMount,
182 TOnChange,
183 TOnChangeAsync,
184 TOnBlur,
185 TOnBlurAsync,
186 TOnSubmit,
187 TOnSubmitAsync,
188 TOnDynamic,
189 TOnDynamicAsync,
190 TOnServer,
191 TSubmitMeta,
192 NoInfer<TFieldComponents>
193 >
194 AppForm: ComponentType<
195 // PropsWithChildren<P> is not optional in React 17
196 PropsWithChildren<{}>
197 >
198 }
199​
200export interface WithFormProps<
201 TFormData,
202 TOnMount extends undefined | FormValidateOrFn<TFormData>,
203 TOnChange extends undefined | FormValidateOrFn<TFormData>,
204 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
205 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
206 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
207 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
208 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
209 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
210 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
211 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
212 TSubmitMeta,
213 TFieldComponents extends Record<string, ComponentType<any>>,
214 TFormComponents extends Record<string, ComponentType<any>>,
215 TRenderProps extends object = Record<string, never>,
216> extends FormOptions<
217 TFormData,
218 TOnMount,
219 TOnChange,
220 TOnChangeAsync,
221 TOnBlur,
222 TOnBlurAsync,
223 TOnSubmit,
224 TOnSubmitAsync,
225 TOnDynamic,
226 TOnDynamicAsync,
227 TOnServer,
228 TSubmitMeta
229> {
230 // Optional, but adds props to the `render` function outside of `form`
231 props?: TRenderProps
232 render: FunctionComponent<
233 PropsWithChildren<
234 NoInfer<TRenderProps> & {
235 form: AppFieldExtendedReactFormApi<
236 TFormData,
237 TOnMount,
238 TOnChange,
239 TOnChangeAsync,
240 TOnBlur,
241 TOnBlurAsync,
242 TOnSubmit,
243 TOnSubmitAsync,
244 TOnDynamic,
245 TOnDynamicAsync,
246 TOnServer,
247 TSubmitMeta,
248 TFieldComponents,
249 TFormComponents
250 >
251 }
252 >
253 >
255​
256export interface WithFieldGroupProps<
257 TFieldGroupData,
258 TFieldComponents extends Record<string, ComponentType<any>>,
259 TFormComponents extends Record<string, ComponentType<any>>,
260 TSubmitMeta,
261 TRenderProps extends object = Record<string, never>,
262> extends BaseFormOptions<TFieldGroupData, TSubmitMeta> {
263 // Optional, but adds props to the `render` function outside of `form`
264 props?: TRenderProps
265 render: FunctionComponent<
266 PropsWithChildren<
267 NoInfer<TRenderProps> & {
268 group: AppFieldExtendedReactFieldGroupApi<
269 unknown,
270 TFieldGroupData,
271 string | FieldsMap<unknown, TFieldGroupData>,
272 undefined | FormValidateOrFn<unknown>,
273 undefined | FormValidateOrFn<unknown>,
274 undefined | FormAsyncValidateOrFn<unknown>,
275 undefined | FormValidateOrFn<unknown>,
276 undefined | FormAsyncValidateOrFn<unknown>,
277 undefined | FormValidateOrFn<unknown>,
278 undefined | FormAsyncValidateOrFn<unknown>,
279 undefined | FormValidateOrFn<unknown>,
280 undefined | FormAsyncValidateOrFn<unknown>,
281 undefined | FormAsyncValidateOrFn<unknown>,
282 // this types it as 'never' in the render prop. It should prevent any
283 // untyped meta passed to the handleSubmit by accident.
284 unknown extends TSubmitMeta ? never : TSubmitMeta,
285 TFieldComponents,
286 TFormComponents
287 >
288 }
289 >
290 >
292​
293export function createFormHook<
294 const TComponents extends Record<string, ComponentType<any>>,
295 const TFormComponents extends Record<string, ComponentType<any>>,
296>({
297 fieldComponents,
298 fieldContext,
299 formContext,
300 formComponents,
301}: CreateFormHookProps<TComponents, TFormComponents>) {
302 function useAppForm<
303 TFormData,
304 TOnMount extends undefined | FormValidateOrFn<TFormData>,
305 TOnChange extends undefined | FormValidateOrFn<TFormData>,
306 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
307 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
308 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
309 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
310 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
311 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
312 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
313 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
314 TSubmitMeta,
315 >(
316 props: FormOptions<
317 TFormData,
318 TOnMount,
319 TOnChange,
320 TOnChangeAsync,
321 TOnBlur,
322 TOnBlurAsync,
323 TOnSubmit,
324 TOnSubmitAsync,
325 TOnDynamic,
326 TOnDynamicAsync,
327 TOnServer,
328 TSubmitMeta
329 >,
330 ): AppFieldExtendedReactFormApi<
331 TFormData,
332 TOnMount,
333 TOnChange,
334 TOnChangeAsync,
335 TOnBlur,
336 TOnBlurAsync,
337 TOnSubmit,
338 TOnSubmitAsync,
339 TOnDynamic,
340 TOnDynamicAsync,
341 TOnServer,
342 TSubmitMeta,
343 TComponents,
344 TFormComponents
345 > {
346 const form = useForm(props)
347​
348 // PropsWithChildren<P> is not optional in React 17
349 const AppForm = useMemo<ComponentType<PropsWithChildren<{}>>>(() => {
350 return ({ children }) => {
351 return (
352 <formContext.Provider value={form}>{children}</formContext.Provider>
353 )
354 }
355 }, [form])
356​
357 const AppField = useMemo(() => {
358 const AppField = (({ children, ...props }) => {
359 return (
360 <form.Field {...props}>
361 {(field) => (
362 <fieldContext.Provider value={field}>
363 {children(Object.assign(field, fieldComponents))}
364 </fieldContext.Provider>
365 )}
366 </form.Field>
367 )
368 }) as FieldComponent<
369 TFormData,
370 TOnMount,
371 TOnChange,
372 TOnChangeAsync,
373 TOnBlur,
374 TOnBlurAsync,
375 TOnSubmit,
376 TOnSubmitAsync,
377 TOnDynamic,
378 TOnDynamicAsync,
379 TOnServer,
380 TSubmitMeta,
381 TComponents
382 >
383 return AppField
384 }, [form])
385​
386 const extendedForm = useMemo(() => {
387 return Object.assign(form, {
388 AppField,
389 AppForm,
390 ...formComponents,
391 })
392 }, [form, AppField, AppForm])
393​
394 return extendedForm
395 }
396​
397 function withForm<
398 TFormData,
399 TOnMount extends undefined | FormValidateOrFn<TFormData>,
400 TOnChange extends undefined | FormValidateOrFn<TFormData>,
401 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
402 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
403 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
404 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
405 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
406 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
407 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
408 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
409 TSubmitMeta,
410 TRenderProps extends object = {},
411 >({
412 render,
413 props,
414 }: WithFormProps<
415 TFormData,
416 TOnMount,
417 TOnChange,
418 TOnChangeAsync,
419 TOnBlur,
420 TOnBlurAsync,
421 TOnSubmit,
422 TOnSubmitAsync,
423 TOnDynamic,
424 TOnDynamicAsync,
425 TOnServer,
426 TSubmitMeta,
427 TComponents,
428 TFormComponents,
429 TRenderProps
430 >): WithFormProps<
431 UnwrapOrAny<TFormData>,
432 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnMount>,
433 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnChange>,
434 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnChangeAsync>,
435 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnBlur>,
436 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnBlurAsync>,
437 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnSubmit>,
438 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnSubmitAsync>,
439 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnDynamic>,
440 UnwrapDefaultOrAny<
441 undefined | FormValidateOrFn<TFormData>,
442 TOnDynamicAsync
443 >,
444 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnServer>,
445 UnwrapOrAny<TSubmitMeta>,
446 UnwrapOrAny<TComponents>,
447 UnwrapOrAny<TFormComponents>,
448 UnwrapOrAny<TRenderProps>
449 >['render'] {
450 return function Render(innerProps) {
451 return render({ ...props, ...innerProps })
452 }
453 }
454​
455 function withFieldGroup<
456 TFieldGroupData,
457 TSubmitMeta,
458 TRenderProps extends object = {},
459 >({
460 render,
461 props,
462 defaultValues,
463 }: WithFieldGroupProps<
464 TFieldGroupData,
465 TComponents,
466 TFormComponents,
467 TSubmitMeta,
468 TRenderProps
469 >): <
470 TFormData,
471 TFields extends
472 | DeepKeysOfType<TFormData, TFieldGroupData | null | undefined>
473 | FieldsMap<TFormData, TFieldGroupData>,
474 TOnMount extends undefined | FormValidateOrFn<TFormData>,
475 TOnChange extends undefined | FormValidateOrFn<TFormData>,
476 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
477 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
478 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
479 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
480 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
481 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
482 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
483 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
484 TFormSubmitMeta,
485 >(
486 params: PropsWithChildren<
487 NoInfer<TRenderProps> & {
488 form:
489 | AppFieldExtendedReactFormApi<
490 TFormData,
491 TOnMount,
492 TOnChange,
493 TOnChangeAsync,
494 TOnBlur,
495 TOnBlurAsync,
496 TOnSubmit,
497 TOnSubmitAsync,
498 TOnDynamic,
499 TOnDynamicAsync,
500 TOnServer,
501 unknown extends TSubmitMeta ? TFormSubmitMeta : TSubmitMeta,
502 TComponents,
503 TFormComponents
504 >
505 | AppFieldExtendedReactFieldGroupApi<
506 // Since this only occurs if you nest it within other field groups, it can be more
507 // lenient with the types.
508 unknown,
509 TFormData,
510 string | FieldsMap<unknown, TFormData>,
511 any,
512 any,
513 any,
514 any,
515 any,
516 any,
517 any,
518 any,
519 any,
520 any,
521 unknown extends TSubmitMeta ? TFormSubmitMeta : TSubmitMeta,
522 TComponents,
523 TFormComponents
524 >
525 fields: TFields
526 }
527 >,
528 ) => ReturnType<FunctionComponent> {
529 return function Render(innerProps) {
530 const fieldGroupProps = useMemo(() => {
531 return {
532 form: innerProps.form,
533 fields: innerProps.fields,
534 defaultValues,
535 formComponents,
536 }
537 }, [innerProps.form, innerProps.fields])
538 const fieldGroupApi = useFieldGroup(fieldGroupProps as any)
539​
540 return render({ ...props, ...innerProps, group: fieldGroupApi as any })
541 }
542 }
543​
544 /**
545 * ⚠️ **Use withForm whenever possible.**
546 *
547 * Gets a typed form from the `<form.AppForm />` context.
548 */
549 function useTypedAppFormContext<
550 TFormData,
551 TOnMount extends undefined | FormValidateOrFn<TFormData>,
552 TOnChange extends undefined | FormValidateOrFn<TFormData>,
553 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
554 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
555 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
556 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
557 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
558 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
559 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
560 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
561 TSubmitMeta,
562 >(
563 _props: FormOptions<
564 TFormData,
565 TOnMount,
566 TOnChange,
567 TOnChangeAsync,
568 TOnBlur,
569 TOnBlurAsync,
570 TOnSubmit,
571 TOnSubmitAsync,
572 TOnDynamic,
573 TOnDynamicAsync,
574 TOnServer,
575 TSubmitMeta
576 >,
577 ): AppFieldExtendedReactFormApi<
578 TFormData,
579 TOnMount,
580 TOnChange,
581 TOnChangeAsync,
582 TOnBlur,
583 TOnBlurAsync,
584 TOnSubmit,
585 TOnSubmitAsync,
586 TOnDynamic,
587 TOnDynamicAsync,
588 TOnServer,
589 TSubmitMeta,
590 TComponents,
591 TFormComponents
592 > {
593 const form = useFormContext()
594​
595 return form as never
596 }
597​
598 function extendForm<
599 const TNewField extends Record<string, ComponentType<any>> & {
600 [K in keyof TComponents]?: 'Error: field component names must be unique β€” this key already exists in the base form'
601 },
602 const TNewForm extends Record<string, ComponentType<any>> & {
603 [K in keyof TFormComponents]?: 'Error: form component names must be unique β€” this key already exists in the base form'
604 },
605 >(extension: { fieldComponents?: TNewField; formComponents?: TNewForm }) {
606 return createFormHook({
607 fieldContext,
608 formContext,
609 fieldComponents: {
610 ...fieldComponents,
611 ...extension.fieldComponents,
612 } as TComponents & TNewField,
613 formComponents: {
614 ...formComponents,
615 ...extension.formComponents,
616 } as TFormComponents & TNewForm,
617 })
618 }
619​
620 return {
621 useAppForm,
622 withForm,
623 withFieldGroup,
624 useTypedAppFormContext,
625 extendForm,
626 }