docs: update examples on recent changes (tldraw#8737)

Updates the examples pages and readmes based on the changes over the
last couple of months.

Adds in a new example showing how you can add in a color picker and font
picker

Author: angrycaptain19

apps/examples/src/examples/collaboration/sync-private-content/style.css

@@ -12,6 +12,7 @@
 	display: flex;
 	align-items: center;
 	gap: 10px;
+	pointer-events: auto;
 }
 
 .toggle-panel button {

apps/examples/src/examples/configuration/asset-props/README.md

@@ -20,4 +20,4 @@ Control the assets (images, videos, etc.) that can be added to the canvas.
 
 ---
 
-This example demonstrates the `<Tldraw/>` component's props that give you control over assets: which types are allowed, the maximum size, and maximum dimensions.
+This example demonstrates the `<Tldraw/>` component's props that give you control over assets: which types are allowed (image only here), the maximum size (set to 1 MB), and maximum dimensions (no limit).

apps/examples/src/examples/configuration/configure-shape-util/README.md

@@ -20,4 +20,4 @@ Change the behavior of built-in shapes by setting their options.
 
 Some of the builtin tldraw shapes can be customized to behave differently based on your needs. This is done via the `ShapeUtil.configure` function which returns a new version of the shape's util class with custom options specified.
 
-You can see a shape's options by looking at the `options` property of its `ShapeUtil`. For example, the note shape's options are listed at [`NoteShapeOptions`](https://tldraw.dev/reference/tldraw/NoteShapeOptions).
+You can see a shape's options by looking at the `options` property of its `ShapeUtil`. For example, the note shape's options are listed at [`NoteShapeOptions`](https://tldraw.dev/reference/tldraw/NoteShapeOptions). In this example the note shape's options are modified so the note scales as text is added.

apps/examples/src/examples/configuration/custom-embed/CustomEmbedExample.tsx

@@ -3,7 +3,11 @@ import {
 	DEFAULT_EMBED_DEFINITIONS,
 	DefaultEmbedDefinitionType,
 	EmbedShapeUtil,
+	TLComponents,
 	Tldraw,
+	TldrawUiButton,
+	TldrawUiButtonLabel,
+	useActions,
 } from 'tldraw'
 import 'tldraw/tldraw.css'
 
@@ -48,11 +52,32 @@ const customEmbed: CustomEmbedDefinition = {
 const embeds = [...defaultEmbedsToKeep, customEmbed]
 const shapeUtils = [EmbedShapeUtil.configure({ embedDefinitions: embeds })]
 
+// [4]
+function InsertEmbedButton() {
+	const actions = useActions()
+	const insertEmbed = actions['insert-embed']
+	return (
+		<div style={{ pointerEvents: 'all' }}>
+			<TldrawUiButton
+				type="normal"
+				onClick={() => insertEmbed.onSelect('helper-buttons')}
+				style={{ backgroundColor: '#e5e5e5' }}
+			>
+				<TldrawUiButtonLabel>Insert embed</TldrawUiButtonLabel>
+			</TldrawUiButton>
+		</div>
+	)
+}
+
+const components: TLComponents = {
+	TopPanel: InsertEmbedButton,
+}
+
 export default function CustomEmbedExample() {
 	return (
 		<div className="tldraw__editor">
-			{/* [4] */}
-			<Tldraw shapeUtils={shapeUtils} />
+			{/* [5] */}
+			<Tldraw shapeUtils={shapeUtils} components={components} />
 		</div>
 	)
 }
@@ -66,9 +91,12 @@ tldraw has built-in support for embedding content from several popular apps. In
 We will also add support for embedding JSFiddles. Please note that you have to specify an icon that will be displayed in the `EmbedDialog` component.
 
 [3]
-We concatenate the filtered embed definitions with our custom JSFiddle one. 
+We concatenate the filtered embed definitions with our custom JSFiddle one.
 
 [4]
-We configure `EmbedShapeUtil` with our custom embed definitions and pass the configured util via `shapeUtils`.
+For convenience, we add an "Insert embed" button to the editor's top panel. It uses the `useActions` hook to trigger the built-in `insert-embed` action, which opens the same embed dialog you'd get from the menu — a quick way to see the available embed options.
+
+[5]
+We configure `EmbedShapeUtil` with our custom embed definitions and pass the configured util via `shapeUtils`. We also pass our custom `components` to render the button in the `TopPanel` slot.
 
 */

apps/examples/src/examples/configuration/deep-links/README.md

@@ -21,34 +21,36 @@ Allow linking to specific parts of a tldraw canvas.
 
 Deep Links are URLs which point to a specific part of a document. We provide a comprehensive set of tools to help you create and manage deep links in your application.
 
-## The `deepLinks` prop
+## The `deepLinks` option
 
-The highest-level API for managing deep links is the `deepLinks` prop on the `<Tldraw />` component. This prop is designed for manipulating `window.location` to add a search param which tldraw can use to navigate to a specific part of the document.
+The highest-level API for managing deep links is the `deepLinks` option on the `<Tldraw />` component's `options` prop. This option is designed for manipulating `window.location` to add a search param which tldraw can use to navigate to a specific part of the document.
 
 e.g. `https://my-app.com/document-name?d=v1234.-234.3.21`
 
-If you set `deepLinks` to `true` e.g. `<Tldraw deepLinks />` the following default behavior will be enabled:
+If you set `deepLinks` to `true` e.g. `<Tldraw options={{ deepLinks: true }} />` the following default behavior will be enabled:
 
 1. When the editor initializes, before the initial render, it will check the current `window.location` for a search param called `d`. If found, it will try to parse the value of this param as a deep link and navigate to that part of the document.
 2. 500 milliseconds after every time the editor finishes navigating to a new part of the document, it will update `window.location` to add the latest version of the `d` param.
 
-You can customize this behavior by passing a configuration object as the `deepLinks` prop. e.g.
+You can customize this behavior by passing a configuration object as the `deepLinks` option. e.g.
 
 ```tsx
 <Tldraw
-	deepLinks={{
-		// change the param name to `page`
-		paramName: 'page',
-		// only link to the current page
-		getTarget(editor) {
-			return { type: 'page', pageId: editor.getCurrentPageId() }
+	options={{
+		deepLinks: {
+			// change the param name to `page`
+			paramName: 'page',
+			// only link to the current page
+			getTarget(editor) {
+				return { type: 'page', pageId: editor.getCurrentPageId() }
+			},
+			// log the new search params to the console instead of updating `window.location`
+			onChange(url) {
+				console.log('the new search params are', url.searchParams)
+			},
+			// set the debounce interval to 100ms instead of 500ms
+			debounceMs: 100,
 		},
-		// log the new search params to the console instead of updating `window.location`
-		onChange(url) {
-			console.log('the new search params are', url.searchParams)
-		},
-		// set the debounce interval to 100ms instead of 500ms
-		debounceMs: 100,
 	}}
 />
 ```
@@ -106,7 +108,7 @@ editor.navigateToDeepLink()
 
 ### Listening for deep link changes
 
-You can listen for deep link changes with the [`Editor#registerDeepLinkListener`](?) method, which takes the same options as the `deepLinks` prop.
+You can listen for deep link changes with the [`Editor#registerDeepLinkListener`](?) method, which takes the same options as the `deepLinks` option.
 
 ```tsx
 useEffect(() => {
@@ -125,3 +127,7 @@ useEffect(() => {
 	}
 }, [])
 ```
+
+### Trying deep links in this demo
+
+Create a shape on the canvas then pan or zoom. The `d` param in the URL updates as you go. Copy that URL into a new tab to return to the same view later.

apps/examples/src/examples/configuration/resize-note/README.md

@@ -19,4 +19,4 @@ Make the note shape resizable.
 
 ---
 
-The editor's options include alternative resizing behavior for note shapes. Set `resizeMode` to either `none` for the default behavior or `scale` to allow a user to scale the note.
+The editor's options include alternative resizing behavior for note shapes. Set `resizeMode` to either `none` for the default behavior or `scale` to allow a user to scale the note. Here you can drag the note to expand it.

apps/examples/src/examples/data/assets/custom-records/CustomRecordsExample.tsx

@@ -79,23 +79,6 @@ const MarkerOverlay = track(function MarkerOverlay() {
 		.allRecords()
 		.filter((r) => isCustomRecord(MARKER_TYPE, r)) as any as Marker[]
 
-	const addMarker = useCallback(() => {
-		const label = prompt('Marker label:')
-		if (!label) return
-		const center = editor.getViewportScreenCenter()
-		const point = editor.screenToPage(center)
-		editor.store.put([
-			{
-				id: createMarkerId(),
-				typeName: MARKER_TYPE,
-				x: point.x,
-				y: point.y,
-				label,
-				icon: ICONS[Math.floor(Math.random() * ICONS.length)],
-			} as any,
-		])
-	}, [editor])
-
 	return (
 		<>
 			{markers.map((marker) => {
@@ -141,27 +124,48 @@ const MarkerOverlay = track(function MarkerOverlay() {
 					</div>
 				)
 			})}
-			<button
-				onClick={addMarker}
-				style={{
-					position: 'absolute',
-					top: 50,
-					right: 10,
-					zIndex: 1000,
-					padding: '6px 12px',
-					borderRadius: 6,
-					border: '1px solid #ccc',
-					background: 'white',
-					cursor: 'pointer',
-					fontSize: 14,
-				}}
-			>
-				+ Add marker
-			</button>
 		</>
 	)
 })
 
+function AddMarkerButton() {
+	const editor = useEditor()
+
+	const addMarker = useCallback(() => {
+		const label = prompt('Marker label:')
+		if (!label) return
+		const center = editor.getViewportScreenCenter()
+		const point = editor.screenToPage(center)
+		editor.store.put([
+			{
+				id: createMarkerId(),
+				typeName: MARKER_TYPE,
+				x: point.x,
+				y: point.y,
+				label,
+				icon: ICONS[Math.floor(Math.random() * ICONS.length)],
+			} as any,
+		])
+	}, [editor])
+
+	return (
+		<button
+			onClick={addMarker}
+			style={{
+				padding: '6px 12px',
+				borderRadius: 6,
+				border: '1px solid #ccc',
+				background: 'white',
+				cursor: 'pointer',
+				fontSize: 14,
+				pointerEvents: 'all',
+			}}
+		>
+			+ Add marker
+		</button>
+	)
+}
+
 // [6]
 export default function CustomRecordsExample() {
 	const store = useMemo(
@@ -178,6 +182,7 @@ export default function CustomRecordsExample() {
 				store={store}
 				components={{
 					InFrontOfTheCanvas: MarkerOverlay,
+					TopPanel: AddMarkerButton,
 				}}
 			/>
 		</div>

apps/examples/src/examples/data/assets/export-canvas-settings/ExportCanvasImageSettingsExample.tsx

@@ -25,7 +25,10 @@ function ExportCanvasButton() {
 	})
 
 	// [2]
-	const [box, setBox] = useState({ x: 0, y: 0, w: 0, h: 0 })
+	const [box, setBox] = useState(() => {
+		const v = editor.getViewportPageBounds()
+		return { x: Math.round(v.x), y: Math.round(v.y), w: Math.round(v.w), h: Math.round(v.h) }
+	})
 
 	return (
 		<div
@@ -108,10 +111,9 @@ function ExportCanvasButton() {
 					const { blob } = await editor.toImage([...shapeIds], {
 						format: 'png',
 						...opts,
-						// If we have numbers for all of the box values, we can use them as bounds
-						bounds: Object.values(box).every((b) => !Number.isNaN(b))
-							? new Box(box.x, box.y, box.w, box.h)
-							: undefined,
+						// Use the box as bounds when it has a positive width and height;
+						// otherwise let the export auto-fit all shapes.
+						bounds: box.w > 0 && box.h > 0 ? new Box(box.x, box.y, box.w, box.h) : undefined,
 					})
 
 					const link = document.createElement('a')