@tldraw/tlschema 4.1.0-next.542f014c3fac → 4.1.0-next.9f145d10c7d0

package/src/records/TLPage.ts

@@ -10,7 +10,23 @@ import { T } from '@tldraw/validate'
 import { idValidator } from '../misc/id-validator'
 
 /**
- * TLPage
+ * A page within a tldraw document. Pages are containers for shapes and provide
+ * a way to organize content into separate canvases. Each document can have multiple
+ * pages, and users can navigate between them.
+ *
+ * Pages have a name for identification, an index for ordering, and can store
+ * custom metadata.
+ *
+ * @example
+ * ```ts
+ * const page: TLPage = {
+ *   id: 'page:page1',
+ *   typeName: 'page',
+ *   name: 'Page 1',
+ *   index: 'a1',
+ *   meta: { description: 'Main design page' }
+ * }
+ * ```
  *
  * @public
  */
@@ -20,13 +36,47 @@ export interface TLPage extends BaseRecord<'page', TLPageId> {
 	meta: JsonObject
 }
 
-/** @public */
+/**
+ * A unique identifier for TLPage records.
+ *
+ * Page IDs follow the format 'page:' followed by a unique string identifier.
+ *
+ * @example
+ * ```ts
+ * const pageId: TLPageId = 'page:main'
+ * const pageId2: TLPageId = createShapeId() // generates 'page:abc123'
+ * ```
+ *
+ * @public
+ */
 export type TLPageId = RecordId<TLPage>
 
-/** @public */
+/**
+ * Validator for TLPageId values. Ensures the ID follows the correct
+ * format for page records ('page:' prefix).
+ *
+ * @example
+ * ```ts
+ * const isValid = pageIdValidator.isValid('page:main') // true
+ * const isValid2 = pageIdValidator.isValid('shape:abc') // false
+ * ```
+ *
+ * @public
+ */
 export const pageIdValidator = idValidator<TLPageId>('page')
 
-/** @public */
+/**
+ * Runtime validator for TLPage records. Validates the structure and types
+ * of all page properties to ensure data integrity.
+ *
+ * @example
+ * ```ts
+ * const page = { id: 'page:1', typeName: 'page', name: 'My Page', index: 'a1', meta: {} }
+ * const isValid = pageValidator.isValid(page) // true
+ * ```
+ *
+ * @public
+ */
 export const pageValidator: T.Validator<TLPage> = T.model(
 	'page',
 	T.object({
@@ -38,12 +88,28 @@ export const pageValidator: T.Validator<TLPage> = T.model(
 	})
 )
 
-/** @public */
+/**
+ * Migration version identifiers for TLPage records. Each version represents
+ * a schema change that requires data transformation when loading older documents.
+ *
+ * @public
+ */
 export const pageVersions = createMigrationIds('com.tldraw.page', {
 	AddMeta: 1,
 })
 
-/** @public */
+/**
+ * Migration sequence for TLPage records. Defines how to transform page
+ * records between different schema versions, ensuring data compatibility.
+ *
+ * @example
+ * ```ts
+ * // Migrations are applied automatically when loading documents
+ * const migratedPage = pageMigrations.migrate(oldPage, targetVersion)
+ * ```
+ *
+ * @public
+ */
 export const pageMigrations = createRecordMigrationSequence({
 	sequenceId: 'com.tldraw.page',
 	recordType: 'page',
@@ -57,7 +123,24 @@ export const pageMigrations = createRecordMigrationSequence({
 	],
 })
 
-/** @public */
+/**
+ * The RecordType definition for TLPage records. Defines validation, scope,
+ * and default properties for page records in the tldraw store.
+ *
+ * Pages are scoped to the document level, meaning they persist across sessions
+ * and are shared in collaborative environments.
+ *
+ * @example
+ * ```ts
+ * const page = PageRecordType.create({
+ *   id: 'page:main',
+ *   name: 'Main Page',
+ *   index: 'a1'
+ * })
+ * ```
+ *
+ * @public
+ */
 export const PageRecordType = createRecordType<TLPage>('page', {
 	validator: pageValidator,
 	scope: 'document',
@@ -65,7 +148,22 @@ export const PageRecordType = createRecordType<TLPage>('page', {
 	meta: {},
 }))
 
-/** @public */
+/**
+ * Type guard to check if a string is a valid TLPageId.
+ *
+ * @param id - The string to check
+ * @returns True if the ID is a valid page ID, false otherwise
+ *
+ * @example
+ * ```ts
+ * if (isPageId('page:main')) {
+ *   // TypeScript knows this is a TLPageId
+ *   console.log('Valid page ID')
+ * }
+ * ```
+ *
+ * @public
+ */
 export function isPageId(id: string): id is TLPageId {
 	return PageRecordType.isId(id)
 }

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

@@ -13,9 +13,25 @@ import { pageIdValidator, TLPage } from './TLPage'
 import { TLShapeId } from './TLShape'
 
 /**
- * TLInstancePageState
+ * State that is unique to a particular page within a particular browser tab.
+ * This record tracks all page-specific interaction state including selected shapes,
+ * editing state, hover state, and other transient UI state that is tied to
+ * both a specific page and a specific browser session.
  *
- * State that is unique to a particular page of the document in a particular browser tab
+ * Each combination of page and browser tab has its own TLInstancePageState record.
+ *
+ * @example
+ * ```ts
+ * const pageState: TLInstancePageState = {
+ *   id: 'instance_page_state:page1',
+ *   typeName: 'instance_page_state',
+ *   pageId: 'page:page1',
+ *   selectedShapeIds: ['shape:rect1', 'shape:circle2'],
+ *   hoveredShapeId: 'shape:text3',
+ *   editingShapeId: null,
+ *   focusedGroupId: null
+ * }
+ * ```
  *
  * @public
  */
@@ -32,7 +48,24 @@ export interface TLInstancePageState
 	meta: JsonObject
 }
 
-/** @public */
+/**
+ * Runtime validator for TLInstancePageState records. Validates the structure
+ * and types of all instance page state properties to ensure data integrity.
+ *
+ * @example
+ * ```ts
+ * const pageState = {
+ *   id: 'instance_page_state:page1',
+ *   typeName: 'instance_page_state',
+ *   pageId: 'page:page1',
+ *   selectedShapeIds: ['shape:rect1'],
+ *   // ... other properties
+ * }
+ * const isValid = instancePageStateValidator.isValid(pageState) // true
+ * ```
+ *
+ * @public
+ */
 export const instancePageStateValidator: T.Validator<TLInstancePageState> = T.model(
 	'instance_page_state',
 	T.object({
@@ -50,7 +83,13 @@ export const instancePageStateValidator: T.Validator<TLInstancePageState> = T.mo
 	})
 )
 
-/** @public */
+/**
+ * Migration version identifiers for TLInstancePageState records. Each version
+ * represents a schema change that requires data transformation when loading
+ * older documents.
+ *
+ * @public
+ */
 export const instancePageStateVersions = createMigrationIds('com.tldraw.instance_page_state', {
 	AddCroppingId: 1,
 	RemoveInstanceIdAndCameraId: 2,
@@ -59,7 +98,19 @@ export const instancePageStateVersions = createMigrationIds('com.tldraw.instance
 	RenamePropertiesAgain: 5,
 } as const)
 
-/** @public */
+/**
+ * Migration sequence for TLInstancePageState records. Defines how to transform
+ * instance page state records between different schema versions, ensuring data
+ * compatibility when loading documents created with different versions.
+ *
+ * @example
+ * ```ts
+ * // Migrations are applied automatically when loading documents
+ * const migrated = instancePageStateMigrations.migrate(oldState, targetVersion)
+ * ```
+ *
+ * @public
+ */
 export const instancePageStateMigrations = createRecordMigrationSequence({
 	sequenceId: 'com.tldraw.instance_page_state',
 	recordType: 'instance_page_state',
@@ -132,7 +183,25 @@ export const instancePageStateMigrations = createRecordMigrationSequence({
 	],
 })
 
-/** @public */
+/**
+ * The RecordType definition for TLInstancePageState records. Defines validation,
+ * scope, and default properties for instance page state records.
+ *
+ * Instance page states are scoped to the session level, meaning they are
+ * specific to a browser tab and don't persist across sessions or sync
+ * in collaborative environments.
+ *
+ * @example
+ * ```ts
+ * const pageState = InstancePageStateRecordType.create({
+ *   id: 'instance_page_state:page1',
+ *   pageId: 'page:page1',
+ *   selectedShapeIds: ['shape:rect1']
+ * })
+ * ```
+ *
+ * @public
+ */
 export const InstancePageStateRecordType = createRecordType<TLInstancePageState>(
 	'instance_page_state',
 	{
@@ -164,5 +233,17 @@ export const InstancePageStateRecordType = createRecordType<TLInstancePageState>
 	})
 )
 
-/** @public */
+/**
+ * A unique identifier for TLInstancePageState records.
+ *
+ * Instance page state IDs follow the format 'instance_page_state:' followed
+ * by a unique identifier, typically related to the page ID.
+ *
+ * @example
+ * ```ts
+ * const stateId: TLInstancePageStateId = 'instance_page_state:page1'
+ * ```
+ *
+ * @public
+ */
 export type TLInstancePageStateId = RecordId<TLInstancePageState>

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