@tldraw/tlschema 4.1.0-canary.ccd6179e1cb2 → 4.1.0-canary.e23ee15a46bc

package/src/records/TLDocument.ts

@@ -10,17 +10,58 @@ import { JsonObject } from '@tldraw/utils'
 import { T } from '@tldraw/validate'
 
 /**
- * TLDocument
+ * Document record containing global settings and metadata for a tldraw document.
+ * There is exactly one document record per tldraw instance with a fixed ID.
+ *
+ * @example
+ * ```ts
+ * const document: TLDocument = {
+ *   id: 'document:document',
+ *   typeName: 'document',
+ *   gridSize: 20,        // Grid snap size in pixels
+ *   name: 'My Drawing',  // Document name
+ *   meta: {
+ *     createdAt: Date.now(),
+ *     author: 'user123',
+ *     version: '1.0.0'
+ *   }
+ * }
+ *
+ * // Update document settings
+ * editor.updateDocumentSettings({
+ *   name: 'Updated Drawing',
+ *   gridSize: 25
+ * })
+ * ```
  *
  * @public
  */
 export interface TLDocument extends BaseRecord<'document', RecordId<TLDocument>> {
+	/** Grid snap size in pixels. Used for shape positioning and alignment */
 	gridSize: number
+	/** Human-readable name of the document */
 	name: string
+	/** User-defined metadata for the document */
 	meta: JsonObject
 }
 
-/** @public */
+/**
+ * Validator for TLDocument records that ensures runtime type safety.
+ * Enforces the fixed document ID and validates all document properties.
+ *
+ * @example
+ * ```ts
+ * // Validation happens automatically when document is stored
+ * try {
+ *   const validatedDocument = documentValidator.validate(documentData)
+ *   store.put([validatedDocument])
+ * } catch (error) {
+ *   console.error('Document validation failed:', error.message)
+ * }
+ * ```
+ *
+ * @public
+ */
 export const documentValidator: T.Validator<TLDocument> = T.model(
 	'document',
 	T.object({
@@ -32,19 +73,72 @@ export const documentValidator: T.Validator<TLDocument> = T.model(
 	})
 )
 
-/** @public */
+/**
+ * Type guard to check if a record is a TLDocument.
+ * Useful for filtering or type narrowing when working with mixed record types.
+ *
+ * @param record - The record to check
+ * @returns True if the record is a document, false otherwise
+ *
+ * @example
+ * ```ts
+ * // Type guard usage
+ * function processRecord(record: UnknownRecord) {
+ *   if (isDocument(record)) {
+ *     // record is now typed as TLDocument
+ *     console.log(`Document: ${record.name}, Grid: ${record.gridSize}px`)
+ *   }
+ * }
+ *
+ * // Filter documents from mixed records
+ * const allRecords = store.allRecords()
+ * const documents = allRecords.filter(isDocument) // Should be exactly one
+ * ```
+ *
+ * @public
+ */
 export function isDocument(record?: UnknownRecord): record is TLDocument {
 	if (!record) return false
 	return record.typeName === 'document'
 }
 
-/** @public */
+/**
+ * Migration version identifiers for document record schema evolution.
+ * Each version represents a breaking change that requires data migration.
+ *
+ * @example
+ * ```ts
+ * // Check if document needs migration
+ * const needsNameMigration = currentVersion < documentVersions.AddName
+ * const needsMetaMigration = currentVersion < documentVersions.AddMeta
+ * ```
+ *
+ * @public
+ */
 export const documentVersions = createMigrationIds('com.tldraw.document', {
 	AddName: 1,
 	AddMeta: 2,
 } as const)
 
-/** @public */
+/**
+ * Migration sequence for evolving document record structure over time.
+ * Handles converting document records from older schema versions to current format.
+ *
+ * @example
+ * ```ts
+ * // Migration is applied automatically when loading old documents
+ * const migratedStore = migrator.migrateStoreSnapshot({
+ *   schema: oldSchema,
+ *   store: oldStoreSnapshot
+ * })
+ *
+ * // The migrations:
+ * // v1: Added 'name' property with empty string default
+ * // v2: Added 'meta' property with empty object default
+ * ```
+ *
+ * @public
+ */
 export const documentMigrations = createRecordMigrationSequence({
 	sequenceId: 'com.tldraw.document',
 	recordType: 'document',
@@ -67,7 +161,32 @@ export const documentMigrations = createRecordMigrationSequence({
 	],
 })
 
-/** @public */
+/**
+ * Record type definition for TLDocument with validation and default properties.
+ * Configures the document as a document-scoped record that persists across sessions.
+ *
+ * @example
+ * ```ts
+ * // Create a document record (usually done automatically)
+ * const documentRecord = DocumentRecordType.create({
+ *   id: TLDOCUMENT_ID,
+ *   name: 'My Drawing',
+ *   gridSize: 20,
+ *   meta: { createdAt: Date.now() }
+ * })
+ *
+ * // Create with defaults
+ * const defaultDocument = DocumentRecordType.create({
+ *   id: TLDOCUMENT_ID
+ *   // gridSize: 10, name: '', meta: {} are applied as defaults
+ * })
+ *
+ * // Store the document
+ * store.put([documentRecord])
+ * ```
+ *
+ * @public
+ */
 export const DocumentRecordType = createRecordType<TLDocument>('document', {
 	validator: documentValidator,
 	scope: 'document',
@@ -79,6 +198,27 @@ export const DocumentRecordType = createRecordType<TLDocument>('document', {
 	})
 )
 
-// all document records have the same ID: 'document:document'
-/** @public */
+/**
+ * The fixed ID for the singleton document record in every tldraw store.
+ * All document records use this same ID: 'document:document'
+ *
+ * @example
+ * ```ts
+ * // Get the document from store
+ * const document = store.get(TLDOCUMENT_ID)
+ *
+ * // Update document settings
+ * store.put([{
+ *   ...document,
+ *   name: 'Updated Name',
+ *   gridSize: 25
+ * }])
+ *
+ * // Access via editor
+ * const documentSettings = editor.getDocumentSettings()
+ * editor.updateDocumentSettings({ name: 'New Name' })
+ * ```
+ *
+ * @public
+ */
 export const TLDOCUMENT_ID: RecordId<TLDocument> = DocumentRecordType.createId('document')

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/TLInstance.ts

@@ -17,9 +17,25 @@ import { pageIdValidator, TLPageId } from './TLPage'
 import { TLShapeId } from './TLShape'
 
 /**
- * TLInstance
+ * State that is particular to a single browser tab. The TLInstance record stores
+ * all session-specific state including cursor position, selected tools, UI preferences,
+ * and temporary interaction state.
  *
- * State that is particular to a single browser tab
+ * Each browser tab has exactly one TLInstance record that persists for the duration
+ * of the session and tracks the user's current interaction state.
+ *
+ * @example
+ * ```ts
+ * const instance: TLInstance = {
+ *   id: 'instance:instance',
+ *   typeName: 'instance',
+ *   currentPageId: 'page:page1',
+ *   cursor: { type: 'default', rotation: 0 },
+ *   screenBounds: { x: 0, y: 0, w: 1920, h: 1080 },
+ *   isFocusMode: false,
+ *   isGridMode: true
+ * }
+ * ```
  *
  * @public
  */
@@ -68,7 +84,14 @@ export interface TLInstance extends BaseRecord<'instance', TLInstanceId> {
 	} | null
 }
 
-/** @internal */
+/**
+ * Configuration object defining which TLInstance properties should be preserved
+ * when loading snapshots across browser sessions. Properties marked as `true`
+ * represent user preferences that should persist, while `false` indicates
+ * temporary state that should reset.
+ *
+ * @internal
+ */
 export const shouldKeyBePreservedBetweenSessions = {
 	// This object defines keys that should be preserved across calls to loadSnapshot()
 
@@ -108,7 +131,15 @@ export const shouldKeyBePreservedBetweenSessions = {
 	duplicateProps: false, //
 } as const satisfies { [K in keyof TLInstance]: boolean }
 
-/** @internal */
+/**
+ * Extracts only the properties from a TLInstance that should be preserved
+ * between browser sessions, filtering out temporary state.
+ *
+ * @param val - The TLInstance to filter, or null/undefined
+ * @returns A partial TLInstance containing only preservable properties, or null
+ *
+ * @internal
+ */
 export function pluckPreservingValues(val?: TLInstance | null): null | Partial<TLInstance> {
 	return val
 		? (filterEntries(val, (key) => {
@@ -117,12 +148,51 @@ export function pluckPreservingValues(val?: TLInstance | null): null | Partial<T
 		: null
 }
 
-/** @public */
+/**
+ * A unique identifier for TLInstance records.
+ *
+ * TLInstance IDs are always the constant 'instance:instance' since there
+ * is exactly one instance record per browser tab.
+ *
+ * @public
+ */
 export type TLInstanceId = RecordId<TLInstance>
 
-/** @public */
+/**
+ * Validator for TLInstanceId values. Ensures the ID follows the correct
+ * format for instance records.
+ *
+ * @example
+ * ```ts
+ * const isValid = instanceIdValidator.isValid('instance:instance') // true
+ * const isValid2 = instanceIdValidator.isValid('invalid') // false
+ * ```
+ *
+ * @public
+ */
 export const instanceIdValidator = idValidator<TLInstanceId>('instance')
 
+/**
+ * Creates the record type definition for TLInstance records, including validation
+ * and default properties. The function takes a map of available style properties
+ * to configure validation for the stylesForNextShape field.
+ *
+ * @param stylesById - Map of style property IDs to their corresponding StyleProp definitions
+ * @returns A configured RecordType for TLInstance records
+ *
+ * @example
+ * ```ts
+ * const stylesMap = new Map([['color', DefaultColorStyle]])
+ * const InstanceRecordType = createInstanceRecordType(stylesMap)
+ *
+ * const instance = InstanceRecordType.create({
+ *   id: 'instance:instance',
+ *   currentPageId: 'page:page1'
+ * })
+ * ```
+ *
+ * @public
+ */
 export function createInstanceRecordType(stylesById: Map<string, StyleProp<unknown>>) {
 	const stylesForNextShapeValidators = {} as Record<string, T.Validator<unknown>>
 	for (const [id, style] of stylesById) {
@@ -241,7 +311,15 @@ export function createInstanceRecordType(stylesById: Map<string, StyleProp<unkno
 	)
 }
 
-/** @public */
+/**
+ * Migration version identifiers for TLInstance records. Each version represents
+ * a schema change that requires data transformation when loading older documents.
+ *
+ * The versions track the evolution of the instance record structure over time,
+ * enabling backward and forward compatibility.
+ *
+ * @public
+ */
 export const instanceVersions = createMigrationIds('com.tldraw.instance', {
 	AddTransparentExportBgs: 1,
 	RemoveDialog: 2,
@@ -272,7 +350,22 @@ export const instanceVersions = createMigrationIds('com.tldraw.instance', {
 
 // TODO: rewrite these to use mutation
 
-/** @public */
+/**
+ * Migration sequence for TLInstance records. Defines how to transform instance
+ * records between different schema versions, ensuring data compatibility when
+ * loading documents created with different versions of tldraw.
+ *
+ * Each migration includes an 'up' function to migrate forward and optionally
+ * a 'down' function for reverse migration.
+ *
+ * @example
+ * ```ts
+ * // Migrations are applied automatically when loading documents
+ * const migratedInstance = instanceMigrations.migrate(oldInstance, targetVersion)
+ * ```
+ *
+ * @public
+ */
 export const instanceMigrations = createRecordMigrationSequence({
 	sequenceId: 'com.tldraw.instance',
 	recordType: 'instance',
@@ -524,5 +617,20 @@ export const instanceMigrations = createRecordMigrationSequence({
 	],
 })
 
-/** @public */
+/**
+ * The constant ID used for the singleton TLInstance record.
+ *
+ * Since each browser tab has exactly one instance, this constant ID
+ * is used universally across the application.
+ *
+ * @example
+ * ```ts
+ * const instance = store.get(TLINSTANCE_ID)
+ * if (instance) {
+ *   console.log('Current page:', instance.currentPageId)
+ * }
+ * ```
+ *
+ * @public
+ */
 export const TLINSTANCE_ID = 'instance:instance' as TLInstanceId

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