@tldraw/tlschema 4.1.0-canary.9f9255bd7a83 → 4.1.0-canary.a152954244d2

package/src/shapes/TLArrowShape.ts

@@ -18,13 +18,45 @@ import { DefaultSizeStyle, TLDefaultSizeStyle } from '../styles/TLSizeStyle'
 import { TLBaseShape } from './TLBaseShape'
 
 const arrowKinds = ['arc', 'elbow'] as const
-/** @public */
+/**
+ * Style property for arrow shape kind, determining how the arrow is drawn.
+ *
+ * Arrows can be drawn as arcs (curved) or elbows (angled with straight segments).
+ * This affects the visual appearance and behavior of arrow shapes.
+ *
+ * @example
+ * ```ts
+ * // Create an arrow with arc style (curved)
+ * const arcArrow: TLArrowShape = {
+ *   // ... other properties
+ *   props: {
+ *     kind: 'arc',
+ *     // ... other props
+ *   }
+ * }
+ *
+ * // Create an arrow with elbow style (angled)
+ * const elbowArrow: TLArrowShape = {
+ *   // ... other properties
+ *   props: {
+ *     kind: 'elbow',
+ *     // ... other props
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const ArrowShapeKindStyle = StyleProp.defineEnum('tldraw:arrowKind', {
 	defaultValue: 'arc',
 	values: arrowKinds,
 })
 
-/** @public */
+/**
+ * The type representing arrow shape kinds.
+ *
+ * @public
+ */
 export type TLArrowShapeKind = T.TypeOf<typeof ArrowShapeKindStyle>
 
 const arrowheadTypes = [
@@ -39,22 +71,96 @@ const arrowheadTypes = [
 	'none',
 ] as const
 
-/** @public */
+/**
+ * Style property for the arrowhead at the start of an arrow.
+ *
+ * Defines the visual style of the arrowhead at the beginning of the arrow path.
+ * Can be one of several predefined styles or none for no arrowhead.
+ *
+ * @example
+ * ```ts
+ * // Arrow with no start arrowhead but triangle end arrowhead
+ * const arrow: TLArrowShape = {
+ *   // ... other properties
+ *   props: {
+ *     arrowheadStart: 'none',
+ *     arrowheadEnd: 'triangle',
+ *     // ... other props
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const ArrowShapeArrowheadStartStyle = StyleProp.defineEnum('tldraw:arrowheadStart', {
 	defaultValue: 'none',
 	values: arrowheadTypes,
 })
 
-/** @public */
+/**
+ * Style property for the arrowhead at the end of an arrow.
+ *
+ * Defines the visual style of the arrowhead at the end of the arrow path.
+ * Defaults to 'arrow' style, giving arrows their characteristic pointed appearance.
+ *
+ * @example
+ * ```ts
+ * // Arrow with different start and end arrowheads
+ * const doubleArrow: TLArrowShape = {
+ *   // ... other properties
+ *   props: {
+ *     arrowheadStart: 'triangle',
+ *     arrowheadEnd: 'diamond',
+ *     // ... other props
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
 export const ArrowShapeArrowheadEndStyle = StyleProp.defineEnum('tldraw:arrowheadEnd', {
 	defaultValue: 'arrow',
 	values: arrowheadTypes,
 })
 
-/** @public */
+/**
+ * The type representing arrowhead styles for both start and end of arrows.
+ *
+ * @public
+ */
 export type TLArrowShapeArrowheadStyle = T.TypeOf<typeof ArrowShapeArrowheadStartStyle>
 
-/** @public */
+/**
+ * Properties specific to arrow shapes.
+ *
+ * Defines all the configurable aspects of an arrow shape, including visual styling,
+ * geometry, text labeling, and positioning. Arrows can connect two points and
+ * optionally display text labels.
+ *
+ * @example
+ * ```ts
+ * const arrowProps: TLArrowShapeProps = {
+ *   kind: 'arc',
+ *   labelColor: 'black',
+ *   color: 'blue',
+ *   fill: 'none',
+ *   dash: 'solid',
+ *   size: 'm',
+ *   arrowheadStart: 'none',
+ *   arrowheadEnd: 'arrow',
+ *   font: 'draw',
+ *   start: { x: 0, y: 0 },
+ *   end: { x: 100, y: 100 },
+ *   bend: 0.2,
+ *   richText: toRichText('Label'),
+ *   labelPosition: 0.5,
+ *   scale: 1,
+ *   elbowMidPoint: 0.5
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface TLArrowShapeProps {
 	kind: TLArrowShapeKind
 	labelColor: TLDefaultColorStyle
@@ -74,10 +180,59 @@ export interface TLArrowShapeProps {
 	elbowMidPoint: number
 }
 
-/** @public */
+/**
+ * A complete arrow shape record.
+ *
+ * Combines the base shape interface with arrow-specific properties to create
+ * a full arrow shape that can be stored and manipulated in the editor.
+ *
+ * @example
+ * ```ts
+ * const arrowShape: TLArrowShape = {
+ *   id: 'shape:arrow123',
+ *   typeName: 'shape',
+ *   type: 'arrow',
+ *   x: 100,
+ *   y: 200,
+ *   rotation: 0,
+ *   index: 'a1',
+ *   parentId: 'page:main',
+ *   isLocked: false,
+ *   opacity: 1,
+ *   props: {
+ *     kind: 'arc',
+ *     start: { x: 0, y: 0 },
+ *     end: { x: 150, y: 100 },
+ *     // ... other props
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ *
+ * @public
+ */
 export type TLArrowShape = TLBaseShape<'arrow', TLArrowShapeProps>
 
-/** @public */
+/**
+ * Validation configuration for arrow shape properties.
+ *
+ * Defines the validators for each property of an arrow shape, ensuring that
+ * arrow shape data is valid and conforms to the expected types and constraints.
+ *
+ * @example
+ * ```ts
+ * // The validators ensure proper typing and validation
+ * const validator = T.object(arrowShapeProps)
+ * const validArrowProps = validator.validate({
+ *   kind: 'arc',
+ *   start: { x: 0, y: 0 },
+ *   end: { x: 100, y: 50 },
+ *   // ... other required properties
+ * })
+ * ```
+ *
+ * @public
+ */
 export const arrowShapeProps: RecordProps<TLArrowShape> = {
 	kind: ArrowShapeKindStyle,
 	labelColor: DefaultLabelColorStyle,
@@ -97,7 +252,22 @@ export const arrowShapeProps: RecordProps<TLArrowShape> = {
 	elbowMidPoint: T.number,
 }
 
-/** @public */
+/**
+ * Migration version identifiers for arrow shape properties.
+ *
+ * These track the evolution of the arrow shape schema over time, with each
+ * version representing a specific change to the arrow shape structure or properties.
+ *
+ * @example
+ * ```ts
+ * // Used internally for migration system
+ * if (version < arrowShapeVersions.AddLabelColor) {
+ *   // Apply label color migration
+ * }
+ * ```
+ *
+ * @public
+ */
 export const arrowShapeVersions = createShapePropsMigrationIds('arrow', {
 	AddLabelColor: 1,
 	AddIsPrecise: 2,
@@ -112,7 +282,15 @@ function propsMigration(migration: TLPropsMigration) {
 	return createPropsMigration<TLArrowShape>('shape', 'arrow', migration)
 }
 
-/** @public */
+/**
+ * Complete migration sequence for arrow shapes.
+ *
+ * Defines all the migrations needed to transform arrow shape data from older
+ * versions to the current version. Each migration handles a specific schema change,
+ * ensuring backward compatibility and smooth data evolution.
+ *
+ * @public
+ */
 export const arrowShapeMigrations = createMigrationSequence({
 	sequenceId: 'com.tldraw.shape.arrow',
 	retroactive: false,

package/src/shapes/TLBaseShape.test.ts

@@ -0,0 +1,142 @@
+import { T } from '@tldraw/validate'
+import { describe, expect, it } from 'vitest'
+import { createShapeValidator, parentIdValidator, shapeIdValidator } from './TLBaseShape'
+
+describe('TLBaseShape', () => {
+	describe('parentIdValidator', () => {
+		it('should accept valid page and shape parent IDs', () => {
+			expect(() => parentIdValidator.validate('page:main')).not.toThrow()
+			expect(() => parentIdValidator.validate('shape:frame1')).not.toThrow()
+			expect(parentIdValidator.validate('page:main')).toBe('page:main')
+		})
+
+		it('should reject invalid parent ID prefixes', () => {
+			expect(() => parentIdValidator.validate('invalid:123')).toThrow(
+				'Parent ID must start with "page:" or "shape:"'
+			)
+			expect(() => parentIdValidator.validate('asset:123')).toThrow(
+				'Parent ID must start with "page:" or "shape:"'
+			)
+			expect(() => parentIdValidator.validate('page-main')).toThrow(
+				'Parent ID must start with "page:" or "shape:"'
+			)
+		})
+	})
+
+	describe('shapeIdValidator', () => {
+		it('should accept valid shape IDs', () => {
+			expect(() => shapeIdValidator.validate('shape:abc123')).not.toThrow()
+			expect(shapeIdValidator.validate('shape:test')).toBe('shape:test')
+		})
+
+		it('should reject non-shape IDs', () => {
+			expect(() => shapeIdValidator.validate('page:123')).toThrow(
+				'shape ID must start with "shape:"'
+			)
+			expect(() => shapeIdValidator.validate('asset:123')).toThrow(
+				'shape ID must start with "shape:"'
+			)
+			expect(() => shapeIdValidator.validate('shape-abc123')).toThrow(
+				'shape ID must start with "shape:"'
+			)
+		})
+	})
+
+	describe('createShapeValidator', () => {
+		it('should create validator for shape with no custom props', () => {
+			const validator = createShapeValidator('simple')
+
+			const validShape = {
+				id: 'shape:simple123',
+				typeName: 'shape',
+				type: 'simple',
+				x: 100,
+				y: 200,
+				rotation: 0.5,
+				index: 'a1',
+				parentId: 'page:main',
+				isLocked: false,
+				opacity: 0.8,
+				props: {},
+				meta: {},
+			}
+
+			expect(() => validator.validate(validShape)).not.toThrow()
+		})
+
+		it('should create validator for shape with custom props', () => {
+			const validator = createShapeValidator('custom', {
+				width: T.number,
+				height: T.number,
+				color: T.string,
+			})
+
+			const validShape = {
+				id: 'shape:custom456',
+				typeName: 'shape',
+				type: 'custom',
+				x: 50,
+				y: 75,
+				rotation: 1.0,
+				index: 'a2',
+				parentId: 'shape:frame1',
+				isLocked: true,
+				opacity: 0.5,
+				props: {
+					width: 150,
+					height: 100,
+					color: 'blue',
+				},
+				meta: {},
+			}
+
+			expect(() => validator.validate(validShape)).not.toThrow()
+		})
+
+		it('should reject shapes with wrong type', () => {
+			const validator = createShapeValidator('test')
+
+			const invalidShape = {
+				id: 'shape:test',
+				typeName: 'shape',
+				type: 'wrong',
+				x: 0,
+				y: 0,
+				rotation: 0,
+				index: 'a1',
+				parentId: 'page:main',
+				isLocked: false,
+				opacity: 1,
+				props: {},
+				meta: {},
+			}
+
+			expect(() => validator.validate(invalidShape)).toThrow()
+		})
+
+		it('should reject shapes with invalid custom props', () => {
+			const validator = createShapeValidator('custom', {
+				width: T.number,
+				height: T.number,
+				color: T.string,
+			})
+
+			const invalidShape = {
+				id: 'shape:custom123',
+				typeName: 'shape',
+				type: 'custom',
+				x: 0,
+				y: 0,
+				rotation: 0,
+				index: 'a1',
+				parentId: 'page:main',
+				isLocked: false,
+				opacity: 1,
+				meta: {},
+				props: { width: '100' }, // Wrong type - should be number
+			}
+
+			expect(() => validator.validate(invalidShape)).toThrow()
+		})
+	})
+})

package/src/shapes/TLBaseShape.ts

@@ -5,7 +5,39 @@ import { TLOpacityType, opacityValidator } from '../misc/TLOpacity'
 import { idValidator } from '../misc/id-validator'
 import { TLParentId, TLShapeId } from '../records/TLShape'
 
-/** @public */
+/**
+ * Base interface for all shapes in tldraw.
+ *
+ * This interface defines the common properties that all shapes share, regardless of their
+ * specific type. Every shape extends this base with additional type-specific properties.
+ *
+ * @example
+ * ```ts
+ * // Define a custom shape type
+ * interface MyCustomShape extends TLBaseShape<'custom', { size: number; color: string }> {}
+ *
+ * // Create a shape instance
+ * const myShape: MyCustomShape = {
+ *   id: 'shape:abc123',
+ *   typeName: 'shape',
+ *   type: 'custom',
+ *   x: 100,
+ *   y: 200,
+ *   rotation: 0,
+ *   index: 'a1',
+ *   parentId: 'page:main',
+ *   isLocked: false,
+ *   opacity: 1,
+ *   props: {
+ *     size: 50,
+ *     color: 'blue'
+ *   },
+ *   meta: {}
+ * }
+ * ```
+ *
+ * @public
+ */
 export interface TLBaseShape<Type extends string, Props extends object>
 	extends BaseRecord<'shape', TLShapeId> {
 	type: Type
@@ -20,7 +52,24 @@ export interface TLBaseShape<Type extends string, Props extends object>
 	meta: JsonObject
 }
 
-/** @public */
+/**
+ * Validator for parent IDs, ensuring they follow the correct format.
+ *
+ * Parent IDs must start with either "page:" (for shapes directly on a page)
+ * or "shape:" (for shapes inside other shapes like frames or groups).
+ *
+ * @example
+ * ```ts
+ * // Valid parent IDs
+ * const pageParent = parentIdValidator.validate('page:main') // ✓
+ * const shapeParent = parentIdValidator.validate('shape:frame1') // ✓
+ *
+ * // Invalid parent ID (throws error)
+ * const invalid = parentIdValidator.validate('invalid:123') // ✗
+ * ```
+ *
+ * @public
+ */
 export const parentIdValidator = T.string.refine((id) => {
 	if (!id.startsWith('page:') && !id.startsWith('shape:')) {
 		throw new Error('Parent ID must start with "page:" or "shape:"')
@@ -28,10 +77,60 @@ export const parentIdValidator = T.string.refine((id) => {
 	return id as TLParentId
 })
 
-/** @public */
+/**
+ * Validator for shape IDs, ensuring they follow the "shape:" format.
+ *
+ * @example
+ * ```ts
+ * const validId = shapeIdValidator.validate('shape:abc123') // ✓
+ * const invalidId = shapeIdValidator.validate('page:abc123') // ✗ throws error
+ * ```
+ *
+ * @public
+ */
 export const shapeIdValidator = idValidator<TLShapeId>('shape')
 
-/** @public */
+/**
+ * Creates a validator for a specific shape type.
+ *
+ * This function generates a complete validator that can validate shape records
+ * of the specified type, including both the base shape properties and any
+ * custom properties and metadata specific to that shape type.
+ *
+ * @param type - The string literal type for this shape (e.g., 'geo', 'arrow')
+ * @param props - Optional validator configuration for shape-specific properties
+ * @param meta - Optional validator configuration for shape-specific metadata
+ * @returns A validator that can validate complete shape records of the specified type
+ *
+ * @example
+ * ```ts
+ * // Create a validator for a custom shape type
+ * const customShapeValidator = createShapeValidator('custom', {
+ *   width: T.number,
+ *   height: T.number,
+ *   color: T.string
+ * })
+ *
+ * // Use the validator to validate shape data
+ * const shapeData = {
+ *   id: 'shape:abc123',
+ *   typeName: 'shape',
+ *   type: 'custom',
+ *   x: 100,
+ *   y: 200,
+ *   // ... other base properties
+ *   props: {
+ *     width: 150,
+ *     height: 100,
+ *     color: 'red'
+ *   }
+ * }
+ *
+ * const validatedShape = customShapeValidator.validate(shapeData)
+ * ```
+ *
+ * @public
+ */
 export function createShapeValidator<
 	Type extends string,
 	Props extends JsonObject,

package/src/shapes/TLBookmarkShape.test.ts

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest'
+import { getTestMigration } from '../__tests__/migrationTestUtils'
+import { bookmarkShapeProps, bookmarkShapeVersions } from './TLBookmarkShape'
+
+describe('TLBookmarkShape', () => {
+	describe('bookmarkShapeProps validation', () => {
+		it('should validate width as nonZeroNumber', () => {
+			// Valid non-zero positive numbers
+			expect(() => bookmarkShapeProps.w.validate(0.1)).not.toThrow()
+			expect(() => bookmarkShapeProps.w.validate(100)).not.toThrow()
+
+			// Invalid: zero and negative
+			expect(() => bookmarkShapeProps.w.validate(0)).toThrow()
+			expect(() => bookmarkShapeProps.w.validate(-1)).toThrow()
+		})
+
+		it('should validate height as nonZeroNumber', () => {
+			// Valid non-zero positive numbers
+			expect(() => bookmarkShapeProps.h.validate(0.1)).not.toThrow()
+			expect(() => bookmarkShapeProps.h.validate(100)).not.toThrow()
+
+			// Invalid: zero and negative
+			expect(() => bookmarkShapeProps.h.validate(0)).toThrow()
+			expect(() => bookmarkShapeProps.h.validate(-1)).toThrow()
+		})
+
+		it('should validate assetId as nullable asset ID', () => {
+			// Valid asset IDs
+			expect(() => bookmarkShapeProps.assetId.validate(null)).not.toThrow()
+			expect(() => bookmarkShapeProps.assetId.validate('asset:bookmark123')).not.toThrow()
+
+			// Invalid asset IDs
+			expect(() => bookmarkShapeProps.assetId.validate('shape:notasset')).toThrow()
+			expect(() => bookmarkShapeProps.assetId.validate('bookmark123')).toThrow()
+			expect(() => bookmarkShapeProps.assetId.validate(undefined)).toThrow()
+		})
+
+		it('should validate url as linkUrl', () => {
+			// Valid URLs
+			expect(() => bookmarkShapeProps.url.validate('')).not.toThrow()
+			expect(() => bookmarkShapeProps.url.validate('https://example.com')).not.toThrow()
+
+			// Invalid URLs
+			expect(() => bookmarkShapeProps.url.validate('not-a-url')).toThrow()
+			expect(() => bookmarkShapeProps.url.validate('javascript:alert("xss")')).toThrow()
+		})
+	})
+
+	describe('NullAssetId migration', () => {
+		const { up, down } = getTestMigration(bookmarkShapeVersions.NullAssetId)
+
+		it('should add assetId as null when undefined', () => {
+			const oldRecord = {
+				props: {
+					w: 300,
+					h: 320,
+					url: 'https://example.com',
+					// assetId undefined
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.assetId).toBeNull()
+		})
+
+		it('should preserve existing assetId when present', () => {
+			const oldRecord = {
+				props: {
+					w: 300,
+					h: 320,
+					url: 'https://example.com',
+					assetId: 'asset:existing123',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.assetId).toBe('asset:existing123')
+		})
+
+		it('should throw on retired down migration', () => {
+			expect(() => down({})).toThrow()
+		})
+	})
+
+	describe('MakeUrlsValid migration', () => {
+		const { up, down } = getTestMigration(bookmarkShapeVersions.MakeUrlsValid)
+
+		it('should set invalid URLs to empty string', () => {
+			const oldRecord = {
+				props: {
+					w: 300,
+					h: 320,
+					assetId: null,
+					url: 'not-a-valid-url',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.url).toBe('')
+		})
+
+		it('should preserve valid URLs', () => {
+			const oldRecord = {
+				props: {
+					w: 300,
+					h: 320,
+					assetId: null,
+					url: 'https://example.com',
+				},
+			}
+
+			const result = up(oldRecord)
+			expect(result.props.url).toBe('https://example.com')
+		})
+
+		it('should be noop for down migration', () => {
+			const newRecord = { props: { url: 'https://example.com' } }
+			const result = down(newRecord)
+			expect(result).toEqual(newRecord)
+		})
+	})
+})