Open History to see the last commit
1import { useState } from 'react'
2import { useStore } from '@tanstack/react-store'
3import { FieldGroupApi, functionalUpdate } from '@tanstack/form-core'
4import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'
5import type {
6 AnyFieldGroupApi,
7 DeepKeysOfType,
8 FieldGroupState,
9 FieldsMap,
10 FormAsyncValidateOrFn,
11 FormValidateOrFn,
12} from '@tanstack/form-core'
13import type { AppFieldExtendedReactFormApi } from './createFormHook'
14import type { ComponentType, PropsWithChildren, ReactNode } from 'react'
15import type { LensFieldComponent } from './useField'
16β
17function LocalSubscribe({
18 lens,
19 selector,
20 children,
21}: PropsWithChildren<{
22 lens: AnyFieldGroupApi
23 selector: (state: FieldGroupState<any>) => FieldGroupState<any>
24}>) {
25 const data = useStore(lens.store, selector)
26β
27 return functionalUpdate(children, data)
28}
29β
30/**
31 * @private
32 */
33export type AppFieldExtendedReactFieldGroupApi<
34 TFormData,
35 TFieldGroupData,
36 TFields extends
37 | DeepKeysOfType<TFormData, TFieldGroupData | null | undefined>
38 | FieldsMap<TFormData, TFieldGroupData>,
39 TOnMount extends undefined | FormValidateOrFn<TFormData>,
40 TOnChange extends undefined | FormValidateOrFn<TFormData>,
41 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
42 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
43 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
44 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
45 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
46 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
47 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
48 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
49 TSubmitMeta,
50 TFieldComponents extends Record<string, ComponentType<any>>,
51 TFormComponents extends Record<string, ComponentType<any>>,
52> = FieldGroupApi<
53 TFormData,
54 TFieldGroupData,
55 TFields,
56 TOnMount,
57 TOnChange,
58 TOnChangeAsync,
59 TOnBlur,
60 TOnBlurAsync,
61 TOnSubmit,
62 TOnSubmitAsync,
63 TOnDynamic,
64 TOnDynamicAsync,
65 TOnServer,
66 TSubmitMeta
67> &
68 NoInfer<TFormComponents> & {
69 AppField: LensFieldComponent<
70 TFieldGroupData,
71 TSubmitMeta,
72 NoInfer<TFieldComponents>
73 >
74 AppForm: ComponentType<PropsWithChildren>
75 /**
76 * A React component to render form fields. With this, you can render and manage individual form fields.
77 */
78 Field: LensFieldComponent<TFieldGroupData, TSubmitMeta>
79β
80 /**
81 * A `Subscribe` function that allows you to listen and react to changes in the form's state. It's especially useful when you need to execute side effects or render specific components in response to state updates.
82 */
83 Subscribe: <TSelected = NoInfer<FieldGroupState<TFieldGroupData>>>(props: {
84 selector?: (state: NoInfer<FieldGroupState<TFieldGroupData>>) => TSelected
85 children: ((state: NoInfer<TSelected>) => ReactNode) | ReactNode
86 }) => ReactNode
87 }
88β
89export function useFieldGroup<
90 TFormData,
91 TFieldGroupData,
92 TFields extends
93 | DeepKeysOfType<TFormData, TFieldGroupData | null | undefined>
94 | FieldsMap<TFormData, TFieldGroupData>,
95 TOnMount extends undefined | FormValidateOrFn<TFormData>,
96 TOnChange extends undefined | FormValidateOrFn<TFormData>,
97 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
98 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
99 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
100 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
101 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
102 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
103 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
104 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
105 TComponents extends Record<string, ComponentType<any>>,
106 TFormComponents extends Record<string, ComponentType<any>>,
107 TSubmitMeta = never,
108>(opts: {
109 form:
110 | AppFieldExtendedReactFormApi<
111 TFormData,
112 TOnMount,
113 TOnChange,
114 TOnChangeAsync,
115 TOnBlur,
116 TOnBlurAsync,
117 TOnSubmit,
118 TOnSubmitAsync,
119 TOnDynamic,
120 TOnDynamicAsync,
121 TOnServer,
122 TSubmitMeta,
123 TComponents,
124 TFormComponents
125 >
126 | AppFieldExtendedReactFieldGroupApi<
127 // Since this only occurs if you nest it within other form lenses, it can be more
128 // lenient with the types.
129 unknown,
130 TFormData,
131 string | FieldsMap<unknown, TFormData>,
132 any,
133 any,
134 any,
135 any,
136 any,
137 any,
138 any,
139 any,
140 any,
141 any,
142 TSubmitMeta,
143 TComponents,
144 TFormComponents
145 >
146 fields: TFields
147 defaultValues?: TFieldGroupData
148 onSubmitMeta?: TSubmitMeta
149 formComponents: TFormComponents
150}): AppFieldExtendedReactFieldGroupApi<
151 TFormData,
152 TFieldGroupData,
153 TFields,
154 TOnMount,
155 TOnChange,
156 TOnChangeAsync,
157 TOnBlur,
158 TOnBlurAsync,
159 TOnSubmit,
160 TOnSubmitAsync,
161 TOnDynamic,
162 TOnDynamicAsync,
163 TOnServer,
164 TSubmitMeta,
165 TComponents,
166 TFormComponents
167> {
168 const [formLensApi] = useState(() => {
169 const api = new FieldGroupApi(opts)
170 const form =
171 opts.form instanceof FieldGroupApi
172 ? (opts.form.form as AppFieldExtendedReactFormApi<
173 TFormData,
174 TOnMount,
175 TOnChange,
176 TOnChangeAsync,
177 TOnBlur,
178 TOnBlurAsync,
179 TOnSubmit,
180 TOnSubmitAsync,
181 TOnDynamic,
182 TOnDynamicAsync,
183 TOnServer,
184 TSubmitMeta,
185 TComponents,
186 TFormComponents
187 >)
188 : opts.form
189β
190 const extendedApi: AppFieldExtendedReactFieldGroupApi<
191 TFormData,
192 TFieldGroupData,
193 TFields,
194 TOnMount,
195 TOnChange,
196 TOnChangeAsync,
197 TOnBlur,
198 TOnBlurAsync,
199 TOnSubmit,
200 TOnSubmitAsync,
201 TOnDynamic,
202 TOnDynamicAsync,
203 TOnServer,
204 TSubmitMeta,
205 TComponents,
206 TFormComponents
207 > = api as never
208β
209 extendedApi.AppForm = function AppForm(appFormProps) {
210 return <form.AppForm {...appFormProps} />
211 }
212β
213 extendedApi.AppField = function AppField(props) {
214 return (
215 <form.AppField {...(formLensApi.getFormFieldOptions(props) as any)} />
216 )
217 }
218β
219 extendedApi.Field = function Field(props) {
220 return <form.Field {...(formLensApi.getFormFieldOptions(props) as any)} />
221 }
222β
223 extendedApi.Subscribe = function Subscribe(props: any) {
224 return (
225 <LocalSubscribe
226 lens={formLensApi}
227 selector={props.selector}
228 children={props.children}
229 />
230 )
231 }
232β
233 return Object.assign(extendedApi, {
234 ...opts.formComponents,
235 }) as AppFieldExtendedReactFieldGroupApi<
236 TFormData,
237 TFieldGroupData,
238 TFields,
239 TOnMount,
240 TOnChange,
241 TOnChangeAsync,
242 TOnBlur,
243 TOnBlurAsync,
244 TOnSubmit,
245 TOnSubmitAsync,
246 TOnDynamic,
247 TOnDynamicAsync,
248 TOnServer,
249 TSubmitMeta,
250 TComponents,
251 TFormComponents
252 >
253 })
254β
255 useIsomorphicLayoutEffect(formLensApi.mount, [formLensApi])
256β
257 return formLensApi
258}