Open History to see the last commit
1import { afterEach, describe, expect, it, vi } from 'vitest'
2import { InternalFormApi } from '../../src/FormApi/FormApi.lib'
3import { InternalFormGroupApi } from '../../src/FormGroupApi/FormGroupApi.lib'
4import { defaultFieldMeta } from '../../src/FieldApi/fieldState.lib'
5import { reconcileValidatorInstances } from '../../src/ValidatorInstance.lib'
6import type { AnyInternalFieldApi } from '../../src/FieldApi/FieldApi.lib'
7import type { ValidationIssue } from '../../src/validation.public'
8import type { ValidationSourceErrorMap } from '../../src/validation'
9β
10function setFieldValidatorErrors(
11 field: AnyInternalFieldApi,
12 errors: Array<ValidationIssue>,
13): void {
14 field._validatorInstances ??= reconcileValidatorInstances({
15 definitions: [{ run: () => null, triggers: [] }],
16 instances: null,
17 owner: field,
18 scope: 'field',
19 })
20 const validatorInstance = field._validatorInstances![0]!
21β
22 field._setMeta((prev) => ({
23 ...prev,
24 _validationSourceErrors:
25 errors.length > 0
26 ? new Map([[validatorInstance, { errors, sourceEvent: 'test' }]])
27 : null,
28 }))
29}
30β
31describe('field - meta', () => {
32 afterEach(() => {
33 vi.useRealTimers()
34 })
35β
36 describe('field meta derived properties', () => {
37 it('orders validator errors by scope and pipeline index', () => {
38 const form = new InternalFormApi({
39 defaultValues: { profile: { name: '' } },
40 validators: [
41 { run: () => null, triggers: [] },
42 { run: () => null, triggers: [] },
43 ],
44 })
45 const group = new InternalFormGroupApi({
46 form,
47 name: 'profile',
48 validators: [
49 { run: () => null, triggers: [] },
50 { run: () => null, triggers: [] },
51 ],
52 })
53 const field = form._getOrCreateFieldApi({
54 name: 'profile.name',
55 validators: [
56 { run: () => null, triggers: [] },
57 { run: () => null, triggers: [] },
58 ],
59 })
60 const [fieldFirst, fieldSecond] = field._validatorInstances!
61 const [groupFirst, groupSecond] = group._validatorInstances!
62 const [formFirst, formSecond] = form._validatorInstances!
63β
64 const validationSourceErrors: ValidationSourceErrorMap = new Map()
65 // Deliberately reverse both scope and pipeline insertion order.
66 validationSourceErrors.set(form._onSubmitSource, {
67 errors: [{ message: 'onSubmit' }],
68 sourceEvent: 'submit',
69 })
70 validationSourceErrors.set(formSecond!, {
71 errors: [{ message: 'form 1' }],
72 sourceEvent: '',
73 })
74 validationSourceErrors.set(formFirst!, {
75 errors: [{ message: 'form 0' }],
76 sourceEvent: '',
77 })
78 validationSourceErrors.set(groupSecond!, {
79 errors: [{ message: 'group 1' }],
80 sourceEvent: '',
81 })
82 validationSourceErrors.set(groupFirst!, {
83 errors: [{ message: 'group 0' }],
84 sourceEvent: '',
85 })
86 validationSourceErrors.set(fieldSecond!, {
87 errors: [{ message: 'field 1' }],
88 sourceEvent: '',
89 })
90 validationSourceErrors.set(fieldFirst!, {
91 errors: [{ message: 'field 0' }],
92 sourceEvent: '',
93 })
94β
95 field._setMeta((prev) => ({
96 ...prev,
97 _validationSourceErrors: validationSourceErrors,
98 }))
99β
100 expect(field.meta.original.errors.map((error) => error.message)).toEqual([
101 'field 0',
102 'field 1',
103 'group 0',
104 'group 1',
105 'form 0',
106 'form 1',
107 'onSubmit',
108 ])
109β
110 group._cleanup()
111 })
112β
113 it('starts with defaultFieldMeta values', () => {
114 const form = new InternalFormApi({ defaultValues: { x: '' } })
115 const field = form._getOrCreateFieldApi({ name: 'x' })
116 expect(field.meta).toMatchObject(defaultFieldMeta)
117 })
118β
119 it('isPristine becomes false after a change', () => {
120 const form = new InternalFormApi({ defaultValues: { x: '' } })
121 const field = form._getOrCreateFieldApi({ name: 'x' })
122 field.handleChange('new')
123 expect(field.meta.isPristine).toBe(false)
124 })
125β
126 it('isValid is true and isInvalid is false when there are no errors', () => {
127 const form = new InternalFormApi({ defaultValues: { x: '' } })
128 const field = form._getOrCreateFieldApi({ name: 'x' })
129 expect(field.meta.isValid).toBe(true)
130 expect(field.meta.isInvalid).toBe(false)
131 expect(field.meta.isSelfValid).toBe(true)
132 expect(field.meta.subfields.isEveryValid).toBe(true)
133 expect(field.meta.subfields.isAnyInvalid).toBe(false)
134 })
135β
136 it('isDirty is false when self and subfields are pristine', () => {
137 const form = new InternalFormApi({ defaultValues: { x: '' } })
138 const field = form._getOrCreateFieldApi({ name: 'x' })
139 expect(field.meta.isDirty).toBe(false)
140 expect(field.meta.isSelfDirty).toBe(false)
141 expect(field.meta.subfields.isSomeDirty).toBe(false)
142 expect(field.meta.subfields.isEveryPristine).toBe(true)
143 expect(field.meta.isPristine).toBe(true)
144 })
145β
146 it('isTouched is false when self and subfields are untouched', () => {
147 const form = new InternalFormApi({ defaultValues: { x: '' } })
148 const field = form._getOrCreateFieldApi({ name: 'x' })
149 expect(field.meta.isTouched).toBe(false)
150 expect(field.meta.isSelfTouched).toBe(false)
151 expect(field.meta.subfields.isSomeTouched).toBe(false)
152 })
153β
154 it('tracks self validation state while a field validator is pending', async () => {
155 vi.useFakeTimers()
156 const form = new InternalFormApi({ defaultValues: { x: '' } })
157 const field = form._getOrCreateFieldApi({
158 name: 'x',
159 validators: [
160 {
161 triggers: ['change'],
162 run: async () => {
163 await new Promise((resolve) => setTimeout(resolve, 100))
164 return null
165 },
166 },
167 ],
168 })
169β
170 const validationPromise = field._runFieldValidation('change')
171β
172 expect(field.meta.isValidating).toBe(true)
173 expect(field.meta.isSelfValidating).toBe(true)
174 expect(field.meta.subfields.isSomeValidating).toBe(false)
175β
176 await vi.runAllTimersAsync()
177 await validationPromise
178β
179 expect(field.meta.isValidating).toBe(false)
180 expect(field.meta.isSelfValidating).toBe(false)
181 vi.useRealTimers()
182 })
183β
184 it('aggregates validation state from subfields', async () => {
185 vi.useFakeTimers()
186 const form = new InternalFormApi({ defaultValues: { a: { b: '' } } })
187 const parent = form._getOrCreateFieldApi({ name: 'a' })
188 const child = form._getOrCreateFieldApi({
189 name: 'a.b',
190 validators: [
191 {
192 triggers: ['change'],
193 run: async () => {
194 await new Promise((resolve) => setTimeout(resolve, 100))
195 return null
196 },
197 },
198 ],
199 })
200β
201 const validationPromise = child._runFieldValidation('change')
202β
203 vi.waitFor(() => {
204 expect(child.meta.isValidating).toBe(true)
205 expect(parent.meta.isValidating).toBe(true)
206 expect(parent.meta.isSelfValidating).toBe(false)
207 expect(parent.meta.subfields.isSomeValidating).toBe(true)
208 })
209β
210 await vi.runAllTimersAsync()
211 await validationPromise
212β
213 expect(parent.meta.isValidating).toBe(false)
214 expect(parent.meta.subfields.isSomeValidating).toBe(false)
215 vi.useRealTimers()
216 })
217β
218 it('separates self validity from subfield validity', () => {
219 const form = new InternalFormApi({ defaultValues: { a: { b: '' } } })
220 const parent = form._getOrCreateFieldApi({ name: 'a' })
221 const child = form._getOrCreateFieldApi({ name: 'a.b' })
222β
223 setFieldValidatorErrors(child, [{ message: 'Required' }])
224β
225 vi.waitFor(() => {
226 expect(child.meta.isSelfValid).toBe(false)
227 expect(child.meta.subfields.isEveryValid).toBe(true)
228 expect(child.meta.subfields.isAnyInvalid).toBe(false)
229 expect(child.meta.isValid).toBe(false)
230β
231 expect(parent.meta.isSelfValid).toBe(true)
232 expect(parent.meta.subfields.isEveryValid).toBe(false)
233 expect(parent.meta.subfields.isAnyInvalid).toBe(true)
234 expect(parent.meta.isValid).toBe(false)
235 expect(parent.meta.isInvalid).toBe(true)
236 })
237 })
238β
239 it('updates child error contribution counts when only error state changes', () => {
240 const form = new InternalFormApi({ defaultValues: { a: { b: '' } } })
241 const parent = form._getOrCreateFieldApi({ name: 'a' })
242 const child = form._getOrCreateFieldApi({ name: 'a.b' })
243β
244 setFieldValidatorErrors(child, [{ message: 'Required' }])
245β
246 expect(parent._getBaseMeta().childContributionCounts.error).toBe(1)
247β
248 setFieldValidatorErrors(child, [])
249β
250 expect(parent._getBaseMeta().childContributionCounts.error).toBe(0)
251 })
252β
253 it('keeps aggregate validity invalid when self and subfields both have errors', () => {
254 const form = new InternalFormApi({ defaultValues: { a: { b: '' } } })
255 const parent = form._getOrCreateFieldApi({ name: 'a' })
256 const child = form._getOrCreateFieldApi({ name: 'a.b' })
257β
258 setFieldValidatorErrors(parent, [{ message: 'Parent error' }])
259 setFieldValidatorErrors(child, [{ message: 'Child error' }])
260β
261 vi.waitFor(() => {
262 expect(parent.meta.isSelfValid).toBe(false)
263 expect(parent.meta.subfields.isEveryValid).toBe(false)
264 expect(parent.meta.subfields.isAnyInvalid).toBe(true)
265 expect(parent.meta.isValid).toBe(false)
266 expect(parent.meta.isInvalid).toBe(true)
267 })
268 })
269 })
270β
271 describe('dirty/touched propagation', () => {
272 it('marks parent fields as dirty when a child changes', () => {
273 const form = new InternalFormApi({ defaultValues: { a: { b: '' } } })
274 const parent = form._getOrCreateFieldApi({ name: 'a' })
275 const child = form._getOrCreateFieldApi({ name: 'a.b' })
276 child.handleChange('new')
277 expect(parent.meta.isDirty).toBe(true)
278 expect(parent.meta.isSelfDirty).toBe(false)
279 expect(parent.meta.subfields.isSomeDirty).toBe(true)
280 expect(parent.meta.subfields.isEveryPristine).toBe(false)
281 expect(child.meta.isDirty).toBe(true)
282 expect(child.meta.isSelfDirty).toBe(true)
283 expect(child.meta.subfields.isSomeDirty).toBe(false)
284 expect(child.meta.subfields.isEveryPristine).toBe(true)
285 })
286β
287 it('keeps self and subfield dirtiness separate when both are dirty', () => {
288 const form = new InternalFormApi({ defaultValues: { a: { b: '' } } })
289 const parent = form._getOrCreateFieldApi({ name: 'a' })
290 const child = form._getOrCreateFieldApi({ name: 'a.b' })
291β
292 parent.handleChange({ b: 'parent' })
293 child.handleChange('child')
294β
295 expect(parent.meta.isSelfDirty).toBe(true)
296 expect(parent.meta.subfields.isSomeDirty).toBe(true)
297 expect(parent.meta.isDirty).toBe(true)
298 expect(parent.meta.isPristine).toBe(false)
299 })
300β
301 it('marks parent fields as touched when a child changes', () => {
302 const form = new InternalFormApi({ defaultValues: { a: { b: '' } } })
303 const parent = form._getOrCreateFieldApi({ name: 'a' })
304 const child = form._getOrCreateFieldApi({ name: 'a.b' })
305 child.handleChange('new')
306 expect(parent.meta.isTouched).toBe(true)
307 expect(parent.meta.isSelfTouched).toBe(false)
308 expect(parent.meta.subfields.isSomeTouched).toBe(true)
309 expect(child.meta.isTouched).toBe(true)
310 expect(child.meta.isSelfTouched).toBe(true)
311 expect(child.meta.subfields.isSomeTouched).toBe(false)
312 })
313β
314 it('keeps self and subfield touched state separate when both are touched', () => {
315 const form = new InternalFormApi({ defaultValues: { a: { b: '' } } })
316 const parent = form._getOrCreateFieldApi({ name: 'a' })
317 const child = form._getOrCreateFieldApi({ name: 'a.b' })
318β
319 parent.handleBlur()
320 child.handleBlur()
321β
322 expect(parent.meta.isSelfTouched).toBe(true)
323 expect(parent.meta.subfields.isSomeTouched).toBe(true)
324 expect(parent.meta.isTouched).toBe(true)
325 })
326β
327 it('does not mark parent as dirty when markAsDirty is false', () => {
328 const form = new InternalFormApi({ defaultValues: { a: { b: '' } } })
329 const parent = form._getOrCreateFieldApi({ name: 'a' })
330 const child = form._getOrCreateFieldApi({ name: 'a.b' })
331 child.handleChange('new', { markAsDirty: false })
332 expect(parent.meta.isDirty).toBe(false)
333 })
334β
335 it('propagates dirtiness through multiple levels', () => {
336 const form = new InternalFormApi({
337 defaultValues: { a: { b: { c: '' } } },
338 })
339 const grandparent = form._getOrCreateFieldApi({ name: 'a' })
340 const parent = form._getOrCreateFieldApi({ name: 'a.b' })
341 const child = form._getOrCreateFieldApi({ name: 'a.b.c' })
342 child.handleChange('new')
343 // This needs waitFor? Why? Why is this a race condition?
344 vi.waitFor(() => {
345 expect(parent.meta.isDirty).toBe(true)
346 expect(grandparent.meta.isDirty).toBe(true)
347 })
348 })
349 })
350β
351 describe('Field Meta', () => {
352 it('returns default meta for nested fields', () => {
353 const form = new InternalFormApi({
354 defaultValues: { foo: { bar: '' } },
355 })
356 const field = form._getOrCreateFieldApi({ name: 'foo.bar' })
357 expect(field.meta).toEqual(defaultFieldMeta)
358 })
359β
360 it('updates meta via handleChange', () => {
361 const form = new InternalFormApi({
362 defaultValues: { foo: '' },
363 })
364 const field = form._getOrCreateFieldApi({ name: 'foo' })
365 expect(field.meta.isDirty).toBe(false)
366 expect(field.meta.isTouched).toBe(false)
367β
368 field.handleChange('bar')
369β
370 expect(field.meta.isDirty).toBe(true)
371 expect(field.meta.isTouched).toBe(true)
372 expect(field.meta.isPristine).toBe(false)
373 })
374β
375 it('computes isPristine from isDirty', () => {
376 const form = new InternalFormApi({
377 defaultValues: { foo: '' },
378 })
379 const field = form._getOrCreateFieldApi({ name: 'foo' })
380β
381 expect(field.meta.isPristine).toBe(true)
382 expect(field.meta.isDirty).toBe(false)
383β
384 field.handleChange('bar')
385β
386 expect(field.meta.isPristine).toBe(false)
387 expect(field.meta.isDirty).toBe(true)
388 })
389β
390 it('updates meta for array fields when using pushValue', () => {
391 const form = new InternalFormApi({
392 defaultValues: { arr: ['a'] },
393 })
394 const field = form._getOrCreateFieldApi({ name: 'arr' })
395β
396 expect(field.meta.isDirty).toBe(false)
397β
398 field.pushValue('b')
399β
400 expect(field.meta.isDirty).toBe(true)
401 expect(field.meta.isTouched).toBe(true)
402 })
403β
404 it('updates meta for array fields when using insertValue', () => {
405 const form = new InternalFormApi({
406 defaultValues: { arr: ['a', 'b'] },
407 })
408 const field = form._getOrCreateFieldApi({ name: 'arr' })
409β
410 expect(field.meta.isDirty).toBe(false)
411β
412 field.insertValue(1, 'x')
413β
414 expect(field.meta.isDirty).toBe(true)
415 expect(field.meta.isTouched).toBe(true)
416 })
417β
418 it('updates meta for array fields when using swapValues', () => {
419 const form = new InternalFormApi({
420 defaultValues: { arr: ['a', 'b'] },
421 })
422 const field = form._getOrCreateFieldApi({ name: 'arr' })
423β
424 expect(field.meta.isDirty).toBe(false)
425β
426 field.swapValues(0, 1)
427β
428 expect(field.meta.isDirty).toBe(true)
429 expect(field.meta.isTouched).toBe(true)
430 })
431β
432 it('updates meta for array fields when using moveValue', () => {
433 const form = new InternalFormApi({
434 defaultValues: { arr: ['a', 'b', 'c'] },
435 })
436 const field = form._getOrCreateFieldApi({ name: 'arr' })
437β
438 expect(field.meta.isDirty).toBe(false)
439β
440 field.moveValue(0, 2)
441β
442 expect(field.meta.isDirty).toBe(true)
443 expect(field.meta.isTouched).toBe(true)
444 })
445 })
446})