Open History to see the last commit
1import React from 'react'
2import { expectTypeOf } from 'vitest'
3import {
4 createFormHook,
5 defineFieldGroup,
6 getFormHookHelpers,
7 useForm,
8 useSelector,
9} from '../src'
10import type {
11 FieldGroupApi,
12 FieldGroupFieldBindings,
13 FieldGroupFieldNameForSlot,
14 FieldGroupFieldNames,
15 FieldGroupFieldSlotAllows,
16 FieldGroupFieldSlotModeOf,
17 FieldGroupFieldSlotValue,
18 FieldGroupFieldsOf,
19 FieldGroupForm,
20 FieldGroupFormState,
21 FieldValidators,
22 FieldWithValue,
23} from '../src'
24β
25type BookingFields = {
26 guest: {
27 name: string
28 age: number
29 }
30 emails: Array<{ value: string }>
31 tags: Array<string>
32}
33β
34function TextFieldComponent(props: { field: FieldWithValue<string> }) {
35 void props.field
36 return null
37}
38β
39const { fieldComponent } = getFormHookHelpers()
40const TextField = fieldComponent.strict(TextFieldComponent, 'field')
41β
42type FieldComponents = {
43 TextField: typeof TextField
44}
45β
46declare const fields: FieldGroupApi<BookingFields, FieldComponents>
47declare const form: FieldGroupForm
48const { defineAppFieldGroup } = createFormHook({
49 fieldComponents: {
50 TextField,
51 },
52 formComponents: {},
53})
54const { fields: definedFields, bindComponent: bindDefinedFields } =
55 defineFieldGroup(({ strict }) => ({
56 name: strict<string>(),
57 age: strict<number>(),
58 emails: strict<Array<{ value: string }>>(),
59 }))
60const { fields: looseDefinedFields, bindComponent: bindLooseDefinedFields } =
61 defineFieldGroup(({ loose }) => ({
62 name: loose<string>(),
63 }))
64const { fields: looseNullableNumberFields } = defineFieldGroup(({ loose }) => ({
65 value: loose<number | null>(),
66}))
67const invalidWatchFieldValidators: FieldValidators<
68 BookingFields,
69 'guest.age',
70 number
71> = [
72 {
73 run: () => undefined,
74 triggers: ['change'],
75 // @ts-expect-error watchFields only accepts virtual field paths
76 watchFields: ['unknown'],
77 },
78]
79void invalidWatchFieldValidators
80const { fields: appDefinedFields } = defineAppFieldGroup(({ strict }) => ({
81 name: strict<string>(),
82}))
83const { fields: hookAppDefinedFields } = defineAppFieldGroup(({ strict }) => ({
84 name: strict<string>(),
85}))
86β
87type DefinedFieldsSpec = FieldGroupFieldsOf<typeof definedFields>
88type LooseDefinedFieldsSpec = FieldGroupFieldsOf<typeof looseDefinedFields>
89type LooseNullableNumberFieldsSpec = FieldGroupFieldsOf<
90 typeof looseNullableNumberFields
91>
92declare const stringSlot: DefinedFieldsSpec['name']
93declare const looseStringSlot: LooseDefinedFieldsSpec['name']
94declare const looseNullableNumberSlot: LooseNullableNumberFieldsSpec['value']
95declare const numberSlot: DefinedFieldsSpec['age']
96declare const emailsSlot: DefinedFieldsSpec['emails']
97type FieldNameTestData = {
98 exactString: string
99 literalString: 'literal'
100 stringOrNumber: string | number
101 exactNumber: number
102 nullableNumber: number | null
103 nullOnly: null
104 stringOrNull: string | null
105 nested: {
106 value: 'literal'
107 }
108}
109β
110interface DefinedFieldsProps {
111 fields: typeof definedFields
112 label: string
113}
114β
115interface MismatchedFieldsProps {
116 fields: typeof looseDefinedFields
117}
118β
119interface RenamedDefinedFieldsProps {
120 fieldGroup: typeof definedFields
121}
122β
123type FieldBindingFormData = {
124 user: {
125 name: string
126 age: number
127 emails: Array<{ value: string }>
128 }
129 literalName: 'literal'
130 stringOrNumber: string | number
131 tags: Array<string>
132}
133β
134declare const typedForm: FieldGroupForm<
135 Record<never, never>,
136 FieldBindingFormData
137>
138β
139function DefinedFieldsImpl(props: DefinedFieldsProps) {
140 return (
141 <props.fields.Field name="name">
142 {(field) => {
143 expectTypeOf(field.value).toEqualTypeOf<string>()
144 return props.label
145 }}
146 </props.fields.Field>
147 )
148}
149β
150const WrappedDefinedFields = bindDefinedFields(DefinedFieldsImpl, 'fields')
151β
152function MismatchedFieldsImpl(props: MismatchedFieldsProps) {
153 return <props.fields.Field name="name">{() => null}</props.fields.Field>
154}
155β
156bindDefinedFields(
157 MismatchedFieldsImpl,
158 // @ts-expect-error fieldsPropName must point to the matching field group
159 'fields',
160)
161β
162function RenamedDefinedFieldsImpl(props: RenamedDefinedFieldsProps) {
163 return (
164 <props.fieldGroup.Field name="name">{() => null}</props.fieldGroup.Field>
165 )
166}
167β
168bindDefinedFields(RenamedDefinedFieldsImpl, 'fieldGroup')
169β
170bindDefinedFields(
171 RenamedDefinedFieldsImpl,
172 // @ts-expect-error fieldsPropName must be the prop containing the field group
173 'fields',
174)
175β
176interface LooseDefinedFieldsProps {
177 fields: typeof looseDefinedFields
178}
179β
180function LooseDefinedFieldsImpl(props: LooseDefinedFieldsProps) {
181 return <props.fields.Field name="name">{() => null}</props.fields.Field>
182}
183β
184const WrappedLooseDefinedFields = bindLooseDefinedFields(
185 LooseDefinedFieldsImpl,
186 'fields',
187)
188β
189type DefinedFieldBindings = FieldGroupFieldBindings<
190 FieldGroupFieldsOf<typeof definedFields>,
191 FieldBindingFormData
192>
193type LooseDefinedFieldBindings = FieldGroupFieldBindings<
194 FieldGroupFieldsOf<typeof looseDefinedFields>,
195 FieldBindingFormData
196>
197type LooseNullableNumberBindings = FieldGroupFieldBindings<
198 FieldGroupFieldsOf<typeof looseNullableNumberFields>,
199 FieldNameTestData
200>
201β
202function FieldGroupApiTypes() {
203 const values = useSelector(fields.atom)
204β
205 expectTypeOf(values).toEqualTypeOf<BookingFields>()
206 expectTypeOf(fields.atom.get()).toEqualTypeOf<BookingFields>()
207 expectTypeOf(fields.getFieldValue('guest.name')).toEqualTypeOf<string>()
208 expectTypeOf(fields.getFieldValue('guest.age')).toEqualTypeOf<number>()
209 expectTypeOf(fields.getFieldValue('emails')).toEqualTypeOf<
210 Array<{ value: string }>
211 >()
212β
213 fields.setFieldValue('guest.name', 'Tony')
214 // @ts-expect-error field value must match the virtual field path
215 fields.setFieldValue('guest.name', 42)
216β
217 fields.resetField('guest.age')
218 // @ts-expect-error field methods only accept virtual field paths
219 fields.resetField('unknown')
220β
221 fields.pushFieldValue('tags', 'vip')
222 // @ts-expect-error array element must match the virtual array path
223 fields.pushFieldValue('tags', 1)
224 fields.insertFieldValue('emails', 0, { value: 'a@example.com' })
225 fields.removeFieldValue('emails', 0)
226 fields.replaceFieldValue('emails', 0, { value: 'b@example.com' })
227 // @ts-expect-error replacement must match the virtual array element
228 fields.replaceFieldValue('emails', 0, 'b@example.com')
229 fields.swapFieldValues('emails', 0, 1)
230 fields.moveFieldValue('emails', 0, 1)
231 fields.clearFieldValues('emails')
232 fields.filterFieldValues('emails', (email, index, array) => {
233 expectTypeOf(email).toEqualTypeOf<{ value: string }>()
234 expectTypeOf(index).toEqualTypeOf<number>()
235 expectTypeOf(array).toEqualTypeOf<Array<{ value: string }>>()
236 return email.value.length > 0
237 })
238 // @ts-expect-error array methods only accept array-valued virtual paths
239 fields.pushFieldValue('guest.name', 'Tony')
240β
241 return (
242 <>
243 <fields.Field name="guest.name">
244 {(field) => {
245 expectTypeOf(field.value).toEqualTypeOf<string>()
246 return <field.TextField />
247 }}
248 </fields.Field>
249β
250 <fields.Field name="guest.age">
251 {(field) => {
252 expectTypeOf(field.value).toEqualTypeOf<number>()
253 return (
254 <>
255 {/* @ts-expect-error strict string field component is not available on number fields */}
256 <field.TextField />
257 </>
258 )
259 }}
260 </fields.Field>
261β
262 <fields.Field
263 name="guest.age"
264 validators={[
265 {
266 run: ({ value }) => {
267 expectTypeOf(value).toEqualTypeOf<number>()
268 return undefined
269 },
270 triggers: ['change'],
271 watchFields: ['guest.name'],
272 },
273 ]}
274 >
275 {() => null}
276 </fields.Field>
277β
278 <fields.Field
279 name="guest.age"
280 validators={[
281 {
282 run: () => undefined,
283 triggers: ['change'],
284 // @ts-expect-error watchFields only accepts virtual field paths
285 watchFields: ['unknown'],
286 },
287 ]}
288 >
289 {() => null}
290 </fields.Field>
291β
292 {/* @ts-expect-error Field only accepts virtual field paths */}
293 <fields.Field name="unknown">{() => null}</fields.Field>
294β
295 <fields.ArrayField name="emails">
296 {(field) => {
297 expectTypeOf(field.value).toEqualTypeOf<Array<{ value: string }>>()
298 return null
299 }}
300 </fields.ArrayField>
301β
302 {/* @ts-expect-error ArrayField only accepts array-valued virtual paths */}
303 <fields.ArrayField name="guest.name">{() => null}</fields.ArrayField>
304β
305 <fields.Subscribe
306 selector={(state) => {
307 expectTypeOf(state).toEqualTypeOf<FieldGroupFormState>()
308 expectTypeOf(state.submissionAttempts).toEqualTypeOf<number>()
309 expectTypeOf(state.values).toBeUnknown()
310 return state.submissionAttempts
311 }}
312 >
313 {(submissionAttempts) => {
314 expectTypeOf(submissionAttempts).toEqualTypeOf<number>()
315 return null
316 }}
317 </fields.Subscribe>
318 </>
319 )
320}
321β
322function DefineFieldGroupTypes() {
323 const formWithSubmitReturn = useForm({
324 defaultValues: {
325 user: {
326 name: '',
327 age: 0,
328 emails: [] as Array<{ value: string }>,
329 },
330 literalName: 'literal' as const,
331 stringOrNumber: '',
332 tags: [] as Array<string>,
333 } satisfies FieldBindingFormData,
334 onSubmit: () => 'submitted' as const,
335 })
336 const formWithIdentityBindings = useForm({
337 defaultValues: {
338 name: '',
339 age: 0,
340 emails: [] as Array<{ value: string }>,
341 alternate: {
342 name: '',
343 age: 0,
344 emails: [] as Array<{ value: string }>,
345 },
346 },
347 })
348β
349 expectTypeOf(stringSlot.mode).toEqualTypeOf<'strict'>()
350 expectTypeOf(looseStringSlot.mode).toEqualTypeOf<'loose'>()
351 expectTypeOf<
352 FieldGroupFieldSlotValue<typeof stringSlot>
353 >().toEqualTypeOf<string>()
354 expectTypeOf<
355 FieldGroupFieldSlotModeOf<typeof stringSlot>
356 >().toEqualTypeOf<'strict'>()
357 expectTypeOf<
358 FieldGroupFieldSlotModeOf<typeof looseStringSlot>
359 >().toEqualTypeOf<'loose'>()
360β
361 expectTypeOf<
362 FieldGroupFieldSlotAllows<typeof stringSlot, string>
363 >().toEqualTypeOf<true>()
364 expectTypeOf<
365 FieldGroupFieldSlotAllows<typeof stringSlot, 'literal'>
366 >().toEqualTypeOf<false>()
367 expectTypeOf<
368 FieldGroupFieldSlotAllows<typeof looseStringSlot, 'literal'>
369 >().toEqualTypeOf<true>()
370 expectTypeOf<
371 FieldGroupFieldSlotAllows<typeof looseStringSlot, string | number>
372 >().toEqualTypeOf<false>()
373 expectTypeOf<
374 FieldGroupFieldSlotAllows<typeof looseNullableNumberSlot, null>
375 >().toEqualTypeOf<true>()
376 expectTypeOf<
377 FieldGroupFieldSlotAllows<typeof looseNullableNumberSlot, string | null>
378 >().toEqualTypeOf<false>()
379 expectTypeOf<
380 FieldGroupFieldNameForSlot<FieldNameTestData, typeof stringSlot>
381 >().toEqualTypeOf<'exactString'>()
382 expectTypeOf<
383 FieldGroupFieldNameForSlot<FieldNameTestData, typeof looseStringSlot>
384 >().toEqualTypeOf<'exactString' | 'literalString' | 'nested.value'>()
385 expectTypeOf<
386 FieldGroupFieldNames<
387 FieldNameTestData,
388 {
389 exact: typeof stringSlot
390 loose: typeof looseStringSlot
391 }
392 >
393 >().toEqualTypeOf<{
394 exact: 'exactString'
395 loose: 'exactString' | 'literalString' | 'nested.value'
396 }>()
397 expectTypeOf<DefinedFieldBindings>().toEqualTypeOf<{
398 readonly name:
399 'user.name' | `user.emails[${number}].value` | `tags[${number}]`
400 readonly age: 'user.age'
401 readonly emails: 'user.emails'
402 }>()
403 expectTypeOf<LooseDefinedFieldBindings>().toEqualTypeOf<{
404 readonly name:
405 | 'user.name'
406 | 'literalName'
407 | `user.emails[${number}].value`
408 | `tags[${number}]`
409 }>()
410 expectTypeOf<LooseNullableNumberBindings>().toEqualTypeOf<{
411 readonly value: 'exactNumber' | 'nullableNumber' | 'nullOnly'
412 }>()
413β
414 expectTypeOf(definedFields).toExtend<
415 FieldGroupApi<
416 {
417 name: string
418 age: number
419 emails: Array<{ value: string }>
420 },
421 Record<never, never>
422 >
423 >()
424 expectTypeOf<DefinedFieldsSpec>().toEqualTypeOf<{
425 readonly name: typeof stringSlot
426 readonly age: typeof numberSlot
427 readonly emails: typeof emailsSlot
428 }>()
429 // @ts-expect-error fields exposes the FieldGroupApi shape, not raw spec keys
430 definedFields.name
431β
432 expectTypeOf(definedFields.getFieldValue('name')).toEqualTypeOf<string>()
433 expectTypeOf(definedFields.getFieldValue('age')).toEqualTypeOf<number>()
434 expectTypeOf(definedFields.atom.get()).toEqualTypeOf<{
435 readonly name: string
436 readonly age: number
437 readonly emails: Array<{ value: string }>
438 }>()
439 // @ts-expect-error fields only exposes the defined virtual fields
440 definedFields.getFieldValue('unknown')
441β
442 return (
443 <>
444 <WrappedDefinedFields form={formWithIdentityBindings} label="Identity" />
445β
446 <WrappedDefinedFields
447 form={formWithIdentityBindings}
448 label="Rerouted"
449 fields={{
450 name: 'alternate.name',
451 age: 'alternate.age',
452 emails: 'alternate.emails',
453 }}
454 />
455β
456 <WrappedDefinedFields
457 form={formWithIdentityBindings}
458 label="Incomplete"
459 // @ts-expect-error optional field bindings still need every defined field
460 fields={{ name: 'name' }}
461 />
462β
463 <WrappedDefinedFields
464 form={formWithSubmitReturn}
465 label="User"
466 fields={{
467 name: 'user.name',
468 age: 'user.age',
469 emails: 'user.emails',
470 }}
471 />
472β
473 <WrappedDefinedFields
474 form={form}
475 label="User"
476 fields={{
477 name: 'user.name',
478 age: 'user.age',
479 emails: 'user.emails',
480 }}
481 />
482β
483 <WrappedDefinedFields
484 form={typedForm}
485 label="User"
486 fields={{
487 name: 'user.name',
488 age: 'user.age',
489 emails: 'user.emails',
490 }}
491 />
492β
493 {/* @ts-expect-error non-identity field bindings remain required */}
494 <WrappedDefinedFields form={typedForm} label="User" />
495β
496 <WrappedDefinedFields
497 form={typedForm}
498 label="User"
499 fields={{
500 // @ts-expect-error strict field bindings require exact value types
501 name: 'literalName',
502 age: 'user.age',
503 emails: 'user.emails',
504 }}
505 />
506β
507 <WrappedDefinedFields
508 form={typedForm}
509 label="User"
510 fields={{
511 name: 'user.name',
512 // @ts-expect-error strict field bindings require exact value types
513 age: 'user.name',
514 emails: 'user.emails',
515 }}
516 />
517β
518 <WrappedLooseDefinedFields
519 form={typedForm}
520 fields={{ name: 'literalName' }}
521 />
522β
523 <WrappedLooseDefinedFields
524 form={typedForm}
525 fields={{
526 // @ts-expect-error loose field bindings reject wider value types
527 name: 'stringOrNumber',
528 }}
529 />
530β
531 <WrappedLooseDefinedFields
532 form={typedForm}
533 fields={{
534 // @ts-expect-error loose field bindings require assignable value types
535 name: 'user.age',
536 }}
537 />
538β
539 <WrappedDefinedFields
540 form={form}
541 label="User"
542 // @ts-expect-error wrapped component fields prop needs every defined field binding
543 fields={{ name: 'user.name' }}
544 />
545β
546 {/* @ts-expect-error wrapped component receives field bindings, not the internal field group API */}
547 <WrappedDefinedFields form={form} label="User" fields={definedFields} />
548β
549 {/* @ts-expect-error wrapped component requires a form prop */}
550 <WrappedDefinedFields label="User" fields={undefined as never} />
551β
552 <definedFields.Field name="name">
553 {(field) => {
554 expectTypeOf(field.value).toEqualTypeOf<string>()
555 return null
556 }}
557 </definedFields.Field>
558β
559 {/* @ts-expect-error Field only accepts keys from the defined fields */}
560 <definedFields.Field name="unknown">{() => null}</definedFields.Field>
561β
562 <appDefinedFields.Field name="name">
563 {(field) => {
564 expectTypeOf(field.value).toEqualTypeOf<string>()
565 return <field.TextField />
566 }}
567 </appDefinedFields.Field>
568β
569 <hookAppDefinedFields.Field name="name">
570 {(field) => {
571 expectTypeOf(field.value).toEqualTypeOf<string>()
572 return <field.TextField />
573 }}
574 </hookAppDefinedFields.Field>
575 </>
576 )
577}
578β
579void FieldGroupApiTypes
580void DefineFieldGroupTypes