From 0235f841153c40a89c538a369708b7c8422cbbdd Mon Sep 17 00:00:00 2001
From: David Sheldrick <d.j.sheldrick@gmail.com>
Date: Sun, 14 Jul 2024 11:54:27 +0100
Subject: [PATCH] [sdk] make EffectScheduler and useStateTracking public
 (#4155)

closes #4085

Neither of these should be too valuable for tldraw users, but they're
also both totally stable and well documented (now) so it should be fine
to make them public?

### Change type

- [ ] `bugfix`
- [ ] `improvement`
- [ ] `feature`
- [x] `api`
- [ ] `other`

### Test plan

1. Create a shape...
2.

- [ ] Unit tests
- [ ] End to end tests

### Release notes

- Made `EffectScheduler` and `useStateTracking` public
---
 packages/editor/api-report.md                 |  6 ++++++
 packages/editor/src/index.ts                  |  2 ++
 packages/state/api-report.md                  |  2 +-
 .../state/src/lib/react/useStateTracking.ts   | 20 ++++++++++++++++++-
 4 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/packages/editor/api-report.md b/packages/editor/api-report.md
index b5c5b826b..a0365c4b7 100644
--- a/packages/editor/api-report.md
+++ b/packages/editor/api-report.md
@@ -13,6 +13,7 @@ import { ComponentType } from 'react';
 import { Computed } from '@tldraw/state';
 import { computed } from '@tldraw/state';
 import { Dispatch } from 'react';
+import { EffectScheduler } from '@tldraw/state';
 import { EmbedDefinition } from '@tldraw/tlschema';
 import { EMPTY_ARRAY } from '@tldraw/state';
 import EventEmitter from 'eventemitter3';
@@ -85,6 +86,7 @@ import { UnknownRecord } from '@tldraw/store';
 import { useComputed } from '@tldraw/state';
 import { useQuickReactor } from '@tldraw/state';
 import { useReactor } from '@tldraw/state';
+import { useStateTracking } from '@tldraw/state';
 import { useValue } from '@tldraw/state';
 import { VecModel } from '@tldraw/tlschema';
 import { whyAmIRunning } from '@tldraw/state';
@@ -1227,6 +1229,8 @@ export class Editor extends EventEmitter<TLEventMap> {
     zoomToUser(userId: string, opts?: TLCameraMoveOptions): this;
 }
 
+export { EffectScheduler }
+
 // @public (undocumented)
 export class Ellipse2d extends Geometry2d {
     constructor(config: Omit<Geometry2dOptions, 'isClosed'> & {
@@ -3508,6 +3512,8 @@ export function useShallowArrayIdentity<T>(arr: readonly T[]): readonly T[];
 // @internal (undocumented)
 export function useShallowObjectIdentity<T extends object>(arr: T): T;
 
+export { useStateTracking }
+
 // @public
 export function useSvgExportContext(): {
     isDarkMode: boolean;
diff --git a/packages/editor/src/index.ts b/packages/editor/src/index.ts
index dc7c7d80f..81dd0688a 100644
--- a/packages/editor/src/index.ts
+++ b/packages/editor/src/index.ts
@@ -18,6 +18,7 @@ export * from '@tldraw/validate'
 
 export {
 	EMPTY_ARRAY,
+	EffectScheduler,
 	atom,
 	computed,
 	react,
@@ -27,6 +28,7 @@ export {
 	useComputed,
 	useQuickReactor,
 	useReactor,
+	useStateTracking,
 	useValue,
 	whyAmIRunning,
 	type Atom,
diff --git a/packages/state/api-report.md b/packages/state/api-report.md
index 41539204b..96795fc88 100644
--- a/packages/state/api-report.md
+++ b/packages/state/api-report.md
@@ -198,7 +198,7 @@ export function useQuickReactor(name: string, reactFn: () => void, deps?: any[])
 // @public (undocumented)
 export function useReactor(name: string, reactFn: () => void, deps?: any[] | undefined): void;
 
-// @internal (undocumented)
+// @public
 export function useStateTracking<T>(name: string, render: () => T): T;
 
 // @public
diff --git a/packages/state/src/lib/react/useStateTracking.ts b/packages/state/src/lib/react/useStateTracking.ts
index d72e12e60..65dc1a10e 100644
--- a/packages/state/src/lib/react/useStateTracking.ts
+++ b/packages/state/src/lib/react/useStateTracking.ts
@@ -1,7 +1,25 @@
 import React from 'react'
 import { EffectScheduler } from '../core'
 
-/** @internal */
+/**
+ * Wraps some synchronous react render logic in a reactive tracking context.
+ *
+ * This allows you to use reactive values transparently.
+ *
+ * @example
+ * ```ts
+ * function MyComponent() {
+ *   return useStateTracking('MyComponent', () => {
+ *     const editor = useEditor()
+ *     return <div>Num shapes: {editor.getCurrentPageShapes().length}</div>
+ *   })
+ * }
+ * ```
+ *
+ * @see the `track` component wrapper, which uses this under the hood.
+ *
+ * @public
+ */
 export function useStateTracking<T>(name: string, render: () => T): T {
 	// This hook creates an effect scheduler that will trigger re-renders when its reactive dependencies change, but it
 	// defers the actual execution of the effect to the consumer of this hook.