@tldraw/editor 3.16.0-canary.ca347c5375a5 → 3.16.0-canary.da3348c13973

package/src/lib/editor/Editor.ts

@@ -176,6 +176,7 @@ import {
 	RequiredKeys,
 	TLCameraMoveOptions,
 	TLCameraOptions,
+	TLGetShapeAtPointOptions,
 	TLImageExportOptions,
 	TLSvgExportOptions,
 	TLUpdatePointerOptions,
@@ -5154,20 +5155,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 	 *
 	 * @returns The shape at the given point, or undefined if there is no shape at the point.
 	 */
-	getShapeAtPoint(
-		point: VecLike,
-		opts = {} as {
-			renderingOnly?: boolean
-			margin?: number
-			hitInside?: boolean
-			hitLocked?: boolean
-			// TODO: we probably need to rename this, we don't quite _always_
-			// respect this esp. in the part below that does "Check labels first"
-			hitLabels?: boolean
-			hitFrameInside?: boolean
-			filter?(shape: TLShape): boolean
-		}
-	): TLShape | undefined {
+	getShapeAtPoint(point: VecLike, opts: TLGetShapeAtPointOptions = {}): TLShape | undefined {
 		const zoomLevel = this.getZoomLevel()
 		const viewportPageBounds = this.getViewportPageBounds()
 		const {
@@ -5179,6 +5167,8 @@ export class Editor extends EventEmitter<TLEventMap> {
 			hitFrameInside = false,
 		} = opts
 
+		const [innerMargin, outerMargin] = Array.isArray(margin) ? margin : [margin, margin]
+
 		let inHollowSmallestArea = Infinity
 		let inHollowSmallestAreaHit: TLShape | null = null
 
@@ -5198,7 +5188,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 				return false
 			const pageMask = this.getShapeMask(shape)
 			if (pageMask && !pointInPolygon(point, pageMask)) return false
-			if (filter) return filter(shape)
+			if (filter && !filter(shape)) return false
 			return true
 		})
 
@@ -5224,13 +5214,18 @@ export class Editor extends EventEmitter<TLEventMap> {
 				}
 			}
 
-			if (this.isShapeOfType(shape, 'frame')) {
+			if (this.isShapeOfType<TLFrameShape>(shape, 'frame')) {
 				// On the rare case that we've hit a frame (not its label), test again hitInside to be forced true;
 				// this prevents clicks from passing through the body of a frame to shapes behind it.
 
 				// If the hit is within the frame's outer margin, then select the frame
-				const distance = geometry.distanceToPoint(pointInShapeSpace, hitInside)
-				if (Math.abs(distance) <= margin) {
+				const distance = geometry.distanceToPoint(pointInShapeSpace, hitFrameInside)
+				if (
+					hitFrameInside
+						? (distance > 0 && distance <= outerMargin) ||
+							(distance <= 0 && distance > -innerMargin)
+						: distance > 0 && distance <= outerMargin
+				) {
 					return inMarginClosestToEdgeHit || shape
 				}
 
@@ -5269,11 +5264,11 @@ export class Editor extends EventEmitter<TLEventMap> {
 				// If the margin is zero and the geometry has a very small width or height,
 				// then check the actual distance. This is to prevent a bug where straight
 				// lines would never pass the broad phase (point-in-bounds) check.
-				if (margin === 0 && (geometry.bounds.w < 1 || geometry.bounds.h < 1)) {
+				if (outerMargin === 0 && (geometry.bounds.w < 1 || geometry.bounds.h < 1)) {
 					distance = geometry.distanceToPoint(pointInShapeSpace, hitInside)
 				} else {
 					// Broad phase
-					if (geometry.bounds.containsPoint(pointInShapeSpace, margin)) {
+					if (geometry.bounds.containsPoint(pointInShapeSpace, outerMargin)) {
 						// Narrow phase (actual distance)
 						distance = geometry.distanceToPoint(pointInShapeSpace, hitInside)
 					} else {
@@ -5288,7 +5283,8 @@ export class Editor extends EventEmitter<TLEventMap> {
 				// the shape or negative if inside of the shape. If the distance
 				// is greater than the margin, then it's a miss. Otherwise...
 
-				if (distance <= margin) {
+				// Are we close to the shape's edge?
+				if (distance <= outerMargin || (hitInside && distance <= 0 && distance > -innerMargin)) {
 					if (geometry.isFilled || (isGroup && geometry.children[0].isFilled)) {
 						// If the shape is filled, then it's a hit. Remember, we're
 						// starting from the TOP-MOST shape in z-index order, so any
@@ -5298,11 +5294,21 @@ export class Editor extends EventEmitter<TLEventMap> {
 						// If the shape is bigger than the viewport, then skip it.
 						if (this.getShapePageBounds(shape)!.contains(viewportPageBounds)) continue
 
-						// For hollow shapes...
-						if (Math.abs(distance) < margin) {
-							// We want to preference shapes where we're inside of the
-							// shape margin; and we would want to hit the shape with the
-							// edge closest to the point.
+						// If we're close to the edge of the shape, and if it's the closest edge among
+						// all the edges that we've gotten close to so far, then we will want to hit the
+						// shape unless we hit something else or closer in later iterations.
+						if (
+							hitInside
+								? // On hitInside, the distance will be negative for hits inside
+									// If the distance is positive, check against the outer margin
+									(distance > 0 && distance <= outerMargin) ||
+									// If the distance is negative, check against the inner margin
+									(distance <= 0 && distance > -innerMargin)
+								: // If hitInside is false, then sadly _we do not know_ whether the
+									// point is inside or outside of the shape, so we check against
+									// the max of the two margins
+									Math.abs(distance) <= Math.max(innerMargin, outerMargin)
+						) {
 							if (Math.abs(distance) < inMarginClosestToEdgeDistance) {
 								inMarginClosestToEdgeDistance = Math.abs(distance)
 								inMarginClosestToEdgeHit = shape
@@ -5324,6 +5330,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 			} else {
 				// For open shapes (e.g. lines or draw shapes) always use the margin.
 				// If the distance is less than the margin, return the shape as the hit.
+				// Use the editor's configurable hit test margin.
 				if (distance < this.options.hitTestMargin / zoomLevel) {
 					return shape
 				}
@@ -7380,7 +7387,6 @@ export class Editor extends EventEmitter<TLEventMap> {
 			if (
 				!this.getShapeUtil(shape).canBeLaidOut?.(shape, {
 					type: 'stretch',
-					shapes: shapesToStretchFirstPass,
 				})
 			) {
 				continue
@@ -7851,25 +7857,32 @@ export class Editor extends EventEmitter<TLEventMap> {
 				) {
 					let parentId: TLParentId = this.getFocusedGroupId()
 
-					for (let i = currentPageShapesSorted.length - 1; i >= 0; i--) {
-						const parent = currentPageShapesSorted[i]
-						const util = this.getShapeUtil(parent)
-						if (
-							util.canReceiveNewChildrenOfType(parent, partial.type) &&
-							!this.isShapeHidden(parent) &&
-							this.isPointInShape(
-								parent,
-								// If no parent is provided, then we can treat the
-								// shape's provided x/y as being in the page's space.
-								{ x: partial.x ?? 0, y: partial.y ?? 0 },
-								{
-									margin: 0,
-									hitInside: true,
-								}
-							)
-						) {
-							parentId = parent.id
-							break
+					const isPositioned = partial.x !== undefined && partial.y !== undefined
+
+					// If the shape has been explicitly positioned, we'll try to find a parent at
+					// that position. If not, we'll assume the user isn't deliberately placing the
+					// shape and the positioning will be handled later by another system.
+					if (isPositioned) {
+						for (let i = currentPageShapesSorted.length - 1; i >= 0; i--) {
+							const parent = currentPageShapesSorted[i]
+							const util = this.getShapeUtil(parent)
+							if (
+								util.canReceiveNewChildrenOfType(parent, partial.type) &&
+								!this.isShapeHidden(parent) &&
+								this.isPointInShape(
+									parent,
+									// If no parent is provided, then we can treat the
+									// shape's provided x/y as being in the page's space.
+									{ x: partial.x ?? 0, y: partial.y ?? 0 },
+									{
+										margin: 0,
+										hitInside: true,
+									}
+								)
+							) {
+								parentId = parent.id
+								break
+							}
 						}
 					}
 

package/src/lib/editor/managers/UserPreferencesManager/UserPreferencesManager.test.ts

@@ -25,6 +25,7 @@ describe('UserPreferencesManager', () => {
 		locale: 'en',
 		animationSpeed: 1,
 		areKeyboardShortcutsEnabled: true,
+		showUiLabels: false,
 		edgeScrollSpeed: 1,
 		colorScheme: 'light',
 		isSnapMode: false,
@@ -231,6 +232,7 @@ describe('UserPreferencesManager', () => {
 				color: mockUserPreferences.color,
 				animationSpeed: mockUserPreferences.animationSpeed,
 				areKeyboardShortcutsEnabled: mockUserPreferences.areKeyboardShortcutsEnabled,
+				showUiLabels: mockUserPreferences.showUiLabels,
 				isSnapMode: mockUserPreferences.isSnapMode,
 				colorScheme: mockUserPreferences.colorScheme,
 				isDarkMode: false, // light mode
@@ -379,6 +381,17 @@ describe('UserPreferencesManager', () => {
 			})
 		})
 
+		describe('getShowUiLabels', () => {
+			it('should return user show ui labels setting', () => {
+				expect(userPreferencesManager.getShowUiLabels()).toBe(mockUserPreferences.showUiLabels)
+			})
+
+			it('should return default show ui labels when null', () => {
+				userPreferencesAtom.set({ ...mockUserPreferences, showUiLabels: null })
+				expect(userPreferencesManager.getShowUiLabels()).toBe(defaultUserPreferences.showUiLabels)
+			})
+		})
+
 		describe('getEdgeScrollSpeed', () => {
 			it('should return user edge scroll speed', () => {
 				expect(userPreferencesManager.getEdgeScrollSpeed()).toBe(

package/src/lib/editor/managers/UserPreferencesManager/UserPreferencesManager.ts

@@ -49,6 +49,7 @@ export class UserPreferencesManager {
 			isDarkMode: this.getIsDarkMode(),
 			isWrapMode: this.getIsWrapMode(),
 			isDynamicResizeMode: this.getIsDynamicResizeMode(),
+			showUiLabels: this.getShowUiLabels(),
 		}
 	}
 
@@ -119,4 +120,8 @@ export class UserPreferencesManager {
 			defaultUserPreferences.isPasteAtCursorMode
 		)
 	}
+
+	@computed getShowUiLabels() {
+		return this.user.userPreferences.get().showUiLabels ?? defaultUserPreferences.showUiLabels
+	}
 }

package/src/lib/editor/types/misc-types.ts

@@ -1,4 +1,4 @@
-import { BoxModel } from '@tldraw/tlschema'
+import { BoxModel, TLShape } from '@tldraw/tlschema'
 import { Box } from '../../primitives/Box'
 import { VecLike } from '../../primitives/Vec'
 
@@ -206,3 +206,56 @@ export interface TLUpdatePointerOptions {
 	isPen?: boolean
 	button?: number
 }
+
+/**
+ * Options to {@link Editor.getShapeAtPoint}.
+ *
+ * @public
+ */
+export interface TLGetShapeAtPointOptions {
+	/**
+	 * The margin to apply to the shape.
+	 * If a number, it will be applied to both the inside and outside of the shape.
+	 * If an array, the first element will be applied to the inside of the shape, and the second element will be applied to the outside.
+	 *
+	 * @example
+	 * ```ts
+	 * // Get the shape at the center of the screen
+	 * const shape = editor.getShapeAtProps({
+	 *   margin: 10,
+	 * })
+	 *
+	 * // Get the shape at the center of the screen with a 10px inner margin and a 5px outer margin
+	 * const shape = editor.getShapeAtProps({
+	 *   margin: [10, 5],
+	 * })
+	 * ```
+	 */
+	margin?: number | [number, number]
+	/**
+	 * Whether to register hits inside of shapes (beyond the margin), such as the inside of a solid shape.
+	 */
+	hitInside?: boolean
+	/**
+	 * Whether to register hits on locked shapes.
+	 */
+	hitLocked?: boolean
+	/**
+	 * Whether to register hits on labels.
+	 */
+	hitLabels?: boolean
+	/**
+	 * Whether to only return hits on shapes that are currently being rendered.
+	 * todo: rename this to hitCulled or hitNotRendering
+	 */
+	renderingOnly?: boolean
+	/**
+	 * Whether to register hits on the inside of frame shapes.
+	 * todo: rename this to hitInsideFrames
+	 */
+	hitFrameInside?: boolean
+	/**
+	 * A filter function to apply to the shapes.
+	 */
+	filter?(shape: TLShape): boolean
+}

package/src/lib/hooks/useCanvasEvents.ts

@@ -1,5 +1,5 @@
 import { useValue } from '@tldraw/state-react'
-import React, { useMemo } from 'react'
+import React, { useEffect, useMemo } from 'react'
 import { RIGHT_MOUSE_BUTTON } from '../constants'
 import {
 	preventDefault,
@@ -16,9 +16,6 @@ export function useCanvasEvents() {
 
 	const events = useMemo(
 		function canvasEvents() {
-			// Track the last screen point
-			let lastX: number, lastY: number
-
 			function onPointerDown(e: React.PointerEvent) {
 				if ((e as any).isKilled) return
 
@@ -44,35 +41,9 @@ export function useCanvasEvents() {
 				})
 			}
 
-			function onPointerMove(e: React.PointerEvent) {
-				if ((e as any).isKilled) return
-
-				if (e.clientX === lastX && e.clientY === lastY) return
-				lastX = e.clientX
-				lastY = e.clientY
-
-				// For tools that benefit from a higher fidelity of events,
-				// we dispatch the coalesced events.
-				// N.B. Sometimes getCoalescedEvents isn't present on iOS, ugh.
-				const events =
-					currentTool.useCoalescedEvents && e.nativeEvent.getCoalescedEvents
-						? e.nativeEvent.getCoalescedEvents()
-						: [e]
-				for (const singleEvent of events) {
-					editor.dispatch({
-						type: 'pointer',
-						target: 'canvas',
-						name: 'pointer_move',
-						...getPointerInfo(singleEvent),
-					})
-				}
-			}
-
 			function onPointerUp(e: React.PointerEvent) {
 				if ((e as any).isKilled) return
 				if (e.button !== 0 && e.button !== 1 && e.button !== 2 && e.button !== 5) return
-				lastX = e.clientX
-				lastY = e.clientY
 
 				releasePointerCapture(e.currentTarget, e)
 
@@ -158,7 +129,6 @@ export function useCanvasEvents() {
 
 			return {
 				onPointerDown,
-				onPointerMove,
 				onPointerUp,
 				onPointerEnter,
 				onPointerLeave,
@@ -169,8 +139,45 @@ export function useCanvasEvents() {
 				onClick,
 			}
 		},
-		[editor, currentTool]
+		[editor]
 	)
 
+	// onPointerMove is special: where we're only interested in the other events when they're
+	// happening _on_ the canvas (as opposed to outside of it, or on UI floating over it), we want
+	// the pointer position to be up to date regardless of whether it's over the tldraw canvas or
+	// not. So instead of returning a listener to be attached to the canvas, we directly attach a
+	// listener to the whole document instead.
+	useEffect(() => {
+		let lastX: number, lastY: number
+
+		function onPointerMove(e: PointerEvent) {
+			if ((e as any).isKilled) return
+			;(e as any).isKilled = true
+
+			if (e.clientX === lastX && e.clientY === lastY) return
+			lastX = e.clientX
+			lastY = e.clientY
+
+			// For tools that benefit from a higher fidelity of events,
+			// we dispatch the coalesced events.
+			// N.B. Sometimes getCoalescedEvents isn't present on iOS, ugh.
+			const events =
+				currentTool.useCoalescedEvents && e.getCoalescedEvents ? e.getCoalescedEvents() : [e]
+			for (const singleEvent of events) {
+				editor.dispatch({
+					type: 'pointer',
+					target: 'canvas',
+					name: 'pointer_move',
+					...getPointerInfo(singleEvent),
+				})
+			}
+		}
+
+		document.body.addEventListener('pointermove', onPointerMove)
+		return () => {
+			document.body.removeEventListener('pointermove', onPointerMove)
+		}
+	}, [editor, currentTool])
+
 	return events
 }

package/src/lib/hooks/useStateAttribute.ts

@@ -0,0 +1,15 @@
+import { react } from '@tldraw/state'
+import { useLayoutEffect } from 'react'
+import { useEditor } from './useEditor'
+
+export function useStateAttribute() {
+	const editor = useEditor()
+
+	// we use a layout effect because we don't want there to be any perceptible delay between the
+	// editor mounting and this attribute being applied, because styles may depend on it:
+	useLayoutEffect(() => {
+		return react('stateAttribute', () => {
+			editor.getContainer().setAttribute('data-state', editor.getPath())
+		})
+	}, [editor])
+}

package/src/lib/options.ts

@@ -53,6 +53,7 @@ export interface TldrawOptions {
 	readonly flattenImageBoundsPadding: number
 	readonly laserDelayMs: number
 	readonly maxExportDelayMs: number
+	readonly tooltipDelayMs: number
 	/**
 	 * How long should previews created by {@link Editor.createTemporaryAssetPreview} last before
 	 * they expire? Defaults to 3 minutes.
@@ -124,6 +125,7 @@ export const defaultTldrawOptions = {
 	flattenImageBoundsPadding: 16,
 	laserDelayMs: 1200,
 	maxExportDelayMs: 5000,
+	tooltipDelayMs: 700,
 	temporaryAssetPreviewLifetimeMs: 180000,
 	actionShortcutsLocation: 'swap',
 	createTextOnCanvasDoubleClick: true,

package/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)
+	}
+}

package/src/version.ts

@@ -1,9 +1,9 @@
 // This file is automatically generated by internal/scripts/refresh-assets.ts.
 // Do not edit manually. Or do, I'm a comment, not a cop.
 
-export const version = '3.16.0-canary.ca347c5375a5'
+export const version = '3.16.0-canary.da3348c13973'
 export const publishDates = {
 	major: '2024-09-13T14:36:29.063Z',
-	minor: '2025-07-30T14:49:37.329Z',
-	patch: '2025-07-30T14:49:37.329Z',
+	minor: '2025-08-08T16:06:35.607Z',
+	patch: '2025-08-08T16:06:35.607Z',
 }