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

defaultOptions.public.ts

139 lines4.5 KB

1import type { FieldApiOptions } from './FieldApi/FieldApi.public'
2import type { FormOptions } from './FormApi/FormApi.public'
3import type { FormGroupOptions } from './FormGroupApi/FormGroupApi.public'
4import type {
5 FieldValidators,
6 FormErrorTypes,
7 FormGroupValidators,
8 FormValidators,
9} from './validation.public'
10​
11/**
12 * Determines how a supplied usage-site listener array combines with default
13 * listeners.
14 *
15 * `'append'` runs default listeners before usage-site listeners. `'prepend'`
16 * runs usage-site listeners first. `'replace'` uses only the usage-site
17 * listeners. Omitting the usage-site property keeps the defaults, while
18 * explicitly setting it to `undefined` suppresses them.
19 */
20export type DefaultListenersMergeMode = 'replace' | 'append' | 'prepend'
21​
22interface DefaultListenersMergeOptions {
23 /**
24 * Controls how usage-site listeners combine with default listeners.
25 *
26 * - `'replace'`: Usage-site listeners replace default listeners.
27 * - `'append'`: Usage-site listeners run after default listeners.
28 * - `'prepend'`: Usage-site listeners run before default listeners.
29 *
30 * Omitting `listeners` keeps the defaults. Explicitly setting `listeners` to
31 * `undefined` suppresses them for every merge mode.
32 *
33 * @default 'replace'
34 */
35 listenersMerge?: DefaultListenersMergeMode
37​
38/**
39 * Reusable form behavior that does not participate in form value inference.
40 *
41 * Only `errorVisibility`, `listeners`, `onSubmitInvalid`, and `listenersMerge`
42 * can be shared this way. Callback values are typed as `unknown`, so behavior
43 * that depends on the inferred form value should remain in the usage-site form
44 * options. Usage-site properties override defaults even when explicitly set
45 * to `undefined`; a supplied listener array instead follows `listenersMerge`.
46 *
47 * @example
48 * ```ts
49 * const formDefaults: DefaultFormOptions = {
50 * errorVisibility: ({ fieldState }) => fieldState.meta.isBlurred,
51 * listenersMerge: 'append',
52 * onSubmitInvalid: () => {
53 * document.querySelector<HTMLElement>('[aria-invalid="true"]')?.focus()
54 * },
55 * }
56 * ```
57 */
58export type DefaultFormOptions = Pick<
59 FormOptions<unknown, FormValidators<unknown>, unknown, unknown>,
60 'errorVisibility' | 'listeners' | 'onSubmitInvalid'
61> &
62 DefaultListenersMergeOptions
63​
64/**
65 * Reusable field behavior that does not participate in form or field value
66 * inference.
67 *
68 * Only `errorVisibility`, `errorBoundary`, `listeners`, and `listenersMerge`
69 * can be shared this way. Listener values and APIs are typed with `unknown`
70 * values, so value-dependent behavior should remain in the usage-site field
71 * options. Usage-site properties override defaults even when explicitly set
72 * to `undefined`; a supplied listener array instead follows `listenersMerge`.
73 *
74 * @example
75 * ```ts
76 * const fieldDefaults: DefaultFieldOptions = {
77 * errorVisibility: ({ fieldState }) => fieldState.meta.isBlurred,
78 * errorBoundary: true,
79 * }
80 * ```
81 */
82export type DefaultFieldOptions = Pick<
83 FieldApiOptions<
84 unknown,
85 string,
86 unknown,
87 FieldValidators<unknown, string, unknown>,
88 never,
89 unknown,
90 FormErrorTypes
91 >,
92 'errorVisibility' | 'errorBoundary' | 'listeners'
93> &
94 DefaultListenersMergeOptions
95​
96/**
97 * Reusable form-group behavior that does not participate in group value
98 * inference.
99 *
100 * Only `onSubmitInvalid` can be shared this way. Its callback receives
101 * `unknown` form and group values, so value-dependent behavior should remain
102 * in the usage-site form-group options. A usage-site `onSubmitInvalid`
103 * property overrides the default even when explicitly set to `undefined`.
104 *
105 * @example
106 * ```ts
107 * const formGroupDefaults: DefaultFormGroupOptions = {
108 * onSubmitInvalid: ({ groupApi }) => {
109 * console.error('Invalid group', groupApi.name)
110 * },
111 * }
112 * ```
113 */
114export type DefaultFormGroupOptions = Pick<
115 FormGroupOptions<
116 unknown,
117 string,
118 unknown,
119 FormGroupValidators<unknown>,
120 FormErrorTypes
121 >,
122 'onSubmitInvalid'
124​
125/**
126 * Collects the reusable defaults owned by one form.
127 *
128 * Each API resolves its usage-site options against the corresponding entry.
129 * The defaults remain form-wide configuration rather than becoming part of
130 * form, field, or group value inference.
131 */
132export interface DefaultOptions {
133 /** Defaults resolved against form options. */
134 form?: DefaultFormOptions
135 /** Defaults resolved against field options. */
136 field?: DefaultFieldOptions
137 /** Defaults resolved against form-group options. */
138 formGroup?: DefaultFormGroupOptions