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

package/src/lib/useReactor.ts

@@ -2,7 +2,78 @@ import { EffectScheduler } from '@tldraw/state'
 import { throttleToNextFrame } from '@tldraw/utils'
 import { useEffect } from 'react'
 
-/** @public */
+/**
+ * A React hook that runs a side effect in response to changes in signals (reactive state).
+ *
+ * The effect function will automatically track any signals (atoms, computed values) that are
+ * accessed during its execution. When any of those signals change, the effect will be
+ * scheduled to run again on the next animation frame.
+ *
+ * This is useful for performing side effects (like updating the DOM, making API calls, or
+ * updating external state) in response to changes in tldraw's reactive state system, while
+ * keeping those effects efficiently batched and throttled.
+ *
+ * @example
+ * ```tsx
+ * import { useReactor, useEditor } from 'tldraw'
+ *
+ * function MyComponent() {
+ *   const editor = useEditor()
+ *
+ *   // Update document title when shapes change
+ *   useReactor(
+ *     'update title',
+ *     () => {
+ *       const shapes = editor.getCurrentPageShapes()
+ *       document.title = `Shapes: ${shapes.length}`
+ *     },
+ *     [editor]
+ *   )
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * import { useReactor, useEditor } from 'tldraw'
+ *
+ * function SelectionAnnouncer() {
+ *   const editor = useEditor()
+ *
+ *   // Announce selection changes for accessibility
+ *   useReactor(
+ *     'announce selection',
+ *     () => {
+ *       const selectedIds = editor.getSelectedShapeIds()
+ *       if (selectedIds.length > 0) {
+ *         console.log(`Selected ${selectedIds.length} shape(s)`)
+ *       }
+ *     },
+ *     [editor]
+ *   )
+ *
+ *   return null
+ * }
+ * ```
+ *
+ * @remarks
+ * The effect is throttled to run at most once per animation frame using `requestAnimationFrame`.
+ * This makes it suitable for effects that need to respond to state changes but don't need to
+ * run synchronously.
+ *
+ * If you need the effect to run immediately without throttling, use {@link useQuickReactor} instead.
+ *
+ * The effect function will be re-created when any of the `deps` change, similar to React's
+ * `useEffect`. The effect automatically tracks which signals it accesses, so you don't need
+ * to manually specify them as dependencies.
+ *
+ * @param name - A debug name for the effect, useful for debugging and performance profiling.
+ * @param reactFn - The effect function to run. Any signals accessed in this function will be tracked.
+ * @param deps - React dependencies array. The effect will be recreated when these change. Defaults to `[]`.
+ *
+ * @public
+ */
 export function useReactor(name: string, reactFn: () => void, deps: undefined | any[] = []) {
 	useEffect(() => {
 		let cancelFn: () => void | undefined

package/src/lib/useStateTracking.ts

@@ -8,6 +8,11 @@ import React from 'react'
  *
  * See the `track` component wrapper, which uses this under the hood.
  *
+ * @param name - A debug name for the reactive tracking context
+ * @param render - The render function that accesses reactive values
+ * @param deps - Optional dependency array to control when the tracking context is recreated
+ * @returns The result of calling the render function
+ *
  * @example
  * ```ts
  * function MyComponent() {

package/src/lib/useValue.ts

@@ -2,47 +2,80 @@
 import { Signal, computed, react } from '@tldraw/state'
 import { useMemo, useSyncExternalStore } from 'react'
 
-/** @public */
-export function useValue<Value>(value: Signal<Value>): Value
-
 /**
- * Extracts the value from a signal and subscribes to it.
+ * Extracts the current value from a signal and subscribes the component to changes.
+ *
+ * This is the most straightforward way to read signal values in React components.
+ * When the signal changes, the component will automatically re-render with the new value.
  *
- * Note that you do not need to use this hook if you are wrapping the component with {@link track}
+ * Note: You do not need to use this hook if you are wrapping the component with {@link track},
+ * as tracked components automatically subscribe to any signals accessed with `.get()`.
+ *
+ * @param value - The signal to read the value from
+ * @returns The current value of the signal
  *
  * @example
  * ```ts
- * const Counter: React.FC = () => {
- *   const $count = useAtom('count', 0)
- *   const increment = useCallback(() => $count.set($count.get() + 1), [count])
- *   const currentCount = useValue($count)
- *   return <button onClick={increment}>{currentCount}</button>
+ * import { atom } from '@tldraw/state'
+ * import { useValue } from '@tldraw/state-react'
+ *
+ * const count = atom('count', 0)
+ *
+ * function Counter() {
+ *   const currentCount = useValue(count)
+ *   return (
+ *     <button onClick={() => count.set(currentCount + 1)}>
+ *       Count: {currentCount}
+ *     </button>
+ *   )
  * }
  * ```
  *
- * You can also pass a function to compute the value and it will be memoized as in `useComputed`:
+ * @public
+ */
+export function useValue<Value>(value: Signal<Value>): Value
+
+/**
+ * Creates a computed value with automatic dependency tracking and subscribes to changes.
+ *
+ * This overload allows you to compute a value from one or more signals with automatic
+ * memoization. The computed function will only re-execute when its dependencies change,
+ * and the component will only re-render when the computed result changes.
+ *
+ * @param name - A descriptive name for debugging purposes
+ * @param fn - Function that computes the value, should call `.get()` on any signals it depends on
+ * @param deps - Array of signals that the computed function depends on
+ * @returns The computed value
  *
  * @example
  * ```ts
- * type GreeterProps = {
- *   firstName: Signal<string>
- *   lastName: Signal<string>
- * }
+ * import { atom } from '@tldraw/state'
+ * import { useValue } from '@tldraw/state-react'
+ *
+ * const firstName = atom('firstName', 'John')
+ * const lastName = atom('lastName', 'Doe')
+ *
+ * function UserGreeting() {
+ *   const fullName = useValue('fullName', () => {
+ *     return `${firstName.get()} ${lastName.get()}`
+ *   }, [firstName, lastName])
  *
- * const Greeter = track(function Greeter({ firstName, lastName }: GreeterProps) {
- *   const fullName = useValue('fullName', () => `${firstName.get()} ${lastName.get()}`, [
- *     firstName,
- *     lastName,
- *   ])
  *   return <div>Hello {fullName}!</div>
- * })
+ * }
  * ```
  *
  * @public
  */
 export function useValue<Value>(name: string, fn: () => Value, deps: unknown[]): Value
 
-/** @public */
+/**
+ * Implementation function for useValue hook overloads.
+ *
+ * Handles both single signal subscription and computed value creation with dependency tracking.
+ * Uses React's useSyncExternalStore for efficient subscription management and automatic cleanup.
+ *
+ * @internal
+ */
 export function useValue() {
 	const args = arguments
 	// deps will be either the computed or the deps array