@tldraw/tlschema 5.2.0-next.b91d4a4551c9 → 5.2.0-next.cd4a35fc06d5

package/DOCS.md

@@ -0,0 +1,682 @@
+# @tldraw/tlschema
+
+The schema package defines the type system, data structures, validation, and migrations for tldraw's persisted data. It provides a complete, type-safe, and version-aware data model that powers the tldraw editor.
+
+## 1. Introduction
+
+**@tldraw/tlschema** is the foundational package that defines how tldraw stores and manages data. It contains:
+
+- **Record types** for all persisted data (shapes, assets, pages, user state)
+- **Validation schemas** that ensure data integrity at runtime
+- **Migration sequences** that handle data evolution over time
+- **Style properties** that enable consistent styling across shapes
+
+You'll use this package when creating custom shapes, defining your own data schemas, or when you need to work with tldraw's data structures directly.
+
+## 2. Core Concepts
+
+### Schemas: The Foundation
+
+A **schema** defines the structure of your tldraw store. It specifies what types of records can exist, how they're validated, and how they evolve over time.
+
+```ts
+import { createTLSchema, defaultShapeSchemas } from '@tldraw/tlschema'
+
+// Create a schema with default shapes
+const schema = createTLSchema({
+	shapes: defaultShapeSchemas,
+})
+```
+
+### Records: The Data Units
+
+**Records** are the individual pieces of data stored in tldraw. Every record has a type, an ID, and properties specific to that type:
+
+```ts
+import { TLShape, TLPage, TLAsset } from '@tldraw/tlschema'
+
+// All records extend BaseRecord
+const shape: TLShape = {
+	id: 'shape:abc123',
+	typeName: 'shape',
+	type: 'geo',
+	x: 100,
+	y: 200,
+	rotation: 0,
+	// ... other properties
+}
+```
+
+### Style Properties: Shared Styling
+
+**Style properties** are special properties that can be applied across multiple shapes and persist for new shape creation:
+
+```ts
+import { StyleProp } from '@tldraw/tlschema'
+import { T } from '@tldraw/validate'
+
+// Define a custom style property
+const MyCustomStyle = StyleProp.define('myapp:custom', {
+	defaultValue: 'default',
+	type: T.string,
+})
+```
+
+## 3. Basic Usage
+
+### Creating a Custom Schema
+
+You create schemas by combining shape configurations, bindings, and migrations:
+
+```ts
+import { createTLSchema, defaultShapeSchemas, defaultBindingSchemas } from '@tldraw/tlschema'
+
+const schema = createTLSchema({
+	shapes: {
+		...defaultShapeSchemas,
+		// Add custom shapes here
+	},
+	bindings: defaultBindingSchemas,
+})
+```
+
+### Working with Shape Records
+
+Shape records are the most common type you'll work with. Every shape extends `TLBaseShape`:
+
+```ts
+import { createShapeValidator } from '@tldraw/tlschema'
+import { T } from '@tldraw/validate'
+
+const CUSTOM_TYPE = 'custom'
+
+// Define a custom shape type
+declare module '@tldraw/tlschema' {
+	export interface TLGlobalShapePropsMap {
+		[CUSTOM_TYPE]: MyCustomShapeProps
+	}
+}
+
+interface MyCustomShapeProps {
+	width: number
+	height: number
+	color: string
+}
+
+type MyCustomShape = TLShape<typeof CUSTOM_TYPE>
+
+// Create validation for your shape
+const customShapeValidator = createShapeValidator(CUSTOM_TYPE, {
+	width: T.number,
+	height: T.number,
+	color: T.string,
+})
+```
+
+### Integrating with Store
+
+Once you have a schema, you use it to create a store:
+
+```ts
+import { Store } from '@tldraw/store'
+import { TLStoreProps } from '@tldraw/tlschema'
+
+const store = new Store({
+	schema,
+	props: {
+		defaultName: 'My Drawing',
+		assets: myAssetStore, // Your asset storage implementation
+	},
+})
+```
+
+## 4. Advanced Topics
+
+### Creating Custom Shapes
+
+When creating custom shapes, follow this pattern for complete integration:
+
+```ts
+import {
+	createShapeValidator,
+	createShapePropsMigrationSequence,
+	RecordProps,
+} from '@tldraw/tlschema'
+import { DefaultColorStyle } from '@tldraw/tlschema'
+
+const MY_SHAPE_TYPE = 'myshape'
+
+// 1. Define the shape
+declare module '@tldraw/tlschema' {
+	export interface TLGlobalShapePropsMap {
+		[MY_SHAPE_TYPE]: MyShapeProps
+	}
+}
+
+interface MyShapeProps {
+	color: typeof DefaultColorStyle // Use existing style
+	width: number
+	height: number
+	customData: string
+}
+
+type MyShape = TLShape<typeof MY_SHAPE_TYPE>
+
+// 2. Create props validation
+const myShapeProps: RecordProps<MyShape> = {
+	color: DefaultColorStyle,
+	width: T.number,
+	height: T.number,
+	customData: T.string,
+}
+
+// 3. Define migrations for schema evolution
+const myShapeMigrations = createShapePropsMigrationSequence({
+	sequenceId: 'com.myapp.shape.myshape',
+	sequence: [
+		{
+			id: 'com.myapp.shape.myshape/1.0.0',
+			up: (props) => props, // Initial version
+			down: (props) => props,
+		},
+	],
+})
+
+// 4. Add to schema
+const schema = createTLSchema({
+	shapes: {
+		...defaultShapeSchemas,
+		myshape: {
+			props: myShapeProps,
+			migrations: myShapeMigrations,
+		},
+	},
+})
+```
+
+### Custom Style Properties
+
+Style properties enable consistent styling across shapes and remember the last used value:
+
+```ts
+import { StyleProp, EnumStyleProp } from '@tldraw/tlschema'
+import { T } from '@tldraw/validate'
+
+// Free-form style property
+const MyWidthStyle = StyleProp.define('myapp:width', {
+	defaultValue: 2,
+	type: T.number,
+})
+
+// Enum-based style property
+const MyPatternStyle = StyleProp.defineEnum('myapp:pattern', {
+	defaultValue: 'solid',
+	values: ['solid', 'dashed', 'dotted'],
+})
+
+// Use in shape props
+interface MyShapeProps {
+	width: typeof MyWidthStyle
+	pattern: typeof MyPatternStyle
+	// other props...
+}
+```
+
+### Asset Management
+
+Assets represent external resources like images, videos, or bookmarks:
+
+```ts
+import { TLImageAsset, TLAssetStore } from '@tldraw/tlschema'
+
+// Implement asset storage
+const assetStore: TLAssetStore = {
+	async upload(asset, file) {
+		// Upload file to your storage service
+		const src = await uploadToStorage(file)
+		return { src }
+	},
+
+	async resolve(asset, context) {
+		// Resolve asset URL for rendering
+		return asset.props.src
+	},
+
+	async remove(assetIds) {
+		// Clean up removed assets
+		await deleteFromStorage(assetIds)
+	},
+}
+```
+
+### Migration Strategies
+
+Migrations handle schema evolution as your application develops:
+
+```ts
+import { createShapePropsMigrationSequence } from '@tldraw/tlschema'
+
+const migrations = createShapePropsMigrationSequence({
+	sequenceId: 'com.myapp.shape.custom',
+	sequence: [
+		{
+			id: 'com.myapp.shape.custom/1.1.0',
+			up: (props) => {
+				// Add new property with default value
+				return { ...props, newProperty: 'default' }
+			},
+			down: ({ newProperty, ...props }) => {
+				// Remove property for backward compatibility
+				return props
+			},
+		},
+		{
+			id: 'com.myapp.shape.custom/1.2.0',
+			up: (props) => {
+				// Rename property
+				return {
+					...props,
+					renamedProperty: props.oldProperty,
+					oldProperty: undefined,
+				}
+			},
+			down: (props) => {
+				return {
+					...props,
+					oldProperty: props.renamedProperty,
+					renamedProperty: undefined,
+				}
+			},
+		},
+	],
+})
+```
+
+## 5. Built-in Shape Types
+
+### Default Shapes
+
+tldraw includes several built-in shape types:
+
+```ts
+import {
+	TLGeoShape, // Rectangles, ellipses, triangles, etc.
+	TLTextShape, // Text with rich formatting
+	TLDrawShape, // Freehand drawing paths
+	TLArrowShape, // Arrows with optional binding to shapes
+	TLLineShape, // Multi-point lines and splines
+	TLImageShape, // Raster images
+	TLVideoShape, // Video files
+	TLNoteShape, // Sticky notes
+	TLBookmarkShape, // Website bookmarks
+	TLEmbedShape, // Embedded content (YouTube, Figma, etc.)
+	TLFrameShape, // Frames for grouping content
+	TLGroupShape, // Groups for organizing shapes
+	TLHighlightShape, // Highlighting tool strokes
+} from '@tldraw/tlschema'
+```
+
+### Shape Properties
+
+All shapes share common base properties from `TLBaseShape`:
+
+```ts
+interface TLBaseShape<Type, Props> {
+	id: TLShapeId
+	type: Type
+	x: number // Position X
+	y: number // Position Y
+	rotation: number // Rotation in radians
+	index: IndexKey // Fractional index for ordering
+	parentId: TLParentId // Parent page or shape
+	isLocked: boolean // Whether shape can be selected
+	opacity: TLOpacityType // Transparency (0-1)
+	props: Props // Shape-specific properties
+	meta: JsonObject // User-defined metadata
+}
+```
+
+### Geo Shapes
+
+Geometric shapes support various styles and configurations:
+
+```ts
+import { TLGeoShape, GeoShapeGeoStyle } from '@tldraw/tlschema'
+
+// Geo shapes can be rectangles, ellipses, triangles, etc.
+const geoShape: TLGeoShape = {
+	// ... base properties
+	props: {
+		geo: GeoShapeGeoStyle, // 'rectangle', 'ellipse', 'triangle', etc.
+		w: 100, // Width
+		h: 80, // Height
+		color: 'blue', // Color style
+		fill: 'solid', // Fill style
+		dash: 'solid', // Dash style
+		size: 'm', // Size style
+		richText: null, // Optional text content
+	},
+}
+```
+
+## 6. Validation and Type Safety
+
+### Runtime Validation
+
+All records are validated at runtime to ensure data integrity:
+
+```ts
+import { T } from '@tldraw/validate'
+import { createShapeValidator } from '@tldraw/tlschema'
+
+// Validation happens automatically when records enter the store
+const validator = createShapeValidator('myshape', {
+	width: T.number.check((n) => n > 0), // Custom validation
+	height: T.number.check((n) => n > 0),
+	color: T.string,
+})
+```
+
+### Error Handling
+
+When validation fails, you can handle errors gracefully:
+
+```ts
+try {
+	store.put([invalidRecord])
+} catch (error) {
+	if (error instanceof ValidationError) {
+		console.log('Validation failed:', error.message)
+		// Handle validation error appropriately
+	}
+}
+```
+
+### Type-Safe IDs
+
+Record IDs are strongly typed to prevent mixing different record types:
+
+```ts
+import { TLShapeId, TLPageId, createShapeId } from '@tldraw/tlschema'
+
+// IDs are branded types - compiler prevents mixing them up
+const shapeId: TLShapeId = createShapeId()
+const pageId: TLPageId = 'page:123' // TypeScript error if you use wrong format
+```
+
+## 7. Integration with @tldraw/store
+
+### Store Configuration
+
+The schema integrates with the store system to provide reactive data management:
+
+```ts
+import { Store } from '@tldraw/store'
+import { TLStoreProps, createTLSchema } from '@tldraw/tlschema'
+
+const schema = createTLSchema()
+const store = new Store({
+	schema,
+	props: {
+		defaultName: 'Untitled',
+		assets: assetStore,
+		onMount: (editor) => {
+			// Initialize when editor mounts
+			console.log('Editor mounted with store')
+		},
+	},
+})
+```
+
+### Reactive Queries
+
+The store provides reactive access to records:
+
+```ts
+import { track } from '@tldraw/state'
+
+// This function will re-run when shapes change
+const ShapeCounter = track(() => {
+	const shapes = store.query.records('shape').get()
+	return `Total shapes: ${shapes.length}`
+})
+```
+
+## 8. Performance Considerations
+
+### Validation Optimization
+
+- Use `validateUsingKnownGoodVersion()` when you know data is already valid
+- Minimize validation in hot paths during user interactions
+- Consider validation levels (development vs production)
+
+### Memory Management
+
+- Style properties are shared across shapes to reduce memory usage
+- Records use immutable structures to prevent accidental mutations
+- `devFreeze()` helps catch mutation bugs in development
+
+### Migration Performance
+
+- Group related changes into single migration steps
+- Test migration performance with realistic data sizes
+- Use migration sequence IDs to optimize dependency resolution
+
+## 9. Debugging
+
+### Understanding Schema Structure
+
+You can inspect your schema to understand its configuration:
+
+```ts
+const schema = createTLSchema()
+
+// Examine record types
+console.log('Record types:', Object.keys(schema.types))
+
+// Check validation for specific record type
+const shapeValidator = schema.types.shape
+console.log('Shape validator:', shapeValidator)
+```
+
+### Migration Debugging
+
+When migrations fail, examine the migration sequence:
+
+```ts
+// Check migration history
+const migrations = schema.sortedMigrations
+console.log(
+	'Migration sequence:',
+	migrations.map((m) => m.id)
+)
+
+// Test individual migrations
+try {
+	const migrated = migrator.migrateStoreSnapshot({
+		schema: oldSchema,
+		store: snapshot,
+	})
+	console.log('Migration successful')
+} catch (error) {
+	console.error('Migration failed:', error)
+}
+```
+
+### Validation Errors
+
+When records fail validation, examine the validation path:
+
+```ts
+import { T } from '@tldraw/validate'
+
+try {
+	shapeValidator.validate(invalidShape)
+} catch (error) {
+	console.log('Validation path:', error.path)
+	console.log('Validation message:', error.message)
+	console.log('Invalid value:', error.value)
+}
+```
+
+## 10. Common Patterns
+
+### Shape with Asset References
+
+Many shapes reference assets for their content:
+
+```ts
+interface MediaShapeProps {
+	assetId: TLAssetId | null
+	width: number
+	height: number
+	crop?: TLShapeCrop // Optional cropping info
+}
+
+// Usage pattern
+const imageShape: TLImageShape = {
+	// ... base properties
+	props: {
+		assetId: 'asset:image123',
+		w: 200,
+		h: 150,
+		crop: {
+			topLeft: { x: 0, y: 0 },
+			bottomRight: { x: 1, y: 1 },
+		},
+	},
+}
+```
+
+### Binding Relationships
+
+Arrows can bind to other shapes:
+
+```ts
+import { TLArrowBinding } from '@tldraw/tlschema'
+
+const arrowBinding: TLArrowBinding = {
+	id: 'binding:abc123',
+	typeName: 'binding',
+	type: 'arrow',
+	fromId: 'shape:arrow1', // Arrow shape ID
+	toId: 'shape:rectangle1', // Target shape ID
+	props: {
+		terminal: 'end', // 'start' or 'end'
+		normalizedAnchor: { x: 0.5, y: 0.5 }, // Position on target
+		isExact: false, // Whether position is exact
+		isPrecise: true, // Whether binding is precise
+	},
+}
+```
+
+### Rich Text Content
+
+Shapes can contain formatted text:
+
+```ts
+import { TLRichText, toRichText } from '@tldraw/tlschema'
+
+const richText: TLRichText = toRichText('Hello **bold** text')
+
+const textShape: TLTextShape = {
+	// ... base properties
+	props: {
+		color: 'black',
+		size: 'm',
+		font: 'draw',
+		textAlign: 'start',
+		richText: richText,
+		autoSize: true,
+		scale: 1,
+	},
+}
+```
+
+## 11. Best Practices
+
+### Schema Design
+
+- **Start simple** - Begin with minimal shape properties and add complexity gradually
+- **Use existing styles** - Leverage built-in style properties before creating custom ones
+- **Plan for evolution** - Design your schema with migrations in mind
+- **Validate thoroughly** - Include validation for edge cases and invalid states
+
+### Migration Strategy
+
+- **Version incrementally** - Use semantic versioning in migration IDs
+- **Test both directions** - Ensure up and down migrations work correctly
+- **Handle failures gracefully** - Provide fallbacks when migrations fail
+- **Document breaking changes** - Clearly communicate migration requirements
+
+### Performance Optimization
+
+- **Minimize validation overhead** - Use efficient validators for frequently accessed properties
+- **Batch related changes** - Group property updates to reduce reactive updates
+- **Use appropriate record scopes** - Choose correct scope (document/session/presence) for data
+- **Optimize asset handling** - Implement efficient asset storage and resolution
+
+### Error Handling
+
+- **Validate early** - Catch validation errors as close to the source as possible
+- **Provide clear messages** - Use descriptive error messages for debugging
+- **Handle partial failures** - Design systems that can recover from individual record failures
+- **Log strategically** - Include enough context for debugging without overwhelming logs
+
+## 12. Extension Points
+
+### Custom Shapes
+
+Extend the built-in shape system:
+
+```ts
+// Add custom shapes to default schemas
+const customSchema = createTLSchema({
+	shapes: {
+		...defaultShapeSchemas,
+		myCustomShape: customShapeConfig,
+	},
+})
+```
+
+### Custom Bindings
+
+Create new types of shape relationships:
+
+```ts
+const CUSTOM_TYPE = 'custom'
+
+// Define custom binding types
+declare module '@tldraw/tlschema' {
+	export interface TLGlobalBindingPropsMap {
+		[CUSTOM_TYPE]: MyBindingProps
+	}
+}
+
+type MyCustomBinding = TLBinding<typeof CUSTOM_TYPE>
+
+const customBindingConfig = {
+	props: myBindingProps,
+	migrations: myBindingMigrations,
+}
+```
+
+### Asset Storage
+
+Implement custom asset storage backends:
+
+```ts
+const customAssetStore: TLAssetStore = {
+	async upload(asset, file) {
+		return await myCloudStorage.upload(file)
+	},
+	async resolve(asset, context) {
+		return await myCloudStorage.getUrl(asset.props.src, context)
+	},
+	async remove(assetIds) {
+		await Promise.all(assetIds.map((id) => myCloudStorage.delete(id)))
+	},
+}
+```
+
+The tlschema package provides a robust foundation for building applications with tldraw. By following these patterns and understanding the core concepts, you can create custom shapes, manage data effectively, and build experiences that scale with your users' needs.

package/README.md

@@ -2,6 +2,10 @@
 
 Type definitions, schema migrations, and other type metadata for the tldraw editor's default persisted data.
 
+## Documentation
+
+A `DOCS.md` file is included alongside this README in the published package, with detailed API documentation and usage examples.
+
 ## Records
 
 There are three main kinds of types:
@@ -80,7 +84,7 @@ You can find tldraw on npm [here](https://www.npmjs.com/package/@tldraw/tldraw?a
 
 ## Contribution
 
-Please see our [contributing guide](https://github.com/tldraw/tldraw/blob/main/CONTRIBUTING.md). Found a bug? Please [submit an issue](https://github.com/tldraw/tldraw/issues/new).
+Found a bug? Please [submit an issue](https://github.com/tldraw/tldraw/issues/new).
 
 ## Community
 

package/dist-cjs/index.js

@@ -205,7 +205,7 @@ var import_translations = require("./translations/translations");
 var import_b64Vecs = require("./misc/b64Vecs");
 (0, import_utils.registerTldrawLibraryVersion)(
   "@tldraw/tlschema",
-  "5.2.0-next.b91d4a4551c9",
+  "5.2.0-next.cd4a35fc06d5",
   "cjs"
 );
 //# sourceMappingURL=index.js.map

package/dist-esm/index.mjs

@@ -198,7 +198,7 @@ import {
 } from "./translations/translations.mjs";
 registerTldrawLibraryVersion(
   "@tldraw/tlschema",
-  "5.2.0-next.b91d4a4551c9",
+  "5.2.0-next.cd4a35fc06d5",
   "esm"
 );
 import { b64Vecs } from "./misc/b64Vecs.mjs";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tldraw/tlschema",
   "description": "tldraw infinite canvas SDK (schema).",
-  "version": "5.2.0-next.b91d4a4551c9",
+  "version": "5.2.0-next.cd4a35fc06d5",
   "author": {
     "name": "tldraw Inc.",
     "email": "hello@tldraw.com"
@@ -29,7 +29,8 @@
   "files": [
     "dist-esm",
     "dist-cjs",
-    "src"
+    "src",
+    "DOCS.md"
   ],
   "scripts": {
     "test-ci": "yarn run -T vitest run --passWithNoTests",
@@ -47,13 +48,13 @@
     "kleur": "^4.1.5",
     "lazyrepo": "0.0.0-alpha.27",
     "react": "^19.2.1",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.7"
   },
   "dependencies": {
-    "@tldraw/state": "5.2.0-next.b91d4a4551c9",
-    "@tldraw/store": "5.2.0-next.b91d4a4551c9",
-    "@tldraw/utils": "5.2.0-next.b91d4a4551c9",
-    "@tldraw/validate": "5.2.0-next.b91d4a4551c9"
+    "@tldraw/state": "5.2.0-next.cd4a35fc06d5",
+    "@tldraw/store": "5.2.0-next.cd4a35fc06d5",
+    "@tldraw/utils": "5.2.0-next.cd4a35fc06d5",
+    "@tldraw/validate": "5.2.0-next.cd4a35fc06d5"
   },
   "peerDependencies": {
     "react": "^18.2.0 || ^19.2.1",