@tldraw/editor 3.12.0-canary.485c2dd13354 → 3.12.0-canary.4ecb34d3434d

package/src/lib/editor/Editor.ts

@@ -87,6 +87,7 @@ import {
 	last,
 	lerp,
 	maxBy,
+	minBy,
 	sortById,
 	sortByIndex,
 	structuredClone,
@@ -176,7 +177,7 @@ import {
 	TLImageExportOptions,
 	TLSvgExportOptions,
 } from './types/misc-types'
-import { TLResizeHandle } from './types/selection-types'
+import { TLAdjacentDirection, TLResizeHandle } from './types/selection-types'
 
 /** @public */
 export type TLResizeShapeOptions = Partial<{
@@ -241,10 +242,33 @@ export interface TLEditorOptions {
 	fontAssetUrls?: { [key: string]: string | undefined }
 	/**
 	 * A predicate that should return true if the given shape should be hidden.
+	 *
+	 * @deprecated Use {@link Editor#getShapeVisibility} instead.
+	 *
 	 * @param shape - The shape to check.
 	 * @param editor - The editor instance.
 	 */
 	isShapeHidden?(shape: TLShape, editor: Editor): boolean
+
+	/**
+	 * Provides a way to hide shapes.
+	 *
+	 * @example
+	 * ```ts
+	 * getShapeVisibility={(shape, editor) => shape.meta.hidden ? 'hidden' : 'inherit'}
+	 * ```
+	 *
+	 * - `'inherit' | undefined` - (default) The shape will be visible unless its parent is hidden.
+	 * - `'hidden'` - The shape will be hidden.
+	 * - `'visible'` - The shape will be visible.
+	 *
+	 * @param shape - The shape to check.
+	 * @param editor - The editor instance.
+	 */
+	getShapeVisibility?(
+		shape: TLShape,
+		editor: Editor
+	): 'visible' | 'hidden' | 'inherit' | null | undefined
 }
 
 /**
@@ -281,12 +305,21 @@ export class Editor extends EventEmitter<TLEventMap> {
 		autoFocus,
 		inferDarkMode,
 		options,
+		// eslint-disable-next-line @typescript-eslint/no-deprecated
 		isShapeHidden,
+		getShapeVisibility,
 		fontAssetUrls,
 	}: TLEditorOptions) {
 		super()
+		assert(
+			!(isShapeHidden && getShapeVisibility),
+			'Cannot use both isShapeHidden and getShapeVisibility'
+		)
 
-		this._isShapeHiddenPredicate = isShapeHidden
+		this._getShapeVisibility = isShapeHidden
+			? // eslint-disable-next-line @typescript-eslint/no-deprecated
+				(shape: TLShape, editor: Editor) => (isShapeHidden(shape, editor) ? 'hidden' : 'inherit')
+			: getShapeVisibility
 
 		this.options = { ...defaultTldrawOptions, ...options }
 
@@ -773,18 +806,22 @@ export class Editor extends EventEmitter<TLEventMap> {
 		}
 	}
 
-	private readonly _isShapeHiddenPredicate?: (shape: TLShape, editor: Editor) => boolean
+	private readonly _getShapeVisibility?: TLEditorOptions['getShapeVisibility']
 	@computed
 	private getIsShapeHiddenCache() {
-		if (!this._isShapeHiddenPredicate) return null
+		if (!this._getShapeVisibility) return null
 		return this.store.createComputedCache<boolean, TLShape>('isShapeHidden', (shape: TLShape) => {
-			const hiddenParent = this.findShapeAncestor(shape, (p) => this.isShapeHidden(p))
-			if (hiddenParent) return true
-			return this._isShapeHiddenPredicate!(shape, this) ?? false
+			const visibility = this._getShapeVisibility!(shape, this)
+			const isParentHidden = PageRecordType.isId(shape.parentId)
+				? false
+				: this.isShapeHidden(shape.parentId)
+
+			if (isParentHidden) return visibility !== 'visible'
+			return visibility === 'hidden'
 		})
 	}
 	isShapeHidden(shapeOrId: TLShape | TLShapeId): boolean {
-		if (!this._isShapeHiddenPredicate) return false
+		if (!this._getShapeVisibility) return false
 		return !!this.getIsShapeHiddenCache!()!.get(
 			typeof shapeOrId === 'string' ? shapeOrId : shapeOrId.id
 		)
@@ -1777,6 +1814,195 @@ export class Editor extends EventEmitter<TLEventMap> {
 		return this
 	}
 
+	selectAdjacentShape(direction: TLAdjacentDirection) {
+		const readingOrderShapes = this.getCurrentPageShapesInReadingOrder()
+		const selectedShapeIds = this.getSelectedShapeIds()
+		const currentShapeId: TLShapeId | undefined =
+			selectedShapeIds.length === 1
+				? selectedShapeIds[0]
+				: readingOrderShapes.find((shape) => selectedShapeIds.includes(shape.id))?.id
+
+		let adjacentShapeId: TLShapeId
+		if (direction === 'next' || direction === 'prev') {
+			const shapeIds = readingOrderShapes.map((shape) => shape.id)
+
+			const currentIndex = currentShapeId ? shapeIds.indexOf(currentShapeId) : -1
+			const adjacentIndex =
+				(currentIndex + (direction === 'next' ? 1 : -1) + shapeIds.length) % shapeIds.length
+			adjacentShapeId = shapeIds[adjacentIndex]
+		} else {
+			if (!currentShapeId) return
+			adjacentShapeId = this.getNearestAdjacentShape(currentShapeId, direction)
+		}
+
+		const shape = this.getShape(adjacentShapeId)
+		if (!shape) return
+
+		this.setSelectedShapes([shape.id])
+		this.zoomToSelectionIfOffscreen(256, {
+			animation: {
+				duration: this.options.animationMediumMs,
+			},
+			inset: 0,
+		})
+	}
+
+	/**
+	 * Generates a reading order for shapes based on rows grouping.
+	 * Tries to keep a natural reading order (left-to-right, top-to-bottom).
+	 *
+	 * @public
+	 */
+	@computed getCurrentPageShapesInReadingOrder(): TLShape[] {
+		const SHALLOW_ANGLE = 20
+		const ROW_THRESHOLD = 100
+
+		const shapes = this.getCurrentPageShapes()
+		const tabbableShapes = shapes.filter((shape) => this.getShapeUtil(shape).canTabTo(shape))
+
+		if (tabbableShapes.length <= 1) return tabbableShapes
+
+		const shapesWithCenters = tabbableShapes.map((shape) => ({
+			shape,
+			center: this.getShapePageBounds(shape)!.center,
+		}))
+		shapesWithCenters.sort((a, b) => a.center.y - b.center.y)
+
+		const rows: Array<typeof shapesWithCenters> = []
+
+		// First, group shapes into rows based on y-coordinates.
+		for (const shapeWithCenter of shapesWithCenters) {
+			let rowIndex = -1
+			for (let i = rows.length - 1; i >= 0; i--) {
+				const row = rows[i]
+				const lastShapeInRow = row[row.length - 1]
+
+				// If the shape is close enough vertically to the last shape in this row.
+				if (Math.abs(shapeWithCenter.center.y - lastShapeInRow.center.y) < ROW_THRESHOLD) {
+					rowIndex = i
+					break
+				}
+			}
+
+			// If no suitable row found, create a new row.
+			if (rowIndex === -1) {
+				rows.push([shapeWithCenter])
+			} else {
+				rows[rowIndex].push(shapeWithCenter)
+			}
+		}
+
+		// Then, sort each row by x-coordinate (left-to-right).
+		for (const row of rows) {
+			row.sort((a, b) => a.center.x - b.center.x)
+		}
+
+		// Finally, apply angle/distance weight adjustments within rows for closely positioned shapes.
+		for (const row of rows) {
+			if (row.length <= 2) continue
+
+			for (let i = 0; i < row.length - 2; i++) {
+				const currentShape = row[i]
+				const nextShape = row[i + 1]
+				const nextNextShape = row[i + 2]
+
+				// Only consider adjustment if the next two shapes are relatively close to each other.
+				const dist1 = Vec.Dist2(currentShape.center, nextShape.center)
+				const dist2 = Vec.Dist2(currentShape.center, nextNextShape.center)
+
+				// Check if the 2nd shape is actually closer to the current shape.
+				if (dist2 < dist1 * 0.9) {
+					// Check if it's a shallow enough angle.
+					const angle = Math.abs(
+						Vec.Angle(currentShape.center, nextNextShape.center) * (180 / Math.PI)
+					)
+					if (angle <= SHALLOW_ANGLE) {
+						// Swap swap.
+						;[row[i + 1], row[i + 2]] = [row[i + 2], row[i + 1]]
+					}
+				}
+			}
+		}
+
+		return rows.flat().map((item) => item.shape)
+	}
+
+	/**
+	 * Find the nearest adjacent shape in a specific direction.
+	 *
+	 * @public
+	 */
+	getNearestAdjacentShape(
+		currentShapeId: TLShapeId,
+		direction: 'left' | 'right' | 'up' | 'down'
+	): TLShapeId {
+		const directionToAngle = { right: 0, left: 180, down: 90, up: 270 }
+		const currentShape = this.getShape(currentShapeId)
+		if (!currentShape) return currentShapeId
+
+		const shapes = this.getCurrentPageShapes()
+		const tabbableShapes = shapes.filter(
+			(shape) => this.getShapeUtil(shape).canTabTo(shape) && shape.id !== currentShapeId
+		)
+		if (!tabbableShapes.length) return currentShapeId
+
+		const currentCenter = this.getShapePageBounds(currentShape)!.center
+		const shapesWithCenters = tabbableShapes.map((shape) => ({
+			shape,
+			center: this.getShapePageBounds(shape)!.center,
+		}))
+
+		// Filter shapes that are in the same direction.
+		const shapesInDirection = shapesWithCenters.filter(({ center }) => {
+			const isRight = center.x > currentCenter.x
+			const isDown = center.y > currentCenter.y
+			const xDist = center.x - currentCenter.x
+			const yDist = center.y - currentCenter.y
+			const isInXDirection = Math.abs(yDist) < Math.abs(xDist) * 2
+			const isInYDirection = Math.abs(xDist) < Math.abs(yDist) * 2
+			if (direction === 'left' || direction === 'right') {
+				return isInXDirection && (direction === 'right' ? isRight : !isRight)
+			}
+			if (direction === 'up' || direction === 'down') {
+				return isInYDirection && (direction === 'down' ? isDown : !isDown)
+			}
+		})
+
+		if (shapesInDirection.length === 0) return currentShapeId
+
+		// Ok, now score that subset of shapes.
+		const lowestScoringShape = minBy(shapesInDirection, ({ center }) => {
+			// Distance is the primary weighting factor.
+			const distance = Vec.Dist2(currentCenter, center)
+
+			// Distance along the primary axis.
+			const dirProp = ['left', 'right'].includes(direction) ? 'x' : 'y'
+			const directionalDistance = Math.abs(center[dirProp] - currentCenter[dirProp])
+
+			// Distance off the perpendicular to the primary axis.
+			const offProp = ['left', 'right'].includes(direction) ? 'y' : 'x'
+			const offAxisDeviation = Math.abs(center[offProp] - currentCenter[offProp])
+
+			// Angle in degrees
+			const angle = Math.abs(Vec.Angle(currentCenter, center) * (180 / Math.PI))
+			const angleDeviation = Math.abs(angle - directionToAngle[direction])
+
+			// Calculate final score (lower is better).
+			// Weight factors to prioritize:
+			// 1. Shapes directly in line with the current shape
+			// 2. Shapes closer to the current shape
+			// 3. Shapes with less angular deviation from the primary direction
+			return (
+				distance * 1.0 + // Base distance
+				offAxisDeviation * 2.0 + // Heavy penalty for off-axis deviation
+				(distance - directionalDistance) * 1.5 + // Penalty for diagonal distance
+				angleDeviation * 0.5
+			) // Slight penalty for angular deviation
+		})
+
+		return lowestScoringShape!.shape.id
+	}
+
 	/**
 	 * Clear the selection.
 	 *
@@ -3018,6 +3244,34 @@ export class Editor extends EventEmitter<TLEventMap> {
 		return this
 	}
 
+	/**
+	 * Zoom the camera to the current selection if offscreen.
+	 *
+	 * @public
+	 */
+	zoomToSelectionIfOffscreen(
+		padding = 16,
+		opts?: { targetZoom?: number; inset?: number } & TLCameraMoveOptions
+	) {
+		const selectionPageBounds = this.getSelectionPageBounds()
+		const viewportPageBounds = this.getViewportPageBounds()
+		if (selectionPageBounds && !viewportPageBounds.contains(selectionPageBounds)) {
+			const eb = selectionPageBounds
+				.clone()
+				// Expand the bounds by the padding
+				.expandBy(padding / this.getZoomLevel())
+				// then expand the bounds to include the viewport bounds
+				.expand(viewportPageBounds)
+
+			// then use the difference between the centers to calculate the offset
+			const nextBounds = viewportPageBounds.clone().translate({
+				x: (eb.center.x - viewportPageBounds.center.x) * 2,
+				y: (eb.center.y - viewportPageBounds.center.y) * 2,
+			})
+			this.zoomToBounds(nextBounds, opts)
+		}
+	}
+
 	/**
 	 * Zoom the camera to fit a bounding box (in the current page space).
 	 *
@@ -3711,7 +3965,15 @@ export class Editor extends EventEmitter<TLEventMap> {
 		const addShapeById = (id: TLShapeId, opacity: number, isAncestorErasing: boolean) => {
 			const shape = this.getShape(id)
 			if (!shape) return
-			if (this.isShapeHidden(shape)) return
+
+			if (this.isShapeHidden(shape)) {
+				// process children just in case they are overriding the hidden state
+				const isErasing = isAncestorErasing || erasingShapeIds.includes(id)
+				for (const childId of this.getSortedChildIdsForParent(id)) {
+					addShapeById(childId, opacity, isErasing)
+				}
+				return
+			}
 
 			opacity *= shape.opacity
 			let isShapeErasing = false
@@ -4286,7 +4548,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 	private _shapeGeometryCaches: Record<string, ComputedCache<Geometry2d, TLShape>> = {}
 
 	/**
-	 * Get the geometry of a shape.
+	 * Get the geometry of a shape in shape-space.
 	 *
 	 * @example
 	 * ```ts
@@ -4317,6 +4579,44 @@ export class Editor extends EventEmitter<TLEventMap> {
 		)! as T
 	}
 
+	private _shapePageGeometryCaches: Record<string, ComputedCache<Geometry2d, TLShape>> = {}
+
+	/**
+	 * Get the geometry of a shape in page-space.
+	 *
+	 * @example
+	 * ```ts
+	 * editor.getShapePageGeometry(myShape)
+	 * editor.getShapePageGeometry(myShapeId)
+	 * editor.getShapePageGeometry(myShapeId, { context: "arrow" })
+	 * ```
+	 *
+	 * @param shape - The shape (or shape id) to get the geometry for.
+	 * @param opts - Additional options about the request for geometry. Passed to {@link ShapeUtil.getGeometry}.
+	 *
+	 * @public
+	 */
+	getShapePageGeometry<T extends Geometry2d>(shape: TLShape | TLShapeId, opts?: TLGeometryOpts): T {
+		const context = opts?.context ?? 'none'
+		if (!this._shapePageGeometryCaches[context]) {
+			this._shapePageGeometryCaches[context] = this.store.createComputedCache(
+				'bounds',
+				(shape) => {
+					const geometry = this.getShapeGeometry(shape.id, opts)
+					const pageTransform = this.getShapePageTransform(shape.id)
+					return geometry.transform(pageTransform)
+				},
+				{
+					// we only depend directly on the shape id, and changing geometry/transform will update us anyway
+					areRecordsEqual: () => true,
+				}
+			)
+		}
+		return this._shapePageGeometryCaches[context].get(
+			typeof shape === 'string' ? shape : shape.id
+		)! as T
+	}
+
 	/** @internal */
 	@computed private _getShapeHandlesCache(): ComputedCache<TLHandle[] | undefined, TLShape> {
 		return this.store.createComputedCache('handles', (shape) => {
@@ -4423,15 +4723,7 @@ export class Editor extends EventEmitter<TLEventMap> {
 	/** @internal */
 	@computed private _getShapePageBoundsCache(): ComputedCache<Box, TLShape> {
 		return this.store.createComputedCache<Box, TLShape>('pageBoundsCache', (shape) => {
-			const pageTransform = this._getShapePageTransformCache().get(shape.id)
-
-			if (!pageTransform) return new Box()
-
-			const result = Box.FromPoints(
-				Mat.applyToPoints(pageTransform, this.getShapeGeometry(shape).vertices)
-			)
-
-			return result
+			return this.getShapePageGeometry(shape).bounds
 		})
 	}
 
@@ -4505,11 +4797,10 @@ export class Editor extends EventEmitter<TLEventMap> {
 			if (frameAncestors.length === 0) return undefined
 
 			const pageMask = frameAncestors
-				.map<Vec[] | undefined>((s) =>
-					// Apply the frame transform to the frame outline to get the frame outline in the current page space
-					this._getShapePageTransformCache()
-						.get(s.id)!
-						.applyToPoints(this.getShapeGeometry(s).vertices)
+				.map<Vec[] | undefined>(
+					(s) =>
+						// Apply the frame transform to the frame outline to get the frame outline in the current page space
+						this.getShapePageGeometry(s.id).vertices
 				)
 				.reduce((acc, b) => {
 					if (!(b && acc)) return undefined

package/src/lib/editor/shapes/ShapeUtil.ts

@@ -193,6 +193,16 @@ export abstract class ShapeUtil<Shape extends TLUnknownShape = TLUnknownShape> {
 		return true
 	}
 
+	/**
+	 * Whether the shape can be tabbed to.
+	 *
+	 * @param shape - The shape.
+	 * @public
+	 */
+	canTabTo(_shape: Shape): boolean {
+		return true
+	}
+
 	/**
 	 * Whether the shape can be scrolled while editing.
 	 *
@@ -438,6 +448,10 @@ export abstract class ShapeUtil<Shape extends TLUnknownShape = TLUnknownShape> {
 		return undefined
 	}
 
+	getAriaDescriptor(_shape: Shape): string | undefined {
+		return undefined
+	}
+
 	//  Events
 
 	/**

package/src/lib/editor/shapes/group/GroupShapeUtil.tsx

@@ -2,8 +2,6 @@ import { TLGroupShape, groupShapeMigrations, groupShapeProps } from '@tldraw/tls
 import { SVGContainer } from '../../../components/SVGContainer'
 import { Geometry2d } from '../../../primitives/geometry/Geometry2d'
 import { Group2d } from '../../../primitives/geometry/Group2d'
-import { Polygon2d } from '../../../primitives/geometry/Polygon2d'
-import { Polyline2d } from '../../../primitives/geometry/Polyline2d'
 import { Rectangle2d } from '../../../primitives/geometry/Rectangle2d'
 import { ShapeUtil } from '../ShapeUtil'
 import { DashedOutlineBox } from './DashedOutlineBox'
@@ -14,6 +12,10 @@ export class GroupShapeUtil extends ShapeUtil<TLGroupShape> {
 	static override props = groupShapeProps
 	static override migrations = groupShapeMigrations
 
+	override canTabTo() {
+		return false
+	}
+
 	override hideSelectionBoundsFg() {
 		return true
 	}
@@ -35,19 +37,9 @@ export class GroupShapeUtil extends ShapeUtil<TLGroupShape> {
 		return new Group2d({
 			children: children.map((childId) => {
 				const shape = this.editor.getShape(childId)!
-				const geometry = this.editor.getShapeGeometry(childId)
-				const points = this.editor.getShapeLocalTransform(shape)!.applyToPoints(geometry.vertices)
-
-				if (geometry.isClosed) {
-					return new Polygon2d({
-						points,
-						isFilled: true,
-					})
-				}
-
-				return new Polyline2d({
-					points,
-				})
+				return this.editor
+					.getShapeGeometry(childId)
+					.transform(this.editor.getShapeLocalTransform(shape)!)
 			}),
 		})
 	}

package/src/lib/editor/types/selection-types.ts

@@ -5,3 +5,6 @@ export type TLSelectionHandle = SelectionCorner | SelectionEdge | RotateCorner
 
 /** @public */
 export type TLResizeHandle = SelectionCorner | SelectionEdge
+
+/** @public */
+export type TLAdjacentDirection = 'next' | 'prev' | 'left' | 'right' | 'up' | 'down'

package/src/lib/exports/StyleEmbedder.ts

@@ -1,5 +1,6 @@
-import { assertExists, objectMapValues, uniqueId } from '@tldraw/utils'
+import { assertExists, getOwnProperty, objectMapValues, uniqueId } from '@tldraw/utils'
 import { FontEmbedder } from './FontEmbedder'
+import { ReadonlyStyles, Styles, cssRules } from './cssRules'
 import {
 	elementStyle,
 	getComputedStyle,
@@ -7,15 +8,8 @@ import {
 	getRenderedChildren,
 } from './domUtils'
 import { resourceToDataUrl } from './fetchCache'
-import {
-	isPropertyCoveredByCurrentColor,
-	isPropertyInherited,
-	parseCssValueUrls,
-	shouldIncludeCssProperty,
-} from './parseCss'
-
-type Styles = { [K in string]?: string }
-type ReadonlyStyles = { readonly [K in string]?: string }
+import { parseCssValueUrls, shouldIncludeCssProperty } from './parseCss'
+
 const NO_STYLES = {} as const
 
 interface ElementStyleInfo {
@@ -239,15 +233,22 @@ function styleFromComputedStyleMap(
 	{ defaultStyles, parentStyles }: ReadStyleOpts
 ) {
 	const styles: Record<string, string> = {}
+	const currentColor = style.get('color')?.toString() || ''
+	const ruleOptions = {
+		currentColor,
+		parentStyles,
+		defaultStyles,
+		getStyle: (property: string) => style.get(property)?.toString() ?? '',
+	}
 	for (const property of style.keys()) {
 		if (!shouldIncludeCssProperty(property)) continue
 
 		const value = style.get(property)!.toString()
 
 		if (defaultStyles[property] === value) continue
-		if (parentStyles[property] === value && isPropertyInherited(property)) continue
-		if (isPropertyCoveredByCurrentColor(style.get('color')?.toString() || '', property, value))
-			continue
+
+		const rule = getOwnProperty(cssRules, property)
+		if (rule && rule(value, property, ruleOptions)) continue
 
 		styles[property] = value
 	}
@@ -260,14 +261,23 @@ function styleFromComputedStyle(
 	{ defaultStyles, parentStyles }: ReadStyleOpts
 ) {
 	const styles: Record<string, string> = {}
+	const currentColor = style.color
+	const ruleOptions = {
+		currentColor,
+		parentStyles,
+		defaultStyles,
+		getStyle: (property: string) => style.getPropertyValue(property),
+	}
+
 	for (const property in style) {
 		if (!shouldIncludeCssProperty(property)) continue
 
 		const value = style.getPropertyValue(property)
 
 		if (defaultStyles[property] === value) continue
-		if (parentStyles[property] === value && isPropertyInherited(property)) continue
-		if (isPropertyCoveredByCurrentColor(style.color, property, value)) continue
+
+		const rule = getOwnProperty(cssRules, property)
+		if (rule && rule(value, property, ruleOptions)) continue
 
 		styles[property] = value
 	}