@tldraw/tlschema 4.1.0-next.542f014c3fac → 4.1.0-next.74327a60f18a

package/src/misc/TLHandle.ts

@@ -2,30 +2,110 @@ import { IndexKey } from '@tldraw/utils'
 import { SetValue } from '../util-types'
 
 /**
- * The handle types used by tldraw's default shapes.
+ * All available handle types used by shapes in the tldraw editor.
  *
- * @public */
+ * Handles are interactive control points on shapes that allow users to
+ * modify the shape's geometry. Different handle types serve different purposes:
+ *
+ * - `vertex`: A control point that defines a vertex of the shape
+ * - `virtual`: A handle that exists between vertices for adding new points
+ * - `create`: A handle for creating new geometry (like extending a line)
+ * - `clone`: A handle for duplicating or cloning shape elements
+ *
+ * @example
+ * ```ts
+ * // Check if a handle type is valid
+ * if (TL_HANDLE_TYPES.has('vertex')) {
+ *   console.log('Valid handle type')
+ * }
+ *
+ * // Get all available handle types
+ * const allHandleTypes = Array.from(TL_HANDLE_TYPES)
+ * ```
+ *
+ * @public
+ */
 export const TL_HANDLE_TYPES = new Set(['vertex', 'virtual', 'create', 'clone'] as const)
 
 /**
- * A type for the handle types used by tldraw's default shapes.
+ * A union type representing all available handle types.
+ *
+ * Handle types determine how a handle behaves when interacted with and
+ * what kind of shape modification it enables.
  *
- * @public */
+ * @example
+ * ```ts
+ * const vertexHandle: TLHandleType = 'vertex'
+ * const virtualHandle: TLHandleType = 'virtual'
+ * const createHandle: TLHandleType = 'create'
+ * const cloneHandle: TLHandleType = 'clone'
+ * ```
+ *
+ * @public
+ */
 export type TLHandleType = SetValue<typeof TL_HANDLE_TYPES>
 
 /**
- * A base interface for a shape's handles.
+ * A handle object representing an interactive control point on a shape.
+ *
+ * Handles allow users to manipulate shape geometry by dragging control points.
+ * Each handle has a position, type, and various properties that control its
+ * behavior during interactions.
+ *
+ * @example
+ * ```ts
+ * // A vertex handle for a line endpoint
+ * const lineEndHandle: TLHandle = {
+ *   id: 'end',
+ *   label: 'End point',
+ *   type: 'vertex',
+ *   canSnap: true,
+ *   index: 'a1',
+ *   x: 100,
+ *   y: 50
+ * }
+ *
+ * // A virtual handle for adding new points
+ * const virtualHandle: TLHandle = {
+ *   id: 'virtual-1',
+ *   type: 'virtual',
+ *   canSnap: false,
+ *   index: 'a1V',
+ *   x: 75,
+ *   y: 25
+ * }
+ *
+ * // A create handle for extending geometry
+ * const createHandle: TLHandle = {
+ *   id: 'create',
+ *   type: 'create',
+ *   canSnap: true,
+ *   index: 'a2',
+ *   x: 200,
+ *   y: 100
+ * }
+ * ```
  *
  * @public
  */
 export interface TLHandle {
-	/** A unique identifier for the handle. */
+	/** A unique identifier for the handle within the shape */
 	id: string
+	/** Optional human-readable label for the handle */
 	// TODO(mime): this needs to be required.
 	label?: string
+	/** The type of handle, determining its behavior and interaction mode */
 	type: TLHandleType
+	/**
+	 * @deprecated Use `snapType` instead. Whether this handle should snap to other geometry during interactions.
+	 */
 	canSnap?: boolean
+	/** The type of snap to use for this handle */
+	snapType?: 'point' | 'align'
+	/** The fractional index used for ordering handles */
 	index: IndexKey
+	/** The x-coordinate of the handle in the shape's local coordinate system */
 	x: number
+	/** The y-coordinate of the handle in the shape's local coordinate system */
 	y: number
 }

package/src/misc/TLOpacity.ts

@@ -1,9 +1,58 @@
 import { T } from '@tldraw/validate'
 
-/** @public */
+/**
+ * A type representing opacity values in tldraw.
+ *
+ * Opacity values are numbers between 0 and 1, where 0 is fully transparent
+ * and 1 is fully opaque. This type is used throughout the editor to control
+ * the transparency of shapes, UI elements, and other visual components.
+ *
+ * @example
+ * ```ts
+ * const fullyOpaque: TLOpacityType = 1.0
+ * const halfTransparent: TLOpacityType = 0.5
+ * const fullyTransparent: TLOpacityType = 0.0
+ * const quarterOpaque: TLOpacityType = 0.25
+ * ```
+ *
+ * @public
+ */
 export type TLOpacityType = number
 
-/** @public */
+/**
+ * A validator for opacity values.
+ *
+ * This validator ensures that opacity values are numbers between 0 and 1 (inclusive).
+ * Values outside this range will cause a validation error. The validator provides
+ * runtime type checking for opacity properties throughout the editor.
+ *
+ * @param n - The number to validate as an opacity value
+ * @throws T.ValidationError When the value is not between 0 and 1
+ *
+ * @example
+ * ```ts
+ * import { opacityValidator } from '@tldraw/tlschema'
+ *
+ * // Valid opacity values
+ * try {
+ *   const validOpacity1 = opacityValidator.validate(0.5) // ✓
+ *   const validOpacity2 = opacityValidator.validate(1.0) // ✓
+ *   const validOpacity3 = opacityValidator.validate(0.0) // ✓
+ * } catch (error) {
+ *   console.error('Validation failed:', error.message)
+ * }
+ *
+ * // Invalid opacity values
+ * try {
+ *   opacityValidator.validate(-0.1) // ✗ Throws error
+ *   opacityValidator.validate(1.5)  // ✗ Throws error
+ * } catch (error) {
+ *   console.error('Invalid opacity:', error.message)
+ * }
+ * ```
+ *
+ * @public
+ */
 export const opacityValidator = T.number.check((n) => {
 	if (n < 0 || n > 1) {
 		throw new T.ValidationError('Opacity must be between 0 and 1')

package/src/misc/TLRichText.ts

@@ -1,12 +1,65 @@
 import { T } from '@tldraw/validate'
 
-/** @public */
+/**
+ * Validator for TLRichText objects that ensures they have the correct structure
+ * for document-based rich text content. Validates a document with a type field
+ * and an array of content blocks.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const richText = { type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Hello' }] }] }
+ * const isValid = richTextValidator.check(richText) // true
+ * ```
+ */
 export const richTextValidator = T.object({ type: T.string, content: T.arrayOf(T.unknown) })
 
-/** @public */
+/**
+ * Type representing rich text content in tldraw. Rich text follows a document-based
+ * structure with a root document containing an array of content blocks (paragraphs,
+ * text nodes, etc.). This enables formatted text with support for multiple paragraphs,
+ * styling, and other rich content.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const richText: TLRichText = {
+ *   type: 'doc',
+ *   content: [
+ *     {
+ *       type: 'paragraph',
+ *       content: [{ type: 'text', text: 'Hello world!' }]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
 export type TLRichText = T.TypeOf<typeof richTextValidator>
 
-/** @public */
+/**
+ * Converts a plain text string into a TLRichText object. Each line of the input
+ * text becomes a separate paragraph in the rich text document. Empty lines are
+ * preserved as empty paragraphs to maintain the original text structure.
+ *
+ * @param text - The plain text string to convert to rich text
+ * @returns A TLRichText object with the text content structured as paragraphs
+ * @public
+ * @example
+ * ```ts
+ * const richText = toRichText('Hello\nWorld')
+ * // Returns:
+ * // {
+ * //   type: 'doc',
+ * //   content: [
+ * //     { type: 'paragraph', content: [{ type: 'text', text: 'Hello' }] },
+ * //     { type: 'paragraph', content: [{ type: 'text', text: 'World' }] }
+ * //   ]
+ * // }
+ *
+ * const emptyLine = toRichText('Line 1\n\nLine 3')
+ * // Creates three paragraphs, with the middle one being empty
+ * ```
+ */
 export function toRichText(text: string): TLRichText {
 	const lines = text.split('\n')
 	const content = lines.map((text) => {

package/src/misc/TLScribble.ts

@@ -4,28 +4,128 @@ import { TLCanvasUiColor, canvasUiColorTypeValidator } from './TLColor'
 import { VecModel, vecModelValidator } from './geometry-types'
 
 /**
- * The scribble states used by tldraw.
+ * All available scribble states used by the tldraw drawing system.
  *
- *  @public */
+ * Scribble states represent the different phases of a drawing stroke:
+ *
+ * - `starting`: The scribble is being initiated
+ * - `paused`: The scribble is temporarily paused
+ * - `active`: The scribble is actively being drawn
+ * - `stopping`: The scribble is being finished
+ *
+ * These states help manage the drawing lifecycle and apply appropriate
+ * visual effects during different phases of the stroke.
+ *
+ * @example
+ * ```ts
+ * // Check if a scribble state is valid
+ * if (TL_SCRIBBLE_STATES.has('active')) {
+ *   console.log('Valid scribble state')
+ * }
+ *
+ * // Get all available scribble states
+ * const allStates = Array.from(TL_SCRIBBLE_STATES)
+ * ```
+ *
+ * @public
+ */
 export const TL_SCRIBBLE_STATES = new Set(['starting', 'paused', 'active', 'stopping'] as const)
 
 /**
- * A type for the scribble used by tldraw.
+ * A scribble object representing a drawing stroke in tldraw.
+ *
+ * Scribbles are temporary drawing strokes that appear during freehand drawing
+ * operations. They provide visual feedback as the user draws and can be styled
+ * with various properties like size, color, and effects.
+ *
+ * @example
+ * ```ts
+ * // A basic scribble stroke
+ * const scribble: TLScribble = {
+ *   id: 'scribble-123',
+ *   points: [
+ *     { x: 0, y: 0, z: 0.5 },
+ *     { x: 10, y: 5, z: 0.7 },
+ *     { x: 20, y: 10, z: 0.6 }
+ *   ],
+ *   size: 4,
+ *   color: 'black',
+ *   opacity: 0.8,
+ *   state: 'active',
+ *   delay: 0,
+ *   shrink: 0.1,
+ *   taper: true
+ * }
  *
- * @public */
+ * // A laser pointer scribble
+ * const laserScribble: TLScribble = {
+ *   id: 'laser-pointer',
+ *   points: [{ x: 50, y: 50, z: 1.0 }],
+ *   size: 8,
+ *   color: 'laser',
+ *   opacity: 1.0,
+ *   state: 'active',
+ *   delay: 100,
+ *   shrink: 0,
+ *   taper: false
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface TLScribble {
+	/** Unique identifier for the scribble */
 	id: string
+	/** Array of points that make up the scribble path */
 	points: VecModel[]
+	/** The brush size/width of the scribble stroke */
 	size: number
+	/** The color of the scribble using canvas UI color types */
 	color: TLCanvasUiColor
+	/** The opacity of the scribble (0-1) */
 	opacity: number
+	/** The current state of the scribble drawing */
 	state: SetValue<typeof TL_SCRIBBLE_STATES>
+	/** Time delay in milliseconds for animation effects */
 	delay: number
+	/** Amount the stroke should shrink over time (0-1) */
 	shrink: number
+	/** Whether the stroke should taper at the ends */
 	taper: boolean
 }
 
-/** @public */
+/**
+ * A validator for TLScribble objects.
+ *
+ * This validator ensures that scribble objects have all required properties
+ * with valid types and values. It validates the points array, size constraints,
+ * color types, and state values according to the scribble system requirements.
+ *
+ * @example
+ * ```ts
+ * import { scribbleValidator } from '@tldraw/tlschema'
+ *
+ * // Validate a scribble object
+ * try {
+ *   const validScribble = scribbleValidator.validate({
+ *     id: 'scribble-1',
+ *     points: [{ x: 0, y: 0, z: 1 }, { x: 10, y: 10, z: 1 }],
+ *     size: 3,
+ *     color: 'black',
+ *     opacity: 0.8,
+ *     state: 'active',
+ *     delay: 0,
+ *     shrink: 0.05,
+ *     taper: true
+ *   })
+ *   console.log('Valid scribble:', validScribble)
+ * } catch (error) {
+ *   console.error('Invalid scribble:', error.message)
+ * }
+ * ```
+ *
+ * @public
+ */
 export const scribbleValidator: T.ObjectValidator<TLScribble> = T.object({
 	id: T.string,
 	points: T.arrayOf(vecModelValidator),

package/src/misc/geometry-types.ts

@@ -21,14 +21,42 @@ export interface VecModel {
 	z?: number
 }
 
-/** @public */
+/**
+ * Validator for VecModel objects that ensures they have numeric x and y coordinates,
+ * with an optional z coordinate for 3D vectors. Used throughout the schema to
+ * validate point and vector data structures.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const vector2D = { x: 10, y: 20 }
+ * const isValid = vecModelValidator.check(vector2D) // true
+ *
+ * const vector3D = { x: 10, y: 20, z: 30 }
+ * const isValid3D = vecModelValidator.check(vector3D) // true
+ * ```
+ */
 export const vecModelValidator: T.ObjectValidator<VecModel> = T.object({
 	x: T.number,
 	y: T.number,
 	z: T.number.optional(),
 })
 
-/** @public */
+/**
+ * Validator for BoxModel objects that ensures they have numeric x, y coordinates
+ * for position and w, h values for width and height. Used throughout the schema
+ * to validate bounding box and rectangular area data structures.
+ *
+ * @public
+ * @example
+ * ```ts
+ * const box = { x: 10, y: 20, w: 100, h: 50 }
+ * const isValid = boxModelValidator.check(box) // true
+ *
+ * const invalidBox = { x: 10, y: 20, w: -5, h: 50 }
+ * const isValidNegative = boxModelValidator.check(invalidBox) // true (validator allows negative values)
+ * ```
+ */
 export const boxModelValidator: T.ObjectValidator<BoxModel> = T.object({
 	x: T.number,
 	y: T.number,

package/src/misc/id-validator.test.ts

@@ -0,0 +1,50 @@
+import type { RecordId, UnknownRecord } from '@tldraw/store'
+import { describe, expect, it } from 'vitest'
+import { idValidator } from './id-validator'
+
+// Mock record types for testing
+interface MockShapeRecord extends UnknownRecord {
+	typeName: 'shape'
+}
+
+interface MockPageRecord extends UnknownRecord {
+	typeName: 'page'
+}
+
+type MockShapeId = RecordId<MockShapeRecord>
+type MockPageId = RecordId<MockPageRecord>
+
+describe('idValidator', () => {
+	it('should validate correct IDs with proper prefix', () => {
+		const shapeValidator = idValidator<MockShapeId>('shape')
+		const pageValidator = idValidator<MockPageId>('page')
+
+		expect(shapeValidator.validate('shape:abc123')).toBe('shape:abc123')
+		expect(shapeValidator.validate('shape:')).toBe('shape:')
+		expect(pageValidator.validate('page:main')).toBe('page:main')
+	})
+
+	it('should reject IDs with wrong prefix', () => {
+		const shapeValidator = idValidator<MockShapeId>('shape')
+
+		expect(() => shapeValidator.validate('page:abc123')).toThrow(
+			'shape ID must start with "shape:"'
+		)
+		expect(() => shapeValidator.validate('asset:xyz789')).toThrow(
+			'shape ID must start with "shape:"'
+		)
+		expect(() => shapeValidator.validate('abc123')).toThrow('shape ID must start with "shape:"')
+		expect(() => shapeValidator.validate('')).toThrow('shape ID must start with "shape:"')
+	})
+
+	it('should work with different prefixes independently', () => {
+		const shapeValidator = idValidator<MockShapeId>('shape')
+		const pageValidator = idValidator<MockPageId>('page')
+
+		expect(shapeValidator.isValid('shape:abc123')).toBe(true)
+		expect(shapeValidator.isValid('page:abc123')).toBe(false)
+
+		expect(pageValidator.isValid('shape:abc123')).toBe(false)
+		expect(pageValidator.isValid('page:abc123')).toBe(true)
+	})
+})

package/src/misc/id-validator.ts

@@ -1,7 +1,26 @@
 import type { RecordId, UnknownRecord } from '@tldraw/store'
 import { T } from '@tldraw/validate'
 
-/** @public */
+/**
+ * Creates a validator for typed record IDs that ensures they follow the correct
+ * format with the specified prefix. Record IDs in tldraw follow the pattern
+ * "prefix:identifier" where the prefix indicates the record type.
+ *
+ * @param prefix - The required prefix for the ID (e.g., 'shape', 'page', 'asset')
+ * @returns A validator that checks the ID format and returns the typed ID
+ * @public
+ * @example
+ * ```ts
+ * const shapeIdValidator = idValidator<TLShapeId>('shape')
+ * const validId = shapeIdValidator.validate('shape:abc123') // Returns 'shape:abc123' as TLShapeId
+ *
+ * const pageIdValidator = idValidator<TLPageId>('page')
+ * const pageId = pageIdValidator.validate('page:main') // Returns 'page:main' as TLPageId
+ *
+ * // This would throw an error:
+ * // shapeIdValidator.validate('page:abc123') // Error: shape ID must start with "shape:"
+ * ```
+ */
 export function idValidator<Id extends RecordId<UnknownRecord>>(
 	prefix: Id['__type__']['typeName']
 ): T.Validator<Id> {