Open History to see the last commit
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 >
93}
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 }
134}
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>
144}
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 >
254}
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 >
291}
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 // eslint-disable-next-line @eslint-react/no-context-provider
363 <fieldContext.Provider value={field}>
364 {children(Object.assign(field, fieldComponents))}
365 </fieldContext.Provider>
366 )}
367 </form.Field>
368 )
369 }) as FieldComponent<
370 TFormData,
371 TOnMount,
372 TOnChange,
373 TOnChangeAsync,
374 TOnBlur,
375 TOnBlurAsync,
376 TOnSubmit,
377 TOnSubmitAsync,
378 TOnDynamic,
379 TOnDynamicAsync,
380 TOnServer,
381 TSubmitMeta,
382 TComponents
383 >
384 return AppField
385 }, [form])
386β
387 const extendedForm = useMemo(() => {
388 return Object.assign(form, {
389 AppField,
390 AppForm,
391 ...formComponents,
392 })
393 }, [form, AppField, AppForm])
394β
395 return extendedForm
396 }
397β
398 function withForm<
399 TFormData,
400 TOnMount extends undefined | FormValidateOrFn<TFormData>,
401 TOnChange extends undefined | FormValidateOrFn<TFormData>,
402 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
403 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
404 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
405 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
406 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
407 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
408 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
409 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
410 TSubmitMeta,
411 TRenderProps extends object = {},
412 >({
413 render,
414 props,
415 }: WithFormProps<
416 TFormData,
417 TOnMount,
418 TOnChange,
419 TOnChangeAsync,
420 TOnBlur,
421 TOnBlurAsync,
422 TOnSubmit,
423 TOnSubmitAsync,
424 TOnDynamic,
425 TOnDynamicAsync,
426 TOnServer,
427 TSubmitMeta,
428 TComponents,
429 TFormComponents,
430 TRenderProps
431 >): WithFormProps<
432 UnwrapOrAny<TFormData>,
433 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnMount>,
434 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnChange>,
435 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnChangeAsync>,
436 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnBlur>,
437 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnBlurAsync>,
438 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnSubmit>,
439 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnSubmitAsync>,
440 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnDynamic>,
441 UnwrapDefaultOrAny<
442 undefined | FormValidateOrFn<TFormData>,
443 TOnDynamicAsync
444 >,
445 UnwrapDefaultOrAny<undefined | FormValidateOrFn<TFormData>, TOnServer>,
446 UnwrapOrAny<TSubmitMeta>,
447 UnwrapOrAny<TComponents>,
448 UnwrapOrAny<TFormComponents>,
449 UnwrapOrAny<TRenderProps>
450 >['render'] {
451 return function Render(innerProps) {
452 return render({ ...props, ...innerProps })
453 }
454 }
455β
456 function withFieldGroup<
457 TFieldGroupData,
458 TSubmitMeta,
459 TRenderProps extends object = {},
460 >({
461 render,
462 props,
463 defaultValues,
464 }: WithFieldGroupProps<
465 TFieldGroupData,
466 TComponents,
467 TFormComponents,
468 TSubmitMeta,
469 TRenderProps
470 >): <
471 TFormData,
472 TFields extends
473 | DeepKeysOfType<TFormData, TFieldGroupData | null | undefined>
474 | FieldsMap<TFormData, TFieldGroupData>,
475 TOnMount extends undefined | FormValidateOrFn<TFormData>,
476 TOnChange extends undefined | FormValidateOrFn<TFormData>,
477 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
478 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
479 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
480 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
481 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
482 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
483 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
484 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
485 TFormSubmitMeta,
486 >(
487 params: PropsWithChildren<
488 NoInfer<TRenderProps> & {
489 form:
490 | AppFieldExtendedReactFormApi<
491 TFormData,
492 TOnMount,
493 TOnChange,
494 TOnChangeAsync,
495 TOnBlur,
496 TOnBlurAsync,
497 TOnSubmit,
498 TOnSubmitAsync,
499 TOnDynamic,
500 TOnDynamicAsync,
501 TOnServer,
502 unknown extends TSubmitMeta ? TFormSubmitMeta : TSubmitMeta,
503 TComponents,
504 TFormComponents
505 >
506 | AppFieldExtendedReactFieldGroupApi<
507 // Since this only occurs if you nest it within other field groups, it can be more
508 // lenient with the types.
509 unknown,
510 TFormData,
511 string | FieldsMap<unknown, TFormData>,
512 any,
513 any,
514 any,
515 any,
516 any,
517 any,
518 any,
519 any,
520 any,
521 any,
522 unknown extends TSubmitMeta ? TFormSubmitMeta : TSubmitMeta,
523 TComponents,
524 TFormComponents
525 >
526 fields: TFields
527 }
528 >,
529 ) => ReturnType<FunctionComponent> {
530 return function Render(innerProps) {
531 const fieldGroupProps = useMemo(() => {
532 return {
533 form: innerProps.form,
534 fields: innerProps.fields,
535 defaultValues,
536 formComponents,
537 }
538 }, [innerProps.form, innerProps.fields])
539 const fieldGroupApi = useFieldGroup(fieldGroupProps as any)
540β
541 return render({ ...props, ...innerProps, group: fieldGroupApi as any })
542 }
543 }
544β
545 /**
546 * β οΈ **Use withForm whenever possible.**
547 *
548 * Gets a typed form from the `<form.AppForm />` context.
549 */
550 function useTypedAppFormContext<
551 TFormData,
552 TOnMount extends undefined | FormValidateOrFn<TFormData>,
553 TOnChange extends undefined | FormValidateOrFn<TFormData>,
554 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
555 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
556 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
557 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
558 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
559 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
560 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
561 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
562 TSubmitMeta,
563 >(
564 _props: FormOptions<
565 TFormData,
566 TOnMount,
567 TOnChange,
568 TOnChangeAsync,
569 TOnBlur,
570 TOnBlurAsync,
571 TOnSubmit,
572 TOnSubmitAsync,
573 TOnDynamic,
574 TOnDynamicAsync,
575 TOnServer,
576 TSubmitMeta
577 >,
578 ): AppFieldExtendedReactFormApi<
579 TFormData,
580 TOnMount,
581 TOnChange,
582 TOnChangeAsync,
583 TOnBlur,
584 TOnBlurAsync,
585 TOnSubmit,
586 TOnSubmitAsync,
587 TOnDynamic,
588 TOnDynamicAsync,
589 TOnServer,
590 TSubmitMeta,
591 TComponents,
592 TFormComponents
593 > {
594 const form = useFormContext()
595β
596 return form as never
597 }
598β
599 return {
600 useAppForm,
601 withForm,
602 withFieldGroup,
603 useTypedAppFormContext,
604 }
605}