@tldraw/editor 4.6.0-next.fecc64eee134 → 5.0.0

package/src/lib/editor/overlays/OverlayManager.ts

@@ -0,0 +1,183 @@
+import { atom, computed } from '@tldraw/state'
+import { Geometry2d } from '../../primitives/geometry/Geometry2d'
+import { VecLike } from '../../primitives/Vec'
+import type { Editor } from '../Editor'
+import { OverlayUtil, TLOverlay } from './OverlayUtil'
+
+/**
+ * An active overlay util paired with the overlays it produced for the current
+ * editor state. Returned by {@link OverlayManager.getActiveOverlayEntries} so
+ * hit-test, render, and debug paths share a single scan per reactive tick.
+ *
+ * @public
+ */
+export interface TLOverlayEntry {
+	util: OverlayUtil
+	overlays: TLOverlay[]
+}
+
+/** @public */
+export class OverlayManager {
+	constructor(public readonly editor: Editor) {}
+
+	/** @internal */
+	readonly _overlayUtils = new Map<string, OverlayUtil>()
+
+	/**
+	 * Register an overlay util instance. Called during editor construction.
+	 * @internal
+	 */
+	registerUtil(util: OverlayUtil) {
+		const type = (util.constructor as typeof OverlayUtil).type
+		if (!type) {
+			throw new Error(`Overlay util ${util.constructor.name} is missing a static 'type' property.`)
+		}
+		if (this._overlayUtils.has(type)) {
+			throw new Error(`Duplicate overlay util type: "${type}"`)
+		}
+		this._overlayUtils.set(type, util)
+	}
+
+	/**
+	 * Get an overlay util by type string, overlay instance, or by passing
+	 * a util class as a generic parameter for type-safe lookup.
+	 *
+	 * @example
+	 * ```ts
+	 * const util = editor.overlays.getOverlayUtil('brush')
+	 * const util = editor.overlays.getOverlayUtil<BrushOverlayUtil>('brush')
+	 * const util = editor.overlays.getOverlayUtil(myOverlay)
+	 * ```
+	 *
+	 * @public
+	 */
+	getOverlayUtil<T extends OverlayUtil>(
+		type: T extends OverlayUtil<infer O> ? O['type'] : string
+	): T
+	getOverlayUtil<O extends TLOverlay>(overlay: O): OverlayUtil<O>
+	getOverlayUtil(arg: string | TLOverlay): OverlayUtil {
+		const type = typeof arg === 'string' ? arg : arg.type
+		const util = this._overlayUtils.get(type)
+		if (!util) throw new Error(`No overlay util found for type: "${type}"`)
+		return util
+	}
+
+	/**
+	 * Returns all registered overlay utils in paint order (ascending zIndex).
+	 * Utils with the same zIndex preserve their registration order.
+	 *
+	 * @public
+	 */
+	@computed getOverlayUtilsInZOrder(): OverlayUtil[] {
+		const utils = Array.from(this._overlayUtils.values())
+		// Stable sort by zIndex (registration order breaks ties).
+		return utils
+			.map((util, i) => ({ util, i, z: util.options.zIndex ?? 0 }))
+			.sort((a, b) => a.z - b.z || a.i - b.i)
+			.map((entry) => entry.util)
+	}
+
+	/**
+	 * Reactive list of active overlay utils paired with the overlays they
+	 * produced for the current editor state, in paint order (ascending
+	 * zIndex). Both the hit-test and render paths read from this single
+	 * cached scan instead of each re-deriving the active set. Active utils
+	 * are included even when their `getOverlays()` returns an empty array,
+	 * since `render()` may still draw non-interactive UI (e.g. the selection
+	 * bounding box during brushing).
+	 *
+	 * @public
+	 */
+	@computed getActiveOverlayEntries(): TLOverlayEntry[] {
+		const entries: TLOverlayEntry[] = []
+		for (const util of this.getOverlayUtilsInZOrder()) {
+			if (!util.isActive()) continue
+			entries.push({ util, overlays: util.getOverlays() })
+		}
+		return entries
+	}
+
+	/**
+	 * Reactively computed list of all currently active overlays, in paint order.
+	 * @public
+	 */
+	@computed getCurrentOverlays(): TLOverlay[] {
+		const all: TLOverlay[] = []
+		for (const { overlays } of this.getActiveOverlayEntries()) {
+			all.push(...overlays)
+		}
+		return all
+	}
+
+	// Hit-test geometry cache keyed by overlay identity. Entries remain valid
+	// while getActiveOverlayEntries() keeps returning the same overlay
+	// instances; when its reactive deps change, getOverlays() emits fresh
+	// objects and stale entries fall out by GC.
+	private _geometryCache = new WeakMap<TLOverlay, Geometry2d | null>()
+
+	/**
+	 * Get hit-test geometry for an overlay, cached by overlay identity. Lets
+	 * hit-testing on a pointermove storm skip the per-overlay geometry
+	 * allocation that {@link OverlayUtil.getGeometry} would otherwise do on
+	 * every call.
+	 *
+	 * @public
+	 */
+	getOverlayGeometry(overlay: TLOverlay): Geometry2d | null {
+		const cached = this._geometryCache.get(overlay)
+		if (cached !== undefined) return cached
+		const util = this.getOverlayUtil(overlay)
+		const geometry = util.getGeometry(overlay)
+		this._geometryCache.set(overlay, geometry)
+		return geometry
+	}
+
+	/**
+	 * The currently hovered overlay id.
+	 * @public
+	 */
+	private _hoveredOverlayId = atom<string | null>('hoveredOverlayId', null)
+
+	getHoveredOverlayId(): string | null {
+		return this._hoveredOverlayId.get()
+	}
+
+	getHoveredOverlay(): TLOverlay | null {
+		const id = this._hoveredOverlayId.get()
+		if (!id) return null
+		return this.getCurrentOverlays().find((o) => o.id === id) ?? null
+	}
+
+	setHoveredOverlay(id: string | null) {
+		if (id === this._hoveredOverlayId.get()) return
+		this._hoveredOverlayId.set(id)
+	}
+
+	/**
+	 * Hit test all active overlays at a given page point.
+	 * Returns the topmost overlay whose geometry contains the point, or null.
+	 * Utils are walked from highest zIndex to lowest so the overlay painted on
+	 * top also wins the hit test. Within a util, overlays are walked in
+	 * array order: the first overlay whose geometry contains the point wins,
+	 * so utils should place highest-priority overlays first in `getOverlays`.
+	 * Interactive overlays (those with geometry) are checked; non-interactive are skipped.
+	 *
+	 * @param point - Point in page coordinates
+	 * @param margin - Hit test margin
+	 * @public
+	 */
+	getOverlayAtPoint(point: VecLike, margin = 0): TLOverlay | null {
+		const entries = this.getActiveOverlayEntries()
+		for (let i = entries.length - 1; i >= 0; i--) {
+			const { overlays } = entries[i]
+			for (const overlay of overlays) {
+				const geometry = this.getOverlayGeometry(overlay)
+				if (!geometry) continue
+				if (geometry.hitTestPoint(point, geometry.isFilled ? 0 : margin, true)) {
+					return overlay
+				}
+			}
+		}
+		return null
+	}
+}

package/src/lib/editor/overlays/OverlayUtil.ts

@@ -0,0 +1,143 @@
+import { TLCursorType } from '@tldraw/tlschema'
+import { Geometry2d } from '../../primitives/geometry/Geometry2d'
+import type { Editor } from '../Editor'
+import { TLPointerEventInfo } from '../types/event-types'
+
+/** @public */
+export interface TLOverlay<Props = Record<string, unknown>> {
+	/**
+	 * Globally unique id for this overlay instance across all overlay utils.
+	 * Hit-test and hover lookup key on `id` alone, so utils must namespace their
+	 * ids (e.g. `'selection_fg:top_left'`, `'handle:<shapeId>:<handleId>'`) to
+	 * avoid colliding with overlays from other utils.
+	 */
+	id: string
+	/** The overlay util type that owns this instance */
+	type: string
+	/** Arbitrary props for the overlay (handle id, corner name, etc.) */
+	props: Props
+}
+
+/** @public */
+export interface TLOverlayUtilConstructor<U extends OverlayUtil = OverlayUtil> {
+	new (editor: Editor): U
+	type: string
+	configure<T extends TLOverlayUtilConstructor<any>>(
+		this: T,
+		options: T extends new (...args: any[]) => { options: infer Options } ? Partial<Options> : never
+	): T
+}
+
+/** @public */
+export type TLAnyOverlayUtilConstructor = TLOverlayUtilConstructor<any>
+
+/**
+ * Base class for overlay utilities. Overlays are ephemeral UI elements rendered
+ * on top of the canvas (selection handles, rotation corners, shape handles, etc.).
+ *
+ * Each OverlayUtil defines a type of overlay and knows how to:
+ * - Determine when its overlays should be active (predicate)
+ * - Produce overlay instances from current editor state
+ * - Provide hit-test geometry for interactive overlays
+ * - Provide cursor style on hover
+ * - Render into a canvas 2D context
+ *
+ * @public
+ */
+export abstract class OverlayUtil<T extends TLOverlay = TLOverlay> {
+	constructor(public editor: Editor) {}
+	static type: string
+
+	/**
+	 * Options for this overlay util. Override this to provide customization options.
+	 * Use {@link OverlayUtil.configure} to customize existing overlay utils.
+	 *
+	 * `zIndex` controls paint and hit-test order across utils — higher numbers
+	 * paint on top and are hit-tested first. Ties resolve by registration order.
+	 * Defaults to `0`; built-in utils use larger integers (100, 200, …) with
+	 * gaps so custom utils can slot between.
+	 *
+	 * @public
+	 */
+	options: { zIndex?: number } = {}
+
+	/**
+	 * Create a new overlay util class with the given options merged in.
+	 *
+	 * @example
+	 * ```ts
+	 * const MyBrush = BrushOverlayUtil.configure({ fill: 'rgba(0,0,255,0.1)' })
+	 * ```
+	 *
+	 * @public
+	 */
+	static configure<T extends TLOverlayUtilConstructor<any>>(
+		this: T,
+		options: T extends new (...args: any[]) => { options: infer Options } ? Partial<Options> : never
+	): T {
+		// @ts-expect-error -- typescript has no idea what's going on here but it's fine
+		return class extends this {
+			// @ts-expect-error
+			options = { ...this.options, ...options }
+		}
+	}
+
+	/**
+	 * Whether this overlay util's overlays should currently be active.
+	 * Checked reactively to determine which overlays exist at any given time.
+	 */
+	abstract isActive(): boolean
+
+	/**
+	 * Returns the overlay instances that currently exist.
+	 * Called only when `isActive()` returns true.
+	 */
+	abstract getOverlays(): T[]
+
+	/**
+	 * Returns hit-test geometry for an overlay instance, in page coordinates.
+	 * Return null for non-interactive overlays (e.g. snap indicators, scribbles).
+	 */
+	getGeometry(_overlay: T): Geometry2d | null {
+		return null
+	}
+
+	/**
+	 * Returns the cursor type to show when hovering this overlay.
+	 */
+	getCursor(_overlay: T): TLCursorType | undefined {
+		return undefined
+	}
+
+	/**
+	 * Called when the user points down on this overlay, before the default
+	 * routing runs. Acts as an interrupt: define it to take over the event.
+	 *
+	 * Return `false` to continue with the default behavior (e.g. the
+	 * built-in rotate/resize handle transitions or shape-handle dispatch).
+	 * Return `true` — or nothing at all — to skip the default. In other
+	 * words, once you override this method you own the event unless you
+	 * explicitly opt back in by returning `false`.
+	 */
+	onPointerDown?(overlay: T, info: TLPointerEventInfo): boolean | void
+
+	/**
+	 * Render all active overlays into the canvas context.
+	 * The context is already transformed to page space (camera transform applied).
+	 * Called reactively when overlays or editor state changes.
+	 */
+	render(_ctx: CanvasRenderingContext2D, _overlays: T[]): void {}
+
+	/**
+	 * Optional: render all active overlays into the minimap canvas.
+	 * The context is already transformed to page space (minimap camera applied),
+	 * so overlays can use the same page-space coordinates as in {@link OverlayUtil.render}.
+	 *
+	 * `zoom` is the minimap's screen-pixels-per-page-unit, analogous to
+	 * `editor.getCamera().z`; use `1 / zoom` for one-minimap-pixel line widths.
+	 *
+	 * Most overlays should leave this blank — only overlays that are meaningful
+	 * at minimap scale (e.g. brushes, collaborator cursors) should opt in.
+	 */
+	renderMinimap(_ctx: CanvasRenderingContext2D, _overlays: T[], _zoom: number): void {}
+}

package/src/lib/editor/overlays/ShapeIndicatorOverlayUtil.ts

@@ -0,0 +1,216 @@
+import { computed } from '@tldraw/state'
+import { createComputedCache } from '@tldraw/store'
+import { TLShape, TLShapeId } from '@tldraw/tlschema'
+import type { Editor } from '../Editor'
+import { OverlayUtil, TLOverlay } from './OverlayUtil'
+
+interface RelevantInstanceFlags {
+	isChangingStyle: boolean
+	isHoveringCanvas: boolean | null
+	isCoarsePointer: boolean
+}
+
+/** @public */
+export interface TLShapeIndicatorOverlay extends TLOverlay {
+	props: {
+		idsToDisplay: TLShapeId[]
+		hintingShapeIds: TLShapeId[]
+	}
+}
+
+const indicatorPathCache = createComputedCache(
+	'shapeIndicatorPath',
+	(editor: Editor, shape: TLShape) => {
+		const util = editor.getShapeUtil(shape)
+		return util.getIndicatorPath(shape)
+	},
+	{
+		areRecordsEqual(a, b) {
+			return a.props === b.props
+		},
+	}
+)
+
+/**
+ * Combine every batchable shape indicator into a single page-space `Path2D` and
+ * emit one stroke call. Shapes whose indicator needs an evenodd clip (e.g.
+ * arrows with labels or complex arrowheads) can't be batched — they still
+ * stroke individually inside a save/restore with `ctx.clip` applied.
+ *
+ * Shared by {@link ShapeIndicatorOverlayUtil} and any overlay util that paints
+ * shape indicators (e.g. collaborator selections).
+ *
+ * @public
+ */
+export function strokeShapeIndicators(
+	editor: Editor,
+	ctx: CanvasRenderingContext2D,
+	shapeIds: TLShapeId[]
+): void {
+	if (shapeIds.length === 0) return
+
+	const batched = new Path2D()
+
+	for (const shapeId of shapeIds) {
+		const shape = editor.getShape(shapeId)
+		if (!shape || shape.isLocked) continue
+
+		const pageTransform = editor.getShapePageTransform(shape)
+		if (!pageTransform) continue
+
+		const indicatorPath = indicatorPathCache.get(editor, shape.id)
+		if (!indicatorPath) continue
+
+		if (indicatorPath instanceof Path2D) {
+			batched.addPath(indicatorPath, pageTransform)
+			continue
+		}
+
+		const { path, clipPath, additionalPaths } = indicatorPath
+
+		if (!clipPath) {
+			batched.addPath(path, pageTransform)
+			if (additionalPaths) {
+				for (const p of additionalPaths) batched.addPath(p, pageTransform)
+			}
+			continue
+		}
+
+		// Clipped case: fall back to an individual stroke. Rare (arrows with
+		// labels / complex arrowheads), so the extra save/restore/stroke
+		// pair per such shape isn't worth batching away.
+		ctx.save()
+		ctx.transform(
+			pageTransform.a,
+			pageTransform.b,
+			pageTransform.c,
+			pageTransform.d,
+			pageTransform.e,
+			pageTransform.f
+		)
+		ctx.save()
+		ctx.clip(clipPath, 'evenodd')
+		ctx.stroke(path)
+		ctx.restore()
+		if (additionalPaths) {
+			for (const p of additionalPaths) ctx.stroke(p)
+		}
+		ctx.restore()
+	}
+
+	ctx.stroke(batched)
+}
+
+/**
+ * Overlay util for shape indicators — the selection / hover / hint outlines drawn
+ * under the selection foreground. Paints local indicators in the theme's
+ * selection color.
+ *
+ * Remote collaborator selection indicators are drawn by a separate overlay util
+ * (e.g. `CollaboratorShapeIndicatorOverlayUtil` from `tldraw`) that runs at a
+ * lower z-index so peer selections appear under the local indicators.
+ *
+ * Non-interactive: contributes no hit-test geometry.
+ *
+ * @public
+ */
+export class ShapeIndicatorOverlayUtil extends OverlayUtil<TLShapeIndicatorOverlay> {
+	static override type = 'shape_indicator'
+	override options = { zIndex: 50, lineWidth: 1.5, hintedLineWidth: 2.5 }
+
+	// Narrow projection of instance state. Reading the full record would
+	// re-fire getOverlays on every cursor move / brush update; gating on these
+	// three booleans means we only re-fire when one of them actually flips.
+	private _instanceFlags$ = computed<RelevantInstanceFlags>(
+		'shape indicator instance flags',
+		() => {
+			const i = this.editor.getInstanceState()
+			return {
+				isChangingStyle: i.isChangingStyle,
+				isHoveringCanvas: i.isHoveringCanvas,
+				isCoarsePointer: i.isCoarsePointer,
+			}
+		},
+		{
+			isEqual: (a, b) =>
+				a.isChangingStyle === b.isChangingStyle &&
+				a.isHoveringCanvas === b.isHoveringCanvas &&
+				a.isCoarsePointer === b.isCoarsePointer,
+		}
+	)
+
+	override isActive(): boolean {
+		return true
+	}
+
+	override getOverlays(): TLShapeIndicatorOverlay[] {
+		const editor = this.editor
+		const renderingShapeIds = new Set(editor.getRenderingShapes().map((s) => s.id))
+
+		// Local selected / hovered indicators.
+		const idsToDisplay: TLShapeId[] = []
+		const { isChangingStyle, isHoveringCanvas, isCoarsePointer } = this._instanceFlags$.get()
+		const isIdleOrEditing = editor.isInAny('select.idle', 'select.editing_shape')
+		const isInSelectState = editor.isInAny(
+			'select.brushing',
+			'select.scribble_brushing',
+			'select.pointing_shape',
+			'select.pointing_selection',
+			'select.pointing_handle'
+		)
+
+		if (!isChangingStyle && (isIdleOrEditing || isInSelectState)) {
+			for (const id of editor.getSelectedShapeIds()) {
+				if (renderingShapeIds.has(id)) idsToDisplay.push(id)
+			}
+			if (isIdleOrEditing && isHoveringCanvas && !isCoarsePointer) {
+				const hovered = editor.getHoveredShapeId()
+				if (hovered && renderingShapeIds.has(hovered) && !idsToDisplay.includes(hovered)) {
+					idsToDisplay.push(hovered)
+				}
+			}
+		}
+
+		// Hinted shapes (drawn thicker). Already deduped at write time in
+		// `updateHintingShapeIds`, so no need to dedupe again here.
+		const hintingShapeIds: TLShapeId[] = []
+		for (const id of editor.getHintingShapeIds()) {
+			if (renderingShapeIds.has(id)) hintingShapeIds.push(id)
+		}
+
+		if (idsToDisplay.length === 0 && hintingShapeIds.length === 0) {
+			return []
+		}
+
+		return [
+			{
+				id: 'shape_indicator',
+				type: 'shape_indicator',
+				props: { idsToDisplay, hintingShapeIds },
+			},
+		]
+	}
+
+	override render(ctx: CanvasRenderingContext2D, overlays: TLShapeIndicatorOverlay[]): void {
+		const overlay = overlays[0]
+		if (!overlay) return
+
+		const editor = this.editor
+		const zoom = editor.getZoomLevel()
+		const { idsToDisplay, hintingShapeIds } = overlay.props
+
+		ctx.lineCap = 'round'
+		ctx.lineJoin = 'round'
+
+		// Local selected / hovered indicators — one stroke call for the whole batch.
+		ctx.strokeStyle = editor.getCurrentTheme().colors[editor.getColorMode()].selectionStroke
+		ctx.lineWidth = this.options.lineWidth / zoom
+		strokeShapeIndicators(editor, ctx, idsToDisplay)
+
+		// Hinted shapes — thicker stroke, one call for the whole batch.
+		if (hintingShapeIds.length > 0) {
+			ctx.lineWidth = this.options.hintedLineWidth / zoom
+			strokeShapeIndicators(editor, ctx, hintingShapeIds)
+		}
+	}
+}

package/src/lib/editor/overlays/getOverlayDisplayValues.ts

@@ -0,0 +1,51 @@
+import { TLTheme } from '@tldraw/tlschema'
+import type { Editor } from '../Editor'
+import { TLOverlay } from './OverlayUtil'
+
+/** @public */
+export interface OverlayOptionsWithDisplayValues<
+	Overlay extends TLOverlay,
+	DisplayValues extends object,
+> {
+	getDefaultDisplayValues(
+		editor: Editor,
+		overlay: Overlay,
+		theme: TLTheme,
+		colorMode: 'light' | 'dark'
+	): DisplayValues
+	getCustomDisplayValues(
+		editor: Editor,
+		overlay: Overlay,
+		theme: TLTheme,
+		colorMode: 'light' | 'dark'
+	): Partial<DisplayValues>
+}
+
+const dvCache = new WeakMap<
+	TLOverlay,
+	{ theme: TLTheme; colorMode: 'light' | 'dark'; values: object }
+>()
+
+/**
+ * Get the resolved display values for an overlay, merging the base values with any overrides.
+ *
+ * @public
+ */
+export function getOverlayDisplayValues<Overlay extends TLOverlay, DisplayValues extends object>(
+	util: { editor: Editor; options: OverlayOptionsWithDisplayValues<Overlay, DisplayValues> },
+	overlay: Overlay,
+	colorMode?: 'light' | 'dark'
+): DisplayValues {
+	const theme = util.editor.getCurrentTheme()
+	const resolvedColorMode = colorMode ?? util.editor.getColorMode()
+	const cached = dvCache.get(overlay)
+	if (cached && cached.theme === theme && cached.colorMode === resolvedColorMode) {
+		return cached.values as DisplayValues
+	}
+	const values = {
+		...util.options.getDefaultDisplayValues(util.editor, overlay, theme, resolvedColorMode),
+		...util.options.getCustomDisplayValues(util.editor, overlay, theme, resolvedColorMode),
+	}
+	dvCache.set(overlay, { theme, colorMode: resolvedColorMode, values })
+	return values
+}