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

fieldState.lib.ts

333 lines9.0 KB

1import { createFormStateProxy } from '../FormApi/formState.lib'
2import { getValidationSourceErrors } from '../validation'
3import type { RootCounterContributionKey } from './RootFieldApi.lib'
4import type { AnyInternalFieldApi } from './FieldApi.lib'
5import type {
6 AnyFieldMeta as AnyPublicFieldMeta,
7 BaseFieldMeta,
8 FieldState as PublicFieldState,
9 SubfieldsMeta,
10} from './FieldApi.public'
11import type {
12 ErrorVisibility,
13 ErrorVisibilityFieldState,
14 ValidationIssue,
15} from '../validation.public'
16import type { ValidationSourceErrorMap } from '../validation'
17import type { Atom, ReadonlyAtom } from '@tanstack/store'
18​
19export type ChildContributionKey =
20 RootCounterContributionKey | 'dirty' | 'error'
21type ChildContributionCounts = Record<ChildContributionKey, number>
22export type ChildContributionStates = Record<ChildContributionKey, boolean>
23​
24export const childContributionKeys: Array<ChildContributionKey> = [
25 'touched',
26 'dirty',
27 'error',
28 'validating',
30​
31interface MetaExtension {
32 /**
33 * Validation errors targeting this field, keyed by stable source instance.
34 *
35 * Derived errors are ordered by field, group, and form scope, then by each
36 * scope's validator pipeline order rather than this map's insertion order.
37 */
38 _validationSourceErrors: ValidationSourceErrorMap | null
39 childContributionCounts: ChildContributionCounts
40 _validationCount: number
41 /**
42 * @private
43 * Used to rerender for ArrayField components
44 */
45 _arrayVersion: number
47​
48export interface InternalBaseFieldMeta extends BaseFieldMeta, MetaExtension {}
49export interface InternalFieldMeta extends AnyPublicFieldMeta, MetaExtension {}
50​
51/**
52 * @private
53 * Used to track the prev meta for a field
54 */
55export interface DerivedMetaMarkers {
56 source: InternalBaseFieldMeta | undefined
57 canDisplayErrors: boolean | undefined
59​
60export interface InternalFieldState extends PublicFieldState<any, any> {
61 meta: InternalFieldMeta
63​
64export interface FieldAtoms {
65 store?: ReadonlyAtom<InternalFieldState>
66 meta?: Atom<InternalBaseFieldMeta>
68​
69export const defaultBaseFieldMeta: BaseFieldMeta = {
70 isTouched: false,
71 isDirty: false,
72 isBlurred: false,
73 isValidating: false,
75​
76export const defaultInternalBaseFieldMeta: InternalBaseFieldMeta = {
77 ...defaultBaseFieldMeta,
78 childContributionCounts: {
79 touched: 0,
80 dirty: 0,
81 error: 0,
82 validating: 0,
83 },
84 _validationCount: 0,
85 _validationSourceErrors: null,
86 _arrayVersion: 0,
88​
89export const defaultFieldMeta: InternalFieldMeta = deriveFromBaseFieldMeta(
90 defaultInternalBaseFieldMeta,
91 undefined,
92 undefined,
94​
95export function getFieldSnapshot(
96 field: AnyInternalFieldApi,
97): InternalFieldState {
98 const value = field._getValue()
99 return {
100 value,
101 meta: deriveFromBaseFieldMeta(
102 field._getBaseMeta(),
103 undefined,
104 field,
105 value,
106 ),
107 }
109​
110export function deriveFromBaseFieldMeta(
111 baseMeta: InternalBaseFieldMeta,
112 previousMeta: InternalFieldMeta | undefined,
113 field: AnyInternalFieldApi | undefined,
114 value?: any,
115 markers?: DerivedMetaMarkers,
116): InternalFieldMeta {
117 const isDefaultValue = field ? field._getIsDefaultValue(value) : true
118 const errorVisibility = getErrorVisibility(field)
119 const canDisplayErrors = shouldDisplayErrors(
120 errorVisibility,
121 field,
122 baseMeta,
123 value,
124 isDefaultValue,
125 )
126 const originalErrors = getErrorsFromBaseMeta(baseMeta, previousMeta)
127 const errors = canDisplayErrors ? originalErrors : []
128 const isSelfTouched = baseMeta.isTouched
129 const isSelfDirty = baseMeta.isDirty
130 const isSelfValid = errors.length === 0
131 const isOriginalSelfValid = originalErrors.length === 0
132 const subfields: SubfieldsMeta = {
133 isEveryValid: baseMeta.childContributionCounts.error === 0,
134 isAnyInvalid: baseMeta.childContributionCounts.error > 0,
135 isEveryPristine: baseMeta.childContributionCounts.dirty === 0,
136 isSomeDirty: baseMeta.childContributionCounts.dirty > 0,
137 isSomeTouched: baseMeta.childContributionCounts.touched > 0,
138 isSomeValidating: baseMeta.childContributionCounts.validating > 0,
139 }
140 const isTouched = isSelfTouched || subfields.isSomeTouched
141 const isDirty = isSelfDirty || subfields.isSomeDirty
142 const isSelfValidating = baseMeta.isValidating
143 const isValidating = isSelfValidating || subfields.isSomeValidating
144 const isValid = isSelfValid && subfields.isEveryValid
145 const isInvalid = !isValid
146 const isOriginalValid = isOriginalSelfValid && subfields.isEveryValid
147​
148 if (
149 previousMeta &&
150 markers &&
151 canReusePreviousMeta({
152 baseMeta,
153 canDisplayErrors,
154 isDefaultValue,
155 markers,
156 originalErrors,
157 previousMeta,
158 })
159 ) {
160 return previousMeta
161 }
162​
163 const result: InternalFieldMeta = {
164 ...baseMeta,
165 isTouched,
166 isSelfTouched,
167 isDirty,
168 isSelfDirty,
169 isInvalid,
170 isSelfValid,
171 isSelfValidating,
172 isDefaultValue,
173 isValidating,
174 errors,
175 original: {
176 errors: originalErrors,
177 isValid: isOriginalValid,
178 isInvalid: !isOriginalValid,
179 },
180 isValid,
181 subfields,
182 isPristine: !isDirty,
183 }
184​
185 if (markers) {
186 markers.source = baseMeta
187 markers.canDisplayErrors = canDisplayErrors
188 }
189​
190 return result
192​
193function canReusePreviousMeta({
194 baseMeta,
195 canDisplayErrors,
196 isDefaultValue,
197 markers,
198 originalErrors,
199 previousMeta,
200}: {
201 baseMeta: InternalBaseFieldMeta
202 canDisplayErrors: boolean
203 isDefaultValue: boolean
204 markers: DerivedMetaMarkers
205 originalErrors: Array<ValidationIssue>
206 previousMeta: InternalFieldMeta
207}): boolean {
208 if (markers.source !== baseMeta) return false
209 if (markers.canDisplayErrors !== canDisplayErrors) return false
210 if (previousMeta.isDefaultValue !== isDefaultValue) return false
211 if (previousMeta.original.errors !== originalErrors) return false
212​
213 return true
215​
216function getErrorVisibility(
217 field: AnyInternalFieldApi | undefined,
218): ErrorVisibility<any, any> | undefined {
219 return field?._errorVisibility ?? field?.form._options.errorVisibility
221​
222function shouldDisplayErrors(
223 errorVisibility: ErrorVisibility<any, any> | undefined,
224 field: AnyInternalFieldApi | undefined,
225 baseMeta: InternalBaseFieldMeta,
226 value?: any,
227 isDefaultValue = true,
228): boolean {
229 if (!field || !errorVisibility) return true
230 const group = field._getFormGroup()
231 const stateOverrides = group?._getScopedFormStateOverrides()
232​
233 return errorVisibility({
234 state: createFormStateProxy(field.form, stateOverrides),
235 fieldState: createErrorVisibilityFieldState(
236 value,
237 baseMeta,
238 isDefaultValue,
239 ),
240 })
242​
243function createErrorVisibilityFieldState(
244 value: any,
245 meta: InternalBaseFieldMeta,
246 isDefaultValue: boolean,
247): ErrorVisibilityFieldState {
248 const isSomeTouched = meta.childContributionCounts.touched > 0
249 const isSomeDirty = meta.childContributionCounts.dirty > 0
250 const isSomeValidating = meta.childContributionCounts.validating > 0
251 const isSelfTouched = meta.isTouched
252 const isSelfDirty = meta.isDirty
253 const isSelfValidating = meta.isValidating
254 const isTouched = isSelfTouched || isSomeTouched
255 const isDirty = isSelfDirty || isSomeDirty
256​
257 return {
258 value,
259 meta: {
260 isTouched,
261 isSelfTouched,
262 isDirty,
263 isSelfDirty,
264 isPristine: !isDirty,
265 isDefaultValue,
266 isBlurred: meta.isBlurred,
267 isValidating: isSelfValidating || isSomeValidating,
268 isSelfValidating,
269 subfields: {
270 isEveryPristine: !isSomeDirty,
271 isSomeDirty,
272 isSomeTouched,
273 isSomeValidating,
274 },
275 },
276 }
278​
279export function getChildContributionStates(
280 meta: InternalBaseFieldMeta,
281): ChildContributionStates {
282 return {
283 touched: meta.isTouched || meta.childContributionCounts.touched > 0,
284 dirty: meta.isDirty || meta.childContributionCounts.dirty > 0,
285 validating:
286 meta.isValidating || meta.childContributionCounts.validating > 0,
287 error:
288 getErrorsFromBaseMeta(meta).length > 0 ||
289 meta.childContributionCounts.error > 0,
290 }
292​
293function hasValidationSourceErrors(
294 errors: ValidationSourceErrorMap | null,
295): boolean {
296 return errors !== null && errors.size > 0
298​
299export function isPrunableMeta(meta: InternalBaseFieldMeta): boolean {
300 if (meta.isTouched) return false
301 if (meta.isDirty) return false
302 if (meta.isBlurred) return false
303 if (meta.isValidating) return false
304 if (meta._validationCount !== 0) return false
305 if (meta._arrayVersion !== 0) return false
306 if (hasValidationSourceErrors(meta._validationSourceErrors)) return false
307​
308 return childContributionKeys.every(
309 (key) => meta.childContributionCounts[key] === 0,
310 )
312​
313function getErrorsFromBaseMeta(
314 baseMeta: InternalBaseFieldMeta,
315 previousMeta?: InternalFieldMeta,
316): Array<ValidationIssue> {
317 let result: Array<ValidationIssue>
318 if (
319 previousMeta?._validationSourceErrors === baseMeta._validationSourceErrors
320 ) {
321 result = previousMeta.original.errors
322 } else {
323 result = getValidationSourceErrors(baseMeta._validationSourceErrors)
324 }
325 return result
327​
328export function hasFieldMetaErrors(meta: InternalBaseFieldMeta): boolean {
329 return (
330 hasValidationSourceErrors(meta._validationSourceErrors) ||
331 meta.childContributionCounts.error > 0
332 )