@tldraw/tlschema 4.1.0-next.b6dfe9bccde9 → 4.1.0-next.b9999db71010

package/src/shapes/TLBookmarkShape.ts

@@ -5,18 +5,62 @@ import { createShapePropsMigrationIds, createShapePropsMigrationSequence } from
 import { RecordProps } from '../recordsWithProps'
 import { TLBaseShape } from './TLBaseShape'
 
-/** @public */
+/**
+ * Properties for the bookmark shape, which displays website bookmarks as interactive cards.
+ *
+ * @public
+ */
 export interface TLBookmarkShapeProps {
+	/** Width of the bookmark shape in pixels */
 	w: number
+	/** Height of the bookmark shape in pixels */
 	h: number
+	/** Asset ID for the bookmark's preview image, or null if no image is available */
 	assetId: TLAssetId | null
+	/** The URL that this bookmark points to */
 	url: string
 }
 
-/** @public */
+/**
+ * A bookmark shape represents a website link with optional preview content.
+ * Bookmark shapes display as cards showing the page title, description, and preview image.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const bookmarkShape: TLBookmarkShape = {
+ *   id: createShapeId(),
+ *   typeName: 'shape',
+ *   type: 'bookmark',
+ *   x: 100,
+ *   y: 100,
+ *   rotation: 0,
+ *   index: 'a1',
+ *   parentId: 'page:page1',
+ *   isLocked: false,
+ *   opacity: 1,
+ *   props: {
+ *     w: 300,
+ *     h: 320,
+ *     assetId: 'asset:bookmark123',
+ *     url: 'https://www.example.com'
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ */
 export type TLBookmarkShape = TLBaseShape<'bookmark', TLBookmarkShapeProps>
 
-/** @public */
+/**
+ * Validation schema for bookmark shape properties.
+ *
+ * @public
+ * @example
+ * ```ts
+ * // Validates bookmark shape properties
+ * const isValid = bookmarkShapeProps.url.isValid('https://example.com')
+ * ```
+ */
 export const bookmarkShapeProps: RecordProps<TLBookmarkShape> = {
 	w: T.nonZeroNumber,
 	h: T.nonZeroNumber,
@@ -29,9 +73,19 @@ const Versions = createShapePropsMigrationIds('bookmark', {
 	MakeUrlsValid: 2,
 })
 
+/**
+ * Version identifiers for bookmark shape migrations.
+ *
+ * @public
+ */
 export { Versions as bookmarkShapeVersions }
 
-/** @public */
+/**
+ * Migration sequence for bookmark shape properties across different schema versions.
+ * Handles backwards compatibility when bookmark shape structure changes.
+ *
+ * @public
+ */
 export const bookmarkShapeMigrations = createShapePropsMigrationSequence({
 	sequence: [
 		{

package/src/shapes/TLDrawShape.test.ts

@@ -0,0 +1,177 @@
+import { T } from '@tldraw/validate'
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { VecModel } from '../misc/geometry-types'
+import { DefaultColorStyle } from '../styles/TLColorStyle'
+import { DefaultDashStyle } from '../styles/TLDashStyle'
+import { DefaultFillStyle } from '../styles/TLFillStyle'
+import { DefaultSizeStyle } from '../styles/TLSizeStyle'
+import { DrawShapeSegment, drawShapeProps, drawShapeVersions } from './TLDrawShape'
+
+describe('TLDrawShape', () => {
+	describe('DrawShapeSegment validator', () => {
+		it('should validate valid segment structures', () => {
+			const validSegments = [
+				{ type: 'free', points: [{ x: 0, y: 0 }] },
+				{ type: 'straight', points: [{ x: 0, y: 0, z: 0.5 }] },
+				{ type: 'free', points: [] },
+			]
+
+			validSegments.forEach((segment) => {
+				expect(() => DrawShapeSegment.validate(segment)).not.toThrow()
+			})
+		})
+
+		it('should reject invalid segment types and points', () => {
+			const invalidSegments = [
+				{ type: 'invalid', points: [{ x: 0, y: 0 }] },
+				{ type: 'free', points: [{ x: 'invalid', y: 0 }] },
+				{ type: 'free', points: 'not-array' },
+				{}, // Missing required fields
+			]
+
+			invalidSegments.forEach((segment) => {
+				expect(() => DrawShapeSegment.validate(segment)).toThrow()
+			})
+		})
+	})
+
+	describe('drawShapeProps validation schema', () => {
+		it('should validate complete valid props object', () => {
+			const fullValidator = T.object(drawShapeProps)
+
+			const validProps = {
+				color: 'red' as const,
+				fill: 'solid' as const,
+				dash: 'dashed' as const,
+				size: 'l' as const,
+				segments: [{ type: 'free' as const, points: [{ x: 0, y: 0, z: 0.5 }] as VecModel[] }],
+				isComplete: true,
+				isClosed: true,
+				isPen: true,
+				scale: 1.5,
+			}
+
+			expect(() => fullValidator.validate(validProps)).not.toThrow()
+		})
+
+		it('should reject invalid property values', () => {
+			// Test key invalid cases that matter for business logic
+			expect(() => drawShapeProps.scale.validate(0)).toThrow() // zero scale invalid
+			expect(() => drawShapeProps.scale.validate(-1)).toThrow() // negative scale invalid
+			expect(() => drawShapeProps.segments.validate('not-array')).toThrow()
+			expect(() => drawShapeProps.segments.validate([{ type: 'invalid' }])).toThrow()
+		})
+
+		it('should use correct default style validators', () => {
+			expect(drawShapeProps.color).toBe(DefaultColorStyle)
+			expect(drawShapeProps.fill).toBe(DefaultFillStyle)
+			expect(drawShapeProps.dash).toBe(DefaultDashStyle)
+			expect(drawShapeProps.size).toBe(DefaultSizeStyle)
+		})
+	})
+
+	describe('AddInPen migration', () => {
+		const { up } = getTestMigration(drawShapeVersions.AddInPen)
+
+		it('should detect pen from non-standard pressure values', () => {
+			const recordWithPen = {
+				props: {
+					segments: [
+						{
+							type: 'free',
+							points: [
+								{ x: 0, y: 0, z: 0.3 }, // Non-standard pressure
+								{ x: 10, y: 10, z: 0.7 }, // Non-standard pressure
+							],
+						},
+					],
+				},
+			}
+
+			const result = up(recordWithPen)
+			expect(result.props.isPen).toBe(true)
+		})
+
+		it('should not detect pen from standard pressure values', () => {
+			const recordWithoutPen = {
+				props: {
+					segments: [
+						{
+							type: 'free',
+							points: [
+								{ x: 0, y: 0, z: 0 }, // Standard mouse pressure
+								{ x: 10, y: 10, z: 0.5 }, // Standard touch pressure
+							],
+						},
+					],
+				},
+			}
+
+			const result = up(recordWithoutPen)
+			expect(result.props.isPen).toBe(false)
+		})
+
+		it('should handle empty segments', () => {
+			const recordEmpty = {
+				props: {
+					segments: [{ type: 'free', points: [] }],
+				},
+			}
+
+			const result = up(recordEmpty)
+			expect(result.props.isPen).toBe(false)
+		})
+
+		it('should require both points to have non-standard pressure', () => {
+			const recordMixed = {
+				props: {
+					segments: [
+						{
+							type: 'free',
+							points: [
+								{ x: 0, y: 0, z: 0.3 }, // Non-standard
+								{ x: 10, y: 10, z: 0.5 }, // Standard
+							],
+						},
+					],
+				},
+			}
+
+			const result = up(recordMixed)
+			expect(result.props.isPen).toBe(false)
+		})
+	})
+
+	describe('AddScale migration', () => {
+		const { up, down } = getTestMigration(drawShapeVersions.AddScale)
+
+		it('should add scale property with default value 1', () => {
+			const oldRecord = {
+				props: {
+					color: 'blue',
+					segments: [{ type: 'free', points: [{ x: 0, y: 0 }] }],
+					isPen: false,
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.scale).toBe(1)
+		})
+
+		it('should remove scale property on down migration', () => {
+			const newRecord = {
+				props: {
+					color: 'blue',
+					segments: [{ type: 'free', points: [{ x: 0, y: 0 }] }],
+					isPen: false,
+					scale: 1.5,
+				},
+			}
+
+			const result = down(newRecord)
+			expect(result.props.scale).toBeUndefined()
+			expect(result.props.color).toBe('blue') // Other props preserved
+		})
+	})
+})

package/src/shapes/TLDrawShape.ts

@@ -8,35 +8,116 @@ import { DefaultFillStyle, TLDefaultFillStyle } from '../styles/TLFillStyle'
 import { DefaultSizeStyle, TLDefaultSizeStyle } from '../styles/TLSizeStyle'
 import { TLBaseShape } from './TLBaseShape'
 
-/** @public */
+/**
+ * A segment of a draw shape representing either freehand drawing or straight line segments.
+ *
+ * @public
+ */
 export interface TLDrawShapeSegment {
+	/** Type of drawing segment - 'free' for freehand curves, 'straight' for line segments */
 	type: 'free' | 'straight'
+	/** Array of points defining the segment path with x, y coordinates and pressure (z) */
 	points: VecModel[]
 }
 
-/** @public */
+/**
+ * Validator for draw shape segments ensuring proper structure and data types.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const segment: TLDrawShapeSegment = {
+ *   type: 'free',
+ *   points: [{ x: 0, y: 0, z: 0.5 }, { x: 10, y: 10, z: 0.7 }]
+ * }
+ * const isValid = DrawShapeSegment.isValid(segment)
+ * ```
+ */
 export const DrawShapeSegment: T.ObjectValidator<TLDrawShapeSegment> = T.object({
 	type: T.literalEnum('free', 'straight'),
 	points: T.arrayOf(vecModelValidator),
 })
 
-/** @public */
+/**
+ * Properties for the draw shape, which represents freehand drawing and sketching.
+ *
+ * @public
+ */
 export interface TLDrawShapeProps {
+	/** Color style for the drawing stroke */
 	color: TLDefaultColorStyle
+	/** Fill style for closed drawing shapes */
 	fill: TLDefaultFillStyle
+	/** Dash pattern style for the stroke */
 	dash: TLDefaultDashStyle
+	/** Size/thickness of the drawing stroke */
 	size: TLDefaultSizeStyle
+	/** Array of segments that make up the complete drawing path */
 	segments: TLDrawShapeSegment[]
+	/** Whether the drawing is complete (user finished drawing) */
 	isComplete: boolean
+	/** Whether the drawing path forms a closed shape */
 	isClosed: boolean
+	/** Whether this drawing was created with a pen/stylus device */
 	isPen: boolean
+	/** Scale factor applied to the drawing */
 	scale: number
 }
 
-/** @public */
+/**
+ * A draw shape represents freehand drawing, sketching, and pen input on the canvas.
+ * Draw shapes are composed of segments that can be either smooth curves or straight lines.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const drawShape: TLDrawShape = {
+ *   id: createShapeId(),
+ *   typeName: 'shape',
+ *   type: 'draw',
+ *   x: 50,
+ *   y: 50,
+ *   rotation: 0,
+ *   index: 'a1',
+ *   parentId: 'page:page1',
+ *   isLocked: false,
+ *   opacity: 1,
+ *   props: {
+ *     color: 'black',
+ *     fill: 'none',
+ *     dash: 'solid',
+ *     size: 'm',
+ *     segments: [{
+ *       type: 'free',
+ *       points: [{ x: 0, y: 0, z: 0.5 }, { x: 20, y: 15, z: 0.6 }]
+ *     }],
+ *     isComplete: true,
+ *     isClosed: false,
+ *     isPen: false,
+ *     scale: 1
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ */
 export type TLDrawShape = TLBaseShape<'draw', TLDrawShapeProps>
 
-/** @public */
+/**
+ * Validation schema for draw shape properties.
+ *
+ * @public
+ * @example
+ * ```ts
+ * // Validate draw shape properties
+ * const props = {
+ *   color: 'red',
+ *   fill: 'solid',
+ *   segments: [{ type: 'free', points: [] }],
+ *   isComplete: true
+ * }
+ * const isValid = drawShapeProps.color.isValid(props.color)
+ * ```
+ */
 export const drawShapeProps: RecordProps<TLDrawShape> = {
 	color: DefaultColorStyle,
 	fill: DefaultFillStyle,
@@ -54,9 +135,19 @@ const Versions = createShapePropsMigrationIds('draw', {
 	AddScale: 2,
 })
 
+/**
+ * Version identifiers for draw shape migrations.
+ *
+ * @public
+ */
 export { Versions as drawShapeVersions }
 
-/** @public */
+/**
+ * Migration sequence for draw shape properties across different schema versions.
+ * Handles adding pen detection and scale properties to existing draw shapes.
+ *
+ * @public
+ */
 export const drawShapeMigrations = createShapePropsMigrationSequence({
 	sequence: [
 		{

package/src/shapes/TLEmbedShape.test.ts

@@ -0,0 +1,286 @@
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { embedShapeProps, embedShapeVersions } from './TLEmbedShape'
+
+describe('TLEmbedShape', () => {
+	describe('embedShapeProps validation schema', () => {
+		it('should validate width as nonZeroNumber', () => {
+			const validWidths = [0.1, 0.5, 1, 10, 100, 560, 1920, 1000.5, 9999.99]
+
+			validWidths.forEach((w) => {
+				expect(() => embedShapeProps.w.validate(w)).not.toThrow()
+			})
+
+			const invalidWidths = [0, -1, -10, -0.1, 'not-number', null, undefined, {}, [], true, false]
+
+			invalidWidths.forEach((w) => {
+				expect(() => embedShapeProps.w.validate(w)).toThrow()
+			})
+		})
+
+		it('should validate height as nonZeroNumber', () => {
+			const validHeights = [0.1, 0.5, 1, 10, 100, 315, 1080, 1000.5, 9999.99]
+
+			validHeights.forEach((h) => {
+				expect(() => embedShapeProps.h.validate(h)).not.toThrow()
+			})
+
+			const invalidHeights = [0, -1, -10, -0.1, 'not-number', null, undefined, {}, [], true, false]
+
+			invalidHeights.forEach((h) => {
+				expect(() => embedShapeProps.h.validate(h)).toThrow()
+			})
+		})
+
+		it('should validate url as string', () => {
+			const validUrls = [
+				'',
+				'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+				'https://codepen.io/team/codepen/pen/PNaGbb',
+				'https://codesandbox.io/s/new',
+				'https://vimeo.com/123456789',
+				'https://tldraw.com/r/room123',
+				'invalid-url-format', // Still valid as string
+				'javascript:alert("test")', // Still valid as string
+				'file:///local/file', // Still valid as string
+				'relative/path',
+				'text without protocol',
+			]
+
+			validUrls.forEach((url) => {
+				expect(() => embedShapeProps.url.validate(url)).not.toThrow()
+			})
+
+			const invalidUrls = [123, null, undefined, {}, [], true, false]
+
+			invalidUrls.forEach((url) => {
+				expect(() => embedShapeProps.url.validate(url)).toThrow()
+			})
+		})
+	})
+
+	describe('embedShapeMigrations - GenOriginalUrlInEmbed migration', () => {
+		const { up, down } = getTestMigration(embedShapeVersions.GenOriginalUrlInEmbed)
+
+		describe('GenOriginalUrlInEmbed up migration', () => {
+			it('should extract original URL from tldraw embed URLs', () => {
+				const tldrawUrls = [
+					'https://tldraw.com/r/room123',
+					'https://beta.tldraw.com/r/room456',
+					'http://localhost:3000/r/local-room',
+				]
+
+				tldrawUrls.forEach((url) => {
+					const oldRecord = {
+						id: 'shape:embed1',
+						props: {
+							w: 560,
+							h: 315,
+							url,
+						},
+					}
+
+					const result = up(oldRecord)
+					expect(result.props.url).toBe(url) // Should keep the URL as-is for tldraw
+					expect(result.props.tmpOldUrl).toBe(url)
+				})
+			})
+
+			it('should extract original URL from YouTube embed URLs', () => {
+				const testCases = [
+					{
+						embed: 'https://www.youtube.com/embed/dQw4w9WgXcQ',
+						expected: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+					},
+					{
+						embed: 'https://youtube.com/embed/abc123',
+						expected: 'https://www.youtube.com/watch?v=abc123',
+					},
+				]
+
+				testCases.forEach(({ embed, expected }) => {
+					const oldRecord = {
+						id: 'shape:embed1',
+						props: {
+							w: 560,
+							h: 315,
+							url: embed,
+						},
+					}
+
+					const result = up(oldRecord)
+					expect(result.props.url).toBe(expected)
+					expect(result.props.tmpOldUrl).toBe(embed)
+				})
+			})
+
+			it('should extract original URL from CodePen embed URLs', () => {
+				const oldRecord = {
+					id: 'shape:embed1',
+					props: {
+						w: 560,
+						h: 315,
+						url: 'https://codepen.io/user/embed/abcdef',
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.url).toBe('https://codepen.io/user/pen/abcdef')
+				expect(result.props.tmpOldUrl).toBe('https://codepen.io/user/embed/abcdef')
+			})
+
+			it('should handle Google Maps embed URLs (documents hostname matching limitation)', () => {
+				const oldRecord = {
+					id: 'shape:embed1',
+					props: {
+						w: 560,
+						h: 315,
+						url: 'https://www.google.com/maps/embed/v1/view?center=40.7128,-74.0060&zoom=10',
+					},
+				}
+
+				const result = up(oldRecord)
+				// NOTE: The wildcard 'google.*' doesn't match 'google.com' due to exact string matching
+				// The URL is valid and parseable, so it goes through normal flow but doesn't match any hostname
+				expect(result.props.url).toBe('') // originalUrl is undefined, so becomes empty string
+				expect(result.props.tmpOldUrl).toBe(
+					'https://www.google.com/maps/embed/v1/view?center=40.7128,-74.0060&zoom=10'
+				)
+			})
+
+			it('should extract original URL from Vimeo embed URLs', () => {
+				const oldRecord = {
+					id: 'shape:embed1',
+					props: {
+						w: 560,
+						h: 315,
+						url: 'https://player.vimeo.com/video/123456789',
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.url).toBe('https://vimeo.com/123456789')
+				expect(result.props.tmpOldUrl).toBe('https://player.vimeo.com/video/123456789')
+			})
+		})
+
+		describe('GenOriginalUrlInEmbed down migration', () => {
+			it('should be retired (no down migration)', () => {
+				expect(() => {
+					down({})
+				}).toThrow('Migration com.tldraw.shape.embed/1 does not have a down function')
+			})
+		})
+	})
+
+	describe('embedShapeMigrations - RemoveDoesResize migration', () => {
+		const { up, down } = getTestMigration(embedShapeVersions.RemoveDoesResize)
+
+		describe('RemoveDoesResize up migration', () => {
+			it('should remove doesResize property', () => {
+				const oldRecord = {
+					id: 'shape:embed1',
+					props: {
+						w: 560,
+						h: 315,
+						url: 'https://example.com',
+						doesResize: true,
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.doesResize).toBeUndefined()
+			})
+		})
+
+		describe('RemoveDoesResize down migration', () => {
+			it('should be retired (no down migration)', () => {
+				expect(() => {
+					down({})
+				}).toThrow('Migration com.tldraw.shape.embed/2 does not have a down function')
+			})
+		})
+	})
+
+	describe('embedShapeMigrations - RemoveTmpOldUrl migration', () => {
+		const { up, down } = getTestMigration(embedShapeVersions.RemoveTmpOldUrl)
+
+		describe('RemoveTmpOldUrl up migration', () => {
+			it('should remove tmpOldUrl property', () => {
+				const oldRecord = {
+					id: 'shape:embed1',
+					props: {
+						w: 560,
+						h: 315,
+						url: 'https://example.com',
+						tmpOldUrl: 'https://old-url.com',
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.tmpOldUrl).toBeUndefined()
+			})
+		})
+
+		describe('RemoveTmpOldUrl down migration', () => {
+			it('should be retired (no down migration)', () => {
+				expect(() => {
+					down({})
+				}).toThrow('Migration com.tldraw.shape.embed/3 does not have a down function')
+			})
+		})
+	})
+
+	describe('embedShapeMigrations - RemovePermissionOverrides migration', () => {
+		const { up, down } = getTestMigration(embedShapeVersions.RemovePermissionOverrides)
+
+		describe('RemovePermissionOverrides up migration', () => {
+			it('should remove overridePermissions property', () => {
+				const oldRecord = {
+					id: 'shape:embed1',
+					props: {
+						w: 560,
+						h: 315,
+						url: 'https://example.com',
+						overridePermissions: { allowScripts: true },
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.overridePermissions).toBeUndefined()
+			})
+		})
+
+		describe('RemovePermissionOverrides down migration', () => {
+			it('should be retired (no down migration)', () => {
+				expect(() => {
+					down({})
+				}).toThrow('Migration com.tldraw.shape.embed/4 does not have a down function')
+			})
+		})
+	})
+
+	describe('edge cases and error handling', () => {
+		it('should handle zero dimension validation correctly', () => {
+			// Zero should be invalid for width and height (nonZeroNumber)
+			expect(() => embedShapeProps.w.validate(0)).toThrow()
+			expect(() => embedShapeProps.h.validate(0)).toThrow()
+
+			// Negative numbers should also be invalid
+			expect(() => embedShapeProps.w.validate(-1)).toThrow()
+			expect(() => embedShapeProps.h.validate(-10.5)).toThrow()
+		})
+
+		it('should handle migration errors when props is null', () => {
+			const malformedRecord = {
+				id: 'shape:malformed',
+				props: null,
+			}
+
+			expect(() => {
+				const migration = getTestMigration(embedShapeVersions.GenOriginalUrlInEmbed)
+				migration.up(malformedRecord)
+			}).toThrow('Cannot set properties of null')
+		})
+	})
+})