@tldraw/tlschema 4.1.0-canary.e653ec63c99b → 4.1.0-canary.e87046ba1a0c

package/src/records/TLShape.test.ts

@@ -0,0 +1,232 @@
+import { T } from '@tldraw/validate'
+import { describe, expect, it } from 'vitest'
+import { StyleProp } from '../styles/StyleProp'
+import {
+	createShapeId,
+	createShapePropsMigrationIds,
+	createShapeRecordType,
+	getShapePropKeysByStyle,
+	isShape,
+	isShapeId,
+	rootShapeMigrations,
+	rootShapeVersions,
+	TLShapeId,
+} from './TLShape'
+
+describe('rootShapeMigrations', () => {
+	it('should migrate AddIsLocked correctly', () => {
+		const migration = rootShapeMigrations.sequence.find(
+			(m) => m.id === rootShapeVersions.AddIsLocked
+		)!
+		expect(migration.up).toBeDefined()
+		expect(migration.down).toBeDefined()
+
+		const record: any = { id: 'shape:test', typeName: 'shape', type: 'geo' }
+		migration.up(record)
+		expect(record.isLocked).toBe(false)
+
+		migration.down!(record)
+		expect(record.isLocked).toBeUndefined()
+	})
+
+	it('should migrate HoistOpacity correctly', () => {
+		const migration = rootShapeMigrations.sequence.find(
+			(m) => m.id === rootShapeVersions.HoistOpacity
+		)!
+		expect(migration.up).toBeDefined()
+		expect(migration.down).toBeDefined()
+
+		// Test up migration
+		const record: any = {
+			id: 'shape:test',
+			typeName: 'shape',
+			type: 'geo',
+			props: { opacity: '0.5', color: 'red' },
+		}
+		migration.up(record)
+		expect(record.opacity).toBe(0.5)
+		expect(record.props.opacity).toBeUndefined()
+		expect(record.props.color).toBe('red')
+
+		// Test down migration
+		migration.down!(record)
+		expect(record.props.opacity).toBe('0.5')
+		expect(record.opacity).toBeUndefined()
+	})
+
+	it('should migrate AddMeta correctly', () => {
+		const migration = rootShapeMigrations.sequence.find((m) => m.id === rootShapeVersions.AddMeta)!
+		const record: any = { id: 'shape:test', typeName: 'shape', type: 'geo' }
+		migration.up(record)
+		expect(record.meta).toEqual({})
+	})
+
+	it('should handle AddWhite migration', () => {
+		const migration = rootShapeMigrations.sequence.find((m) => m.id === rootShapeVersions.AddWhite)!
+		expect(migration.up).toBeDefined()
+		expect(migration.down).toBeDefined()
+
+		// Up migration is noop
+		const record: any = { props: { color: 'white' } }
+		const original = { ...record }
+		migration.up(record)
+		expect(record).toEqual(original)
+
+		// Down migration converts white to black
+		migration.down!(record)
+		expect(record.props.color).toBe('black')
+	})
+})
+
+describe('isShape', () => {
+	it('should return true for shape records', () => {
+		const shape = {
+			id: 'shape:test' as TLShapeId,
+			typeName: 'shape',
+			type: 'geo',
+			x: 0,
+			y: 0,
+			rotation: 0,
+			index: 'a1' as any,
+			parentId: 'page:main' as any,
+			isLocked: false,
+			opacity: 1,
+			props: {},
+			meta: {},
+		}
+
+		expect(isShape(shape)).toBe(true)
+	})
+
+	it('should return false for non-shape records', () => {
+		const notShape = {
+			id: 'page:test',
+			typeName: 'page',
+			name: 'Test Page',
+		}
+
+		expect(isShape(notShape as any)).toBe(false)
+	})
+})
+
+describe('isShapeId', () => {
+	it('should return true for valid shape IDs', () => {
+		expect(isShapeId('shape:test')).toBe(true)
+		expect(isShapeId('shape:abc123')).toBe(true)
+		expect(isShapeId('shape:')).toBe(true)
+	})
+
+	it('should return false for invalid shape IDs', () => {
+		expect(isShapeId('page:test')).toBe(false)
+		expect(isShapeId('asset:test')).toBe(false)
+		expect(isShapeId('invalid')).toBe(false)
+		expect(isShapeId('')).toBe(false)
+	})
+})
+
+describe('createShapeId', () => {
+	it('should create shape IDs with auto-generated suffix', () => {
+		const id1 = createShapeId()
+		const id2 = createShapeId()
+
+		expect(id1.startsWith('shape:')).toBe(true)
+		expect(id2.startsWith('shape:')).toBe(true)
+		expect(id1).not.toBe(id2)
+		expect(id1.length).toBeGreaterThan(6) // 'shape:' + some ID
+		expect(id2.length).toBeGreaterThan(6)
+	})
+
+	it('should create shape IDs with custom suffix', () => {
+		const customId = createShapeId('my-custom-id')
+		expect(customId).toBe('shape:my-custom-id')
+	})
+})
+
+describe('getShapePropKeysByStyle', () => {
+	it('should map style props to their keys', () => {
+		const colorStyle = StyleProp.define('color', { defaultValue: 'black' })
+		const sizeStyle = StyleProp.define('size', { defaultValue: 'm' })
+
+		const props = {
+			color: colorStyle,
+			size: sizeStyle,
+			width: T.number,
+			height: T.number,
+		}
+
+		const styleMap = getShapePropKeysByStyle(props)
+		expect(styleMap.get(colorStyle)).toBe('color')
+		expect(styleMap.get(sizeStyle)).toBe('size')
+		expect(styleMap.size).toBe(2) // Only style props
+	})
+
+	it('should throw error for duplicate style props', () => {
+		const colorStyle = StyleProp.define('color', { defaultValue: 'black' })
+		const props = {
+			color1: colorStyle,
+			color2: colorStyle, // Same style prop used twice
+			width: T.number,
+		}
+
+		expect(() => getShapePropKeysByStyle(props)).toThrow('Duplicate style prop')
+	})
+})
+
+describe('createShapePropsMigrationIds', () => {
+	it('should create formatted migration IDs', () => {
+		const ids = createShapePropsMigrationIds('custom', {
+			AddColor: 1,
+			AddSize: 2,
+			RefactorProps: 3,
+		})
+
+		expect(ids.AddColor).toBe('com.tldraw.shape.custom/1')
+		expect(ids.AddSize).toBe('com.tldraw.shape.custom/2')
+		expect(ids.RefactorProps).toBe('com.tldraw.shape.custom/3')
+	})
+})
+
+describe('createShapeRecordType', () => {
+	it('should create a record type for shapes', () => {
+		const shapes = {
+			geo: {
+				props: {
+					w: T.number,
+					h: T.number,
+					color: StyleProp.define('color', { defaultValue: 'black' }),
+				},
+				meta: {},
+			},
+			text: {
+				props: {
+					text: T.string,
+					size: StyleProp.define('size', { defaultValue: 'm' }),
+				},
+				meta: {},
+			},
+		}
+
+		const ShapeRecordType = createShapeRecordType(shapes)
+
+		expect(ShapeRecordType.typeName).toBe('shape')
+		expect(ShapeRecordType.scope).toBe('document')
+
+		// Should be able to create shapes
+		const geoShape = ShapeRecordType.create({
+			id: createShapeId(),
+			type: 'geo',
+			parentId: 'page:main' as any,
+			index: 'a1' as any,
+			props: {},
+		})
+
+		expect(geoShape.typeName).toBe('shape')
+		expect(geoShape.type).toBe('geo')
+		expect(geoShape.x).toBe(0) // Default
+		expect(geoShape.y).toBe(0) // Default
+		expect(geoShape.rotation).toBe(0) // Default
+		expect(geoShape.isLocked).toBe(false) // Default
+		expect(geoShape.opacity).toBe(1) // Default
+		expect(geoShape.meta).toEqual({}) // Default
+	})
+})

package/src/records/TLShape.ts

@@ -29,7 +29,21 @@ import { TLPageId } from './TLPage'
 /**
  * The default set of shapes that are available in the editor.
  *
- * @public */
+ * This union type represents all the built-in shape types supported by tldraw,
+ * including arrows, bookmarks, drawings, embeds, frames, geometry shapes,
+ * groups, images, lines, notes, text, videos, and highlights.
+ *
+ * @example
+ * ```ts
+ * // Check if a shape is a default shape type
+ * function isDefaultShape(shape: TLShape): shape is TLDefaultShape {
+ *   const defaultTypes = ['arrow', 'bookmark', 'draw', 'embed', 'frame', 'geo', 'group', 'image', 'line', 'note', 'text', 'video', 'highlight']
+ *   return defaultTypes.includes(shape.type)
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLDefaultShape =
 	| TLArrowShape
 	| TLBookmarkShape
@@ -49,17 +63,73 @@ export type TLDefaultShape =
  * A type for a shape that is available in the editor but whose type is
  * unknown—either one of the editor's default shapes or else a custom shape.
  *
- * @public */
+ * This is useful when working with shapes generically without knowing their specific type.
+ * The shape type is a string and props are a generic object.
+ *
+ * @example
+ * ```ts
+ * // Handle any shape regardless of its specific type
+ * function processUnknownShape(shape: TLUnknownShape) {
+ *   console.log(`Processing shape of type: ${shape.type}`)
+ *   console.log(`Position: (${shape.x}, ${shape.y})`)
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLUnknownShape = TLBaseShape<string, object>
 
 /**
  * The set of all shapes that are available in the editor, including unknown shapes.
  *
+ * This is the primary shape type used throughout tldraw. It includes both the
+ * built-in default shapes and any custom shapes that might be added.
+ *
+ * @example
+ * ```ts
+ * // Work with any shape in the editor
+ * function moveShape(shape: TLShape, deltaX: number, deltaY: number): TLShape {
+ *   return {
+ *     ...shape,
+ *     x: shape.x + deltaX,
+ *     y: shape.y + deltaY
+ *   }
+ * }
+ * ```
+ *
  * @public
  */
 export type TLShape = TLDefaultShape | TLUnknownShape
 
-/** @public */
+/**
+ * A partial version of a shape, useful for updates and patches.
+ *
+ * This type represents a shape where all properties except `id` and `type` are optional.
+ * It's commonly used when updating existing shapes or creating shape patches.
+ *
+ * @example
+ * ```ts
+ * // Update a shape's position
+ * const shapeUpdate: TLShapePartial = {
+ *   id: 'shape:123',
+ *   type: 'geo',
+ *   x: 100,
+ *   y: 200
+ * }
+ *
+ * // Update shape properties
+ * const propsUpdate: TLShapePartial<TLGeoShape> = {
+ *   id: 'shape:123',
+ *   type: 'geo',
+ *   props: {
+ *     w: 150,
+ *     h: 100
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLShapePartial<T extends TLShape = TLShape> = T extends T
 	? {
 			id: TLShapeId
@@ -69,13 +139,57 @@ export type TLShapePartial<T extends TLShape = TLShape> = T extends T
 		} & Partial<Omit<T, 'type' | 'id' | 'props' | 'meta'>>
 	: never
 
-/** @public */
+/**
+ * A unique identifier for a shape record.
+ *
+ * Shape IDs are branded strings that start with "shape:" followed by a unique identifier.
+ * This type-safe approach prevents mixing up different types of record IDs.
+ *
+ * @example
+ * ```ts
+ * const shapeId: TLShapeId = createShapeId() // "shape:abc123"
+ * const customId: TLShapeId = createShapeId('my-custom-id') // "shape:my-custom-id"
+ * ```
+ *
+ * @public
+ */
 export type TLShapeId = RecordId<TLUnknownShape>
 
-/** @public */
+/**
+ * The ID of a shape's parent, which can be either a page or another shape.
+ *
+ * Shapes can be parented to pages (for top-level shapes) or to other shapes
+ * (for shapes inside frames or groups).
+ *
+ * @example
+ * ```ts
+ * // Shape parented to a page
+ * const pageParentId: TLParentId = 'page:main'
+ *
+ * // Shape parented to another shape (e.g., inside a frame)
+ * const shapeParentId: TLParentId = 'shape:frame123'
+ * ```
+ *
+ * @public
+ */
 export type TLParentId = TLPageId | TLShapeId
 
-/** @public */
+/**
+ * Migration version IDs for the root shape schema.
+ *
+ * These track the evolution of the base shape structure over time, ensuring
+ * that shapes created in older versions can be migrated to newer formats.
+ *
+ * @example
+ * ```ts
+ * // Check if a migration needs to be applied
+ * if (shapeVersion < rootShapeVersions.AddIsLocked) {
+ *   // Apply isLocked migration
+ * }
+ * ```
+ *
+ * @public
+ */
 export const rootShapeVersions = createMigrationIds('com.tldraw.shape', {
 	AddIsLocked: 1,
 	HoistOpacity: 2,
@@ -83,7 +197,15 @@ export const rootShapeVersions = createMigrationIds('com.tldraw.shape', {
 	AddWhite: 4,
 } as const)
 
-/** @public */
+/**
+ * Migration sequence for the root shape record type.
+ *
+ * This sequence defines how shape records should be transformed when migrating
+ * between different schema versions. Each migration handles a specific version
+ * upgrade, ensuring data compatibility across tldraw versions.
+ *
+ * @public
+ */
 export const rootShapeMigrations = createRecordMigrationSequence({
 	sequenceId: 'com.tldraw.shape',
 	recordType: 'shape',
@@ -138,24 +260,115 @@ export const rootShapeMigrations = createRecordMigrationSequence({
 	],
 })
 
-/** @public */
+/**
+ * Type guard to check if a record is a shape.
+ *
+ * @param record - The record to check
+ * @returns True if the record is a shape, false otherwise
+ *
+ * @example
+ * ```ts
+ * const record = store.get('shape:abc123')
+ * if (isShape(record)) {
+ *   console.log(`Shape type: ${record.type}`)
+ *   console.log(`Position: (${record.x}, ${record.y})`)
+ * }
+ * ```
+ *
+ * @public
+ */
 export function isShape(record?: UnknownRecord): record is TLShape {
 	if (!record) return false
 	return record.typeName === 'shape'
 }
 
-/** @public */
+/**
+ * Type guard to check if a string is a valid shape ID.
+ *
+ * @param id - The string to check
+ * @returns True if the string is a valid shape ID, false otherwise
+ *
+ * @example
+ * ```ts
+ * const id = 'shape:abc123'
+ * if (isShapeId(id)) {
+ *   const shape = store.get(id) // TypeScript knows id is TLShapeId
+ * }
+ *
+ * // Check user input
+ * function selectShape(id: string) {
+ *   if (isShapeId(id)) {
+ *     editor.selectShape(id)
+ *   } else {
+ *     console.error('Invalid shape ID format')
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export function isShapeId(id?: string): id is TLShapeId {
 	if (!id) return false
 	return id.startsWith('shape:')
 }
 
-/** @public */
+/**
+ * Creates a new shape ID.
+ *
+ * @param id - Optional custom ID suffix. If not provided, a unique ID will be generated
+ * @returns A new shape ID with the "shape:" prefix
+ *
+ * @example
+ * ```ts
+ * // Create a shape with auto-generated ID
+ * const shapeId = createShapeId() // "shape:abc123"
+ *
+ * // Create a shape with custom ID
+ * const customShapeId = createShapeId('my-rectangle') // "shape:my-rectangle"
+ *
+ * // Use in shape creation
+ * const newShape: TLGeoShape = {
+ *   id: createShapeId(),
+ *   type: 'geo',
+ *   x: 100,
+ *   y: 200,
+ *   // ... other properties
+ * }
+ * ```
+ *
+ * @public
+ */
 export function createShapeId(id?: string): TLShapeId {
 	return `shape:${id ?? uniqueId()}` as TLShapeId
 }
 
-/** @internal */
+/**
+ * Extracts style properties from a shape's props definition and maps them to their property keys.
+ *
+ * This function analyzes shape property validators to identify which ones are style properties
+ * and creates a mapping from StyleProp instances to their corresponding property keys.
+ * It also validates that each style property is only used once per shape.
+ *
+ * @param props - Record of property validators for a shape type
+ * @returns Map from StyleProp instances to their property keys
+ * @throws Error if a style property is used more than once in the same shape
+ *
+ * @example
+ * ```ts
+ * const geoShapeProps = {
+ *   color: DefaultColorStyle,
+ *   fill: DefaultFillStyle,
+ *   width: T.number,
+ *   height: T.number
+ * }
+ *
+ * const styleMap = getShapePropKeysByStyle(geoShapeProps)
+ * // styleMap.get(DefaultColorStyle) === 'color'
+ * // styleMap.get(DefaultFillStyle) === 'fill'
+ * ```
+ *
+ * @internal
+ */
 export function getShapePropKeysByStyle(props: Record<string, T.Validatable<any>>) {
 	const propKeysByStyle = new Map<StyleProp<unknown>, string>()
 	for (const [key, prop] of Object.entries(props)) {
@@ -172,6 +385,27 @@ export function getShapePropKeysByStyle(props: Record<string, T.Validatable<any>
 }
 
 /**
+ * Creates a migration sequence for shape properties.
+ *
+ * This is a pass-through function that maintains the same structure as the input.
+ * It's used for consistency and to provide a clear API for defining shape property migrations.
+ *
+ * @param migrations - The migration sequence to create
+ * @returns The same migration sequence (pass-through)
+ *
+ * @example
+ * ```ts
+ * const myShapeMigrations = createShapePropsMigrationSequence({
+ *   sequence: [
+ *     {
+ *       id: 'com.myapp.shape.custom/1.0.0',
+ *       up: (props) => ({ ...props, newProperty: 'default' }),
+ *       down: ({ newProperty, ...props }) => props
+ *     }
+ *   ]
+ * })
+ * ```
+ *
  * @public
  */
 export function createShapePropsMigrationSequence(
@@ -181,6 +415,29 @@ export function createShapePropsMigrationSequence(
 }
 
 /**
+ * Creates properly formatted migration IDs for shape properties.
+ *
+ * Generates standardized migration IDs following the convention:
+ * `com.tldraw.shape.{shapeType}/{version}`
+ *
+ * @param shapeType - The type of shape these migrations apply to
+ * @param ids - Record mapping migration names to version numbers
+ * @returns Record with the same keys but formatted migration ID values
+ *
+ * @example
+ * ```ts
+ * const myShapeVersions = createShapePropsMigrationIds('custom', {
+ *   AddColor: 1,
+ *   AddSize: 2,
+ *   RefactorProps: 3
+ * })
+ * // Result: {
+ * //   AddColor: 'com.tldraw.shape.custom/1',
+ * //   AddSize: 'com.tldraw.shape.custom/2',
+ * //   RefactorProps: 'com.tldraw.shape.custom/3'
+ * // }
+ * ```
+ *
  * @public
  */
 export function createShapePropsMigrationIds<
@@ -190,7 +447,27 @@ export function createShapePropsMigrationIds<
 	return mapObjectMapValues(ids, (_k, v) => `com.tldraw.shape.${shapeType}/${v}`) as any
 }
 
-/** @internal */
+/**
+ * Creates the record type definition for shapes.
+ *
+ * This function generates a complete record type for shapes that includes validation
+ * for all registered shape types. It combines the base shape properties with
+ * type-specific properties and creates a union validator that can handle any
+ * registered shape type.
+ *
+ * @param shapes - Record of shape type names to their schema configuration
+ * @returns A complete RecordType for shapes with proper validation and default properties
+ *
+ * @example
+ * ```ts
+ * const shapeRecordType = createShapeRecordType({
+ *   geo: { props: geoShapeProps, migrations: geoMigrations },
+ *   arrow: { props: arrowShapeProps, migrations: arrowMigrations }
+ * })
+ * ```
+ *
+ * @internal
+ */
 export function createShapeRecordType(shapes: Record<string, SchemaPropsInfo>) {
 	return createRecordType<TLShape>('shape', {
 		scope: 'document',