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