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

FieldGroupApi.public.ts

191 lines5.1 KB

1import type {
2 DeepKeys,
3 DeepKeysWhereValueIncludes,
4 DeepValue,
5 FieldValidators,
6 FormApiArrayMethods,
7 FormApiFieldMethods,
8 FormErrorTypes,
9 FormState,
10 ValidationIssue,
11} from '@tanstack/form-core'
12import type { FunctionComponent, ReactNode } from 'react'
13import type {
14 ReactFormFieldProps,
15 ReactFormSubscribeProps,
16} from '../ReactForm/Components.public'
17import type { ReactComponentTree } from '../AppForm/componentMap.public'
18import type { ReadonlyAtom } from '@tanstack/react-store'
19​
20export interface FieldGroupFieldComponent<
21 in out TFieldData,
22 in out TFieldComponents extends ReactComponentTree,
23> {
24 /**
25 * Renders a field from this field group.
26 *
27 * The field name is automatically connected to the form section where the
28 * field group is used.
29 *
30 * @example
31 * ```tsx
32 * const passwordFieldGroup = defineFieldGroup(({ strict }) => ({
33 * password: strict<string>(),
34 * confirmPassword: strict<string>(),
35 * }))
36 *
37 * interface PasswordFieldsProps {
38 * fields: typeof passwordFieldGroup.fields
39 * }
40 *
41 * function PasswordFields({ fields }: PasswordFieldsProps) {
42 * return (
43 * <>
44 * <fields.Field name="password">
45 * {(field) => (
46 * <input
47 * type="password"
48 * value={field.value}
49 * onChange={(event) => field.handleChange(event.target.value)}
50 * />
51 * )}
52 * </fields.Field>
53 * <fields.Field name="confirmPassword">
54 * {(field) => (
55 * <input
56 * type="password"
57 * value={field.value}
58 * onChange={(event) => field.handleChange(event.target.value)}
59 * />
60 * )}
61 * </fields.Field>
62 * </>
63 * )
64 * }
65 * ```
66 */
67 <const TFieldName extends DeepKeys<TFieldData>>(
68 props: ReactFormFieldProps<
69 TFieldData,
70 TFieldName,
71 DeepValue<TFieldData, TFieldName>,
72 FieldValidators<
73 TFieldData,
74 TFieldName,
75 DeepValue<TFieldData, TFieldName>
76 >,
77 ValidationIssue,
78 unknown,
79 FormErrorTypes,
80 TFieldComponents
81 >,
82 ): ReactNode
84​
85export interface FieldGroupArrayFieldComponent<
86 in out TFieldData,
87 in out TFieldComponents extends ReactComponentTree,
88> {
89 /**
90 * Renders an array field from this field group.
91 *
92 * The field name is automatically connected to the form section where the
93 * field group is used.
94 *
95 * @example
96 * ```tsx
97 * const contactFieldGroup = defineFieldGroup(({ strict }) => ({
98 * emails: strict<Array<{ value: string }>>(),
99 * }))
100 *
101 * interface ContactFieldsProps {
102 * fields: typeof contactFieldGroup.fields
103 * }
104 *
105 * function ContactFields({ fields }: ContactFieldsProps) {
106 * return (
107 * <fields.ArrayField name="emails">
108 * {(emails) => (
109 * <>
110 * {emails.value.map((_, index) => (
111 * <fields.Field key={index} name={`emails[${index}].value`}>
112 * {(field) => (
113 * <input
114 * value={field.value}
115 * onChange={(event) =>
116 * field.handleChange(event.target.value)
117 * }
118 * />
119 * )}
120 * </fields.Field>
121 * ))}
122 * </>
123 * )}
124 * </fields.ArrayField>
125 * )
126 * }
127 * ```
128 */
129 <const TFieldName extends DeepKeysWhereValueIncludes<TFieldData, Array<any>>>(
130 props: ReactFormFieldProps<
131 TFieldData,
132 TFieldName,
133 DeepValue<TFieldData, TFieldName>,
134 FieldValidators<
135 TFieldData,
136 TFieldName,
137 DeepValue<TFieldData, TFieldName>
138 >,
139 ValidationIssue,
140 unknown,
141 FormErrorTypes,
142 TFieldComponents
143 >,
144 ): ReactNode
146​
147export type FieldGroupSubscribeProps<TSelected> = ReactFormSubscribeProps<
148 unknown,
149 FormErrorTypes,
150 TSelected
152​
153/**
154 * Reads form state from inside a field-group component.
155 *
156 * Because a field group can be used with different forms, `state.values`
157 * cannot be safely typed here and is provided as `unknown`.
158 *
159 * To read values from this field group, use its `atom` with `useSelector`
160 * instead.
161 *
162 * @example
163 * ```tsx
164 * <fields.Subscribe selector={(state) => state.submissionAttempts}>
165 * {(submissionAttempts) => (
166 * <span>Submit attempts: {submissionAttempts}</span>
167 * )}
168 * </fields.Subscribe>
169 * ```
170 */
171export type FieldGroupSubscribeComponent = <const TSelected>(
172 props: FieldGroupSubscribeProps<TSelected>,
173) => ReactNode
174​
175export interface FieldGroupApi<
176 in out TFieldData,
177 in out TFieldComponents extends ReactComponentTree,
179 extends FormApiFieldMethods<TFieldData>, FormApiArrayMethods<TFieldData> {
180 atom: ReadonlyAtom<TFieldData>
181 Field: FieldGroupFieldComponent<TFieldData, TFieldComponents>
182 ArrayField: FieldGroupArrayFieldComponent<TFieldData, TFieldComponents>
183 Subscribe: FieldGroupSubscribeComponent
185​
186export type AnyFieldGroupApi = FieldGroupApi<
187 any,
188 Record<string, FunctionComponent<any>>
190​
191export type FieldGroupFormState = FormState<unknown, FormErrorTypes>