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