@tldraw/tlschema 4.1.0-canary.9c36de6e611c → 4.1.0-canary.a152954244d2

package/src/shapes/TLNoteShape.ts

@@ -19,25 +19,105 @@ import {
 } from '../styles/TLVerticalAlignStyle'
 import { TLBaseShape } from './TLBaseShape'
 
-/** @public */
+/**
+ * Properties for a note shape. Note shapes represent sticky notes or text annotations
+ * with rich formatting capabilities and various styling options.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const noteProps: TLNoteShapeProps = {
+ *   color: 'yellow',
+ *   labelColor: 'black',
+ *   size: 'm',
+ *   font: 'draw',
+ *   fontSizeAdjustment: 0,
+ *   align: 'middle',
+ *   verticalAlign: 'middle',
+ *   growY: 0,
+ *   url: '',
+ *   richText: toRichText('Hello **world**!'),
+ *   scale: 1
+ * }
+ * ```
+ */
 export interface TLNoteShapeProps {
+	/** Background color style of the note */
 	color: TLDefaultColorStyle
+	/** Text color style for the note content */
 	labelColor: TLDefaultColorStyle
+	/** Size style determining the font size and note dimensions */
 	size: TLDefaultSizeStyle
+	/** Font family style for the note text */
 	font: TLDefaultFontStyle
+	/** Adjustment to the base font size (positive increases, negative decreases) */
 	fontSizeAdjustment: number
+	/** Horizontal alignment of text within the note */
 	align: TLDefaultHorizontalAlignStyle
+	/** Vertical alignment of text within the note */
 	verticalAlign: TLDefaultVerticalAlignStyle
+	/** Additional height growth for the note beyond its base size */
 	growY: number
+	/** Optional URL associated with the note for linking */
 	url: string
+	/** Rich text content with formatting like bold, italic, etc. */
 	richText: TLRichText
+	/** Scale factor applied to the note shape for display */
 	scale: number
 }
 
-/** @public */
+/**
+ * A note shape representing a sticky note or text annotation on the canvas.
+ * Note shapes support rich text formatting, various styling options, and can
+ * be used for annotations, reminders, or general text content.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const noteShape: TLNoteShape = {
+ *   id: 'shape:note1',
+ *   type: 'note',
+ *   x: 100,
+ *   y: 100,
+ *   rotation: 0,
+ *   index: 'a1',
+ *   parentId: 'page:main',
+ *   isLocked: false,
+ *   opacity: 1,
+ *   props: {
+ *     color: 'light-blue',
+ *     labelColor: 'black',
+ *     size: 's',
+ *     font: 'sans',
+ *     fontSizeAdjustment: 2,
+ *     align: 'start',
+ *     verticalAlign: 'start',
+ *     growY: 50,
+ *     url: 'https://example.com',
+ *     richText: toRichText('Important **note**!'),
+ *     scale: 1
+ *   },
+ *   meta: {},
+ *   typeName: 'shape'
+ * }
+ * ```
+ */
 export type TLNoteShape = TLBaseShape<'note', TLNoteShapeProps>
 
-/** @public */
+/**
+ * Validation schema for note shape properties. Defines the runtime validation rules
+ * for all properties of note shapes, ensuring data integrity and type safety.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { noteShapeProps } from '@tldraw/tlschema'
+ *
+ * // Used internally by the validation system
+ * const validator = T.object(noteShapeProps)
+ * const validatedProps = validator.validate(someNoteProps)
+ * ```
+ */
 export const noteShapeProps: RecordProps<TLNoteShape> = {
 	color: DefaultColorStyle,
 	labelColor: DefaultLabelColorStyle,
@@ -64,9 +144,22 @@ const Versions = createShapePropsMigrationIds('note', {
 	AddRichText: 9,
 })
 
+/**
+ * Version identifiers for note shape migrations. These version numbers track
+ * significant schema changes over time, enabling proper data migration between versions.
+ *
+ * @public
+ */
 export { Versions as noteShapeVersions }
 
-/** @public */
+/**
+ * Migration sequence for note shapes. Handles schema evolution over time by defining
+ * how to upgrade and downgrade note shape data between different versions. Includes
+ * migrations for URL properties, text alignment changes, vertical alignment addition,
+ * font size adjustments, scaling support, label color, and the transition from plain text to rich text.
+ *
+ * @public
+ */
 export const noteShapeMigrations = createShapePropsMigrationSequence({
 	sequence: [
 		{

package/src/shapes/TLTextShape.test.ts

@@ -0,0 +1,407 @@
+import { T } from '@tldraw/validate'
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { TLRichText, toRichText } from '../misc/TLRichText'
+import { DefaultColorStyle } from '../styles/TLColorStyle'
+import { DefaultFontStyle } from '../styles/TLFontStyle'
+import { DefaultSizeStyle } from '../styles/TLSizeStyle'
+import { DefaultTextAlignStyle } from '../styles/TLTextAlignStyle'
+import { textShapeMigrations, textShapeProps, textShapeVersions } from './TLTextShape'
+
+describe('TLTextShape', () => {
+	describe('textShapeProps validation schema', () => {
+		it('should validate using comprehensive object validator', () => {
+			const fullValidator = T.object(textShapeProps)
+
+			const validPropsObject = {
+				color: 'red' as const,
+				size: 's' as const,
+				font: 'mono' as const,
+				textAlign: 'end' as const,
+				w: 250,
+				richText: toRichText('Complete validation test') as TLRichText,
+				scale: 0.8,
+				autoSize: true,
+			}
+
+			expect(() => fullValidator.validate(validPropsObject)).not.toThrow()
+			const result = fullValidator.validate(validPropsObject)
+			expect(result).toEqual(validPropsObject)
+		})
+
+		it('should validate width as nonZeroNumber', () => {
+			// Valid non-zero positive numbers
+			const validWidths = [0.1, 1, 50, 100, 1000, 0.001]
+
+			validWidths.forEach((w) => {
+				expect(() => textShapeProps.w.validate(w)).not.toThrow()
+			})
+
+			// Invalid widths (zero, negative numbers, and non-numbers)
+			const invalidWidths = [0, -1, -0.1, 'not-number', null, undefined, {}, [], true, false]
+
+			invalidWidths.forEach((w) => {
+				expect(() => textShapeProps.w.validate(w)).toThrow()
+			})
+		})
+
+		it('should validate scale as nonZeroNumber', () => {
+			// Valid non-zero positive numbers
+			const validScales = [0.1, 0.5, 1, 1.5, 2, 10]
+
+			validScales.forEach((scale) => {
+				expect(() => textShapeProps.scale.validate(scale)).not.toThrow()
+			})
+
+			// Invalid scales (zero, negative numbers, and non-numbers)
+			const invalidScales = [0, -0.5, -1, -2, 'not-number', null, undefined, {}, [], true, false]
+
+			invalidScales.forEach((scale) => {
+				expect(() => textShapeProps.scale.validate(scale)).toThrow()
+			})
+		})
+
+		it('should use correct default style validators', () => {
+			// Verify that the props schema uses the expected style validators
+			expect(textShapeProps.color).toBe(DefaultColorStyle)
+			expect(textShapeProps.size).toBe(DefaultSizeStyle)
+			expect(textShapeProps.font).toBe(DefaultFontStyle)
+			expect(textShapeProps.textAlign).toBe(DefaultTextAlignStyle)
+		})
+
+		it('should use correct primitive validators', () => {
+			// Check that non-style properties use correct T validators
+			expect(textShapeProps.w).toBe(T.nonZeroNumber)
+			expect(textShapeProps.scale).toBe(T.nonZeroNumber)
+			expect(textShapeProps.autoSize).toBe(T.boolean)
+		})
+	})
+
+	describe('textShapeVersions', () => {
+		it('should have all expected migration versions', () => {
+			const expectedVersions: Array<keyof typeof textShapeVersions> = [
+				'RemoveJustify',
+				'AddTextAlign',
+				'AddRichText',
+			]
+
+			expectedVersions.forEach((version) => {
+				expect(textShapeVersions[version]).toBeDefined()
+				expect(typeof textShapeVersions[version]).toBe('string')
+			})
+		})
+	})
+
+	describe('textShapeMigrations', () => {
+		it('should have migrations for all version IDs', () => {
+			const migrationIds = textShapeMigrations.sequence
+				.filter((migration) => 'id' in migration)
+				.map((migration) => ('id' in migration ? migration.id : null))
+				.filter(Boolean)
+
+			const versionIds = Object.values(textShapeVersions)
+
+			versionIds.forEach((versionId) => {
+				expect(migrationIds).toContain(versionId)
+			})
+		})
+	})
+
+	describe('textShapeMigrations - RemoveJustify migration', () => {
+		const { up, down } = getTestMigration(textShapeVersions.RemoveJustify)
+
+		describe('RemoveJustify up migration', () => {
+			it('should convert justify alignment to start', () => {
+				const oldRecord = {
+					id: 'shape:text1',
+					props: {
+						color: 'black',
+						font: 'draw',
+						size: 'm',
+						align: 'justify',
+						w: 200,
+						text: 'Test text',
+						scale: 1,
+						autoSize: true,
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.align).toBe('start')
+				expect(result.props.color).toBe('black') // Preserve other props
+				expect(result.props.text).toBe('Test text')
+			})
+
+			it('should preserve non-justify alignments', () => {
+				const alignments = ['start', 'middle', 'end']
+
+				alignments.forEach((align) => {
+					const oldRecord = {
+						id: 'shape:text1',
+						props: {
+							color: 'red',
+							font: 'sans',
+							size: 'l',
+							align,
+							w: 300,
+							text: 'Aligned text',
+							scale: 1,
+							autoSize: false,
+						},
+					}
+
+					const result = up(oldRecord)
+					expect(result.props.align).toBe(align)
+				})
+			})
+
+			it('should preserve all other properties during migration', () => {
+				const oldRecord = {
+					id: 'shape:text1',
+					props: {
+						color: 'blue',
+						font: 'serif',
+						size: 'xl',
+						align: 'justify',
+						w: 400,
+						text: 'Justified text becomes start aligned',
+						scale: 1.5,
+						autoSize: false,
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.align).toBe('start')
+				expect(result.props.color).toBe('blue')
+				expect(result.props.font).toBe('serif')
+				expect(result.props.size).toBe('xl')
+				expect(result.props.w).toBe(400)
+				expect(result.props.text).toBe('Justified text becomes start aligned')
+				expect(result.props.scale).toBe(1.5)
+				expect(result.props.autoSize).toBe(false)
+			})
+		})
+
+		describe('RemoveJustify down migration', () => {
+			it('should be retired (no down migration)', () => {
+				expect(() => {
+					down({})
+				}).toThrow('Migration com.tldraw.shape.text/1 does not have a down function')
+			})
+		})
+	})
+
+	describe('textShapeMigrations - AddTextAlign migration', () => {
+		const { up, down } = getTestMigration(textShapeVersions.AddTextAlign)
+
+		describe('AddTextAlign up migration', () => {
+			it('should migrate align to textAlign', () => {
+				const oldRecord = {
+					id: 'shape:text1',
+					props: {
+						color: 'black',
+						font: 'draw',
+						size: 'm',
+						align: 'start',
+						w: 200,
+						text: 'Test text',
+						scale: 1,
+						autoSize: true,
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.textAlign).toBe('start')
+				expect(result.props.align).toBeUndefined()
+				expect(result.props.color).toBe('black') // Preserve other props
+			})
+
+			it('should handle all alignment values', () => {
+				const alignments = ['start', 'middle', 'end']
+
+				alignments.forEach((align) => {
+					const oldRecord = {
+						id: 'shape:text1',
+						props: {
+							color: 'red',
+							align,
+							w: 200,
+							text: 'Test',
+						},
+					}
+
+					const result = up(oldRecord)
+					expect(result.props.textAlign).toBe(align)
+					expect(result.props.align).toBeUndefined()
+				})
+			})
+
+			it('should preserve all other properties during migration', () => {
+				const oldRecord = {
+					id: 'shape:text1',
+					props: {
+						color: 'green',
+						font: 'mono',
+						size: 's',
+						align: 'middle',
+						w: 150,
+						text: 'Migration test',
+						scale: 2,
+						autoSize: false,
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.textAlign).toBe('middle')
+				expect(result.props.align).toBeUndefined()
+				expect(result.props.color).toBe('green')
+				expect(result.props.font).toBe('mono')
+				expect(result.props.size).toBe('s')
+				expect(result.props.w).toBe(150)
+				expect(result.props.text).toBe('Migration test')
+				expect(result.props.scale).toBe(2)
+				expect(result.props.autoSize).toBe(false)
+			})
+		})
+
+		describe('AddTextAlign down migration', () => {
+			it('should migrate textAlign back to align', () => {
+				const newRecord = {
+					id: 'shape:text1',
+					props: {
+						color: 'black',
+						font: 'draw',
+						size: 'm',
+						textAlign: 'start',
+						w: 200,
+						text: 'Test text',
+						scale: 1,
+						autoSize: true,
+					},
+				}
+
+				const result = down(newRecord)
+				expect(result.props.align).toBe('start')
+				expect(result.props.textAlign).toBeUndefined()
+				expect(result.props.color).toBe('black') // Preserve other props
+			})
+
+			it('should handle all textAlign values during down migration', () => {
+				const alignments = ['start', 'middle', 'end']
+
+				alignments.forEach((textAlign) => {
+					const newRecord = {
+						id: 'shape:text1',
+						props: {
+							color: 'blue',
+							textAlign,
+							w: 200,
+							text: 'Test',
+						},
+					}
+
+					const result = down(newRecord)
+					expect(result.props.align).toBe(textAlign)
+					expect(result.props.textAlign).toBeUndefined()
+				})
+			})
+		})
+	})
+
+	describe('textShapeMigrations - AddRichText migration', () => {
+		const { up } = getTestMigration(textShapeVersions.AddRichText)
+
+		describe('AddRichText up migration', () => {
+			it('should convert text property to richText', () => {
+				const oldRecord = {
+					id: 'shape:text1',
+					props: {
+						color: 'black',
+						font: 'draw',
+						size: 'm',
+						textAlign: 'start',
+						w: 200,
+						text: 'Simple text content',
+						scale: 1,
+						autoSize: true,
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.richText).toBeDefined()
+				expect(result.props.text).toBeUndefined()
+				expect(result.props.color).toBe('black') // Preserve other props
+			})
+
+			it('should handle empty text', () => {
+				const oldRecord = {
+					id: 'shape:text1',
+					props: {
+						color: 'red',
+						font: 'sans',
+						size: 'l',
+						textAlign: 'middle',
+						w: 300,
+						text: '',
+						scale: 1,
+						autoSize: false,
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.richText).toBeDefined()
+				expect(result.props.text).toBeUndefined()
+			})
+
+			it('should handle multi-line text', () => {
+				const oldRecord = {
+					id: 'shape:text1',
+					props: {
+						color: 'blue',
+						font: 'serif',
+						size: 'xl',
+						textAlign: 'end',
+						w: 400,
+						text: 'Line 1\nLine 2\nLine 3',
+						scale: 1.2,
+						autoSize: true,
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.richText).toBeDefined()
+				expect(result.props.text).toBeUndefined()
+			})
+
+			it('should preserve all other properties during migration', () => {
+				const oldRecord = {
+					id: 'shape:text1',
+					props: {
+						color: 'green',
+						font: 'mono',
+						size: 's',
+						textAlign: 'start',
+						w: 250,
+						text: 'Rich text migration test',
+						scale: 0.8,
+						autoSize: false,
+					},
+				}
+
+				const result = up(oldRecord)
+				expect(result.props.richText).toBeDefined()
+				expect(result.props.text).toBeUndefined()
+				expect(result.props.color).toBe('green')
+				expect(result.props.font).toBe('mono')
+				expect(result.props.size).toBe('s')
+				expect(result.props.textAlign).toBe('start')
+				expect(result.props.w).toBe(250)
+				expect(result.props.scale).toBe(0.8)
+				expect(result.props.autoSize).toBe(false)
+			})
+		})
+
+		// Note: The down migration is explicitly not defined (forced client update)
+		// so we don't test it
+	})
+})

package/src/shapes/TLTextShape.ts

@@ -8,7 +8,25 @@ import { DefaultSizeStyle, TLDefaultSizeStyle } from '../styles/TLSizeStyle'
 import { DefaultTextAlignStyle, TLDefaultTextAlignStyle } from '../styles/TLTextAlignStyle'
 import { TLBaseShape } from './TLBaseShape'
 
-/** @public */
+/**
+ * Configuration interface defining properties for text shapes in tldraw.
+ * Text shapes support rich formatting, styling, and automatic sizing.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const textProps: TLTextShapeProps = {
+ *   color: 'black',
+ *   size: 'm',
+ *   font: 'draw',
+ *   textAlign: 'start',
+ *   w: 200,
+ *   richText: toRichText('Hello **bold** text'),
+ *   scale: 1,
+ *   autoSize: true
+ * }
+ * ```
+ */
 export interface TLTextShapeProps {
 	color: TLDefaultColorStyle
 	size: TLDefaultSizeStyle
@@ -20,10 +38,57 @@ export interface TLTextShapeProps {
 	autoSize: boolean
 }
 
-/** @public */
+/**
+ * A text shape that can display formatted text content with various styling options.
+ * Text shapes support rich formatting, automatic sizing, and consistent styling through
+ * the tldraw style system.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const textShape: TLTextShape = {
+ *   id: 'shape:text123',
+ *   typeName: 'shape',
+ *   type: 'text',
+ *   x: 100,
+ *   y: 200,
+ *   rotation: 0,
+ *   index: 'a1',
+ *   parentId: 'page:main',
+ *   isLocked: false,
+ *   opacity: 1,
+ *   props: {
+ *     color: 'black',
+ *     size: 'm',
+ *     font: 'draw',
+ *     textAlign: 'start',
+ *     w: 200,
+ *     richText: toRichText('Sample text'),
+ *     scale: 1,
+ *     autoSize: false
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ */
 export type TLTextShape = TLBaseShape<'text', TLTextShapeProps>
 
-/** @public */
+/**
+ * Validation schema for text shape properties. This defines the runtime validation
+ * rules that ensure text shape data integrity when records are stored or transmitted.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { textShapeProps } from '@tldraw/tlschema'
+ *
+ * // Validate text shape properties
+ * const isValid = textShapeProps.richText.isValid(myRichText)
+ * if (isValid) {
+ *   // Properties are valid, safe to use
+ * }
+ * ```
+ */
 export const textShapeProps: RecordProps<TLTextShape> = {
 	color: DefaultColorStyle,
 	size: DefaultSizeStyle,
@@ -41,9 +106,34 @@ const Versions = createShapePropsMigrationIds('text', {
 	AddRichText: 3,
 })
 
+/**
+ * Version identifiers for text shape migrations. These constants track
+ * the evolution of the text shape schema over time.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { textShapeVersions } from '@tldraw/tlschema'
+ *
+ * // Check if shape data needs migration
+ * if (shapeVersion < textShapeVersions.AddRichText) {
+ *   // Apply rich text migration
+ * }
+ * ```
+ */
 export { Versions as textShapeVersions }
 
-/** @public */
+/**
+ * Migration sequence for text shape schema evolution. This handles transforming
+ * text shape data between different versions as the schema evolves over time.
+ *
+ * Key migrations include:
+ * - RemoveJustify: Replaced 'justify' alignment with 'start'
+ * - AddTextAlign: Migrated from 'align' to 'textAlign' property
+ * - AddRichText: Converted plain text to rich text format
+ *
+ * @public
+ */
 export const textShapeMigrations = createShapePropsMigrationSequence({
 	sequence: [
 		{