@tldraw/editor 4.6.0-internal.e29318c66fb0 → 4.6.0-next.0a51207761bb

package/src/lib/TldrawEditor.tsx

@@ -1,5 +1,14 @@
 import { MigrationSequence, Store } from '@tldraw/store'
-import { TLShape, TLStore, TLStoreSnapshot } from '@tldraw/tlschema'
+import {
+	TLShape,
+	TLStore,
+	TLStoreSnapshot,
+	TLTheme,
+	TLThemeId,
+	TLThemes,
+	registerColorsFromThemes,
+	registerFontsFromThemes,
+} from '@tldraw/tlschema'
 import { annotateError, Required } from '@tldraw/utils'
 import classNames from 'classnames'
 import React, {
@@ -16,16 +25,18 @@ import React, {
 import { version } from '../version'
 import { DefaultErrorFallback } from './components/default-components/DefaultErrorFallback'
 import { OptionalErrorBoundary } from './components/ErrorBoundary'
+import { createTLCurrentUser, TLCurrentUser } from './config/createTLCurrentUser'
 import { TLStoreBaseOptions } from './config/createTLStore'
-import { createTLUser, TLUser } from './config/createTLUser'
+import { TLAnyAssetUtilConstructor } from './config/defaultAssets'
 import { TLAnyBindingUtilConstructor } from './config/defaultBindings'
 import { TLAnyShapeUtilConstructor } from './config/defaultShapes'
 import { TLEditorSnapshot } from './config/TLEditorSnapshot'
 import { Editor } from './editor/Editor'
+import { resolveThemes } from './editor/managers/ThemeManager/ThemeManager'
 import { TLStateNodeConstructor } from './editor/tools/StateNode'
 import { TLCameraOptions } from './editor/types/misc-types'
-import type { TLEditorComponents } from './hooks/EditorComponentsContext'
 import { useEditorComponents } from './hooks/EditorComponentsContext'
+import type { TLEditorComponents } from './hooks/EditorComponentsContext'
 import { ContainerProvider, useContainer } from './hooks/useContainer'
 import { useCursor } from './hooks/useCursor'
 import { useDarkMode } from './hooks/useDarkMode'
@@ -121,6 +132,11 @@ export interface TldrawEditorBaseProps {
 	 */
 	bindingUtils?: readonly TLAnyBindingUtilConstructor[]
 
+	/**
+	 * An array of asset utils to use in the editor.
+	 */
+	assetUtils?: readonly TLAnyAssetUtilConstructor[]
+
 	/**
 	 * An array of tools to add to the editor's state chart.
 	 */
@@ -154,12 +170,26 @@ export interface TldrawEditorBaseProps {
 	/**
 	 * The user interacting with the editor.
 	 */
-	user?: TLUser
+	user?: TLCurrentUser
+
+	/**
+	 * The editor's color scheme. Defaults to `'light'`.
+	 *
+	 * - `'light'` - Always use light mode.
+	 * - `'dark'` - Always use dark mode.
+	 * - `'system'` - Follow the OS color scheme preference.
+	 */
+	colorScheme?: 'light' | 'dark' | 'system'
+
+	/**
+	 * Named themes for the editor.
+	 */
+	themes?: Partial<TLThemes>
 
 	/**
-	 * Whether to infer dark mode from the user's OS. Defaults to false.
+	 * The id of the initially active theme. Defaults to `'default'`.
 	 */
-	inferDarkMode?: boolean
+	initialTheme?: TLThemeId
 
 	/**
 	 * Camera options for the editor.
@@ -242,6 +272,7 @@ declare global {
 
 const EMPTY_SHAPE_UTILS_ARRAY = [] as const
 const EMPTY_BINDING_UTILS_ARRAY = [] as const
+const EMPTY_ASSET_UTILS_ARRAY = [] as const
 const EMPTY_TOOLS_ARRAY = [] as const
 /** @internal */
 export const TL_CONTAINER_CLASS = 'tl-container'
@@ -259,8 +290,15 @@ export const TldrawEditor = memo(function TldrawEditor({
 	deepLinks: _deepLinks,
 	...rest
 }: TldrawEditorProps) {
+	// Register custom colors and fonts before effects run. For external stores,
+	// users should also pass themes to createTLStore so they are
+	// registered before data is loaded into the store.
+	const resolvedThemes = resolveThemes(rest.themes)
+	registerColorsFromThemes(resolvedThemes)
+	registerFontsFromThemes(resolvedThemes)
+
 	const [container, setContainer] = useState<HTMLElement | null>(null)
-	const user = useMemo(() => _user ?? createTLUser(), [_user])
+	const user = useMemo(() => _user ?? createTLCurrentUser(), [_user])
 
 	const ErrorFallback =
 		components?.ErrorFallback === undefined ? DefaultErrorFallback : components?.ErrorFallback
@@ -285,6 +323,7 @@ export const TldrawEditor = memo(function TldrawEditor({
 		...rest,
 		shapeUtils: rest.shapeUtils ?? EMPTY_SHAPE_UTILS_ARRAY,
 		bindingUtils: rest.bindingUtils ?? EMPTY_BINDING_UTILS_ARRAY,
+		assetUtils: rest.assetUtils ?? EMPTY_ASSET_UTILS_ARRAY,
 		tools: rest.tools ?? EMPTY_TOOLS_ARRAY,
 		components,
 		options: useShallowObjectIdentity(mergedOptions),
@@ -331,8 +370,8 @@ export const TldrawEditor = memo(function TldrawEditor({
 
 function TldrawEditorWithOwnStore(
 	props: Required<
-		TldrawEditorProps & { store: undefined; user: TLUser },
-		'shapeUtils' | 'bindingUtils' | 'tools'
+		TldrawEditorProps & { store: undefined; user: TLCurrentUser },
+		'shapeUtils' | 'bindingUtils' | 'assetUtils' | 'tools'
 	>
 ) {
 	const {
@@ -341,23 +380,29 @@ function TldrawEditorWithOwnStore(
 		initialData,
 		shapeUtils,
 		bindingUtils,
+		assetUtils,
 		persistenceKey,
 		sessionId,
 		user,
 		assets,
+		users,
 		migrations,
+		themes,
 	} = props
 
 	const syncedStore = useLocalStore({
 		shapeUtils,
 		bindingUtils,
+		assetUtils,
 		initialData,
 		persistenceKey,
 		sessionId,
 		defaultName,
 		snapshot,
 		assets,
+		users,
 		migrations,
+		themes,
 	})
 
 	return <TldrawEditorWithLoadingStore {...props} store={syncedStore} user={user} />
@@ -368,8 +413,8 @@ const TldrawEditorWithLoadingStore = memo(function TldrawEditorBeforeLoading({
 	user,
 	...rest
 }: Required<
-	TldrawEditorProps & { store: TLStoreWithStatus; user: TLUser },
-	'shapeUtils' | 'bindingUtils' | 'tools'
+	TldrawEditorProps & { store: TLStoreWithStatus; user: TLCurrentUser },
+	'shapeUtils' | 'bindingUtils' | 'assetUtils' | 'tools'
 >) {
 	const container = useContainer()
 
@@ -415,22 +460,25 @@ function TldrawEditorWithReadyStore({
 	tools,
 	shapeUtils,
 	bindingUtils,
+	assetUtils,
 	user,
 	initialState,
 	autoFocus = true,
-	inferDarkMode,
 	// eslint-disable-next-line @typescript-eslint/no-deprecated
 	cameraOptions,
 	options,
 	licenseKey,
 	getShapeVisibility,
+	colorScheme,
 	assetUrls,
+	themes,
+	initialTheme,
 }: Required<
 	TldrawEditorProps & {
 		store: TLStore
-		user: TLUser
+		user: TLCurrentUser
 	},
-	'shapeUtils' | 'bindingUtils' | 'tools'
+	'shapeUtils' | 'bindingUtils' | 'assetUtils' | 'tools'
 >) {
 	const { ErrorFallback } = useEditorComponents()
 	const container = useContainer()
@@ -446,44 +494,58 @@ function TldrawEditorWithReadyStore({
 	const editorOptionsRef = useRef({
 		// for these, it's because they're only used when the editor first mounts:
 		autoFocus: autoFocus && !noAutoFocus(),
-		inferDarkMode,
 		initialState,
+		colorScheme,
 
 		// for these, it's because we keep them up to date in a separate effect:
 		cameraOptions,
 		deepLinks,
+		themes,
+		initialTheme,
 	})
 
 	useLayoutEffect(() => {
 		editorOptionsRef.current = {
 			autoFocus: autoFocus && !noAutoFocus(),
-			inferDarkMode,
 			initialState,
+			colorScheme,
 			cameraOptions,
 			deepLinks,
+			themes,
+			initialTheme,
 		}
-	}, [autoFocus, inferDarkMode, initialState, cameraOptions, deepLinks])
+	}, [autoFocus, initialState, colorScheme, cameraOptions, deepLinks, themes, initialTheme])
 
 	useLayoutEffect(
 		() => {
-			const { autoFocus, inferDarkMode, initialState, cameraOptions, deepLinks } =
-				editorOptionsRef.current
+			const {
+				autoFocus,
+				initialState,
+				colorScheme: initColorScheme,
+				cameraOptions,
+				deepLinks,
+				themes,
+				initialTheme,
+			} = editorOptionsRef.current
 			const editor = new Editor({
 				store,
 				shapeUtils,
 				bindingUtils,
+				assetUtils,
 				tools,
 				getContainer: () => container,
 				user,
 				initialState,
 				// we should check for some kind of query parameter that turns off autofocus
 				autoFocus,
-				inferDarkMode,
 				cameraOptions,
 				options,
 				licenseKey,
 				getShapeVisibility,
+				colorScheme: initColorScheme,
 				fontAssetUrls: assetUrls?.fonts,
+				themes: themes,
+				initialTheme: initialTheme,
 			})
 
 			editor.updateViewportScreenBounds(canvasRef.current ?? container)
@@ -508,7 +570,9 @@ function TldrawEditorWithReadyStore({
 		},
 		// if any of these change, we need to recreate the editor.
 		[
+			assetUtils,
 			bindingUtils,
+			colorScheme,
 			container,
 			options,
 			shapeUtils,
@@ -537,6 +601,21 @@ function TldrawEditorWithReadyStore({
 		}
 	}, [editor, cameraOptions, options?.camera])
 
+	// keep the editor up to date with the latest theme definitions
+	useLayoutEffect(() => {
+		if (editor && themes) {
+			for (const def of Object.values(themes) as TLTheme[]) {
+				editor.updateTheme(def)
+			}
+		}
+	}, [editor, themes])
+
+	useLayoutEffect(() => {
+		if (editor && initialTheme) {
+			editor.setCurrentTheme(initialTheme)
+		}
+	}, [editor, initialTheme])
+
 	const crashingError = useSyncExternalStore(
 		useCallback(
 			(onStoreChange) => {

package/src/lib/components/MenuClickCapture.tsx

@@ -42,6 +42,22 @@ export function MenuClickCapture() {
 				}
 				rDidAPointerDownAndDragWhileMenuWasOpen.current = false
 			}
+			if (e.button === 2) {
+				// Swallow the contextmenu event that follows this right-click pointerdown.
+				// clearOpenMenus() below triggers a synchronous render that unmounts this
+				// component, so our React onContextMenu handler won't be around to catch it.
+				// Without this, the contextmenu event reaches the Radix Trigger and briefly
+				// opens a new context menu (which then immediately dismisses — causing a flash).
+				const ownerDocument = editor.getContainerDocument()
+				ownerDocument.addEventListener(
+					'contextmenu',
+					(event) => {
+						event.preventDefault()
+						event.stopImmediatePropagation()
+					},
+					{ capture: true, once: true }
+				)
+			}
 			editor.menus.clearOpenMenus()
 		},
 		[editor]
@@ -117,6 +133,10 @@ export function MenuClickCapture() {
 				onPointerDown={handlePointerDown}
 				onPointerMove={handlePointerMove}
 				onPointerUp={handlePointerUp}
+				onContextMenu={(e) => {
+					e.preventDefault()
+					e.stopPropagation()
+				}}
 			/>
 		)
 	)

package/src/lib/components/default-components/CanvasShapeIndicators.tsx

@@ -6,8 +6,8 @@ import { memo, useEffect, useRef } from 'react'
 import { Editor } from '../../editor/Editor'
 import { TLIndicatorPath } from '../../editor/shapes/ShapeUtil'
 import { getComputedStyle } from '../../exports/domUtils'
+import { useColorMode } from '../../hooks/useColorMode'
 import { useEditor } from '../../hooks/useEditor'
-import { useIsDarkMode } from '../../hooks/useIsDarkMode'
 import { useActivePeerIds$ } from '../../hooks/usePeerIds'
 
 interface CollaboratorIndicatorData {
@@ -133,14 +133,14 @@ export const CanvasShapeIndicators = memo(function CanvasShapeIndicators() {
 
 	// Cache the selected color to avoid getComputedStyle on every render
 	const rSelectedColor = useRef<string | null>(null)
-	const isDarkMode = useIsDarkMode()
+	const colorMode = useColorMode()
 
 	useEffect(() => {
 		const timer = editor.timers.setTimeout(() => {
 			rSelectedColor.current = null
 		}, 0)
 		return () => clearTimeout(timer)
-	}, [isDarkMode, editor])
+	}, [colorMode, editor])
 
 	// Get active peer IDs (already handles time-based state transitions)
 	const activePeerIds$ = useActivePeerIds$()

package/src/lib/components/default-components/DefaultCanvas.tsx

@@ -19,8 +19,8 @@ import { useScreenBounds } from '../../hooks/useScreenBounds'
 import { ShapeCullingProvider, useShapeCulling } from '../../hooks/useShapeCulling'
 import { Box } from '../../primitives/Box'
 import { Mat } from '../../primitives/Mat'
-import { Vec } from '../../primitives/Vec'
 import { toDomPrecision } from '../../primitives/utils'
+import { Vec } from '../../primitives/Vec'
 import { debugFlags } from '../../utils/debug-flags'
 import { setStyleProperty } from '../../utils/dom'
 import { GeometryDebuggingView } from '../GeometryDebuggingView'

package/src/lib/components/default-components/DefaultCollaboratorHint.tsx

@@ -4,8 +4,8 @@ import { useRef } from 'react'
 import { useSharedSafeId } from '../../hooks/useSafeId'
 import { useTransform } from '../../hooks/useTransform'
 import { Box } from '../../primitives/Box'
-import { Vec } from '../../primitives/Vec'
 import { clamp } from '../../primitives/utils'
+import { Vec } from '../../primitives/Vec'
 
 /** @public */
 export interface TLCollaboratorHintProps {

package/src/lib/config/TLEditorSnapshot.test.ts

@@ -2,8 +2,8 @@ import { PageRecordType, TLStore, createShapeId } from '@tldraw/tlschema'
 import { IndexKey } from '@tldraw/utils'
 import { Editor } from '../editor/Editor'
 import { Box } from '../primitives/Box'
-import { TLEditorSnapshot, getSnapshot, loadSnapshot } from './TLEditorSnapshot'
 import { createTLStore } from './createTLStore'
+import { TLEditorSnapshot, getSnapshot, loadSnapshot } from './TLEditorSnapshot'
 
 const createEditor = (store: TLStore) => {
 	return new Editor({

package/src/lib/config/{createTLUser.ts → createTLCurrentUser.ts}

@@ -5,7 +5,7 @@ import { useShallowObjectIdentity } from '../hooks/useIdentity'
 import { TLUserPreferences, getUserPreferences, setUserPreferences } from './TLUserPreferences'
 
 /** @public */
-export interface TLUser {
+export interface TLCurrentUser {
 	readonly userPreferences: Signal<TLUserPreferences>
 	// eslint-disable-next-line tldraw/method-signature-style
 	readonly setUserPreferences: (userPreferences: TLUserPreferences) => void
@@ -16,13 +16,13 @@ const defaultLocalStorageUserPrefs = computed('defaultLocalStorageUserPrefs', ()
 )
 
 /** @public */
-export function createTLUser(
+export function createTLCurrentUser(
 	opts = {} as {
 		userPreferences?: Signal<TLUserPreferences>
 		// eslint-disable-next-line tldraw/method-signature-style
 		setUserPreferences?: (userPreferences: TLUserPreferences) => void
 	}
-): TLUser {
+): TLCurrentUser {
 	return {
 		userPreferences: opts.userPreferences ?? defaultLocalStorageUserPrefs,
 		setUserPreferences: opts.setUserPreferences ?? setUserPreferences,
@@ -32,11 +32,11 @@ export function createTLUser(
 /**
  * @public
  */
-export function useTldrawUser(opts: {
+export function useTldrawCurrentUser(opts: {
 	userPreferences?: Signal<TLUserPreferences> | TLUserPreferences
 	// eslint-disable-next-line tldraw/method-signature-style
 	setUserPreferences?: (userPreferences: TLUserPreferences) => void
-}): TLUser {
+}): TLCurrentUser {
 	const prefs = useShallowObjectIdentity(opts.userPreferences ?? defaultLocalStorageUserPrefs)
 	const userAtom = useAtom<TLUserPreferences | Signal<TLUserPreferences>>('userAtom', prefs)
 	useEffect(() => {
@@ -45,7 +45,7 @@ export function useTldrawUser(opts: {
 
 	return useMemo(
 		() =>
-			createTLUser({
+			createTLCurrentUser({
 				userPreferences: computed('userPreferences', () => {
 					const userStuff = userAtom.get()
 					return isSignal(userStuff) ? userStuff.get() : userStuff

package/src/lib/config/createTLStore.ts

@@ -1,4 +1,4 @@
-import { Signal } from '@tldraw/state'
+import { Signal, computed } from '@tldraw/state'
 import { HistoryEntry, MigrationSequence, SerializedStore, Store, StoreSchema } from '@tldraw/store'
 import {
 	CustomRecordInfo,
@@ -8,13 +8,24 @@ import {
 	TLStore,
 	TLStoreProps,
 	TLStoreSnapshot,
+	TLThemes,
+	TLUser,
+	TLUserStore,
+	UserRecordType,
+	createCachedUserResolve,
 	createTLSchema,
+	createUserId,
+	registerColorsFromThemes,
+	registerFontsFromThemes,
 } from '@tldraw/tlschema'
 import { FileHelpers, assert } from '@tldraw/utils'
 import { Editor } from '../editor/Editor'
-import { TLEditorSnapshot, loadSnapshot } from './TLEditorSnapshot'
+import { resolveThemes } from '../editor/managers/ThemeManager/ThemeManager'
+import { TLAnyAssetUtilConstructor, checkAssets } from './defaultAssets'
 import { TLAnyBindingUtilConstructor, checkBindings } from './defaultBindings'
 import { TLAnyShapeUtilConstructor, checkShapesAndAddCore } from './defaultShapes'
+import { TLEditorSnapshot, loadSnapshot } from './TLEditorSnapshot'
+import { defaultUserPreferences, getUserPreferences } from './TLUserPreferences'
 
 /** @public */
 export interface TLStoreBaseOptions {
@@ -30,6 +41,16 @@ export interface TLStoreBaseOptions {
 	/** How should this store upload & resolve assets? */
 	assets?: TLAssetStore
 
+	/**
+	 * Named theme definitions. When provided, custom color names are automatically
+	 * registered before the store is constructed so persisted data with those
+	 * colors passes validation on load.
+	 */
+	themes?: Partial<TLThemes>
+
+	/** How should this store resolve users for attribution? */
+	users?: TLUserStore
+
 	/** Called when the store is connected to an {@link @tldraw/editor#Editor}. */
 	onMount?(editor: Editor): void | (() => void)
 }
@@ -41,8 +62,9 @@ export type TLStoreSchemaOptions =
 	  }
 	| {
 			shapeUtils?: readonly TLAnyShapeUtilConstructor[]
-			migrations?: readonly MigrationSequence[]
 			bindingUtils?: readonly TLAnyBindingUtilConstructor[]
+			assetUtils?: readonly TLAnyAssetUtilConstructor[]
+			migrations?: readonly MigrationSequence[]
 			records?: Record<string, CustomRecordInfo>
 	  }
 
@@ -61,6 +83,21 @@ export type TLStoreEventInfo = HistoryEntry<TLRecord>
 
 const defaultAssetResolve: NonNullable<TLAssetStore['resolve']> = (asset) => asset.props.src
 
+const _defaultCurrentUser: Signal<TLUser | null> = computed('defaultCurrentUser', () => {
+	const prefs = getUserPreferences()
+	if (!prefs.id) return null
+	return UserRecordType.create({
+		id: createUserId(prefs.id),
+		name: prefs.name ?? '',
+		color: prefs.color ?? defaultUserPreferences.color,
+	})
+})
+
+/** @public */
+export const defaultUserStore: TLUserStore = {
+	currentUser: _defaultCurrentUser,
+}
+
 /** @public */
 export const inlineBase64AssetStore: TLAssetStore = {
 	upload: async (_, file) => {
@@ -90,6 +127,10 @@ export function createTLSchemaFromUtils(
 			'bindingUtils' in opts && opts.bindingUtils
 				? utilsToMap(checkBindings(opts.bindingUtils))
 				: undefined,
+		assets:
+			'assetUtils' in opts && opts.assetUtils
+				? utilsToMap(checkAssets(opts.assetUtils))
+				: undefined,
 		records: 'records' in opts ? opts.records : undefined,
 		migrations: 'migrations' in opts ? opts.migrations : undefined,
 	})
@@ -107,10 +148,15 @@ export function createTLStore({
 	defaultName = '',
 	id,
 	assets = inlineBase64AssetStore,
+	users = defaultUserStore,
 	onMount,
 	collaboration,
+	themes,
 	...rest
 }: TLStoreOptions = {}): TLStore {
+	const resolvedThemes = resolveThemes(themes)
+	registerColorsFromThemes(resolvedThemes)
+	registerFontsFromThemes(resolvedThemes)
 	const schema = createTLSchemaFromUtils(rest)
 
 	const store = new Store({
@@ -124,6 +170,15 @@ export function createTLStore({
 				resolve: assets.resolve ?? defaultAssetResolve,
 				remove: assets.remove ?? (() => Promise.resolve()),
 			},
+			users: {
+				currentUser: users.currentUser,
+				resolve:
+					users.resolve ??
+					createCachedUserResolve((userId) => {
+						const current = users.currentUser.get()
+						return current && current.id === createUserId(userId) ? current : null
+					}),
+			},
 			onMount: (editor) => {
 				assert(editor instanceof Editor)
 				onMount?.(editor)

package/src/lib/config/defaultAssets.ts

@@ -0,0 +1,19 @@
+import { TLAssetUtilConstructor } from '../editor/assets/AssetUtil'
+
+/** @public */
+export type TLAnyAssetUtilConstructor = TLAssetUtilConstructor<any>
+
+export function checkAssets(customAssets: readonly TLAnyAssetUtilConstructor[]) {
+	const assets = [] as TLAnyAssetUtilConstructor[]
+
+	const addedCustomAssetTypes = new Set<string>()
+	for (const customAsset of customAssets) {
+		if (addedCustomAssetTypes.has(customAsset.type)) {
+			throw new Error(`Asset type "${customAsset.type}" is defined more than once`)
+		}
+		assets.push(customAsset)
+		addedCustomAssetTypes.add(customAsset.type)
+	}
+
+	return assets
+}

package/src/lib/config/defaultShapes.ts

@@ -1,5 +1,5 @@
-import { TLShapeUtilConstructor } from '../editor/shapes/ShapeUtil'
 import { GroupShapeUtil } from '../editor/shapes/group/GroupShapeUtil'
+import { TLShapeUtilConstructor } from '../editor/shapes/ShapeUtil'
 
 /** @public */
 export type TLAnyShapeUtilConstructor = TLShapeUtilConstructor<any>