@tldraw/editor 4.6.0-next.0eb36d65eec3 → 4.6.0-next.1a05e8ec7833

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

@@ -1,6 +1,6 @@
 import { atom } from '@tldraw/state'
 import { Mocked, vi } from 'vitest'
-import { TLUser } from '../../../config/createTLUser'
+import { TLCurrentUser } from '../../../config/createTLCurrentUser'
 import { TLUserPreferences, defaultUserPreferences } from '../../../config/TLUserPreferences'
 import { UserPreferencesManager } from './UserPreferencesManager'
 
@@ -9,7 +9,7 @@ const mockMatchMedia = vi.fn()
 window.matchMedia = mockMatchMedia
 
 describe('UserPreferencesManager', () => {
-	let mockUser: Mocked<TLUser>
+	let mockUser: Mocked<TLCurrentUser>
 	let mockUserPreferences: TLUserPreferences
 	let userPreferencesAtom: any
 	let userPreferencesManager: UserPreferencesManager
@@ -61,7 +61,7 @@ describe('UserPreferencesManager', () => {
 			// Test when window.matchMedia is not available
 			delete (window as any).matchMedia
 
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 
 			expect(userPreferencesManager.systemColorScheme.get()).toBe('light')
 
@@ -76,7 +76,7 @@ describe('UserPreferencesManager', () => {
 				removeEventListener: vi.fn(),
 			})
 
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 
 			expect(userPreferencesManager.systemColorScheme.get()).toBe('light')
 		})
@@ -88,7 +88,7 @@ describe('UserPreferencesManager', () => {
 				removeEventListener: vi.fn(),
 			})
 
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'system')
 
 			expect(userPreferencesManager.systemColorScheme.get()).toBe('dark')
 		})
@@ -103,7 +103,7 @@ describe('UserPreferencesManager', () => {
 				removeEventListener: mockRemoveEventListener,
 			})
 
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'system')
 
 			expect(mockAddEventListener).toHaveBeenCalledWith('change', expect.any(Function))
 		})
@@ -123,7 +123,7 @@ describe('UserPreferencesManager', () => {
 				removeEventListener: vi.fn(),
 			})
 
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'system')
 
 			expect(userPreferencesManager.systemColorScheme.get()).toBe('light')
 
@@ -141,7 +141,7 @@ describe('UserPreferencesManager', () => {
 			delete (global as any).window
 
 			expect(() => {
-				userPreferencesManager = new UserPreferencesManager(mockUser, false)
+				userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 			}).not.toThrow()
 
 			global.window = originalWindow
@@ -158,14 +158,14 @@ describe('UserPreferencesManager', () => {
 				removeEventListener: mockRemoveEventListener,
 			})
 
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'system')
 			userPreferencesManager.dispose()
 
 			expect(mockRemoveEventListener).toHaveBeenCalledWith('change', expect.any(Function))
 		})
 
 		it('should call all disposables', () => {
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 
 			const mockDisposable1 = vi.fn()
 			const mockDisposable2 = vi.fn()
@@ -182,7 +182,7 @@ describe('UserPreferencesManager', () => {
 
 	describe('updateUserPreferences', () => {
 		beforeEach(() => {
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 		})
 
 		it('should update user preferences with partial data', () => {
@@ -216,7 +216,7 @@ describe('UserPreferencesManager', () => {
 
 	describe('getUserPreferences', () => {
 		beforeEach(() => {
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 		})
 
 		it('should return complete user preferences with computed values', () => {
@@ -255,7 +255,7 @@ describe('UserPreferencesManager', () => {
 
 	describe('getIsDarkMode', () => {
 		beforeEach(() => {
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 		})
 
 		it('should return true when colorScheme is dark', () => {
@@ -282,24 +282,18 @@ describe('UserPreferencesManager', () => {
 			expect(userPreferencesManager.getIsDarkMode()).toBe(true)
 		})
 
-		it('should use inferDarkMode when colorScheme is undefined', () => {
+		it('should default to light when colorScheme is undefined', () => {
 			userPreferencesAtom.set({ ...mockUserPreferences, colorScheme: undefined })
 
-			// With inferDarkMode = true
-			const managerWithInfer = new UserPreferencesManager(mockUser, true)
-			managerWithInfer.systemColorScheme.set('dark')
-			expect(managerWithInfer.getIsDarkMode()).toBe(true)
-
-			// With inferDarkMode = false
-			const managerWithoutInfer = new UserPreferencesManager(mockUser, false)
-			managerWithoutInfer.systemColorScheme.set('dark')
-			expect(managerWithoutInfer.getIsDarkMode()).toBe(false)
+			const manager = new UserPreferencesManager(mockUser, 'light')
+			manager.systemColorScheme.set('dark')
+			expect(manager.getIsDarkMode()).toBe(false)
 		})
 	})
 
 	describe('individual preference getters', () => {
 		beforeEach(() => {
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 		})
 
 		describe('getId', () => {
@@ -499,7 +493,7 @@ describe('UserPreferencesManager', () => {
 
 	describe('reactive behavior', () => {
 		beforeEach(() => {
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 		})
 
 		it('should react to user preferences changes', () => {
@@ -533,7 +527,7 @@ describe('UserPreferencesManager', () => {
 
 	describe('edge cases and error handling', () => {
 		beforeEach(() => {
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 		})
 
 		it('should handle undefined user preferences gracefully', () => {
@@ -589,14 +583,14 @@ describe('UserPreferencesManager', () => {
 			mockMatchMedia.mockReturnValue(null)
 
 			expect(() => {
-				userPreferencesManager = new UserPreferencesManager(mockUser, false)
+				userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 			}).not.toThrow()
 
 			expect(userPreferencesManager.systemColorScheme.get()).toBe('light')
 		})
 
 		it('should handle dispose gracefully in all cases', () => {
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 
 			// Should not throw even if dispose is called multiple times
 			expect(() => userPreferencesManager.dispose()).not.toThrow()
@@ -608,7 +602,7 @@ describe('UserPreferencesManager', () => {
 			const originalWindow = global.window
 			delete (global as any).window
 
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 
 			expect(() => userPreferencesManager.dispose()).not.toThrow()
 			expect(userPreferencesManager.disposables.size).toBe(0)
@@ -619,7 +613,7 @@ describe('UserPreferencesManager', () => {
 
 	describe('integration scenarios', () => {
 		it('should work with real-world preference scenarios', () => {
-			userPreferencesManager = new UserPreferencesManager(mockUser, true)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 
 			// User starts with system preference
 			userPreferencesManager.updateUserPreferences({ colorScheme: 'system' })
@@ -641,7 +635,7 @@ describe('UserPreferencesManager', () => {
 		})
 
 		it('should handle preference updates with multiple fields', () => {
-			userPreferencesManager = new UserPreferencesManager(mockUser, false)
+			userPreferencesManager = new UserPreferencesManager(mockUser, 'light')
 
 			const updates = {
 				name: 'New User',

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

@@ -1,5 +1,5 @@
 import { atom, computed } from '@tldraw/state'
-import { TLUser } from '../../../config/createTLUser'
+import { TLCurrentUser } from '../../../config/createTLCurrentUser'
 import { TLUserPreferences, defaultUserPreferences } from '../../../config/TLUserPreferences'
 import { getGlobalWindow } from '../../../utils/dom'
 
@@ -11,8 +11,8 @@ export class UserPreferencesManager {
 		this.disposables.forEach((d) => d())
 	}
 	constructor(
-		private readonly user: TLUser,
-		private readonly inferDarkMode: boolean
+		private readonly user: TLCurrentUser,
+		private readonly colorScheme: 'light' | 'dark' | 'system'
 	) {
 		if (typeof window === 'undefined' || !getGlobalWindow().matchMedia) return
 
@@ -57,7 +57,9 @@ export class UserPreferencesManager {
 	}
 
 	@computed getIsDarkMode() {
-		switch (this.user.userPreferences.get().colorScheme) {
+		const userColorScheme = this.user.userPreferences.get().colorScheme
+		const scheme = userColorScheme ?? this.colorScheme
+		switch (scheme) {
 			case 'dark':
 				return true
 			case 'light':
@@ -65,7 +67,7 @@ export class UserPreferencesManager {
 			case 'system':
 				return this.systemColorScheme.get() === 'dark'
 			default:
-				return this.inferDarkMode ? this.systemColorScheme.get() === 'dark' : false
+				return false
 		}
 	}
 

package/src/lib/editor/shapes/BaseFrameLikeShapeUtil.tsx

@@ -0,0 +1,121 @@
+import { TLShape, TLShapeId } from '@tldraw/tlschema'
+import { IndexKey, compact } from '@tldraw/utils'
+import { Vec } from '../../primitives/Vec'
+import { BaseBoxShapeUtil, TLBaseBoxShape } from './BaseBoxShapeUtil'
+import { TLDragShapesInInfo, TLDragShapesOutInfo } from './ShapeUtil'
+
+/**
+ * A base class for frame-like shapes — containers that clip their children,
+ * require full-brush selection, block erasure from inside, and support
+ * drag-and-drop reparenting.
+ *
+ * Extending this class is the easiest way to create a custom frame-like shape.
+ * It provides sensible defaults for all frame-like behaviors:
+ *
+ * - `isFrameLike()` returns `true`
+ * - `providesBackgroundForChildren()` returns `true`
+ * - `canReceiveNewChildrenOfType()` returns `true` unless the container is locked
+ * - `getClipPath()` returns the shape geometry's vertices
+ * - `onDragShapesIn()` reparents shapes into the frame (with index restoration)
+ * - `onDragShapesOut()` reparents shapes back to the page
+ *
+ * All methods can be overridden for custom behavior.
+ *
+ * @example
+ * ```ts
+ * class MyContainerUtil extends BaseFrameLikeShapeUtil<MyContainerShape> {
+ *   static override type = 'my-container' as const
+ *   static override props = myContainerShapeProps
+ *
+ *   override getDefaultProps() {
+ *     return { w: 300, h: 200 }
+ *   }
+ *
+ *   override component(shape: MyContainerShape) {
+ *     return <SVGContainer>...</SVGContainer>
+ *   }
+ *
+ *   override indicator(shape: MyContainerShape) {
+ *     return <rect width={shape.props.w} height={shape.props.h} />
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export abstract class BaseFrameLikeShapeUtil<
+	Shape extends TLBaseBoxShape,
+> extends BaseBoxShapeUtil<Shape> {
+	override isFrameLike(_shape: Shape): boolean {
+		return true
+	}
+
+	override providesBackgroundForChildren(): boolean {
+		return true
+	}
+
+	override canReceiveNewChildrenOfType(shape: Shape, _type: TLShape['type']): boolean {
+		return !shape.isLocked
+	}
+
+	override getClipPath(shape: Shape): Vec[] | undefined {
+		return this.editor.getShapeGeometry(shape.id).vertices
+	}
+
+	override onDragShapesIn(
+		shape: Shape,
+		draggingShapes: TLShape[],
+		{ initialParentIds, initialIndices }: TLDragShapesInInfo
+	): void {
+		const { editor } = this
+
+		if (draggingShapes.every((s) => s.parentId === shape.id)) return
+
+		// Check to see whether any of the shapes can have their old index restored
+		let canRestoreOriginalIndices = false
+		const previousChildren = draggingShapes.filter(
+			(s) => shape.id === (initialParentIds.get(s.id) as TLShapeId)
+		)
+
+		if (previousChildren.length > 0) {
+			const currentChildren = compact(
+				editor.getSortedChildIdsForParent(shape).map((id) => editor.getShape(id))
+			)
+			if (previousChildren.every((s) => !currentChildren.find((c) => c.index === s.index))) {
+				canRestoreOriginalIndices = true
+			}
+		}
+
+		// If any of the children are the ancestor of the frame, quit here
+		if (draggingShapes.some((s) => editor.hasAncestor(shape, s.id))) return
+
+		editor.reparentShapes(draggingShapes, shape.id)
+
+		if (canRestoreOriginalIndices) {
+			for (const s of previousChildren) {
+				editor.updateShape({
+					id: s.id,
+					type: s.type,
+					index: initialIndices.get(s.id) as IndexKey,
+				})
+			}
+		}
+	}
+
+	override onDragShapesOut(
+		shape: Shape,
+		draggingShapes: TLShape[],
+		info: TLDragShapesOutInfo
+	): void {
+		const { editor } = this
+		// When a user drags shapes out and we're not dragging into a new shape,
+		// reparent the dragging shapes onto the current page instead
+		if (!info.nextDraggingOverShapeId) {
+			// Locked shapes are already filtered out upstream by DragAndDropManager.
+			editor.reparentShapes(
+				draggingShapes.filter((s) => s.parentId === shape.id),
+				editor.getCurrentPageId()
+			)
+		}
+	}
+}

package/src/lib/editor/shapes/ShapeUtil.ts

@@ -3,6 +3,7 @@ import { EMPTY_ARRAY } from '@tldraw/state'
 import { LegacyMigrations, MigrationSequence } from '@tldraw/store'
 import {
 	RecordProps,
+	TLAsset,
 	TLHandle,
 	TLParentId,
 	TLPropsMigrations,
@@ -11,14 +12,15 @@ import {
 	TLShapeId,
 	TLShapePartial,
 	TLUnknownShape,
+	VecModel,
 } from '@tldraw/tlschema'
+import { TLFontFace } from '@tldraw/tlschema'
 import { IndexKey } from '@tldraw/utils'
 import { ReactElement } from 'react'
 import { Box, SelectionHandle } from '../../primitives/Box'
 import { Geometry2d } from '../../primitives/geometry/Geometry2d'
 import { Vec } from '../../primitives/Vec'
 import type { Editor } from '../Editor'
-import { TLFontFace } from '../managers/FontManager/FontManager'
 import { BoundsSnapGeometry } from '../managers/SnapManager/BoundsSnaps'
 import { HandleSnapGeometry } from '../managers/SnapManager/HandleSnaps'
 import { TLClickEventInfo } from '../types/event-types'
@@ -31,6 +33,7 @@ export interface TLShapeUtilConstructor<T extends TLShape, U extends ShapeUtil<T
 	type: T['type']
 	props?: RecordProps<T>
 	migrations?: LegacyMigrations | TLPropsMigrations | MigrationSequence
+	handledAssetTypes?: readonly string[]
 }
 
 /**
@@ -168,6 +171,16 @@ export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
 	 */
 	static type: string
 
+	/**
+	 * The asset types that this shape can be created from.
+	 * When a file is dropped on the canvas, the editor finds the shape util
+	 * whose `handledAssetTypes` includes the asset's type and calls
+	 * {@link ShapeUtil.createShapeForAsset} to produce the shape.
+	 *
+	 * @public
+	 */
+	static handledAssetTypes?: readonly string[]
+
 	/**
 	 * Get the default props for a shape.
 	 *
@@ -175,6 +188,18 @@ export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
 	 */
 	abstract getDefaultProps(): Shape['props']
 
+	/**
+	 * Create a shape partial for placing an asset on the canvas.
+	 * Only called for shapes whose constructor declares matching
+	 * {@link ShapeUtil.handledAssetTypes | `handledAssetTypes`}.
+	 *
+	 * @param asset - The asset to create a shape for.
+	 * @param position - Where to place the shape.
+	 * @returns A shape partial, or null if this shape can't be created for the asset.
+	 * @public
+	 */
+	createShapeForAsset?(asset: TLAsset, position: VecModel): TLShapePartial | null
+
 	/**
 	 * Get the shape's geometry.
 	 *
@@ -276,7 +301,7 @@ export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
 	 *
 	 * @public
 	 */
-	canBind(_opts: TLShapeUtilCanBindOpts): boolean {
+	canBind(opts: TLShapeUtilCanBindOpts): boolean {
 		return true
 	}
 
@@ -467,6 +492,17 @@ export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
 		return false
 	}
 
+	/**
+	 * Whether the shape behaves like a frame — a container that has child shapes,
+	 * requires full-brush selection, blocks erasure from inside, etc.
+	 *
+	 * @param shape - The shape.
+	 * @public
+	 */
+	isFrameLike(_shape: Shape): boolean {
+		return false
+	}
+
 	/**
 	 * By default, the bounds of an image export are the bounds of all the shapes it contains, plus
 	 * some padding. If an export includes a shape where `isExportBoundsContainer` is true, then the
@@ -526,7 +562,7 @@ export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
 	 * @param type - The shape type.
 	 * @public
 	 */
-	canReceiveNewChildrenOfType(shape: Shape, _type: TLShape['type']) {
+	canReceiveNewChildrenOfType(shape: Shape, type: TLShape['type']) {
 		return false
 	}
 
@@ -590,6 +626,17 @@ export abstract class ShapeUtil<Shape extends TLShape = TLShape> {
 		return undefined
 	}
 
+	/**
+	 * Return user IDs referenced in shape-specific props.
+	 * Used when copying shapes to include referenced users on the clipboard.
+	 * Override this if your shape stores user IDs in custom props.
+	 *
+	 * @public
+	 */
+	getReferencedUserIds(shape: Shape): string[] {
+		return EMPTY_ARRAY
+	}
+
 	getAriaDescriptor(shape: Shape): string | undefined {
 		return undefined
 	}

package/src/lib/editor/shapes/group/GroupShapeUtil.tsx

@@ -12,7 +12,7 @@ export class GroupShapeUtil extends ShapeUtil<TLGroupShape> {
 	static override props = groupShapeProps
 	static override migrations = groupShapeMigrations
 
-	override hideSelectionBoundsFg() {
+	override hideSelectionBoundsFg(shape: TLGroupShape) {
 		return true
 	}
 

package/src/lib/editor/shapes/shared/getPerfectDashProps.ts

@@ -43,6 +43,13 @@ export function getPerfectDashProps(
 		}
 	}
 
+	if (style === 'none') {
+		return {
+			strokeDasharray: 'none',
+			strokeDashoffset: 'none',
+		}
+	}
+
 	switch (style) {
 		case 'dashed': {
 			ratio = 1

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

@@ -17,20 +17,6 @@ import {
 	TLWheelEventInfo,
 } from '../types/event-types'
 
-const STATE_NODES_TO_MEASURE = [
-	'brushing',
-	'cropping',
-	'dragging',
-	'dragging_handle',
-	'drawing',
-	'erasing',
-	'lasering',
-	'resizing',
-	'rotating',
-	'scribble_brushing',
-	'translating',
-]
-
 /** @public */
 export interface TLStateNodeConstructor {
 	new (editor: Editor, parent?: StateNode): StateNode
@@ -39,6 +25,7 @@ export interface TLStateNodeConstructor {
 	children?(): TLStateNodeConstructor[]
 	isLockable: boolean
 	useCoalescedEvents: boolean
+	trackPerformance: boolean
 }
 
 /** @public */
@@ -94,6 +81,8 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
 	static children?: () => TLStateNodeConstructor[]
 	static isLockable = true
 	static useCoalescedEvents = false
+	/** Set to `true` in subclasses to emit interaction-start/end performance events when this state is entered/exited. */
+	static trackPerformance = false
 
 	id: string
 	type: 'branch' | 'leaf' | 'root'
@@ -191,8 +180,12 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
 
 	// todo: move this logic into transition
 	enter(info: any, from: string) {
-		if (debugFlags.measurePerformance.get() && STATE_NODES_TO_MEASURE.includes(this.id)) {
-			this.performanceTracker.start(this.id)
+		const track = (this.constructor as TLStateNodeConstructor).trackPerformance
+		if (track) {
+			if (debugFlags.measurePerformance.get()) {
+				this.performanceTracker.start(this.id)
+			}
+			this.editor.performance._notifyInteractionStart(this.id, this.getPath())
 		}
 
 		this._isActive.set(true)
@@ -207,9 +200,14 @@ export abstract class StateNode implements Partial<TLEventHandlers> {
 
 	// todo: move this logic into transition
 	exit(info: any, to: string) {
-		if (debugFlags.measurePerformance.get() && this.performanceTracker.isStarted()) {
-			this.performanceTracker.stop()
+		const track = (this.constructor as TLStateNodeConstructor).trackPerformance
+		if (track) {
+			if (debugFlags.measurePerformance.get() && this.performanceTracker.isStarted()) {
+				this.performanceTracker.stop()
+			}
+			this.editor.performance._notifyInteractionEnd()
 		}
+
 		this._isActive.set(false)
 		this.onExit?.(info, to)
 

package/src/lib/editor/types/SvgExportContext.tsx

@@ -42,6 +42,11 @@ export interface SvgExportContext {
 	 */
 	readonly isDarkMode: boolean
 
+	/**
+	 * The color mode to use for this export.
+	 */
+	readonly colorMode: 'light' | 'dark'
+
 	/**
 	 * The scale of the export - how much CSS pixels will be scaled up/down by.
 	 */

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

@@ -1,5 +1,5 @@
 import { SerializedSchema } from '@tldraw/store'
-import { TLAsset, TLBinding, TLShape, TLShapeId } from '@tldraw/tlschema'
+import { TLAsset, TLBinding, TLShape, TLShapeId, TLUser } from '@tldraw/tlschema'
 
 /** @public */
 export interface TLContent {
@@ -8,4 +8,5 @@ export interface TLContent {
 	rootShapeIds: TLShapeId[]
 	assets: TLAsset[]
 	schema: SerializedSchema
+	users?: TLUser[]
 }

package/src/lib/editor/types/external-content.ts

@@ -60,6 +60,7 @@ export interface TLFileReplaceExternalContent extends TLBaseExternalContent {
 	type: 'file-replace'
 	file: File
 	shapeId: TLShapeId
+	/** @deprecated This field is no longer used by the default handler. It may be removed in a future version. */
 	isImage: boolean
 }