@tldraw/tlschema 4.6.0-next.d8328a2dcc3d → 4.6.0-next.e390fde97eab

package/src/migrations.test.ts

@@ -1749,6 +1749,28 @@ describe('Add font size adjustment to notes', () => {
 	})
 })
 
+describe('Make font size adjustment a ratio on notes', () => {
+	const { up, down } = getTestMigration(noteShapeVersions.MakeFontSizeAdjustmentRatio)
+
+	test('up converts zero to 1 (no adjustment)', () => {
+		expect(up({ props: { fontSizeAdjustment: 0 } })).toEqual({
+			props: { fontSizeAdjustment: 1 },
+		})
+	})
+
+	test('up converts non-zero to null (needs recomputation)', () => {
+		expect(up({ props: { fontSizeAdjustment: 18 } })).toEqual({
+			props: { fontSizeAdjustment: null },
+		})
+	})
+
+	test('down works as expected', () => {
+		expect(down({ props: { fontSizeAdjustment: null } })).toEqual({
+			props: { fontSizeAdjustment: 0 },
+		})
+	})
+})
+
 describe('removes can move camera', () => {
 	const { up, down } = getTestMigration(instanceVersions.RemoveCanMoveCamera)
 

package/src/records/TLAsset.ts

@@ -4,20 +4,22 @@ import {
 	createRecordType,
 	RecordId,
 } from '@tldraw/store'
+import { mapObjectMapValues } from '@tldraw/utils'
 import { T } from '@tldraw/validate'
-import { TLBaseAsset } from '../assets/TLBaseAsset'
-import { bookmarkAssetValidator, TLBookmarkAsset } from '../assets/TLBookmarkAsset'
-import { imageAssetValidator, TLImageAsset } from '../assets/TLImageAsset'
-import { TLVideoAsset, videoAssetValidator } from '../assets/TLVideoAsset'
+import { createAssetValidator, TLBaseAsset } from '../assets/TLBaseAsset'
+import { TLBookmarkAsset } from '../assets/TLBookmarkAsset'
+import { TLImageAsset } from '../assets/TLImageAsset'
+import { TLVideoAsset } from '../assets/TLVideoAsset'
+import { SchemaPropsInfo } from '../createTLSchema'
+import { TLPropsMigrations } from '../recordsWithProps'
 import { ExtractShapeByProps } from './TLShape'
 
 /**
- * Union type representing all possible asset types in tldraw.
- * Assets represent external resources like images, videos, or bookmarks that can be referenced by shapes.
+ * The default set of asset types that are available in the editor.
  *
  * @example
  * ```ts
- * const imageAsset: TLAsset = {
+ * const imageAsset: TLDefaultAsset = {
  *   id: 'asset:image123',
  *   typeName: 'asset',
  *   type: 'image',
@@ -26,41 +28,69 @@ import { ExtractShapeByProps } from './TLShape'
  *     w: 800,
  *     h: 600,
  *     mimeType: 'image/jpeg',
- *     isAnimated: false
+ *     isAnimated: false,
+ *     name: 'image.jpg',
  *   },
- *   meta: {}
+ *   meta: {},
  * }
  * ```
  *
  * @public
  */
-export type TLAsset = TLImageAsset | TLVideoAsset | TLBookmarkAsset
+export type TLDefaultAsset = TLImageAsset | TLVideoAsset | TLBookmarkAsset
 
 /**
- * Validator for TLAsset records that ensures runtime type safety.
- * Uses a discriminated union based on the 'type' field to validate different asset types.
+ * A type for an asset that is available in the editor but whose type is
+ * unknown—either one of the editor's default assets or else a custom asset.
+ *
+ * @public
+ */
+export type TLUnknownAsset = TLBaseAsset<string, object>
+
+/** @public */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface TLGlobalAssetPropsMap {}
+
+/** @public */
+// prettier-ignore
+export type TLIndexedAssets = {
+	[K in keyof TLGlobalAssetPropsMap | TLDefaultAsset['type'] as K extends TLDefaultAsset['type']
+		? K extends keyof TLGlobalAssetPropsMap
+			? TLGlobalAssetPropsMap[K] extends null | undefined
+				? never
+				: K
+			: K
+		: K]: K extends TLDefaultAsset['type']
+		? K extends keyof TLGlobalAssetPropsMap
+			? TLBaseAsset<K, TLGlobalAssetPropsMap[K]>
+			: Extract<TLDefaultAsset, { type: K }>
+		: TLBaseAsset<K, TLGlobalAssetPropsMap[K & keyof TLGlobalAssetPropsMap]>
+}
+
+/**
+ * The set of all assets that are available in the editor.
+ *
+ * This is the primary asset type used throughout tldraw. It includes both the
+ * built-in default assets and any custom assets registered via
+ * {@link TLGlobalAssetPropsMap} augmentation.
+ *
+ * You can use this type without a type argument to work with any asset, or pass
+ * a specific asset type string (e.g., `'image'`, `'video'`, `'bookmark'`) to
+ * narrow down to that specific asset type.
  *
  * @example
  * ```ts
- * // Validation happens automatically when assets are stored
- * try {
- *   const validatedAsset = assetValidator.validate(assetData)
- *   store.put([validatedAsset])
- * } catch (error) {
- *   console.error('Asset validation failed:', error.message)
+ * // Register a custom asset type
+ * declare module '@tldraw/tlschema' {
+ *   interface TLGlobalAssetPropsMap {
+ *     file: { name: string; size: number; mimeType: string; src: string | null }
+ *   }
  * }
  * ```
  *
  * @public
  */
-export const assetValidator: T.Validator<TLAsset> = T.model(
-	'asset',
-	T.union('type', {
-		image: imageAssetValidator,
-		video: videoAssetValidator,
-		bookmark: bookmarkAssetValidator,
-	})
-)
+export type TLAsset<K extends keyof TLIndexedAssets = keyof TLIndexedAssets> = TLIndexedAssets[K]
 
 /**
  * Migration version identifiers for asset record schema evolution.
@@ -87,7 +117,7 @@ export const assetVersions = createMigrationIds('com.tldraw.asset', {
  * // Migration is applied automatically when loading old documents
  * const migratedStore = migrator.migrateStoreSnapshot({
  *   schema: oldSchema,
- *   store: oldStoreSnapshot
+ *   store: oldStoreSnapshot,
  * })
  * ```
  *
@@ -117,8 +147,8 @@ export const assetMigrations = createRecordMigrationSequence({
  *   id: 'asset:image123',
  *   type: 'image',
  *   props: {
- *     w: 800 // Only updating width
- *   }
+ *     w: 800, // Only updating width
+ *   },
  * }
  *
  * // Use in asset updates
@@ -137,32 +167,46 @@ export type TLAssetPartial<T extends TLAsset = TLAsset> = T extends T
 	: never
 
 /**
- * Record type definition for TLAsset with validation and default properties.
- * Configures assets as document-scoped records that persist across sessions.
+ * Creates the record type definition for assets based on registered asset schemas.
+ * This function follows the same pattern as `createShapeRecordType` and `createBindingRecordType`.
+ *
+ * @param assets - Record of asset type names to their schema configuration
+ * @returns A configured record type for assets with validation
  *
  * @example
  * ```ts
- * // Create a new asset record
- * const assetRecord = AssetRecordType.create({
- *   id: 'asset:image123',
- *   type: 'image',
- *   props: {
- *     src: 'https://example.com/image.jpg',
- *     w: 800,
- *     h: 600,
- *     mimeType: 'image/jpeg',
- *     isAnimated: false
- *   }
+ * const AssetRecordType = createAssetRecordType({
+ *   image: { migrations: imageAssetMigrations, props: imageAssetProps },
+ *   video: { migrations: videoAssetMigrations, props: videoAssetProps },
+ *   bookmark: { migrations: bookmarkAssetMigrations, props: bookmarkAssetProps },
  * })
- *
- * // Store the asset
- * store.put([assetRecord])
  * ```
  *
+ * @internal
+ */
+export function createAssetRecordType(assets: Record<string, SchemaPropsInfo>) {
+	return createRecordType('asset', {
+		scope: 'document',
+		validator: T.model(
+			'asset',
+			T.union(
+				'type',
+				mapObjectMapValues(assets, (type, { props, meta }) =>
+					createAssetValidator(type, props, meta)
+				)
+			)
+		),
+	}).withDefaultProperties(() => ({
+		meta: {},
+	}))
+}
+
+/**
+ * Record type definition for default TLAsset records with document scope and default metadata.
+ *
  * @public
  */
 export const AssetRecordType = createRecordType<TLAsset>('asset', {
-	validator: assetValidator,
 	scope: 'document',
 }).withDefaultProperties(() => ({
 	meta: {},
@@ -170,27 +214,15 @@ export const AssetRecordType = createRecordType<TLAsset>('asset', {
 
 /**
  * Branded string type for asset record identifiers.
- * Prevents mixing asset IDs with other types of record IDs at compile time.
+ * Prevents mixing asset IDs with other record IDs at compile time.
  *
  * @example
  * ```ts
- * import { createAssetId } from '@tldraw/tlschema'
- *
- * // Create a new asset ID
- * const assetId: TLAssetId = createAssetId()
- *
- * // Use in asset records
- * const asset: TLAsset = {
- *   id: assetId,
- *   // ... other properties
- * }
- *
- * // Reference in shapes
- * const imageShape: TLImageShape = {
+ * const imageShape = {
+ *   type: 'image',
  *   props: {
- *     assetId: assetId,
- *     // ... other properties
- *   }
+ *     assetId: 'asset:image123' as TLAssetId,
+ *   },
  * }
  * ```
  *
@@ -204,22 +236,55 @@ export type TLAssetId = RecordId<TLBaseAsset<any, any>>
  *
  * @example
  * ```ts
- * // Function that works with any asset-based shape
  * function handleAssetShape(shape: TLAssetShape) {
  *   const assetId = shape.props.assetId
- *   if (assetId) {
- *     const asset = editor.getAsset(assetId)
- *     // Handle the asset...
- *   }
+ *   if (!assetId) return
+ *   const asset = editor.getAsset(assetId)
+ *   // Handle the asset...
  * }
- *
- * // Use with image or video shapes
- * const imageShape: TLImageShape = { props: { assetId: 'asset:img1' } }
- * const videoShape: TLVideoShape = { props: { assetId: 'asset:vid1' } }
- * handleAssetShape(imageShape) // Works
- * handleAssetShape(videoShape) // Works
  * ```
  *
  * @public
  */
 export type TLAssetShape = ExtractShapeByProps<{ assetId: TLAssetId }>
+
+/**
+ * Creates a migration sequence for asset properties.
+ *
+ * @example
+ * ```ts
+ * const migrations = createAssetPropsMigrationSequence({
+ *   sequence: [
+ *     { id: 'com.myapp.asset.custom/1', up: (props) => { props.newField = '' } },
+ *   ],
+ * })
+ * ```
+ *
+ * @public
+ */
+export function createAssetPropsMigrationSequence(
+	migrations: TLPropsMigrations
+): TLPropsMigrations {
+	return migrations
+}
+
+/**
+ * Creates properly formatted migration IDs for asset properties.
+ *
+ * @example
+ * ```ts
+ * const assetPropsVersions = createAssetPropsMigrationIds('file', {
+ *   AddFoo: 1,
+ *   RenameBar: 2,
+ * })
+ * // => { AddFoo: 'com.tldraw.asset.file/1', RenameBar: 'com.tldraw.asset.file/2' }
+ * ```
+ *
+ * @public
+ */
+export function createAssetPropsMigrationIds<S extends string, T extends Record<string, number>>(
+	assetType: S,
+	ids: T
+): { [k in keyof T]: `com.tldraw.asset.${S}/${T[k]}` } {
+	return mapObjectMapValues(ids, (_k, v) => `com.tldraw.asset.${assetType}/${v}`) as any
+}

package/src/shapes/TLFrameShape.ts

@@ -69,7 +69,9 @@ export const frameShapeProps: RecordProps<TLFrameShape> = {
 	// style prop by default, so instead of a proper style we just supply an equivalent validator.
 	// Check `FrameShapeUtil.configure` for how we replace this with the original
 	// `DefaultColorStyle` style when the option is turned on.
-	color: T.literalEnum(...DefaultColorStyle.values),
+	// We delegate to DefaultColorStyle.validate so custom colors from themes are
+	// picked up automatically.
+	color: { validate: (v: unknown) => DefaultColorStyle.validate(v) as TLDefaultColorStyle },
 }
 
 const Versions = createShapePropsMigrationIds('frame', {

package/src/shapes/TLNoteShape.ts

@@ -31,7 +31,7 @@ import { TLBaseShape } from './TLBaseShape'
  *   labelColor: 'black',
  *   size: 'm',
  *   font: 'draw',
- *   fontSizeAdjustment: 0,
+ *   fontSizeAdjustment: null,
  *   align: 'middle',
  *   verticalAlign: 'middle',
  *   growY: 0,
@@ -50,8 +50,8 @@ export interface TLNoteShapeProps {
 	size: TLDefaultSizeStyle
 	/** Font family style for the note text */
 	font: TLDefaultFontStyle
-	/** Adjustment to the base font size (positive increases, negative decreases) */
-	fontSizeAdjustment: number
+	/** Ratio to scale the base font size when text needs to shrink to fit. Null means needs recomputation, 1 means no adjustment, and values less than 1 indicate shrinkage. */
+	fontSizeAdjustment: number | null
 	/** Horizontal alignment of text within the note */
 	align: TLDefaultHorizontalAlignStyle
 	/** Vertical alignment of text within the note */
@@ -91,7 +91,7 @@ export interface TLNoteShapeProps {
  *     labelColor: 'black',
  *     size: 's',
  *     font: 'sans',
- *     fontSizeAdjustment: 2,
+ *     fontSizeAdjustment: 0.85,
  *     align: 'start',
  *     verticalAlign: 'start',
  *     growY: 50,
@@ -125,7 +125,7 @@ export const noteShapeProps: RecordProps<TLNoteShape> = {
 	labelColor: DefaultLabelColorStyle,
 	size: DefaultSizeStyle,
 	font: DefaultFontStyle,
-	fontSizeAdjustment: T.positiveNumber,
+	fontSizeAdjustment: T.positiveNumber.nullable(),
 	align: DefaultHorizontalAlignStyle,
 	verticalAlign: DefaultVerticalAlignStyle,
 	growY: T.positiveNumber,
@@ -147,6 +147,7 @@ const Versions = createShapePropsMigrationIds('note', {
 	AddRichText: 9,
 	AddRichTextAttrs: 10,
 	AddFirstEditedBy: 11,
+	MakeFontSizeAdjustmentRatio: 12,
 })
 
 /**
@@ -278,5 +279,18 @@ export const noteShapeMigrations = createShapePropsMigrationSequence({
 				delete props.textFirstEditedBy
 			},
 		},
+		{
+			id: Versions.MakeFontSizeAdjustmentRatio,
+			up: (props) => {
+				// Old system stored 0 for "no adjustment" or an absolute pixel font size.
+				// New system stores a ratio (1 = no adjustment, <1 = shrunk).
+				// We can convert 0 → 1 (no adjustment), but non-zero values need
+				// recomputation (null) since we don't know the base font size here.
+				props.fontSizeAdjustment = props.fontSizeAdjustment === 0 ? 1 : null
+			},
+			down: (props) => {
+				props.fontSizeAdjustment = 0
+			},
+		},
 	],
 })

package/src/styles/StyleProp.ts

@@ -111,12 +111,49 @@ export class StyleProp<Type> implements T.Validatable<Type> {
  */
 export class EnumStyleProp<T> extends StyleProp<T> {
 	/** @internal */
-	constructor(
-		id: string,
-		defaultValue: T,
-		readonly values: readonly T[]
-	) {
+	constructor(id: string, defaultValue: T, values: readonly T[]) {
 		super(id, defaultValue, T.literalEnum(...values))
+		this.values = [...values]
+	}
+
+	readonly values: T[]
+
+	/**
+	 * Add new values to this enum style prop at runtime. This is useful for extending
+	 * the built-in styles with custom values (e.g. adding custom colors). Be sure to
+	 * also modify the associated types.
+	 *
+	 * @param newValues - The new values to add.
+	 *
+	 * @public
+	 */
+	addValues(...newValues: T[]): void {
+		for (const v of newValues) {
+			if (!this.values.includes(v)) {
+				this.values.push(v)
+			}
+		}
+		// Rebuild the validator with the updated values
+		;(this as any).type = T.literalEnum(...this.values)
+	}
+
+	/**
+	 * Remove values from this enum style prop at runtime. This is useful for narrowing
+	 * the built-in styles with custom values (e.g. adding custom colors). Be sure to
+	 * also modify the associated types.
+	 *
+	 * @param valuesToRemove - The values to remove.
+	 *
+	 * @public
+	 */
+	removeValues(...valuesToRemove: T[]): void {
+		for (const v of valuesToRemove) {
+			if (this.values.includes(v)) {
+				this.values.splice(this.values.indexOf(v), 1)
+			}
+		}
+		// Rebuild the validator with the updated values
+		;(this as any).type = T.literalEnum(...this.values)
 	}
 }