@tldraw/tlschema 4.1.0-canary.a5989c7a02c8 → 4.1.0-canary.ae12c0a5a37b

package/src/shapes/TLLineShape.test.ts

@@ -0,0 +1,269 @@
+import { IndexKey } from '@tldraw/utils'
+import { T } from '@tldraw/validate'
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import {
+	lineShapeMigrations,
+	lineShapeProps,
+	LineShapeSplineStyle,
+	lineShapeVersions,
+} from './TLLineShape'
+
+describe('TLLineShape', () => {
+	describe('LineShapeSplineStyle', () => {
+		it('should validate correct spline values', () => {
+			expect(() => LineShapeSplineStyle.validate('cubic')).not.toThrow()
+			expect(() => LineShapeSplineStyle.validate('line')).not.toThrow()
+		})
+
+		it('should reject invalid spline values', () => {
+			expect(() => LineShapeSplineStyle.validate('bezier')).toThrow()
+			expect(() => LineShapeSplineStyle.validate('')).toThrow()
+			expect(() => LineShapeSplineStyle.validate(null)).toThrow()
+		})
+	})
+
+	describe('lineShapeProps validation schema', () => {
+		it('should validate complete props object', () => {
+			const fullValidator = T.object(lineShapeProps)
+			const validProps = {
+				color: 'red' as const,
+				dash: 'dotted' as const,
+				size: 's' as const,
+				spline: 'line' as const,
+				points: {
+					start: { id: 'start', index: 'a1' as IndexKey, x: 0, y: 0 },
+					end: { id: 'end', index: 'a2' as IndexKey, x: 100, y: 50 },
+				},
+				scale: 1.5,
+			}
+
+			expect(() => fullValidator.validate(validProps)).not.toThrow()
+		})
+
+		it('should validate points dictionary structure', () => {
+			const validPoints = {
+				a: { id: 'a', index: 'a1' as IndexKey, x: 0, y: 0 },
+				b: { id: 'b', index: 'a2' as IndexKey, x: 100, y: 50 },
+			}
+			expect(() => lineShapeProps.points.validate(validPoints)).not.toThrow()
+
+			// Invalid point structures
+			expect(() => lineShapeProps.points.validate({ a: { id: 'a', x: 0, y: 0 } })).toThrow() // Missing index
+			expect(() => lineShapeProps.points.validate({ a: { index: 'a1', x: 0, y: 0 } })).toThrow() // Missing id
+		})
+
+		it('should validate scale as nonZeroNumber', () => {
+			expect(() => lineShapeProps.scale.validate(1.5)).not.toThrow()
+			expect(() => lineShapeProps.scale.validate(0)).toThrow() // Zero should be invalid
+			expect(() => lineShapeProps.scale.validate(-1)).toThrow() // Negative should be invalid
+		})
+	})
+
+	describe('lineShapeMigrations - AddSnapHandles migration', () => {
+		const { up } = getTestMigration(lineShapeVersions.AddSnapHandles)
+
+		it('should add canSnap property to all handles', () => {
+			const oldRecord = {
+				id: 'shape:line1',
+				props: {
+					handles: {
+						start: { x: 0, y: 0 },
+						end: { x: 100, y: 100 },
+					},
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.handles.start.canSnap).toBe(true)
+			expect(result.props.handles.end.canSnap).toBe(true)
+		})
+	})
+
+	describe('lineShapeMigrations - RemoveExtraHandleProps migration', () => {
+		const { up, down } = getTestMigration(lineShapeVersions.RemoveExtraHandleProps)
+
+		it('should preserve only x and y properties from handles', () => {
+			const oldRecord = {
+				id: 'shape:line1',
+				props: {
+					handles: {
+						a1: {
+							x: 10,
+							y: 20,
+							canSnap: true,
+							id: 'start',
+							type: 'vertex',
+							index: 'a1',
+							extraProp: 'remove this',
+						},
+					},
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.handles.a1).toEqual({ x: 10, y: 20 })
+		})
+
+		it('should restore full handle structure in down migration', () => {
+			const newRecord = {
+				id: 'shape:line1',
+				props: {
+					handles: {
+						a1: { x: 0, y: 0 },
+						a2: { x: 100, y: 100 },
+					},
+				},
+			}
+
+			const result = down(newRecord)
+			expect(result.props.handles.start).toEqual({
+				id: 'start',
+				type: 'vertex',
+				canBind: false,
+				canSnap: true,
+				index: 'a1',
+				x: 0,
+				y: 0,
+			})
+		})
+	})
+
+	describe('lineShapeMigrations - HandlesToPoints migration', () => {
+		const { up, down } = getTestMigration(lineShapeVersions.HandlesToPoints)
+
+		it('should convert handles to points array', () => {
+			const oldRecord = {
+				id: 'shape:line1',
+				props: {
+					handles: {
+						a1: { x: 0, y: 0 },
+						a2: { x: 50, y: 25 },
+					},
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.handles).toBeUndefined()
+			expect(result.props.points).toEqual([
+				{ x: 0, y: 0 },
+				{ x: 50, y: 25 },
+			])
+		})
+
+		it('should convert points back to handles', () => {
+			const newRecord = {
+				id: 'shape:line1',
+				props: {
+					points: [
+						{ x: 0, y: 0 },
+						{ x: 100, y: 50 },
+					],
+				},
+			}
+
+			const result = down(newRecord)
+			expect(result.props.points).toBeUndefined()
+			expect(result.props.handles).toBeDefined()
+			expect(Object.keys(result.props.handles)).toHaveLength(2)
+		})
+	})
+
+	describe('lineShapeMigrations - PointIndexIds migration', () => {
+		const { up, down } = getTestMigration(lineShapeVersions.PointIndexIds)
+
+		it('should convert points array to indexed points object', () => {
+			const oldRecord = {
+				id: 'shape:line1',
+				props: {
+					points: [
+						{ x: 0, y: 0 },
+						{ x: 50, y: 25 },
+					],
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(Array.isArray(result.props.points)).toBe(false)
+			expect(typeof result.props.points).toBe('object')
+
+			const pointKeys = Object.keys(result.props.points)
+			expect(pointKeys).toHaveLength(2)
+
+			// Each point should have id, index, x, y
+			pointKeys.forEach((key) => {
+				const point = result.props.points[key]
+				expect(point.id).toBe(key)
+				expect(point.index).toBe(key)
+			})
+		})
+
+		it('should convert indexed points object back to points array', () => {
+			const newRecord = {
+				id: 'shape:line1',
+				props: {
+					points: {
+						a1: { id: 'a1', index: 'a1' as IndexKey, x: 0, y: 0 },
+						a2: { id: 'a2', index: 'a2' as IndexKey, x: 50, y: 25 },
+					},
+				},
+			}
+
+			const result = down(newRecord)
+			expect(Array.isArray(result.props.points)).toBe(true)
+			expect(result.props.points).toEqual([
+				{ x: 0, y: 0 },
+				{ x: 50, y: 25 },
+			])
+		})
+	})
+
+	describe('lineShapeMigrations - AddScale migration', () => {
+		const { up, down } = getTestMigration(lineShapeVersions.AddScale)
+
+		it('should add scale property with default value 1', () => {
+			const oldRecord = {
+				id: 'shape:line1',
+				props: {
+					color: 'blue',
+					points: {
+						a1: { id: 'a1', index: 'a1' as IndexKey, x: 0, y: 0 },
+					},
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.scale).toBe(1)
+			expect(result.props.color).toBe('blue')
+		})
+
+		it('should remove scale property in down migration', () => {
+			const newRecord = {
+				id: 'shape:line1',
+				props: {
+					color: 'blue',
+					scale: 1.5,
+					points: {},
+				},
+			}
+
+			const result = down(newRecord)
+			expect(result.props.scale).toBeUndefined()
+			expect(result.props.color).toBe('blue')
+		})
+	})
+
+	describe('migration integration', () => {
+		it('should have migrations for all version IDs', () => {
+			const migrationIds = lineShapeMigrations.sequence
+				.filter((migration) => 'id' in migration)
+				.map((migration) => ('id' in migration ? migration.id : ''))
+				.filter(Boolean)
+
+			const versionIds = Object.values(lineShapeVersions)
+			versionIds.forEach((versionId) => {
+				expect(migrationIds).toContain(versionId)
+			})
+		})
+	})
+})

package/src/shapes/TLLineShape.ts

@@ -8,20 +8,57 @@ import { DefaultDashStyle, TLDefaultDashStyle } from '../styles/TLDashStyle'
 import { DefaultSizeStyle, TLDefaultSizeStyle } from '../styles/TLSizeStyle'
 import { TLBaseShape } from './TLBaseShape'
 
-/** @public */
+/**
+ * Style property for line shape spline interpolation. Determines how the line is rendered
+ * between points - either as straight line segments or smooth cubic curves.
+ *
+ * @public
+ * @example
+ * ```ts
+ * // Create a shape with cubic spline interpolation
+ * const lineProps = {
+ *   spline: 'cubic' as TLLineShapeSplineStyle,
+ *   // other props...
+ * }
+ * ```
+ */
 export const LineShapeSplineStyle = StyleProp.defineEnum('tldraw:spline', {
 	defaultValue: 'line',
 	values: ['cubic', 'line'],
 })
 
-/** @public */
+/**
+ * Type representing the spline style options for line shapes.
+ * - 'line': Straight line segments between points
+ * - 'cubic': Smooth cubic bezier curves between points
+ *
+ * @public
+ */
 export type TLLineShapeSplineStyle = T.TypeOf<typeof LineShapeSplineStyle>
 
-/** @public */
+/**
+ * Represents a single point in a line shape. Line shapes are made up of multiple points
+ * that define the path of the line, with each point having coordinates and ordering information.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const linePoint: TLLineShapePoint = {
+ *   id: 'a1',
+ *   index: 'a1' as IndexKey,
+ *   x: 100,
+ *   y: 50
+ * }
+ * ```
+ */
 export interface TLLineShapePoint {
+	/** Unique identifier for this point, used for tracking and ordering */
 	id: string
+	/** Fractional index key used for ordering points along the line */
 	index: IndexKey
+	/** X coordinate of the point relative to the line shape's origin */
 	x: number
+	/** Y coordinate of the point relative to the line shape's origin */
 	y: number
 }
 
@@ -32,20 +69,91 @@ const lineShapePointValidator: T.ObjectValidator<TLLineShapePoint> = T.object({
 	y: T.number,
 })
 
-/** @public */
+/**
+ * Properties for a line shape. Line shapes represent multi-point lines or splines
+ * that can be drawn by connecting multiple points with either straight segments or curves.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const lineProps: TLLineShapeProps = {
+ *   color: 'black',
+ *   dash: 'solid',
+ *   size: 'm',
+ *   spline: 'line',
+ *   points: {
+ *     'a1': { id: 'a1', index: 'a1', x: 0, y: 0 },
+ *     'a2': { id: 'a2', index: 'a2', x: 100, y: 50 }
+ *   },
+ *   scale: 1
+ * }
+ * ```
+ */
 export interface TLLineShapeProps {
+	/** Color style of the line stroke */
 	color: TLDefaultColorStyle
+	/** Dash pattern style for the line (solid, dashed, dotted) */
 	dash: TLDefaultDashStyle
+	/** Size/thickness style of the line stroke */
 	size: TLDefaultSizeStyle
+	/** Interpolation style between points (straight lines or curved splines) */
 	spline: TLLineShapeSplineStyle
+	/** Dictionary of points that make up the line, keyed by point ID */
 	points: Record<string, TLLineShapePoint>
+	/** Scale factor applied to the line shape for display */
 	scale: number
 }
 
-/** @public */
+/**
+ * A line shape that represents a multi-point line or spline on the canvas. Line shapes
+ * allow users to draw connected paths with multiple points, supporting both straight
+ * line segments and smooth curved splines.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const lineShape: TLLineShape = {
+ *   id: 'shape:line1',
+ *   type: 'line',
+ *   x: 100,
+ *   y: 100,
+ *   rotation: 0,
+ *   index: 'a1',
+ *   parentId: 'page:main',
+ *   isLocked: false,
+ *   opacity: 1,
+ *   props: {
+ *     color: 'red',
+ *     dash: 'dashed',
+ *     size: 'l',
+ *     spline: 'cubic',
+ *     points: {
+ *       'start': { id: 'start', index: 'a1', x: 0, y: 0 },
+ *       'end': { id: 'end', index: 'a2', x: 200, y: 100 }
+ *     },
+ *     scale: 1
+ *   },
+ *   meta: {},
+ *   typeName: 'shape'
+ * }
+ * ```
+ */
 export type TLLineShape = TLBaseShape<'line', TLLineShapeProps>
 
-/** @public */
+/**
+ * Validation schema for line shape properties. Defines the runtime validation rules
+ * for all properties of line shapes, ensuring data integrity and type safety.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { lineShapeProps } from '@tldraw/tlschema'
+ *
+ * // Used internally by the validation system
+ * const validator = T.object(lineShapeProps)
+ * const validatedProps = validator.validate(someLineProps)
+ * ```
+ */
 export const lineShapeProps: RecordProps<TLLineShape> = {
 	color: DefaultColorStyle,
 	dash: DefaultDashStyle,
@@ -55,7 +163,12 @@ export const lineShapeProps: RecordProps<TLLineShape> = {
 	scale: T.nonZeroNumber,
 }
 
-/** @public */
+/**
+ * Version identifiers for line shape migrations. These version numbers track
+ * significant schema changes over time, enabling proper data migration between versions.
+ *
+ * @public
+ */
 export const lineShapeVersions = createShapePropsMigrationIds('line', {
 	AddSnapHandles: 1,
 	RemoveExtraHandleProps: 2,
@@ -64,7 +177,14 @@ export const lineShapeVersions = createShapePropsMigrationIds('line', {
 	AddScale: 5,
 })
 
-/** @public */
+/**
+ * Migration sequence for line shapes. Handles schema evolution over time by defining
+ * how to upgrade and downgrade line shape data between different versions. Includes
+ * major structural changes like the transition from handles to points and the addition
+ * of scaling support.
+ *
+ * @public
+ */
 export const lineShapeMigrations = createShapePropsMigrationSequence({
 	sequence: [
 		{