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

package/src/clustering/screen-offsets.test.ts

@@ -0,0 +1,171 @@
+import type { VecLike } from 'tldraw'
+import { describe, expect, it } from 'vitest'
+import { computeClusterTable } from './computeClusterTable'
+import type { LeafInput } from './types'
+
+function leaf(id: string, x: number, y: number): LeafInput {
+	return { id, point: { x, y } }
+}
+
+function mulberry32(seed: number): () => number {
+	let a = seed >>> 0
+	return () => {
+		a = (a + 0x6d2b79f5) >>> 0
+		let t = a
+		t = Math.imul(t ^ (t >>> 15), t | 1)
+		t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+	}
+}
+
+function randomLeaves(n: number, seed: number, scale = 1000): LeafInput[] {
+	const rand = mulberry32(seed)
+	return Array.from({ length: n }, (_, i) => leaf(`leaf-${i}`, rand() * scale, rand() * scale))
+}
+
+const ZOOM_BOUNDS = { minZoom: 0.05, maxZoom: 8 }
+// eps 0 keeps every merge as its own solo event, so the exact thresholds under test aren't
+// snapped to a contraction window's anchor.
+const EXACT_OPTS = { Tc: 22, Tu: 26.4, eps: 0, Dmax: 82.5, ...ZOOM_BOUNDS }
+
+function offsets(entries: Record<string, VecLike>): Map<string, VecLike> {
+	return new Map(Object.entries(entries))
+}
+
+describe('computeClusterTable without screen offsets (the guarantee)', () => {
+	it('is deep-equal across omitted, undefined, and empty offset arguments', () => {
+		for (const seed of [3, 21]) {
+			const leaves = randomLeaves(40, seed)
+			const plain = computeClusterTable(leaves, { ...ZOOM_BOUNDS })
+			expect(computeClusterTable(leaves, { ...ZOOM_BOUNDS }, undefined)).toEqual(plain)
+			expect(computeClusterTable(leaves, { ...ZOOM_BOUNDS }, new Map())).toEqual(plain)
+		}
+	})
+
+	it('is deep-equal when every leaf carries the same offset (Δō is always zero)', () => {
+		const leaves = randomLeaves(30, 11)
+		const uniform = new Map(leaves.map((l) => [l.id, { x: -20, y: 20 }]))
+		expect(computeClusterTable(leaves, { ...ZOOM_BOUNDS }, uniform)).toEqual(
+			computeClusterTable(leaves, { ...ZOOM_BOUNDS })
+		)
+	})
+
+	it('never emits a zSplit override on the offset-free path', () => {
+		const table = computeClusterTable(randomLeaves(20, 5), { ...ZOOM_BOUNDS }, new Map())
+		for (const event of table.events) {
+			// finalize always derives ratio splits when no override was carried
+			expect(event.zSplit).toBeCloseTo(event.zMerge * 1.2, 10)
+		}
+	})
+})
+
+describe('offset-aware pricing', () => {
+	const A = leaf('a', 0, 0)
+	const B = leaf('b', 100, 0)
+
+	it('merges earlier when the insets point toward each other, at the exact visual crossing', () => {
+		// Visual positions: a at 100·0·z + 20, b at 100z − 20 → distance |100z − 40|. Tc = 22
+		// crosses at z = 0.62 (raw anchors would say 0.22); the split derives from the Tu/Tc
+		// ratio, as for every event.
+		const table = computeClusterTable(
+			[A, B],
+			EXACT_OPTS,
+			offsets({ a: { x: 20, y: 0 }, b: { x: -20, y: 0 } })
+		)
+		expect(table.events).toHaveLength(1)
+		expect(table.events[0].zMerge).toBeCloseTo(0.62, 10)
+		expect(table.events[0].zSplit).toBeCloseTo(0.62 * 1.2, 10)
+	})
+
+	it('merges later when the insets point apart, at the exact visual crossing', () => {
+		// Distance 100z + 10: Tc at z = 0.12 (raw: 0.22); ratio split at 0.144.
+		const table = computeClusterTable(
+			[A, B],
+			EXACT_OPTS,
+			offsets({ a: { x: -5, y: 0 }, b: { x: 5, y: 0 } })
+		)
+		expect(table.events).toHaveLength(1)
+		expect(table.events[0].zMerge).toBeCloseTo(0.12, 10)
+		expect(table.events[0].zSplit).toBeCloseTo(0.144, 10)
+	})
+
+	it('never merges a pair whose visual distance never reaches Tc', () => {
+		// Distance 100z + 40 ≥ 40 > Tc at every zoom: priced 0 and pruned by the minZoom cut.
+		const table = computeClusterTable(
+			[A, B],
+			EXACT_OPTS,
+			offsets({ a: { x: -20, y: 0 }, b: { x: 20, y: 0 } })
+		)
+		expect(table.events).toEqual([])
+	})
+
+	it('still applies the Dmax fit cap to a corrected merge', () => {
+		// Exaggerated inward offsets put the Tc crossing at z = 1.42, above the spread cap
+		// Dmax/diag = 82.5/100 = 0.825, so the cap wins the min.
+		const table = computeClusterTable(
+			[A, B],
+			EXACT_OPTS,
+			offsets({ a: { x: 60, y: 0 }, b: { x: -60, y: 0 } })
+		)
+		expect(table.events).toHaveLength(1)
+		expect(table.events[0].zMerge).toBeCloseTo(0.825, 10)
+		expect(table.events[0].zSplit).toBeCloseTo(0.825 * 1.2, 10)
+	})
+
+	it('treats coincident anchors with differing offsets as a constant visual distance', () => {
+		// Same anchor point, one pin tucked: constant 20px apart < Tc → merged at every zoom,
+		// entering the same maxSplitZoom band as a coincident pair (zMerge 6/1.2 = 5, zSplit 6).
+		const table = computeClusterTable(
+			[leaf('a', 50, 50), leaf('b', 50, 50)],
+			{ ...EXACT_OPTS, maxSplitZoom: 6 },
+			offsets({ a: { x: 20, y: 0 } })
+		)
+		expect(table.events).toHaveLength(1)
+		expect(table.events[0].zMerge).toBe(5)
+		expect(table.events[0].zSplit).toBe(6)
+	})
+
+	it("dilutes a cluster's mean offset as precise members fold in", () => {
+		// a (tucked 20px) and b (precise) share an anchor: constant 20px apart, always merged.
+		// Their cluster's mean offset is (10, 0); against precise c 100 units right the visual
+		// distance is |100z − 10| → Tc at z = 0.32 — half the lone pin's correction.
+		const table = computeClusterTable(
+			[leaf('a', 0, 0), leaf('b', 0, 0), leaf('c', 100, 0)],
+			EXACT_OPTS,
+			offsets({ a: { x: 20, y: 0 } })
+		)
+		expect(table.events).toHaveLength(2)
+		const outer = table.events.find((e) => e.result.count === 3)!
+		expect(outer.zMerge).toBeCloseTo(0.32, 10)
+		expect(outer.zSplit).toBeCloseTo(0.32 * 1.2, 10)
+	})
+})
+
+describe('table ordering with offsets', () => {
+	it('keeps zMerge and zSplit non-increasing (splits are always ratio-derived)', () => {
+		// Mixed offset and plain leaves at varied spacings: every split is zMerge · (Tu/Tc), so
+		// both threshold sequences inherit the table's non-increasing order — the invariant the
+		// runtime's prefix cursor, split walk, and seed bisection rely on.
+		const leaves = [
+			leaf('a', 0, 0),
+			leaf('b', 100, 0),
+			leaf('c', 130, 0),
+			leaf('d', 400, 0),
+			leaf('e', 470, 0),
+			leaf('f', 1000, 300),
+		]
+		const table = computeClusterTable(
+			leaves,
+			EXACT_OPTS,
+			offsets({ a: { x: -20, y: 0 }, b: { x: 14, y: 0 }, d: { x: 20, y: 14 } })
+		)
+		expect(table.events.length).toBeGreaterThan(2)
+		for (let i = 1; i < table.events.length; i++) {
+			expect(table.events[i].zMerge).toBeLessThanOrEqual(table.events[i - 1].zMerge)
+			expect(table.events[i].zSplit).toBeLessThanOrEqual(table.events[i - 1].zSplit)
+		}
+		for (const event of table.events) {
+			expect(event.zSplit).toBeCloseTo(event.zMerge * 1.2, 10)
+		}
+	})
+})

package/src/clustering/types.ts

@@ -2,7 +2,7 @@ import type { VecLike } from 'tldraw'
 
 /**
  * One comment thread's pin, already resolved to a page-space anchor point.
- * @public
+ * @internal
  */
 export interface LeafInput {
 	/** Unique. Thread id. Uniqueness is a precondition — throw on duplicates. */
@@ -11,6 +11,16 @@ export interface LeafInput {
 	point: VecLike
 }
 
+/**
+ * Constant screen-px render offsets for markers that don't draw exactly on their anchor —
+ * imprecise shape pins, which tuck ~20px into their shape. Keyed by leaf id; leaves absent from
+ * the map render on their anchor. A marker's visual position at zoom z is `z · point + offset`.
+ * Passed as the optional third argument to `computeClusterTable`; when omitted or empty the
+ * algorithm's behavior (and output) is identical to an offset-unaware run.
+ * @internal
+ */
+export type LeafScreenOffsets = ReadonlyMap<string, VecLike>
+
 /** An edge of the Euclidean MST over the leaf anchor points. */
 export interface MstEdge {
 	/** Index into the input leaves array. Normalized: leaves[a].id < leaves[b].id (lexicographic). */
@@ -23,7 +33,7 @@ export interface MstEdge {
 
 /**
  * A cluster in the merge tree: a leaf (one thread) or a merged group.
- * @public
+ * @internal
  */
 export interface ClusterNode {
 	/** Leaves: the thread id verbatim. Merged nodes: `cluster:${count}:${minMemberId}`. */
@@ -58,7 +68,7 @@ export interface ContractedEvent {
 
 /**
  * A finalized merge event, ready for the runtime.
- * @public
+ * @internal
  */
 export interface MergeEvent {
 	zMerge: number
@@ -70,7 +80,7 @@ export interface MergeEvent {
 
 /**
  * The precomputed clustering schedule for one page's comments.
- * @public
+ * @internal
  */
 export interface ClusterTable {
 	/** Sorted non-increasing by zMerge; satisfies the invariants of CLUSTERING.md §7.6. */
@@ -79,15 +89,15 @@ export interface ClusterTable {
 	leaves: readonly ClusterNode[]
 }
 
-/** @public */
+/** @internal */
 export interface ClusterOptions {
-	/** Cluster (merge) distance, screen px. Default 40. */
+	/** Cluster (merge) distance, screen px. Default 22. */
 	Tc?: number
-	/** Uncluster (split) distance, screen px. Must be \> Tc. Default 1.5 · Tc. */
+	/** Uncluster (split) distance, screen px. Must be \> Tc. Default 1.2 · Tc. */
 	Tu?: number
-	/** Contraction window ratio. Default 0.12. */
+	/** Contraction window ratio. Default 0.7. */
 	eps?: number
-	/** Max cluster screen extent at birth, screen px. Must be \>= Tc. Default 3 · Tc. */
+	/** Max cluster screen extent at birth, screen px. Must be \>= Tc. Default 3.75 · Tc. */
 	Dmax?: number
 	/** Camera zoom bounds — pass the editor's camera constraints. Required. */
 	minZoom: number

package/src/index.ts

@@ -1,93 +1,142 @@
 import { registerTldrawLibraryVersion } from '@tldraw/utils'
 
 // Presentational commenting components. These are tldraw-independent and can be used to build
-// custom commenting UI.
-export { Avatar, type AvatarProps } from './ui/avatar'
+// custom commenting UI. The mention picker, pill, and avatar are re-exported from @tldraw/mentions
+// so the commenting public API is unchanged.
+export {
+	Avatar,
+	type AvatarProps,
+	type CommentAuthor,
+	createMentionSuggestion,
+	filterMentionMembers,
+	Mention,
+	MentionList,
+	type MentionListProps,
+	type MentionMember,
+	type MentionProps,
+	type MentionSuggestionOptions,
+} from '@tldraw/mentions'
 export { Byline, type BylineProps } from './ui/byline'
 export { CommentCard, type CommentCardProps } from './ui/comment-card'
 export { CommentComposer, type CommentComposerProps } from './ui/comment-composer'
 export { CountBadge, type CountBadgeProps } from './ui/count-badge'
 export { CommentPin, type CommentPinProps } from './ui/comment-pin'
-export { CommentText, type CommentTextProps } from './ui/comment-text'
 export { CommentThread, type CommentThreadProps } from './ui/comment-thread'
-export { CommentsList, type CommentListItemProps, type CommentsListProps } from './ui/comments-list'
+export {
+	CommentListItem,
+	CommentsList,
+	isOpenInNewTabClick,
+	type CommentListItemProps,
+	type CommentListItemRenderProps,
+	type CommentsListProps,
+} from './ui/comments-list'
 export { EmptyState, type EmptyStateProps } from './ui/empty-state'
-export { formatRelativeTime } from './ui/format-time'
-export { Mention, type MentionProps } from './ui/mention'
-export { MentionList, type MentionListProps, type MentionMember } from './ui/mention-list'
+export { formatFullDateTime, formatRelativeTime } from './ui/format-time'
 export {
-	createMentionSuggestion,
-	filterMentionMembers,
-	type MentionSuggestionOptions,
-} from './ui/mention-suggestion'
-export { Reaction, type ReactionProps } from './ui/reaction'
-export { Reactions } from './ui/reactions'
-export { renderMarkdown } from './ui/render-markdown'
+	DEFAULT_REACTION_EMOJI,
+	EmojiPicker,
+	type EmojiPickerProps,
+	isAllowedReactionEmoji,
+} from './ui/emoji-picker'
+export {
+	Reaction,
+	type ReactionProps,
+	type RenderReaction,
+	defaultRenderReaction,
+	DefaultReactionTooltip,
+	DefaultReactionTooltipContent,
+	type ReactionTooltipProps,
+} from './ui/reaction'
+export { ReactionPicker, type ReactionPickerProps } from './ui/reaction-picker'
+export {
+	Reactions,
+	type ReactionReactor,
+	type ReactionsProps,
+	type ReactionSummary,
+} from './ui/reactions'
 export { SendButton, type SendButtonProps } from './ui/send-button'
 
 // The tldraw-coupled commenting layer: the comment tool, reactive hooks over the comment
 // records, a rich-text body renderer, and a batteries-included <CanvasComments> overlay. Pairs
 // with the presentational components above.
+export { registerCommentAnchorLifecycle } from './canvas/anchor-lifecycle'
 export { CommentBody, type CommentBodyProps } from './canvas/comment-body'
 export {
-	CommentTool,
-	commentToolOverrides,
-	commentTools,
-	type PendingComment,
-} from './canvas/comment-tool'
-export { collectClusterLeaves } from './canvas/cluster-input'
-export { computeClusterTable } from './clustering/computeClusterTable'
+	deleteComment,
+	deleteThread,
+	editComment,
+	putCommentRecords,
+	removeCommentRecords,
+	reopenThread,
+	resolveThread,
+} from './canvas/comment-mutations'
+export {
+	CommentReactionPicker,
+	type CommentReactionPickerProps,
+	CommentReactions,
+	type CommentReactionsProps,
+	type ReactionSummaryInput,
+	summarizeReactions,
+	toggleCommentReaction,
+	useCommentReactions,
+} from './canvas/comment-reactions'
+export { CommentTool, commentToolOverrides, commentTools } from './canvas/comment-tool'
 export {
+	getCommentReactions,
 	getCommentRecord,
 	getComments,
 	getCommentThreads,
-	putCommentRecords,
-	removeCommentRecords,
+	getLiveComments,
+	getLiveCommentThreads,
 	type TLCommentRecord,
 } from './canvas/comment-store'
-export { createClusterRuntime, type ClusterRuntime } from './clustering/runtime'
-export type {
-	ClusterNode,
-	ClusterOptions,
-	ClusterTable,
-	LeafInput,
-	MergeEvent,
-} from './clustering/types'
+export { type CommentingContext } from './canvas/context'
 export { CommentsFilterMenu, type CommentsFilterMenuProps } from './canvas/comments-filter-menu'
 export { CommentsMenuItem } from './canvas/comments-menu-item'
 export { CanvasComments, type CanvasCommentsProps } from './canvas/comments-overlay'
 export {
 	type CommentingComponents,
 	type CommentingOptions,
+	type CommentModification,
+	type CommentModificationContext,
+	defaultCanModifyComment,
 	defaultCommentingOptions,
+	getCanComment,
+	getCanModifyComment,
 	getCommentingOptions,
+	type ShapeCommentPrecisionContext,
+	useCanComment,
+	useCanModifyComment,
 	useCommentingOptions,
 } from './canvas/options'
 export { CommentsOverflowMenu } from './canvas/comments-overflow-menu'
-export { CanvasCommentsSidebar, type CanvasCommentsSidebarProps } from './canvas/comments-sidebar'
+export { CommentsVisibilityToggle } from './canvas/comments-visibility-toggle'
+export {
+	CanvasCommentsSidebar,
+	sortSidebarRows,
+	type CanvasCommentsSidebarProps,
+	type SidebarRow,
+} from './canvas/comments-sidebar'
 export { useComments, useCommentThreads, useThreadComments } from './canvas/hooks'
 export { useCommentingEnabled } from './canvas/license'
-export { DEFAULT_REGION_COMMENT_OPTIONS, type RegionCommentOptions } from './canvas/region-options'
 export { richTextToPlaintext } from './canvas/rich-text'
 export { DEFAULT_SIDEBAR_FILTERS, type SidebarFilters } from './canvas/sidebar-filters'
 export {
 	commentsHidden,
-	commitCommentMutation,
+	commentsSidebarOpen,
+	getRevealThreadPending,
 	openThreadId,
-	pendingComment,
+	revealThread,
 	sidebarFilters,
 	toggleCommentsHidden,
+	toggleCommentsSidebar,
 	useCommentsHidden,
+	useCommentsSidebarOpen,
 	useOpenThreadId,
-	usePendingComment,
+	useRevealThreadPending,
 	useSidebarFilters,
 } from './canvas/state'
-export {
-	anchorPagePoint,
-	DEFAULT_IMPRECISE_SHAPE_ANCHOR,
-	focusThread,
-	shapeAnchorAt,
-} from './canvas/thread-state'
+export { anchorPagePoint, focusThread, shapeAnchorAt } from './canvas/thread-state'
 
 registerTldrawLibraryVersion(
 	(globalThis as any).TLDRAW_LIBRARY_NAME,

package/src/ui/byline.tsx

@@ -1,23 +1,35 @@
-import { formatRelativeTime } from './format-time'
+import { Avatar, type CommentAuthor } from '@tldraw/mentions'
+import { TldrawUiTooltip, useCurrentTranslation } from 'tldraw'
+import { formatFullDateTime, formatRelativeTime } from './format-time'
 
 /** @public */
 export interface BylineProps {
-	author: string
+	author: CommentAuthor
 	/** ISO datetime; formatted to relative time by the component. */
 	date: string
 	/** Shows an "edited" marker when the comment has been edited. */
 	edited?: boolean
 }
 
-/** A comment's metadata line: author name, relative time, and an edited marker. @public @react */
+/**
+ * A comment's metadata line: author name, relative time, and an edited marker. Hovering the time
+ * shows the full date and time in a tooltip.
+ * @public @react
+ */
 export function Byline({ author, date, edited }: BylineProps) {
+	// The relative time is the one piece of a byline that isn't the host's data, so it follows the
+	// same translation context as every other string in the UI rather than a prop of its own.
+	const { locale } = useCurrentTranslation()
 	return (
-		<div className="cmt-head">
-			<span className="cmt-author">{author}</span>
-			<span className="cmt-time">
-				{formatRelativeTime(date)}
-				{edited && <span className="cmt-edited"> · edited</span>}
-			</span>
+		<div className="tlui-cmt-head">
+			<Avatar author={author} />
+			<span className="tlui-cmt-author">{author.name}</span>
+			<TldrawUiTooltip content={formatFullDateTime(date, locale)}>
+				<span className="tlui-cmt-time">
+					{formatRelativeTime(date, locale)}
+					{edited && <span className="tlui-cmt-edited"> · edited</span>}
+				</span>
+			</TldrawUiTooltip>
 		</div>
 	)
 }

package/src/ui/comment-card.tsx

@@ -1,12 +1,12 @@
+import { type CommentAuthor } from '@tldraw/mentions'
 import { ReactNode } from 'react'
-import { Avatar } from './avatar'
 import { Byline } from './byline'
 
 /** @public */
 export interface CommentCardProps {
-	author: string
-	/** The rendered comment body. The card doesn't dictate a format — pass a `<CommentText>`
-	 *  for markdown, a rich-text render, or any node. */
+	author: CommentAuthor
+	/** The rendered comment body. The card doesn't dictate a format — pass a `<CommentBody>`
+	 *  for a comment's rich text, or any node of your own. */
 	body: ReactNode
 	/** ISO datetime; formatted to relative time by the component. */
 	date: string
@@ -15,18 +15,28 @@ export interface CommentCardProps {
 	edited?: boolean
 	/** Hover-revealed controls at the card's top-right (e.g. an edit affordance). */
 	actions?: ReactNode
+	/** Content under the body, aligned with it rather than the avatar (e.g. a `<Reactions>` row). */
+	footer?: ReactNode
 }
 
 /** A single comment: Avatar, Byline, and a body slot the consumer renders. @public @react */
-export function CommentCard({ author, body, date, you, edited, actions }: CommentCardProps) {
+export function CommentCard({
+	author,
+	body,
+	date,
+	you,
+	edited,
+	actions,
+	footer,
+}: CommentCardProps) {
 	return (
-		<div className={you ? 'cmt-card cmt-card--you' : 'cmt-card'}>
-			<Avatar name={author} />
-			<div className="cmt-body">
-				<Byline author={author} date={date} edited={edited} />
+		<div className={you ? 'tlui-cmt-card tlui-cmt-card--you' : 'tlui-cmt-card'}>
+			<Byline author={author} date={date} edited={edited} />
+			<div className="tlui-cmt-body">
 				{body}
+				{footer}
 			</div>
-			{actions !== undefined && <div className="cmt-card__actions">{actions}</div>}
+			{actions !== undefined && <div className="tlui-cmt-card__actions">{actions}</div>}
 		</div>
 	)
 }