@tldraw/tlschema 4.2.0-next.f100cedfc45b → 4.3.0-canary.03ae87dcc44b

package/src/records/TLShape.ts

@@ -79,12 +79,51 @@ export type TLDefaultShape =
  */
 export type TLUnknownShape = TLBaseShape<string, object>
 
+/** @public */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface TLGlobalShapePropsMap {}
+
+/** @public */
+// prettier-ignore
+export type TLIndexedShapes = {
+	// We iterate over a union of augmented keys and default shape types.
+	// This allows us to include (or conditionally exclude or override) the default shapes in one go.
+	//
+	// In the `as` clause we are filtering out disabled shapes.
+	[K in keyof TLGlobalShapePropsMap | TLDefaultShape['type'] as K extends TLDefaultShape['type']
+		? // core shapes are always available and cannot be overridden so we just include them
+			K extends 'group'
+			? K
+			: K extends keyof TLGlobalShapePropsMap
+				? // if it extends a nullish value the user has disabled this shape type so we filter it out with never
+					TLGlobalShapePropsMap[K] extends null | undefined
+					? never
+					: K
+				: K
+		: K]: K extends 'group'
+		? // core shapes are always available and cannot be overridden so we just include them
+			Extract<TLDefaultShape, { type: K }>
+		: K extends TLDefaultShape['type']
+			? // if it's a default shape type we need to check if it's been overridden
+				K extends keyof TLGlobalShapePropsMap
+				? // if it has been overriden then use the custom shape definition
+					TLBaseShape<K, TLGlobalShapePropsMap[K]>
+				: // if it has not been overriden then reuse existing type aliases for better type display
+					Extract<TLDefaultShape, { type: K }>
+			: // use the custom shape definition
+				TLBaseShape<K, TLGlobalShapePropsMap[K & keyof TLGlobalShapePropsMap]>
+}
+
 /**
- * The set of all shapes that are available in the editor, including unknown shapes.
+ * The set of all shapes that are available in the editor.
  *
  * This is the primary shape type used throughout tldraw. It includes both the
  * built-in default shapes and any custom shapes that might be added.
  *
+ * You can use this type without a type argument to work with any shape, or pass
+ * a specific shape type string (e.g., `'geo'`, `'arrow'`, `'text'`) to narrow
+ * down to that specific shape type.
+ *
  * @example
  * ```ts
  * // Work with any shape in the editor
@@ -95,11 +134,16 @@ export type TLUnknownShape = TLBaseShape<string, object>
  *     y: shape.y + deltaY
  *   }
  * }
+ *
+ * // Narrow to a specific shape type by passing the type as a generic argument
+ * function getArrowLabel(shape: TLShape<'arrow'>): string {
+ *   return shape.props.text // TypeScript knows this is a TLArrowShape
+ * }
  * ```
  *
  * @public
  */
-export type TLShape = TLDefaultShape | TLUnknownShape
+export type TLShape<K extends keyof TLIndexedShapes = keyof TLIndexedShapes> = TLIndexedShapes[K]
 
 /**
  * A partial version of a shape, useful for updates and patches.
@@ -139,6 +183,57 @@ export type TLShapePartial<T extends TLShape = TLShape> = T extends T
 		} & Partial<Omit<T, 'type' | 'id' | 'props' | 'meta'>>
 	: never
 
+/**
+ * A partial version of a shape, useful for creating shapes.
+ *
+ * This type represents a shape where all properties except `type` are optional.
+ * It's commonly used when creating shapes.
+ *
+ * @example
+ * ```ts
+ * // Create a shape
+ * const shapeCreate: TLCreateShapePartial = {
+ *   type: 'geo',
+ *   x: 100,
+ *   y: 200
+ * }
+ *
+ * // Create shape properties
+ * const propsCreate: TLCreateShapePartial<TLGeoShape> = {
+ *   type: 'geo',
+ *   props: {
+ *     w: 150,
+ *     h: 100
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+export type TLCreateShapePartial<T extends TLShape = TLShape> = T extends T
+	? {
+			type: T['type']
+			props?: Partial<T['props']>
+			meta?: Partial<T['meta']>
+		} & Partial<Omit<T, 'type' | 'props' | 'meta'>>
+	: never
+
+/**
+ * Extract a shape type by its props.
+ *
+ * This utility type takes a props object type and returns the corresponding shape type
+ * from the TLShape union whose props match the given type.
+ *
+ * @example
+ * ```ts
+ * type MyShape = ExtractShapeByProps<{ w: number; h: number }>
+ * // MyShape is now the type of shape(s) that have props with w and h as numbers
+ * ```
+ *
+ * @public
+ */
+export type ExtractShapeByProps<P> = Extract<TLShape, { props: P }>
+
 /**
  * A unique identifier for a shape record.
  *
@@ -153,7 +248,7 @@ export type TLShapePartial<T extends TLShape = TLShape> = T extends T
  *
  * @public
  */
-export type TLShapeId = RecordId<TLUnknownShape>
+export type TLShapeId = RecordId<TLShape>
 
 /**
  * The ID of a shape's parent, which can be either a page or another shape.
@@ -195,7 +290,7 @@ export const rootShapeVersions = createMigrationIds('com.tldraw.shape', {
 	HoistOpacity: 2,
 	AddMeta: 3,
 	AddWhite: 4,
-} as const)
+})
 
 /**
  * Migration sequence for the root shape record type.
@@ -469,7 +564,7 @@ export function createShapePropsMigrationIds<
  * @internal
  */
 export function createShapeRecordType(shapes: Record<string, SchemaPropsInfo>) {
-	return createRecordType<TLShape>('shape', {
+	return createRecordType('shape', {
 		scope: 'document',
 		validator: T.model(
 			'shape',

package/src/shapes/ShapeWithCrop.ts

@@ -1,5 +1,5 @@
 import { VecModel } from '../misc/geometry-types'
-import { TLBaseShape } from './TLBaseShape'
+import { ExtractShapeByProps } from '../records/TLShape'
 
 /**
  * Defines cropping parameters for shapes that support cropping.
@@ -71,4 +71,4 @@ export interface TLShapeCrop {
  *
  * @public
  */
-export type ShapeWithCrop = TLBaseShape<string, { w: number; h: number; crop: TLShapeCrop | null }>
+export type ShapeWithCrop = ExtractShapeByProps<{ w: number; h: number; crop: TLShapeCrop | null }>

package/src/shapes/TLBaseShape.ts

@@ -1,4 +1,3 @@
-import { BaseRecord } from '@tldraw/store'
 import { IndexKey, JsonObject } from '@tldraw/utils'
 import { T } from '@tldraw/validate'
 import { TLOpacityType, opacityValidator } from '../misc/TLOpacity'
@@ -9,18 +8,37 @@ import { TLParentId, TLShapeId } from '../records/TLShape'
  * 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.
+ * specific type. Every default shape extends this base with additional type-specific properties.
+ *
+ * Custom shapes should be defined by augmenting the TLGlobalShapePropsMap type and getting the shape type from the TLShape type.
  *
  * @example
  * ```ts
- * // Define a custom shape type
- * interface MyCustomShape extends TLBaseShape<'custom', { size: number; color: string }> {}
+ * // Define a default shape type
+ * interface TLArrowShape extends TLBaseShape<'arrow', {
+ *   kind: TLArrowShapeKind
+ *   labelColor: TLDefaultColorStyle
+ *   color: TLDefaultColorStyle
+ *   fill: TLDefaultFillStyle
+ *   dash: TLDefaultDashStyle
+ *   size: TLDefaultSizeStyle
+ *   arrowheadStart: TLArrowShapeArrowheadStyle
+ *   arrowheadEnd: TLArrowShapeArrowheadStyle
+ *   font: TLDefaultFontStyle
+ *   start: VecModel
+ *   end: VecModel
+ *   bend: number
+ *   richText: TLRichText
+ *   labelPosition: number
+ *   scale: number
+ *   elbowMidPoint: number
+ * }> {}
  *
  * // Create a shape instance
- * const myShape: MyCustomShape = {
+ * const arrowShape: TLArrowShape = {
  *   id: 'shape:abc123',
  *   typeName: 'shape',
- *   type: 'custom',
+ *   type: 'arrow',
  *   x: 100,
  *   y: 200,
  *   rotation: 0,
@@ -29,8 +47,10 @@ import { TLParentId, TLShapeId } from '../records/TLShape'
  *   isLocked: false,
  *   opacity: 1,
  *   props: {
- *     size: 50,
- *     color: 'blue'
+ *     kind: 'arc',
+ *     start: { x: 0, y: 0 },
+ *     end: { x: 100, y: 100 },
+ *     // ... other props
  *   },
  *   meta: {}
  * }
@@ -38,8 +58,12 @@ import { TLParentId, TLShapeId } from '../records/TLShape'
  *
  * @public
  */
-export interface TLBaseShape<Type extends string, Props extends object>
-	extends BaseRecord<'shape', TLShapeId> {
+export interface TLBaseShape<Type extends string, Props extends object> {
+	// using real `extends BaseRecord<'shape', TLShapeId>` introduces a circularity in the types
+	// and for that reason those "base members" have to be declared manually here
+	readonly id: TLShapeId
+	readonly typeName: 'shape'
+
 	type: Type
 	x: number
 	y: number

package/src/store-migrations.ts

@@ -72,7 +72,8 @@ export const storeMigrations = createMigrationSequence({
 				for (const [id, record] of objectMapEntries(store)) {
 					if (
 						record.typeName === 'shape' &&
-						((record as TLShape).type === 'icon' || (record as TLShape).type === 'code')
+						'type' in record &&
+						(record.type === 'icon' || record.type === 'code')
 					) {
 						delete store[id]
 					}

package/src/styles/TLColorStyle.ts

@@ -61,6 +61,7 @@ export interface TLDefaultColorThemeColor {
 	semi: string
 	pattern: string
 	fill: string // usually same as solid
+	linedFill: string // usually slightly lighter than fill
 	frameHeadingStroke: string
 	frameHeadingFill: string
 	frameStroke: string
@@ -134,6 +135,7 @@ export const DefaultColorThemePalette: {
 		black: {
 			solid: '#1d1d1d',
 			fill: '#1d1d1d',
+			linedFill: '#363636',
 			frameHeadingStroke: '#717171',
 			frameHeadingFill: '#ffffff',
 			frameStroke: '#717171',
@@ -149,6 +151,7 @@ export const DefaultColorThemePalette: {
 		blue: {
 			solid: '#4465e9',
 			fill: '#4465e9',
+			linedFill: '#6580ec',
 			frameHeadingStroke: '#6681ec',
 			frameHeadingFill: '#f9fafe',
 			frameStroke: '#6681ec',
@@ -164,6 +167,7 @@ export const DefaultColorThemePalette: {
 		green: {
 			solid: '#099268',
 			fill: '#099268',
+			linedFill: '#0bad7c',
 			frameHeadingStroke: '#37a684',
 			frameHeadingFill: '#f8fcfa',
 			frameStroke: '#37a684',
@@ -179,6 +183,7 @@ export const DefaultColorThemePalette: {
 		grey: {
 			solid: '#9fa8b2',
 			fill: '#9fa8b2',
+			linedFill: '#bbc1c9',
 			frameHeadingStroke: '#aaaaab',
 			frameHeadingFill: '#fbfcfc',
 			frameStroke: '#aaaaab',
@@ -194,6 +199,7 @@ export const DefaultColorThemePalette: {
 		'light-blue': {
 			solid: '#4ba1f1',
 			fill: '#4ba1f1',
+			linedFill: '#7abaf5',
 			frameHeadingStroke: '#6cb2f3',
 			frameHeadingFill: '#f8fbfe',
 			frameStroke: '#6cb2f3',
@@ -209,6 +215,7 @@ export const DefaultColorThemePalette: {
 		'light-green': {
 			solid: '#4cb05e',
 			fill: '#4cb05e',
+			linedFill: '#7ec88c',
 			frameHeadingStroke: '#6dbe7c',
 			frameHeadingFill: '#f8fcf9',
 			frameStroke: '#6dbe7c',
@@ -224,6 +231,7 @@ export const DefaultColorThemePalette: {
 		'light-red': {
 			solid: '#f87777',
 			fill: '#f87777',
+			linedFill: '#f99a9a',
 			frameHeadingStroke: '#f89090',
 			frameHeadingFill: '#fffafa',
 			frameStroke: '#f89090',
@@ -239,6 +247,7 @@ export const DefaultColorThemePalette: {
 		'light-violet': {
 			solid: '#e085f4',
 			fill: '#e085f4',
+			linedFill: '#e9abf7',
 			frameHeadingStroke: '#e59bf5',
 			frameHeadingFill: '#fefaff',
 			frameStroke: '#e59bf5',
@@ -254,6 +263,7 @@ export const DefaultColorThemePalette: {
 		orange: {
 			solid: '#e16919',
 			fill: '#e16919',
+			linedFill: '#ea8643',
 			frameHeadingStroke: '#e68544',
 			frameHeadingFill: '#fef9f6',
 			frameStroke: '#e68544',
@@ -269,6 +279,7 @@ export const DefaultColorThemePalette: {
 		red: {
 			solid: '#e03131',
 			fill: '#e03131',
+			linedFill: '#e75f5f',
 			frameHeadingStroke: '#e55757',
 			frameHeadingFill: '#fef7f7',
 			frameStroke: '#e55757',
@@ -284,6 +295,7 @@ export const DefaultColorThemePalette: {
 		violet: {
 			solid: '#ae3ec9',
 			fill: '#ae3ec9',
+			linedFill: '#be68d4',
 			frameHeadingStroke: '#bc62d3',
 			frameHeadingFill: '#fcf7fd',
 			frameStroke: '#bc62d3',
@@ -299,6 +311,7 @@ export const DefaultColorThemePalette: {
 		yellow: {
 			solid: '#f1ac4b',
 			fill: '#f1ac4b',
+			linedFill: '#f5c27a',
 			frameHeadingStroke: '#f3bb6c',
 			frameHeadingFill: '#fefcf8',
 			frameStroke: '#f3bb6c',
@@ -314,6 +327,7 @@ export const DefaultColorThemePalette: {
 		white: {
 			solid: '#FFFFFF',
 			fill: '#FFFFFF',
+			linedFill: '#ffffff',
 			semi: '#f5f5f5',
 			pattern: '#f9f9f9',
 			frameHeadingStroke: '#7d7d7d',
@@ -336,6 +350,7 @@ export const DefaultColorThemePalette: {
 		black: {
 			solid: '#f2f2f2',
 			fill: '#f2f2f2',
+			linedFill: '#ffffff',
 			frameHeadingStroke: '#5c5c5c',
 			frameHeadingFill: '#252525',
 			frameStroke: '#5c5c5c',
@@ -351,6 +366,7 @@ export const DefaultColorThemePalette: {
 		blue: {
 			solid: '#4f72fc', // 3c60f0
 			fill: '#4f72fc',
+			linedFill: '#3c5cdd',
 			frameHeadingStroke: '#384994',
 			frameHeadingFill: '#1C2036',
 			frameStroke: '#384994',
@@ -366,6 +382,7 @@ export const DefaultColorThemePalette: {
 		green: {
 			solid: '#099268',
 			fill: '#099268',
+			linedFill: '#087856',
 			frameHeadingStroke: '#10513C',
 			frameHeadingFill: '#14241f',
 			frameStroke: '#10513C',
@@ -381,6 +398,7 @@ export const DefaultColorThemePalette: {
 		grey: {
 			solid: '#9398b0',
 			fill: '#9398b0',
+			linedFill: '#8388a5',
 			frameHeadingStroke: '#42474D',
 			frameHeadingFill: '#23262A',
 			frameStroke: '#42474D',
@@ -396,6 +414,7 @@ export const DefaultColorThemePalette: {
 		'light-blue': {
 			solid: '#4dabf7',
 			fill: '#4dabf7',
+			linedFill: '#2793ec',
 			frameHeadingStroke: '#075797',
 			frameHeadingFill: '#142839',
 			frameStroke: '#075797',
@@ -411,6 +430,7 @@ export const DefaultColorThemePalette: {
 		'light-green': {
 			solid: '#40c057',
 			fill: '#40c057',
+			linedFill: '#37a44b',
 			frameHeadingStroke: '#1C5427',
 			frameHeadingFill: '#18251A',
 			frameStroke: '#1C5427',
@@ -426,6 +446,7 @@ export const DefaultColorThemePalette: {
 		'light-red': {
 			solid: '#ff8787',
 			fill: '#ff8787',
+			linedFill: '#ff6666',
 			frameHeadingStroke: '#6f3232', // Darker and desaturated variant of solid
 			frameHeadingFill: '#341818', // Deep, muted dark red
 			frameStroke: '#6f3232', // Matches headingStroke
@@ -441,6 +462,7 @@ export const DefaultColorThemePalette: {
 		'light-violet': {
 			solid: '#e599f7',
 			fill: '#e599f7',
+			linedFill: '#dc71f4',
 			frameHeadingStroke: '#6c367a',
 			frameHeadingFill: '#2D2230',
 			frameStroke: '#6c367a',
@@ -456,6 +478,7 @@ export const DefaultColorThemePalette: {
 		orange: {
 			solid: '#f76707',
 			fill: '#f76707',
+			linedFill: '#f54900',
 			frameHeadingStroke: '#773a0e', // Darker, muted version of solid
 			frameHeadingFill: '#2f1d13', // Deep, warm, muted background
 			frameStroke: '#773a0e', // Matches headingStroke
@@ -471,6 +494,7 @@ export const DefaultColorThemePalette: {
 		red: {
 			solid: '#e03131',
 			fill: '#e03131',
+			linedFill: '#c31d1d',
 			frameHeadingStroke: '#701e1e', // Darker, muted variation of solid
 			frameHeadingFill: '#301616', // Deep, muted reddish backdrop
 			frameStroke: '#701e1e', // Matches headingStroke
@@ -486,6 +510,7 @@ export const DefaultColorThemePalette: {
 		violet: {
 			solid: '#ae3ec9',
 			fill: '#ae3ec9',
+			linedFill: '#8f2fa7',
 			frameHeadingStroke: '#6d1583', // Darker, muted variation of solid
 			frameHeadingFill: '#27152e', // Deep, rich muted violet backdrop
 			frameStroke: '#6d1583', // Matches headingStroke
@@ -501,6 +526,7 @@ export const DefaultColorThemePalette: {
 		yellow: {
 			solid: '#ffc034',
 			fill: '#ffc034',
+			linedFill: '#ffae00',
 			frameHeadingStroke: '#684e12', // Darker, muted variant of solid
 			frameHeadingFill: '#2a2113', // Rich, muted dark-yellow background
 			frameStroke: '#684e12', // Matches headingStroke
@@ -516,6 +542,7 @@ export const DefaultColorThemePalette: {
 		white: {
 			solid: '#f3f3f3',
 			fill: '#f3f3f3',
+			linedFill: '#f3f3f3',
 			semi: '#f5f5f5',
 			pattern: '#f9f9f9',
 			frameHeadingStroke: '#ffffff',

package/src/styles/TLFillStyle.ts

@@ -36,7 +36,7 @@ import { StyleProp } from './StyleProp'
  */
 export const DefaultFillStyle = StyleProp.defineEnum('tldraw:fill', {
 	defaultValue: 'none',
-	values: ['none', 'semi', 'solid', 'pattern', 'fill'],
+	values: ['none', 'semi', 'solid', 'pattern', 'fill', 'lined-fill'],
 })
 
 /**