@tldraw/commenting 0.0.0-bootstrap

package/src/ui/mention-list.tsx

@@ -0,0 +1,106 @@
+import { ReactNode } from 'react'
+import { useTranslation } from 'tldraw'
+import { Avatar } from './avatar'
+
+/** A person the composer's \@-mention picker can offer. @public */
+export interface MentionMember {
+	id: string
+	name: string
+	/** Avatar image URL. Falls back to a coloured initial when omitted. */
+	avatar?: string
+	/** Avatar background colour, used when there's no `avatar` image. */
+	color?: string
+	/** A secondary line under the name — e.g. an email or handle. Omit for a single-line row. */
+	secondary?: string
+	/** Marks the current user; shown as a "(You)" suffix after the name. */
+	you?: boolean
+	/** Hosts may carry extra fields; a custom `renderMember` can read them. */
+	[key: string]: unknown
+}
+
+/** @public */
+export interface MentionListProps {
+	/** Members to choose from — already resolved for the current query by the host. */
+	members: MentionMember[]
+	/** Index of the highlighted row, driven by the composer's keyboard navigation. */
+	activeIndex?: number
+	/** Called when a member is chosen (click, or Enter on the active row). */
+	onSelect?(member: MentionMember): void
+	/** Shown when no member matches the query. Defaults to a translated "No matches". */
+	emptyLabel?: string
+	/** Override a row's content (inside the selectable button). Defaults to avatar + name (+ secondary). */
+	renderMember?(member: MentionMember): ReactNode
+}
+
+/** The default row content: avatar, name (with a "(You)" marker), and an optional secondary line. */
+function DefaultMemberRow({ member }: { member: MentionMember }) {
+	const msg = useTranslation()
+	return (
+		<>
+			<Avatar name={member.name} color={member.color} image={member.avatar} />
+			<span className="cmt-mention-list__text">
+				<span className="cmt-mention-list__name">
+					{member.name}
+					{member.you && (
+						<span className="cmt-mention-list__you">{`(${msg('comments.mention-you')})`}</span>
+					)}
+				</span>
+				{member.secondary && (
+					<span className="cmt-mention-list__secondary">{member.secondary}</span>
+				)}
+			</span>
+		</>
+	)
+}
+
+/**
+ * The \@-mention member picker: a popover list of people to mention, shown as the user types after
+ * `@`. Presentational — the composer's suggestion plugin owns resolution, keyboard navigation, and
+ * placement, and drives this with the host-resolved `members` and the highlighted `activeIndex`.
+ * @public @react
+ */
+export function MentionList({
+	members,
+	activeIndex = 0,
+	onSelect,
+	emptyLabel,
+	renderMember,
+}: MentionListProps) {
+	const msg = useTranslation()
+	if (members.length === 0) {
+		return (
+			<div className="cmt-mention-list cmt-mention-list--empty">
+				{emptyLabel ?? msg('comments.mention-no-matches')}
+			</div>
+		)
+	}
+	return (
+		<div className="cmt-mention-list" role="listbox">
+			{members.map((member, i) => {
+				const active = i === activeIndex
+				return (
+					<button
+						key={member.id}
+						type="button"
+						role="option"
+						aria-selected={active}
+						className={
+							active
+								? 'cmt-mention-list__item cmt-mention-list__item--active'
+								: 'cmt-mention-list__item'
+						}
+						// Keep the composer focused on a row press: it's portaled outside the editor, so a
+						// bare mousedown would blur the composer — which now dismisses the picker — before
+						// the click could select. Selection runs on click; focus stays put.
+						onMouseDown={(e) => e.preventDefault()}
+						onClick={() => {
+							if (onSelect) onSelect(member)
+						}}
+					>
+						{renderMember ? renderMember(member) : <DefaultMemberRow member={member} />}
+					</button>
+				)
+			})}
+		</div>
+	)
+}

package/src/ui/mention-suggestion.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'vitest'
+import { filterMentionMembers } from './mention-suggestion'
+
+const members = [
+	{ id: 'u1', name: 'Ada Lovelace' },
+	{ id: 'u2', name: 'Alan Turing' },
+	{ id: 'u3', name: 'Grace Hopper' },
+]
+const ids = (q: string) => filterMentionMembers(members, q).map((m) => m.id)
+
+describe('filterMentionMembers', () => {
+	it('matches a case-insensitive substring; empty query keeps all', () => {
+		expect(ids('')).toEqual(['u1', 'u2', 'u3'])
+		expect(ids('grace')).toEqual(['u3'])
+		expect(ids('AL')).toEqual(['u2']) // "Alan", case-insensitive; "Ada Lovelace" has no "al"
+		expect(ids('zzz')).toEqual([])
+	})
+})

package/src/ui/mention-suggestion.tsx

@@ -0,0 +1,285 @@
+import type { MentionNodeAttrs } from '@tiptap/extension-mention'
+import { ReactRenderer } from '@tiptap/react'
+import type { SuggestionKeyDownProps, SuggestionOptions } from '@tiptap/suggestion'
+import { type ReactNode, forwardRef, useImperativeHandle, useState } from 'react'
+import { type Editor as TldrawEditor, atom, react } from 'tldraw'
+import { MentionList, MentionMember } from './mention-list'
+
+/** The handle the suggestion plugin drives — it forwards navigation keys into the popup. */
+export interface MentionPopupHandle {
+	onKeyDown(props: SuggestionKeyDownProps): boolean
+}
+
+interface MentionPopupProps {
+	items: MentionMember[]
+	command(attrs: MentionNodeAttrs): void
+	renderMember?(member: MentionMember): ReactNode
+}
+
+/** The live @-picker popup: owns the highlighted index and keyboard, renders the presentational list. */
+const MentionPopup = forwardRef<MentionPopupHandle, MentionPopupProps>(function MentionPopup(
+	{ items, command, renderMember },
+	ref
+) {
+	const [activeIndex, setActiveIndex] = useState(0)
+	// A new query yields new items; reset the highlight to the top during render — not in an effect,
+	// which would leave a frame where `activeIndex` still points past a shrunk list and Enter selects
+	// its (now out-of-range, undefined) item, swallowing the key without inserting a mention.
+	const [prevItems, setPrevItems] = useState(items)
+	if (items !== prevItems) {
+		setPrevItems(items)
+		setActiveIndex(0)
+	}
+
+	const select = (member: MentionMember | undefined) => {
+		if (member) command({ id: member.id, label: member.name })
+	}
+
+	useImperativeHandle(ref, () => ({
+		onKeyDown: ({ event }) => {
+			if (items.length === 0) return false
+			if (event.key === 'ArrowUp') {
+				setActiveIndex((i) => (i + items.length - 1) % items.length)
+				return true
+			}
+			if (event.key === 'ArrowDown') {
+				setActiveIndex((i) => (i + 1) % items.length)
+				return true
+			}
+			// Enter and Tab both complete the highlighted member (falling back to the top match so a
+			// stale index never selects `undefined`). The empty-roster case is handled a level up, in
+			// the suggestion's onKeyDown, which cancels the picker.
+			if (event.key === 'Enter' || event.key === 'Tab') {
+				select(items[activeIndex] ?? items[0])
+				return true
+			}
+			return false
+		},
+	}))
+
+	return (
+		<MentionList
+			members={items}
+			activeIndex={activeIndex}
+			onSelect={select}
+			renderMember={renderMember}
+		/>
+	)
+})
+
+const MAX_SUGGESTIONS = 8
+
+/** Members whose name contains the query (case-insensitive), capped to the popup's length.
+ * @public */
+export function filterMentionMembers(members: MentionMember[], query: string): MentionMember[] {
+	const q = query.toLowerCase()
+	return members.filter((m) => m.name.toLowerCase().includes(q)).slice(0, MAX_SUGGESTIONS)
+}
+
+// A reactive flag for whether the @-picker is showing. Deliberately NOT tldraw's open-menu registry:
+// registering there mounts MenuClickCapture, which covers the canvas with a click-capture overlay to
+// make it inert while a menu is open. But the picker is an inline autocomplete, not a modal — the
+// canvas must stay pannable/zoomable beneath it — so we track "open" ourselves instead.
+const mentionPickerOpen = atom('isMentionPickerOpen', false)
+
+/**
+ * Whether the @-mention picker is currently showing. Host dismissal (Escape, outside-click) checks
+ * this so it can defer to the picker instead of tearing down the composer or thread beneath it.
+ */
+export function isMentionPickerOpen(): boolean {
+	return mentionPickerOpen.get()
+}
+
+/** @public */
+export interface MentionSuggestionOptions {
+	/** Override a member row's content in the picker. Defaults to avatar + name (+ secondary). */
+	renderMember?(member: MentionMember): ReactNode
+	/**
+	 * The tldraw editor the composer lives in. When provided, the popup re-anchors reactively as the
+	 * canvas camera moves (the composer rides it) instead of polling every frame. Omit off-canvas.
+	 */
+	editor?: TldrawEditor | null
+}
+
+/**
+ * Build the TipTap `suggestion` config for the comment \@-picker. `getSuggestions(query)` is the
+ * host's resolver — it returns the members matching the query (sync or async); the SDK owns neither
+ * the roster nor the filtering. The plugin runs outside React, so `render` mounts `MentionPopup` via
+ * a `ReactRenderer`, forwards navigation keys through the popup's imperative handle, and lets it call
+ * `command` to insert.
+ * @public
+ */
+export function createMentionSuggestion(
+	getSuggestions: (query: string) => MentionMember[] | Promise<MentionMember[]>,
+	options: MentionSuggestionOptions = {}
+): Omit<SuggestionOptions<MentionMember, MentionNodeAttrs>, 'editor'> {
+	return {
+		char: '@',
+		items: ({ query }) => getSuggestions(query),
+		render: () => {
+			let renderer: ReactRenderer<MentionPopupHandle, MentionPopupProps> | null = null
+			let container: HTMLElement | null = null
+			let editorEl: HTMLElement | null = null
+			let canvasEl: Element | null = null
+			let stopCameraReaction: (() => void) | null = null
+			// The composer field's top-left in page space, plus the popup's screen width. Captured on a
+			// fresh read so camera moves can re-derive the popup's screen position from the page anchor
+			// (see reposition) rather than the field's DOM rect.
+			let anchorPage: { x: number; y: number } | null = null
+			let popupWidth = 0
+
+			const applyScreen = (left: number, top: number, width: number) => {
+				if (!container) return
+				container.style.left = `${left}px`
+				container.style.top = `${top + 4}px`
+				container.style.width = `${width}px`
+			}
+
+			// Fresh placement: read the field's real screen rect, position the popup flush under it (not
+			// the caret, matching its width), and remember the field's page-space anchor for reposition.
+			const place = () => {
+				if (!container || !editorEl || container.style.display === 'none') return
+				const field = editorEl.closest('.cmt-composer__field') ?? editorEl
+				const rect = field.getBoundingClientRect()
+				popupWidth = rect.width
+				anchorPage = options.editor?.screenToPage({ x: rect.left, y: rect.bottom }) ?? null
+				applyScreen(rect.left, rect.bottom, rect.width)
+			}
+
+			// Re-derive the popup's screen position from the remembered page anchor — pure camera math,
+			// always current. Reading the field's DOM rect here instead would lag by a frame: the canvas
+			// composer re-positions itself on a React commit (a `useValue(pageToViewport(...))`), which
+			// lands after a camera reaction runs, so the rect is still last frame's during a pan.
+			const reposition = () => {
+				if (!anchorPage || !options.editor) return
+				const s = options.editor.pageToScreen(anchorPage)
+				applyScreen(s.x, s.y, popupWidth)
+			}
+
+			// The popup is `position: fixed`, but its anchor — a canvas composer — rides the camera:
+			// panning or zooming moves the composer with no scroll/resize event to hook. Re-anchor when
+			// the camera actually changes (via a tldraw reaction) rather than polling every frame, plus
+			// on window scroll/resize for the off-canvas case (which re-read the field directly).
+			const startFollowing = () => {
+				window.addEventListener('scroll', place, true)
+				window.addEventListener('resize', place)
+				if (options.editor) {
+					stopCameraReaction = react('anchor mention popup to camera', () => {
+						options.editor!.getCamera() // track the camera so this re-runs as it moves
+						reposition()
+					})
+				}
+			}
+			const stopFollowing = () => {
+				window.removeEventListener('scroll', place, true)
+				window.removeEventListener('resize', place)
+				stopCameraReaction?.()
+				stopCameraReaction = null
+				anchorPage = null
+			}
+
+			// Dismiss the roster — on Escape, or when the composer loses focus — by hiding it and
+			// clearing the open flag, so isMentionPickerOpen() stays accurate and the thread's own
+			// Escape/outside-click dismissal can take over. The TipTap suggestion stays active, so typing
+			// re-shows the roster via onUpdate.
+			const hide = () => {
+				if (container) container.style.display = 'none'
+				mentionPickerOpen.set(false)
+			}
+
+			// Wheel/panning over the popup drives the canvas beneath it, so scrolling to pan or zoom
+			// isn't swallowed by the roster — the same passthrough the rest of the comments UI gets from
+			// `usePassThroughWheelEvents`. The list still scrolls itself when the roster overflows (we
+			// only redispatch when it can't). Done imperatively because the popup lives outside React.
+			const onWheel = (e: WheelEvent) => {
+				if ((e as any).isSpecialRedispatchedEvent || !canvasEl) return
+				const list = container?.querySelector('.cmt-mention-list')
+				if (list && list.scrollHeight > list.clientHeight) return
+				e.preventDefault()
+				const redispatched = new WheelEvent('wheel', e)
+				;(redispatched as any).isSpecialRedispatchedEvent = true
+				canvasEl.dispatchEvent(redispatched)
+			}
+
+			return {
+				onStart: (props) => {
+					renderer = new ReactRenderer(MentionPopup, {
+						props: {
+							items: props.items,
+							command: props.command,
+							renderMember: options.renderMember,
+						},
+						editor: props.editor,
+					})
+					editorEl = props.editor.view.dom as HTMLElement
+					// The TipTap suggestion has no blur handling, so without this the picker would stay
+					// "open" (and the thread would defer its Escape to it) after focus moved away from the
+					// composer — leaving Escape a no-op and the roster stuck on screen.
+					editorEl.addEventListener('blur', hide)
+					container = document.createElement('div')
+					container.className = 'cmt-mention-popup'
+					container.appendChild(renderer.element)
+					// Mount inside the tldraw container so the popup inherits the theme variables
+					// (--tl-color-*); portaling to document.body would strip them and lose the panel.
+					const themed = editorEl.closest('.tl-container')
+					;(themed ?? document.body).appendChild(container)
+					canvasEl = themed?.querySelector('.tl-canvas') ?? null
+					container.addEventListener('wheel', onWheel, { passive: false })
+					place()
+					startFollowing()
+					mentionPickerOpen.set(true)
+				},
+				onUpdate: (props) => {
+					if (renderer)
+						renderer.updateProps({
+							items: props.items,
+							command: props.command,
+							renderMember: options.renderMember,
+						})
+					// Typing after an Escape re-shows the roster.
+					if (container) container.style.display = ''
+					mentionPickerOpen.set(true)
+					place()
+				},
+				onKeyDown: (props) => {
+					// Once the roster is hidden (a prior Escape), the TipTap suggestion is still active but
+					// this handler goes inert — every key passes through to the composer/thread (so a second
+					// Escape closes them, and Arrow/Enter don't select from an invisible list). Typing
+					// re-shows the roster via onUpdate.
+					if (!isMentionPickerOpen()) return false
+					if (props.event.key === 'Escape') {
+						// Dismiss only the roster: hide it and stop the key so the composer/thread beneath
+						// doesn't also treat Escape as "abandon".
+						hide()
+						props.event.stopPropagation()
+						return true
+					}
+					if (props.event.key === 'Enter' || props.event.key === 'Tab') {
+						// Complete the highlighted member if there is one to complete; if the roster is empty
+						// there's nothing to pick, so cancel the picker and swallow the key — the composer
+						// beneath neither submits (Enter) nor moves focus / indents (Tab).
+						const completed = renderer?.ref?.onKeyDown(props) ?? false
+						if (!completed) {
+							hide()
+							props.event.stopPropagation()
+						}
+						return true
+					}
+					if (renderer && renderer.ref) return renderer.ref.onKeyDown(props)
+					return false
+				},
+				onExit: () => {
+					stopFollowing()
+					if (editorEl) editorEl.removeEventListener('blur', hide)
+					if (container) container.removeEventListener('wheel', onWheel)
+					if (container) container.remove()
+					if (renderer) renderer.destroy()
+					renderer = null
+					container = null
+					canvasEl = null
+					mentionPickerOpen.set(false)
+				},
+			}
+		},
+	}
+}

package/src/ui/mention.tsx

@@ -0,0 +1,9 @@
+/** @public */
+export interface MentionProps {
+	name: string
+}
+
+/** An \@-mention pill for referencing a person in a comment. @public @react */
+export function Mention({ name }: MentionProps) {
+	return <span className="cmt-mention">@{name}</span>
+}

package/src/ui/reaction.tsx

@@ -0,0 +1,16 @@
+/** @public */
+export interface ReactionProps {
+	emoji: string
+	count: number
+	active: boolean
+}
+
+/** A single emoji reaction pill with a count, highlighted when the user reacted. @public @react */
+export function Reaction({ emoji, count, active }: ReactionProps) {
+	return (
+		<button className={active ? 'cmt-reaction cmt-reaction--active' : 'cmt-reaction'} type="button">
+			<span className="cmt-reaction__emoji">{emoji}</span>
+			<span className="cmt-reaction__count">{count}</span>
+		</button>
+	)
+}

package/src/ui/reactions.tsx

@@ -0,0 +1,15 @@
+import { Reaction } from './reaction'
+
+/** The row of reactions under a comment, plus an add-reaction button. @public @react */
+export function Reactions() {
+	return (
+		<div className="cmt-reactions">
+			<Reaction emoji="👍" count={3} active={true} />
+			<Reaction emoji="🎉" count={1} active={false} />
+			<Reaction emoji="👀" count={2} active={false} />
+			<button className="cmt-reaction cmt-reaction--add" type="button" aria-label="Add reaction">
+				＋
+			</button>
+		</div>
+	)
+}

package/src/ui/render-markdown.tsx

@@ -0,0 +1,72 @@
+import { Fragment, ReactNode } from 'react'
+
+/**
+ * Minimal markdown for comment bodies: paragraphs, line breaks, bullet lists, and
+ * inline **bold**, *italic*, `code`, and [links](url). Not a full CommonMark parser —
+ * just the markdown people actually write in comments. Renders React elements only —
+ * never raw HTML — so there's no HTML-injection surface.
+ * @public
+ */
+export function renderMarkdown(text: string): ReactNode {
+	return text
+		.trim()
+		.split(/\n{2,}/)
+		.map((block, i) => {
+			const lines = block.split('\n')
+			if (lines.every((line) => /^\s*[-*]\s+/.test(line))) {
+				return (
+					<ul key={i} className="md-list">
+						{lines.map((line, j) => (
+							<li key={j}>{renderInline(line.replace(/^\s*[-*]\s+/, ''))}</li>
+						))}
+					</ul>
+				)
+			}
+			return (
+				<p key={i} className="md-p">
+					{lines.map((line, j) => (
+						<Fragment key={j}>
+							{j > 0 && <br />}
+							{renderInline(line)}
+						</Fragment>
+					))}
+				</p>
+			)
+		})
+}
+
+const INLINE = /(\*\*[^*]+\*\*|\*[^*]+\*|_[^_]+_|`[^`]+`|\[[^\]]+\]\([^)]+\))/g
+
+function renderInline(text: string): ReactNode {
+	const out: ReactNode[] = []
+	let last = 0
+	let key = 0
+	for (const match of text.matchAll(INLINE)) {
+		const index = match.index ?? 0
+		if (index > last) out.push(text.slice(last, index))
+		out.push(renderToken(match[0], key++))
+		last = index + match[0].length
+	}
+	if (last < text.length) out.push(text.slice(last))
+	return out
+}
+
+function renderToken(token: string, key: number): ReactNode {
+	if (token.startsWith('**')) return <strong key={key}>{token.slice(2, -2)}</strong>
+	if (token.startsWith('`'))
+		return (
+			<code key={key} className="md-code">
+				{token.slice(1, -1)}
+			</code>
+		)
+	if (token.startsWith('[')) {
+		const link = /\[([^\]]+)\]\(([^)]+)\)/.exec(token)
+		if (!link) return token
+		return (
+			<a key={key} href={link[2]} target="_blank" rel="noreferrer">
+				{link[1]}
+			</a>
+		)
+	}
+	return <em key={key}>{token.slice(1, -1)}</em>
+}

package/src/ui/send-button.tsx

@@ -0,0 +1,15 @@
+/** @public */
+export interface SendButtonProps {
+	label: string
+	disabled?: boolean
+	onClick?(): void
+}
+
+/** The button that posts a comment. @public @react */
+export function SendButton({ label, disabled, onClick }: SendButtonProps) {
+	return (
+		<button className="cmt-send" type="button" disabled={disabled} onClick={onClick}>
+			{label}
+		</button>
+	)
+}