add StateNode.addChild (tldraw#6485)

Adds an `addChild` method to `StateNode` for dynamically adding entries
to the state tree.

### Change type

- [x] `api`


### Release notes
Adds an `addChild` method to `StateNode` for dynamically adding entries
to the state tree.

### API Changes

- Add `StateNode.addChild` for dynamically adding new state nodes to
existing tools

Author: SomeHats

.cursor/rules/repo.mdc

@@ -0,0 +1,34 @@
+---
+alwaysApply: true
+---
+
+This is the monorepo for tldraw, an infinite canvas whiteboard SDK.
+
+The monorepo uses yarn berry, and is organized using workspaces.
+
+The workspaces are:
+
+- apps/docs: the tldraw.dev next.js app, hosting our public facing website, written documentation, and generated reference documentation.
+- apps/examples: API examples showing how to use the tldraw sdk.
+- apps/dotcom/client: the front-end to the user-facing tldraw.com white-boarding app. the app adds file and user management functionality around the core tldraw whiteboard sdk.
+- apps/dotcom/sync-worker: the main backend cloudflare worker for tldraw.com.
+- apps/dotcom/asset-upload-worker: a cloudflare worker handling media asset uploads for tldraw.com.
+- apps/dotcom/image-resize-worker: a cloudflare worker handling image resizing and optimization for tldraw.com.
+- apps/analytics: our internal analytics service.
+- apps/bemo-worker: a cloudflare worker hosting a demo server for tldraw sync, our multi-player backend.
+- apps/vscode: the tldraw vscode extension.
+- internal/\*: internal utilities, mostly for running this repo.
+- packages/ai: the tldraw ai module, an sdk addon for working with LLMs.
+- packages/assets: the assets (fonts, icons, images) needed for tldraw.
+- packages/create-tldraw: `npm create tldraw` cli for quickly creating a tldraw app.
+- packages/dotcom-shared: shared utilities used by the `apps/dotcom` workspaces.
+- packages/editor: the core tldraw editor.
+- packages/state: our reactive signals library, used for state management throughout the repo.
+- packages/state-react: react bindings to our reactive signals library.
+- packages/store: the reactive client-side in-memory database used to store the tldraw document in the editor.
+- packages/sync & packages/sync-core: the tldraw sync multi-player sdk addon.
+- packages/tldraw: builds on the editor adding the specific shapes (arrows, boxes, etc), tools, and UI that are recognizably tldraw.
+- packages/tlschema: type definitions, validators, and migrations for the data used & stored by tldraw.
+- packages/utils: internal utilities and helpers. generic things we use a lot, but that aren't part of the public sdk api.
+- packages/validate: lightweight zod-inspired validation library.
+- templates/\*: starting points for building tldraw applications. some of these are minimal starters showing tldraw in different frameworks, but other are more comprehensive mini-apps showing how tldraw can be adapted to a specific domain / vertical.

.cursor/rules/tests.mdc

@@ -0,0 +1,20 @@
+---
+alwaysApply: true
+---
+
+Most tests in tldraw are written using jest. End-to-end tests are written using playwright.
+
+## Jest tests
+
+When writing unit-style jest tests, test files should be named after the file they are testing.
+For example, `src/lib/LicenseManager.ts` should be tested in `src/lib/LicenseManager.test.ts`.
+
+When writing more integration-style jest test that touch several files, they should live in a separate `src/test/the-thing-you-are-testing.test.ts` file.
+For example, selection logic cuts across many files, so it's tested in `src/test/selection.test.ts`.
+
+When testing the editor, if you need tldraw's default shapes and tools, write your tests in the tldraw workspace, not the editor workspace.
+
+Tests for a specific package should be run using `yarn test` within that workspace's directory - ie in `packages/editor` to run editor tests.
+This is an alias for running `jest`, so you can filter down the tests you're running if needed.
+Running `yarn test` from the repo root will run all the tests for the entire repo.
+This can be slow, and can't be filtered as usual, so don't use it unless you have a good reason.

packages/editor/api-report.api.md

@@ -2722,6 +2722,7 @@ export class Stadium2d extends Geometry2d {
 // @public (undocumented)
 export abstract class StateNode implements Partial<TLEventHandlers> {
     constructor(editor: Editor, parent?: StateNode);
+    addChild(childConstructor: TLStateNodeConstructor): this;
     // (undocumented)
     static children?: () => TLStateNodeConstructor[];
     // (undocumented)

packages/editor/src/lib/editor/tools/StateNode.test.ts

@@ -0,0 +1,285 @@
+import { createTLStore } from '../../config/createTLStore'
+import { Editor } from '../Editor'
+import { StateNode } from './StateNode'
+
+describe('StateNode.addChild', () => {
+	// Test state node classes for addChild tests
+	class ParentState extends StateNode {
+		static override id = 'parent'
+		static override initial = 'child1'
+		static override children() {
+			return [ChildState1]
+		}
+	}
+
+	class ChildState1 extends StateNode {
+		static override id = 'child1'
+	}
+
+	class ChildState2 extends StateNode {
+		static override id = 'child2'
+	}
+
+	class ChildState3 extends StateNode {
+		static override id = 'child3'
+	}
+
+	class LeafState extends StateNode {
+		static override id = 'leaf'
+	}
+
+	class RootState extends StateNode {
+		static override id = 'root'
+		static override initial = 'child1'
+		static override children() {
+			return [ChildState1]
+		}
+	}
+
+	class RootStateWithoutChildren extends StateNode {
+		static override id = 'rootWithoutChildren'
+	}
+
+	let editor: Editor
+
+	beforeEach(() => {
+		editor = new Editor({
+			initialState: 'parent',
+			shapeUtils: [],
+			bindingUtils: [],
+			tools: [
+				ParentState,
+				ChildState1,
+				ChildState2,
+				ChildState3,
+				LeafState,
+				RootState,
+				RootStateWithoutChildren,
+			],
+			store: createTLStore({ shapeUtils: [], bindingUtils: [] }),
+			getContainer: () => document.body,
+		})
+	})
+
+	it('should add a child to a branch state node', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		// Initially should have one child
+		expect(Object.keys(parentState.children!)).toHaveLength(1)
+		expect(parentState.children!['child1']).toBeDefined()
+
+		// Add a new child
+		parentState.addChild(ChildState2)
+
+		// Should now have two children
+		expect(Object.keys(parentState.children!)).toHaveLength(2)
+		expect(parentState.children!['child1']).toBeDefined()
+		expect(parentState.children!['child2']).toBeDefined()
+		expect(parentState.children!['child2']).toBeInstanceOf(ChildState2)
+	})
+
+	it('should add a child to a root state node', () => {
+		const rootState = editor.root.children!['root'] as RootState
+
+		// Initially should have one child
+		expect(Object.keys(rootState.children!)).toHaveLength(1)
+		expect(rootState.children!['child1']).toBeDefined()
+
+		// Add a new child
+		rootState.addChild(ChildState2)
+
+		// Should now have two children
+		expect(Object.keys(rootState.children!)).toHaveLength(2)
+		expect(rootState.children!['child1']).toBeDefined()
+		expect(rootState.children!['child2']).toBeDefined()
+		expect(rootState.children!['child2']).toBeInstanceOf(ChildState2)
+	})
+
+	it('should throw an error when trying to add a child to a leaf state node', () => {
+		const leafState = editor.root.children!['leaf'] as LeafState
+
+		// Leaf state should not have children
+		expect(leafState.children).toBeUndefined()
+
+		// Should throw an error when trying to add a child
+		expect(() => {
+			leafState.addChild(ChildState2)
+		}).toThrow('StateNode.addChild: cannot add child to a leaf node')
+	})
+
+	it('should return the parent state node for chaining', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		const result = parentState.addChild(ChildState2)
+
+		expect(result).toBe(parentState)
+	})
+
+	it('should create the child with the correct editor and parent', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		parentState.addChild(ChildState2)
+		const childState = parentState.children!['child2'] as ChildState2
+
+		expect(childState.editor).toBe(editor)
+		expect(childState.parent).toBe(parentState)
+	})
+
+	it('should allow adding multiple children', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		// Add multiple children
+		parentState.addChild(ChildState2).addChild(ChildState3)
+
+		// Should have three children
+		expect(Object.keys(parentState.children!)).toHaveLength(3)
+		expect(parentState.children!['child1']).toBeDefined()
+		expect(parentState.children!['child2']).toBeDefined()
+		expect(parentState.children!['child3']).toBeDefined()
+		expect(parentState.children!['child2']).toBeInstanceOf(ChildState2)
+		expect(parentState.children!['child3']).toBeInstanceOf(ChildState3)
+	})
+
+	it('should allow transitioning to added children', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		// Add a new child
+		parentState.addChild(ChildState2)
+
+		// Should be able to transition to the new child
+		expect(() => {
+			parentState.transition('child2')
+		}).not.toThrow()
+
+		// The current state should be the new child
+		expect(parentState.getCurrent()?.id).toBe('child2')
+	})
+
+	it('should maintain existing children when adding new ones', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+		const originalChild = parentState.children!['child1']
+
+		// Add a new child
+		parentState.addChild(ChildState2)
+
+		// Original child should still exist and be the same instance
+		expect(parentState.children!['child1']).toBe(originalChild)
+		expect(parentState.children!['child1']).toBeInstanceOf(ChildState1)
+	})
+
+	it('should initialize children object for root nodes without static children', () => {
+		// Create a StateNode directly as a root node (no parent)
+		const mockEditor = {} as Editor
+		const rootStateWithoutChildren = new RootStateWithoutChildren(mockEditor, undefined)
+
+		// Root state without static children should not have children initially
+		expect(rootStateWithoutChildren.children).toBeUndefined()
+
+		// Adding a child should initialize the children object
+		rootStateWithoutChildren.addChild(ChildState2)
+
+		// Should now have children object with the added child
+		expect(rootStateWithoutChildren.children).toBeDefined()
+		expect(Object.keys(rootStateWithoutChildren.children!)).toHaveLength(1)
+		expect(rootStateWithoutChildren.children!['child2']).toBeDefined()
+		expect(rootStateWithoutChildren.children!['child2']).toBeInstanceOf(ChildState2)
+	})
+
+	it('should throw an error when trying to add a child with a duplicate ID', () => {
+		const parentState = editor.root.children!['parent'] as ParentState
+
+		// Initially should have one child
+		expect(Object.keys(parentState.children!)).toHaveLength(1)
+		expect(parentState.children!['child1']).toBeDefined()
+
+		// Should throw an error when trying to add a child with the same ID
+		expect(() => {
+			parentState.addChild(ChildState1)
+		}).toThrow("StateNode.addChild: a child with id 'child1' already exists")
+
+		// Should still have only one child
+		expect(Object.keys(parentState.children!)).toHaveLength(1)
+		expect(parentState.children!['child1']).toBeDefined()
+	})
+
+	it('should throw an error when trying to add a child with a duplicate ID to a root state', () => {
+		const rootState = editor.root.children!['root'] as RootState
+
+		// Initially should have one child
+		expect(Object.keys(rootState.children!)).toHaveLength(1)
+		expect(rootState.children!['child1']).toBeDefined()
+
+		// Should throw an error when trying to add a child with the same ID
+		expect(() => {
+			rootState.addChild(ChildState1)
+		}).toThrow("StateNode.addChild: a child with id 'child1' already exists")
+
+		// Should still have only one child
+		expect(Object.keys(rootState.children!)).toHaveLength(1)
+		expect(rootState.children!['child1']).toBeDefined()
+	})
+
+	it('should throw an error when trying to add a child with a duplicate ID to a root state without static children', () => {
+		// Create a StateNode directly as a root node (no parent)
+		const mockEditor = {} as Editor
+		const rootStateWithoutChildren = new RootStateWithoutChildren(mockEditor, undefined)
+
+		// Add a child first
+		rootStateWithoutChildren.addChild(ChildState1)
+
+		// Should throw an error when trying to add a child with the same ID
+		expect(() => {
+			rootStateWithoutChildren.addChild(ChildState1)
+		}).toThrow("StateNode.addChild: a child with id 'child1' already exists")
+
+		// Should still have only one child
+		expect(Object.keys(rootStateWithoutChildren.children!)).toHaveLength(1)
+		expect(rootStateWithoutChildren.children!['child1']).toBeDefined()
+	})
+})
+
+describe('current tool id mask', () => {
+	// Tool mask test classes
+	class ToolA extends StateNode {
+		static override id = 'A'
+	}
+
+	class ToolB extends StateNode {
+		static override id = 'B'
+	}
+
+	class ToolC extends StateNode {
+		static override id = 'C'
+
+		override onEnter() {
+			this.setCurrentToolIdMask('A')
+		}
+	}
+
+	let toolMaskEditor: Editor
+
+	beforeEach(() => {
+		toolMaskEditor = new Editor({
+			initialState: 'A',
+			shapeUtils: [],
+			bindingUtils: [],
+			tools: [ToolA, ToolB, ToolC],
+			store: createTLStore({ shapeUtils: [], bindingUtils: [] }),
+			getContainer: () => document.body,
+		})
+	})
+
+	it('starts with the correct tool id', () => {
+		expect(toolMaskEditor.getCurrentToolId()).toBe('A')
+	})
+
+	it('updates the current tool id', () => {
+		toolMaskEditor.setCurrentTool('B')
+		expect(toolMaskEditor.getCurrentToolId()).toBe('B')
+	})
+
+	it('masks the current tool id', () => {
+		toolMaskEditor.setCurrentTool('C')
+		expect(toolMaskEditor.getCurrentToolId()).toBe('A')
+	})
+})

packages/editor/src/lib/editor/tools/StateNode.ts

@@ -62,7 +62,7 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
 
 		this.parent = parent ?? ({} as any)
 
-		if (this.parent) {
+		if (parent) {
 			if (children && initial) {
 				this.type = 'branch'
 				this.initial = initial
@@ -238,6 +238,32 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
 		this._currentToolIdMask.set(id)
 	}
 
+	/**
+	 * Add a child node to this state node.
+	 *
+	 * @public
+	 */
+	addChild(childConstructor: TLStateNodeConstructor): this {
+		if (this.type === 'leaf') {
+			throw new Error('StateNode.addChild: cannot add child to a leaf node')
+		}
+
+		// Initialize children if it's undefined (for root nodes without static children)
+		if (!this.children) {
+			this.children = {}
+		}
+
+		const child = new childConstructor(this.editor, this)
+
+		// Check if a child with this ID already exists
+		if (this.children[child.id]) {
+			throw new Error(`StateNode.addChild: a child with id '${child.id}' already exists`)
+		}
+
+		this.children[child.id] = child
+		return this
+	}
+
 	onWheel?(info: TLWheelEventInfo): void
 	onPointerDown?(info: TLPointerEventInfo): void
 	onPointerMove?(info: TLPointerEventInfo): void