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

package/src/shapes/TLEmbedShape.ts

@@ -245,17 +245,60 @@ const EMBED_DEFINITIONS = [
 	},
 ]
 
-/** @public */
+/**
+ * Properties for the embed shape, which displays embedded content from external services.
+ *
+ * @public
+ */
 export interface TLEmbedShapeProps {
+	/** Width of the embed shape in pixels */
 	w: number
+	/** Height of the embed shape in pixels */
 	h: number
+	/** URL of the content to embed (supports YouTube, Figma, CodePen, etc.) */
 	url: string
 }
 
-/** @public */
+/**
+ * An embed shape displays external content like YouTube videos, Figma designs, CodePen demos,
+ * and other embeddable content within the tldraw canvas.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const embedShape: TLEmbedShape = {
+ *   id: createShapeId(),
+ *   typeName: 'shape',
+ *   type: 'embed',
+ *   x: 200,
+ *   y: 200,
+ *   rotation: 0,
+ *   index: 'a1',
+ *   parentId: 'page:page1',
+ *   isLocked: false,
+ *   opacity: 1,
+ *   props: {
+ *     w: 560,
+ *     h: 315,
+ *     url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ */
 export type TLEmbedShape = TLBaseShape<'embed', TLEmbedShapeProps>
 
-/** @public */
+/**
+ * Validation schema for embed shape properties.
+ *
+ * @public
+ * @example
+ * ```ts
+ * // Validate embed shape properties
+ * const isValidUrl = embedShapeProps.url.isValid('https://youtube.com/watch?v=abc123')
+ * const isValidSize = embedShapeProps.w.isValid(560)
+ * ```
+ */
 export const embedShapeProps: RecordProps<TLEmbedShape> = {
 	w: T.nonZeroNumber,
 	h: T.nonZeroNumber,
@@ -269,9 +312,19 @@ const Versions = createShapePropsMigrationIds('embed', {
 	RemovePermissionOverrides: 4,
 })
 
+/**
+ * Version identifiers for embed shape migrations.
+ *
+ * @public
+ */
 export { Versions as embedShapeVersions }
 
-/** @public */
+/**
+ * Migration sequence for embed shape properties across different schema versions.
+ * Handles URL transformations and removal of deprecated properties.
+ *
+ * @public
+ */
 export const embedShapeMigrations = createShapePropsMigrationSequence({
 	sequence: [
 		{

package/src/shapes/TLFrameShape.test.ts

@@ -0,0 +1,71 @@
+import { T } from '@tldraw/validate'
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { frameShapeProps, frameShapeVersions } from './TLFrameShape'
+
+describe('TLFrameShape', () => {
+	describe('frameShapeProps validation', () => {
+		it('should validate valid frame props', () => {
+			const validProps = {
+				w: 400,
+				h: 300,
+				name: 'Test Frame',
+				color: 'blue' as const,
+			}
+
+			const validator = T.object(frameShapeProps)
+			expect(() => validator.validate(validProps)).not.toThrow()
+		})
+
+		it('should reject invalid dimensions', () => {
+			// Zero and negative values should be rejected
+			expect(() => frameShapeProps.w.validate(0)).toThrow()
+			expect(() => frameShapeProps.h.validate(-1)).toThrow()
+		})
+
+		it('should reject invalid colors', () => {
+			// Invalid color values
+			expect(() => frameShapeProps.color.validate('invalid-color')).toThrow()
+			expect(() => frameShapeProps.color.validate('')).toThrow()
+		})
+	})
+
+	describe('AddColorProp migration', () => {
+		const { up, down } = getTestMigration(frameShapeVersions.AddColorProp)
+
+		it('should add color property with default value "black"', () => {
+			const oldRecord = {
+				id: 'shape:frame1',
+				props: {
+					w: 400,
+					h: 300,
+					name: 'Test Frame',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.color).toBe('black')
+			expect(result.props.w).toBe(400)
+			expect(result.props.h).toBe(300)
+			expect(result.props.name).toBe('Test Frame')
+		})
+
+		it('should remove color property on down migration', () => {
+			const newRecord = {
+				id: 'shape:frame1',
+				props: {
+					w: 400,
+					h: 300,
+					name: 'Test Frame',
+					color: 'blue',
+				},
+			}
+
+			const result = down(newRecord)
+			expect(result.props.color).toBeUndefined()
+			expect(result.props.w).toBe(400)
+			expect(result.props.h).toBe(300)
+			expect(result.props.name).toBe('Test Frame')
+		})
+	})
+})

package/src/shapes/TLFrameShape.ts

@@ -4,18 +4,63 @@ import { RecordProps } from '../recordsWithProps'
 import { DefaultColorStyle, TLDefaultColorStyle } from '../styles/TLColorStyle'
 import { TLBaseShape } from './TLBaseShape'
 
-/** @public */
+/**
+ * Properties for the frame shape, which provides a container for organizing other shapes.
+ *
+ * @public
+ */
 export interface TLFrameShapeProps {
+	/** Width of the frame in pixels */
 	w: number
+	/** Height of the frame in pixels */
 	h: number
+	/** Display name for the frame (shown in UI) */
 	name: string
+	/** Color style for the frame border and label */
 	color: TLDefaultColorStyle
 }
 
-/** @public */
+/**
+ * A frame shape provides a container for organizing and grouping other shapes.
+ * Frames can be used to create sections, organize content, or define specific areas.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const frameShape: TLFrameShape = {
+ *   id: createShapeId(),
+ *   typeName: 'shape',
+ *   type: 'frame',
+ *   x: 0,
+ *   y: 0,
+ *   rotation: 0,
+ *   index: 'a1',
+ *   parentId: 'page:page1',
+ *   isLocked: false,
+ *   opacity: 1,
+ *   props: {
+ *     w: 400,
+ *     h: 300,
+ *     name: 'Header Section',
+ *     color: 'blue'
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ */
 export type TLFrameShape = TLBaseShape<'frame', TLFrameShapeProps>
 
-/** @public */
+/**
+ * Validation schema for frame shape properties.
+ *
+ * @public
+ * @example
+ * ```ts
+ * // Validate frame properties
+ * const isValidName = frameShapeProps.name.isValid('My Frame')
+ * const isValidColor = frameShapeProps.color.isValid('red')
+ * ```
+ */
 export const frameShapeProps: RecordProps<TLFrameShape> = {
 	w: T.nonZeroNumber,
 	h: T.nonZeroNumber,
@@ -31,9 +76,19 @@ const Versions = createShapePropsMigrationIds('frame', {
 	AddColorProp: 1,
 })
 
+/**
+ * Version identifiers for frame shape migrations.
+ *
+ * @public
+ */
 export { Versions as frameShapeVersions }
 
-/** @public */
+/**
+ * Migration sequence for frame shape properties across different schema versions.
+ * Handles adding color properties to existing frame shapes.
+ *
+ * @public
+ */
 export const frameShapeMigrations = createShapePropsMigrationSequence({
 	sequence: [
 		{

package/src/shapes/TLGeoShape.test.ts

@@ -0,0 +1,247 @@
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { toRichText } from '../misc/TLRichText'
+import { GeoShapeGeoStyle, geoShapeProps, geoShapeVersions } from './TLGeoShape'
+
+describe('TLGeoShape', () => {
+	describe('GeoShapeGeoStyle', () => {
+		it('should validate all geometric shape types', () => {
+			const validGeoTypes = [
+				'cloud',
+				'rectangle',
+				'ellipse',
+				'triangle',
+				'diamond',
+				'pentagon',
+				'hexagon',
+				'octagon',
+				'star',
+				'rhombus',
+				'rhombus-2',
+				'oval',
+				'trapezoid',
+				'arrow-right',
+				'arrow-left',
+				'arrow-up',
+				'arrow-down',
+				'x-box',
+				'check-box',
+				'heart',
+			]
+
+			validGeoTypes.forEach((geoType) => {
+				expect(() => GeoShapeGeoStyle.validate(geoType)).not.toThrow()
+			})
+		})
+
+		it('should reject invalid geometric shape types', () => {
+			const invalidGeoTypes = ['square', 'circle', 'invalid-shape', null, undefined]
+
+			invalidGeoTypes.forEach((geoType) => {
+				expect(() => GeoShapeGeoStyle.validate(geoType)).toThrow()
+			})
+		})
+	})
+
+	describe('geoShapeProps validation schema', () => {
+		it('should validate numeric constraints', () => {
+			// Test nonZeroNumber validation for w, h, scale
+			expect(() => geoShapeProps.w.validate(100)).not.toThrow()
+			expect(() => geoShapeProps.h.validate(50)).not.toThrow()
+			expect(() => geoShapeProps.scale.validate(1.5)).not.toThrow()
+
+			expect(() => geoShapeProps.w.validate(0)).toThrow()
+			expect(() => geoShapeProps.h.validate(0)).toThrow()
+			expect(() => geoShapeProps.scale.validate(0)).toThrow()
+
+			// Test positiveNumber validation for growY
+			expect(() => geoShapeProps.growY.validate(0)).not.toThrow()
+			expect(() => geoShapeProps.growY.validate(10)).not.toThrow()
+			expect(() => geoShapeProps.growY.validate(-1)).toThrow()
+		})
+
+		it('should validate rich text property', () => {
+			expect(() => geoShapeProps.richText.validate(toRichText('test'))).not.toThrow()
+			expect(() => geoShapeProps.richText.validate('plain string')).toThrow()
+		})
+	})
+
+	describe('geoShapeMigrations - AddUrlProp migration', () => {
+		const { up } = getTestMigration(geoShapeVersions.AddUrlProp)
+
+		it('should add url property with empty string default', () => {
+			const oldRecord = {
+				props: {
+					geo: 'rectangle',
+					w: 100,
+					h: 80,
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.url).toBe('')
+		})
+	})
+
+	describe('geoShapeMigrations - AddLabelColor migration', () => {
+		const { up } = getTestMigration(geoShapeVersions.AddLabelColor)
+
+		it('should add labelColor property with default value "black"', () => {
+			const oldRecord = {
+				props: {
+					geo: 'triangle',
+					color: 'blue',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.labelColor).toBe('black')
+		})
+	})
+
+	describe('geoShapeMigrations - RemoveJustify migration', () => {
+		const { up } = getTestMigration(geoShapeVersions.RemoveJustify)
+
+		it('should convert justify alignment to start', () => {
+			const oldRecord = {
+				props: {
+					align: 'justify',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.align).toBe('start')
+		})
+
+		it('should preserve non-justify alignments', () => {
+			const oldRecord = {
+				props: {
+					align: 'middle',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.align).toBe('middle')
+		})
+	})
+
+	describe('geoShapeMigrations - AddVerticalAlign migration', () => {
+		const { up } = getTestMigration(geoShapeVersions.AddVerticalAlign)
+
+		it('should add verticalAlign property with default value "middle"', () => {
+			const oldRecord = {
+				props: {
+					geo: 'rectangle',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.verticalAlign).toBe('middle')
+		})
+	})
+
+	describe('geoShapeMigrations - MigrateLegacyAlign migration', () => {
+		const { up } = getTestMigration(geoShapeVersions.MigrateLegacyAlign)
+
+		it('should convert alignment values to legacy versions', () => {
+			const testCases = [
+				{ input: 'start', expected: 'start-legacy' },
+				{ input: 'end', expected: 'end-legacy' },
+				{ input: 'middle', expected: 'middle-legacy' },
+				{ input: 'unknown-align', expected: 'middle-legacy' },
+			]
+
+			testCases.forEach(({ input, expected }) => {
+				const oldRecord = {
+					props: {
+						align: input,
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.align).toBe(expected)
+			})
+		})
+	})
+
+	describe('geoShapeMigrations - MakeUrlsValid migration', () => {
+		const { up } = getTestMigration(geoShapeVersions.MakeUrlsValid)
+
+		it('should clear invalid URLs', () => {
+			const oldRecord = {
+				props: {
+					url: 'invalid-url',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.url).toBe('')
+		})
+
+		it('should preserve valid URLs', () => {
+			const oldRecord = {
+				props: {
+					url: 'https://example.com',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.url).toBe('https://example.com')
+		})
+	})
+
+	describe('geoShapeMigrations - AddScale migration', () => {
+		const { up, down } = getTestMigration(geoShapeVersions.AddScale)
+
+		it('should add scale property with default value 1', () => {
+			const oldRecord = {
+				props: {
+					geo: 'rectangle',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.scale).toBe(1)
+		})
+
+		it('should remove scale property on down migration', () => {
+			const newRecord = {
+				props: {
+					geo: 'rectangle',
+					scale: 1.5,
+				},
+			}
+
+			const result = down(newRecord)
+			expect(result.props.scale).toBeUndefined()
+		})
+	})
+
+	describe('geoShapeMigrations - AddRichText migration', () => {
+		const { up } = getTestMigration(geoShapeVersions.AddRichText)
+
+		it('should convert text property to richText', () => {
+			const oldRecord = {
+				props: {
+					text: 'Simple text content',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.richText).toBeDefined()
+			expect(result.props.text).toBeUndefined()
+		})
+
+		it('should handle empty text', () => {
+			const oldRecord = {
+				props: {
+					text: '',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.richText).toBeDefined()
+			expect(result.props.text).toBeUndefined()
+		})
+	})
+})

package/src/shapes/TLGeoShape.ts

@@ -22,7 +22,21 @@ import {
 } from '../styles/TLVerticalAlignStyle'
 import { TLBaseShape } from './TLBaseShape'
 
-/** @public */
+/**
+ * Style property defining the geometric shape type for geo shapes.
+ * Provides a variety of built-in geometric forms including basic shapes,
+ * polygons, arrows, and special shapes.
+ *
+ * @public
+ * @example
+ * ```ts
+ * // Use in shape props
+ * const props = {
+ *   geo: 'rectangle', // or 'ellipse', 'triangle', etc.
+ *   // other properties...
+ * }
+ * ```
+ */
 export const GeoShapeGeoStyle = StyleProp.defineEnum('tldraw:geo', {
 	defaultValue: 'rectangle',
 	values: [
@@ -49,34 +63,105 @@ export const GeoShapeGeoStyle = StyleProp.defineEnum('tldraw:geo', {
 	],
 })
 
-/** @public */
+/**
+ * Type representing valid geometric shape styles for geo shapes.
+ *
+ * @public
+ */
 export type TLGeoShapeGeoStyle = T.TypeOf<typeof GeoShapeGeoStyle>
 
-/** @public */
+/**
+ * Properties for the geo shape, which renders various geometric forms with styling and text.
+ *
+ * @public
+ */
 export interface TLGeoShapeProps {
+	/** Geometric shape type (rectangle, ellipse, triangle, etc.) */
 	geo: TLGeoShapeGeoStyle
+	/** Dash pattern style for the shape outline */
 	dash: TLDefaultDashStyle
+	/** URL link associated with the shape */
 	url: string
+	/** Width of the shape in pixels */
 	w: number
+	/** Height of the shape in pixels */
 	h: number
+	/** Additional vertical growth for text content */
 	growY: number
+	/** Scale factor applied to the shape */
 	scale: number
 
-	// Text properties
+	/** Color style for text label */
 	labelColor: TLDefaultColorStyle
+	/** Color style for the shape outline */
 	color: TLDefaultColorStyle
+	/** Fill style for the shape interior */
 	fill: TLDefaultFillStyle
+	/** Size/thickness style for outline and text */
 	size: TLDefaultSizeStyle
+	/** Font style for text content */
 	font: TLDefaultFontStyle
+	/** Horizontal alignment for text content */
 	align: TLDefaultHorizontalAlignStyle
+	/** Vertical alignment for text content */
 	verticalAlign: TLDefaultVerticalAlignStyle
+	/** Rich text content displayed within the shape */
 	richText: TLRichText
 }
 
-/** @public */
+/**
+ * A geo shape represents geometric forms like rectangles, ellipses, triangles, and other
+ * predefined shapes. Geo shapes support styling, text content, and can act as containers.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const geoShape: TLGeoShape = {
+ *   id: createShapeId(),
+ *   typeName: 'shape',
+ *   type: 'geo',
+ *   x: 100,
+ *   y: 100,
+ *   rotation: 0,
+ *   index: 'a1',
+ *   parentId: 'page:page1',
+ *   isLocked: false,
+ *   opacity: 1,
+ *   props: {
+ *     geo: 'rectangle',
+ *     w: 200,
+ *     h: 100,
+ *     color: 'black',
+ *     fill: 'solid',
+ *     dash: 'solid',
+ *     size: 'm',
+ *     font: 'draw',
+ *     align: 'middle',
+ *     verticalAlign: 'middle',
+ *     richText: toRichText('Hello World'),
+ *     labelColor: 'black',
+ *     url: '',
+ *     growY: 0,
+ *     scale: 1
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ */
 export type TLGeoShape = TLBaseShape<'geo', TLGeoShapeProps>
 
-/** @public */
+/**
+ * Validation schema for geo shape properties.
+ *
+ * @public
+ * @example
+ * ```ts
+ * // Validate geo shape properties
+ * const isValidGeo = geoShapeProps.geo.isValid('rectangle')
+ * const isValidSize = geoShapeProps.w.isValid(100)
+ * const isValidText = geoShapeProps.richText.isValid(toRichText('Hello'))
+ * ```
+ */
 export const geoShapeProps: RecordProps<TLGeoShape> = {
 	geo: GeoShapeGeoStyle,
 	dash: DefaultDashStyle,
@@ -110,9 +195,20 @@ const geoShapeVersions = createShapePropsMigrationIds('geo', {
 	AddRichText: 10,
 })
 
+/**
+ * Version identifiers for geo shape migrations.
+ *
+ * @public
+ */
 export { geoShapeVersions as geoShapeVersions }
 
-/** @public */
+/**
+ * Migration sequence for geo shape properties across different schema versions.
+ * Handles evolution of geo shapes including URL support, label colors, alignment changes,
+ * and the transition from plain text to rich text.
+ *
+ * @public
+ */
 export const geoShapeMigrations = createShapePropsMigrationSequence({
 	sequence: [
 		{

package/src/shapes/TLGroupShape.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+import { createShapeValidator } from './TLBaseShape'
+import { groupShapeMigrations, groupShapeProps } from './TLGroupShape'
+
+describe('TLGroupShape', () => {
+	describe('groupShapeProps', () => {
+		it('should be an empty object', () => {
+			expect(groupShapeProps).toEqual({})
+		})
+	})
+
+	describe('groupShapeMigrations', () => {
+		it('should have empty migration sequence', () => {
+			expect(groupShapeMigrations.sequence).toEqual([])
+		})
+	})
+
+	describe('group shape validation', () => {
+		const groupValidator = createShapeValidator('group', groupShapeProps)
+
+		it('should validate valid group shapes', () => {
+			const validGroup = {
+				id: 'shape:test',
+				typeName: 'shape',
+				type: 'group',
+				x: 0,
+				y: 0,
+				rotation: 0,
+				index: 'a1',
+				parentId: 'page:main',
+				isLocked: false,
+				opacity: 1,
+				props: {},
+				meta: {},
+			}
+
+			expect(() => groupValidator.validate(validGroup)).not.toThrow()
+		})
+
+		it('should reject shapes with non-empty props', () => {
+			const invalidGroup = {
+				id: 'shape:invalid',
+				typeName: 'shape',
+				type: 'group',
+				x: 0,
+				y: 0,
+				rotation: 0,
+				index: 'a1',
+				parentId: 'page:main',
+				isLocked: false,
+				opacity: 1,
+				props: { invalid: 'prop' },
+				meta: {},
+			}
+
+			expect(() => groupValidator.validate(invalidGroup)).toThrow()
+		})
+	})
+})