@tldraw/tlschema 4.1.0-next.542f014c3fac → 4.1.0-next.58b63dd1ac80

package/src/bindings/TLArrowBinding.ts

@@ -8,28 +8,96 @@ import { RecordProps } from '../recordsWithProps'
 import { arrowShapeVersions } from '../shapes/TLArrowShape'
 import { TLBaseBinding } from './TLBaseBinding'
 
-/** @public */
+/**
+ * Defines the snapping behavior for elbow-style arrows when binding to shapes.
+ * Controls how the arrow segment aligns with the target shape's geometry.
+ *
+ * @example
+ * ```ts
+ * const binding: TLArrowBindingProps = {
+ *   terminal: 'end',
+ *   normalizedAnchor: { x: 0.5, y: 0.5 },
+ *   isExact: false,
+ *   isPrecise: true,
+ *   snap: 'edge' // Snap to shape edge
+ * }
+ * ```
+ *
+ * @public
+ */
 export const ElbowArrowSnap = T.literalEnum('center', 'edge-point', 'edge', 'none')
-/** @public */
+/**
+ * Type representing the possible elbow arrow snap modes.
+ *
+ * - `'center'` - Snap to the center of the target shape
+ * - `'edge-point'` - Snap to a specific point on the shape's edge
+ * - `'edge'` - Snap to the nearest edge of the shape
+ * - `'none'` - No snapping behavior
+ *
+ * @public
+ */
 export type ElbowArrowSnap = T.TypeOf<typeof ElbowArrowSnap>
 
-/** @public */
+/**
+ * Properties that define how an arrow binds to a target shape.
+ * These properties control the visual and behavioral aspects of the arrow-to-shape connection.
+ *
+ * @example
+ * ```ts
+ * const arrowBindingProps: TLArrowBindingProps = {
+ *   terminal: 'end', // Bind the arrow's end point
+ *   normalizedAnchor: { x: 0.5, y: 0.0 }, // Bind to top center of shape
+ *   isExact: true, // Arrow head enters the shape
+ *   isPrecise: true, // Use exact anchor position
+ *   snap: 'edge' // Snap to shape edge
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface TLArrowBindingProps {
+	/** Which end of the arrow is bound - either 'start' or 'end' */
 	terminal: 'start' | 'end'
+	/**
+	 * Normalized anchor point on the target shape (0,0 = top-left, 1,1 = bottom-right).
+	 * Coordinates are relative to the shape's bounding box.
+	 */
 	normalizedAnchor: VecModel
 	/**
-	 * exact is whether the arrow head 'enters' the bound shape to point directly at the binding
-	 * anchor point
+	 * Whether the arrow head 'enters' the bound shape to point directly at the binding
+	 * anchor point. When true, the arrow head will be positioned inside the target shape.
 	 */
 	isExact: boolean
 	/**
-	 * precise is whether to bind to the normalizedAnchor, or to the middle of the shape
+	 * Whether to bind to the exact normalizedAnchor position, or to the center of the shape.
+	 * When false, the arrow will connect to the shape's center regardless of anchor position.
 	 */
 	isPrecise: boolean
+	/** Snapping behavior for elbow-style arrows */
 	snap: ElbowArrowSnap
 }
 
-/** @public */
+/**
+ * Validation schema for arrow binding properties.
+ * Defines the runtime validation rules for each property in TLArrowBindingProps.
+ *
+ * @example
+ * ```ts
+ * import { arrowBindingProps } from '@tldraw/tlschema'
+ *
+ * // Use in custom shape schema
+ * const customSchema = createTLSchema({
+ *   bindings: {
+ *     arrow: {
+ *       props: arrowBindingProps,
+ *       migrations: arrowBindingMigrations
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @public
+ */
 export const arrowBindingProps: RecordProps<TLArrowBinding> = {
 	terminal: T.literalEnum('start', 'end'),
 	normalizedAnchor: vecModelValidator,
@@ -38,15 +106,69 @@ export const arrowBindingProps: RecordProps<TLArrowBinding> = {
 	snap: ElbowArrowSnap,
 }
 
-/** @public */
+/**
+ * Represents a binding relationship between an arrow shape and another shape.
+ * Arrow bindings allow arrows to connect to and follow other shapes, maintaining
+ * the connection even when shapes are moved or transformed.
+ *
+ * @example
+ * ```ts
+ * const arrowBinding: TLArrowBinding = {
+ *   id: 'binding:abc123',
+ *   typeName: 'binding',
+ *   type: 'arrow',
+ *   fromId: 'shape:arrow1', // The arrow shape
+ *   toId: 'shape:rectangle1', // The target shape
+ *   props: {
+ *     terminal: 'end',
+ *     normalizedAnchor: { x: 0.5, y: 0.5 },
+ *     isExact: false,
+ *     isPrecise: true,
+ *     snap: 'edge'
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLArrowBinding = TLBaseBinding<'arrow', TLArrowBindingProps>
 
-/** @public */
+/**
+ * Version identifiers for arrow binding property migrations.
+ * Each version represents a schema change that requires data migration.
+ *
+ * @example
+ * ```ts
+ * // Check if migration is needed
+ * if (bindingVersion < arrowBindingVersions.AddSnap) {
+ *   // Apply AddSnap migration
+ * }
+ * ```
+ *
+ * @public
+ */
 export const arrowBindingVersions = createBindingPropsMigrationIds('arrow', {
 	AddSnap: 1,
 })
 
-/** @public */
+/**
+ * Migration sequence for arrow binding properties.
+ * Handles schema evolution over time by defining how to migrate data between versions.
+ *
+ * The sequence includes:
+ * - **AddSnap (v1)**: Adds the `snap` property with default value 'none'
+ *
+ * @example
+ * ```ts
+ * import { arrowBindingMigrations } from '@tldraw/tlschema'
+ *
+ * // Apply migrations when loading older data
+ * const migratedBinding = arrowBindingMigrations.migrate(oldBinding)
+ * ```
+ *
+ * @public
+ */
 export const arrowBindingMigrations = createBindingPropsMigrationSequence({
 	sequence: [
 		{ dependsOn: [arrowShapeVersions.ExtractBindings] },

package/src/bindings/TLBaseBinding.ts

@@ -6,20 +6,157 @@ import { TLBindingId } from '../records/TLBinding'
 import { TLShapeId } from '../records/TLShape'
 import { shapeIdValidator } from '../shapes/TLBaseShape'
 
-/** @public */
+/**
+ * Base interface for all binding types in tldraw. Bindings represent relationships
+ * between shapes, such as arrows connecting to other shapes or organizational connections.
+ *
+ * All bindings extend this base interface with specific type and property definitions.
+ * The binding system enables shapes to maintain relationships that persist through
+ * transformations, movements, and other operations.
+ *
+ * @param Type - String literal type identifying the specific binding type (e.g., 'arrow')
+ * @param Props - Object containing binding-specific properties and configuration
+ *
+ * @example
+ * ```ts
+ * // Define a custom binding type
+ * interface MyCustomBinding extends TLBaseBinding<'custom', MyCustomProps> {}
+ *
+ * interface MyCustomProps {
+ *   strength: number
+ *   color: string
+ * }
+ *
+ * // Create a binding instance
+ * const binding: MyCustomBinding = {
+ *   id: 'binding:abc123',
+ *   typeName: 'binding',
+ *   type: 'custom',
+ *   fromId: 'shape:source1',
+ *   toId: 'shape:target1',
+ *   props: {
+ *     strength: 0.8,
+ *     color: 'red'
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface TLBaseBinding<Type extends string, Props extends object>
 	extends BaseRecord<'binding', TLBindingId> {
+	/** The specific type of this binding (e.g., 'arrow', 'custom') */
 	type: Type
+	/** ID of the source shape in this binding relationship */
 	fromId: TLShapeId
+	/** ID of the target shape in this binding relationship */
 	toId: TLShapeId
+	/** Binding-specific properties that define behavior and appearance */
 	props: Props
+	/** User-defined metadata for extending binding functionality */
 	meta: JsonObject
 }
 
-/** @public */
+/**
+ * Validator for binding IDs. Ensures that binding identifiers follow the correct
+ * format and type constraints required by the tldraw schema system.
+ *
+ * Used internally by the schema validation system to verify binding IDs when
+ * records are created or modified. All binding IDs must be prefixed with 'binding:'.
+ *
+ * @example
+ * ```ts
+ * import { bindingIdValidator } from '@tldraw/tlschema'
+ *
+ * // Validate a binding ID
+ * const isValid = bindingIdValidator.isValid('binding:abc123') // true
+ * const isInvalid = bindingIdValidator.isValid('shape:abc123') // false
+ *
+ * // Use in custom validation schema
+ * const customBindingValidator = T.object({
+ *   id: bindingIdValidator,
+ *   // ... other properties
+ * })
+ * ```
+ *
+ * @public
+ */
 export const bindingIdValidator = idValidator<TLBindingId>('binding')
 
-/** @public */
+/**
+ * Creates a runtime validator for a specific binding type. This factory function
+ * generates a complete validation schema for custom bindings that extends TLBaseBinding.
+ *
+ * The validator ensures all binding records conform to the expected structure with
+ * proper type safety and runtime validation. It validates the base binding properties
+ * (id, type, fromId, toId) along with custom props and meta fields.
+ *
+ * @param type - The string literal type identifier for this binding (e.g., 'arrow', 'custom')
+ * @param props - Optional validation schema for binding-specific properties
+ * @param meta - Optional validation schema for metadata fields
+ *
+ * @returns A validator object that can validate complete binding records
+ *
+ * @example
+ * ```ts
+ * import { createBindingValidator } from '@tldraw/tlschema'
+ * import { T } from '@tldraw/validate'
+ *
+ * // Create validator for a custom binding type
+ * const myBindingValidator = createBindingValidator(
+ *   'myBinding',
+ *   {
+ *     strength: T.number,
+ *     color: T.string,
+ *     enabled: T.boolean
+ *   },
+ *   {
+ *     createdAt: T.number,
+ *     author: T.string
+ *   }
+ * )
+ *
+ * // Validate a binding instance
+ * const bindingData = {
+ *   id: 'binding:123',
+ *   typeName: 'binding',
+ *   type: 'myBinding',
+ *   fromId: 'shape:abc',
+ *   toId: 'shape:def',
+ *   props: {
+ *     strength: 0.8,
+ *     color: 'red',
+ *     enabled: true
+ *   },
+ *   meta: {
+ *     createdAt: Date.now(),
+ *     author: 'user123'
+ *   }
+ * }
+ *
+ * const isValid = myBindingValidator.isValid(bindingData) // true
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Simple binding without custom props or meta
+ * const simpleBindingValidator = createBindingValidator('simple')
+ *
+ * // This will use JsonValue validation for props and meta
+ * const binding = {
+ *   id: 'binding:456',
+ *   typeName: 'binding',
+ *   type: 'simple',
+ *   fromId: 'shape:start',
+ *   toId: 'shape:end',
+ *   props: {}, // Any JSON value allowed
+ *   meta: {}   // Any JSON value allowed
+ * }
+ * ```
+ *
+ * @public
+ */
 export function createBindingValidator<
 	Type extends string,
 	Props extends JsonObject,

package/src/createPresenceStateDerivation.test.ts

@@ -0,0 +1,158 @@
+import { atom } from '@tldraw/state'
+import { Store } from '@tldraw/store'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import {
+	createPresenceStateDerivation,
+	getDefaultUserPresence,
+	TLPresenceUserInfo,
+} from './createPresenceStateDerivation'
+import { createTLSchema } from './createTLSchema'
+import { TLINSTANCE_ID } from './records/TLInstance'
+import { TLPageId } from './records/TLPage'
+import { InstancePageStateRecordType } from './records/TLPageState'
+import { TLRecord } from './records/TLRecord'
+import { createIntegrityChecker, TLStoreProps } from './TLStore'
+
+describe('createPresenceStateDerivation', () => {
+	let store: Store<TLRecord, TLStoreProps>
+	let userSignal: ReturnType<typeof atom<TLPresenceUserInfo>>
+
+	beforeEach(() => {
+		const schema = createTLSchema()
+		store = new Store({
+			schema,
+			props: {
+				defaultName: 'Test Store',
+				assets: {
+					upload: vi.fn().mockResolvedValue({ src: 'uploaded-url' }),
+					resolve: vi.fn().mockResolvedValue('resolved-url'),
+					remove: vi.fn().mockResolvedValue(undefined),
+				},
+				onMount: vi.fn(),
+			},
+		})
+
+		// Initialize store with required records
+		const checker = createIntegrityChecker(store)
+		checker()
+
+		userSignal = atom('user', {
+			id: 'user123',
+			name: 'Test User',
+			color: '#007AFF',
+		})
+	})
+
+	afterEach(() => {
+		vi.clearAllMocks()
+	})
+
+	describe('basic functionality', () => {
+		it('should create presence state and be reactive to changes', () => {
+			const derivation = createPresenceStateDerivation(userSignal)
+			const presenceSignal = derivation(store)
+			const presence = presenceSignal.get()
+
+			expect(presence!.userId).toBe('user123')
+			expect(presence!.userName).toBe('Test User')
+			expect(presence!.color).toBe('#007AFF')
+
+			// Update user signal
+			userSignal.set({
+				id: 'user456',
+				name: 'Updated User',
+				color: '#FF6B6B',
+			})
+
+			const updatedPresence = presenceSignal.get()
+			expect(updatedPresence!.userName).toBe('Updated User')
+			expect(updatedPresence!.color).toBe('#FF6B6B')
+		})
+
+		it('should return null when required records are missing', () => {
+			store.remove([TLINSTANCE_ID])
+
+			const derivation = createPresenceStateDerivation(userSignal)
+			expect(derivation(store).get()).toBe(null)
+		})
+	})
+
+	describe('store state integration', () => {
+		it('should be reactive to store changes', () => {
+			const derivation = createPresenceStateDerivation(userSignal)
+			const presenceSignal = derivation(store)
+
+			const pageId = [...store.query.ids('page').get()][0] as TLPageId
+			const pageState = store.get(InstancePageStateRecordType.createId(pageId))!
+			store.put([
+				{
+					...pageState,
+					selectedShapeIds: ['shape:test' as any],
+				},
+			])
+
+			const presence = presenceSignal.get()
+			expect(presence!.selectedShapeIds).toEqual(['shape:test'])
+		})
+	})
+})
+
+describe('getDefaultUserPresence', () => {
+	let store: Store<TLRecord, TLStoreProps>
+
+	beforeEach(() => {
+		const schema = createTLSchema()
+		store = new Store({
+			schema,
+			props: {
+				defaultName: 'Test Store',
+				assets: {
+					upload: vi.fn().mockResolvedValue({ src: 'uploaded-url' }),
+					resolve: vi.fn().mockResolvedValue('resolved-url'),
+					remove: vi.fn().mockResolvedValue(undefined),
+				},
+				onMount: vi.fn(),
+			},
+		})
+
+		// Initialize store with required records
+		const checker = createIntegrityChecker(store)
+		checker()
+	})
+
+	afterEach(() => {
+		vi.clearAllMocks()
+	})
+
+	describe('basic functionality', () => {
+		it('should return presence state with user info and default values', () => {
+			const user: TLPresenceUserInfo = {
+				id: 'test-user',
+				name: 'Test User',
+				color: '#00FF00',
+			}
+
+			const presence = getDefaultUserPresence(store, user)
+
+			expect(presence!.userId).toBe('test-user')
+			expect(presence!.userName).toBe('Test User')
+			expect(presence!.color).toBe('#00FF00')
+		})
+
+		it('should use defaults for missing user fields', () => {
+			const minimalUser: TLPresenceUserInfo = { id: 'minimal' }
+			const presence = getDefaultUserPresence(store, minimalUser)
+
+			expect(presence!.userName).toBe('')
+			expect(presence!.color).toBe('#FF0000')
+		})
+	})
+
+	describe('error conditions', () => {
+		it('should return null when required records are missing', () => {
+			store.remove([TLINSTANCE_ID])
+			const user: TLPresenceUserInfo = { id: 'test' }
+			expect(getDefaultUserPresence(store, user)).toBe(null)
+		})
+	})
+})

package/src/createPresenceStateDerivation.ts

@@ -27,6 +27,29 @@ export interface TLPresenceUserInfo {
 
 /**
  * Creates a derivation that represents the current presence state of the current user.
+ *
+ * This function returns a derivation factory that, when given a store, creates a computed signal
+ * containing the user's current presence state. The presence state includes information like cursor
+ * position, selected shapes, camera position, and user metadata that gets synchronized in
+ * multiplayer scenarios.
+ *
+ * @param $user - A reactive signal containing the user information
+ * @param instanceId - Optional custom instance ID. If not provided, one will be generated based on the store ID
+ * @returns A function that takes a store and returns a computed signal of the user's presence state
+ *
+ * @example
+ * ```ts
+ * import { createPresenceStateDerivation } from '@tldraw/tlschema'
+ * import { atom } from '@tldraw/state'
+ *
+ * const userSignal = atom('user', { id: 'user-123', name: 'Alice', color: '#ff0000' })
+ * const presenceDerivation = createPresenceStateDerivation(userSignal)
+ *
+ * // Use with a store to get reactive presence state
+ * const presenceState = presenceDerivation(store)
+ * console.log(presenceState.get()) // Current user presence or null
+ * ```
+ *
  * @public
  */
 export function createPresenceStateDerivation(
@@ -49,10 +72,56 @@ export function createPresenceStateDerivation(
 	}
 }
 
-/** @public */
+/**
+ * The shape of data used to create a presence record.
+ *
+ * This type represents all the properties needed to construct a TLInstancePresence record.
+ * It includes user information, cursor state, camera position, selected shapes, and other
+ * presence-related data that gets synchronized across multiplayer clients.
+ *
+ * @public
+ */
 export type TLPresenceStateInfo = Parameters<(typeof InstancePresenceRecordType)['create']>[0]
 
-/** @public */
+/**
+ * Creates default presence state information for a user based on the current store state.
+ *
+ * This function extracts the current state from various store records (instance, page state,
+ * camera, pointer) and combines them with user information to create a complete presence
+ * state object. This is commonly used as a starting point for custom presence implementations.
+ *
+ * @param store - The tldraw store containing the current editor state
+ * @param user - The user information to include in the presence state
+ * @returns The default presence state info, or null if required store records are missing
+ *
+ * @example
+ * ```ts
+ * import { getDefaultUserPresence } from '@tldraw/tlschema'
+ *
+ * const user = { id: 'user-123', name: 'Alice', color: '#ff0000' }
+ * const presenceInfo = getDefaultUserPresence(store, user)
+ *
+ * if (presenceInfo) {
+ *   console.log('Current cursor:', presenceInfo.cursor)
+ *   console.log('Selected shapes:', presenceInfo.selectedShapeIds)
+ *   console.log('Camera position:', presenceInfo.camera)
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Common pattern: customize default presence
+ * const customPresence = {
+ *   ...getDefaultUserPresence(store, user),
+ *   // Remove camera for privacy
+ *   camera: undefined,
+ *   // Add custom metadata
+ *   customField: 'my-data'
+ * }
+ * ```
+ *
+ * @public
+ */
 export function getDefaultUserPresence(store: TLStore, user: TLPresenceUserInfo) {
 	const instance = store.get(TLINSTANCE_ID)
 	const pageState = store.get(InstancePageStateRecordType.createId(instance?.currentPageId))