Open History to see the last commit
1import React, { useState } from 'react'
2import { useStore } from '@tanstack/react-store'
3import { FieldApi, functionalUpdate } from '@tanstack/form-core'
4import { useIsomorphicLayoutEffect } from './useIsomorphicLayoutEffect'
5import type { FunctionComponent } from 'react'
6import type { NodeType, UseFieldOptions } from './types'
7import type { DeepKeys, DeepValue, Validator } from '@tanstack/form-core'
8β
9interface ReactFieldApi<
10 TParentData,
11 TFormValidator extends
12 | Validator<TParentData, unknown>
13 | undefined = undefined,
14> {
15 /**
16 * A pre-bound and type-safe sub-field component using this field as a root.
17 */
18 Field: FieldComponent<TParentData, TFormValidator>
19}
20β
21/**
22 * A type representing a hook for using a field in a form with the given form data type.
23 *
24 * A function that takes an optional object with a `name` property and field options, and returns a `FieldApi` instance for the specified field.
25 */
26export type UseField<
27 TParentData,
28 TFormValidator extends
29 | Validator<TParentData, unknown>
30 | undefined = undefined,
31> = <
32 TName extends DeepKeys<TParentData>,
33 TFieldValidator extends
34 | Validator<DeepValue<TParentData, TName>, unknown>
35 | undefined = undefined,
36 TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
37>(
38 opts: Omit<
39 UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>,
40 'form'
41 >,
42) => FieldApi<TParentData, TName, TFieldValidator, TFormValidator, TData>
43β
44/**
45 * A hook for managing a field in a form.
46 * @param opts An object with field options.
47 *
48 * @returns The `FieldApi` instance for the specified field.
49 */
50export function useField<
51 TParentData,
52 TName extends DeepKeys<TParentData>,
53 TFieldValidator extends
54 | Validator<DeepValue<TParentData, TName>, unknown>
55 | undefined = undefined,
56 TFormValidator extends
57 | Validator<TParentData, unknown>
58 | undefined = undefined,
59 TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
60>(
61 opts: UseFieldOptions<
62 TParentData,
63 TName,
64 TFieldValidator,
65 TFormValidator,
66 TData
67 >,
68) {
69 const [fieldApi] = useState(() => {
70 const api = new FieldApi({
71 ...opts,
72 form: opts.form,
73 name: opts.name,
74 })
75β
76 const extendedApi: typeof api & ReactFieldApi<TParentData, TFormValidator> =
77 api as never
78β
79 extendedApi.Field = Field as never
80β
81 return extendedApi
82 })
83β
84 useIsomorphicLayoutEffect(fieldApi.mount, [fieldApi])
85β
86 /**
87 * fieldApi.update should not have any side effects. Think of it like a `useRef`
88 * that we need to keep updated every render with the most up-to-date information.
89 */
90 useIsomorphicLayoutEffect(() => {
91 fieldApi.update(opts)
92 })
93β
94 useStore(
95 fieldApi.store,
96 opts.mode === 'array'
97 ? (state) => {
98 return [state.meta, Object.keys(state.value ?? []).length]
99 }
100 : undefined,
101 )
102β
103 return fieldApi
104}
105β
106/**
107 * @param children A render function that takes a field API instance and returns a React element.
108 */
109type FieldComponentProps<
110 TParentData,
111 TName extends DeepKeys<TParentData>,
112 TFieldValidator extends
113 | Validator<DeepValue<TParentData, TName>, unknown>
114 | undefined = undefined,
115 TFormValidator extends
116 | Validator<TParentData, unknown>
117 | undefined = undefined,
118 TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
119> = {
120 children: (
121 fieldApi: FieldApi<
122 TParentData,
123 TName,
124 TFieldValidator,
125 TFormValidator,
126 TData
127 >,
128 ) => NodeType
129} & UseFieldOptions<TParentData, TName, TFieldValidator, TFormValidator, TData>
130β
131/**
132 * A type alias representing a field component for a specific form data type.
133 */
134export type FieldComponent<
135 TParentData,
136 TFormValidator extends
137 | Validator<TParentData, unknown>
138 | undefined = undefined,
139> = <
140 TName extends DeepKeys<TParentData>,
141 TFieldValidator extends
142 | Validator<DeepValue<TParentData, TName>, unknown>
143 | undefined = undefined,
144 TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
145>({
146 children,
147 ...fieldOptions
148}: Omit<
149 FieldComponentProps<
150 TParentData,
151 TName,
152 TFieldValidator,
153 TFormValidator,
154 TData
155 >,
156 'form'
157>) => NodeType
158β
159/**
160 * A function component that takes field options and a render function as children and returns a React component.
161 *
162 * The `Field` component uses the `useField` hook internally to manage the field instance.
163 */
164export const Field = (<
165 TParentData,
166 TName extends DeepKeys<TParentData>,
167 TFieldValidator extends
168 | Validator<DeepValue<TParentData, TName>, unknown>
169 | undefined = undefined,
170 TFormValidator extends
171 | Validator<TParentData, unknown>
172 | undefined = undefined,
173 TData extends DeepValue<TParentData, TName> = DeepValue<TParentData, TName>,
174>({
175 children,
176 ...fieldOptions
177}: FieldComponentProps<
178 TParentData,
179 TName,
180 TFieldValidator,
181 TFormValidator,
182 TData
183>): NodeType => {
184 const fieldApi = useField(fieldOptions as any)
185β
186 return (<>{functionalUpdate(children, fieldApi as any)}</>) as never
187}) satisfies FunctionComponent<FieldComponentProps<any, any, any, any, any>>