@tldraw/tlschema 4.2.2 → 4.2.3

package/src/shapes/TLBaseShape.test.ts

@@ -0,0 +1,142 @@
+import { T } from '@tldraw/validate'
+import { describe, expect, it } from 'vitest'
+import { createShapeValidator, parentIdValidator, shapeIdValidator } from './TLBaseShape'
+
+describe('TLBaseShape', () => {
+	describe('parentIdValidator', () => {
+		it('should accept valid page and shape parent IDs', () => {
+			expect(() => parentIdValidator.validate('page:main')).not.toThrow()
+			expect(() => parentIdValidator.validate('shape:frame1')).not.toThrow()
+			expect(parentIdValidator.validate('page:main')).toBe('page:main')
+		})
+
+		it('should reject invalid parent ID prefixes', () => {
+			expect(() => parentIdValidator.validate('invalid:123')).toThrow(
+				'Parent ID must start with "page:" or "shape:"'
+			)
+			expect(() => parentIdValidator.validate('asset:123')).toThrow(
+				'Parent ID must start with "page:" or "shape:"'
+			)
+			expect(() => parentIdValidator.validate('page-main')).toThrow(
+				'Parent ID must start with "page:" or "shape:"'
+			)
+		})
+	})
+
+	describe('shapeIdValidator', () => {
+		it('should accept valid shape IDs', () => {
+			expect(() => shapeIdValidator.validate('shape:abc123')).not.toThrow()
+			expect(shapeIdValidator.validate('shape:test')).toBe('shape:test')
+		})
+
+		it('should reject non-shape IDs', () => {
+			expect(() => shapeIdValidator.validate('page:123')).toThrow(
+				'shape ID must start with "shape:"'
+			)
+			expect(() => shapeIdValidator.validate('asset:123')).toThrow(
+				'shape ID must start with "shape:"'
+			)
+			expect(() => shapeIdValidator.validate('shape-abc123')).toThrow(
+				'shape ID must start with "shape:"'
+			)
+		})
+	})
+
+	describe('createShapeValidator', () => {
+		it('should create validator for shape with no custom props', () => {
+			const validator = createShapeValidator('simple')
+
+			const validShape = {
+				id: 'shape:simple123',
+				typeName: 'shape',
+				type: 'simple',
+				x: 100,
+				y: 200,
+				rotation: 0.5,
+				index: 'a1',
+				parentId: 'page:main',
+				isLocked: false,
+				opacity: 0.8,
+				props: {},
+				meta: {},
+			}
+
+			expect(() => validator.validate(validShape)).not.toThrow()
+		})
+
+		it('should create validator for shape with custom props', () => {
+			const validator = createShapeValidator('custom', {
+				width: T.number,
+				height: T.number,
+				color: T.string,
+			})
+
+			const validShape = {
+				id: 'shape:custom456',
+				typeName: 'shape',
+				type: 'custom',
+				x: 50,
+				y: 75,
+				rotation: 1.0,
+				index: 'a2',
+				parentId: 'shape:frame1',
+				isLocked: true,
+				opacity: 0.5,
+				props: {
+					width: 150,
+					height: 100,
+					color: 'blue',
+				},
+				meta: {},
+			}
+
+			expect(() => validator.validate(validShape)).not.toThrow()
+		})
+
+		it('should reject shapes with wrong type', () => {
+			const validator = createShapeValidator('test')
+
+			const invalidShape = {
+				id: 'shape:test',
+				typeName: 'shape',
+				type: 'wrong',
+				x: 0,
+				y: 0,
+				rotation: 0,
+				index: 'a1',
+				parentId: 'page:main',
+				isLocked: false,
+				opacity: 1,
+				props: {},
+				meta: {},
+			}
+
+			expect(() => validator.validate(invalidShape)).toThrow()
+		})
+
+		it('should reject shapes with invalid custom props', () => {
+			const validator = createShapeValidator('custom', {
+				width: T.number,
+				height: T.number,
+				color: T.string,
+			})
+
+			const invalidShape = {
+				id: 'shape:custom123',
+				typeName: 'shape',
+				type: 'custom',
+				x: 0,
+				y: 0,
+				rotation: 0,
+				index: 'a1',
+				parentId: 'page:main',
+				isLocked: false,
+				opacity: 1,
+				meta: {},
+				props: { width: '100' }, // Wrong type - should be number
+			}
+
+			expect(() => validator.validate(invalidShape)).toThrow()
+		})
+	})
+})

package/src/shapes/TLBaseShape.ts

@@ -1,3 +1,4 @@
+import { BaseRecord } from '@tldraw/store'
 import { IndexKey, JsonObject } from '@tldraw/utils'
 import { T } from '@tldraw/validate'
 import { TLOpacityType, opacityValidator } from '../misc/TLOpacity'
@@ -8,37 +9,18 @@ import { TLParentId, TLShapeId } from '../records/TLShape'
  * Base interface for all shapes in tldraw.
  *
  * This interface defines the common properties that all shapes share, regardless of their
- * specific type. Every default shape extends this base with additional type-specific properties.
- *
- * Custom shapes should be defined by augmenting the TLGlobalShapePropsMap type and getting the shape type from the TLShape type.
+ * specific type. Every shape extends this base with additional type-specific properties.
  *
  * @example
  * ```ts
- * // Define a default shape type
- * interface TLArrowShape extends TLBaseShape<'arrow', {
- *   kind: TLArrowShapeKind
- *   labelColor: TLDefaultColorStyle
- *   color: TLDefaultColorStyle
- *   fill: TLDefaultFillStyle
- *   dash: TLDefaultDashStyle
- *   size: TLDefaultSizeStyle
- *   arrowheadStart: TLArrowShapeArrowheadStyle
- *   arrowheadEnd: TLArrowShapeArrowheadStyle
- *   font: TLDefaultFontStyle
- *   start: VecModel
- *   end: VecModel
- *   bend: number
- *   richText: TLRichText
- *   labelPosition: number
- *   scale: number
- *   elbowMidPoint: number
- * }> {}
+ * // Define a custom shape type
+ * interface MyCustomShape extends TLBaseShape<'custom', { size: number; color: string }> {}
  *
  * // Create a shape instance
- * const arrowShape: TLArrowShape = {
+ * const myShape: MyCustomShape = {
  *   id: 'shape:abc123',
  *   typeName: 'shape',
- *   type: 'arrow',
+ *   type: 'custom',
  *   x: 100,
  *   y: 200,
  *   rotation: 0,
@@ -47,10 +29,8 @@ import { TLParentId, TLShapeId } from '../records/TLShape'
  *   isLocked: false,
  *   opacity: 1,
  *   props: {
- *     kind: 'arc',
- *     start: { x: 0, y: 0 },
- *     end: { x: 100, y: 100 },
- *     // ... other props
+ *     size: 50,
+ *     color: 'blue'
  *   },
  *   meta: {}
  * }
@@ -58,12 +38,8 @@ import { TLParentId, TLShapeId } from '../records/TLShape'
  *
  * @public
  */
-export interface TLBaseShape<Type extends string, Props extends object> {
-	// using real `extends BaseRecord<'shape', TLShapeId>` introduces a circularity in the types
-	// and for that reason those "base members" have to be declared manually here
-	readonly id: TLShapeId
-	readonly typeName: 'shape'
-
+export interface TLBaseShape<Type extends string, Props extends object>
+	extends BaseRecord<'shape', TLShapeId> {
 	type: Type
 	x: number
 	y: number

package/src/shapes/TLBookmarkShape.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { bookmarkShapeProps, bookmarkShapeVersions } from './TLBookmarkShape'
+
+describe('TLBookmarkShape', () => {
+	describe('bookmarkShapeProps validation', () => {
+		it('should validate width as nonZeroNumber', () => {
+			// Valid non-zero positive numbers
+			expect(() => bookmarkShapeProps.w.validate(0.1)).not.toThrow()
+			expect(() => bookmarkShapeProps.w.validate(100)).not.toThrow()
+
+			// Invalid: zero and negative
+			expect(() => bookmarkShapeProps.w.validate(0)).toThrow()
+			expect(() => bookmarkShapeProps.w.validate(-1)).toThrow()
+		})
+
+		it('should validate height as nonZeroNumber', () => {
+			// Valid non-zero positive numbers
+			expect(() => bookmarkShapeProps.h.validate(0.1)).not.toThrow()
+			expect(() => bookmarkShapeProps.h.validate(100)).not.toThrow()
+
+			// Invalid: zero and negative
+			expect(() => bookmarkShapeProps.h.validate(0)).toThrow()
+			expect(() => bookmarkShapeProps.h.validate(-1)).toThrow()
+		})
+
+		it('should validate assetId as nullable asset ID', () => {
+			// Valid asset IDs
+			expect(() => bookmarkShapeProps.assetId.validate(null)).not.toThrow()
+			expect(() => bookmarkShapeProps.assetId.validate('asset:bookmark123')).not.toThrow()
+
+			// Invalid asset IDs
+			expect(() => bookmarkShapeProps.assetId.validate('shape:notasset')).toThrow()
+			expect(() => bookmarkShapeProps.assetId.validate('bookmark123')).toThrow()
+			expect(() => bookmarkShapeProps.assetId.validate(undefined)).toThrow()
+		})
+
+		it('should validate url as linkUrl', () => {
+			// Valid URLs
+			expect(() => bookmarkShapeProps.url.validate('')).not.toThrow()
+			expect(() => bookmarkShapeProps.url.validate('https://example.com')).not.toThrow()
+
+			// Invalid URLs
+			expect(() => bookmarkShapeProps.url.validate('not-a-url')).toThrow()
+			expect(() => bookmarkShapeProps.url.validate('javascript:alert("xss")')).toThrow()
+		})
+	})
+
+	describe('NullAssetId migration', () => {
+		const { up, down } = getTestMigration(bookmarkShapeVersions.NullAssetId)
+
+		it('should add assetId as null when undefined', () => {
+			const oldRecord = {
+				props: {
+					w: 300,
+					h: 320,
+					url: 'https://example.com',
+					// assetId undefined
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.assetId).toBeNull()
+		})
+
+		it('should preserve existing assetId when present', () => {
+			const oldRecord = {
+				props: {
+					w: 300,
+					h: 320,
+					url: 'https://example.com',
+					assetId: 'asset:existing123',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.assetId).toBe('asset:existing123')
+		})
+
+		it('should throw on retired down migration', () => {
+			expect(() => down({})).toThrow()
+		})
+	})
+
+	describe('MakeUrlsValid migration', () => {
+		const { up, down } = getTestMigration(bookmarkShapeVersions.MakeUrlsValid)
+
+		it('should set invalid URLs to empty string', () => {
+			const oldRecord = {
+				props: {
+					w: 300,
+					h: 320,
+					assetId: null,
+					url: 'not-a-valid-url',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.url).toBe('')
+		})
+
+		it('should preserve valid URLs', () => {
+			const oldRecord = {
+				props: {
+					w: 300,
+					h: 320,
+					assetId: null,
+					url: 'https://example.com',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.url).toBe('https://example.com')
+		})
+
+		it('should be noop for down migration', () => {
+			const newRecord = { props: { url: 'https://example.com' } }
+			const result = down(newRecord)
+			expect(result).toEqual(newRecord)
+		})
+	})
+})

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

@@ -1,6 +1,5 @@
 import { T } from '@tldraw/validate'
-import { b64Vecs } from '../misc/b64Vecs'
-import { VecModel } from '../misc/geometry-types'
+import { VecModel, vecModelValidator } from '../misc/geometry-types'
 import { createShapePropsMigrationIds, createShapePropsMigrationSequence } from '../records/TLShape'
 import { RecordProps } from '../recordsWithProps'
 import { DefaultColorStyle, TLDefaultColorStyle } from '../styles/TLColorStyle'
@@ -17,18 +16,26 @@ import { TLBaseShape } from './TLBaseShape'
 export interface TLDrawShapeSegment {
 	/** Type of drawing segment - 'free' for freehand curves, 'straight' for line segments */
 	type: 'free' | 'straight'
-	/** Base64-encoded points (x, y, z triplets stored as Float16) */
-	points: string
+	/** Array of points defining the segment path with x, y coordinates and pressure (z) */
+	points: VecModel[]
 }
 
 /**
  * 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.string,
+	points: T.arrayOf(vecModelValidator),
 })
 
 /**
@@ -55,10 +62,6 @@ export interface TLDrawShapeProps {
 	isPen: boolean
 	/** Scale factor applied to the drawing */
 	scale: number
-	/** Horizontal scale factor for lazy resize */
-	scaleX: number
-	/** Vertical scale factor for lazy resize */
-	scaleY: number
 }
 
 /**
@@ -115,7 +118,6 @@ export type TLDrawShape = TLBaseShape<'draw', TLDrawShapeProps>
  * const isValid = drawShapeProps.color.isValid(props.color)
  * ```
  */
-/** @public */
 export const drawShapeProps: RecordProps<TLDrawShape> = {
 	color: DefaultColorStyle,
 	fill: DefaultFillStyle,
@@ -126,14 +128,11 @@ export const drawShapeProps: RecordProps<TLDrawShape> = {
 	isClosed: T.boolean,
 	isPen: T.boolean,
 	scale: T.nonZeroNumber,
-	scaleX: T.nonZeroFiniteNumber,
-	scaleY: T.nonZeroFiniteNumber,
 }
 
 const Versions = createShapePropsMigrationIds('draw', {
 	AddInPen: 1,
 	AddScale: 2,
-	Base64: 3,
 })
 
 /**
@@ -185,51 +184,5 @@ export const drawShapeMigrations = createShapePropsMigrationSequence({
 				delete props.scale
 			},
 		},
-		{
-			id: Versions.Base64,
-			up: (props) => {
-				props.segments = props.segments.map((segment: any) => {
-					return {
-						...segment,
-						// Only encode if points is an array (not already base64 string)
-						points:
-							typeof segment.points === 'string'
-								? segment.points
-								: b64Vecs.encodePoints(segment.points),
-					}
-				})
-				props.scaleX = props.scaleX ?? 1
-				props.scaleY = props.scaleY ?? 1
-			},
-			down: (props) => {
-				props.segments = props.segments.map((segment: any) => ({
-					...segment,
-					// Only decode if points is a string (not already VecModel[])
-					points: Array.isArray(segment.points)
-						? segment.points
-						: b64Vecs.decodePoints(segment.points),
-				}))
-				delete props.scaleX
-				delete props.scaleY
-			},
-		},
 	],
 })
-
-/**
- * Compress legacy draw shape segments by converting VecModel[] points to base64 format.
- * This function is useful for converting old draw shape data to the new compressed format.
- *
- * @public
- */
-export function compressLegacySegments(
-	segments: {
-		type: 'free' | 'straight'
-		points: VecModel[]
-	}[]
-): TLDrawShapeSegment[] {
-	return segments.map((segment) => ({
-		...segment,
-		points: b64Vecs.encodePoints(segment.points),
-	}))
-}