add EditorAtom helper (tldraw#6531)

When I was working on the workflows starter, I found myself needing to
store a lot of state in atoms. This includes:
* The current exectution
* Which ports on which shapes should be highlighted when dragging a
connection
* Whether the on-canvas component picker was visible, and which shape it
should be attached to

All of this state should really belong to a specific `Editor` instance.
It's referencing data from that instance. If I was building a full app
and navigated from one workflow to another, I would want all the state
to be cleared due to the editor getting re-created. It's possible to get
this sort of functionality by using a weak map from editors to atoms,
but it takes a fair bit of management.

This diff adds an `EditorAtom` helper which handles the weak-map
juggling. The interface is similar to that of `Editor`, but each method
takes an `editor` for scoping.

### Change type

- [x] `api`


### Release notes

### API Changes

- Added `EditorAtom`, a helper for storing editor UI state in an `Atom`

Author: SomeHats

packages/editor/api-report.api.md

@@ -1549,6 +1549,19 @@ export class Editor extends EventEmitter<TLEventMap> {
     zoomToUser(userId: string, opts?: TLCameraMoveOptions): this;
 }
 
+// @public
+export class EditorAtom<T> {
+    constructor(name: string, getInitialState: (editor: Editor) => T);
+    // (undocumented)
+    get(editor: Editor): T;
+    // (undocumented)
+    getAtom(editor: Editor): Atom<T>;
+    // (undocumented)
+    set(editor: Editor, state: T): T;
+    // (undocumented)
+    update(editor: Editor, update: (state: T) => T): T;
+}
+
 // @public (undocumented)
 export const EditorContext: React_3.Context<Editor | null>;
 

packages/editor/src/index.ts

@@ -450,6 +450,7 @@ export {
 	setPointerCapture,
 	stopEventPropagation,
 } from './lib/utils/dom'
+export { EditorAtom } from './lib/utils/EditorAtom'
 export { getIncrementedName } from './lib/utils/getIncrementedName'
 export { getPointerInfo } from './lib/utils/getPointerInfo'
 export { getSvgPathFromPoints } from './lib/utils/getSvgPathFromPoints'

packages/editor/src/lib/utils/EditorAtom.ts

@@ -0,0 +1,37 @@
+import { atom, Atom } from '@tldraw/state'
+import { WeakCache } from '@tldraw/utils'
+import { Editor } from '../editor/Editor'
+
+/**
+ * An Atom that is scoped to the lifetime of an Editor.
+ *
+ * This is useful for storing UI state for tldraw applications. Keeping state scoped to an editor
+ * instead of stored in a global atom can prevent issues with state being shared between editors
+ * when navigating between pages, or when multiple editor instances are used on the same page.
+ *
+ * @public
+ */
+export class EditorAtom<T> {
+	private states = new WeakCache<Editor, Atom<T>>()
+
+	constructor(
+		private name: string,
+		private getInitialState: (editor: Editor) => T
+	) {}
+
+	getAtom(editor: Editor): Atom<T> {
+		return this.states.get(editor, () => atom(this.name, this.getInitialState(editor)))
+	}
+
+	get(editor: Editor): T {
+		return this.getAtom(editor).get()
+	}
+
+	update(editor: Editor, update: (state: T) => T): T {
+		return this.getAtom(editor).update(update)
+	}
+
+	set(editor: Editor, state: T): T {
+		return this.getAtom(editor).set(state)
+	}
+}