@tldraw/tlschema 4.2.2 → 4.2.3

package/src/records/TLPresence.test.ts

@@ -0,0 +1,190 @@
+import { describe, expect, it } from 'vitest'
+import {
+	instancePresenceMigrations,
+	instancePresenceValidator,
+	instancePresenceVersions,
+	TLInstancePresenceID,
+} from './TLPresence'
+
+describe('instancePresenceValidator', () => {
+	it('should validate valid instance presence records', () => {
+		const validPresence = {
+			typeName: 'instance_presence',
+			id: 'instance_presence:test' as TLInstancePresenceID,
+			userId: 'user123',
+			userName: 'Test User',
+			lastActivityTimestamp: null,
+			color: '#007AFF',
+			camera: null,
+			selectedShapeIds: [],
+			currentPageId: 'page:main' as any,
+			brush: null,
+			scribbles: [],
+			screenBounds: null,
+			followingUserId: null,
+			cursor: null,
+			chatMessage: '',
+			meta: {},
+		}
+
+		expect(() => instancePresenceValidator.validate(validPresence)).not.toThrow()
+		const validated = instancePresenceValidator.validate(validPresence)
+		expect(validated).toEqual(validPresence)
+	})
+
+	it('should validate presence with complete data', () => {
+		const complexPresence = {
+			typeName: 'instance_presence',
+			id: 'instance_presence:complex' as TLInstancePresenceID,
+			userId: 'user456',
+			userName: 'Complex User',
+			lastActivityTimestamp: Date.now(),
+			color: '#FF3B30',
+			camera: { x: -100, y: 200, z: 0.75 },
+			selectedShapeIds: ['shape:1' as any, 'shape:2' as any],
+			currentPageId: 'page:design' as any,
+			brush: { x: 50, y: 75, w: 150, h: 100 },
+			scribbles: [
+				{
+					id: 'scribble:1',
+					points: [{ x: 0, y: 0, z: 0.5 }],
+					size: 4,
+					color: 'black',
+					opacity: 1,
+					state: 'starting',
+					delay: 0,
+					shrink: 0,
+					taper: false,
+				},
+			],
+			screenBounds: { x: 0, y: 0, w: 2560, h: 1440 },
+			followingUserId: 'leader123',
+			cursor: { x: 300, y: 400, type: 'pointer', rotation: 45 },
+			chatMessage: 'Working on design!',
+			meta: { team: 'design', role: 'designer' },
+		}
+
+		expect(() => instancePresenceValidator.validate(complexPresence)).not.toThrow()
+	})
+
+	it('should reject invalid typeName', () => {
+		const invalidPresence = {
+			typeName: 'not-instance-presence',
+			id: 'instance_presence:test' as TLInstancePresenceID,
+			userId: 'user123',
+			userName: 'Test',
+			lastActivityTimestamp: null,
+			color: '#000000',
+			camera: null,
+			selectedShapeIds: [],
+			currentPageId: 'page:main' as any,
+			brush: null,
+			scribbles: [],
+			screenBounds: null,
+			followingUserId: null,
+			cursor: null,
+			chatMessage: '',
+			meta: {},
+		}
+
+		expect(() => instancePresenceValidator.validate(invalidPresence)).toThrow()
+	})
+})
+
+describe('instancePresenceMigrations', () => {
+	it('should migrate AddScribbleDelay correctly', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.AddScribbleDelay
+		)!
+
+		const oldRecordWithScribble: any = {
+			scribble: { points: [], size: 4, color: 'black' },
+		}
+		migration.up(oldRecordWithScribble)
+		expect(oldRecordWithScribble.scribble.delay).toBe(0)
+
+		const oldRecordWithoutScribble: any = {
+			scribble: null,
+		}
+		migration.up(oldRecordWithoutScribble)
+		expect(oldRecordWithoutScribble.scribble).toBe(null)
+	})
+
+	it('should migrate RemoveInstanceId correctly', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.RemoveInstanceId
+		)!
+		const oldRecord: any = {
+			instanceId: 'instance:removed',
+			otherProp: 'keep-me',
+		}
+		migration.up(oldRecord)
+
+		expect(oldRecord.instanceId).toBeUndefined()
+		expect(oldRecord.otherProp).toBe('keep-me')
+	})
+
+	it('should migrate AddChatMessage correctly', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.AddChatMessage
+		)!
+		const oldRecord: any = { id: 'instance_presence:test' }
+		migration.up(oldRecord)
+
+		expect(oldRecord.chatMessage).toBe('')
+	})
+
+	it('should migrate AddMeta correctly', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.AddMeta
+		)!
+		const oldRecord: any = { id: 'instance_presence:test' }
+		migration.up(oldRecord)
+
+		expect(oldRecord.meta).toEqual({})
+	})
+
+	it('should handle RenameSelectedShapeIds migration (noop)', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.RenameSelectedShapeIds
+		)!
+		const oldRecord: any = { selectedShapeIds: ['shape:1'] }
+		const originalRecord = { ...oldRecord }
+		migration.up(oldRecord)
+
+		// Should be a noop
+		expect(oldRecord).toEqual(originalRecord)
+	})
+
+	it('should handle NullableCameraCursor migration up (noop)', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.NullableCameraCursor
+		)!
+		const record: any = { camera: null, cursor: null }
+		const originalRecord = { ...record }
+		migration.up(record)
+
+		// Should be a noop
+		expect(record).toEqual(originalRecord)
+	})
+
+	it('should handle NullableCameraCursor migration down', () => {
+		const migration = instancePresenceMigrations.sequence.find(
+			(m) => m.id === instancePresenceVersions.NullableCameraCursor
+		)!
+		expect(migration.down).toBeDefined()
+
+		const record: any = {
+			camera: null,
+			lastActivityTimestamp: null,
+			cursor: null,
+			screenBounds: null,
+		}
+		migration.down!(record)
+
+		expect(record.camera).toEqual({ x: 0, y: 0, z: 1 })
+		expect(record.lastActivityTimestamp).toBe(0)
+		expect(record.cursor).toEqual({ type: 'default', x: 0, y: 0, rotation: 0 })
+		expect(record.screenBounds).toEqual({ x: 0, y: 0, w: 1, h: 1 })
+	})
+})

package/src/records/TLRecord.test.ts

@@ -0,0 +1,70 @@
+import { describe, expect, it } from 'vitest'
+import { TLRecord } from './TLRecord'
+
+describe('TLRecord', () => {
+	it('should support type discrimination by typeName', () => {
+		function processRecord(record: TLRecord): string {
+			// TypeScript should be able to narrow types based on typeName
+			switch (record.typeName) {
+				case 'shape':
+					return `Shape at (${record.x}, ${record.y})`
+				case 'page':
+					return `Page: ${record.name}`
+				case 'asset':
+					return `Asset: ${record.type}`
+				case 'binding':
+					return `Binding from ${record.fromId} to ${record.toId}`
+				case 'camera':
+					return `Camera at (${record.x}, ${record.y}) zoom: ${record.z}`
+				case 'document':
+					return `Document: ${record.name}, grid: ${record.gridSize}`
+				case 'instance':
+					return `Instance on page ${record.currentPageId}`
+				case 'instance_page_state':
+					return `Page state for ${record.pageId}`
+				case 'instance_presence':
+					return `Presence of ${record.userName}`
+				case 'pointer':
+					return `Pointer at (${record.x}, ${record.y})`
+				default:
+					// This should never be reached if all cases are handled
+					return 'Unknown record type'
+			}
+		}
+
+		// Test that the discriminated union works correctly
+		const shapeRecord: TLRecord = {
+			id: 'shape:test' as any,
+			typeName: 'shape',
+			type: 'geo',
+			x: 50,
+			y: 100,
+			rotation: 0,
+			index: 'a1' as any,
+			parentId: 'page:main' as any,
+			isLocked: false,
+			opacity: 1,
+			props: {
+				geo: 'rectangle',
+				w: 80,
+				h: 80,
+				color: 'black',
+				fill: 'none',
+				dash: 'draw',
+				size: 'm',
+			},
+			meta: {},
+		}
+
+		const pageRecord: TLRecord = {
+			id: 'page:test' as any,
+			typeName: 'page',
+			name: 'Test Page',
+			index: 'a1' as any,
+			meta: {},
+		}
+
+		expect(processRecord(shapeRecord)).toBe('Shape at (50, 100)')
+		expect(processRecord(pageRecord)).toBe('Page: Test Page')
+	})
+})

package/src/records/TLShape.test.ts

@@ -0,0 +1,232 @@
+import { T } from '@tldraw/validate'
+import { describe, expect, it } from 'vitest'
+import { StyleProp } from '../styles/StyleProp'
+import {
+	createShapeId,
+	createShapePropsMigrationIds,
+	createShapeRecordType,
+	getShapePropKeysByStyle,
+	isShape,
+	isShapeId,
+	rootShapeMigrations,
+	rootShapeVersions,
+	TLShapeId,
+} from './TLShape'
+
+describe('rootShapeMigrations', () => {
+	it('should migrate AddIsLocked correctly', () => {
+		const migration = rootShapeMigrations.sequence.find(
+			(m) => m.id === rootShapeVersions.AddIsLocked
+		)!
+		expect(migration.up).toBeDefined()
+		expect(migration.down).toBeDefined()
+
+		const record: any = { id: 'shape:test', typeName: 'shape', type: 'geo' }
+		migration.up(record)
+		expect(record.isLocked).toBe(false)
+
+		migration.down!(record)
+		expect(record.isLocked).toBeUndefined()
+	})
+
+	it('should migrate HoistOpacity correctly', () => {
+		const migration = rootShapeMigrations.sequence.find(
+			(m) => m.id === rootShapeVersions.HoistOpacity
+		)!
+		expect(migration.up).toBeDefined()
+		expect(migration.down).toBeDefined()
+
+		// Test up migration
+		const record: any = {
+			id: 'shape:test',
+			typeName: 'shape',
+			type: 'geo',
+			props: { opacity: '0.5', color: 'red' },
+		}
+		migration.up(record)
+		expect(record.opacity).toBe(0.5)
+		expect(record.props.opacity).toBeUndefined()
+		expect(record.props.color).toBe('red')
+
+		// Test down migration
+		migration.down!(record)
+		expect(record.props.opacity).toBe('0.5')
+		expect(record.opacity).toBeUndefined()
+	})
+
+	it('should migrate AddMeta correctly', () => {
+		const migration = rootShapeMigrations.sequence.find((m) => m.id === rootShapeVersions.AddMeta)!
+		const record: any = { id: 'shape:test', typeName: 'shape', type: 'geo' }
+		migration.up(record)
+		expect(record.meta).toEqual({})
+	})
+
+	it('should handle AddWhite migration', () => {
+		const migration = rootShapeMigrations.sequence.find((m) => m.id === rootShapeVersions.AddWhite)!
+		expect(migration.up).toBeDefined()
+		expect(migration.down).toBeDefined()
+
+		// Up migration is noop
+		const record: any = { props: { color: 'white' } }
+		const original = { ...record }
+		migration.up(record)
+		expect(record).toEqual(original)
+
+		// Down migration converts white to black
+		migration.down!(record)
+		expect(record.props.color).toBe('black')
+	})
+})
+
+describe('isShape', () => {
+	it('should return true for shape records', () => {
+		const shape = {
+			id: 'shape:test' as TLShapeId,
+			typeName: 'shape',
+			type: 'geo',
+			x: 0,
+			y: 0,
+			rotation: 0,
+			index: 'a1' as any,
+			parentId: 'page:main' as any,
+			isLocked: false,
+			opacity: 1,
+			props: {},
+			meta: {},
+		}
+
+		expect(isShape(shape)).toBe(true)
+	})
+
+	it('should return false for non-shape records', () => {
+		const notShape = {
+			id: 'page:test',
+			typeName: 'page',
+			name: 'Test Page',
+		}
+
+		expect(isShape(notShape as any)).toBe(false)
+	})
+})
+
+describe('isShapeId', () => {
+	it('should return true for valid shape IDs', () => {
+		expect(isShapeId('shape:test')).toBe(true)
+		expect(isShapeId('shape:abc123')).toBe(true)
+		expect(isShapeId('shape:')).toBe(true)
+	})
+
+	it('should return false for invalid shape IDs', () => {
+		expect(isShapeId('page:test')).toBe(false)
+		expect(isShapeId('asset:test')).toBe(false)
+		expect(isShapeId('invalid')).toBe(false)
+		expect(isShapeId('')).toBe(false)
+	})
+})
+
+describe('createShapeId', () => {
+	it('should create shape IDs with auto-generated suffix', () => {
+		const id1 = createShapeId()
+		const id2 = createShapeId()
+
+		expect(id1.startsWith('shape:')).toBe(true)
+		expect(id2.startsWith('shape:')).toBe(true)
+		expect(id1).not.toBe(id2)
+		expect(id1.length).toBeGreaterThan(6) // 'shape:' + some ID
+		expect(id2.length).toBeGreaterThan(6)
+	})
+
+	it('should create shape IDs with custom suffix', () => {
+		const customId = createShapeId('my-custom-id')
+		expect(customId).toBe('shape:my-custom-id')
+	})
+})
+
+describe('getShapePropKeysByStyle', () => {
+	it('should map style props to their keys', () => {
+		const colorStyle = StyleProp.define('color', { defaultValue: 'black' })
+		const sizeStyle = StyleProp.define('size', { defaultValue: 'm' })
+
+		const props = {
+			color: colorStyle,
+			size: sizeStyle,
+			width: T.number,
+			height: T.number,
+		}
+
+		const styleMap = getShapePropKeysByStyle(props)
+		expect(styleMap.get(colorStyle)).toBe('color')
+		expect(styleMap.get(sizeStyle)).toBe('size')
+		expect(styleMap.size).toBe(2) // Only style props
+	})
+
+	it('should throw error for duplicate style props', () => {
+		const colorStyle = StyleProp.define('color', { defaultValue: 'black' })
+		const props = {
+			color1: colorStyle,
+			color2: colorStyle, // Same style prop used twice
+			width: T.number,
+		}
+
+		expect(() => getShapePropKeysByStyle(props)).toThrow('Duplicate style prop')
+	})
+})
+
+describe('createShapePropsMigrationIds', () => {
+	it('should create formatted migration IDs', () => {
+		const ids = createShapePropsMigrationIds('custom', {
+			AddColor: 1,
+			AddSize: 2,
+			RefactorProps: 3,
+		})
+
+		expect(ids.AddColor).toBe('com.tldraw.shape.custom/1')
+		expect(ids.AddSize).toBe('com.tldraw.shape.custom/2')
+		expect(ids.RefactorProps).toBe('com.tldraw.shape.custom/3')
+	})
+})
+
+describe('createShapeRecordType', () => {
+	it('should create a record type for shapes', () => {
+		const shapes = {
+			geo: {
+				props: {
+					w: T.number,
+					h: T.number,
+					color: StyleProp.define('color', { defaultValue: 'black' }),
+				},
+				meta: {},
+			},
+			text: {
+				props: {
+					text: T.string,
+					size: StyleProp.define('size', { defaultValue: 'm' }),
+				},
+				meta: {},
+			},
+		}
+
+		const ShapeRecordType = createShapeRecordType(shapes)
+
+		expect(ShapeRecordType.typeName).toBe('shape')
+		expect(ShapeRecordType.scope).toBe('document')
+
+		// Should be able to create shapes
+		const geoShape = ShapeRecordType.create({
+			id: createShapeId(),
+			type: 'geo',
+			parentId: 'page:main' as any,
+			index: 'a1' as any,
+			props: {},
+		})
+
+		expect(geoShape.typeName).toBe('shape')
+		expect(geoShape.type).toBe('geo')
+		expect(geoShape.x).toBe(0) // Default
+		expect(geoShape.y).toBe(0) // Default
+		expect(geoShape.rotation).toBe(0) // Default
+		expect(geoShape.isLocked).toBe(false) // Default
+		expect(geoShape.opacity).toBe(1) // Default
+		expect(geoShape.meta).toEqual({}) // Default
+	})
+})

package/src/records/TLShape.ts

@@ -79,51 +79,12 @@ export type TLDefaultShape =
  */
 export type TLUnknownShape = TLBaseShape<string, object>
 
-/** @public */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface TLGlobalShapePropsMap {}
-
-/** @public */
-// prettier-ignore
-export type TLIndexedShapes = {
-	// We iterate over a union of augmented keys and default shape types.
-	// This allows us to include (or conditionally exclude or override) the default shapes in one go.
-	//
-	// In the `as` clause we are filtering out disabled shapes.
-	[K in keyof TLGlobalShapePropsMap | TLDefaultShape['type'] as K extends TLDefaultShape['type']
-		? // core shapes are always available and cannot be overridden so we just include them
-			K extends 'group'
-			? K
-			: K extends keyof TLGlobalShapePropsMap
-				? // if it extends a nullish value the user has disabled this shape type so we filter it out with never
-					TLGlobalShapePropsMap[K] extends null | undefined
-					? never
-					: K
-				: K
-		: K]: K extends 'group'
-		? // core shapes are always available and cannot be overridden so we just include them
-			Extract<TLDefaultShape, { type: K }>
-		: K extends TLDefaultShape['type']
-			? // if it's a default shape type we need to check if it's been overridden
-				K extends keyof TLGlobalShapePropsMap
-				? // if it has been overriden then use the custom shape definition
-					TLBaseShape<K, TLGlobalShapePropsMap[K]>
-				: // if it has not been overriden then reuse existing type aliases for better type display
-					Extract<TLDefaultShape, { type: K }>
-			: // use the custom shape definition
-				TLBaseShape<K, TLGlobalShapePropsMap[K & keyof TLGlobalShapePropsMap]>
-}
-
 /**
- * The set of all shapes that are available in the editor.
+ * The set of all shapes that are available in the editor, including unknown shapes.
  *
  * This is the primary shape type used throughout tldraw. It includes both the
  * built-in default shapes and any custom shapes that might be added.
  *
- * You can use this type without a type argument to work with any shape, or pass
- * a specific shape type string (e.g., `'geo'`, `'arrow'`, `'text'`) to narrow
- * down to that specific shape type.
- *
  * @example
  * ```ts
  * // Work with any shape in the editor
@@ -134,16 +95,11 @@ export type TLIndexedShapes = {
  *     y: shape.y + deltaY
  *   }
  * }
- *
- * // Narrow to a specific shape type by passing the type as a generic argument
- * function getArrowLabel(shape: TLShape<'arrow'>): string {
- *   return shape.props.text // TypeScript knows this is a TLArrowShape
- * }
  * ```
  *
  * @public
  */
-export type TLShape<K extends keyof TLIndexedShapes = keyof TLIndexedShapes> = TLIndexedShapes[K]
+export type TLShape = TLDefaultShape | TLUnknownShape
 
 /**
  * A partial version of a shape, useful for updates and patches.
@@ -183,57 +139,6 @@ export type TLShapePartial<T extends TLShape = TLShape> = T extends T
 		} & Partial<Omit<T, 'type' | 'id' | 'props' | 'meta'>>
 	: never
 
-/**
- * A partial version of a shape, useful for creating shapes.
- *
- * This type represents a shape where all properties except `type` are optional.
- * It's commonly used when creating shapes.
- *
- * @example
- * ```ts
- * // Create a shape
- * const shapeCreate: TLCreateShapePartial = {
- *   type: 'geo',
- *   x: 100,
- *   y: 200
- * }
- *
- * // Create shape properties
- * const propsCreate: TLCreateShapePartial<TLGeoShape> = {
- *   type: 'geo',
- *   props: {
- *     w: 150,
- *     h: 100
- *   }
- * }
- * ```
- *
- * @public
- */
-export type TLCreateShapePartial<T extends TLShape = TLShape> = T extends T
-	? {
-			type: T['type']
-			props?: Partial<T['props']>
-			meta?: Partial<T['meta']>
-		} & Partial<Omit<T, 'type' | 'props' | 'meta'>>
-	: never
-
-/**
- * Extract a shape type by its props.
- *
- * This utility type takes a props object type and returns the corresponding shape type
- * from the TLShape union whose props match the given type.
- *
- * @example
- * ```ts
- * type MyShape = ExtractShapeByProps<{ w: number; h: number }>
- * // MyShape is now the type of shape(s) that have props with w and h as numbers
- * ```
- *
- * @public
- */
-export type ExtractShapeByProps<P> = Extract<TLShape, { props: P }>
-
 /**
  * A unique identifier for a shape record.
  *
@@ -248,7 +153,7 @@ export type ExtractShapeByProps<P> = Extract<TLShape, { props: P }>
  *
  * @public
  */
-export type TLShapeId = RecordId<TLShape>
+export type TLShapeId = RecordId<TLUnknownShape>
 
 /**
  * The ID of a shape's parent, which can be either a page or another shape.
@@ -290,7 +195,7 @@ export const rootShapeVersions = createMigrationIds('com.tldraw.shape', {
 	HoistOpacity: 2,
 	AddMeta: 3,
 	AddWhite: 4,
-})
+} as const)
 
 /**
  * Migration sequence for the root shape record type.
@@ -564,7 +469,7 @@ export function createShapePropsMigrationIds<
  * @internal
  */
 export function createShapeRecordType(shapes: Record<string, SchemaPropsInfo>) {
-	return createRecordType('shape', {
+	return createRecordType<TLShape>('shape', {
 		scope: 'document',
 		validator: T.model(
 			'shape',

package/src/shapes/ShapeWithCrop.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from 'vitest'
+import { TLShapeCrop } from './ShapeWithCrop'
+
+describe('TLShapeCrop', () => {
+	test('should calculate crop dimensions correctly', () => {
+		const crop: TLShapeCrop = {
+			topLeft: { x: 0.2, y: 0.3 },
+			bottomRight: { x: 0.8, y: 0.7 },
+		}
+
+		// This tests the actual utility of the crop interface - calculating dimensions
+		const width = crop.bottomRight.x - crop.topLeft.x
+		const height = crop.bottomRight.y - crop.topLeft.y
+
+		expect(width).toBeCloseTo(0.6)
+		expect(height).toBeCloseTo(0.4)
+	})
+})

package/src/shapes/ShapeWithCrop.ts

@@ -1,5 +1,5 @@
 import { VecModel } from '../misc/geometry-types'
-import { ExtractShapeByProps } from '../records/TLShape'
+import { TLBaseShape } from './TLBaseShape'
 
 /**
  * Defines cropping parameters for shapes that support cropping.
@@ -71,4 +71,4 @@ export interface TLShapeCrop {
  *
  * @public
  */
-export type ShapeWithCrop = ExtractShapeByProps<{ w: number; h: number; crop: TLShapeCrop | null }>
+export type ShapeWithCrop = TLBaseShape<string, { w: number; h: number; crop: TLShapeCrop | null }>