@tldraw/tlschema 4.1.0-next.542f014c3fac → 4.1.0-next.cb6f90590225

package/src/createTLSchema.test.ts

@@ -0,0 +1,181 @@
+import { createMigrationSequence, MigrationSequence, StoreSchema } from '@tldraw/store'
+import { T } from '@tldraw/validate'
+import { describe, expect, it } from 'vitest'
+import { createTLSchema, defaultBindingSchemas, defaultShapeSchemas } from './createTLSchema'
+import { TLDefaultBinding } from './records/TLBinding'
+import { TLDefaultShape } from './records/TLShape'
+import { StyleProp } from './styles/StyleProp'
+import { DefaultColorStyle } from './styles/TLColorStyle'
+
+describe('defaultShapeSchemas', () => {
+	const expectedShapeTypes: Array<TLDefaultShape['type']> = [
+		'arrow',
+		'bookmark',
+		'draw',
+		'embed',
+		'frame',
+		'geo',
+		'group',
+		'highlight',
+		'image',
+		'line',
+		'note',
+		'text',
+		'video',
+	]
+
+	it('should contain all default shape types', () => {
+		const actualShapeTypes = Object.keys(defaultShapeSchemas)
+
+		expect(actualShapeTypes).toHaveLength(expectedShapeTypes.length)
+
+		for (const shapeType of expectedShapeTypes) {
+			expect(actualShapeTypes).toContain(shapeType)
+		}
+	})
+
+	it('should contain style properties in shape props', () => {
+		// Test a few known shapes that should have style properties
+		const geoProps = defaultShapeSchemas.geo.props
+		const arrowProps = defaultShapeSchemas.arrow.props
+
+		// Check that some props are StyleProp instances
+		let hasStyleProp = false
+		for (const prop of Object.values(geoProps || {})) {
+			if (prop instanceof StyleProp) {
+				hasStyleProp = true
+				break
+			}
+		}
+		expect(hasStyleProp).toBe(true)
+
+		// Check arrow props too
+		hasStyleProp = false
+		for (const prop of Object.values(arrowProps || {})) {
+			if (prop instanceof StyleProp) {
+				hasStyleProp = true
+				break
+			}
+		}
+		expect(hasStyleProp).toBe(true)
+	})
+})
+
+describe('defaultBindingSchemas', () => {
+	const expectedBindingTypes: Array<TLDefaultBinding['type']> = ['arrow']
+
+	it('should contain all default binding types', () => {
+		const actualBindingTypes = Object.keys(defaultBindingSchemas)
+
+		expect(actualBindingTypes).toHaveLength(expectedBindingTypes.length)
+
+		for (const bindingType of expectedBindingTypes) {
+			expect(actualBindingTypes).toContain(bindingType)
+		}
+	})
+})
+
+describe('createTLSchema', () => {
+	it('should create a valid schema with default parameters', () => {
+		const schema = createTLSchema()
+
+		expect(schema).toBeInstanceOf(StoreSchema)
+		expect(schema.types).toBeDefined()
+		expect(schema.migrations).toBeDefined()
+	})
+
+	it('should create schema with custom shapes', () => {
+		const customShapeProps = {
+			customProp: T.string,
+			color: DefaultColorStyle,
+		}
+
+		const customShapes = {
+			...defaultShapeSchemas,
+			custom: {
+				props: customShapeProps,
+				migrations: createMigrationSequence({
+					sequenceId: 'com.tldraw.shape.custom', // Use the expected format
+					sequence: [],
+				}),
+			},
+		}
+
+		const schema = createTLSchema({ shapes: customShapes })
+
+		expect(schema).toBeInstanceOf(StoreSchema)
+		expect(schema.types.shape).toBeDefined()
+	})
+
+	it('should create schema with custom bindings', () => {
+		const customBindingProps = {
+			customProp: T.number,
+		}
+
+		const customBindings = {
+			...defaultBindingSchemas,
+			custom: {
+				props: customBindingProps,
+				migrations: createMigrationSequence({
+					sequenceId: 'com.tldraw.binding.custom', // Use the expected format
+					sequence: [],
+				}),
+			},
+		}
+
+		const schema = createTLSchema({ bindings: customBindings })
+
+		expect(schema).toBeInstanceOf(StoreSchema)
+		expect(schema.types.binding).toBeDefined()
+	})
+
+	it('should create schema with additional migrations', () => {
+		const additionalMigrations: MigrationSequence[] = [
+			createMigrationSequence({
+				sequenceId: 'com.test.additional',
+				sequence: [],
+			}),
+		]
+
+		const schema = createTLSchema({ migrations: additionalMigrations })
+
+		expect(schema).toBeInstanceOf(StoreSchema)
+		expect(schema.migrations).toBeDefined()
+	})
+
+	it('should create schema with only specific shapes', () => {
+		const minimalShapes = {
+			geo: defaultShapeSchemas.geo,
+			text: defaultShapeSchemas.text,
+			arrow: defaultShapeSchemas.arrow, // Include arrow to satisfy binding dependencies
+		}
+
+		const schema = createTLSchema({ shapes: minimalShapes })
+
+		expect(schema).toBeInstanceOf(StoreSchema)
+		expect(schema.types.shape).toBeDefined()
+	})
+
+	describe('style property collection and validation', () => {
+		it('should throw error for duplicate style property IDs', () => {
+			// Create a duplicate style property with same ID as DefaultColorStyle
+			const duplicateColorStyle = StyleProp.defineEnum('tldraw:color', {
+				defaultValue: 'black',
+				values: ['black', 'white'],
+			})
+
+			const conflictingShapes = {
+				shape1: {
+					props: { color: DefaultColorStyle },
+				},
+				shape2: {
+					props: { color: duplicateColorStyle },
+				},
+			}
+
+			expect(() => createTLSchema({ shapes: conflictingShapes })).toThrow(
+				'Multiple StyleProp instances with the same id: tldraw:color'
+			)
+		})
+	})
+})

package/src/createTLSchema.ts

@@ -39,17 +39,100 @@ import { videoShapeMigrations, videoShapeProps } from './shapes/TLVideoShape'
 import { storeMigrations } from './store-migrations'
 import { StyleProp } from './styles/StyleProp'
 
-/** @public */
+/**
+ * Configuration information for a schema type (shape or binding), including its properties,
+ * metadata, and migration sequences for data evolution over time.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { arrowShapeMigrations, arrowShapeProps } from './shapes/TLArrowShape'
+ *
+ * const myShapeSchema: SchemaPropsInfo = {
+ *   migrations: arrowShapeMigrations,
+ *   props: arrowShapeProps,
+ *   meta: {
+ *     customField: T.string,
+ *   },
+ * }
+ * ```
+ */
 export interface SchemaPropsInfo {
+	/**
+	 * Migration sequences for handling data evolution over time. Can be legacy migrations,
+	 * props-specific migrations, or general migration sequences.
+	 */
 	migrations?: LegacyMigrations | TLPropsMigrations | MigrationSequence
+
+	/**
+	 * Validation schema for the shape or binding properties. Maps property names to their validators.
+	 */
 	props?: Record<string, StoreValidator<any>>
+
+	/**
+	 * Validation schema for metadata fields. Maps metadata field names to their validators.
+	 */
 	meta?: Record<string, StoreValidator<any>>
 }
 
-/** @public */
+/**
+ * The complete schema definition for a tldraw store, encompassing all record types,
+ * validation rules, and migration sequences. This schema defines the structure of
+ * the persistent data model used by tldraw.
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { createTLSchema, defaultShapeSchemas } from '@tldraw/tlschema'
+ * import { Store } from '@tldraw/store'
+ *
+ * const schema: TLSchema = createTLSchema({
+ *   shapes: defaultShapeSchemas,
+ * })
+ *
+ * const store = new Store({ schema })
+ * ```
+ */
 export type TLSchema = StoreSchema<TLRecord, TLStoreProps>
 
-/** @public */
+/**
+ * Default shape schema configurations for all built-in tldraw shape types.
+ * Each shape type includes its validation props and migration sequences.
+ *
+ * This object contains schema information for:
+ * - arrow: Directional lines that can bind to other shapes
+ * - bookmark: Website bookmark cards with preview information
+ * - draw: Freehand drawing paths created with drawing tools
+ * - embed: Embedded content from external services (YouTube, Figma, etc.)
+ * - frame: Container shapes for organizing content
+ * - geo: Geometric shapes (rectangles, ellipses, triangles, etc.)
+ * - group: Logical groupings of multiple shapes
+ * - highlight: Highlighting strokes from the highlighter tool
+ * - image: Raster image shapes referencing image assets
+ * - line: Multi-point lines and splines
+ * - note: Sticky note shapes with text content
+ * - text: Rich text shapes with formatting support
+ * - video: Video shapes referencing video assets
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { createTLSchema, defaultShapeSchemas } from '@tldraw/tlschema'
+ *
+ * // Use all default shapes
+ * const schema = createTLSchema({
+ *   shapes: defaultShapeSchemas,
+ * })
+ *
+ * // Use only specific default shapes
+ * const minimalSchema = createTLSchema({
+ *   shapes: {
+ *     geo: defaultShapeSchemas.geo,
+ *     text: defaultShapeSchemas.text,
+ *   },
+ * })
+ * ```
+ */
 export const defaultShapeSchemas = {
 	arrow: { migrations: arrowShapeMigrations, props: arrowShapeProps },
 	bookmark: { migrations: bookmarkShapeMigrations, props: bookmarkShapeProps },
@@ -66,17 +149,91 @@ export const defaultShapeSchemas = {
 	video: { migrations: videoShapeMigrations, props: videoShapeProps },
 } satisfies { [T in TLDefaultShape['type']]: SchemaPropsInfo }
 
-/** @public */
+/**
+ * Default binding schema configurations for all built-in tldraw binding types.
+ * Bindings represent relationships between shapes, such as arrows connected to shapes.
+ *
+ * Currently includes:
+ * - arrow: Bindings that connect arrow shapes to other shapes at specific anchor points
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { createTLSchema, defaultBindingSchemas } from '@tldraw/tlschema'
+ *
+ * // Use default bindings
+ * const schema = createTLSchema({
+ *   bindings: defaultBindingSchemas,
+ * })
+ *
+ * // Add custom binding alongside defaults
+ * const customSchema = createTLSchema({
+ *   bindings: {
+ *     ...defaultBindingSchemas,
+ *     myCustomBinding: {
+ *       props: myCustomBindingProps,
+ *       migrations: myCustomBindingMigrations,
+ *     },
+ *   },
+ * })
+ * ```
+ */
 export const defaultBindingSchemas = {
 	arrow: { migrations: arrowBindingMigrations, props: arrowBindingProps },
 } satisfies { [T in TLDefaultBinding['type']]: SchemaPropsInfo }
 
 /**
- * Create a TLSchema with custom shapes. Custom shapes cannot override default shapes.
+ * Creates a complete TLSchema for use with tldraw stores. This schema defines the structure,
+ * validation, and migration sequences for all record types in a tldraw application.
+ *
+ * The schema includes all core record types (pages, cameras, instances, etc.) plus the
+ * shape and binding types you specify. Style properties are automatically collected from
+ * all shapes to ensure consistency across the application.
+ *
+ * @param options - Configuration options for the schema
+ *   - shapes - Shape schema configurations. Defaults to defaultShapeSchemas if not provided
+ *   - bindings - Binding schema configurations. Defaults to defaultBindingSchemas if not provided
+ *   - migrations - Additional migration sequences to include in the schema
+ * @returns A complete TLSchema ready for use with Store creation
+ *
+ * @public
+ * @example
+ * ```ts
+ * import { createTLSchema, defaultShapeSchemas, defaultBindingSchemas } from '@tldraw/tlschema'
+ * import { Store } from '@tldraw/store'
+ *
+ * // Create schema with all default shapes and bindings
+ * const schema = createTLSchema()
+ *
+ * // Create schema with custom shapes added
+ * const customSchema = createTLSchema({
+ *   shapes: {
+ *     ...defaultShapeSchemas,
+ *     myCustomShape: {
+ *       props: myCustomShapeProps,
+ *       migrations: myCustomShapeMigrations,
+ *     },
+ *   },
+ * })
  *
- * @param opts - Options
+ * // Create schema with only specific shapes
+ * const minimalSchema = createTLSchema({
+ *   shapes: {
+ *     geo: defaultShapeSchemas.geo,
+ *     text: defaultShapeSchemas.text,
+ *   },
+ *   bindings: defaultBindingSchemas,
+ * })
  *
- * @public */
+ * // Use the schema with a store
+ * const store = new Store({
+ *   schema: customSchema,
+ *   props: {
+ *     defaultName: 'My Drawing',
+ *   },
+ * })
+ * ```
+ */
 export function createTLSchema({
 	shapes = defaultShapeSchemas,
 	bindings = defaultBindingSchemas,

package/src/index.ts

@@ -1,3 +1,35 @@
+/**
+ * @fileoverview
+ * Main entry point for the tldraw schema package. Exports the complete type system,
+ * data structures, validation, and migrations for tldraw's persisted data.
+ *
+ * This package provides:
+ * - Schema creation utilities (createTLSchema, defaultShapeSchemas, defaultBindingSchemas)
+ * - All built-in shape types (TLGeoShape, TLTextShape, TLArrowShape, etc.)
+ * - Asset management types and validators (TLImageAsset, TLVideoAsset, TLBookmarkAsset)
+ * - Binding system for shape relationships (TLArrowBinding)
+ * - Store integration types (TLStore, TLStoreProps, TLStoreSnapshot)
+ * - Style properties for consistent styling (DefaultColorStyle, DefaultSizeStyle, etc.)
+ * - Validation utilities and type guards
+ * - Migration systems for schema evolution
+ * - Geometry and utility types
+ *
+ * @example
+ * ```ts
+ * import { createTLSchema, defaultShapeSchemas, TLStore } from '@tldraw/tlschema'
+ *
+ * // Create a schema with default shapes
+ * const schema = createTLSchema({
+ *   shapes: defaultShapeSchemas
+ * })
+ *
+ * // Use with a store
+ * const store = new Store({ schema })
+ * ```
+ *
+ * @public
+ */
+
 import { registerTldrawLibraryVersion } from '@tldraw/utils'
 export { assetIdValidator, createAssetValidator, type TLBaseAsset } from './assets/TLBaseAsset'
 export { type TLBookmarkAsset } from './assets/TLBookmarkAsset'

package/src/misc/TLColor.ts

@@ -2,9 +2,23 @@ import { T } from '@tldraw/validate'
 import { SetValue } from '../util-types'
 
 /**
- * The colors used by tldraw's default shapes.
+ * The colors used by tldraw's canvas UI system.
  *
- *  @public */
+ * These are special color types used for canvas UI elements like selections,
+ * accents, and other interface components that overlay the drawing canvas.
+ * Unlike shape colors, these are semantic color types that adapt to the
+ * current theme.
+ *
+ * @example
+ * ```ts
+ * // Check if a color is a canvas UI color
+ * if (TL_CANVAS_UI_COLOR_TYPES.has('selection-stroke')) {
+ *   console.log('This is a valid canvas UI color')
+ * }
+ * ```
+ *
+ * @public
+ */
 export const TL_CANVAS_UI_COLOR_TYPES = new Set([
 	'accent',
 	'white',
@@ -16,13 +30,43 @@ export const TL_CANVAS_UI_COLOR_TYPES = new Set([
 ] as const)
 
 /**
- * A type for the colors used by tldraw's default shapes.
+ * A union type representing the available canvas UI color types.
+ *
+ * Canvas UI colors are semantic color types used for interface elements
+ * that overlay the drawing canvas, such as selection indicators, accents,
+ * and other UI components.
+ *
+ * @example
+ * ```ts
+ * const selectionColor: TLCanvasUiColor = 'selection-stroke'
+ * const accentColor: TLCanvasUiColor = 'accent'
+ * const backgroundColor: TLCanvasUiColor = 'white'
+ * ```
  *
- *  @public */
+ * @public
+ */
 export type TLCanvasUiColor = SetValue<typeof TL_CANVAS_UI_COLOR_TYPES>
 
 /**
- * A validator for the colors used by tldraw's default shapes.
+ * A validator for canvas UI color types.
+ *
+ * This validator ensures that color values are one of the valid canvas UI
+ * color types defined in {@link TL_CANVAS_UI_COLOR_TYPES}. It provides
+ * runtime type checking for canvas UI color properties.
+ *
+ * @example
+ * ```ts
+ * import { canvasUiColorTypeValidator } from '@tldraw/tlschema'
+ *
+ * // Validate a color value
+ * try {
+ *   const validColor = canvasUiColorTypeValidator.validate('accent')
+ *   console.log('Valid color:', validColor)
+ * } catch (error) {
+ *   console.error('Invalid color:', error.message)
+ * }
+ * ```
  *
- * @public */
+ * @public
+ */
 export const canvasUiColorTypeValidator = T.setEnum(TL_CANVAS_UI_COLOR_TYPES)

package/src/misc/TLCursor.ts

@@ -2,9 +2,26 @@ import { T } from '@tldraw/validate'
 import { SetValue } from '../util-types'
 
 /**
- * The cursor types used by tldraw's default shapes.
+ * All available cursor types used throughout the tldraw editor.
  *
- * @public */
+ * These cursor types correspond to CSS cursor values and are used to indicate
+ * different interaction modes and states within the editor. The cursor types
+ * cover selection, resizing, rotation, text editing, and various other editor
+ * interactions.
+ *
+ * @example
+ * ```ts
+ * // Check if a cursor type is valid
+ * if (TL_CURSOR_TYPES.has('resize-corner')) {
+ *   console.log('Valid cursor type')
+ * }
+ *
+ * // Get all available cursor types
+ * const allCursors = Array.from(TL_CURSOR_TYPES)
+ * ```
+ *
+ * @public
+ */
 export const TL_CURSOR_TYPES = new Set([
 	'none',
 	'default',
@@ -30,24 +47,109 @@ export const TL_CURSOR_TYPES = new Set([
 ])
 
 /**
- * A type for the cursor types used by tldraw's default shapes.
+ * A union type representing all available cursor types in the tldraw editor.
+ *
+ * Each cursor type corresponds to a different interaction mode or state,
+ * helping users understand what action they can perform at any given moment.
+ *
+ * @example
+ * ```ts
+ * const defaultCursor: TLCursorType = 'default'
+ * const textCursor: TLCursorType = 'text'
+ * const resizeCursor: TLCursorType = 'resize-corner'
+ * const rotateCursor: TLCursorType = 'nesw-rotate'
+ * ```
  *
- *  @public */
+ * @public
+ */
 export type TLCursorType = SetValue<typeof TL_CURSOR_TYPES>
 
-/** @public */
+/**
+ * A validator for cursor types.
+ *
+ * This validator ensures that cursor type values are one of the valid types
+ * defined in {@link TL_CURSOR_TYPES}. It provides runtime type checking for
+ * cursor properties throughout the editor.
+ *
+ * @example
+ * ```ts
+ * import { cursorTypeValidator } from '@tldraw/tlschema'
+ *
+ * // Validate a cursor type
+ * try {
+ *   const validCursor = cursorTypeValidator.validate('pointer')
+ *   console.log('Valid cursor:', validCursor)
+ * } catch (error) {
+ *   console.error('Invalid cursor:', error.message)
+ * }
+ * ```
+ *
+ * @public
+ */
 export const cursorTypeValidator = T.setEnum(TL_CURSOR_TYPES)
 
 /**
- * A cursor used by tldraw.
+ * A cursor object used throughout the tldraw editor.
  *
- *  @public */
+ * Represents both the cursor type (which determines the visual appearance)
+ * and its rotation angle. The rotation is particularly useful for resize
+ * and rotation cursors that need to align with the current interaction angle.
+ *
+ * @example
+ * ```ts
+ * // Default cursor
+ * const defaultCursor: TLCursor = {
+ *   type: 'default',
+ *   rotation: 0
+ * }
+ *
+ * // Rotated resize cursor
+ * const rotatedResizeCursor: TLCursor = {
+ *   type: 'resize-corner',
+ *   rotation: Math.PI / 4 // 45 degrees
+ * }
+ *
+ * // Text editing cursor
+ * const textCursor: TLCursor = {
+ *   type: 'text',
+ *   rotation: 0
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface TLCursor {
+	/** The cursor type, determining the visual appearance and interaction mode */
 	type: TLCursorType
+	/** The rotation angle in radians, used for rotated cursors like resize handles */
 	rotation: number
 }
 
-/** @public */
+/**
+ * A validator for TLCursor objects.
+ *
+ * This validator ensures that cursor objects have valid cursor types and
+ * numeric rotation values. It provides runtime validation for cursor
+ * properties used throughout the editor.
+ *
+ * @example
+ * ```ts
+ * import { cursorValidator } from '@tldraw/tlschema'
+ *
+ * // Validate a cursor object
+ * try {
+ *   const validCursor = cursorValidator.validate({
+ *     type: 'pointer',
+ *     rotation: 0.5
+ *   })
+ *   console.log('Valid cursor:', validCursor)
+ * } catch (error) {
+ *   console.error('Invalid cursor:', error.message)
+ * }
+ * ```
+ *
+ * @public
+ */
 export const cursorValidator: T.ObjectValidator<TLCursor> = T.object<TLCursor>({
 	type: cursorTypeValidator,
 	rotation: T.number,