@tldraw/commenting 0.0.0-bootstrap

package/src/canvas/comment-tool.tsx

@@ -0,0 +1,200 @@
+import {
+	BoxModel,
+	StateNode,
+	TLCommentAnchor,
+	TLStateNodeConstructor,
+	TLUiOverrides,
+	VecLike,
+} from 'tldraw'
+import { type CommentingOptions, defaultCommentingOptions } from './options'
+import { getRegionCommentOptions } from './region-options'
+import { pendingComment, regionDraft } from './state'
+import { regionPinPoint, shapeAnchorAt } from './thread-state'
+
+/** A comment being placed but not yet posted: where its composer sits and what it will anchor
+ *  to. Shared between the tool (which sets it on click) and the overlay (which renders the
+ *  composer). Null when nothing is being placed. The atom itself lives in `./state`
+ *  ({@link pendingComment}), scoped per editor.
+ * @public */
+export interface PendingComment {
+	anchor: TLCommentAnchor
+	/** Page point where the composer opens (the click location, or a region's pin corner). */
+	point: VecLike
+}
+
+/**
+ * Merge configure options over a base. Shallow for scalars; `components` is merged rather than
+ * replaced so chained `configure` calls layer their slots — a later `{ components: { PinContent } }`
+ * doesn't drop an earlier `{ components: { CommentBody } }`.
+ */
+function mergeCommentingOptions(
+	base: CommentingOptions,
+	overrides: Partial<CommentingOptions>
+): CommentingOptions {
+	return {
+		...base,
+		...overrides,
+		components: { ...base.components, ...overrides.components },
+	}
+}
+
+/** The page-space rectangle spanned by two points, normalized so w/h are non-negative. Shared by
+ *  region creation (pointer-down → cursor) and corner resize (fixed corner → cursor). */
+export function regionBetween(a: VecLike, b: VecLike): BoxModel {
+	return {
+		x: Math.min(a.x, b.x),
+		y: Math.min(a.y, b.y),
+		w: Math.abs(a.x - b.x),
+		h: Math.abs(a.y - b.y),
+	}
+}
+
+/**
+ * The comment tool. A click starts a point/shape thread (the pin tracks the shape it lands on);
+ * dragging out a rectangle starts a region thread anchored to that area. Placement only opens a
+ * composer (via `pendingComment`); the records are created when the comment is posted.
+ * @public
+ */
+export class CommentTool extends StateNode {
+	static override id = 'comment'
+	static override initial = 'idle'
+	static override children(): TLStateNodeConstructor[] {
+		return [CommentIdle, CommentPointing, CommentDragging]
+	}
+
+	/**
+	 * Configure this tool's {@link CommentTool.options | `options`}, returning a configured subclass
+	 * to register via `tools`. Mirrors `ShapeUtil.configure`. Layers over any prior `configure`, so
+	 * calls can be chained.
+	 *
+	 * @example
+	 * ```tsx
+	 * <Tldraw tools={[CommentTool.configure({ history: 'ignore', enableClustering: false })]} />
+	 * ```
+	 */
+	static configure<T extends TLStateNodeConstructor>(
+		this: T,
+		options: T extends new (...args: any[]) => { options: infer Options } ? Partial<Options> : never
+	): T {
+		// @ts-expect-error -- mirrors ShapeUtil.configure; extending `this` is sound at runtime.
+		return class extends this {
+			// @ts-expect-error
+			options = mergeCommentingOptions(this.options, options)
+		}
+	}
+
+	/**
+	 * The merged commenting options for this editor. Read from anywhere via
+	 * {@link getCommentingOptions}. Override with {@link CommentTool.configure}.
+	 */
+	options: CommentingOptions = defaultCommentingOptions
+
+	override onEnter() {
+		this.editor.setCursor({ type: 'cross', rotation: 0 })
+	}
+
+	// Escape leaves the tool, like the built-in tools (the editor dispatches `cancel` on Escape).
+	override onCancel() {
+		this.editor.setCurrentTool('select')
+	}
+}
+
+class CommentIdle extends StateNode {
+	static override id = 'idle'
+
+	override onPointerDown() {
+		this.parent.transition('pointing')
+	}
+}
+
+class CommentPointing extends StateNode {
+	static override id = 'pointing'
+
+	// Once the pointer passes the editor's drag threshold this is a region, not a click — but only
+	// when region comments are enabled; otherwise a drag is treated as a click (point/shape).
+	override onPointerMove() {
+		if (getRegionCommentOptions(this.editor).enabled && this.editor.inputs.getIsDragging()) {
+			this.parent.transition('dragging')
+		}
+	}
+
+	// A pointer up with no drag is a click: anchor to the shape under it, or drop a point.
+	override onPointerUp() {
+		const { editor } = this
+		const point = editor.inputs.getCurrentPagePoint()
+		const hit = editor.getShapeAtPoint(point, { hitInside: true })
+		const anchor: TLCommentAnchor = hit
+			? shapeAnchorAt(editor, hit.id, point, editor.inputs.getAltKey())
+			: { type: 'point', x: point.x, y: point.y }
+		pendingComment.set(editor, { anchor, point: { x: point.x, y: point.y } })
+		// Hand back to select; the open composer is now the focus.
+		editor.setCurrentTool('select')
+	}
+}
+
+class CommentDragging extends StateNode {
+	static override id = 'dragging'
+
+	override onEnter() {
+		this.updateDraft()
+	}
+
+	override onPointerMove() {
+		this.updateDraft()
+	}
+
+	// Commit the dragged rectangle as a region anchor; the composer opens at its pin corner.
+	override onPointerUp() {
+		const { editor } = this
+		const region = regionBetween(
+			editor.inputs.getOriginPagePoint(),
+			editor.inputs.getCurrentPagePoint()
+		)
+		regionDraft.set(editor, null)
+		pendingComment.set(editor, {
+			anchor: { type: 'region', ...region },
+			point: regionPinPoint(region, getRegionCommentOptions(editor).pinCorner),
+		})
+		editor.setCurrentTool('select')
+	}
+
+	override onCancel() {
+		this.cancel()
+	}
+
+	override onInterrupt() {
+		this.cancel()
+	}
+
+	private updateDraft() {
+		const { editor } = this
+		regionDraft.set(
+			editor,
+			regionBetween(editor.inputs.getOriginPagePoint(), editor.inputs.getCurrentPagePoint())
+		)
+	}
+
+	private cancel() {
+		regionDraft.set(this.editor, null)
+		this.editor.setCurrentTool('select')
+	}
+}
+
+/** @public */
+export const commentTools = [CommentTool]
+
+/** Registers the comment tool in the UI (icon, label, shortcut). Compose into your overrides.
+ *  Once registered, tldraw's `DefaultToolbarContent` shows the comment button next to the eraser.
+ * @public */
+export const commentToolOverrides: TLUiOverrides = {
+	tools(editor, tools) {
+		tools.comment = {
+			id: 'comment',
+			icon: 'comment',
+			label: 'Comment',
+			kbd: 'c',
+			onSelect: () => editor.setCurrentTool('comment'),
+		}
+		return tools
+	},
+}

package/src/canvas/comments-filter-menu.tsx

@@ -0,0 +1,104 @@
+import {
+	TldrawUiDropdownMenuContent,
+	TldrawUiDropdownMenuRoot,
+	TldrawUiDropdownMenuTrigger,
+	TldrawUiMenuCheckboxItem,
+	TldrawUiMenuContextProvider,
+	TldrawUiMenuGroup,
+	useEditor,
+	useTranslation,
+	useValue,
+} from 'tldraw'
+import { SidebarFilters } from './sidebar-filters'
+import { sidebarFilters } from './state'
+
+/** @public */
+export interface CommentsFilterMenuProps {
+	/** Whether to offer the "only your threads" toggle (needs a known current user). */
+	canFilterByAuthor?: boolean
+	/** Whether to offer the "only unread" toggle (needs a read-status source). */
+	canFilterByUnread?: boolean
+}
+
+/** The funnel dropdown in the sidebar header: toggles for which threads the list shows.
+ * @public @react */
+export function CommentsFilterMenu({
+	canFilterByAuthor,
+	canFilterByUnread,
+}: CommentsFilterMenuProps) {
+	const editor = useEditor()
+	const msg = useTranslation()
+	const filters = useValue('sidebar filters', () => sidebarFilters.get(editor), [editor])
+	const toggle = (key: keyof SidebarFilters) => {
+		sidebarFilters.update(editor, (f) => ({ ...f, [key]: !f[key] }))
+	}
+
+	return (
+		<TldrawUiDropdownMenuRoot id="comments-filter">
+			<TldrawUiDropdownMenuTrigger>
+				<button
+					type="button"
+					className="cmt-header-btn"
+					title={msg('comments.filter')}
+					aria-label={msg('comments.filter')}
+				>
+					<FilterIcon />
+				</button>
+			</TldrawUiDropdownMenuTrigger>
+			<TldrawUiDropdownMenuContent side="bottom" align="start">
+				<TldrawUiMenuContextProvider type="menu" sourceId="menu">
+					<TldrawUiMenuGroup id="comments-filter">
+						<TldrawUiMenuCheckboxItem
+							id="show-resolved"
+							label="comments.show-resolved"
+							checked={filters.showResolved}
+							onSelect={() => toggle('showResolved')}
+						/>
+						{canFilterByAuthor && (
+							<TldrawUiMenuCheckboxItem
+								id="only-mine"
+								label="comments.only-mine"
+								checked={filters.onlyMine}
+								onSelect={() => toggle('onlyMine')}
+							/>
+						)}
+						{canFilterByUnread && (
+							<TldrawUiMenuCheckboxItem
+								id="only-unread"
+								label="comments.only-unread"
+								checked={filters.onlyUnread}
+								onSelect={() => toggle('onlyUnread')}
+							/>
+						)}
+						<TldrawUiMenuCheckboxItem
+							id="only-current-page"
+							label="comments.only-current-page"
+							checked={filters.onlyCurrentPage}
+							onSelect={() => toggle('onlyCurrentPage')}
+						/>
+					</TldrawUiMenuGroup>
+				</TldrawUiMenuContextProvider>
+			</TldrawUiDropdownMenuContent>
+		</TldrawUiDropdownMenuRoot>
+	)
+}
+
+function FilterIcon() {
+	return (
+		<svg
+			width="16"
+			height="16"
+			viewBox="0 0 16 16"
+			fill="none"
+			stroke="currentColor"
+			strokeWidth="1.5"
+			strokeLinecap="round"
+			aria-hidden="true"
+		>
+			<line x1="2.5" y1="5" x2="13.5" y2="5" />
+			<line x1="2.5" y1="11" x2="13.5" y2="11" />
+			<circle cx="6" cy="5" r="1.9" fill="currentColor" stroke="none" />
+			<circle cx="10.5" cy="11" r="1.9" fill="currentColor" stroke="none" />
+		</svg>
+	)
+}

package/src/canvas/comments-menu-item.tsx

@@ -0,0 +1,24 @@
+import { TldrawUiMenuCheckboxItem, useEditor, useValue } from 'tldraw'
+import { commentsHidden, toggleCommentsHidden } from './state'
+
+/**
+ * A checkbox menu item for a "View" menu that shows/hides comment pins on the canvas — checked
+ * when comments are visible, like tldraw's own grid/snap toggles. Reads and toggles the shared
+ * {@link commentsHidden} signal, so it stays in sync with the Shift+C shortcut and the sidebar
+ * control. Drop it into whichever menu your app owns.
+ * @public @react
+ */
+export function CommentsMenuItem() {
+	const editor = useEditor()
+	const hidden = useValue('comments hidden', () => commentsHidden.get(editor), [editor])
+	return (
+		<TldrawUiMenuCheckboxItem
+			id="comments-visible"
+			label="comments.title"
+			kbd="!c"
+			readonlyOk
+			checked={!hidden}
+			onSelect={() => toggleCommentsHidden(editor)}
+		/>
+	)
+}

package/src/canvas/comments-overflow-menu.tsx

@@ -0,0 +1,62 @@
+import {
+	TldrawUiDropdownMenuContent,
+	TldrawUiDropdownMenuGroup,
+	TldrawUiDropdownMenuItem,
+	TldrawUiDropdownMenuRoot,
+	TldrawUiDropdownMenuTrigger,
+	useEditor,
+	useTranslation,
+	useValue,
+} from 'tldraw'
+import { commentsHidden, toggleCommentsHidden } from './state'
+
+// A keyboard-shortcut glyph, not translatable copy — kept out of JSX as a constant.
+const HIDE_SHORTCUT = '⇧C'
+
+/** The overflow (⋯) dropdown in the sidebar header. For now it holds the hide/show-comments
+ *  toggle; it's the home for later comment-wide controls (notifications, mark all as read).
+ * @public @react */
+export function CommentsOverflowMenu() {
+	const editor = useEditor()
+	const msg = useTranslation()
+	const hidden = useValue('comments hidden', () => commentsHidden.get(editor), [editor])
+
+	return (
+		<TldrawUiDropdownMenuRoot id="comments-overflow">
+			<TldrawUiDropdownMenuTrigger>
+				<button
+					type="button"
+					className="cmt-header-btn"
+					title={msg('comments.more-options')}
+					aria-label={msg('comments.more-options')}
+				>
+					<MoreIcon />
+				</button>
+			</TldrawUiDropdownMenuTrigger>
+			<TldrawUiDropdownMenuContent side="bottom" align="end">
+				<TldrawUiDropdownMenuGroup>
+					<TldrawUiDropdownMenuItem>
+						<button
+							type="button"
+							className="cmt-menu-item"
+							onClick={() => toggleCommentsHidden(editor)}
+						>
+							<span>{hidden ? msg('comments.show') : msg('comments.hide')}</span>
+							<span className="cmt-menu-item__shortcut">{HIDE_SHORTCUT}</span>
+						</button>
+					</TldrawUiDropdownMenuItem>
+				</TldrawUiDropdownMenuGroup>
+			</TldrawUiDropdownMenuContent>
+		</TldrawUiDropdownMenuRoot>
+	)
+}
+
+function MoreIcon() {
+	return (
+		<svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true">
+			<circle cx="3" cy="8" r="1.4" />
+			<circle cx="8" cy="8" r="1.4" />
+			<circle cx="13" cy="8" r="1.4" />
+		</svg>
+	)
+}