@tldraw/tlschema 4.2.2 → 4.2.3

package/src/records/TLCamera.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest'
+import { cameraMigrations, cameraVersions } from './TLCamera'
+
+describe('cameraMigrations', () => {
+	it('should apply AddMeta migration correctly', () => {
+		const addMetaMigration = cameraMigrations.sequence.find((m) => m.id === cameraVersions.AddMeta)!
+
+		const oldRecord: any = {
+			typeName: 'camera',
+			id: 'camera:test',
+			x: 100,
+			y: 200,
+			z: 0.5,
+		}
+
+		addMetaMigration.up(oldRecord)
+		expect(oldRecord.meta).toEqual({})
+	})
+})

package/src/records/TLDocument.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest'
+import { documentMigrations, documentVersions, TLDOCUMENT_ID } from './TLDocument'
+
+describe('documentMigrations', () => {
+	it('should apply AddName migration correctly', () => {
+		const addNameMigration = documentMigrations.sequence.find(
+			(m) => m.id === documentVersions.AddName
+		)!
+
+		const oldRecord: any = {
+			typeName: 'document',
+			id: TLDOCUMENT_ID,
+			gridSize: 10,
+		}
+
+		addNameMigration.up(oldRecord)
+		expect(oldRecord.name).toBe('')
+	})
+
+	it('should apply AddMeta migration correctly', () => {
+		const addMetaMigration = documentMigrations.sequence.find(
+			(m) => m.id === documentVersions.AddMeta
+		)!
+
+		const oldRecord: any = {
+			typeName: 'document',
+			id: TLDOCUMENT_ID,
+			gridSize: 10,
+			name: 'Test',
+		}
+
+		addMetaMigration.up(oldRecord)
+		expect(oldRecord.meta).toEqual({})
+	})
+})

package/src/records/TLInstance.test.ts

@@ -0,0 +1,201 @@
+import { describe, expect, it } from 'vitest'
+import { StyleProp } from '../styles/StyleProp'
+import {
+	createInstanceRecordType,
+	instanceIdValidator,
+	instanceMigrations,
+	instanceVersions,
+	pluckPreservingValues,
+	shouldKeyBePreservedBetweenSessions,
+	TLInstance,
+	TLINSTANCE_ID,
+} from './TLInstance'
+
+// Mock style prop for testing
+const mockColorStyle = {
+	type: 'color',
+	defaultValue: 'black',
+	getDefaultValue: () => 'black',
+} as unknown as StyleProp<string>
+
+const mockStylesMap = new Map([['color', mockColorStyle]])
+createInstanceRecordType(mockStylesMap)
+
+describe('shouldKeyBePreservedBetweenSessions', () => {
+	it('should preserve user preferences', () => {
+		const userPreferences = [
+			'isFocusMode',
+			'isDebugMode',
+			'isToolLocked',
+			'exportBackground',
+			'isGridMode',
+			'isReadonly',
+		]
+
+		userPreferences.forEach((key) => {
+			expect(
+				shouldKeyBePreservedBetweenSessions[key as keyof typeof shouldKeyBePreservedBetweenSessions]
+			).toBe(true)
+		})
+	})
+
+	it('should not preserve temporary state', () => {
+		const temporaryState = [
+			'currentPageId',
+			'opacityForNextShape',
+			'stylesForNextShape',
+			'followingUserId',
+			'brush',
+			'cursor',
+			'scribbles',
+			'zoomBrush',
+			'chatMessage',
+			'isChatting',
+			'isPenMode',
+			'isHoveringCanvas',
+			'openMenus',
+			'isChangingStyle',
+			'duplicateProps',
+		]
+
+		temporaryState.forEach((key) => {
+			expect(
+				shouldKeyBePreservedBetweenSessions[key as keyof typeof shouldKeyBePreservedBetweenSessions]
+			).toBe(false)
+		})
+	})
+})
+
+describe('pluckPreservingValues', () => {
+	it('should return null for null or undefined input', () => {
+		expect(pluckPreservingValues(null)).toBe(null)
+		expect(pluckPreservingValues(undefined)).toBe(null)
+	})
+
+	it('should filter properties according to preservation rules', () => {
+		const fullInstance: TLInstance = {
+			id: TLINSTANCE_ID,
+			typeName: 'instance',
+			currentPageId: 'page:page1' as any,
+			opacityForNextShape: 0.5,
+			stylesForNextShape: {},
+			followingUserId: null,
+			highlightedUserIds: [],
+			brush: null,
+			cursor: { type: 'default', rotation: 0 },
+			scribbles: [],
+			isFocusMode: true,
+			isDebugMode: false,
+			isToolLocked: true,
+			exportBackground: true,
+			screenBounds: { x: 0, y: 0, w: 1920, h: 1080 },
+			insets: [false, false, false, false],
+			zoomBrush: null,
+			chatMessage: '',
+			isChatting: false,
+			isPenMode: false,
+			isGridMode: true,
+			isFocused: true,
+			devicePixelRatio: 2,
+			isCoarsePointer: false,
+			isHoveringCanvas: null,
+			openMenus: [],
+			isChangingStyle: false,
+			isReadonly: false,
+			meta: {},
+			duplicateProps: null,
+		}
+
+		const preserved = pluckPreservingValues(fullInstance)
+
+		// Should preserve user preferences
+		expect(preserved?.isFocusMode).toBe(true)
+		expect(preserved?.isDebugMode).toBe(false)
+		expect(preserved?.isToolLocked).toBe(true)
+		expect(preserved?.exportBackground).toBe(true)
+		expect(preserved?.isGridMode).toBe(true)
+
+		// Should not preserve temporary state
+		expect(preserved?.currentPageId).toBeUndefined()
+		expect(preserved?.opacityForNextShape).toBeUndefined()
+		expect(preserved?.brush).toBeUndefined()
+		expect(preserved?.cursor).toBeUndefined()
+		expect(preserved?.chatMessage).toBeUndefined()
+		expect(preserved?.openMenus).toBeUndefined()
+	})
+})
+
+describe('instanceIdValidator', () => {
+	it('should validate correct instance IDs and reject invalid ones', () => {
+		expect(() => instanceIdValidator.validate('instance:instance')).not.toThrow()
+		expect(() => instanceIdValidator.validate('instance:test')).not.toThrow()
+		expect(() => instanceIdValidator.validate(TLINSTANCE_ID)).not.toThrow()
+
+		expect(() => instanceIdValidator.validate('invalid')).toThrow()
+		expect(() => instanceIdValidator.validate('page:instance')).toThrow()
+		expect(() => instanceIdValidator.validate('')).toThrow()
+	})
+})
+
+describe('createInstanceRecordType', () => {
+	it('should create a valid record type with correct configuration', () => {
+		const recordType = createInstanceRecordType(mockStylesMap)
+		expect(recordType.typeName).toBe('instance')
+		expect(recordType.scope).toBe('session')
+	})
+})
+
+describe('instanceMigrations', () => {
+	it('should have correct migration configuration', () => {
+		expect(instanceMigrations.sequenceId).toBe('com.tldraw.instance')
+		expect(Array.isArray(instanceMigrations.sequence)).toBe(true)
+		expect(instanceMigrations.sequence.length).toBe(25)
+	})
+
+	it('should migrate HoistOpacity correctly', () => {
+		const migration = instanceMigrations.sequence.find(
+			(m) => m.id === instanceVersions.HoistOpacity
+		)!
+		const oldRecord: any = {
+			id: TLINSTANCE_ID,
+			typeName: 'instance',
+			propsForNextShape: {
+				opacity: '0.5',
+				color: 'red',
+			},
+		}
+		const result = migration.up(oldRecord)
+
+		expect((result as any).opacityForNextShape).toBe(0.5)
+		expect((result as any).propsForNextShape.opacity).toBeUndefined()
+		expect((result as any).propsForNextShape.color).toBe('red')
+	})
+
+	it('should migrate RemoveDialog correctly', () => {
+		const migration = instanceMigrations.sequence.find(
+			(m) => m.id === instanceVersions.RemoveDialog
+		)!
+		const oldRecord: any = {
+			id: TLINSTANCE_ID,
+			typeName: 'instance',
+			dialog: 'some-dialog',
+			otherProp: 'keep-me',
+		}
+		const result = migration.up(oldRecord)
+
+		expect((result as any).dialog).toBeUndefined()
+		expect((result as any).otherProp).toBe('keep-me')
+	})
+
+	it('should have bidirectional migrations where applicable', () => {
+		const addInsetMigration = instanceMigrations.sequence.find(
+			(m) => m.id === instanceVersions.AddInset
+		)!
+		expect(addInsetMigration.down).toBeDefined()
+
+		const removeCameraMigration = instanceMigrations.sequence.find(
+			(m) => m.id === instanceVersions.RemoveCanMoveCamera
+		)!
+		expect(removeCameraMigration.down).toBeDefined()
+	})
+})

package/src/records/TLPage.test.ts

@@ -0,0 +1,110 @@
+import { describe, expect, it } from 'vitest'
+import {
+	isPageId,
+	pageIdValidator,
+	pageMigrations,
+	PageRecordType,
+	pageValidator,
+	pageVersions,
+	TLPageId,
+} from './TLPage'
+
+describe('pageIdValidator', () => {
+	it('should validate correct page IDs', () => {
+		expect(() => pageIdValidator.validate('page:main')).not.toThrow()
+		expect(() => pageIdValidator.validate('page:page1')).not.toThrow()
+	})
+
+	it('should reject invalid page IDs', () => {
+		expect(() => pageIdValidator.validate('invalid')).toThrow()
+		expect(() => pageIdValidator.validate('shape:page1')).toThrow()
+		expect(() => pageIdValidator.validate('')).toThrow()
+	})
+})
+
+describe('pageValidator', () => {
+	it('should validate valid page records', () => {
+		const validPage = {
+			typeName: 'page',
+			id: 'page:test' as TLPageId,
+			name: 'Test Page',
+			index: 'a1' as any,
+			meta: {},
+		}
+
+		expect(() => pageValidator.validate(validPage)).not.toThrow()
+	})
+
+	it('should reject pages with invalid typeName', () => {
+		const invalidPage = {
+			typeName: 'not-page',
+			id: 'page:test' as TLPageId,
+			name: 'Test',
+			index: 'a1' as any,
+			meta: {},
+		}
+
+		expect(() => pageValidator.validate(invalidPage)).toThrow()
+	})
+
+	it('should reject pages with missing required fields', () => {
+		const incompletePages = [
+			{
+				typeName: 'page',
+				id: 'page:test' as TLPageId,
+				// missing name, index, meta
+			},
+			{
+				typeName: 'page',
+				id: 'page:test' as TLPageId,
+				name: 'Test',
+				// missing index, meta
+			},
+		]
+
+		incompletePages.forEach((page) => {
+			expect(() => pageValidator.validate(page)).toThrow()
+		})
+	})
+})
+
+describe('pageMigrations', () => {
+	it('should apply AddMeta migration correctly', () => {
+		const addMetaMigration = pageMigrations.sequence.find((m) => m.id === pageVersions.AddMeta)!
+
+		const oldRecord: any = {
+			typeName: 'page',
+			id: 'page:test',
+			name: 'Test Page',
+			index: 'a1',
+		}
+
+		addMetaMigration.up(oldRecord)
+		expect(oldRecord.meta).toEqual({})
+	})
+})
+
+describe('PageRecordType', () => {
+	it('should create page records with defaults', () => {
+		const page = PageRecordType.create({
+			id: 'page:test' as TLPageId,
+			name: 'Test Page',
+			index: 'a1' as any,
+		})
+
+		expect(page.meta).toEqual({})
+	})
+})
+
+describe('isPageId', () => {
+	it('should return true for valid page IDs', () => {
+		expect(isPageId('page:main')).toBe(true)
+		expect(isPageId('page:page1')).toBe(true)
+	})
+
+	it('should return false for invalid page IDs', () => {
+		expect(isPageId('shape:main')).toBe(false)
+		expect(isPageId('invalid')).toBe(false)
+		expect(isPageId('')).toBe(false)
+	})
+})

package/src/records/TLPageState.test.ts

@@ -0,0 +1,228 @@
+import { describe, expect, it } from 'vitest'
+import {
+	instancePageStateMigrations,
+	InstancePageStateRecordType,
+	instancePageStateValidator,
+	instancePageStateVersions,
+	TLInstancePageStateId,
+} from './TLPageState'
+
+describe('instancePageStateValidator', () => {
+	it('should reject invalid typeName', () => {
+		const invalidPageState = {
+			typeName: 'not-instance-page-state',
+			id: 'instance_page_state:test' as TLInstancePageStateId,
+			pageId: 'page:test' as any,
+			selectedShapeIds: [],
+			hintingShapeIds: [],
+			erasingShapeIds: [],
+			hoveredShapeId: null,
+			editingShapeId: null,
+			croppingShapeId: null,
+			focusedGroupId: null,
+			meta: {},
+		}
+
+		expect(() => instancePageStateValidator.validate(invalidPageState)).toThrow()
+	})
+
+	it('should reject invalid id format', () => {
+		const invalidPageState = {
+			typeName: 'instance_page_state',
+			id: 'not-valid-id' as TLInstancePageStateId,
+			pageId: 'page:test' as any,
+			selectedShapeIds: [],
+			hintingShapeIds: [],
+			erasingShapeIds: [],
+			hoveredShapeId: null,
+			editingShapeId: null,
+			croppingShapeId: null,
+			focusedGroupId: null,
+			meta: {},
+		}
+
+		expect(() => instancePageStateValidator.validate(invalidPageState)).toThrow()
+	})
+
+	it('should reject missing required fields', () => {
+		const incompletePageState = {
+			typeName: 'instance_page_state',
+			id: 'instance_page_state:test' as TLInstancePageStateId,
+			pageId: 'page:test' as any,
+			// missing required array fields
+		}
+
+		expect(() => instancePageStateValidator.validate(incompletePageState)).toThrow()
+	})
+})
+
+describe('instancePageStateMigrations', () => {
+	it('should migrate AddCroppingId correctly', () => {
+		const migration = instancePageStateMigrations.sequence.find(
+			(m) => m.id === instancePageStateVersions.AddCroppingId
+		)!
+		const oldRecord: any = { id: 'instance_page_state:test', typeName: 'instance_page_state' }
+		migration.up(oldRecord)
+
+		expect(oldRecord.croppingShapeId).toBe(null)
+	})
+
+	it('should migrate RemoveInstanceIdAndCameraId correctly', () => {
+		const migration = instancePageStateMigrations.sequence.find(
+			(m) => m.id === instancePageStateVersions.RemoveInstanceIdAndCameraId
+		)!
+		const oldRecord: any = {
+			id: 'instance_page_state:test',
+			typeName: 'instance_page_state',
+			instanceId: 'instance:removed',
+			cameraId: 'camera:removed',
+			otherProp: 'keep-me',
+		}
+		migration.up(oldRecord)
+
+		expect(oldRecord.instanceId).toBeUndefined()
+		expect(oldRecord.cameraId).toBeUndefined()
+		expect(oldRecord.otherProp).toBe('keep-me')
+	})
+
+	it('should migrate AddMeta correctly', () => {
+		const migration = instancePageStateMigrations.sequence.find(
+			(m) => m.id === instancePageStateVersions.AddMeta
+		)!
+		const oldRecord: any = { id: 'instance_page_state:test', typeName: 'instance_page_state' }
+		migration.up(oldRecord)
+
+		expect(oldRecord.meta).toEqual({})
+	})
+
+	it('should handle RenameProperties migration (noop)', () => {
+		const migration = instancePageStateMigrations.sequence.find(
+			(m) => m.id === instancePageStateVersions.RenameProperties
+		)!
+		const oldRecord: any = {
+			id: 'instance_page_state:test',
+			typeName: 'instance_page_state',
+			selectedIds: ['shape:1'],
+		}
+		const originalRecord = { ...oldRecord }
+		migration.up(oldRecord)
+
+		// Should be a noop
+		expect(oldRecord).toEqual(originalRecord)
+	})
+
+	it('should migrate RenamePropertiesAgain correctly', () => {
+		const migration = instancePageStateMigrations.sequence.find(
+			(m) => m.id === instancePageStateVersions.RenamePropertiesAgain
+		)!
+		const oldRecord: any = {
+			id: 'instance_page_state:test',
+			typeName: 'instance_page_state',
+			selectedIds: ['shape:1', 'shape:2'],
+			hintingIds: ['shape:3'],
+			erasingIds: ['shape:4'],
+			hoveredId: 'shape:5',
+			editingId: 'shape:6',
+			croppingId: 'shape:7',
+			focusLayerId: 'shape:8',
+		}
+		migration.up(oldRecord)
+
+		expect(oldRecord.selectedShapeIds).toEqual(['shape:1', 'shape:2'])
+		expect(oldRecord.hintingShapeIds).toEqual(['shape:3'])
+		expect(oldRecord.erasingShapeIds).toEqual(['shape:4'])
+		expect(oldRecord.hoveredShapeId).toBe('shape:5')
+		expect(oldRecord.editingShapeId).toBe('shape:6')
+		expect(oldRecord.croppingShapeId).toBe('shape:7')
+		expect(oldRecord.focusedGroupId).toBe('shape:8')
+
+		// Old properties should be removed
+		expect(oldRecord.selectedIds).toBeUndefined()
+		expect(oldRecord.hintingIds).toBeUndefined()
+		expect(oldRecord.erasingIds).toBeUndefined()
+		expect(oldRecord.hoveredId).toBeUndefined()
+		expect(oldRecord.editingId).toBeUndefined()
+		expect(oldRecord.croppingId).toBeUndefined()
+		expect(oldRecord.focusLayerId).toBeUndefined()
+	})
+
+	it('should handle down migration for RenamePropertiesAgain', () => {
+		const migration = instancePageStateMigrations.sequence.find(
+			(m) => m.id === instancePageStateVersions.RenamePropertiesAgain
+		)!
+		expect(migration.down).toBeDefined()
+
+		const record: any = {
+			id: 'instance_page_state:test',
+			typeName: 'instance_page_state',
+			selectedShapeIds: ['shape:1', 'shape:2'],
+			hintingShapeIds: ['shape:3'],
+			erasingShapeIds: ['shape:4'],
+			hoveredShapeId: 'shape:5',
+			editingShapeId: 'shape:6',
+			croppingShapeId: 'shape:7',
+			focusedGroupId: 'shape:8',
+		}
+		migration.down!(record)
+
+		expect(record.selectedIds).toEqual(['shape:1', 'shape:2'])
+		expect(record.hintingIds).toEqual(['shape:3'])
+		expect(record.erasingIds).toEqual(['shape:4'])
+		expect(record.hoveredId).toBe('shape:5')
+		expect(record.editingId).toBe('shape:6')
+		expect(record.croppingId).toBe('shape:7')
+		expect(record.focusLayerId).toBe('shape:8')
+
+		// New properties should be removed
+		expect(record.selectedShapeIds).toBeUndefined()
+		expect(record.hintingShapeIds).toBeUndefined()
+		expect(record.erasingShapeIds).toBeUndefined()
+		expect(record.hoveredShapeId).toBeUndefined()
+		expect(record.editingShapeId).toBeUndefined()
+		expect(record.croppingShapeId).toBeUndefined()
+		expect(record.focusedGroupId).toBeUndefined()
+	})
+
+	it('should handle croppingShapeId fallback in RenamePropertiesAgain', () => {
+		const migration = instancePageStateMigrations.sequence.find(
+			(m) => m.id === instancePageStateVersions.RenamePropertiesAgain
+		)!
+
+		// Test with existing croppingShapeId
+		const recordWithCroppingShapeId: any = {
+			croppingShapeId: 'shape:existing',
+			croppingId: 'shape:fallback',
+		}
+		migration.up(recordWithCroppingShapeId)
+		expect(recordWithCroppingShapeId.croppingShapeId).toBe('shape:existing')
+
+		// Test with only croppingId
+		const recordWithCroppingId: any = {
+			croppingId: 'shape:fallback',
+		}
+		migration.up(recordWithCroppingId)
+		expect(recordWithCroppingId.croppingShapeId).toBe('shape:fallback')
+
+		// Test with neither
+		const recordWithNeither: any = {}
+		migration.up(recordWithNeither)
+		expect(recordWithNeither.croppingShapeId).toBe(null)
+	})
+})
+
+describe('InstancePageStateRecordType', () => {
+	it('should have correct ephemeral keys configuration', () => {
+		// Non-ephemeral keys (persistent)
+		expect(InstancePageStateRecordType.ephemeralKeys?.pageId).toBe(false)
+		expect(InstancePageStateRecordType.ephemeralKeys?.selectedShapeIds).toBe(false)
+		expect(InstancePageStateRecordType.ephemeralKeys?.editingShapeId).toBe(false)
+		expect(InstancePageStateRecordType.ephemeralKeys?.croppingShapeId).toBe(false)
+		expect(InstancePageStateRecordType.ephemeralKeys?.meta).toBe(false)
+
+		// Ephemeral keys (temporary)
+		expect(InstancePageStateRecordType.ephemeralKeys?.hintingShapeIds).toBe(true)
+		expect(InstancePageStateRecordType.ephemeralKeys?.erasingShapeIds).toBe(true)
+		expect(InstancePageStateRecordType.ephemeralKeys?.hoveredShapeId).toBe(true)
+		expect(InstancePageStateRecordType.ephemeralKeys?.focusedGroupId).toBe(true)
+	})
+})

package/src/records/TLPointer.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from 'vitest'
+import { pointerMigrations, pointerValidator, pointerVersions, TLPOINTER_ID } from './TLPointer'
+
+describe('pointerValidator', () => {
+	it('should validate valid pointer records', () => {
+		const validPointer = {
+			typeName: 'pointer',
+			id: TLPOINTER_ID,
+			x: 100,
+			y: 200,
+			lastActivityTimestamp: Date.now(),
+			meta: {},
+		}
+
+		expect(() => pointerValidator.validate(validPointer)).not.toThrow()
+	})
+
+	it('should reject pointers with invalid typeName', () => {
+		const invalidPointer = {
+			typeName: 'not-pointer',
+			id: TLPOINTER_ID,
+			x: 0,
+			y: 0,
+			lastActivityTimestamp: 0,
+			meta: {},
+		}
+
+		expect(() => pointerValidator.validate(invalidPointer)).toThrow()
+	})
+
+	it('should reject pointers with missing required fields', () => {
+		const incompletePointer = {
+			typeName: 'pointer',
+			id: TLPOINTER_ID,
+			x: 0,
+			// missing y, lastActivityTimestamp, meta
+		}
+
+		expect(() => pointerValidator.validate(incompletePointer)).toThrow()
+	})
+})
+
+describe('pointerMigrations', () => {
+	it('should apply AddMeta migration correctly', () => {
+		const addMetaMigration = pointerMigrations.sequence.find(
+			(m) => m.id === pointerVersions.AddMeta
+		)!
+
+		const oldRecord: any = {
+			typeName: 'pointer',
+			id: TLPOINTER_ID,
+			x: 100,
+			y: 200,
+			lastActivityTimestamp: 123456,
+		}
+
+		addMetaMigration.up(oldRecord)
+		expect(oldRecord.meta).toEqual({})
+		expect(oldRecord.x).toBe(100)
+		expect(oldRecord.y).toBe(200)
+		expect(oldRecord.lastActivityTimestamp).toBe(123456)
+	})
+})