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

package/src/canvas/thread-preview.tsx

@@ -0,0 +1,304 @@
+import { useEffect, useMemo, useRef, type CSSProperties } from 'react'
+import { createPortal } from 'react-dom'
+import {
+	Editor,
+	EditorAtom,
+	TLComment,
+	TLCommentThread,
+	usePassThroughWheelEvents,
+	useTranslation,
+	useValue,
+} from 'tldraw'
+import { CommentCard } from '../ui/comment-card'
+import { replyCountLabel } from '../ui/reply-count'
+import { type CommentingContext } from './context'
+import { useComments } from './hooks'
+import { useCommentingOptions } from './options'
+import { openStackId, openThreadId } from './state'
+import { POPOVER_OFFSET, toCardProps, useResolveName } from './thread-view'
+
+/**
+ * Hover previews for every canvas marker — a single pin, a coincident stack, or a cluster badge.
+ * Hovering shows the thread(s) behind the marker as cards; the marker's own click keeps whatever
+ * it already did (open the thread, open the stack list, zoom to the cluster's split).
+ *
+ * The panel is live, not a passive tooltip: the pointer can travel right into it and hover each
+ * card, and clicking one opens that thread — the same affordance the stack list gives its cards.
+ * Two pieces make that work. The close delay survives the trip across the gap, and the panel
+ * carries an invisible bridge over that gap (see `.tlui-cmt-canvas-preview::before`) so the
+ * journey never crosses dead space and retracts the panel mid-move.
+ *
+ * Opening a thread from a card needs nothing more than setting `openThreadId`, including for a
+ * thread currently folded inside a cluster badge: `collectClusterLeaves` skips the open thread, so
+ * it drops out of its badge and renders its own pin and popover.
+ */
+
+/** How long the pointer must rest on a marker before its preview appears. */
+const PREVIEW_OPEN_DELAY_MS = 180
+/**
+ * Grace period after the pointer leaves the marker *or* the panel. Long enough to cross the gap
+ * between them by hand — the bridge element covers that gap geometrically, and this covers the
+ * moment of transit between the two elements' enter/leave events.
+ */
+const PREVIEW_CLOSE_DELAY_MS = 220
+/** Cards shown before the panel falls back to a "+N more" line. */
+const PREVIEW_MAX_THREADS = 5
+
+/** A thread paired with the comment that opens it — one card of a preview. */
+export interface ThreadPreviewCard {
+	thread: TLCommentThread
+	first: TLComment
+}
+
+/**
+ * The cards a marker's preview will show, and how many threads it will summarise as "+N more".
+ *
+ * A thread can exist before its opening comment does — a collaborator's, mid-sync — and has nothing
+ * to preview until it arrives. Those are dropped here rather than rendered as blank cards, and they
+ * don't count toward the overflow tally either, so "+2 more" always means two readable threads.
+ */
+export function selectPreviewCards(
+	threads: readonly TLCommentThread[],
+	firstCommentOf: (thread: TLCommentThread) => TLComment | undefined,
+	max = PREVIEW_MAX_THREADS
+): { cards: ThreadPreviewCard[]; overflow: number } {
+	const readable: ThreadPreviewCard[] = []
+	for (const thread of threads) {
+		const first = firstCommentOf(thread)
+		if (first) readable.push({ thread, first })
+	}
+	return { cards: readable.slice(0, max), overflow: Math.max(0, readable.length - max) }
+}
+
+/**
+ * What a marker's click opens, which is what its preview imitates — the panel's surface, its
+ * width, and how it lays a comment out.
+ *
+ * `'thread'` previews a single pin: a thread panel without the header. `'list'` previews a
+ * coincident stack or a cluster: one card per thread, like the stack list.
+ */
+export type ThreadPreviewVariant = 'thread' | 'list'
+
+/**
+ * Which marker's preview is showing, or null. One atom for the whole layer, so previews are
+ * mutually exclusive by construction: the close delay means an outgoing marker's timer can still
+ * be pending when the next marker opens, and per-component state would briefly show both.
+ */
+const hoveredMarkerId = new EditorAtom<string | null>('commentHoveredMarkerId', () => null)
+
+/**
+ * Hover state for one marker. Returns whether its preview should render, plus the pointer handlers
+ * to spread onto the marker element.
+ *
+ * `markerId` must be stable and unique per marker across the layer — prefix by kind, since a stack
+ * is keyed by its oldest member's thread id and would otherwise collide with that thread's own pin.
+ */
+export function useMarkerPreview(editor: Editor, markerId: string) {
+	const openTimer = useRef(0)
+	const closeTimer = useRef(0)
+
+	// Previews are a resting-state affordance. While a thread or stack list is open, that view is
+	// the thing being read — a preview floating over it would just compete with it.
+	const suppressed = useValue(
+		'marker preview suppressed',
+		() => openThreadId.get(editor) !== null || openStackId.get(editor) !== null,
+		[editor]
+	)
+	const shown = useValue('marker preview shown', () => hoveredMarkerId.get(editor) === markerId, [
+		editor,
+		markerId,
+	])
+
+	useEffect(() => {
+		const open = openTimer
+		const close = closeTimer
+		return () => {
+			window.clearTimeout(open.current)
+			window.clearTimeout(close.current)
+			// Don't strand the atom on a marker that has unmounted — zoomed into a cluster, deleted,
+			// or folded away — or no other marker's preview could ever show.
+			if (hoveredMarkerId.get(editor) === markerId) hoveredMarkerId.set(editor, null)
+		}
+	}, [editor, markerId])
+
+	// Suppression can start *while* a preview is up: clicking the hovered pin opens its thread.
+	// Retract the preview rather than leaving it stranded behind the popover that just opened.
+	useEffect(() => {
+		if (suppressed && hoveredMarkerId.get(editor) === markerId) {
+			hoveredMarkerId.set(editor, null)
+		}
+	}, [suppressed, editor, markerId])
+
+	const onPointerEnter = () => {
+		window.clearTimeout(openTimer.current)
+		window.clearTimeout(closeTimer.current)
+		if (suppressed) return
+		openTimer.current = window.setTimeout(
+			() => hoveredMarkerId.set(editor, markerId),
+			PREVIEW_OPEN_DELAY_MS
+		)
+	}
+
+	const onPointerLeave = () => {
+		window.clearTimeout(openTimer.current)
+		window.clearTimeout(closeTimer.current)
+		closeTimer.current = window.setTimeout(() => {
+			if (hoveredMarkerId.get(editor) === markerId) hoveredMarkerId.set(editor, null)
+		}, PREVIEW_CLOSE_DELAY_MS)
+	}
+
+	return {
+		previewShown: shown && !suppressed,
+		previewHandlers: { onPointerEnter, onPointerLeave },
+	}
+}
+
+/**
+ * The hover panel: each thread's opening comment as a read-only card, capped with a "+N more"
+ * line. Mounted only while hovering, so the store subscription it needs to find those comments
+ * costs nothing at rest.
+ */
+export function ThreadPreview({
+	editor,
+	threads,
+	container,
+	variant,
+	point,
+	onSelectThread,
+	onPointerEnter,
+	onPointerLeave,
+	...props
+}: Pick<CommentingContext, 'currentUserId' | 'resolveAuthor'> & {
+	editor: Editor
+	/** The marker's threads, in the order they should read (oldest first). */
+	threads: readonly TLCommentThread[]
+	container: HTMLElement
+	/** What the marker's click opens, which this panel imitates. */
+	variant: ThreadPreviewVariant
+	/** The marker's anchor point in viewport space — the same origin its popover is placed from. */
+	point: { x: number; y: number }
+	/** Open a thread from its card. Omit to leave the cards inert. */
+	onSelectThread?(thread: TLCommentThread): void
+	/** The owning marker's hover handlers, so the panel counts as part of its hover region. */
+	onPointerEnter?(): void
+	onPointerLeave?(): void
+}) {
+	const options = useCommentingOptions()
+	const msg = useTranslation()
+	const comments = useComments(editor)
+	const resolveName = useResolveName(props.resolveAuthor)
+
+	// The panel floats over the canvas and scrolls nothing of its own, so a wheel on it should zoom
+	// and pan the canvas underneath — like every other tldraw panel, and like the popover it
+	// previews. Without this the canvas would freeze wherever the preview happened to be.
+	const ref = useRef<HTMLDivElement>(null)
+	usePassThroughWheelEvents(ref)
+
+	// Each thread's opening comment and its total comment count. `useComments` is oldest-first, so
+	// the first hit per thread is that thread's first comment. One pass over every comment beats a
+	// per-thread hook — the thread count here is driven by cluster size, which has no fixed bound.
+	const { firstByThread, countByThread } = useMemo(() => {
+		const first = new Map<string, TLComment>()
+		const count = new Map<string, number>()
+		for (const comment of comments) {
+			if (!first.has(comment.threadId)) first.set(comment.threadId, comment)
+			count.set(comment.threadId, (count.get(comment.threadId) ?? 0) + 1)
+		}
+		return { firstByThread: first, countByThread: count }
+	}, [comments])
+
+	const { cards, overflow } = useMemo(
+		() => selectPreviewCards(threads, (thread) => firstByThread.get(thread.id)),
+		[threads, firstByThread]
+	)
+
+	// Nothing readable yet — render no panel rather than an empty one. It matters most for the
+	// thread variant, where the panel *is* the card's surface: an empty one would paint as a blank
+	// box floating on the canvas.
+	if (cards.length === 0) return null
+
+	// Placed at the same origin as the popover this previews, so the two only differ by what their
+	// stylesheets do — see `.tlui-cmt-canvas-preview__panel--thread` for the header compensation.
+	const offset = POPOVER_OFFSET[variant]
+	// A thread preview is one comment on the panel itself, so the panel carries the hover and the
+	// click. A list preview puts each thread on its own card, as the stack list does.
+	const isThread = variant === 'thread'
+	const panelClass = [
+		'tlui-cmt-canvas-preview__panel',
+		`tlui-cmt-canvas-preview__panel--${variant}`,
+		isThread && onSelectThread ? 'tlui-cmt-canvas-preview__panel--selectable' : '',
+	]
+		.filter(Boolean)
+		.join(' ')
+
+	return createPortal(
+		// The root is the hover region — it carries the bridge back to the marker — while the panel
+		// inside it is the visible surface. Keeping them apart is what lets the surface light up on
+		// its own hover without the bridge (which reaches back over the marker) lighting it up too.
+		<div
+			ref={ref}
+			className={`tlui-cmt-canvas-preview tlui-cmt-canvas-preview--${variant}`}
+			style={
+				{
+					left: point.x + offset.x,
+					top: point.y + offset.y,
+					// The stylesheet sizes the hover bridge against this, so the gap it spans follows
+					// the offset rather than being restated as a second magic number.
+					'--tlui-cmt-preview-offset': `${offset.x}px`,
+				} as CSSProperties
+			}
+			onPointerEnter={onPointerEnter}
+			onPointerLeave={onPointerLeave}
+			// The panel sits over the canvas; a press on it is not a canvas press.
+			onPointerDown={(e) => e.stopPropagation()}
+		>
+			<div className={panelClass}>
+				{cards.map(({ thread, first }) => {
+					// The preview shows only the opening comment, so its reply count is what tells the
+					// reader the thread continues past what they see.
+					const replies = replyCountLabel(msg, (countByThread.get(thread.id) ?? 1) - 1)
+					return (
+						<div
+							key={thread.id}
+							className={
+								isThread
+									? undefined
+									: onSelectThread
+										? 'tlui-cmt-preview-card tlui-cmt-preview-card--selectable'
+										: 'tlui-cmt-preview-card'
+							}
+							onClick={
+								onSelectThread
+									? (e) => {
+											e.stopPropagation()
+											onSelectThread(thread)
+										}
+									: undefined
+							}
+						>
+							<CommentCard
+								{...toCardProps(first, props, options.components, resolveName)}
+								footer={
+									replies ? <span className="tlui-cmt-card__replies">{replies}</span> : undefined
+								}
+							/>
+						</div>
+					)
+				})}
+				{overflow > 0 && (
+					<div className="tlui-cmt-preview-more">
+						{msg('comments.preview-more').replace('{count}', String(overflow))}
+					</div>
+				)}
+			</div>
+		</div>,
+		container
+	)
+}
+
+/** Order a marker's threads for reading: oldest first, id as the tiebreak so it's stable. */
+export function sortThreadsForPreview(
+	threads: readonly TLCommentThread[]
+): readonly TLCommentThread[] {
+	return [...threads].sort((a, b) => a.createdAt - b.createdAt || (a.id < b.id ? -1 : 1))
+}

package/src/canvas/thread-stack.tsx

@@ -0,0 +1,252 @@
+import { type MouseEvent as ReactMouseEvent, memo, useEffect, useRef } from 'react'
+import {
+	Editor,
+	TLCommentThread,
+	useContainer,
+	usePassThroughWheelEvents,
+	useTranslation,
+	useValue,
+} from 'tldraw'
+import { CommentCard } from '../ui/comment-card'
+import { CountBadge } from '../ui/count-badge'
+import { UNKNOWN_AUTHOR } from './comment-render'
+import { type CommentingContext } from './context'
+import { useThreadComments } from './hooks'
+import { useCommentingOptions } from './options'
+import { pinStackKey } from './pin-stacking'
+import { openStackId, openThreadId } from './state'
+import { ThreadPreview, useMarkerPreview } from './thread-preview'
+import { anchorPagePoint } from './thread-state'
+import {
+	POPOVER_OFFSET,
+	ThreadPopover,
+	ThreadView,
+	toCardProps,
+	useResolveName,
+} from './thread-view'
+
+/**
+ * The pin for threads whose anchors resolve to the same page point — pins zooming can never
+ * separate, so instead of stacked markers they share one count badge. Clicking it opens a
+ * popover listing each thread as a card; clicking a card expands that thread in place (via the
+ * single open-thread state, so expanding one collapses another).
+ */
+export const ThreadStackPin = memo(function ThreadStackPin({
+	editor,
+	threads,
+	...props
+}: CommentingContext & {
+	editor: Editor
+	/** The stack's threads, oldest first. All resolve to the same anchor point. */
+	threads: readonly TLCommentThread[]
+}) {
+	const container = useContainer()
+	const msg = useTranslation()
+	const badgeRef = useRef<HTMLButtonElement>(null)
+	// The badge takes pointer events (to open on click), so wheel input over it would otherwise be
+	// swallowed instead of zooming — pass it through to the canvas, as the pin and cluster badge do.
+	usePassThroughWheelEvents(badgeRef)
+	// Hovering the badge previews its threads; clicking still opens them as the interactive list.
+	// The preview is what makes the badge legible before you commit to opening it.
+	const { previewShown, previewHandlers } = useMarkerPreview(editor, `stack:${threads[0].id}`)
+	// The list stays open while a member thread is expanded, and on its own after the member
+	// collapses — so Escape steps back: expanded thread → card list → closed. Held in editor
+	// state (not component state) because this pin remounts as its owning render path changes.
+	// Keyed by the coincident page point, not a member id, so the open state survives losing a
+	// member (including the oldest): the survivors keep the same key. Falls back to a thread id
+	// only when the anchor can't resolve (off page), where the list isn't shown anyway.
+	const stackId = useValue(
+		'stack id',
+		() => {
+			const pagePoint = anchorPagePoint(editor, threads[0].anchor)
+			return pagePoint ? pinStackKey(pagePoint) : threads[0].id
+		},
+		[editor, threads]
+	)
+	const listOpen = useValue('stack list open', () => openStackId.get(editor) === stackId, [
+		editor,
+		stackId,
+	])
+	const openId = useValue('open thread id', () => openThreadId.get(editor), [editor])
+	const openMember = threads.find((thread) => thread.id === openId)
+	const open = listOpen || openMember !== undefined
+
+	const point = useValue(
+		'stack point',
+		() => {
+			const first = threads[0]
+			if (first.pageId !== editor.getCurrentPageId()) return null
+			// The badge hangs off its anchor point bottom-left (transform: translate(0, -100%)),
+			// like a pin and like the cluster badge — but it sits at the raw page point with no pin
+			// inset. The inset only tucks an imprecise single pin inside its shape; applying it here
+			// would offset the badge from where the cluster badge sits (cluster centroids average
+			// raw anchor points) and make it hop as pins flip between them.
+			const pagePoint = anchorPagePoint(editor, first.anchor)
+			return pagePoint ? editor.pageToViewport(pagePoint) : null
+		},
+		[editor, threads]
+	)
+
+	// Clicking outside the popover (and off the badge) closes the whole stack — mirrors the
+	// single pin's dismiss. Capture phase + class checks, since the popover portals elsewhere.
+	useEffect(() => {
+		if (!open) return
+		const onPointerDown = (e: PointerEvent) => {
+			const target = e.target as HTMLElement | null
+			if (!target) return
+			if (target.closest('.tlui-cmt-canvas-popover')) return
+			const badge = badgeRef.current
+			if (badge && badge.contains(target)) return
+			// A click inside a menu/popover layered above us belongs to that layer; defer to its
+			// own dismissal instead of closing the stack out from under it.
+			if (
+				target.closest('.tlui-menu, [data-radix-popper-content-wrapper], .tlui-cmt-mention-popup')
+			)
+				return
+			openStackId.set(editor, null)
+			openThreadId.set(editor, null)
+		}
+		document.addEventListener('pointerdown', onPointerDown, true)
+		return () => document.removeEventListener('pointerdown', onPointerDown, true)
+	}, [open, editor])
+
+	// Escape with only the card list showing closes it. When a member thread is expanded, the
+	// layer's Escape handler collapses that first and marks the event consumed — stepping back
+	// to the list rather than closing everything at once.
+	useEffect(() => {
+		if (!listOpen) return
+		const onKeyDown = (e: KeyboardEvent) => {
+			if (e.key !== 'Escape' || e.defaultPrevented) return
+			openStackId.set(editor, null)
+		}
+		document.addEventListener('keydown', onKeyDown, true)
+		return () => document.removeEventListener('keydown', onKeyDown, true)
+	}, [listOpen, editor])
+
+	if (!point) return null
+
+	const toggle = () => {
+		if (open) {
+			openStackId.set(editor, null)
+			openThreadId.set(editor, null)
+		} else {
+			openStackId.set(editor, stackId)
+		}
+	}
+
+	// The expanded thread gains a "Comment" header that pushes its first comment down from where the
+	// hover preview showed it. When that thread is the list's first, lift the whole list by the
+	// header block so its "You" holds position across hover -> open: the single thread's
+	// THREAD_HEADER_BLOCK (36) plus the 8px margin above the expanded entry, less the 2px top the
+	// preview card sits its "You" down by. Only the first entry — lifting the list can't also hold a
+	// lower thread's neighbours in place.
+	const liftForHeader = threads[0]?.id === openId ? 42 : 0
+
+	return (
+		<>
+			<div className="tlui-cmt-canvas-pin" style={{ left: point.x, top: point.y }}>
+				<button
+					ref={badgeRef}
+					type="button"
+					className="tlui-cmt-button tlui-cmt-canvas-stack-badge"
+					aria-label={msg('comments.stack-label').replace('{count}', String(threads.length))}
+					aria-expanded={open}
+					onPointerDown={(e) => e.stopPropagation()}
+					onClick={(e) => {
+						e.stopPropagation()
+						toggle()
+					}}
+					{...previewHandlers}
+					onFocus={previewHandlers.onPointerEnter}
+					onBlur={previewHandlers.onPointerLeave}
+				>
+					<CountBadge count={threads.length} open={open} />
+				</button>
+			</div>
+			{previewShown && !open && (
+				<ThreadPreview
+					editor={editor}
+					threads={threads}
+					container={container}
+					// Lines the preview up with the stack list itself, so opening it leaves the cards
+					// exactly where the preview had them.
+					variant="list"
+					point={point}
+					// Picking a card from the preview lands in the same place clicking the badge and
+					// then the card would: the list open, that thread expanded within it.
+					onSelectThread={(thread) => {
+						openStackId.set(editor, stackId)
+						openThreadId.set(editor, thread.id)
+					}}
+					{...previewHandlers}
+					currentUserId={props.currentUserId}
+					resolveAuthor={props.resolveAuthor}
+				/>
+			)}
+			{open && (
+				<ThreadPopover
+					container={container}
+					style={{
+						left: point.x + POPOVER_OFFSET.list.x,
+						top: point.y + POPOVER_OFFSET.list.y - liftForHeader,
+					}}
+				>
+					<div className="tlui-cmt-stack-list">
+						{threads.map((thread) =>
+							thread.id === openId ? (
+								<div key={thread.id} className="tlui-cmt-stack-list__thread">
+									<ThreadView editor={editor} thread={thread} {...props} />
+								</div>
+							) : (
+								<StackThreadCard
+									key={thread.id}
+									editor={editor}
+									thread={thread}
+									{...props}
+									onOpen={() => openThreadId.set(editor, thread.id)}
+								/>
+							)
+						)}
+					</div>
+				</ThreadPopover>
+			)}
+		</>
+	)
+})
+
+/** A collapsed stack entry: the thread's first comment as a card; clicking expands the thread. */
+function StackThreadCard({
+	editor,
+	thread,
+	onOpen,
+	...props
+}: CommentingContext & { editor: Editor; thread: TLCommentThread; onOpen(): void }) {
+	const msg = useTranslation()
+	const options = useCommentingOptions()
+	const comments = useThreadComments(editor, thread.id)
+	const resolveName = useResolveName(props.resolveAuthor)
+	const first = comments[0]
+	if (!first) return null
+	const open = (e: ReactMouseEvent) => {
+		e.stopPropagation()
+		onOpen()
+	}
+	return (
+		<div className="tlui-cmt-stack-list__card" onClick={open}>
+			{/* The card's keyboard affordance. A button *wrapping* the card would put the comment
+			    body inside it, and a body renders its links as real anchors — interactive content
+			    nested in a button, which is an invalid content model and reads to assistive tech as a
+			    broken control. So the button covers the card as a sibling instead, leaving the body's
+			    own links above it and still reachable. */}
+			<button
+				type="button"
+				className="tlui-cmt-button tlui-cmt-stack-list__card-action"
+				aria-label={msg(
+					thread.resolved ? 'comments.pin-label-resolved' : 'comments.pin-label'
+				).replace('{name}', props.resolveAuthor(thread.createdBy)?.name ?? UNKNOWN_AUTHOR)}
+				onClick={open}
+			/>
+			<CommentCard {...toCardProps(first, props, options.components, resolveName)} />
+		</div>
+	)
+}