Open History to see the last commit
1import { visitAllFormFields } from '@tanstack/form-core/internals'
2import { formDevtoolsEventClient } from '../../eventClient.lib'
3import { compareFieldPaths } from '../utils'
4import { createDelayedActivationController } from './delayedActivation'
5import type {
6 AnyInternalFieldApi,
7 AnyInternalFormApi,
8} from '@tanstack/form-core/internals'
9import type {
10 DevtoolsMountedFieldPatch,
11 DevtoolsMountedFieldScaffold,
12 DevtoolsMountedFieldSummaryPatch,
13} from '../../eventClientTypes'
14import type { FieldId, FormId } from '../../types/branded'
15import type { MountedFormsController } from '../forms/mountedForms'
16import type { FieldIdentityController } from './identity'
17import {
18 diffBaselinePatches,
19 toDevtoolsMountedFieldSummaryPatch,
20} from '@/fieldSummaryMeta'
21β
22const FIELD_LIST_LONG_VALIDATION_DELAY_MS = 300
23β
24interface FieldListController {
25 dispose: () => void
26 fieldMounted: (field: AnyInternalFieldApi) => void
27 fieldMoved: (field: AnyInternalFieldApi, previousPath: string) => void
28 fieldUpdated: (field: AnyInternalFieldApi) => void
29 fieldSubtreeRemoved: (
30 form: AnyInternalFormApi,
31 fields: Array<AnyInternalFieldApi>,
32 ) => void
33 fieldUnmounted: (field: AnyInternalFieldApi, previousPath: string) => void
34 formMounted: (form: AnyInternalFormApi) => void
35 formUnmounted: (formInstanceId: FormId) => void
36 getFieldRowsSnapshot: (
37 form: AnyInternalFormApi,
38 ) => Array<DevtoolsMountedFieldScaffold>
39}
40β
41type PendingStructure = 'upsert' | 'remove'
42β
43interface PendingFieldChange {
44 fieldId: FieldId
45 field: AnyInternalFieldApi
46 structure?: PendingStructure
47 summary: boolean
48}
49β
50interface PendingFormChanges {
51 form: AnyInternalFormApi
52 fields: Map<FieldId, PendingFieldChange>
53}
54β
55interface FieldRowsSnapshotOptions {
56 getSummary?: (
57 field: AnyInternalFieldApi,
58 ) => DevtoolsMountedFieldSummaryPatch | undefined
59 onSummary?: (
60 field: AnyInternalFieldApi,
61 summary: DevtoolsMountedFieldSummaryPatch | undefined,
62 ) => void
63}
64β
65function isFormGroupField(field: AnyInternalFieldApi): boolean {
66 return field._formGroup !== null
67}
68β
69export function getFieldRowsSnapshot(
70 form: AnyInternalFormApi,
71 identity: Pick<FieldIdentityController, 'getFieldId'>,
72 {
73 getSummary = (field) =>
74 toDevtoolsMountedFieldSummaryPatch(field.state.meta),
75 onSummary,
76 }: FieldRowsSnapshotOptions = {},
77): Array<DevtoolsMountedFieldScaffold> {
78 const fields: Array<DevtoolsMountedFieldScaffold> = []
79β
80 visitAllFormFields(form._fieldRootNode, (field) => {
81 if (field._isKilled || isFormGroupField(field)) return
82β
83 const summary = getSummary(field)
84 onSummary?.(field, summary)
85β
86 fields.push({
87 fieldId: identity.getFieldId(field),
88 path: field.name,
89 ...(field._isMounted ? {} : { isMounted: false }),
90 ...(summary ? { summary } : {}),
91 })
92 })
93β
94 return fields.sort((left, right) => compareFieldPaths(left.path, right.path))
95}
96β
97export function createFieldListController({
98 identity,
99 mountedForms,
100}: {
101 identity: FieldIdentityController
102 mountedForms: MountedFormsController
103}): FieldListController {
104 const subscribedFormIds = new Set<FormId>()
105 const sparseSummaryByField = new WeakMap<
106 AnyInternalFieldApi,
107 DevtoolsMountedFieldSummaryPatch
108 >()
109 const mountedStateByField = new WeakMap<AnyInternalFieldApi, boolean>()
110 const pendingChanges = new Map<FormId, PendingFormChanges>()
111 let flushScheduled = false
112 let disposed = false
113β
114 const isFieldListSubscribed = (field: AnyInternalFieldApi): boolean => {
115 if (!mountedForms.isMounted(field.form)) return false
116 return subscribedFormIds.has(mountedForms.getFormInstanceId(field.form))
117 }
118β
119 const longValidation = createDelayedActivationController({
120 delayMs: FIELD_LIST_LONG_VALIDATION_DELAY_MS,
121 canActivate: (field: AnyInternalFieldApi) =>
122 !disposed &&
123 field._isMounted &&
124 !field._isKilled &&
125 field.state.meta.isValidating &&
126 isFieldListSubscribed(field),
127 onChange: (field: AnyInternalFieldApi) => queueFieldChange(field),
128 })
129β
130 const observeLongValidation = (field: AnyInternalFieldApi): void => {
131 if (!field._isMounted || field._isKilled || !isFieldListSubscribed(field)) {
132 longValidation.remove(field)
133 return
134 }
135β
136 longValidation.observe(field, field.state.meta.isValidating)
137 }
138β
139 const getProjectedSummary = (
140 field: AnyInternalFieldApi,
141 ): DevtoolsMountedFieldSummaryPatch | undefined =>
142 toDevtoolsMountedFieldSummaryPatch(field.state.meta, {
143 isLongValidating: longValidation.isActive(field),
144 })
145β
146 const getObservedSummary = (
147 field: AnyInternalFieldApi,
148 ): DevtoolsMountedFieldSummaryPatch | undefined => {
149 observeLongValidation(field)
150 return getProjectedSummary(field)
151 }
152β
153 const cacheSummary = (
154 field: AnyInternalFieldApi,
155 summary: DevtoolsMountedFieldSummaryPatch | undefined,
156 ): void => {
157 if (summary) sparseSummaryByField.set(field, summary)
158 else sparseSummaryByField.delete(field)
159 }
160β
161 const createSnapshot = (
162 form: AnyInternalFormApi,
163 ): Array<DevtoolsMountedFieldScaffold> =>
164 getFieldRowsSnapshot(form, identity, {
165 getSummary: getObservedSummary,
166 onSummary: (field, summary) => {
167 cacheSummary(field, summary)
168 mountedStateByField.set(field, field._isMounted)
169 },
170 })
171β
172 const emitSnapshot = (
173 formInstanceId: FormId,
174 form: AnyInternalFormApi | null | undefined = mountedForms.getMountedForm(
175 formInstanceId,
176 ),
177 ): void => {
178 pendingChanges.delete(formInstanceId)
179 formDevtoolsEventClient.emit('field-list-snapshot', {
180 formInstanceId,
181 fields: form ? createSnapshot(form) : [],
182 })
183 }
184β
185 const emitSubscribedSnapshot = (form: AnyInternalFormApi): void => {
186 if (!mountedForms.isMounted(form)) return
187β
188 const formInstanceId = mountedForms.getFormInstanceId(form)
189 if (!subscribedFormIds.has(formInstanceId)) return
190β
191 emitSnapshot(formInstanceId, form)
192 }
193β
194 const flushPendingChanges = (): void => {
195 flushScheduled = false
196 if (disposed) return
197β
198 const batches = Array.from(pendingChanges.entries())
199 pendingChanges.clear()
200β
201 for (const [formInstanceId, batch] of batches) {
202 if (
203 !subscribedFormIds.has(formInstanceId) ||
204 !mountedForms.isMounted(batch.form)
205 ) {
206 continue
207 }
208β
209 const upsert: Array<DevtoolsMountedFieldPatch> = []
210 const remove: Array<FieldId> = []
211β
212 for (const change of batch.fields.values()) {
213 const wasIncluded = mountedStateByField.has(change.field)
214 const previousMounted = mountedStateByField.get(change.field)
215 const shouldRemove =
216 change.structure === 'remove' ||
217 change.field._isKilled ||
218 isFormGroupField(change.field)
219β
220 if (shouldRemove) {
221 sparseSummaryByField.delete(change.field)
222 mountedStateByField.delete(change.field)
223 if (wasIncluded) remove.push(change.fieldId)
224 continue
225 }
226β
227 const previousSummary = sparseSummaryByField.get(change.field)
228 const currentSummary = getProjectedSummary(change.field)
229 const summaryDifference = change.summary
230 ? diffBaselinePatches(previousSummary, currentSummary)
231 : {}
232β
233 cacheSummary(change.field, currentSummary)
234 mountedStateByField.set(change.field, change.field._isMounted)
235β
236 const patch: DevtoolsMountedFieldPatch = {
237 fieldId: change.fieldId,
238 ...(change.structure === 'upsert' || !wasIncluded
239 ? {
240 path: change.field.name,
241 ...(previousMounted !== change.field._isMounted &&
242 (previousMounted !== undefined || !change.field._isMounted)
243 ? { isMounted: change.field._isMounted }
244 : {}),
245 }
246 : {}),
247 ...(summaryDifference.set
248 ? { setSummary: summaryDifference.set }
249 : {}),
250 ...(summaryDifference.clear
251 ? { clearSummary: summaryDifference.clear }
252 : {}),
253 }
254β
255 if (
256 patch.path !== undefined ||
257 patch.isMounted !== undefined ||
258 patch.setSummary !== undefined ||
259 patch.clearSummary !== undefined
260 ) {
261 upsert.push(patch)
262 }
263 }
264β
265 if (upsert.length === 0 && remove.length === 0) continue
266β
267 formDevtoolsEventClient.emit('field-list-patch', {
268 formInstanceId,
269 ...(upsert.length > 0 ? { upsert } : {}),
270 ...(remove.length > 0 ? { remove } : {}),
271 })
272 }
273 }
274β
275 const scheduleFlush = (): void => {
276 if (flushScheduled) return
277 flushScheduled = true
278 queueMicrotask(flushPendingChanges)
279 }
280β
281 function queueFieldChange(
282 field: AnyInternalFieldApi,
283 structure?: PendingStructure,
284 summary = true,
285 ): void {
286 const form = field.form
287 if (!mountedForms.isMounted(form)) return
288β
289 const formInstanceId = mountedForms.getFormInstanceId(form)
290 if (!subscribedFormIds.has(formInstanceId)) return
291β
292 const fieldId =
293 structure === 'remove'
294 ? identity.getExistingFieldId(field)
295 : identity.getFieldId(field)
296 if (!fieldId) return
297β
298 let formChanges = pendingChanges.get(formInstanceId)
299 if (!formChanges) {
300 formChanges = { form, fields: new Map() }
301 pendingChanges.set(formInstanceId, formChanges)
302 }
303β
304 const previous = formChanges.fields.get(fieldId)
305 formChanges.fields.set(fieldId, {
306 fieldId,
307 field,
308 structure: structure ?? previous?.structure,
309 summary: summary || previous?.summary === true,
310 })
311 scheduleFlush()
312 }
313β
314 const removeLongValidationForForm = (formInstanceId: FormId): void => {
315 const form = mountedForms.getMountedForm(formInstanceId)
316 if (!form) return
317β
318 longValidation.removeWhere((field) => field.form === form)
319 }
320β
321 const cleanupSubscribeListener = formDevtoolsEventClient.on(
322 'field-list-subscribe',
323 (event) => {
324 const { formInstanceId } = event.payload
325 subscribedFormIds.add(formInstanceId)
326 emitSnapshot(formInstanceId)
327 },
328 )
329 const cleanupUnsubscribeListener = formDevtoolsEventClient.on(
330 'field-list-unsubscribe',
331 (event) => {
332 const { formInstanceId } = event.payload
333 removeLongValidationForForm(formInstanceId)
334 subscribedFormIds.delete(formInstanceId)
335 pendingChanges.delete(formInstanceId)
336 },
337 )
338β
339 return {
340 dispose: () => {
341 disposed = true
342 pendingChanges.clear()
343 longValidation.dispose()
344 cleanupSubscribeListener()
345 cleanupUnsubscribeListener()
346 },
347 fieldMounted: (field) => {
348 observeLongValidation(field)
349 queueFieldChange(field, 'upsert')
350 },
351 fieldMoved: (field, _previousPath) => {
352 observeLongValidation(field)
353 queueFieldChange(field, 'upsert')
354 },
355 fieldUpdated: (field) => {
356 if (field._isKilled) {
357 longValidation.remove(field)
358 return
359 }
360 observeLongValidation(field)
361 queueFieldChange(field)
362 },
363 fieldSubtreeRemoved: (_form, fields) => {
364 for (const field of fields) {
365 longValidation.remove(field)
366 queueFieldChange(field, 'remove', false)
367 }
368 },
369 fieldUnmounted: (field, _previousPath) => {
370 longValidation.remove(field)
371 queueFieldChange(field, 'upsert', false)
372 },
373 formMounted: emitSubscribedSnapshot,
374 formUnmounted: (formInstanceId) => {
375 removeLongValidationForForm(formInstanceId)
376 pendingChanges.delete(formInstanceId)
377 emitSnapshot(formInstanceId, null)
378 subscribedFormIds.delete(formInstanceId)
379 },
380 getFieldRowsSnapshot: createSnapshot,
381 }
382}