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

devtoolsBridge.lib.ts

143 lines4.9 KB

1import type { AnyInternalFormApi } from './FormApi/FormApi.lib'
2import type {
3 AnyInternalFieldApi,
4 InternalFieldListenerInstance,
5 InternalFieldValidatorInstance,
6} from './FieldApi/FieldApi.lib'
7​
8/**
9 * A listener or validator dependency edge affected by reconciliation.
10 */
11interface BaseFieldDependencyChange {
12 sourceField: AnyInternalFieldApi
13 watchingField: AnyInternalFieldApi
15​
16export interface FieldListenerDependencyChange extends BaseFieldDependencyChange {
17 kind: 'listener'
18 listenerInstance: InternalFieldListenerInstance
20​
21export interface FieldValidatorDependencyChange extends BaseFieldDependencyChange {
22 kind: 'validator'
23 validatorInstance: InternalFieldValidatorInstance
25​
26export type FieldDependencyChange =
27 FieldListenerDependencyChange | FieldValidatorDependencyChange
28​
29/**
30 * Optional hooks installed by `@tanstack/form-devtools`.
31 *
32 * The core package owns only this narrow lifecycle contract. It passes live
33 * form instances to the installed bridge, and the devtools package decides how
34 * to transform those instances into serializable event payloads for the panel.
35 */
36export interface FormDevtoolsBridge {
37 /**
38 * Called when `form.mount()` runs.
39 *
40 * Use this to register a form as currently available to Devtools. The same
41 * form object is later passed to `unmountForm` when the cleanup returned by
42 * `form.mount()` runs.
43 */
44 mountForm?: (form: AnyInternalFormApi) => void
45 /**
46 * Called when a mounted form's `form.mount()` cleanup runs.
47 *
48 * Use this to remove the form from Devtools-owned mounted-form state and to
49 * clean up subscriptions associated with that form.
50 */
51 unmountForm?: (form: AnyInternalFormApi) => void
52 /**
53 * Called after `form._update(options)` applies new options.
54 *
55 * Use this for Devtools metadata that can change without a new form instance,
56 * such as `form.formId`. This hook may run often in framework adapters, so
57 * the bridge should ignore updates that do not change Devtools-visible data.
58 */
59 updateForm?: (form: AnyInternalFormApi) => void
60 /**
61 * Called after a field's meta state updates.
62 *
63 * Use this for Devtools data derived from field meta, such as field-list
64 * summary flags. This hook may run often, so the bridge should ignore fields
65 * whose form is not currently subscribed.
66 */
67 updateField?: (field: AnyInternalFieldApi) => void
68 /**
69 * Called after a field is inserted into the form field trie.
70 */
71 fieldAdded?: (field: AnyInternalFieldApi) => void
72 /**
73 * Called after listener or validator dependency edges change. Attached and
74 * detached edges are both included so removed endpoints remain observable.
75 */
76 fieldDependenciesChanged?: (
77 changes: ReadonlyArray<FieldDependencyChange>,
78 ) => void
79 /**
80 * Called when a field's component registration count transitions from 0 to 1.
81 *
82 * Use this to add mounted fields to Devtools-owned field-list state.
83 */
84 mountField?: (field: AnyInternalFieldApi) => void
85 /**
86 * Called when a field's component registration count transitions from 1 to 0.
87 *
88 * `previousPath` is captured before the field can be pruned or moved, so the
89 * bridge can clean up path-indexed state without reading stale tree data.
90 */
91 unmountField?: (field: AnyInternalFieldApi, previousPath: string) => void
92 /**
93 * Called after a field moves to a new path, usually because of array
94 * operations such as move, swap, insert, or remove.
95 */
96 moveField?: (field: AnyInternalFieldApi, previousPath: string) => void
97 /**
98 * Called after a field subtree is removed from the form field tree.
99 *
100 * The field objects are passed only as live internals for the installed
101 * bridge. Event payload conversion still belongs to `@tanstack/form-devtools`.
102 */
103 removeFieldSubtree?: (
104 form: AnyInternalFormApi,
105 fields: Array<{ field: AnyInternalFieldApi; previousPath: string }>,
106 ) => void
108​
109let activeBridge: FormDevtoolsBridge | null = null
110​
111/**
112 * Installs the active Devtools bridge for form-core lifecycle notifications.
113 *
114 * This is intentionally an internals-only API. Form Devtools calls it when the
115 * Devtools panel/context is mounted, and core runtime code reads the active
116 * bridge through `devtools()`. The returned cleanup removes this bridge only if
117 * it is still the active bridge.
118 */
119export function installDevtoolsBridge(bridge: FormDevtoolsBridge): () => void {
120 activeBridge = bridge
121​
122 let didUninstall = false
123​
124 return () => {
125 if (didUninstall) return
126 didUninstall = true
127​
128 if (activeBridge !== bridge) return
129​
130 activeBridge = null
131 }
133​
134/**
135 * Returns the active bridge, or an empty bridge object when Devtools is absent.
136 *
137 * Core call sites use optional hook calls on this value so normal form-core
138 * users do not pay for Devtools dependencies or event payload logic.
139 */
140export function devtools(): FormDevtoolsBridge {
141 // Double conditional chains are dumb, so I prefer this approach
142 return activeBridge ?? {}