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

package/src/canvas/thread-preview.tsx

@@ -0,0 +1,294 @@
+import { useEffect, useMemo, useRef, type CSSProperties } from 'react'
+import {
+	Editor,
+	EditorAtom,
+	EditorPortal,
+	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 is unchanged.
+ *
+ * The panel is live, not a passive tooltip: the pointer can travel into it and click a card to open
+ * that thread. Two pieces make that work — the close delay survives the trip across the gap, and
+ * the panel carries an invisible bridge over it (see `.tlui-cmt-canvas-preview::before`).
+ *
+ * Opening a thread from a card needs nothing more than setting `openThreadId`, even for one folded
+ * inside a badge: `collectClusterLeaves` skips the open thread, so it drops out and renders itself.
+ */
+
+/** 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, which the bridge element covers geometrically.
+ */
+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. Those are
+ * dropped rather than rendered blank, and don't count toward the overflow tally.
+ */
+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: the close delay can leave an outgoing marker's timer pending when the next
+ * 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, or a stack collides with its oldest member'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 its store subscription costs nothing at rest.
+ */
+export function ThreadPreview({
+	editor,
+	threads,
+	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[]
+	/** 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 (
+		<EditorPortal>
+			{/* 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>
+		</EditorPortal>
+	)
+}
+
+/** 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,242 @@
+import { type MouseEvent as ReactMouseEvent, memo, useEffect, useRef } from 'react'
+import {
+	Editor,
+	TLCommentThread,
+	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, impreciseShapePinInset } 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 they share one count badge. Clicking it lists each thread as a card; clicking a card
+ * expands that thread in place, via the single open-thread state.
+ */
+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 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, so Escape steps back: expanded thread ->
+	// card list -> closed. Held in editor state because this pin remounts as its owning render path
+	// changes, and keyed by the coincident page point so the open state survives losing a member.
+	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 like a pin, and applies the same imprecise-shape
+			// inset the pins it stands in for would (see ThreadPin) — otherwise the marker would snap from tucked
+			// inside the shape to the raw corner the moment a second comment turns a pin into a stack.
+			const pagePoint = anchorPagePoint(editor, first.anchor)
+			if (!pagePoint) return null
+			const viewportPoint = editor.pageToViewport(pagePoint)
+			const inset = impreciseShapePinInset(editor, first.anchor)
+			return inset ? { x: viewportPoint.x + inset.x, y: viewportPoint.y + inset.y } : viewportPoint
+		},
+		[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 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 so its "You" holds position
+	// across hover -> open. Only the first entry — lifting can't also hold a lower thread's neighbours.
+	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}
+					// 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
+					base={{
+						x: point.x + POPOVER_OFFSET.list.x,
+						y: 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>
+	)
+}