@tldraw/state-react 4.1.0-next.1b89b40eff1c → 4.1.0-next.9f145d10c7d0

package/src/lib/useComputed.ts

@@ -2,23 +2,65 @@
 import { Computed, ComputedOptions, computed } from '@tldraw/state'
 import { useMemo } from 'react'
 
-/** @public */
+/**
+ * Creates a new computed signal that automatically tracks its dependencies and recalculates when they change.
+ * This overload is for basic computed values without custom options.
+ *
+ * @param name - A descriptive name for the computed signal, used for debugging and identification
+ * @param compute - A function that computes the value, automatically tracking any signal dependencies
+ * @param deps - React dependency array that controls when the computed signal is recreated
+ * @returns A computed signal containing the calculated value
+ *
+ * @example
+ * ```ts
+ * const firstName = atom('firstName', 'John')
+ * const lastName = atom('lastName', 'Doe')
+ *
+ * function UserProfile() {
+ *   const fullName = useComputed(
+ *     'fullName',
+ *     () => `${firstName.get()} ${lastName.get()}`,
+ *     [firstName, lastName]
+ *   )
+ *
+ *   return <div>Welcome, {fullName.get()}!</div>
+ * }
+ * ```
+ *
+ * @public
+ */
 export function useComputed<Value>(name: string, compute: () => Value, deps: any[]): Computed<Value>
 
 /**
- * Creates a new computed signal and returns it. The computed signal will be created only once.
+ * Creates a new computed signal with custom options for advanced behavior like custom equality checking,
+ * diff computation, and history tracking. The computed signal will be created only once.
+ *
+ * @param name - A descriptive name for the computed signal, used for debugging and identification
+ * @param compute - A function that computes the value, automatically tracking any signal dependencies
+ * @param opts - Configuration options for the computed signal
+ *   - isEqual - Custom equality function to determine if the computed value has changed
+ *   - computeDiff - Function to compute diffs between old and new values for history tracking
+ *   - historyLength - Maximum number of diffs to keep in history buffer for time-travel functionality
+ * @param deps - React dependency array that controls when the computed signal is recreated
+ * @returns A computed signal containing the calculated value with the specified options
  *
  * @example
  * ```ts
- * type GreeterProps = {
- *   firstName: Signal<string>
- *   lastName: Signal<string>
- * }
+ * function ShoppingCart() {
+ *   const items = useAtom('items', [])
  *
- * const Greeter = track(function Greeter ({firstName, lastName}: GreeterProps) {
- *   const fullName = useComputed('fullName', () => `${firstName.get()} ${lastName.get()}`)
- *   return <div>Hello {fullName.get()}!</div>
- * })
+ *   // Computed with custom equality to avoid recalculation for equivalent arrays
+ *   const sortedItems = useComputed(
+ *     'sortedItems',
+ *     () => items.get().sort((a, b) => a.name.localeCompare(b.name)),
+ *     {
+ *       isEqual: (a, b) => a.length === b.length && a.every((item, i) => item.id === b[i].id)
+ *     },
+ *     [items]
+ *   )
+ *
+ *   return <ItemList items={sortedItems.get()} />
+ * }
  * ```
  *
  * @public
@@ -29,7 +71,16 @@ export function useComputed<Value, Diff = unknown>(
 	opts: ComputedOptions<Value, Diff>,
 	deps: any[]
 ): Computed<Value>
-/** @public */
+/**
+ * Implementation function that handles both overloaded signatures of useComputed.
+ * Uses the arguments object to dynamically determine which signature was called.
+ *
+ * This function creates a memoized computed signal that automatically tracks dependencies
+ * and only recreates when the dependency array changes, providing optimal performance
+ * in React components.
+ *
+ * @public
+ */
 export function useComputed() {
 	const name = arguments[0]
 	const compute = arguments[1]

package/src/lib/useQuickReactor.test.tsx

@@ -0,0 +1,405 @@
+import { act, render, RenderResult } from '@testing-library/react'
+import { atom, Atom } from '@tldraw/state'
+import { useState } from 'react'
+import { vi } from 'vitest'
+import { useAtom } from './useAtom'
+import { useQuickReactor } from './useQuickReactor'
+
+describe('useQuickReactor', () => {
+	let mockEffectFn: ReturnType<typeof vi.fn>
+	let _component: () => React.JSX.Element
+	let view: RenderResult
+
+	beforeEach(() => {
+		mockEffectFn = vi.fn()
+		vi.clearAllMocks()
+	})
+
+	describe('basic functionality', () => {
+		it('executes the effect function immediately on mount', async () => {
+			function Component() {
+				useQuickReactor('test-reactor', mockEffectFn, [])
+				return <div>test</div>
+			}
+
+			await act(() => {
+				render(<Component />)
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledTimes(1)
+		})
+
+		it('executes the effect function immediately when tracked signals change', async () => {
+			let theAtom: Atom<number>
+			function Component() {
+				theAtom = useAtom('counter', 0)
+				useQuickReactor(
+					'test-reactor',
+					() => {
+						mockEffectFn(theAtom.get())
+					},
+					[]
+				)
+				return <div>{theAtom.get()}</div>
+			}
+
+			await act(() => {
+				view = render(<Component />)
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledTimes(1)
+			expect(mockEffectFn).toHaveBeenLastCalledWith(0)
+
+			// Change the atom value - should trigger immediate effect
+			await act(() => {
+				theAtom!.set(5)
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledTimes(2)
+			expect(mockEffectFn).toHaveBeenLastCalledWith(5)
+		})
+
+		it('works with external atoms not created via useAtom', async () => {
+			const externalAtom = atom('external', 'initial')
+
+			function Component() {
+				useQuickReactor(
+					'test-reactor',
+					() => {
+						mockEffectFn(externalAtom.get())
+					},
+					[]
+				)
+				return <div>test</div>
+			}
+
+			await act(() => {
+				render(<Component />)
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledWith('initial')
+
+			await act(() => {
+				externalAtom.set('changed')
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledTimes(2)
+			expect(mockEffectFn).toHaveBeenLastCalledWith('changed')
+		})
+	})
+
+	describe('dependency array behavior', () => {
+		it('recreates the reactor when dependencies change', async () => {
+			const dep = 'dep1'
+			let setDep: (newDep: string) => void
+			const reactorExecutions: string[] = []
+
+			function Component() {
+				const [currentDep, setCurrentDep] = useState(dep)
+				setDep = setCurrentDep
+
+				useQuickReactor(
+					'test-reactor',
+					() => {
+						reactorExecutions.push(`executed with ${currentDep}`)
+						mockEffectFn(currentDep)
+					},
+					[currentDep]
+				)
+
+				return <div>{currentDep}</div>
+			}
+
+			await act(() => {
+				render(<Component />)
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledWith('dep1')
+			expect(reactorExecutions).toEqual(['executed with dep1'])
+
+			// Change dependency - should recreate reactor
+			await act(() => {
+				setDep('dep2')
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledTimes(2)
+			expect(mockEffectFn).toHaveBeenLastCalledWith('dep2')
+			expect(reactorExecutions).toEqual(['executed with dep1', 'executed with dep2'])
+		})
+	})
+
+	describe('cleanup behavior', () => {
+		it('cleans up the effect scheduler when component unmounts', async () => {
+			let theAtom: Atom<number>
+			let isUnmounted = false
+
+			function Component() {
+				theAtom = useAtom('counter', 0)
+				useQuickReactor(
+					'test-reactor',
+					() => {
+						if (isUnmounted) {
+							mockEffectFn('should-not-execute')
+						} else {
+							mockEffectFn(theAtom.get())
+						}
+					},
+					[]
+				)
+				return <div>{theAtom.get()}</div>
+			}
+
+			await act(() => {
+				view = render(<Component />)
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledWith(0)
+
+			// Unmount the component
+			await act(() => {
+				view.unmount()
+				isUnmounted = true
+			})
+
+			// Try to change the atom after unmount - effect should not run
+			await act(() => {
+				theAtom!.set(10)
+			})
+
+			// Should still only have been called once (during mount)
+			expect(mockEffectFn).toHaveBeenCalledTimes(1)
+			expect(mockEffectFn).not.toHaveBeenCalledWith('should-not-execute')
+		})
+
+		it('cleans up the previous scheduler when dependencies change', async () => {
+			const dep = 1
+			let setDep: (newDep: number) => void
+			const oldAtom = atom('old', 'old-value')
+			const newAtom = atom('new', 'new-value')
+
+			function Component() {
+				const [currentDep, setCurrentDep] = useState(dep)
+				setDep = setCurrentDep
+
+				useQuickReactor(
+					'test-reactor',
+					() => {
+						const atomToUse = currentDep === 1 ? oldAtom : newAtom
+						mockEffectFn(atomToUse.get())
+					},
+					[currentDep]
+				)
+
+				return <div>dep: {currentDep}</div>
+			}
+
+			await act(() => {
+				render(<Component />)
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledWith('old-value')
+
+			// Change the old atom - should trigger effect
+			await act(() => {
+				oldAtom.set('old-updated')
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledTimes(2)
+			expect(mockEffectFn).toHaveBeenLastCalledWith('old-updated')
+
+			// Change dependency - should cleanup old scheduler and create new one
+			await act(() => {
+				setDep(2)
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledTimes(3)
+			expect(mockEffectFn).toHaveBeenLastCalledWith('new-value')
+
+			// Old atom changes should no longer trigger effects
+			await act(() => {
+				oldAtom.set('old-should-not-trigger')
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledTimes(3) // No additional calls
+
+			// New atom changes should trigger effects
+			await act(() => {
+				newAtom.set('new-updated')
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledTimes(4)
+			expect(mockEffectFn).toHaveBeenLastCalledWith('new-updated')
+		})
+	})
+
+	describe('multiple reactors', () => {
+		it('supports multiple reactors in the same component', async () => {
+			let atom1: Atom<number>
+			let atom2: Atom<string>
+			const effect1 = vi.fn()
+			const effect2 = vi.fn()
+
+			function Component() {
+				atom1 = useAtom('atom1', 1)
+				atom2 = useAtom('atom2', 'a')
+
+				useQuickReactor(
+					'reactor1',
+					() => {
+						effect1(atom1.get())
+					},
+					[]
+				)
+
+				useQuickReactor(
+					'reactor2',
+					() => {
+						effect2(atom2.get())
+					},
+					[]
+				)
+
+				return (
+					<div>
+						{atom1.get()} {atom2.get()}
+					</div>
+				)
+			}
+
+			await act(() => {
+				render(<Component />)
+			})
+
+			expect(effect1).toHaveBeenCalledWith(1)
+			expect(effect2).toHaveBeenCalledWith('a')
+
+			// Change first atom
+			await act(() => {
+				atom1!.set(2)
+			})
+
+			expect(effect1).toHaveBeenCalledTimes(2)
+			expect(effect1).toHaveBeenLastCalledWith(2)
+			expect(effect2).toHaveBeenCalledTimes(1) // Should not be affected
+
+			// Change second atom
+			await act(() => {
+				atom2!.set('b')
+			})
+
+			expect(effect1).toHaveBeenCalledTimes(2) // Should not be affected
+			expect(effect2).toHaveBeenCalledTimes(2)
+			expect(effect2).toHaveBeenLastCalledWith('b')
+		})
+	})
+
+	describe('complex scenarios', () => {
+		it('handles complex dependency tracking with multiple atoms', async () => {
+			let atom1: Atom<number>
+			let atom2: Atom<number>
+			let atom3: Atom<number>
+
+			function Component() {
+				atom1 = useAtom('a', 1)
+				atom2 = useAtom('b', 2)
+				atom3 = useAtom('c', 3)
+
+				useQuickReactor(
+					'complex-reactor',
+					() => {
+						const sum = atom1.get() + atom2.get() + atom3.get()
+						mockEffectFn(sum)
+					},
+					[]
+				)
+
+				return <div>sum</div>
+			}
+
+			await act(() => {
+				render(<Component />)
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledWith(6) // 1 + 2 + 3
+
+			// Change each atom individually
+			await act(() => {
+				atom1!.set(10)
+			})
+			expect(mockEffectFn).toHaveBeenLastCalledWith(15) // 10 + 2 + 3
+
+			await act(() => {
+				atom2!.set(20)
+			})
+			expect(mockEffectFn).toHaveBeenLastCalledWith(33) // 10 + 20 + 3
+
+			await act(() => {
+				atom3!.set(30)
+			})
+			expect(mockEffectFn).toHaveBeenLastCalledWith(60) // 10 + 20 + 30
+
+			expect(mockEffectFn).toHaveBeenCalledTimes(4)
+		})
+
+		it('works with conditional atom access', async () => {
+			let toggleAtom: Atom<boolean>
+			let atom1: Atom<string>
+			let atom2: Atom<string>
+
+			function Component() {
+				toggleAtom = useAtom('toggle', true)
+				atom1 = useAtom('atom1', 'value1')
+				atom2 = useAtom('atom2', 'value2')
+
+				useQuickReactor(
+					'conditional-reactor',
+					() => {
+						const useFirst = toggleAtom.get()
+						const value = useFirst ? atom1.get() : atom2.get()
+						mockEffectFn(value)
+					},
+					[]
+				)
+
+				return <div>conditional</div>
+			}
+
+			await act(() => {
+				render(<Component />)
+			})
+
+			expect(mockEffectFn).toHaveBeenCalledWith('value1')
+
+			// Change atom1 - should trigger since toggle is true
+			await act(() => {
+				atom1!.set('new-value1')
+			})
+			expect(mockEffectFn).toHaveBeenCalledWith('new-value1')
+
+			// Change atom2 - should NOT trigger since toggle is true
+			await act(() => {
+				atom2!.set('new-value2')
+			})
+			expect(mockEffectFn).toHaveBeenCalledTimes(2) // No new call
+
+			// Toggle to false - should now use atom2
+			await act(() => {
+				toggleAtom!.set(false)
+			})
+			expect(mockEffectFn).toHaveBeenCalledWith('new-value2')
+
+			// Now changes to atom1 should not trigger
+			await act(() => {
+				atom1!.set('ignored-value1')
+			})
+			expect(mockEffectFn).toHaveBeenCalledTimes(3) // No new call
+
+			// But changes to atom2 should trigger
+			await act(() => {
+				atom2!.set('final-value2')
+			})
+			expect(mockEffectFn).toHaveBeenCalledWith('final-value2')
+			expect(mockEffectFn).toHaveBeenCalledTimes(4)
+		})
+	})
+})

package/src/lib/useQuickReactor.ts

@@ -1,7 +1,46 @@
 import { EMPTY_ARRAY, EffectScheduler } from '@tldraw/state'
 import { useEffect } from 'react'
 
-/** @public */
+/**
+ * A React hook that runs side effects immediately in response to signal changes, without throttling.
+ * Unlike useReactor which batches updates to animation frames, useQuickReactor executes the effect
+ * function immediately when dependencies change, making it ideal for critical updates that cannot wait.
+ *
+ * The effect runs immediately when the component mounts and whenever tracked signals change.
+ * Updates are not throttled, so the effect executes synchronously on every change.
+ *
+ * @example
+ * ```ts
+ * function DataSynchronizer() {
+ *   const criticalData = useAtom('criticalData', null)
+ *
+ *   useQuickReactor('sync-data', () => {
+ *     const data = criticalData.get()
+ *     if (data) {
+ *       // Send immediately - don't wait for next frame
+ *       sendToServer(data)
+ *     }
+ *   }, [criticalData])
+ *
+ *   return <div>Sync status updated</div>
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * function CursorUpdater({ editor }) {
+ *   useQuickReactor('update-cursor', () => {
+ *     const cursor = editor.getInstanceState().cursor
+ *     document.body.style.cursor = cursor.type
+ *   }, [])
+ * }
+ * ```
+ *
+ * @param name - A descriptive name for the reactor, used for debugging and performance profiling
+ * @param reactFn - The effect function to execute when signals change. Should not return a value.
+ * @param deps - Optional dependency array that controls when the reactor is recreated. Works like useEffect deps.
+ * @public
+ */
 export function useQuickReactor(name: string, reactFn: () => void, deps: any[] = EMPTY_ARRAY) {
 	useEffect(() => {
 		const scheduler = new EffectScheduler(name, reactFn)

package/src/lib/useReactor.test.tsx

@@ -0,0 +1,128 @@
+import { act, render, RenderResult } from '@testing-library/react'
+import { Atom } from '@tldraw/state'
+import { useState } from 'react'
+import { vi } from 'vitest'
+import { useAtom } from './useAtom'
+import { useReactor } from './useReactor'
+
+describe('useReactor', () => {
+	let mockEffectFn: ReturnType<typeof vi.fn>
+	let view: RenderResult
+
+	beforeEach(() => {
+		mockEffectFn = vi.fn()
+		vi.clearAllMocks()
+	})
+
+	it('executes the effect function immediately on mount', async () => {
+		function Component() {
+			useReactor('test-reactor', mockEffectFn, [])
+			return <div>test</div>
+		}
+
+		await act(() => {
+			render(<Component />)
+		})
+
+		expect(mockEffectFn).toHaveBeenCalledTimes(1)
+	})
+
+	it('executes the effect function when tracked signals change', async () => {
+		let theAtom: Atom<number>
+		function Component() {
+			theAtom = useAtom('counter', 0)
+			useReactor(
+				'test-reactor',
+				() => {
+					mockEffectFn(theAtom.get())
+				},
+				[]
+			)
+			return <div>{theAtom.get()}</div>
+		}
+
+		await act(() => {
+			view = render(<Component />)
+		})
+
+		expect(mockEffectFn).toHaveBeenCalledTimes(1)
+		expect(mockEffectFn).toHaveBeenLastCalledWith(0)
+
+		// Change the atom value - should trigger throttled effect
+		await act(() => {
+			theAtom!.set(5)
+		})
+
+		// In test mode, throttleToNextFrame executes immediately
+		expect(mockEffectFn).toHaveBeenCalledTimes(2)
+		expect(mockEffectFn).toHaveBeenLastCalledWith(5)
+	})
+
+	it('recreates the reactor when dependencies change', async () => {
+		let setDep: (newDep: string) => void
+
+		function Component() {
+			const [currentDep, setCurrentDep] = useState('dep1')
+			setDep = setCurrentDep
+
+			useReactor(
+				'test-reactor',
+				() => {
+					mockEffectFn(currentDep)
+				},
+				[currentDep]
+			)
+
+			return <div>{currentDep}</div>
+		}
+
+		await act(() => {
+			render(<Component />)
+		})
+
+		expect(mockEffectFn).toHaveBeenCalledWith('dep1')
+
+		// Change dependency - should recreate reactor
+		await act(() => {
+			setDep('dep2')
+		})
+
+		expect(mockEffectFn).toHaveBeenCalledTimes(2)
+		expect(mockEffectFn).toHaveBeenLastCalledWith('dep2')
+	})
+
+	it('cleans up effects when component unmounts', async () => {
+		let theAtom: Atom<number>
+
+		function Component() {
+			theAtom = useAtom('counter', 0)
+			useReactor(
+				'test-reactor',
+				() => {
+					mockEffectFn(theAtom.get())
+				},
+				[]
+			)
+			return <div>{theAtom.get()}</div>
+		}
+
+		await act(() => {
+			view = render(<Component />)
+		})
+
+		expect(mockEffectFn).toHaveBeenCalledWith(0)
+
+		// Unmount the component
+		await act(() => {
+			view.unmount()
+		})
+
+		// Try to change the atom after unmount - effect should not run
+		await act(() => {
+			theAtom!.set(10)
+		})
+
+		// Should still only have been called once (during mount)
+		expect(mockEffectFn).toHaveBeenCalledTimes(1)
+	})
+})