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

package/src/shapes/TLVideoShape.test.ts

@@ -0,0 +1,112 @@
+import { T } from '@tldraw/validate'
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { TLAssetId } from '../records/TLAsset'
+import { videoShapeMigrations, videoShapeProps, videoShapeVersions } from './TLVideoShape'
+
+describe('TLVideoShape', () => {
+	describe('videoShapeProps validation', () => {
+		it('should validate dimensions as nonZeroNumber', () => {
+			expect(() => videoShapeProps.w.validate(1)).not.toThrow()
+			expect(() => videoShapeProps.h.validate(100)).not.toThrow()
+			expect(() => videoShapeProps.w.validate(0)).toThrow()
+			expect(() => videoShapeProps.h.validate(-1)).toThrow()
+		})
+
+		it('should validate time as number including negatives', () => {
+			expect(() => videoShapeProps.time.validate(0)).not.toThrow()
+			expect(() => videoShapeProps.time.validate(-5)).not.toThrow()
+			expect(() => videoShapeProps.time.validate(30.5)).not.toThrow()
+			expect(() => videoShapeProps.time.validate('not-number')).toThrow()
+		})
+
+		it('should validate boolean properties', () => {
+			expect(() => videoShapeProps.playing.validate(true)).not.toThrow()
+			expect(() => videoShapeProps.autoplay.validate(false)).not.toThrow()
+			expect(() => videoShapeProps.playing.validate('true')).toThrow()
+		})
+
+		it('should validate URLs and assetIds', () => {
+			expect(() => videoShapeProps.url.validate('')).not.toThrow()
+			expect(() => videoShapeProps.url.validate('https://example.com/video.mp4')).not.toThrow()
+			expect(() => videoShapeProps.assetId.validate(null)).not.toThrow()
+			expect(() => videoShapeProps.assetId.validate('asset:video123' as TLAssetId)).not.toThrow()
+			expect(() => videoShapeProps.altText.validate('Alt text')).not.toThrow()
+		})
+
+		it('should validate complete props object', () => {
+			const validator = T.object(videoShapeProps)
+			const validProps = {
+				w: 640,
+				h: 480,
+				time: 0,
+				playing: false,
+				autoplay: true,
+				url: 'https://example.com/video.mp4',
+				assetId: 'asset:video123' as TLAssetId,
+				altText: 'Test video',
+			}
+			expect(() => validator.validate(validProps)).not.toThrow()
+		})
+	})
+
+	describe('videoShapeVersions', () => {
+		it('should have expected migration versions', () => {
+			expect(videoShapeVersions.AddUrlProp).toBeDefined()
+			expect(videoShapeVersions.MakeUrlsValid).toBeDefined()
+			expect(videoShapeVersions.AddAltText).toBeDefined()
+			expect(videoShapeVersions.AddAutoplay).toBeDefined()
+		})
+	})
+
+	describe('videoShapeMigrations', () => {
+		it('should add url property in AddUrlProp migration', () => {
+			const { up } = getTestMigration(videoShapeVersions.AddUrlProp)
+			const oldRecord = {
+				props: { w: 640, h: 480, time: 30, playing: true, assetId: 'asset:video123' },
+			}
+			const result = up(oldRecord)
+			expect(result.props.url).toBe('')
+			expect(result.props.w).toBe(640)
+		})
+
+		it('should clear invalid URLs in MakeUrlsValid migration', () => {
+			const { up } = getTestMigration(videoShapeVersions.MakeUrlsValid)
+			const oldRecord = {
+				props: { url: 'invalid-url', w: 400, h: 300 },
+			}
+			const result = up(oldRecord)
+			expect(result.props.url).toBe('')
+		})
+
+		it('should add altText in AddAltText migration', () => {
+			const { up, down } = getTestMigration(videoShapeVersions.AddAltText)
+			const oldRecord = { props: { w: 800, h: 600 } }
+			const result = up(oldRecord)
+			expect(result.props.altText).toBe('')
+
+			// Test down migration removes altText
+			const newRecord = { props: { w: 640, h: 480, altText: 'Test' } }
+			const downResult = down(newRecord)
+			expect(downResult.props.altText).toBeUndefined()
+		})
+
+		it('should add autoplay in AddAutoplay migration', () => {
+			const { up, down } = getTestMigration(videoShapeVersions.AddAutoplay)
+			const oldRecord = { props: { w: 480, h: 270 } }
+			const result = up(oldRecord)
+			expect(result.props.autoplay).toBe(true)
+
+			// Test down migration removes autoplay
+			const newRecord = { props: { w: 800, h: 450, autoplay: false } }
+			const downResult = down(newRecord)
+			expect(downResult.props.autoplay).toBeUndefined()
+		})
+
+		it('should have migrations for all versions', () => {
+			expect(videoShapeMigrations.sequence).toBeDefined()
+			expect(Array.isArray(videoShapeMigrations.sequence)).toBe(true)
+			expect(videoShapeMigrations.sequence.length).toBeGreaterThanOrEqual(4)
+		})
+	})
+})

package/src/shapes/TLVideoShape.ts

@@ -5,7 +5,26 @@ import { createShapePropsMigrationIds, createShapePropsMigrationSequence } from
 import { RecordProps } from '../recordsWithProps'
 import { TLBaseShape } from './TLBaseShape'
 
-/** @public */
+/**
+ * Configuration interface defining properties for video shapes in tldraw.
+ * Video shapes can display video content from URLs or asset references,
+ * with controls for playback state, timing, and accessibility.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const videoProps: TLVideoShapeProps = {
+ *   w: 640,
+ *   h: 480,
+ *   time: 0,
+ *   playing: false,
+ *   autoplay: true,
+ *   url: 'https://example.com/video.mp4',
+ *   assetId: 'asset:video123',
+ *   altText: 'Educational video about shapes'
+ * }
+ * ```
+ */
 export interface TLVideoShapeProps {
 	w: number
 	h: number
@@ -17,10 +36,60 @@ export interface TLVideoShapeProps {
 	altText: string
 }
 
-/** @public */
+/**
+ * A video shape that can display video content with playback controls and timing.
+ * Video shapes support both direct URL references and asset-based video storage,
+ * with accessibility features and playback state management.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const videoShape: TLVideoShape = {
+ *   id: 'shape:video123',
+ *   typeName: 'shape',
+ *   type: 'video',
+ *   x: 100,
+ *   y: 100,
+ *   rotation: 0,
+ *   index: 'a1',
+ *   parentId: 'page:main',
+ *   isLocked: false,
+ *   opacity: 1,
+ *   props: {
+ *     w: 640,
+ *     h: 480,
+ *     time: 15.5,
+ *     playing: false,
+ *     autoplay: false,
+ *     url: 'https://example.com/video.mp4',
+ *     assetId: 'asset:video123',
+ *     altText: 'Product demo video'
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ */
 export type TLVideoShape = TLBaseShape<'video', TLVideoShapeProps>
 
-/** @public */
+/**
+ * Validation schema for video shape properties. This defines the runtime validation
+ * rules that ensure video shape data integrity, including URL validation, numeric
+ * constraints, and proper asset ID formatting.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { videoShapeProps } from '@tldraw/tlschema'
+ *
+ * // Validate video URL
+ * const isValidUrl = videoShapeProps.url.isValid('https://example.com/video.mp4')
+ * const isValidTime = videoShapeProps.time.isValid(42.5)
+ *
+ * if (isValidUrl && isValidTime) {
+ *   // Video properties are valid
+ * }
+ * ```
+ */
 export const videoShapeProps: RecordProps<TLVideoShape> = {
 	w: T.nonZeroNumber,
 	h: T.nonZeroNumber,
@@ -39,9 +108,35 @@ const Versions = createShapePropsMigrationIds('video', {
 	AddAutoplay: 4,
 })
 
+/**
+ * Version identifiers for video shape migrations. These constants track
+ * the evolution of the video shape schema over time.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { videoShapeVersions } from '@tldraw/tlschema'
+ *
+ * // Check if shape data needs migration
+ * if (shapeVersion < videoShapeVersions.AddAltText) {
+ *   // Apply alt text migration for accessibility
+ * }
+ * ```
+ */
 export { Versions as videoShapeVersions }
 
-/** @public */
+/**
+ * Migration sequence for video shape schema evolution. This handles transforming
+ * video shape data between different versions as the schema evolves over time.
+ *
+ * Key migrations include:
+ * - AddUrlProp: Added URL property for direct video links
+ * - MakeUrlsValid: Ensured all URLs conform to link URL validation
+ * - AddAltText: Added accessibility support with alternative text
+ * - AddAutoplay: Added autoplay control for video playback
+ *
+ * @public
+ */
 export const videoShapeMigrations = createShapePropsMigrationSequence({
 	sequence: [
 		{

package/src/store-migrations.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from './__tests__/migrationTestUtils'
+import { storeMigrations, storeVersions } from './store-migrations'
+
+describe('storeMigrations', () => {
+	it('has valid migration sequence structure', () => {
+		expect(storeMigrations.sequenceId).toBe('com.tldraw.store')
+		expect(storeMigrations.retroactive).toBe(false)
+		expect(storeMigrations.sequence.length).toBeGreaterThan(0)
+
+		// Verify all migrations have required fields
+		for (const migration of storeMigrations.sequence) {
+			expect(migration.id).toBeDefined()
+			expect(migration.scope).toBeDefined()
+			expect(migration.up).toBeInstanceOf(Function)
+		}
+	})
+})
+
+describe('RemoveCodeAndIconShapeTypes migration', () => {
+	const { up } = getTestMigration(storeVersions.RemoveCodeAndIconShapeTypes)
+
+	it('removes icon and code shapes from store', () => {
+		const store = {
+			'shape:icon1': { typeName: 'shape', type: 'icon' },
+			'shape:code1': { typeName: 'shape', type: 'code' },
+			'shape:geo1': { typeName: 'shape', type: 'geo' },
+			'page:test': { typeName: 'page' },
+		}
+
+		const result = up(store)
+
+		expect(result['shape:icon1']).toBeUndefined()
+		expect(result['shape:code1']).toBeUndefined()
+		expect(result['shape:geo1']).toBeDefined()
+		expect(result['page:test']).toBeDefined()
+	})
+})
+
+describe('AddInstancePresenceType migration', () => {
+	const { up } = getTestMigration(storeVersions.AddInstancePresenceType)
+
+	it('is a no-op migration', () => {
+		const store = { 'page:test': { typeName: 'page' } }
+		const result = up(store)
+		expect(result).toEqual(store)
+	})
+})
+
+describe('RemoveTLUserAndPresenceAndAddPointer migration', () => {
+	const { up } = getTestMigration(storeVersions.RemoveTLUserAndPresenceAndAddPointer)
+
+	it('removes user and user_presence records', () => {
+		const store = {
+			'user:123': { typeName: 'user' },
+			'user_presence:456': { typeName: 'user_presence' },
+			'instance:789': { typeName: 'instance' },
+			'user_something:abc': { typeName: 'user_something' }, // Should not match
+		}
+
+		const result = up(store)
+
+		expect(result['user:123']).toBeUndefined()
+		expect(result['user_presence:456']).toBeUndefined()
+		expect(result['instance:789']).toBeDefined()
+		expect(result['user_something:abc']).toBeDefined() // Uses exact regex match
+	})
+})
+
+describe('RemoveUserDocument migration', () => {
+	const { up } = getTestMigration(storeVersions.RemoveUserDocument)
+
+	it('removes user_document records', () => {
+		const store = {
+			'user_document:123': { typeName: 'user_document' },
+			'user_document_meta:456': { typeName: 'user_document_meta' }, // Also matches due to substring
+			'document:789': { typeName: 'document' },
+			'instance:abc': { typeName: 'instance' },
+		}
+
+		const result = up(store)
+
+		expect(result['user_document:123']).toBeUndefined()
+		expect(result['user_document_meta:456']).toBeUndefined() // Uses match() which finds substring
+		expect(result['document:789']).toBeDefined()
+		expect(result['instance:abc']).toBeDefined()
+	})
+})

package/src/store-migrations.ts

@@ -4,6 +4,12 @@ import { TLPage } from './records/TLPage'
 import { TLShape } from './records/TLShape'
 import { TLLineShape } from './shapes/TLLineShape'
 
+/**
+ * Migration version constants for store-level schema changes.
+ * Each version represents a breaking change that requires data transformation.
+ *
+ * @internal
+ */
 const Versions = createMigrationIds('com.tldraw.store', {
 	RemoveCodeAndIconShapeTypes: 1,
 	AddInstancePresenceType: 2,
@@ -12,9 +18,49 @@ const Versions = createMigrationIds('com.tldraw.store', {
 	FixIndexKeys: 5,
 } as const)
 
+/**
+ * Migration version identifiers for store-level migrations.
+ * These versions track changes to the overall store structure and data model.
+ *
+ * @example
+ * ```ts
+ * import { storeVersions } from '@tldraw/tlschema'
+ *
+ * // Check if a specific migration version exists
+ * const hasRemoveCodeShapes = storeVersions.RemoveCodeAndIconShapeTypes
+ * ```
+ *
+ * @public
+ */
 export { Versions as storeVersions }
 
-/** @public */
+/**
+ * Store-level migration sequence that handles evolution of the tldraw data model.
+ * These migrations run when the store schema version changes and ensure backward
+ * compatibility by transforming old data structures to new formats.
+ *
+ * The migrations handle:
+ * - Removal of deprecated shape types (code, icon)
+ * - Addition of new record types (instance presence)
+ * - Cleanup of obsolete user and presence data
+ * - Removal of deprecated user document records
+ *
+ * @example
+ * ```ts
+ * import { storeMigrations } from '@tldraw/tlschema'
+ * import { migrate } from '@tldraw/store'
+ *
+ * // Apply store migrations to old data
+ * const migratedStore = migrate({
+ *   store: oldStoreData,
+ *   migrations: storeMigrations,
+ *   fromVersion: 0,
+ *   toVersion: storeMigrations.currentVersion
+ * })
+ * ```
+ *
+ * @public
+ */
 export const storeMigrations = createMigrationSequence({
 	sequenceId: 'com.tldraw.store',
 	retroactive: false,