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

package/src/recordsWithProps.test.ts

@@ -0,0 +1,188 @@
+import { Migration, createMigrationSequence } from '@tldraw/store'
+import { T } from '@tldraw/validate'
+import { describe, expect, it, vi } from 'vitest'
+import { SchemaPropsInfo } from './createTLSchema'
+import {
+	TLPropsMigration,
+	TLPropsMigrations,
+	createPropsMigration,
+	processPropsMigrations,
+} from './recordsWithProps'
+
+describe('createPropsMigration', () => {
+	it('should create a store migration from props migration', () => {
+		const propsMigration: TLPropsMigration = {
+			id: 'com.test.shape.custom/1' as const,
+			up: (props: any) => ({ ...props, newProp: 'added' }),
+			down: (props: any) => {
+				const { newProp: _newProp, ...rest } = props
+				return rest
+			},
+		}
+
+		const storeMigration = createPropsMigration('shape', 'custom', propsMigration)
+
+		expect(storeMigration.id).toBe('com.test.shape.custom/1')
+		expect(storeMigration.scope).toBe('record')
+		expect(typeof storeMigration.up).toBe('function')
+		expect(typeof storeMigration.down).toBe('function')
+		expect(typeof (storeMigration as any).filter).toBe('function')
+	})
+
+	it('should apply up migration to record props', () => {
+		const propsMigration: TLPropsMigration = {
+			id: 'com.test.shape.custom/1' as const,
+			up: (props: any) => ({ ...props, newProp: 'added' }),
+		}
+
+		const storeMigration = createPropsMigration('shape', 'custom', propsMigration)
+
+		const record = {
+			id: 'shape:test' as const,
+			typeName: 'shape' as const,
+			type: 'custom' as const,
+			props: { oldProp: 'value' },
+		}
+
+		storeMigration.up(record as any)
+
+		expect(record.props).toEqual({
+			oldProp: 'value',
+			newProp: 'added',
+		})
+	})
+
+	it('should apply down migration to record props', () => {
+		const propsMigration: TLPropsMigration = {
+			id: 'com.test.shape.custom/1' as const,
+			up: (props: any) => ({ ...props, newProp: 'added' }),
+			down: (props: any) => {
+				const { newProp: _newProp, ...rest } = props
+				return rest
+			},
+		}
+
+		const storeMigration = createPropsMigration('shape', 'custom', propsMigration)
+
+		const record = {
+			id: 'shape:test' as const,
+			typeName: 'shape' as const,
+			type: 'custom' as const,
+			props: { oldProp: 'value', newProp: 'added' },
+		}
+
+		if (storeMigration.down) {
+			storeMigration.down(record as any)
+		}
+
+		expect(record.props).toEqual({ oldProp: 'value' })
+	})
+})
+
+describe('processPropsMigrations', () => {
+	it('should throw error for mismatched sequenceId', () => {
+		const wrongSequenceId = createMigrationSequence({
+			sequenceId: 'com.wrong.shape.custom', // Wrong sequence ID
+			retroactive: true,
+			sequence: [],
+		})
+
+		const records: Record<string, SchemaPropsInfo> = {
+			custom: {
+				props: { width: T.number },
+				migrations: wrongSequenceId,
+			},
+		}
+
+		expect(() => processPropsMigrations('shape', records)).toThrow(`sequenceId mismatch for custom`)
+	})
+
+	it('should process TLPropsMigrations format', () => {
+		const propsMigrations: TLPropsMigrations = {
+			sequence: [
+				{
+					id: 'com.tldraw.shape.custom/1',
+					up: (props: any) => ({ ...props, v: 1 }),
+					down: (props: any) => {
+						const { v: _v, ...rest } = props
+						return rest
+					},
+				},
+				{
+					id: 'com.tldraw.shape.custom/2',
+					dependsOn: ['com.tldraw.shape.custom/1'],
+					up: (props: any) => ({ ...props, v: 2 }),
+					down: (props: any) => ({ ...props, v: 1 }),
+				},
+			],
+		}
+
+		const records: Record<string, SchemaPropsInfo> = {
+			custom: {
+				props: { width: T.number },
+				migrations: propsMigrations,
+			},
+		}
+
+		const result = processPropsMigrations('shape', records)
+
+		expect(result).toHaveLength(1)
+		expect(result[0].sequenceId).toBe('com.tldraw.shape.custom')
+		expect(result[0].retroactive).toBe(true)
+		expect(result[0].sequence).toHaveLength(2)
+
+		// Check that props migrations were converted to store migrations
+		const storeMigrations = result[0].sequence as Migration[]
+		expect(storeMigrations[0].id).toBe('com.tldraw.shape.custom/1')
+		expect(storeMigrations[0].scope).toBe('record')
+		expect(storeMigrations[1].id).toBe('com.tldraw.shape.custom/2')
+		expect(storeMigrations[1].dependsOn).toEqual(['com.tldraw.shape.custom/1'])
+	})
+
+	it('should process legacy migrations format', () => {
+		const legacyMigrations = {
+			migrators: {
+				1: {
+					up: vi.fn((record: any) => ({ ...record, version: 1 })),
+					down: vi.fn((record: any) => {
+						const { version: _version, ...rest } = record
+						return rest
+					}),
+				},
+				2: {
+					up: vi.fn((record: any) => ({ ...record, version: 2 })),
+					down: vi.fn((record: any) => ({ ...record, version: 1 })),
+				},
+			},
+		}
+
+		const records: Record<string, SchemaPropsInfo> = {
+			legacy: {
+				props: { width: T.number },
+				migrations: legacyMigrations as any,
+			},
+		}
+
+		const result = processPropsMigrations('shape', records)
+
+		expect(result).toHaveLength(1)
+		expect(result[0].sequenceId).toBe('com.tldraw.shape.legacy')
+		expect(result[0].retroactive).toBe(true)
+		expect(result[0].sequence).toHaveLength(2)
+
+		// Check legacy migration conversion
+		const migrations = result[0].sequence as Migration[]
+		expect(migrations[0].id).toBe('com.tldraw.shape.legacy/1')
+		expect(migrations[0].scope).toBe('record')
+		expect(migrations[1].id).toBe('com.tldraw.shape.legacy/2')
+		expect(migrations[1].scope).toBe('record')
+
+		// Test filter function - cast to the specific migration type that has filter
+		const recordMigration = migrations[0] as any
+		const matchingRecord = { typeName: 'shape', type: 'legacy' }
+		const nonMatchingRecord = { typeName: 'shape', type: 'other' }
+
+		expect(recordMigration.filter(matchingRecord)).toBe(true)
+		expect(recordMigration.filter(nonMatchingRecord)).toBe(false)
+	})
+})

package/src/recordsWithProps.ts

@@ -11,18 +11,78 @@ import { MakeUndefinedOptional, assert } from '@tldraw/utils'
 import { T } from '@tldraw/validate'
 import { SchemaPropsInfo } from './createTLSchema'
 
-/** @public */
+/**
+ * Maps a record's property types to their corresponding validators.
+ *
+ * This utility type takes a record type with a `props` object and creates
+ * a mapping where each property key maps to a validator for that property's type.
+ * This is used to define validation schemas for record properties.
+ *
+ * @example
+ * ```ts
+ * interface MyShape extends TLBaseShape<'custom', { width: number; color: string }> {}
+ *
+ * // Define validators for the shape properties
+ * const myShapeProps: RecordProps<MyShape> = {
+ *   width: T.number,
+ *   color: T.string
+ * }
+ * ```
+ *
+ * @public
+ */
 export type RecordProps<R extends UnknownRecord & { props: object }> = {
 	[K in keyof R['props']]: T.Validatable<R['props'][K]>
 }
 
-/** @public */
+/**
+ * Extracts the TypeScript types from a record properties configuration.
+ *
+ * Takes a configuration object where values are validators and returns the
+ * corresponding TypeScript types, with undefined values made optional.
+ *
+ * @example
+ * ```ts
+ * const shapePropsConfig = {
+ *   width: T.number,
+ *   height: T.number,
+ *   color: T.optional(T.string)
+ * }
+ *
+ * type ShapeProps = RecordPropsType<typeof shapePropsConfig>
+ * // Result: { width: number; height: number; color?: string }
+ * ```
+ *
+ * @public
+ */
 export type RecordPropsType<Config extends Record<string, T.Validatable<any>>> =
 	MakeUndefinedOptional<{
 		[K in keyof Config]: T.TypeOf<Config[K]>
 	}>
 
 /**
+ * A migration definition for shape or record properties.
+ *
+ * Defines how to transform record properties when migrating between schema versions.
+ * Each migration has an `up` function to upgrade data and an optional `down` function
+ * to downgrade data if needed.
+ *
+ * @example
+ * ```ts
+ * const addColorMigration: TLPropsMigration = {
+ *   id: 'com.myapp.shape.custom/1.0.0',
+ *   up: (props) => {
+ *     // Add a default color property
+ *     return { ...props, color: 'black' }
+ *   },
+ *   down: (props) => {
+ *     // Remove the color property
+ *     const { color, ...rest } = props
+ *     return rest
+ *   }
+ * }
+ * ```
+ *
  * @public
  */
 export interface TLPropsMigration {
@@ -43,12 +103,57 @@ export interface TLPropsMigration {
 }
 
 /**
+ * A sequence of property migrations for a record type.
+ *
+ * Contains an ordered array of migrations that should be applied to transform
+ * record properties from one version to another. Migrations can include both
+ * property-specific migrations and standalone dependency declarations.
+ *
+ * @example
+ * ```ts
+ * const myShapeMigrations: TLPropsMigrations = {
+ *   sequence: [
+ *     {
+ *       id: 'com.myapp.shape.custom/1.0.0',
+ *       up: (props) => ({ ...props, version: 1 })
+ *     },
+ *     {
+ *       id: 'com.myapp.shape.custom/2.0.0',
+ *       up: (props) => ({ ...props, newFeature: true })
+ *     }
+ *   ]
+ * }
+ * ```
+ *
  * @public
  */
 export interface TLPropsMigrations {
 	readonly sequence: Array<StandaloneDependsOn | TLPropsMigration>
 }
 
+/**
+ * Processes property migrations for all record types in a schema.
+ *
+ * Takes a collection of record configurations and converts their migrations
+ * into proper migration sequences that can be used by the store system.
+ * Handles different migration formats including legacy migrations.
+ *
+ * @param typeName - The base type name for the records (e.g., 'shape', 'binding')
+ * @param records - Record of type names to their schema configuration
+ * @returns Array of processed migration sequences
+ *
+ * @example
+ * ```ts
+ * const shapeRecords = {
+ *   geo: { props: geoProps, migrations: geoMigrations },
+ *   arrow: { props: arrowProps, migrations: arrowMigrations }
+ * }
+ *
+ * const sequences = processPropsMigrations('shape', shapeRecords)
+ * ```
+ *
+ * @internal
+ */
 export function processPropsMigrations<R extends UnknownRecord & { type: string; props: object }>(
 	typeName: R['typeName'],
 	records: Record<string, SchemaPropsInfo>
@@ -118,6 +223,30 @@ export function processPropsMigrations<R extends UnknownRecord & { type: string;
 	return result
 }
 
+/**
+ * Creates a store migration from a props migration definition.
+ *
+ * Converts a high-level property migration into a low-level store migration
+ * that can be applied to records. The resulting migration will only affect
+ * records of the specified type and subtype.
+ *
+ * @param typeName - The base type name (e.g., 'shape', 'binding')
+ * @param subType - The specific subtype (e.g., 'geo', 'arrow')
+ * @param m - The property migration definition
+ * @returns A store migration that applies the property transformation
+ *
+ * @example
+ * ```ts
+ * const propsMigration: TLPropsMigration = {
+ *   id: 'com.myapp.shape.custom/1.0.0',
+ *   up: (props) => ({ ...props, color: 'blue' })
+ * }
+ *
+ * const storeMigration = createPropsMigration('shape', 'custom', propsMigration)
+ * ```
+ *
+ * @internal
+ */
 export function createPropsMigration<R extends UnknownRecord & { type: string; props: object }>(
 	typeName: R['typeName'],
 	subType: R['type'],

package/src/shapes/ShapeWithCrop.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from 'vitest'
+import { TLShapeCrop } from './ShapeWithCrop'
+
+describe('TLShapeCrop', () => {
+	test('should calculate crop dimensions correctly', () => {
+		const crop: TLShapeCrop = {
+			topLeft: { x: 0.2, y: 0.3 },
+			bottomRight: { x: 0.8, y: 0.7 },
+		}
+
+		// This tests the actual utility of the crop interface - calculating dimensions
+		const width = crop.bottomRight.x - crop.topLeft.x
+		const height = crop.bottomRight.y - crop.topLeft.y
+
+		expect(width).toBeCloseTo(0.6)
+		expect(height).toBeCloseTo(0.4)
+	})
+})

package/src/shapes/ShapeWithCrop.ts

@@ -1,12 +1,74 @@
 import { VecModel } from '../misc/geometry-types'
 import { TLBaseShape } from './TLBaseShape'
 
-/** @public */
+/**
+ * Defines cropping parameters for shapes that support cropping.
+ *
+ * Specifies the visible area of an asset (like an image or video) within a shape.
+ * The crop is defined by top-left and bottom-right coordinates in normalized space (0-1),
+ * where (0,0) is the top-left of the original asset and (1,1) is the bottom-right.
+ *
+ * @example
+ * ```ts
+ * // Crop the center 50% of an image
+ * const centerCrop: TLShapeCrop = {
+ *   topLeft: { x: 0.25, y: 0.25 },
+ *   bottomRight: { x: 0.75, y: 0.75 }
+ * }
+ *
+ * // Crop for a circular image shape
+ * const circleCrop: TLShapeCrop = {
+ *   topLeft: { x: 0, y: 0 },
+ *   bottomRight: { x: 1, y: 1 },
+ *   isCircle: true
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface TLShapeCrop {
 	topLeft: VecModel
 	bottomRight: VecModel
 	isCircle?: boolean
 }
 
-/** @public */
+/**
+ * A shape type that supports cropping functionality.
+ *
+ * This type represents any shape that can display cropped content, typically media shapes
+ * like images and videos. The shape has width, height, and optional crop parameters.
+ * When crop is null, the entire asset is displayed.
+ *
+ * @example
+ * ```ts
+ * // An image shape with cropping
+ * const croppedImageShape: ShapeWithCrop = {
+ *   id: 'shape:image1',
+ *   type: 'image',
+ *   x: 100,
+ *   y: 200,
+ *   // ... other base shape properties
+ *   props: {
+ *     w: 300,
+ *     h: 200,
+ *     crop: {
+ *       topLeft: { x: 0.1, y: 0.1 },
+ *       bottomRight: { x: 0.9, y: 0.9 }
+ *     }
+ *   }
+ * }
+ *
+ * // A shape without cropping (shows full asset)
+ * const fullImageShape: ShapeWithCrop = {
+ *   // ... shape properties
+ *   props: {
+ *     w: 400,
+ *     h: 300,
+ *     crop: null // Shows entire asset
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export type ShapeWithCrop = TLBaseShape<string, { w: number; h: number; crop: TLShapeCrop | null }>