@tldraw/commenting 0.0.0-bootstrap → 5.3.0-canary.31036673d3f8

package/src/canvas/thread-state.test.ts

@@ -0,0 +1,209 @@
+import {
+	Box,
+	commentSchemaRecords,
+	createShapeId,
+	createTLSchema,
+	createTLStore,
+	defaultBindingUtils,
+	defaultShapeUtils,
+	defaultTools,
+	Editor,
+	TLShapeId,
+} from 'tldraw'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { commentsSidebarOpen } from './state'
+import {
+	anchorPagePoint,
+	commentCenterScreenOffset,
+	commentTargetShapeAt,
+	impreciseShapePinInset,
+	IMPRECISE_PIN_INSET_PX,
+	shapeAnchorAt,
+} from './thread-state'
+
+/**
+ * A real editor: the behavior under test is hit-testing against real shape geometry, which is
+ * exactly what a stub can't model.
+ */
+let editor: Editor
+
+beforeEach(() => {
+	editor = new Editor({
+		store: createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
+		shapeUtils: defaultShapeUtils,
+		bindingUtils: defaultBindingUtils,
+		tools: defaultTools,
+		getContainer: () => document.body,
+	})
+	editor.updateViewportScreenBounds(new Box(0, 0, 1000, 1000))
+})
+
+describe('commentTargetShapeAt', () => {
+	it('hits an arrow pointed at near its line', () => {
+		const id = createShapeId()
+		editor.createShape({
+			id,
+			type: 'arrow',
+			x: 100,
+			y: 100,
+			props: { start: { x: 0, y: 0 }, end: { x: 200, y: 0 } },
+		})
+
+		// Dead on the line, and a couple of pixels off it — both are a hit. Without a hit-test
+		// margin only the pixel-perfect click would land, which made arrows uncommentable.
+		expect(commentTargetShapeAt(editor, { x: 200, y: 100 })?.id).toBe(id)
+		expect(commentTargetShapeAt(editor, { x: 200, y: 102 })?.id).toBe(id)
+	})
+
+	it('hits a line shape near its segment', () => {
+		const id = createShapeId()
+		editor.createShape({ id, type: 'line', x: 100, y: 100 })
+
+		const bounds = editor.getShapePageBounds(id)!
+		expect(commentTargetShapeAt(editor, { x: bounds.center.x, y: bounds.center.y })?.id).toBe(id)
+	})
+
+	it('hits inside a hollow shape', () => {
+		const id = createShapeId()
+		editor.createShape({
+			id,
+			type: 'geo',
+			x: 100,
+			y: 100,
+			props: { w: 100, h: 100, fill: 'none' },
+		})
+
+		expect(commentTargetShapeAt(editor, { x: 150, y: 150 })?.id).toBe(id)
+	})
+
+	it('returns undefined on empty canvas', () => {
+		editor.createShape({
+			id: createShapeId(),
+			type: 'arrow',
+			x: 100,
+			y: 100,
+			props: { start: { x: 0, y: 0 }, end: { x: 200, y: 0 } },
+		})
+
+		expect(commentTargetShapeAt(editor, { x: 600, y: 600 })).toBeUndefined()
+	})
+})
+
+/** A 100×100 square whose page bounds are (100,100)–(200,200), unrotated. */
+function createSquare(): TLShapeId {
+	const id = createShapeId()
+	editor.createShape({ id, type: 'geo', x: 100, y: 100, props: { w: 100, h: 100 } })
+	return id
+}
+
+describe('shape anchors under a shape transform', () => {
+	it('carries a precise pin around when the shape rotates', () => {
+		const id = createSquare()
+		// Top-right corner of the square.
+		const anchor = shapeAnchorAt(editor, id, { x: 200, y: 100 }, true)
+		expect(anchor).toMatchObject({ type: 'shape', shapeId: id, x: 1, y: 0, isPrecise: true })
+		expect(anchorPagePoint(editor, anchor)).toMatchObject({ x: 200, y: 100 })
+
+		// A quarter turn about the square's centre takes that corner to the bottom-right. The
+		// square's page bounds don't change, so a pin normalized against them would sit still.
+		editor.rotateShapesBy([id], Math.PI / 2)
+		const rotated = anchorPagePoint(editor, anchor)!
+		expect(rotated.x).toBeCloseTo(200)
+		expect(rotated.y).toBeCloseTo(200)
+	})
+
+	it('records the spot a pin was dropped on a rotated shape', () => {
+		const id = createSquare()
+		editor.rotateShapesBy([id], Math.PI / 2)
+
+		// After the quarter turn the square's local top-right corner sits at the page's bottom-right.
+		const anchor = shapeAnchorAt(editor, id, { x: 200, y: 200 }, true)
+		expect(anchor.type).toBe('shape')
+		if (anchor.type !== 'shape') return
+		expect(anchor.x).toBeCloseTo(1)
+		expect(anchor.y).toBeCloseTo(0)
+
+		const point = anchorPagePoint(editor, anchor)!
+		expect(point.x).toBeCloseTo(200)
+		expect(point.y).toBeCloseTo(200)
+	})
+
+	it('still tracks moves and resizes', () => {
+		const id = createSquare()
+		const anchor = shapeAnchorAt(editor, id, { x: 200, y: 100 }, true)
+
+		editor.updateShape({ id, type: 'geo', x: 300, props: { w: 200 } })
+		expect(anchorPagePoint(editor, anchor)).toMatchObject({ x: 500, y: 100 })
+	})
+
+	it('turns an imprecise pin inset with the shape so it keeps stepping inward', () => {
+		const id = createSquare()
+		const anchor = shapeAnchorAt(editor, id, { x: 200, y: 100 }, false)
+		// The default top-right spot: step left and down, into the square.
+		expect(impreciseShapePinInset(editor, anchor)).toMatchObject({
+			x: -IMPRECISE_PIN_INSET_PX,
+			y: IMPRECISE_PIN_INSET_PX,
+		})
+
+		editor.rotateShapesBy([id], Math.PI / 2)
+		// The corner is now bottom-right, so stepping inward means left and up.
+		const inset = impreciseShapePinInset(editor, anchor)!
+		expect(inset.x).toBeCloseTo(-IMPRECISE_PIN_INSET_PX)
+		expect(inset.y).toBeCloseTo(-IMPRECISE_PIN_INSET_PX)
+	})
+
+	it('hides the pin for a shape that no longer exists', () => {
+		const id = createSquare()
+		const anchor = shapeAnchorAt(editor, id, { x: 200, y: 100 }, true)
+		editor.deleteShape(id)
+		expect(anchorPagePoint(editor, anchor)).toBe(null)
+	})
+})
+
+describe('commentCenterScreenOffset', () => {
+	/** A sidebar element whose left edge sits at `left` client px, in the editor's container. */
+	function mountSidebar(left: number) {
+		const el = document.createElement('div')
+		el.className = 'tlui-cmt-canvas-sidebar'
+		el.getBoundingClientRect = () => ({ left }) as DOMRect
+		document.body.appendChild(el)
+		return el
+	}
+
+	afterEach(() => {
+		document.querySelector('.tlui-cmt-canvas-sidebar')?.remove()
+	})
+
+	it('is zero while the sidebar is closed', () => {
+		mountSidebar(712)
+		expect(commentCenterScreenOffset(editor)).toBe(0)
+	})
+
+	it('is half the covered width, so the pin centers in the uncovered area', () => {
+		commentsSidebarOpen.set(editor, true)
+		// Viewport is 1000px wide; the sidebar covers the rightmost 288px. The centered pin (at
+		// 356px) leaves the thread UI clear of the sidebar, so no nudge is needed.
+		mountSidebar(712)
+		expect(commentCenterScreenOffset(editor)).toBe(144)
+	})
+
+	it('nudges the pin further left when the thread UI would reach the sidebar', () => {
+		commentsSidebarOpen.set(editor, true)
+		// Centered in the uncovered area the pin sits at 300px, and the thread UI (334px wide,
+		// plus the 8px gap) would cross the sidebar's edge — so the pin backs off to 258px.
+		mountSidebar(600)
+		expect(commentCenterScreenOffset(editor)).toBe(500 - 258)
+	})
+
+	it('never nudges the pin past the left edge', () => {
+		commentsSidebarOpen.set(editor, true)
+		// Clearing the sidebar would need a negative pin position; the left inset wins.
+		mountSidebar(300)
+		expect(commentCenterScreenOffset(editor)).toBe(500 - 8)
+	})
+
+	it('is zero while the sidebar element is not mounted', () => {
+		commentsSidebarOpen.set(editor, true)
+		expect(commentCenterScreenOffset(editor)).toBe(0)
+	})
+})

package/src/canvas/thread-state.ts

@@ -1,15 +1,57 @@
-import { BoxModel, Editor, TLCommentAnchor, TLCommentThread, TLShapeId, VecLike } from 'tldraw'
-import { getRegionCommentOptions } from './region-options'
-import { openThreadId } from './state'
+import {
+	BoxModel,
+	Editor,
+	Mat,
+	TLCommentAnchor,
+	TLCommentThread,
+	TLShape,
+	TLShapeId,
+	Vec,
+	VecLike,
+} from 'tldraw'
+import { getCommentingOptions } from './options'
+import { commentsSidebarOpen, openThreadId } from './state'
+import { POPOVER_OFFSET } from './thread-view'
 
-/** Where an imprecise shape comment sits by default: the shape's top-right corner. Overridable. @public */
-export const DEFAULT_IMPRECISE_SHAPE_ANCHOR = { x: 1, y: 0 }
+/** How far an imprecise shape pin steps inside the shape from its anchor spot, in screen px —
+ *  most of the marker sits within the shape, with a small overhang past the corner. */
+export const IMPRECISE_PIN_INSET_PX = 20
 
-/** The default corner a region's pin and composer sit on, as a normalized 0–1 offset (bottom-right).
- *  Overridable per editor via region options; pin position, composer placement, region move, and
- *  which corner has no resize handle all derive from the chosen corner. */
+/** Imprecise shape pins tuck inside the shape rather than hanging off its edge: the marker
+ *  extends up-right of its anchor point, so step it toward the shape's centre. Screen px — the
+ *  pin is screen-fixed while the shape scales with zoom. Null for anchors that need no inset. */
+export function impreciseShapePinInset(
+	editor: Editor,
+	anchor: TLCommentThread['anchor']
+): { x: number; y: number } | null {
+	if (anchor.type !== 'shape' || anchor.isPrecise) return null
+	const spot = getCommentingOptions(editor).impreciseShapeAnchor
+	const inset = {
+		x: Math.sign(0.5 - spot.x) * IMPRECISE_PIN_INSET_PX,
+		y: Math.sign(0.5 - spot.y) * IMPRECISE_PIN_INSET_PX,
+	}
+	// The spot is a corner of the shape's own bounds, so which way "toward the centre" points turns
+	// with the shape: without this a rotated shape's pin would step out of the shape, not into it.
+	const rotation = editor.getShapePageTransform(anchor.shapeId as TLShapeId)?.rotation() ?? 0
+	return rotation === 0 ? inset : Vec.Rot(inset, rotation)
+}
+
+/** The corner a region's pin and composer sit on, as a normalized 0–1 offset (bottom-right). Pin
+ *  position, composer placement, region move, and which corner has no resize handle all derive
+ *  from it. */
 export const REGION_PIN_CORNER: VecLike = { x: 1, y: 1 }
 
+/** A region anchor's pin corner: the corner its creating drag released on, when recorded, else
+ *  {@link REGION_PIN_CORNER}. @internal */
+export function regionAnchorPinCorner(
+	anchor: Extract<TLCommentAnchor, { type: 'region' }>
+): VecLike {
+	if (anchor.pinX !== undefined && anchor.pinY !== undefined) {
+		return { x: anchor.pinX, y: anchor.pinY }
+	}
+	return REGION_PIN_CORNER
+}
+
 /** The page point of a region's pin corner. */
 export function regionPinPoint(region: BoxModel, corner: VecLike = REGION_PIN_CORNER): VecLike {
 	return {
@@ -20,41 +62,68 @@ export function regionPinPoint(region: BoxModel, corner: VecLike = REGION_PIN_CO
 
 /**
  * Where a thread's pin sits on the page, for each anchor kind. Null hides the pin. For imprecise
- * shape anchors the pin uses `impreciseShapeAnchor` (a normalized 0–1 spot, top-right by default)
- * rather than the stored `x`/`y`.
+ * shape anchors the pin uses the editor's {@link CommentingOptions.impreciseShapeAnchor} (a
+ * normalized 0–1 spot, top-right by default) rather than the stored `x`/`y`.
+ *
+ * A shape anchor's `x`/`y` are normalized within the shape's own bounds and resolved through the
+ * shape's page transform, so the pin rides every part of that transform — rotating the shape
+ * carries the pin around with it instead of leaving it behind in the bounding box.
  * @public
  */
 export function anchorPagePoint(
 	editor: Editor,
-	anchor: TLCommentAnchor,
-	impreciseShapeAnchor: { x: number; y: number } = DEFAULT_IMPRECISE_SHAPE_ANCHOR
+	anchor: TLCommentAnchor
 ): { x: number; y: number } | null {
 	switch (anchor.type) {
 		case 'shape': {
-			const bounds = editor.getShapePageBounds(anchor.shapeId as TLShapeId)
-			if (!bounds) return null
-			// Precise pins sit at their stored x/y; imprecise ones at the consumer's default spot.
-			const { x, y } = anchor.isPrecise ? anchor : impreciseShapeAnchor
-			return { x: bounds.minX + x * bounds.w, y: bounds.minY + y * bounds.h }
-		}
-		case 'text-range': {
-			const bounds = editor.getShapePageBounds(anchor.shapeId as TLShapeId)
-			if (!bounds) return null
-			return { x: bounds.maxX, y: bounds.minY }
+			const shape = editor.getShape(anchor.shapeId as TLShapeId)
+			if (!shape) return null
+			const transform = editor.getShapePageTransform(shape)
+			if (!transform) return null
+			const { point, size } = editor.getShapeGeometry(shape).bounds
+			// Precise pins sit at their stored x/y; imprecise ones at the editor's configured spot.
+			const spot = anchor.isPrecise ? anchor : getCommentingOptions(editor).impreciseShapeAnchor
+			return Mat.applyToPoint(transform, Vec.Add(point, Vec.MulV(spot, size)))
 		}
 		case 'point':
 			return { x: anchor.x, y: anchor.y }
 		case 'region':
-			return regionPinPoint(anchor, getRegionCommentOptions(editor).pinCorner)
+			return regionPinPoint(anchor, regionAnchorPinCorner(anchor))
 		case 'page':
 			return null
 	}
 }
 
+/**
+ * The shape a comment placed at a page point should anchor to, or undefined for empty canvas.
+ *
+ * Uses the editor's hit-test margin, the same slack select and hover use. Without it, shapes whose
+ * geometry is an open path — arrows, lines, draw strokes — are unhittable in practice: their
+ * geometry reports a positive distance for every point off the stroke, so a zero margin only
+ * matches a pixel-perfect click right on the line.
+ *
+ * `hitFrameInside` lets a click inside a frame's body anchor to the frame — without it a frame is
+ * hit only on its edge/label (the select-tool convention), so the frame's interior would fall
+ * through to a bare point. A child shape under the pointer still wins (children sort above the
+ * frame), so only a frame's empty interior anchors the frame.
+ *
+ * @internal
+ */
+export function commentTargetShapeAt(editor: Editor, page: VecLike): TLShape | undefined {
+	return editor.getShapeAtPoint(page, {
+		hitInside: true,
+		hitFrameInside: true,
+		margin: editor.getHitTestMargin(),
+	})
+}
+
 /**
  * A shape anchor for a page point. `x`/`y` are the point's normalized (0–1) offset within the
- * shape's page bounds, remembered either way. When `precise` (Alt held) the pin sits at exactly
- * `x`/`y`; otherwise it sits at the consumer's imprecise default (top-right out of the box).
+ * shape's own bounds — taken in the shape's own space, so a pin placed on a rotated shape records
+ * the spot it was dropped on rather than a spot in the bounding box. Remembered either way: when
+ * `precise` the pin sits at exactly `x`/`y`; otherwise it sits at the consumer's imprecise default
+ * (top-right out of the box). Placement gestures get `precise` from the `shouldBePrecise`
+ * commenting option (always precise, by default).
  * @public
  */
 export function shapeAnchorAt(
@@ -63,29 +132,61 @@ export function shapeAnchorAt(
 	page: { x: number; y: number },
 	precise: boolean
 ): TLCommentAnchor {
-	const bounds = editor.getShapePageBounds(shapeId)
-	if (!bounds || bounds.w === 0 || bounds.h === 0) {
+	const shape = editor.getShape(shapeId)
+	const bounds = shape && editor.getShapeGeometry(shape).bounds
+	if (!shape || !bounds || bounds.w === 0 || bounds.h === 0) {
 		return { type: 'shape', shapeId, x: 0.5, y: 0.5, isPrecise: precise }
 	}
+	const local = editor.getPointInShapeSpace(shape, page)
 	return {
 		type: 'shape',
 		shapeId,
-		x: (page.x - bounds.minX) / bounds.w,
-		y: (page.y - bounds.minY) / bounds.h,
+		x: (local.x - bounds.minX) / bounds.w,
+		y: (local.y - bounds.minY) / bounds.h,
 		isPrecise: precise,
 	}
 }
 
 /** Open a thread and bring it into view — switch to its page if needed, then center its pin. @public */
-export function focusThread(
-	editor: Editor,
-	thread: TLCommentThread,
-	impreciseShapeAnchor?: { x: number; y: number }
-): void {
+export function focusThread(editor: Editor, thread: TLCommentThread): void {
 	if (thread.pageId !== editor.getCurrentPageId()) {
 		editor.setCurrentPage(thread.pageId as any)
 	}
 	openThreadId.set(editor, thread.id)
-	const point = anchorPagePoint(editor, thread.anchor, impreciseShapeAnchor)
-	if (point) editor.centerOnPoint(point, { animation: { duration: 200 } })
+	const point = anchorPagePoint(editor, thread.anchor)
+	if (!point) return
+	const offset = commentCenterScreenOffset(editor) / editor.getZoomLevel()
+	editor.centerOnPoint({ x: point.x + offset, y: point.y }, { animation: { duration: 200 } })
+}
+
+/** The left inset a nudged pin never crosses, and the gap kept between thread UI and sidebar. */
+const CENTER_MARGIN_PX = 8
+
+/** How far the open thread UI reaches right of its pin, in screen px: the popover's offset plus
+ *  the thread panel's fixed width (300px, `.tlui-cmt-thread`). */
+const THREAD_UI_EXTENT_PX = POPOVER_OFFSET.thread.x + 300
+
+/**
+ * How far right of a centered-on pin the true viewport center should sit, in screen px. While the
+ * comments sidebar covers the viewport's right edge, centering a pin dead-center puts the thread
+ * popover that opens on it under the sidebar — so centering aims the pin at the middle of the
+ * uncovered area instead, nudged further left if the thread UI would still reach the sidebar, but
+ * never past the viewport's left edge. Zero when the sidebar is closed or not on screen.
+ * @internal
+ */
+export function commentCenterScreenOffset(editor: Editor): number {
+	if (!commentsSidebarOpen.get(editor)) return 0
+	const sidebar = editor.getContainer().querySelector('.tlui-cmt-canvas-sidebar')
+	if (!sidebar) return 0
+	const viewport = editor.getViewportScreenBounds()
+	// Viewport screen bounds are the container's client rect, so this is container-local.
+	const sidebarLeft = sidebar.getBoundingClientRect().left - viewport.x
+	if (sidebarLeft >= viewport.w) return 0
+	// Aim the pin at the middle of the uncovered area, nudged left until the thread UI clears the
+	// sidebar — but never past the left edge (the edge wins when there's no room for both).
+	const pinX = Math.max(
+		Math.min(sidebarLeft / 2, sidebarLeft - CENTER_MARGIN_PX - THREAD_UI_EXTENT_PX),
+		CENTER_MARGIN_PX
+	)
+	return viewport.w / 2 - pinX
 }