@tldraw/commenting 0.0.0-bootstrap

package/src/ui/comment-mention.ts

@@ -0,0 +1,47 @@
+import { mergeAttributes } from '@tiptap/core'
+import { Mention, type MentionNodeAttrs, type MentionOptions } from '@tiptap/extension-mention'
+
+/**
+ * A mention node's display name: the member's current name, resolved live from its id when a
+ * resolver is given (so a rename shows through), falling back to the label captured at insert time
+ * when no source can name the id — e.g. a deleted account. The stored id is always the source of
+ * truth; live resolution only freshens the displayed name over that captured label.
+ */
+function mentionName(
+	attrs: MentionNodeAttrs,
+	resolveName?: (id: string) => string | undefined
+): string {
+	const resolved = attrs.id && resolveName ? resolveName(attrs.id) : undefined
+	return resolved ?? attrs.label ?? attrs.id ?? ''
+}
+
+export interface CommentMentionOptions {
+	/**
+	 * Resolve a member id to its current display name — for the read-only render paths. Returns
+	 * `undefined` when the id can't be resolved, so the render falls back to the mention's stored label.
+	 */
+	resolveName?(id: string): string | undefined
+	/** The `@`-picker suggestion config — for the composer (omit on the render paths). */
+	suggestion?: MentionOptions['suggestion']
+}
+
+/**
+ * The comment @-mention node — TipTap's `Mention` configured to render as a `.cmt-mention` pill.
+ *
+ * A factory rather than a shared constant because it's configured differently per context: the
+ * read-only render paths pass `resolveName` (so the stored `{ id }` node always shows the member's
+ * current name, not a copy frozen at insert time), while the composer passes a `suggestion` (the
+ * `@` picker). The node schema is identical either way — only these two levers differ.
+ */
+export function commentMention({ resolveName, suggestion }: CommentMentionOptions = {}) {
+	return Mention.configure({
+		HTMLAttributes: { class: 'cmt-mention' },
+		renderText: ({ node }) => `@${mentionName(node.attrs as MentionNodeAttrs, resolveName)}`,
+		renderHTML: ({ node, options }) => [
+			'span',
+			mergeAttributes(options.HTMLAttributes, { 'data-mention-id': node.attrs.id }),
+			`@${mentionName(node.attrs as MentionNodeAttrs, resolveName)}`,
+		],
+		...(suggestion ? { suggestion } : {}),
+	})
+}

package/src/ui/comment-pin.tsx

@@ -0,0 +1,21 @@
+import { ReactNode } from 'react'
+
+/** @public */
+export interface CommentPinProps {
+	/** What the pin shows when unresolved — a number, an author initial, an <Avatar>, etc.
+	 *  Left as a lever so consumers aren't locked into a count. */
+	children?: ReactNode
+	resolved?: boolean
+	/** The pin's thread is open — shows the active/selected indicator state. */
+	open?: boolean
+}
+
+/** A canvas comment marker: shows its `children` (or a check when resolved). Purely
+ * presentational — it reflects open/resolved state via CSS; wrap it to make it clickable.
+ * @public @react */
+export function CommentPin({ children, resolved, open }: CommentPinProps) {
+	const className = ['cmt-pin', resolved && 'cmt-pin--resolved', open && 'cmt-pin--open']
+		.filter(Boolean)
+		.join(' ')
+	return <div className={className}>{resolved ? '✓' : children}</div>
+}

package/src/ui/comment-text.tsx

@@ -0,0 +1,12 @@
+import { renderMarkdown } from './render-markdown'
+
+/** @public */
+export interface CommentTextProps {
+	/** Rich text body, authored as markdown. */
+	text: string
+}
+
+/** A comment's body, rendered as markdown (bold, italic, code, links, lists). @public @react */
+export function CommentText({ text }: CommentTextProps) {
+	return <div className="cmt-text">{renderMarkdown(text)}</div>
+}

package/src/ui/comment-thread.tsx

@@ -0,0 +1,56 @@
+import { ReactNode } from 'react'
+import { CommentCard, CommentCardProps } from './comment-card'
+import { CommentComposer, CommentComposerProps } from './comment-composer'
+
+/** @public */
+export interface CommentThreadProps {
+	/** The thread's comments, already adapted to card props (oldest first). */
+	comments: CommentCardProps[]
+	/** Optional header, e.g. "Thread". Omit for no header. */
+	header?: ReactNode
+	/** Action controls shown at the right of the header (resolve, delete, dismiss…). */
+	headerActions?: ReactNode
+	/** When set, shows a banner above the comments (e.g. "Resolved by Jess"). */
+	resolvedBanner?: ReactNode
+	/** Reply composer props. Omit for a read-only thread (no composer). */
+	composer?: CommentComposerProps
+	/** Override how each comment renders. Defaults to `<CommentCard>`. */
+	renderComment?(comment: CommentCardProps, index: number): ReactNode
+}
+
+/**
+ * A comment thread: an optional header, an optional resolved banner, the comments, and an
+ * optional reply composer. Presentational — you supply the comments (as card props) and the
+ * composer's handlers; how each comment renders is overridable via `renderComment`.
+ * @public @react
+ */
+export function CommentThread({
+	comments,
+	header,
+	headerActions,
+	resolvedBanner,
+	composer,
+	renderComment,
+}: CommentThreadProps) {
+	return (
+		<div className="cmt-thread">
+			{(header !== undefined || headerActions !== undefined) && (
+				<div className="cmt-thread__header">
+					<span className="cmt-thread__title">{header}</span>
+					{headerActions !== undefined && (
+						<div className="cmt-thread__actions">{headerActions}</div>
+					)}
+				</div>
+			)}
+			{resolvedBanner !== undefined && <div className="cmt-thread__resolved">{resolvedBanner}</div>}
+			<div className="cmt-thread__list">
+				{comments.map((comment, i) => (
+					<div key={i}>
+						{renderComment ? renderComment(comment, i) : <CommentCard {...comment} />}
+					</div>
+				))}
+			</div>
+			{composer !== undefined && <CommentComposer {...composer} />}
+		</div>
+	)
+}

package/src/ui/comments-list.tsx

@@ -0,0 +1,139 @@
+import { ReactNode } from 'react'
+import { Avatar } from './avatar'
+import { Byline } from './byline'
+
+/** @public */
+export interface CommentListItemProps {
+	id: string
+	author: string
+	/** A short preview of the thread — e.g. the first comment's body. */
+	preview: ReactNode
+	/** ISO datetime of the thread's first comment. */
+	date: string
+	resolved?: boolean
+	/** Name of the page the thread lives on, shown as a small label. Omit to hide. */
+	page?: string
+	/** Total comments in the thread. */
+	count?: number
+	/** Whether this thread is the open one. */
+	selected?: boolean
+}
+
+/** @public */
+export interface CommentsListProps {
+	items: CommentListItemProps[]
+	/** Called with a thread id when an item is chosen. */
+	onSelect?(id: string): void
+	/** Shown above the list (e.g. "Comments"). Omit for none. */
+	header?: ReactNode
+	/** Rendered at the right of the header row — e.g. a filter menu. */
+	headerAction?: ReactNode
+	/** Shown in place of the list when there are no threads. */
+	empty?: ReactNode
+	/** Label for a resolved thread's marker on its row. Defaults to "Resolved". */
+	resolvedLabel?: string
+	/** Override how each item renders. Defaults to `<CommentListItem>`. */
+	renderItem?(item: CommentListItemProps): ReactNode
+}
+
+/**
+ * A scrollable list of comment threads — each an avatar, byline, and a one-line preview.
+ * Presentational: you supply the items (already summarised) and an `onSelect` handler; the canvas
+ * `CanvasCommentsSidebar` wires it to the store, but a consumer can build their own list from this.
+ * @public @react
+ */
+export function CommentsList({
+	items,
+	onSelect,
+	header,
+	headerAction,
+	empty,
+	resolvedLabel,
+	renderItem,
+}: CommentsListProps) {
+	return (
+		<div className="cmt-list">
+			{(header !== undefined || headerAction) && (
+				<div className="cmt-list__header">
+					{header !== undefined && <span className="cmt-list__header-title">{header}</span>}
+					{headerAction}
+				</div>
+			)}
+			{items.length === 0 ? (
+				<div className="cmt-list__empty">{empty}</div>
+			) : (
+				<div className="cmt-list__items">
+					{items.map((item) =>
+						renderItem ? (
+							renderItem(item)
+						) : (
+							<CommentListItem
+								key={item.id}
+								{...item}
+								resolvedLabel={resolvedLabel}
+								onSelect={onSelect}
+							/>
+						)
+					)}
+				</div>
+			)}
+		</div>
+	)
+}
+
+function CommentListItem({
+	id,
+	author,
+	preview,
+	date,
+	resolved,
+	page,
+	count,
+	selected,
+	resolvedLabel = 'Resolved',
+	onSelect,
+}: CommentListItemProps & { resolvedLabel?: string; onSelect?(id: string): void }) {
+	const handleClick = () => {
+		if (onSelect) onSelect(id)
+	}
+	return (
+		<button
+			type="button"
+			className={selected ? 'cmt-list__item cmt-list__item--selected' : 'cmt-list__item'}
+			data-resolved={resolved || undefined}
+			onClick={handleClick}
+		>
+			<Avatar name={author} />
+			<div className="cmt-list__item-body">
+				<Byline author={author} date={date} />
+				<div className="cmt-list__item-preview">{preview}</div>
+				{(resolved || page !== undefined) && (
+					<div className="cmt-list__item-meta">
+						{resolved && (
+							<span className="cmt-list__item-resolved">
+								<CheckIcon />
+								{resolvedLabel}
+							</span>
+						)}
+						{page !== undefined && <span className="cmt-list__item-page">{page}</span>}
+					</div>
+				)}
+			</div>
+			{count !== undefined && count > 1 && <span className="cmt-list__item-count">{count}</span>}
+		</button>
+	)
+}
+
+function CheckIcon() {
+	return (
+		<svg width="12" height="12" viewBox="0 0 12 12" fill="none" aria-hidden="true">
+			<path
+				d="M2.5 6.2 4.7 8.4 9.5 3.6"
+				stroke="currentColor"
+				strokeWidth="1.5"
+				strokeLinecap="round"
+				strokeLinejoin="round"
+			/>
+		</svg>
+	)
+}