@tldraw/editor 4.6.0-next.793daa9fe264 → 4.6.0-next.a31a8a6b83f2

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, {
@@ -18,10 +27,12 @@ import { DefaultErrorFallback } from './components/default-components/DefaultErr
 import { OptionalErrorBoundary } from './components/ErrorBoundary'
 import { createTLCurrentUser, TLCurrentUser } from './config/createTLCurrentUser'
 import { TLStoreBaseOptions } from './config/createTLStore'
+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 { useEditorComponents } from './hooks/EditorComponentsContext'
@@ -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.
 	 */
@@ -157,9 +173,23 @@ export interface TldrawEditorBaseProps {
 	user?: TLCurrentUser
 
 	/**
-	 * Whether to infer dark mode from the user's OS. Defaults to false.
+	 * 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.
 	 */
-	inferDarkMode?: boolean
+	colorScheme?: 'light' | 'dark' | 'system'
+
+	/**
+	 * Named themes for the editor.
+	 */
+	themes?: Partial<TLThemes>
+
+	/**
+	 * The id of the initially active theme. Defaults to `'default'`.
+	 */
+	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,6 +290,13 @@ 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 ?? createTLCurrentUser(), [_user])
 
@@ -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),
@@ -332,7 +371,7 @@ export const TldrawEditor = memo(function TldrawEditor({
 function TldrawEditorWithOwnStore(
 	props: Required<
 		TldrawEditorProps & { store: undefined; user: TLCurrentUser },
-		'shapeUtils' | 'bindingUtils' | 'tools'
+		'shapeUtils' | 'bindingUtils' | 'assetUtils' | 'tools'
 	>
 ) {
 	const {
@@ -341,17 +380,20 @@ function TldrawEditorWithOwnStore(
 		initialData,
 		shapeUtils,
 		bindingUtils,
+		assetUtils,
 		persistenceKey,
 		sessionId,
 		user,
 		assets,
 		users,
 		migrations,
+		themes,
 	} = props
 
 	const syncedStore = useLocalStore({
 		shapeUtils,
 		bindingUtils,
+		assetUtils,
 		initialData,
 		persistenceKey,
 		sessionId,
@@ -360,6 +402,7 @@ function TldrawEditorWithOwnStore(
 		assets,
 		users,
 		migrations,
+		themes,
 	})
 
 	return <TldrawEditorWithLoadingStore {...props} store={syncedStore} user={user} />
@@ -371,7 +414,7 @@ const TldrawEditorWithLoadingStore = memo(function TldrawEditorBeforeLoading({
 	...rest
 }: Required<
 	TldrawEditorProps & { store: TLStoreWithStatus; user: TLCurrentUser },
-	'shapeUtils' | 'bindingUtils' | 'tools'
+	'shapeUtils' | 'bindingUtils' | 'assetUtils' | 'tools'
 >) {
 	const container = useContainer()
 
@@ -417,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: TLCurrentUser
 	},
-	'shapeUtils' | 'bindingUtils' | 'tools'
+	'shapeUtils' | 'bindingUtils' | 'assetUtils' | 'tools'
 >) {
 	const { ErrorFallback } = useEditorComponents()
 	const container = useContainer()
@@ -448,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)
@@ -510,7 +570,9 @@ function TldrawEditorWithReadyStore({
 		},
 		// if any of these change, we need to recreate the editor.
 		[
+			assetUtils,
 			bindingUtils,
+			colorScheme,
 			container,
 			options,
 			shapeUtils,
@@ -539,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/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/config/createTLStore.ts

@@ -8,15 +8,20 @@ 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 { 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'
@@ -36,6 +41,13 @@ 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
 
@@ -50,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>
 	  }
 
@@ -114,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,
 	})
@@ -134,8 +151,12 @@ export function createTLStore({
 	users = defaultUserStore,
 	onMount,
 	collaboration,
+	themes,
 	...rest
 }: TLStoreOptions = {}): TLStore {
+	const resolvedThemes = resolveThemes(themes)
+	registerColorsFromThemes(resolvedThemes)
+	registerFontsFromThemes(resolvedThemes)
 	const schema = createTLSchemaFromUtils(rest)
 
 	const store = new Store({

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
+}