Open History to see the last commit
1import { FormApi, functionalUpdate, mergeAndUpdate } from '@tanstack/form-core'
2import { useMemo, useRef, useState } from 'preact/hooks'
3import { useSelector } from '@tanstack/preact-store'
4import { Field } from './useField'
5import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'
6import { useFormId } from './useFormId'
7import { FormGroup } from './useFormGroup'
8import type { FormGroupComponent } from './useFormGroup'
9import type {
10 AnyFormApi,
11 AnyFormState,
12 FormAsyncValidateOrFn,
13 FormOptions,
14 FormState,
15 FormValidateOrFn,
16} from '@tanstack/form-core'
17import type { ComponentChild, FunctionComponent } from 'preact'
18import type { FieldComponent } from './useField'
19import type { PropsWithChildren } from './types'
20β
21/**
22 * Fields that are added onto the `FormAPI` from `@tanstack/form-core` and returned from `useForm`
23 */
24export interface PreactFormApi<
25 in out TFormData,
26 in out TOnMount extends undefined | FormValidateOrFn<TFormData>,
27 in out TOnChange extends undefined | FormValidateOrFn<TFormData>,
28 in out TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
29 in out TOnBlur extends undefined | FormValidateOrFn<TFormData>,
30 in out TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
31 in out TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
32 in out TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
33 in out TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
34 in out TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
35 in out TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
36 in out TSubmitMeta,
37> {
38 /**
39 * A Preact component to render form fields. With this, you can render and manage individual form fields.
40 */
41 Field: FieldComponent<
42 TFormData,
43 TOnMount,
44 TOnChange,
45 TOnChangeAsync,
46 TOnBlur,
47 TOnBlurAsync,
48 TOnSubmit,
49 TOnSubmitAsync,
50 TOnDynamic,
51 TOnDynamicAsync,
52 TOnServer,
53 TSubmitMeta
54 >
55 FormGroup: FormGroupComponent<
56 TFormData,
57 TOnMount,
58 TOnChange,
59 TOnChangeAsync,
60 TOnBlur,
61 TOnBlurAsync,
62 TOnSubmit,
63 TOnSubmitAsync,
64 TOnDynamic,
65 TOnDynamicAsync,
66 TOnServer,
67 TSubmitMeta
68 >
69 /**
70 * 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.
71 */
72 Subscribe: <
73 TSelected = NoInfer<
74 FormState<
75 TFormData,
76 TOnMount,
77 TOnChange,
78 TOnChangeAsync,
79 TOnBlur,
80 TOnBlurAsync,
81 TOnSubmit,
82 TOnSubmitAsync,
83 TOnDynamic,
84 TOnDynamicAsync,
85 TOnServer
86 >
87 >,
88 >(props: {
89 selector?: (
90 state: NoInfer<
91 FormState<
92 TFormData,
93 TOnMount,
94 TOnChange,
95 TOnChangeAsync,
96 TOnBlur,
97 TOnBlurAsync,
98 TOnSubmit,
99 TOnSubmitAsync,
100 TOnDynamic,
101 TOnDynamicAsync,
102 TOnServer
103 >
104 >,
105 ) => TSelected
106 children: ((state: NoInfer<TSelected>) => ComponentChild) | ComponentChild
107 }) => ReturnType<FunctionComponent>
108}
109β
110/**
111 * An extended version of the `FormApi` class that includes Preact-specific functionalities from `PreactFormApi`
112 */
113export type PreactFormExtendedApi<
114 TFormData,
115 TOnMount extends undefined | FormValidateOrFn<TFormData>,
116 TOnChange extends undefined | FormValidateOrFn<TFormData>,
117 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
118 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
119 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
120 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
121 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
122 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
123 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
124 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
125 TSubmitMeta,
126> = FormApi<
127 TFormData,
128 TOnMount,
129 TOnChange,
130 TOnChangeAsync,
131 TOnBlur,
132 TOnBlurAsync,
133 TOnSubmit,
134 TOnSubmitAsync,
135 TOnDynamic,
136 TOnDynamicAsync,
137 TOnServer,
138 TSubmitMeta
139> &
140 PreactFormApi<
141 TFormData,
142 TOnMount,
143 TOnChange,
144 TOnChangeAsync,
145 TOnBlur,
146 TOnBlurAsync,
147 TOnSubmit,
148 TOnSubmitAsync,
149 TOnDynamic,
150 TOnDynamicAsync,
151 TOnServer,
152 TSubmitMeta
153 >
154β
155function LocalSubscribe({
156 form,
157 selector,
158 children,
159}: PropsWithChildren<{
160 form: AnyFormApi
161 selector: (state: AnyFormState) => AnyFormState
162}>): ReturnType<FunctionComponent> {
163 const data = useSelector(form.store, selector)
164β
165 return <>{functionalUpdate(children, data)}</>
166}
167β
168/**
169 * A custom React Hook that returns an extended instance of the `FormApi` class.
170 *
171 * This API encapsulates all the necessary functionalities related to the form. It allows you to manage form state, handle submissions, and interact with form fields
172 */
173export function useForm<
174 TFormData,
175 TOnMount extends undefined | FormValidateOrFn<TFormData>,
176 TOnChange extends undefined | FormValidateOrFn<TFormData>,
177 TOnChangeAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
178 TOnBlur extends undefined | FormValidateOrFn<TFormData>,
179 TOnBlurAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
180 TOnSubmit extends undefined | FormValidateOrFn<TFormData>,
181 TOnSubmitAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
182 TOnDynamic extends undefined | FormValidateOrFn<TFormData>,
183 TOnDynamicAsync extends undefined | FormAsyncValidateOrFn<TFormData>,
184 TOnServer extends undefined | FormAsyncValidateOrFn<TFormData>,
185 TSubmitMeta,
186>(
187 opts?: FormOptions<
188 TFormData,
189 TOnMount,
190 TOnChange,
191 TOnChangeAsync,
192 TOnBlur,
193 TOnBlurAsync,
194 TOnSubmit,
195 TOnSubmitAsync,
196 TOnDynamic,
197 TOnDynamicAsync,
198 TOnServer,
199 TSubmitMeta
200 >,
201) {
202 const fallbackFormId = useFormId()
203 const [prevFormId, setPrevFormId] = useState<string>(opts?.formId as never)
204β
205 const [formApi, setFormApi] = useState(() => {
206 return new FormApi<
207 TFormData,
208 TOnMount,
209 TOnChange,
210 TOnChangeAsync,
211 TOnBlur,
212 TOnBlurAsync,
213 TOnSubmit,
214 TOnSubmitAsync,
215 TOnDynamic,
216 TOnDynamicAsync,
217 TOnServer,
218 TSubmitMeta
219 >({ ...opts, formId: opts?.formId ?? fallbackFormId })
220 })
221β
222 if (prevFormId !== opts?.formId) {
223 const formId = opts?.formId ?? fallbackFormId
224 setFormApi(new FormApi({ ...opts, formId }))
225 setPrevFormId(formId)
226 }
227β
228 const extendedFormApi = useMemo(() => {
229 const extendedApi: PreactFormExtendedApi<
230 TFormData,
231 TOnMount,
232 TOnChange,
233 TOnChangeAsync,
234 TOnBlur,
235 TOnBlurAsync,
236 TOnSubmit,
237 TOnSubmitAsync,
238 TOnDynamic,
239 TOnDynamicAsync,
240 TOnServer,
241 TSubmitMeta
242 > = {
243 ...formApi,
244 handleSubmit: ((...props: never[]) => {
245 return formApi._handleSubmit(...props)
246 }) as typeof formApi.handleSubmit,
247 // We must add all `get`ters from `core`'s `FormApi` here, as otherwise the spread operator won't catch those
248 get formId(): string {
249 return formApi._formId
250 },
251 get state() {
252 return formApi.store.state
253 },
254 } as never
255β
256 extendedApi.Field = function APIField(props) {
257 return <Field {...props} form={formApi} />
258 }
259β
260 extendedApi.FormGroup = function APIFormGroup(props) {
261 return <FormGroup {...props} form={formApi} />
262 }
263β
264 extendedApi.Subscribe = function Subscribe(props: any) {
265 return (
266 <LocalSubscribe
267 form={formApi}
268 selector={props.selector}
269 children={props.children}
270 />
271 )
272 }
273β
274 return extendedApi
275 }, [formApi])
276β
277 useIsomorphicLayoutEffect(formApi.mount, [])
278β
279 /**
280 * formApi.update should not have any side effects. Think of it like a `useRef`
281 * that we need to keep updated every render with the most up-to-date information.
282 */
283 useIsomorphicLayoutEffect(() => {
284 formApi.update(opts)
285 })
286β
287 const hasRan = useRef(false)
288β
289 useIsomorphicLayoutEffect(() => {
290 if (!hasRan.current) return
291 if (!opts?.transform) return
292 mergeAndUpdate(formApi, opts.transform as never)
293 }, [formApi, opts?.transform])
294β
295 useIsomorphicLayoutEffect(() => {
296 hasRan.current = true
297 })
298β
299 return extendedFormApi
300}