@tldraw/commenting 0.0.0-bootstrap → 5.3.0-canary.04044ed9e96d

package/src/canvas/anchor-lifecycle.test.ts

@@ -0,0 +1,290 @@
+import {
+	commentSchemaRecords,
+	createCommentThread,
+	createShapeId,
+	createTLSchema,
+	createTLStore,
+	defaultBindingUtils,
+	defaultShapeUtils,
+	defaultTools,
+	Editor,
+	toRichText,
+	createComment as tlCreateComment,
+	TLPageId,
+	TLShapeId,
+} from 'tldraw'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { registerCommentAnchorLifecycle } from './anchor-lifecycle'
+import { commitCommentMutation, putCommentRecords } from './comment-mutations'
+import { getCommentRecord, getComments } from './comment-store'
+import { CommentTool } from './comment-tool'
+
+/**
+ * These tests need a real editor: the behavior under test is the interplay between store
+ * side effects (the beforeDelete snapshot, operation-complete settlement) and real editor
+ * operations like `deleteShapes` and `moveShapesToPage` — exactly what a stub can't model.
+ */
+
+let editor: Editor
+let dispose: () => void
+
+beforeEach(() => {
+	editor = new Editor({
+		store: createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
+		shapeUtils: defaultShapeUtils,
+		bindingUtils: defaultBindingUtils,
+		tools: defaultTools,
+		getContainer: () => document.body,
+	})
+	dispose = registerCommentAnchorLifecycle(editor)
+})
+
+afterEach(() => {
+	dispose()
+	editor.dispose()
+})
+
+function makeShape(x = 100, y = 100, w = 100, h = 50): TLShapeId {
+	const id = createShapeId()
+	editor.createShape({ id, type: 'geo', x, y, props: { w, h } })
+	return id
+}
+
+function makeThread(shapeId: TLShapeId, anchorX = 0.5, anchorY = 0.5, isPrecise = true) {
+	const thread = createCommentThread({
+		pageId: editor.getCurrentPageId(),
+		anchor: { type: 'shape', shapeId, x: anchorX, y: anchorY, isPrecise },
+		createdBy: 'me',
+	})
+	const comment = tlCreateComment({
+		threadId: thread.id,
+		pageId: thread.pageId,
+		authorId: 'me',
+		body: toRichText('hello'),
+	})
+	putCommentRecords(editor, [thread, comment])
+	return { thread, comment }
+}
+
+function makeSecondPage(): TLPageId {
+	editor.createPage({ name: 'page 2' })
+	return editor.getPages()[1].id
+}
+
+describe('shape deletion', () => {
+	it('converts a precise shape anchor to a point anchor where the pin sat', () => {
+		const shapeId = makeShape(100, 100, 100, 50)
+		const { thread } = makeThread(shapeId, 0.5, 0.5, true)
+
+		editor.deleteShape(shapeId)
+
+		const updated = getCommentRecord(editor, thread.id)!
+		expect(updated.typeName).toBe('comment-thread')
+		expect((updated as typeof thread).anchor).toEqual({ type: 'point', x: 150, y: 125 })
+	})
+
+	it('converts an imprecise shape anchor where the inset pin is drawn, not at the raw corner', () => {
+		const shapeId = makeShape(100, 100, 100, 50)
+		const { thread } = makeThread(shapeId, 0.2, 0.9, false)
+
+		editor.deleteShape(shapeId)
+
+		// Top-right corner (200, 100) plus the 20px screen inset toward the shape's centre.
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual({ type: 'point', x: 180, y: 120 })
+	})
+
+	it('resolves the imprecise spot from the commenting options when no override is passed', () => {
+		const configured = new Editor({
+			store: createTLStore({ schema: createTLSchema({ records: commentSchemaRecords }) }),
+			shapeUtils: defaultShapeUtils,
+			bindingUtils: defaultBindingUtils,
+			tools: [...defaultTools, CommentTool.configure({ impreciseShapeAnchor: { x: 0, y: 1 } })],
+			getContainer: () => document.body,
+		})
+		const disposeConfigured = registerCommentAnchorLifecycle(configured)
+		try {
+			const shapeId = createShapeId()
+			configured.createShape({ id: shapeId, type: 'geo', x: 100, y: 100, props: { w: 100, h: 50 } })
+			const thread = createCommentThread({
+				pageId: configured.getCurrentPageId(),
+				anchor: { type: 'shape', shapeId, x: 0.5, y: 0.5, isPrecise: false },
+				createdBy: 'me',
+			})
+			putCommentRecords(configured, [thread])
+
+			configured.deleteShape(shapeId)
+
+			// Bottom-left corner (100, 150) plus the inset toward the shape's centre.
+			const updated = getCommentRecord(configured, thread.id) as typeof thread
+			expect(updated.anchor).toEqual({ type: 'point', x: 120, y: 130 })
+		} finally {
+			disposeConfigured()
+			configured.dispose()
+		}
+	})
+
+	it('converts anchors on children when their frame is deleted with them', () => {
+		const frameId = createShapeId()
+		editor.createShape({ id: frameId, type: 'frame', x: 0, y: 0, props: { w: 400, h: 400 } })
+		const childId = createShapeId()
+		editor.createShape({
+			id: childId,
+			type: 'geo',
+			parentId: frameId,
+			x: 50,
+			y: 50,
+			props: { w: 100, h: 100 },
+		})
+		const { thread } = makeThread(childId, 0.5, 0.5, true)
+
+		editor.deleteShape(frameId)
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual({ type: 'point', x: 100, y: 100 })
+	})
+
+	it('re-attaches the thread when the delete is undone', () => {
+		const shapeId = makeShape(100, 100, 100, 50)
+		const { thread } = makeThread(shapeId, 0.5, 0.5, true)
+		editor.markHistoryStoppingPoint()
+
+		editor.deleteShape(shapeId)
+		expect((getCommentRecord(editor, thread.id) as typeof thread).anchor.type).toBe('point')
+
+		editor.undo()
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual(thread.anchor)
+	})
+
+	it('keeps the restore when a returning shape cannot resolve its page yet', () => {
+		const frameId = createShapeId()
+		editor.createShape({ id: frameId, type: 'frame', x: 0, y: 0, props: { w: 400, h: 400 } })
+		const childId = createShapeId()
+		editor.createShape({
+			id: childId,
+			type: 'geo',
+			parentId: frameId,
+			x: 50,
+			y: 50,
+			props: { w: 100, h: 100 },
+		})
+		const { thread } = makeThread(childId, 0.5, 0.5, true)
+		const childRecord = editor.getShape(childId)!
+		const frameRecord = editor.getShape(frameId)!
+
+		editor.deleteShape(frameId)
+		expect((getCommentRecord(editor, thread.id) as typeof thread).anchor.type).toBe('point')
+
+		// The child returns in an earlier operation than its parent, so its ancestor page can't
+		// resolve when it first reappears.
+		editor.store.put([childRecord])
+		editor.store.put([frameRecord])
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual(thread.anchor)
+	})
+
+	it('re-attaches on undo even when the lifecycle was re-registered in between', () => {
+		const shapeId = makeShape(100, 100, 100, 50)
+		const { thread } = makeThread(shapeId, 0.5, 0.5, true)
+		editor.markHistoryStoppingPoint()
+
+		editor.deleteShape(shapeId)
+		expect((getCommentRecord(editor, thread.id) as typeof thread).anchor.type).toBe('point')
+
+		// The registering effect re-runs whenever its inputs change identity; conversion memory
+		// must not live and die with any one registration.
+		dispose()
+		dispose = registerCommentAnchorLifecycle(editor)
+
+		editor.undo()
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual(thread.anchor)
+	})
+
+	it('does not re-attach on undo when the pin was moved after the conversion', () => {
+		const shapeId = makeShape(100, 100, 100, 50)
+		const { thread } = makeThread(shapeId, 0.5, 0.5, true)
+		editor.markHistoryStoppingPoint()
+
+		editor.deleteShape(shapeId)
+		const converted = getCommentRecord(editor, thread.id) as typeof thread
+		commitCommentMutation(editor, ({ put }) =>
+			put([{ ...converted, anchor: { type: 'point', x: 900, y: 900 } }])
+		)
+
+		editor.undo()
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor).toEqual({ type: 'point', x: 900, y: 900 })
+	})
+
+	it('leaves threads on other shapes untouched', () => {
+		const shapeId = makeShape()
+		const otherId = makeShape(300, 300)
+		const { thread } = makeThread(otherId)
+
+		editor.deleteShape(shapeId)
+
+		const updated = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updated.anchor.type).toBe('shape')
+	})
+})
+
+describe('moving a shape to another page', () => {
+	it('re-homes the thread and its comments to the new page, keeping the shape anchor', () => {
+		const shapeId = makeShape()
+		const { thread, comment } = makeThread(shapeId)
+		const page2 = makeSecondPage()
+
+		editor.moveShapesToPage([shapeId], page2)
+
+		const updatedThread = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updatedThread.pageId).toBe(page2)
+		expect(updatedThread.anchor).toEqual(thread.anchor)
+		const updatedComment = getComments(editor).find((c) => c.id === comment.id)!
+		expect(updatedComment.pageId).toBe(page2)
+	})
+
+	it('re-homes threads anchored to children of a moved frame', () => {
+		const frameId = createShapeId()
+		editor.createShape({ id: frameId, type: 'frame', x: 0, y: 0, props: { w: 400, h: 400 } })
+		const childId = createShapeId()
+		editor.createShape({
+			id: childId,
+			type: 'geo',
+			parentId: frameId,
+			x: 50,
+			y: 50,
+			props: { w: 100, h: 100 },
+		})
+		const { thread } = makeThread(childId)
+		const page2 = makeSecondPage()
+
+		editor.moveShapesToPage([frameId], page2)
+
+		const updatedThread = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updatedThread.pageId).toBe(page2)
+		expect(updatedThread.anchor.type).toBe('shape')
+	})
+
+	it('re-homes the thread back when the move is undone', () => {
+		const shapeId = makeShape()
+		const { thread } = makeThread(shapeId)
+		const page1 = editor.getCurrentPageId()
+		const page2 = makeSecondPage()
+		editor.markHistoryStoppingPoint()
+
+		editor.moveShapesToPage([shapeId], page2)
+		expect((getCommentRecord(editor, thread.id) as typeof thread).pageId).toBe(page2)
+
+		editor.undo()
+
+		const updatedThread = getCommentRecord(editor, thread.id) as typeof thread
+		expect(updatedThread.pageId).toBe(page1)
+		expect(updatedThread.anchor.type).toBe('shape')
+	})
+})

package/src/canvas/anchor-lifecycle.ts

@@ -0,0 +1,191 @@
+import { WeakCache } from '@tldraw/utils'
+import { Editor, TLCommentAnchor, TLCommentThread, TLPageId, TLShapeId, VecLike } from 'tldraw'
+import { commitCommentMutation } from './comment-mutations'
+import { getCommentRecord, getComments, getCommentThreads, TLCommentRecord } from './comment-store'
+import { anchorPagePoint, impreciseShapePinInset } from './thread-state'
+
+type ShapeAnchor = Extract<TLCommentAnchor, { type: 'shape' }>
+
+/**
+ * Threads converted to point anchors because their shape was deleted, kept so the anchor can be
+ * restored if the shape comes back. Owned by the editor, not the registration closure: the
+ * registering effect can re-run, and an undo can arrive long after the delete.
+ */
+const convertedByShapeCache = new WeakCache<
+	Editor,
+	Map<TLShapeId, { threadId: string; anchor: ShapeAnchor; point: VecLike }[]>
+>()
+
+function isAnchoredToShape(
+	thread: TLCommentThread,
+	shapeId: TLShapeId
+): thread is TLCommentThread & { anchor: ShapeAnchor } {
+	const anchor = thread.anchor
+	return anchor.type === 'shape' && anchor.shapeId === shapeId
+}
+
+/**
+ * Keep shape-anchored threads alive across their shape's lifecycle:
+ *
+ * - When the shape is deleted, the thread converts to a `point` anchor where its pin last sat, so
+ *   the conversation outlives the shape instead of becoming invisible.
+ * - When the shape moves to another page, the thread follows: its `pageId` and each comment's
+ *   denormalized `pageId` update, and the anchor keeps riding the shape.
+ * - When a deleted shape comes back, the thread re-attaches — unless its pin was manually moved in
+ *   the meantime, in which case the manual placement wins.
+ *
+ * A page move is `deleteShapes` + re-create with preserved ids inside one `editor.run`, but each
+ * store write is its own operation, so "this shape is being moved" is never observable as a single
+ * event. The handlers therefore cooperate across operations: `beforeDelete` snapshots where each
+ * affected pin sits, the operation-complete pass converts threads whose shape is really gone, and
+ * `afterCreate` plus that same pass restore the anchor once the store has settled. Undo/redo of a
+ * move replays as a `parentId` update, so `afterChange` re-homes threads on cross-page reparents —
+ * including threads anchored to descendants, which move without change events of their own.
+ *
+ * Remote changes are ignored: the client that performed the operation runs this same maintenance
+ * and syncs the result. Writes honour the {@link CommentingOptions.history} option.
+ *
+ * Registered by `CanvasComments` on mount; parts-built consumers can call this directly. Returns a
+ * cleanup function that unregisters all handlers.
+ *
+ * @public
+ */
+export function registerCommentAnchorLifecycle(editor: Editor): () => void {
+	// Pin positions snapshotted during the current operation: shape id -> (thread id -> pin page
+	// point).
+	const pendingByShape = new Map<TLShapeId, Map<string, VecLike | null>>()
+	const convertedByShape = convertedByShapeCache.get(editor, () => new Map())
+
+	function rehomeThread(thread: TLCommentThread, pageId: TLPageId, updates: TLCommentRecord[]) {
+		updates.push({ ...thread, pageId })
+		for (const comment of getComments(editor)) {
+			if (comment.threadId === thread.id) updates.push({ ...comment, pageId })
+		}
+	}
+
+	const disposeBeforeDelete = editor.sideEffects.registerBeforeDeleteHandler(
+		'shape',
+		(shape, source) => {
+			if (source === 'remote') return
+			for (const thread of getCommentThreads(editor)) {
+				if (!isAnchoredToShape(thread, shape.id)) continue
+				let snapshot = pendingByShape.get(shape.id)
+				if (!snapshot) {
+					snapshot = new Map()
+					pendingByShape.set(shape.id, snapshot)
+				}
+				// Snapshot where the pin is drawn, not just the anchor point: imprecise shape pins render inset
+				// toward the shape's centre, so without baking the inset in at the current zoom the pin would jump.
+				let point = anchorPagePoint(editor, thread.anchor)
+				const inset = impreciseShapePinInset(editor, thread.anchor)
+				if (point && inset) {
+					const zoom = editor.getZoomLevel()
+					point = { x: point.x + inset.x / zoom, y: point.y + inset.y / zoom }
+				}
+				snapshot.set(thread.id, point)
+			}
+		}
+	)
+
+	// Shape ids from `convertedByShape` re-created during the current operation. Settled at operation
+	// complete rather than in `afterCreate`: creation order within an operation is arbitrary, so a shape
+	// can appear before its parent and not resolve an ancestor page yet.
+	const returnedShapeIds = new Set<TLShapeId>()
+
+	const disposeOperationComplete = editor.sideEffects.registerOperationCompleteHandler((source) => {
+		// Only user-sourced handlers populate the maps and only local operations should settle
+		// them; a remote operation completing leaves any (impossible-in-practice) leftovers for
+		// the next local settle rather than judging them against remote state.
+		if (source === 'remote') return
+		if (pendingByShape.size === 0 && returnedShapeIds.size === 0) return
+		const settled = [...pendingByShape.entries()]
+		pendingByShape.clear()
+		const returned = [...returnedShapeIds]
+		returnedShapeIds.clear()
+
+		const updates: TLCommentRecord[] = []
+		for (const [shapeId, threadPoints] of settled) {
+			if (editor.getShape(shapeId)) continue
+			for (const [threadId, point] of threadPoints) {
+				if (!point) continue
+				const thread = getCommentRecord(editor, threadId)
+				if (!thread || thread.typeName !== 'comment-thread') continue
+				if (!isAnchoredToShape(thread, shapeId)) continue
+				let converted = convertedByShape.get(shapeId)
+				if (!converted) {
+					converted = []
+					convertedByShape.set(shapeId, converted)
+				}
+				converted.push({ threadId, anchor: thread.anchor, point })
+				updates.push({ ...thread, anchor: { type: 'point', x: point.x, y: point.y } })
+			}
+		}
+
+		for (const shapeId of returned) {
+			const shape = editor.getShape(shapeId)
+			if (!shape) continue
+			const converted = convertedByShape.get(shapeId)
+			if (!converted) continue
+			convertedByShape.delete(shapeId)
+
+			const pageId = editor.getAncestorPageId(shape)
+			for (const { threadId, anchor, point } of converted) {
+				const thread = getCommentRecord(editor, threadId)
+				if (!thread || thread.typeName !== 'comment-thread') continue
+				// Re-attach only threads still sitting exactly where the conversion left them — a
+				// pin moved since then was placed deliberately, and that placement wins.
+				const current = thread.anchor
+				if (current.type !== 'point' || current.x !== point.x || current.y !== point.y) {
+					continue
+				}
+				if (!pageId || thread.pageId === pageId) {
+					updates.push({ ...thread, anchor })
+				} else {
+					rehomeThread({ ...thread, anchor }, pageId, updates)
+				}
+			}
+		}
+
+		if (updates.length > 0) {
+			commitCommentMutation(editor, ({ put }) => put(updates))
+		}
+	})
+
+	const disposeAfterCreate = editor.sideEffects.registerAfterCreateHandler(
+		'shape',
+		(shape, source) => {
+			if (source === 'remote') return
+			if (convertedByShape.has(shape.id)) returnedShapeIds.add(shape.id)
+		}
+	)
+
+	const disposeAfterChange = editor.sideEffects.registerAfterChangeHandler(
+		'shape',
+		(prev, next, source) => {
+			if (source === 'remote') return
+			if (prev.parentId === next.parentId) return
+			const pageId = editor.getAncestorPageId(next)
+			if (!pageId) return
+			// Descendants move with their parent without change events of their own.
+			const movedIds = editor.getShapeAndDescendantIds([next.id])
+			const updates: TLCommentRecord[] = []
+			for (const thread of getCommentThreads(editor)) {
+				const anchor = thread.anchor
+				if (anchor.type !== 'shape') continue
+				if (!movedIds.has(anchor.shapeId)) continue
+				if (thread.pageId === pageId) continue
+				rehomeThread(thread, pageId, updates)
+			}
+			if (updates.length > 0) {
+				commitCommentMutation(editor, ({ put }) => put(updates))
+			}
+		}
+	)
+
+	return () => {
+		disposeBeforeDelete()
+		disposeOperationComplete()
+		disposeAfterCreate()
+		disposeAfterChange()
+	}
+}

package/src/canvas/canvas-events.ts

@@ -0,0 +1,18 @@
+import { type PointerEvent as ReactPointerEvent } from 'react'
+import { Editor } from 'tldraw'
+
+/** A pointer-down that belongs to the camera, not the comment UI: any non-primary button
+ *  (middle/right-button pans), or a primary press with the spacebar pan key held. */
+export function isCanvasPanGesture(editor: Editor, e: ReactPointerEvent) {
+	return e.button !== 0 || editor.inputs.keys.has('Space')
+}
+
+/** Hand a pointer event to the canvas beneath the comments layer, marked the same way the
+ *  pass-through wheel/hover hooks mark their re-dispatched events. */
+export function forwardPointerEventToCanvas(container: HTMLElement, e: ReactPointerEvent) {
+	const cvs = container.querySelector('.tl-canvas')
+	if (!cvs) return
+	const newEvent = new PointerEvent(e.type, e.nativeEvent as any)
+	;(newEvent as any).isSpecialRedispatchedEvent = true
+	cvs.dispatchEvent(newEvent)
+}