From 077d42c6f970bff321f624ea779c561e52eb2932 Mon Sep 17 00:00:00 2001
From: Steve Ruiz <steveruizok@gmail.com>
Date: Tue, 16 Jul 2024 11:00:02 +0100
Subject: [PATCH] Editor.run docs (#4182)

This PR adds a docs section for `Editor.run`.

### Change type

- [x] `other`
---
 apps/docs/content/docs/editor.mdx        | 64 ++++++++++++++++++++++++
 packages/editor/src/lib/editor/Editor.ts | 11 ++--
 2 files changed, 70 insertions(+), 5 deletions(-)

diff --git a/apps/docs/content/docs/editor.mdx b/apps/docs/content/docs/editor.mdx
index ea889db23..ff0f9be51 100644
--- a/apps/docs/content/docs/editor.mdx
+++ b/apps/docs/content/docs/editor.mdx
@@ -144,6 +144,44 @@ editor.duplicateShapes(editor.getSelectedShapeIds())
 editor.bailToMark('first') // will return to A
 ```
 
+## Running code in context
+
+You can use the [Editor#run] method to run a function inside of a transaction. All changes made during the transaction will be settled at once. This improves performance and avoids unnecessary renders in the user interface.
+
+```ts
+editor.run(() => {
+	editor.createShapes(myShapes)
+	editor.sendToBack(myShapes)
+	editor.selectNone()
+})
+```
+
+You can also use [Editor#run] to execute code with contextual options.
+
+For example, you can use the options to perform actions without effecting the undo / redo history:
+
+```ts
+editor.run(
+	() => {
+		editor.createShapes(myShapes)
+		editor.sendToBack(myShapes)
+		editor.selectNone()
+	},
+	{ history: 'ignore' }
+)
+```
+
+You can also use the options to make changes to locked shapes.
+
+```ts
+editor.run(
+	() => {
+		editor.updateShapes(myLockedShapes)
+	},
+	{ ignoreShapeLock: true }
+)
+```
+
 ## Events
 
 The [Editor](?) class receives events from its [Editor#dispatch](?) method. When the [Editor](?) receives an event, it is first handled internally to update [Editor#inputs](?) and other state before, and then sent into to the editor's state chart.
@@ -603,6 +641,32 @@ You can turn on or off dark mode via the [setUserPreferences](?) method. Note th
 setUserPreferences({ isDarkMode: true })
 ```
 
+### Make changes without effecting the history
+
+You can use the [Editor#run](?) method to make changes without effecting the undo redo history.
+
+```ts
+editor.run(
+	() => {
+		editor.deleteShapes(myLockedShapes)
+	},
+	{ history: 'ignore' }
+)
+```
+
+### Make changes to locked shape
+
+You can use the [Editor#run](?) method to make changes to locked shapes without having to unlock them first.
+
+```ts
+editor.run(
+	() => {
+		editor.deleteShapes(myLockedShapes)
+	},
+	{ ignoreShapeLock: true }
+)
+```
+
 ---
 
 See the [tldraw repository](https://github.com/tldraw/tldraw/tree/main/apps/examples) for an example of how to use tldraw's Editor API to control the editor.
diff --git a/packages/editor/src/lib/editor/Editor.ts b/packages/editor/src/lib/editor/Editor.ts
index 962ad80ba..62ed87b0c 100644
--- a/packages/editor/src/lib/editor/Editor.ts
+++ b/packages/editor/src/lib/editor/Editor.ts
@@ -1059,19 +1059,20 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 * @example
 	 * ```ts
 	 * // updating with
-	 * editor.run({ history: "ignore" }, () => {
+	 * editor.run(() => {
 	 * 	editor.updateShape({ ...myShape, x: 100 })
-	 * })
+	 * }, { history: "ignore" })
 	 *
 	 * // forcing changes / deletions for locked shapes
 	 * editor.toggleLock([myShape])
-	 * editor.run({ ignoreShapeLock: true }, () => {
+	 * editor.run(() => {
 	 * 	editor.updateShape({ ...myShape, x: 100 })
 	 * 	editor.deleteShape(myShape)
-	 * })
+	 * }, { ignoreShapeLock: true }, )
 	 * ```
-	 * @param opts - The options for the batch.
+	 *
 	 * @param fn - The callback function to run.
+	 * @param opts - The options for the batch.
 	 *
 	 *
 	 * @public