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

withFields.public.ts

256 lines7.4 KB

1import { defineFieldGroupRuntime } from './withFields.lib'
2import type {
3 FieldGroupFieldBindings,
4 FieldGroupFieldBindingsProps,
5 FieldGroupFieldData,
6 FieldGroupFields,
7 FieldGroupFieldsPropName,
8 FieldGroupHelper,
9 FormApi,
10} from '@tanstack/form-core'
11import type { ReactNode } from 'react'
12import type { ReactTanStackFormComponents } from '../ReactForm/Components.public'
13import type { FieldGroupApi } from './FieldGroupApi.public'
14import type { ReactComponentTree } from '../AppForm/componentMap.public'
15​
16declare const fieldGroupFieldsSymbol: unique symbol
17​
18export type FieldGroupFieldsOf<TFieldGroup> = TFieldGroup extends {
19 readonly [fieldGroupFieldsSymbol]: infer TFields extends FieldGroupFields
21 ? TFields
22 : never
23​
24export type ReactFieldGroup<
25 TFields extends FieldGroupFields,
26 TFieldComponents extends ReactComponentTree = Record<never, never>,
27> = FieldGroupApi<FieldGroupFieldData<TFields>, TFieldComponents> & {
28 readonly [fieldGroupFieldsSymbol]: TFields
30​
31export type FieldGroupFieldComponentsOf<TFieldGroup> =
32 TFieldGroup extends ReactFieldGroup<any, infer TFieldComponents>
33 ? TFieldComponents
34 : never
35​
36export type FieldGroupForm<
37 TFieldComponents extends ReactComponentTree = Record<never, never>,
38 TFormData = any,
39> = FormApi<TFormData, any> &
40 ReactTanStackFormComponents<TFormData, any, TFieldComponents>
41​
42export type FieldGroupFieldBindingsOf<TFieldGroup, TFormData> =
43 FieldGroupFieldsOf<TFieldGroup> extends FieldGroupFields
44 ? FieldGroupFieldBindings<FieldGroupFieldsOf<TFieldGroup>, TFormData>
45 : never
46​
47/**
48 * Wraps a component that accepts a field-group API and returns a component
49 * that accepts a form and, when needed, virtual-to-concrete field bindings.
50 *
51 * If every virtual field name is already a compatible path in the form, the
52 * returned component binds those paths automatically when the bindings prop is
53 * omitted. A complete bindings map can still reroute them. Otherwise, the
54 * bindings prop is required.
55 *
56 * @example
57 * ```tsx
58 * const passwordFieldGroup = defineFieldGroup(({ strict }) => ({
59 * password: strict<string>(),
60 * confirmPassword: strict<string>(),
61 * }))
62 *
63 * interface PasswordFieldsProps {
64 * fields: typeof passwordFieldGroup.fields
65 * }
66 *
67 * function PasswordFields({ fields }: PasswordFieldsProps) {
68 * // ...
69 * }
70 *
71 * const PasswordSection = passwordFieldGroup.bindComponent(
72 * PasswordFields,
73 * 'fields',
74 * )
75 *
76 * function AccountForm() {
77 * const form = useForm({
78 * defaultValues: {
79 * account: {
80 * password: '',
81 * confirmPassword: '',
82 * },
83 * },
84 * })
85 *
86 * return (
87 * <PasswordSection
88 * form={form}
89 * fields={{
90 * password: 'account.password',
91 * confirmPassword: 'account.confirmPassword',
92 * }}
93 * />
94 * )
95 * }
96 * ```
97 *
98 * @typeParam TFieldGroup - Library-managed. Do not specify explicitly.
99 */
100export type FieldGroupWithFieldsFn<
101 TFieldGroup extends ReactFieldGroup<any, any>,
102> = <
103 TProps extends object,
104 TFieldsPropName extends FieldGroupFieldsPropName<TProps, TFieldGroup>,
105>(
106 Component: (props: TProps) => ReactNode,
107 fieldsPropName: TFieldsPropName,
108) => <TFormData>(
109 props: Omit<TProps, TFieldsPropName | 'form'> & {
110 form: FieldGroupForm<FieldGroupFieldComponentsOf<TFieldGroup>, TFormData>
111 } & FieldGroupFieldBindingsProps<
112 FieldGroupFieldsOf<TFieldGroup>,
113 TFormData,
114 TFieldsPropName
115 >,
116) => ReactNode
117​
118export interface FieldGroupDefinition<
119 TFields extends FieldGroupFields,
120 TFieldComponents extends ReactComponentTree,
121> {
122 /**
123 * The virtual field-group API injected into the component passed to
124 * `bindComponent`.
125 */
126 fields: ReactFieldGroup<TFields, TFieldComponents>
127 /**
128 * Binds a component's field-group API prop to concrete paths in a parent
129 * form.
130 *
131 * The returned component accepts the original component props except for the
132 * injected field-group API prop and adds a `form` prop. When every virtual
133 * field name is already a compatible form path, those paths bind
134 * automatically when the bindings prop is omitted. A complete bindings map
135 * can still reroute them. Otherwise, the injected prop name is reused for the
136 * required virtual-to-concrete field binding map.
137 *
138 * @example
139 * ```tsx
140 * const passwordFieldGroup = defineFieldGroup(({ strict }) => ({
141 * password: strict<string>(),
142 * confirmPassword: strict<string>(),
143 * }))
144 *
145 * interface PasswordFieldsProps {
146 * fields: typeof passwordFieldGroup.fields
147 * legend: string
148 * }
149 *
150 * function PasswordFields({ fields, legend }: PasswordFieldsProps) {
151 * return (
152 * <fieldset>
153 * <legend>{legend}</legend>
154 * <fields.Field name="password">
155 * {(field) => (
156 * <input
157 * type="password"
158 * value={field.value}
159 * onChange={(event) => field.handleChange(event.target.value)}
160 * />
161 * )}
162 * </fields.Field>
163 * <fields.Field name="confirmPassword">
164 * {(field) => (
165 * <input
166 * type="password"
167 * value={field.value}
168 * onChange={(event) => field.handleChange(event.target.value)}
169 * />
170 * )}
171 * </fields.Field>
172 * </fieldset>
173 * )
174 * }
175 *
176 * const PasswordSection = passwordFieldGroup.bindComponent(
177 * PasswordFields,
178 * 'fields',
179 * )
180 *
181 * <PasswordSection
182 * form={form}
183 * legend="Choose a password"
184 * fields={{
185 * password: 'account.password',
186 * confirmPassword: 'account.confirmPassword',
187 * }}
188 * />
189 * ```
190 */
191 bindComponent: FieldGroupWithFieldsFn<
192 ReactFieldGroup<TFields, TFieldComponents>
193 >
195​
196/**
197 * Signature shared by `defineFieldGroup` and app-form field-group definers.
198 */
199export type DefineFieldGroupFn<TFieldComponents extends ReactComponentTree> = <
200 const TFields extends FieldGroupFields,
201>(
202 defineFn: (helper: FieldGroupHelper) => TFields,
203) => FieldGroupDefinition<TFields, TFieldComponents>
204​
205/**
206 * Defines a reusable group of virtual fields that can be bound to concrete
207 * paths in different parent forms.
208 *
209 * Use `strict` when a binding must have exactly the declared value type. Use
210 * `loose` when a binding may have the declared type or a narrower assignable
211 * type.
212 *
213 * @example
214 * ```tsx
215 * const passwordFieldGroup = defineFieldGroup(({ strict }) => ({
216 * password: strict<string>(),
217 * confirmPassword: strict<string>(),
218 * }))
219 *
220 * interface PasswordFieldsProps {
221 * fields: typeof passwordFieldGroup.fields
222 * }
223 *
224 * function PasswordFields({ fields }: PasswordFieldsProps) {
225 * return (
226 * <>
227 * <fields.Field name="password">
228 * {(field) => (
229 * <input
230 * type="password"
231 * value={field.value}
232 * onChange={(event) => field.handleChange(event.target.value)}
233 * />
234 * )}
235 * </fields.Field>
236 * <fields.Field name="confirmPassword">
237 * {(field) => (
238 * <input
239 * type="password"
240 * value={field.value}
241 * onChange={(event) => field.handleChange(event.target.value)}
242 * />
243 * )}
244 * </fields.Field>
245 * </>
246 * )
247 * }
248 *
249 * export const PasswordSection = passwordFieldGroup.bindComponent(
250 * PasswordFields,
251 * 'fields',
252 * )
253 * ```
254 */
255export const defineFieldGroup: DefineFieldGroupFn<Record<never, never>> =
256 defineFieldGroupRuntime as never