@tldraw/tlschema 4.1.0-canary.bdf9b3703a3d → 4.1.0-canary.c0b3a5b0ca61

package/src/assets/TLImageAsset.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { imageAssetVersions } from './TLImageAsset'
+
+describe('TLImageAsset', () => {
+	describe('AddIsAnimated migration', () => {
+		const { up, down } = getTestMigration(imageAssetVersions.AddIsAnimated)
+
+		it('should add isAnimated property in up migration', () => {
+			const assetWithoutIsAnimated = {
+				id: 'asset:image1',
+				type: 'image',
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+				},
+			}
+
+			const result = up(assetWithoutIsAnimated)
+			expect(result.props.isAnimated).toBe(false)
+		})
+
+		it('should remove isAnimated property in down migration', () => {
+			const assetWithIsAnimated = {
+				id: 'asset:image3',
+				type: 'image',
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+					isAnimated: false,
+				},
+			}
+
+			const result = down(assetWithIsAnimated)
+			expect(result.props).not.toHaveProperty('isAnimated')
+		})
+	})
+
+	describe('RenameWidthHeight migration', () => {
+		const { up, down } = getTestMigration(imageAssetVersions.RenameWidthHeight)
+
+		it('should rename width and height to w and h in up migration', () => {
+			const assetWithWidthHeight = {
+				id: 'asset:image1',
+				type: 'image',
+				props: {
+					width: 800,
+					height: 600,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+				},
+			}
+
+			const result = up(assetWithWidthHeight)
+			expect(result.props.w).toBe(800)
+			expect(result.props.h).toBe(600)
+			expect(result.props).not.toHaveProperty('width')
+			expect(result.props).not.toHaveProperty('height')
+		})
+
+		it('should rename w and h to width and height in down migration', () => {
+			const assetWithWH = {
+				id: 'asset:image3',
+				type: 'image',
+				props: {
+					w: 1024,
+					h: 768,
+					name: 'test.png',
+					isAnimated: false,
+					mimeType: 'image/png',
+					src: 'https://example.com/test.png',
+				},
+			}
+
+			const result = down(assetWithWH)
+			expect(result.props.width).toBe(1024)
+			expect(result.props.height).toBe(768)
+			expect(result.props).not.toHaveProperty('w')
+			expect(result.props).not.toHaveProperty('h')
+		})
+	})
+
+	describe('MakeUrlsValid migration', () => {
+		const { up, down: _down } = getTestMigration(imageAssetVersions.MakeUrlsValid)
+
+		it('should clean invalid src URLs in up migration', () => {
+			const assetWithInvalidSrc = {
+				id: 'asset:image1',
+				type: 'image',
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'invalid-url-format',
+				},
+			}
+
+			const result = up(assetWithInvalidSrc)
+			expect(result.props.src).toBe('')
+		})
+
+		it('should preserve valid src URLs in up migration', () => {
+			const assetWithValidSrc = {
+				id: 'asset:image2',
+				type: 'image',
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+				},
+			}
+
+			const result = up(assetWithValidSrc)
+			expect(result.props.src).toBe('https://example.com/test.jpg')
+		})
+	})
+
+	describe('AddFileSize migration', () => {
+		const { up, down } = getTestMigration(imageAssetVersions.AddFileSize)
+
+		it('should add fileSize property with -1 default in up migration', () => {
+			const assetWithoutFileSize = {
+				id: 'asset:image1',
+				type: 'image',
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+				},
+			}
+
+			const result = up(assetWithoutFileSize)
+			expect(result.props.fileSize).toBe(-1)
+		})
+
+		it('should remove fileSize property in down migration', () => {
+			const assetWithFileSize = {
+				id: 'asset:image3',
+				type: 'image',
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+					fileSize: 50000,
+				},
+			}
+
+			const result = down(assetWithFileSize)
+			expect(result.props).not.toHaveProperty('fileSize')
+		})
+	})
+
+	describe('MakeFileSizeOptional migration', () => {
+		const { up, down } = getTestMigration(imageAssetVersions.MakeFileSizeOptional)
+
+		it('should convert fileSize -1 to undefined in up migration', () => {
+			const assetWithNegativeFileSize = {
+				id: 'asset:image1',
+				type: 'image',
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+					fileSize: -1,
+				},
+			}
+
+			const result = up(assetWithNegativeFileSize)
+			expect(result.props.fileSize).toBeUndefined()
+		})
+
+		it('should convert undefined fileSize to -1 in down migration', () => {
+			const assetWithUndefinedFileSize = {
+				id: 'asset:image5',
+				type: 'image',
+				props: {
+					w: 100,
+					h: 100,
+					name: 'test.jpg',
+					isAnimated: false,
+					mimeType: 'image/jpeg',
+					src: 'https://example.com/test.jpg',
+					fileSize: undefined,
+				},
+			}
+
+			const result = down(assetWithUndefinedFileSize)
+			expect(result.props.fileSize).toBe(-1)
+		})
+	})
+})

package/src/assets/TLImageAsset.ts

@@ -20,7 +20,36 @@ export type TLImageAsset = TLBaseAsset<
 	}
 >
 
-/** @public */
+/**
+ * Validator for image assets. Validates the structure and properties of TLImageAsset records
+ * to ensure data integrity when image assets are stored or retrieved from the tldraw store.
+ *
+ * @example
+ * ```ts
+ * import { imageAssetValidator } from '@tldraw/tlschema'
+ *
+ * const imageAsset = {
+ *   id: 'asset:image123',
+ *   typeName: 'asset',
+ *   type: 'image',
+ *   props: {
+ *     w: 800,
+ *     h: 600,
+ *     name: 'photo.jpg',
+ *     isAnimated: false,
+ *     mimeType: 'image/jpeg',
+ *     src: 'https://example.com/photo.jpg',
+ *     fileSize: 156000
+ *   },
+ *   meta: {}
+ * }
+ *
+ * // Validate the asset
+ * const isValid = imageAssetValidator.validate(imageAsset)
+ * ```
+ *
+ * @public
+ */
 export const imageAssetValidator: T.Validator<TLImageAsset> = createAssetValidator(
 	'image',
 	T.object({
@@ -42,9 +71,38 @@ const Versions = createMigrationIds('com.tldraw.asset.image', {
 	MakeFileSizeOptional: 5,
 } as const)
 
+/**
+ * Migration version identifiers for image assets. These define the different schema versions
+ * that image assets have gone through during the evolution of the tldraw data model.
+ *
+ * @example
+ * ```ts
+ * import { imageAssetVersions } from '@tldraw/tlschema'
+ *
+ * // Access specific version IDs
+ * console.log(imageAssetVersions.AddIsAnimated) // Version when isAnimated was added
+ * console.log(imageAssetVersions.RenameWidthHeight) // Version when width/height became w/h
+ * ```
+ *
+ * @public
+ */
 export { Versions as imageAssetVersions }
 
-/** @public */
+/**
+ * Migration sequence for image assets. Handles the evolution of the image asset schema
+ * over time, providing both forward (up) and backward (down) migration functions to
+ * maintain compatibility across different versions of the tldraw data model.
+ *
+ * The sequence includes migrations for:
+ * - Adding the `isAnimated` property to track animated images
+ * - Renaming `width`/`height` properties to shorter `w`/`h` names
+ * - Ensuring URLs are valid format
+ * - Adding file size tracking
+ * - Making file size optional
+ *
+ *
+ * @public
+ */
 export const imageAssetMigrations = createRecordMigrationSequence({
 	sequenceId: 'com.tldraw.asset.image',
 	recordType: 'asset',

package/src/assets/TLVideoAsset.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { videoAssetVersions } from './TLVideoAsset'
+
+describe('TLVideoAsset', () => {
+	describe('migrations', () => {
+		it('should handle AddIsAnimated migration', () => {
+			const { up, down } = getTestMigration(videoAssetVersions.AddIsAnimated)
+
+			const assetWithoutIsAnimated = {
+				id: 'asset:video1',
+				type: 'video',
+				props: {
+					w: 640,
+					h: 480,
+					name: 'test.mp4',
+					mimeType: 'video/mp4',
+					src: 'https://example.com/test.mp4',
+				},
+			}
+
+			const upResult = up(assetWithoutIsAnimated)
+			expect(upResult.props.isAnimated).toBe(false)
+
+			const downResult = down(upResult)
+			expect(downResult.props).not.toHaveProperty('isAnimated')
+		})
+
+		it('should handle RenameWidthHeight migration', () => {
+			const { up, down } = getTestMigration(videoAssetVersions.RenameWidthHeight)
+
+			const assetWithWidthHeight = {
+				id: 'asset:video1',
+				type: 'video',
+				props: {
+					width: 1920,
+					height: 1080,
+					name: 'test.mp4',
+					isAnimated: true,
+					mimeType: 'video/mp4',
+					src: 'https://example.com/test.mp4',
+				},
+			}
+
+			const upResult = up(assetWithWidthHeight)
+			expect(upResult.props.w).toBe(1920)
+			expect(upResult.props.h).toBe(1080)
+			expect(upResult.props).not.toHaveProperty('width')
+			expect(upResult.props).not.toHaveProperty('height')
+
+			const downResult = down(upResult)
+			expect(downResult.props.width).toBe(1920)
+			expect(downResult.props.height).toBe(1080)
+			expect(downResult.props).not.toHaveProperty('w')
+			expect(downResult.props).not.toHaveProperty('h')
+		})
+
+		it('should handle MakeUrlsValid migration', () => {
+			const { up } = getTestMigration(videoAssetVersions.MakeUrlsValid)
+
+			const assetWithInvalidSrc = {
+				id: 'asset:video1',
+				type: 'video',
+				props: {
+					w: 640,
+					h: 480,
+					name: 'test.mp4',
+					isAnimated: true,
+					mimeType: 'video/mp4',
+					src: 'invalid-url-format',
+				},
+			}
+
+			const result = up(assetWithInvalidSrc)
+			expect(result.props.src).toBe('')
+		})
+
+		it('should handle MakeFileSizeOptional migration', () => {
+			const { up, down } = getTestMigration(videoAssetVersions.MakeFileSizeOptional)
+
+			const assetWithNegativeFileSize = {
+				id: 'asset:video1',
+				type: 'video',
+				props: {
+					w: 640,
+					h: 480,
+					name: 'test.mp4',
+					isAnimated: true,
+					mimeType: 'video/mp4',
+					src: 'https://example.com/test.mp4',
+					fileSize: -1,
+				},
+			}
+
+			const upResult = up(assetWithNegativeFileSize)
+			expect(upResult.props.fileSize).toBeUndefined()
+
+			const downResult = down({
+				...assetWithNegativeFileSize,
+				props: { ...assetWithNegativeFileSize.props, fileSize: undefined },
+			})
+			expect(downResult.props.fileSize).toBe(-1)
+		})
+	})
+})

package/src/assets/TLVideoAsset.ts

@@ -4,23 +4,83 @@ import { TLAsset } from '../records/TLAsset'
 import { TLBaseAsset, createAssetValidator } from './TLBaseAsset'
 
 /**
- * An asset used for videos, used by the TLVideoShape.
+ * An asset record representing video files that can be displayed in video shapes.
+ * Video assets store metadata about video files including dimensions, MIME type,
+ * animation status, and file source information. They are referenced by TLVideoShape
+ * instances to display video content on the canvas.
  *
- * @public */
+ * @example
+ * ```ts
+ * import { TLVideoAsset } from '@tldraw/tlschema'
+ *
+ * const videoAsset: TLVideoAsset = {
+ *   id: 'asset:video123',
+ *   typeName: 'asset',
+ *   type: 'video',
+ *   props: {
+ *     w: 1920,
+ *     h: 1080,
+ *     name: 'my-video.mp4',
+ *     isAnimated: true,
+ *     mimeType: 'video/mp4',
+ *     src: 'https://example.com/video.mp4',
+ *     fileSize: 5242880
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLVideoAsset = TLBaseAsset<
 	'video',
 	{
+		/** The width of the video in pixels */
 		w: number
+		/** The height of the video in pixels */
 		h: number
+		/** The original filename or display name of the video */
 		name: string
+		/** Whether the video contains animation/motion (true for most videos) */
 		isAnimated: boolean
+		/** The MIME type of the video file (e.g., 'video/mp4', 'video/webm'), null if unknown */
 		mimeType: string | null
+		/** The source URL or data URI for the video file, null if not yet available */
 		src: string | null
+		/** The file size in bytes, optional for backward compatibility */
 		fileSize?: number
 	}
 >
 
-/** @public */
+/**
+ * Runtime validator for TLVideoAsset records. This validator ensures that video asset
+ * data conforms to the expected structure and types, providing type safety at runtime.
+ * It validates dimensions, file metadata, and ensures URLs are properly formatted.
+ *
+ * @example
+ * ```ts
+ * import { videoAssetValidator } from '@tldraw/tlschema'
+ *
+ * // Validate a video asset object
+ * const validAsset = videoAssetValidator.validate({
+ *   id: 'asset:video123',
+ *   typeName: 'asset',
+ *   type: 'video',
+ *   props: {
+ *     w: 1920,
+ *     h: 1080,
+ *     name: 'video.mp4',
+ *     isAnimated: true,
+ *     mimeType: 'video/mp4',
+ *     src: 'https://example.com/video.mp4',
+ *     fileSize: 1024000
+ *   },
+ *   meta: {}
+ * })
+ * ```
+ *
+ * @public
+ */
 export const videoAssetValidator: T.Validator<TLVideoAsset> = createAssetValidator(
 	'video',
 	T.object({
@@ -42,9 +102,38 @@ const Versions = createMigrationIds('com.tldraw.asset.video', {
 	MakeFileSizeOptional: 5,
 } as const)
 
+/**
+ * Version identifiers for video asset migration sequences. These versions track
+ * the evolution of the video asset schema over time, enabling proper data migration
+ * when the asset structure changes.
+ *
+ * @example
+ * ```ts
+ * import { videoAssetVersions } from '@tldraw/tlschema'
+ *
+ * // Check the current version of a specific migration
+ * console.log(videoAssetVersions.AddFileSize) // 4
+ * ```
+ *
+ * @public
+ */
 export { Versions as videoAssetVersions }
 
-/** @public */
+/**
+ * Migration sequence for video assets that handles schema evolution over time.
+ * This sequence defines how video asset data should be transformed when upgrading
+ * or downgrading between different schema versions. Each migration step handles
+ * specific changes like adding properties, renaming fields, or changing data formats.
+ *
+ * The migrations handle:
+ * - Adding animation detection (isAnimated property)
+ * - Renaming width/height properties to w/h for consistency
+ * - Ensuring URL validity for src properties
+ * - Adding file size tracking
+ * - Making file size optional for backward compatibility
+ *
+ * @public
+ */
 export const videoAssetMigrations = createRecordMigrationSequence({
 	sequenceId: 'com.tldraw.asset.video',
 	recordType: 'asset',

package/src/bindings/TLArrowBinding.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { arrowBindingVersions } from './TLArrowBinding'
+
+describe('TLArrowBinding', () => {
+	describe('AddSnap migration', () => {
+		const { up, down } = getTestMigration(arrowBindingVersions.AddSnap)
+
+		it('should add snap property with default value "none"', () => {
+			const oldRecord = {
+				props: {
+					terminal: 'end',
+					normalizedAnchor: { x: 0.5, y: 0.5 },
+					isExact: true,
+					isPrecise: false,
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.snap).toBe('none')
+			expect(result.props.terminal).toBe('end')
+		})
+
+		it('should remove snap property on down migration', () => {
+			const newRecord = {
+				props: {
+					terminal: 'end',
+					normalizedAnchor: { x: 0.5, y: 0.5 },
+					isExact: true,
+					isPrecise: false,
+					snap: 'center',
+				},
+			}
+
+			const result = down(newRecord)
+			expect(result.props.snap).toBeUndefined()
+			expect(result.props.terminal).toBe('end')
+		})
+
+		it('should be reversible', () => {
+			const originalRecord = {
+				props: {
+					terminal: 'start',
+					normalizedAnchor: { x: 0.5, y: 0.5 },
+					isExact: true,
+					isPrecise: false,
+				},
+			}
+
+			const upResult = up(originalRecord)
+			const downResult = down(upResult)
+			expect(downResult.props).toEqual(originalRecord.props)
+		})
+	})
+})