Add example for external UI (#2846)

This PR adds an example for how to add external UI components.

It's something that I've been asked for help with in the past, and it's
something I wish more consumers would do when using tldraw inline - it
would help the editor feel less cramped. Therefore, I'd like to have it
is as an example we can point people to.

![2024-02-19 at 11 53 18 - Maroon
Boar](https://github.com/tldraw/tldraw/assets/15892272/f043bb77-3181-4a7d-b736-2b6a5012e208)

> Some other context:
> We've talked about giving this sorta thing more first-class support in
the future, eg: with a `useEditorInstance` hook or something.

Closes TLD-2128

### Change Type

- [x] `documentation` — Changes to the documentation only[^2]

[^1]: publishes a `patch` release, for devDependencies use `internal`
[^2]: will not publish a new version

### Test Plan

1. Try out the External UI example.
2. Make sure you can change tool by pressing the toolbar buttons.
3. Make sure you can change tool by pressing keys (eg: d, e)

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

### Release Notes

- Docs: Added external UI example.

---------

Co-authored-by: Steve Ruiz <steveruizok@gmail.com>

apps/examples/src/examples/external-ui-context/ExternalUiContextExample.tsx

@@ -0,0 +1,74 @@
+import { Editor, Tldraw, useValue } from '@tldraw/tldraw'
+import '@tldraw/tldraw/tldraw.css'
+import { createContext, useContext, useState } from 'react'
+import './external-ui.css'
+
+// There's a guide at the bottom of this file!
+
+// [1]
+const editorContext = createContext({} as { editor: Editor })
+
+export default function ExternalUiExample2() {
+	const [editor, setEditor] = useState<Editor | null>(null)
+
+	return (
+		<div style={{ margin: 32, width: 600 }}>
+			<div style={{ height: 400 }}>
+				<Tldraw
+					// [2]
+					onMount={(editor) => setEditor(editor)}
+					components={{ Toolbar: null }}
+				/>
+			</div>
+			{/* [3] */}
+			{editor && (
+				<editorContext.Provider value={{ editor }}>
+					<ExternalToolbar />
+				</editorContext.Provider>
+			)}
+		</div>
+	)
+}
+
+// [4]
+const ExternalToolbar = () => {
+	const { editor } = useContext(editorContext)
+
+	const currentToolId = useValue('current tool id', () => editor?.getCurrentToolId(), [editor])
+
+	return (
+		<div>
+			<div className="external-toolbar">
+				<button
+					className="external-button"
+					data-isactive={currentToolId === 'select'}
+					onClick={() => editor.setCurrentTool('select')}
+				>
+					Select
+				</button>
+				<button
+					className="external-button"
+					data-isactive={currentToolId === 'draw'}
+					onClick={() => editor.setCurrentTool('draw')}
+				>
+					Pencil
+				</button>
+			</div>
+		</div>
+	)
+}
+
+/*
+
+[1] 
+Use React context to store the editor at a higher place in the React component tree. 
+
+[2] 
+Use the `onMount` prop to get the editor instance and store it in state.
+
+[3]
+When we have an editor in state, render the context provider and its descendants.
+
+[4]
+You can access the editor from any of the provider's descendants.
+*/

apps/examples/src/examples/external-ui-context/README.md

@@ -0,0 +1,15 @@
+---
+title: External UI (Context)
+component: ./ExternalUiContextExample.tsx
+category: ui
+---
+
+This example shows how to control the tldraw editor from an external UI, outside of the `Tldraw` component. This example shows how to pass a reference
+to the editor around using React Context.
+
+---
+
+This example shows how to control the tldraw editor from an external UI, outside
+of the `Tldraw` component. There are a few ways of doing this—for example, by putting the editor on the window object, passing it around via props, or using React context.
+
+In this example, we use React context to distribute a reference to the editor to child components.

apps/examples/src/examples/external-ui-context/external-ui.css

@@ -0,0 +1,20 @@
+.external-toolbar {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	padding: 8px;
+	gap: 8px;
+}
+
+.external-button {
+	pointer-events: all;
+	padding: 4px 12px;
+	background: white;
+	border: 1px solid black;
+	border-radius: 16px;
+}
+
+.external-button[data-isactive='true'] {
+	background-color: black;
+	color: white;
+}

apps/examples/src/examples/external-ui/ExternalUiExample.tsx

@@ -0,0 +1,56 @@
+import { Editor, Tldraw, useValue } from '@tldraw/tldraw'
+import '@tldraw/tldraw/tldraw.css'
+import { useState } from 'react'
+import './external-ui.css'
+
+// There's a guide at the bottom of this file!
+
+export default function ExternalUiExample() {
+	// [1]
+	const [editor, setEditor] = useState<Editor | null>(null)
+
+	const currentToolId = useValue('current tool id', () => editor?.getCurrentToolId(), [editor])
+
+	return (
+		<div style={{ margin: 32, width: 600 }}>
+			<div style={{ height: 400 }}>
+				<Tldraw
+					// [2]
+					onMount={(editor) => setEditor(editor)}
+					components={{ Toolbar: null }}
+				/>
+			</div>
+			{/* [3] */}
+			<div>
+				<div className="external-toolbar">
+					<button
+						className="external-button"
+						data-isactive={currentToolId === 'select'}
+						onClick={() => editor?.setCurrentTool('select')}
+					>
+						Select
+					</button>
+					<button
+						className="external-button"
+						data-isactive={currentToolId === 'draw'}
+						onClick={() => editor?.setCurrentTool('draw')}
+					>
+						Pencil
+					</button>
+				</div>
+			</div>
+		</div>
+	)
+}
+
+/*
+[1] 
+Use React state to store the editor instance.
+
+[2]
+Use the `onMount` prop to get the editor instance and store it in state.
+
+[3]
+Use data from the editor instance or use the editor's methods to control the editor.
+Note that these callbacks also need to work if the editor isn't mounted yet.
+*/

apps/examples/src/examples/external-ui/README.md

@@ -0,0 +1,14 @@
+---
+title: External UI
+component: ./ExternalUiExample.tsx
+category: ui
+---
+
+This example shows how to control the tldraw editor from an external UI, outside of the `Tldraw` component.
+
+---
+
+This example shows how to control the tldraw editor from an external UI, outside
+of the `Tldraw` component. There are a few ways of doing this—for example, by putting the editor on the window object, passing it around via props, or using React context.
+
+In this example, we'll just put the editor instance in state and use it in the same component. See the External UI Example 2 for an alternative (and more realistic) solution using React context.

apps/examples/src/examples/external-ui/external-ui.css

@@ -0,0 +1,20 @@
+.external-toolbar {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	padding: 8px;
+	gap: 8px;
+}
+
+.external-button {
+	pointer-events: all;
+	padding: 4px 12px;
+	background: white;
+	border: 1px solid black;
+	border-radius: 16px;
+}
+
+.external-button[data-isactive='true'] {
+	background-color: black;
+	color: white;
+}

apps/examples/src/examples/image-component/TldrawImageExample.tsx

@@ -100,8 +100,8 @@ and viewing it.
 
 [2] You can specify which page to display by using the `pageId` prop. By
     default, the first page is shown.
-	
+
 [3] You can customize the appearance of the image by passing other props to the
-		`TldrawImage` component. For example, you can toggle the background, set the
-		dark mode, and specify the viewport bounds.
+        `TldrawImage` component. For example, you can toggle the background, set
+        the dark mode, and specify the viewport bounds.
  */