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

getFormHookHelpers.public.ts

279 lines9.0 KB

1import { brandComponentFactory, wrapField } from './fieldComponentHelpers.lib'
2import type { FieldWithValue } from '@tanstack/form-core'
3import type { ReactNode } from 'react'
4​
5type ExactFieldBrand<out TValue> = {
6 readonly __tanstackFieldExactType: TValue
7}
8​
9type AcceptsFieldBrand<out TAcceptedValue> = {
10 readonly __tanstackFieldAcceptsType: TAcceptedValue
12​
13type AnyFieldComponent = (props: any) => ReactNode
14​
15type PropsOf<TComponent> = TComponent extends (props: infer TProps) => ReactNode
16 ? TProps
17 : never
18​
19type FieldValuePropKeys<TProps> = {
20 [K in keyof TProps]-?: TProps[K] extends FieldWithValue<any> ? K : never
21}[keyof TProps]
22​
23type FieldValueFromProp<TProp> =
24 TProp extends FieldWithValue<infer TValue> ? TValue : never
25​
26type FieldValueFromComponentProp<
27 TProps,
28 TFieldPropKey extends keyof TProps,
29> = FieldValueFromProp<TProps[TFieldPropKey]>
30​
31type PublicPropsReplacingField<
32 TProps,
33 TFieldPropKey extends keyof TProps,
34> = Omit<TProps, TFieldPropKey>
35​
36type StrictInjectedFieldComponent<
37 TComponent extends AnyFieldComponent,
38 TProps = PropsOf<TComponent>,
39 TFieldPropKey extends FieldValuePropKeys<TProps> = FieldValuePropKeys<TProps>,
40> = ((
41 props: PublicPropsReplacingField<TProps, TFieldPropKey>,
42) => React.ReactNode) &
43 ExactFieldBrand<FieldValueFromComponentProp<TProps, TFieldPropKey>>
44​
45type LooseInjectedFieldComponent<
46 TComponent extends AnyFieldComponent,
47 TProps = PropsOf<TComponent>,
48 TFieldPropKey extends FieldValuePropKeys<TProps> = FieldValuePropKeys<TProps>,
49> = ((
50 props: PublicPropsReplacingField<TProps, TFieldPropKey>,
51) => React.ReactNode) &
52 AcceptsFieldBrand<FieldValueFromComponentProp<TProps, TFieldPropKey>>
53​
54type StrictBrandedFieldComponent<
55 TComponent extends AnyFieldComponent,
56 TValue,
57> = TComponent & ExactFieldBrand<TValue>
58​
59type LooseBrandedFieldComponent<
60 TComponent extends AnyFieldComponent,
61 TAcceptedValue,
62> = TComponent & AcceptsFieldBrand<TAcceptedValue>
63​
64/**
65 * Wraps components that accept a field API prop so App Form can supply that
66 * prop from field context.
67 */
68export interface FieldComponentHelper {
69 /**
70 * Wraps a component for fields whose value type exactly matches the value
71 * type of its field API prop.
72 *
73 * The returned component omits `fieldPropKey` from its public props and reads
74 * that field API from the nearest App Form field context. It must be rendered
75 * beneath an App Form or field-group `Field` or `ArrayField` component.
76 *
77 * @example
78 * ```tsx
79 * import { getFormHookHelpers } from '@tanstack/react-form'
80 * import type { FieldWithValue } from '@tanstack/react-form'
81 *
82 * function TextInput({
83 * field,
84 * label,
85 * }: {
86 * field: FieldWithValue<string>
87 * label: string
88 * }) {
89 * return (
90 * <label>
91 * {label}
92 * <input
93 * value={field.value}
94 * onChange={(event) => field.handleChange(event.target.value)}
95 * />
96 * </label>
97 * )
98 * }
99 *
100 * const { fieldComponent } = getFormHookHelpers()
101 * const TextField = fieldComponent.strict(TextInput, 'field')
102 * ```
103 *
104 * @param Component - The component whose field API prop should be injected.
105 * @param fieldPropKey - The prop that accepts the current field API.
106 * @typeParam TComponent - Library-managed. Do not specify explicitly.
107 * @typeParam TProps - Library-managed. Do not specify explicitly.
108 * @typeParam TFieldPropKey - Library-managed. Do not specify explicitly.
109 */
110 strict: <
111 TComponent extends AnyFieldComponent,
112 TProps = PropsOf<TComponent>,
113 TFieldPropKey extends FieldValuePropKeys<TProps> =
114 FieldValuePropKeys<TProps>,
115 >(
116 Component: TComponent,
117 fieldPropKey: TFieldPropKey,
118 ) => StrictInjectedFieldComponent<TComponent, TProps, TFieldPropKey>
119​
120 /**
121 * Wraps a component for fields whose value type is assignable to the value
122 * type accepted by its field API prop.
123 *
124 * The returned component omits `fieldPropKey` from its public props and reads
125 * that field API from the nearest App Form field context. Use this mode for a
126 * component that intentionally supports a broader range of field values.
127 *
128 * @example
129 * ```tsx
130 * import { getFormHookHelpers } from '@tanstack/react-form'
131 * import type { AnyFieldApi } from '@tanstack/react-form'
132 *
133 * function FieldErrors({ field }: { field: AnyFieldApi }) {
134 * return <span>{field.errors.map((error) => error.message).join(', ')}</span>
135 * }
136 *
137 * const { fieldComponent } = getFormHookHelpers()
138 * const Errors = fieldComponent.loose(FieldErrors, 'field')
139 * ```
140 *
141 * @param Component - The component whose field API prop should be injected.
142 * @param fieldPropKey - The prop that accepts the current field API.
143 * @typeParam TComponent - Library-managed. Do not specify explicitly.
144 * @typeParam TProps - Library-managed. Do not specify explicitly.
145 * @typeParam TFieldPropKey - Library-managed. Do not specify explicitly.
146 */
147 loose: <
148 TComponent extends AnyFieldComponent,
149 TProps = PropsOf<TComponent>,
150 TFieldPropKey extends FieldValuePropKeys<TProps> =
151 FieldValuePropKeys<TProps>,
152 >(
153 Component: TComponent,
154 fieldPropKey: TFieldPropKey,
155 ) => LooseInjectedFieldComponent<TComponent, TProps, TFieldPropKey>
157​
158/**
159 * Adds field-value compatibility metadata to components without wrapping them
160 * or changing their runtime props.
161 */
162export interface FieldBrandHelper {
163 /**
164 * Brands a component for fields whose value type exactly matches `TValue`.
165 *
166 * The returned value is the original component at runtime. Unlike
167 * `fieldComponent.strict`, this helper does not inject a field API prop.
168 *
169 * @example
170 * ```tsx
171 * import { getFormHookHelpers } from '@tanstack/react-form'
172 *
173 * function Adornment() {
174 * return <span>Required</span>
175 * }
176 *
177 * const { fieldBrand } = getFormHookHelpers()
178 * const StringAdornment = fieldBrand.strict<string>()(Adornment)
179 * ```
180 *
181 * @typeParam TValue - The exact field value type that exposes the component.
182 * @typeParam TComponent - Library-managed. Do not specify explicitly.
183 */
184 strict: <TValue>() => <TComponent extends AnyFieldComponent>(
185 Component: TComponent,
186 ) => StrictBrandedFieldComponent<TComponent, TValue>
187​
188 /**
189 * Brands a component for fields whose value type is assignable to
190 * `TValue`.
191 *
192 * The returned value is the original component at runtime. Unlike
193 * `fieldComponent.loose`, this helper does not inject a field API prop.
194 *
195 * @example
196 * ```tsx
197 * import { getFormHookHelpers } from '@tanstack/react-form'
198 *
199 * function FieldDescription() {
200 * return <span>Changes are saved automatically.</span>
201 * }
202 *
203 * const { fieldBrand } = getFormHookHelpers()
204 * const Description = fieldBrand.loose<unknown>()(FieldDescription)
205 * ```
206 *
207 * @typeParam TValue - The field value type accepted by the component.
208 * @typeParam TComponent - Library-managed. Do not specify explicitly.
209 */
210 loose: <TValue>() => <TComponent extends AnyFieldComponent>(
211 Component: TComponent,
212 ) => LooseBrandedFieldComponent<TComponent, TValue>
214​
215/**
216 * Helpers for preparing value-compatible field components for registration
217 * with `createFormHook`.
218 *
219 * Use `fieldComponent` when the current field API should be injected into a
220 * component prop. Use `fieldBrand` when the component should retain its
221 * original runtime props.
222 *
223 * @example
224 * ```tsx
225 * import { getFormHookHelpers } from '@tanstack/react-form'
226 *
227 * const { fieldBrand, fieldComponent } = getFormHookHelpers()
228 * ```
229 */
230export interface FormHookHelpers {
231 /** Brands components without wrapping them or injecting a field API prop. */
232 fieldBrand: FieldBrandHelper
233 /** Wraps components and injects the current field API into a selected prop. */
234 fieldComponent: FieldComponentHelper
236​
237/**
238 * Creates helpers that make React field components value-aware for
239 * `createFormHook`.
240 *
241 * `fieldComponent` injects the current App Form field API into a selected prop.
242 * `fieldBrand` only adds compile-time field-value compatibility and returns the
243 * original component at runtime.
244 *
245 * @example
246 * ```tsx
247 * import { createFormHook, getFormHookHelpers } from '@tanstack/react-form'
248 * import type { FieldWithValue } from '@tanstack/react-form'
249 *
250 * function TextInput({ field }: { field: FieldWithValue<string> }) {
251 * return (
252 * <input
253 * value={field.value}
254 * onChange={(event) => field.handleChange(event.target.value)}
255 * />
256 * )
257 * }
258 *
259 * const { fieldComponent } = getFormHookHelpers()
260 * const TextField = fieldComponent.strict(TextInput, 'field')
261 *
262 * export const { useAppForm } = createFormHook({
263 * fieldComponents: { TextField },
264 * formComponents: {},
265 * })
266 * ```
267 */
268export function getFormHookHelpers(): FormHookHelpers {
269 return {
270 fieldComponent: {
271 loose: wrapField as FieldComponentHelper['loose'],
272 strict: wrapField as FieldComponentHelper['strict'],
273 },
274 fieldBrand: {
275 loose: brandComponentFactory as FieldBrandHelper['loose'],
276 strict: brandComponentFactory as FieldBrandHelper['strict'],
277 },
278 }