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

package/src/ui/count-badge.tsx

@@ -1,9 +1,16 @@
 /** @public */
 export interface CountBadgeProps {
 	count: number
+	/** The badge's list is showing — shows the active/selected indicator state, as an open pin does. */
+	open?: boolean
 }
 
 /** @public @react */
-export function CountBadge({ count }: CountBadgeProps) {
-	return <div className="cmt-count-badge">{count}</div>
+export function CountBadge({ count, open }: CountBadgeProps) {
+	// `tlui-cmt-marker` carries the resting shadow, the hover lift, and the open ring — the same
+	// treatment a comment pin wears, so the two markers behave alike.
+	const className = ['tlui-cmt-marker', 'tlui-cmt-count-badge', open && 'tlui-cmt-marker--open']
+		.filter(Boolean)
+		.join(' ')
+	return <div className={className}>{count}</div>
 }

package/src/ui/emoji-picker.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest'
+import { DEFAULT_REACTION_EMOJI, isAllowedReactionEmoji } from './emoji-picker'
+
+describe('isAllowedReactionEmoji', () => {
+	it('accepts every emoji in the default palette', () => {
+		for (const emoji of DEFAULT_REACTION_EMOJI) {
+			expect(isAllowedReactionEmoji(emoji)).toBe(true)
+		}
+	})
+
+	it('rejects emoji not in the palette', () => {
+		expect(isAllowedReactionEmoji('🦄')).toBe(false)
+	})
+
+	// the record's emoji field is a free string, so this is the guard against junk values
+	it('rejects arbitrary non-emoji strings', () => {
+		expect(isAllowedReactionEmoji('not an emoji')).toBe(false)
+		expect(isAllowedReactionEmoji('')).toBe(false)
+	})
+
+	it('checks against a custom palette when given one', () => {
+		expect(isAllowedReactionEmoji('🦄', ['🦄', '🌈'])).toBe(true)
+		expect(isAllowedReactionEmoji('👍', ['🦄', '🌈'])).toBe(false)
+	})
+})

package/src/ui/emoji-picker.tsx

@@ -0,0 +1,76 @@
+import { RenderReaction, defaultRenderReaction } from './reaction'
+
+/**
+ * The reaction emoji palette: the small, opinionated set the picker offers *and* the set a
+ * reaction is allowed to use. It's deliberately short — a quick affordance under a comment, not a
+ * full emoji keyboard — and it's the single source of truth for "which emoji may a reaction
+ * carry". A reaction's `emoji` field is a free-form `string`, so this palette is what keeps it to
+ * real, offered emoji; check membership with {@link isAllowedReactionEmoji}. Pass a custom `emoji`
+ * array to `ReactionPicker` to offer a different set — validate against that same set if you do.
+ *
+ * @public
+ */
+export const DEFAULT_REACTION_EMOJI = ['👍', '👎', '❤️', '🎉', '😄', '😮', '😢', '🙏', '👀', '🔥']
+
+/**
+ * Whether `emoji` belongs to a reaction palette (defaults to {@link DEFAULT_REACTION_EMOJI}). Use
+ * it to reject arbitrary strings before writing a reaction, so a scripted client can't spam a
+ * comment with junk `emoji` values that the picker would never offer. Pass a custom `palette` to
+ * match a customized picker.
+ *
+ * @public
+ */
+export function isAllowedReactionEmoji(
+	emoji: string,
+	palette: readonly string[] = DEFAULT_REACTION_EMOJI
+): boolean {
+	return palette.includes(emoji)
+}
+
+/** @public */
+export interface EmojiPickerProps {
+	/** The emoji to offer. Defaults to `DEFAULT_REACTION_EMOJI`. */
+	emoji?: string[]
+	/** Emoji the current user has already reacted with; shown as pressed. */
+	selected?: string[]
+	/** Called when an emoji is chosen. */
+	onSelect?(emoji: string): void
+	/** How to draw each emoji token. Defaults to the token string (OS emoji font). */
+	renderReaction?: RenderReaction
+}
+
+/**
+ * A grid of emoji to react with. Presentational and unpositioned — the host owns placement and
+ * dismissal; `ReactionPicker` renders it in a dropdown under the add-reaction button.
+ * @public @react
+ */
+export function EmojiPicker({
+	emoji = DEFAULT_REACTION_EMOJI,
+	selected,
+	onSelect,
+	renderReaction = defaultRenderReaction,
+}: EmojiPickerProps) {
+	return (
+		<div className="tlui-cmt-emoji-picker" role="group">
+			{emoji.map((value) => {
+				const active = selected?.includes(value) ?? false
+				return (
+					<button
+						key={value}
+						type="button"
+						className={
+							active
+								? 'tlui-cmt-emoji-picker__item tlui-cmt-emoji-picker__item--active'
+								: 'tlui-cmt-emoji-picker__item'
+						}
+						aria-label={value}
+						aria-pressed={active}
+						onClick={() => onSelect?.(value)}
+					>
+						{renderReaction(value)}
+					</button>
+				)
+			})}
+		</div>
+	)
+}

package/src/ui/empty-state.tsx

@@ -6,11 +6,11 @@ export interface EmptyStateProps {
 /** The empty state shown when a thread has no comments yet. @public @react */
 export function EmptyState({ message }: EmptyStateProps) {
 	return (
-		<div className="cmt-empty">
-			<div className="cmt-empty__icon" aria-hidden="true">
+		<div className="tlui-cmt-empty">
+			<div className="tlui-cmt-empty__icon" aria-hidden="true">
 				💬
 			</div>
-			<p className="cmt-empty__message">{message}</p>
+			<p className="tlui-cmt-empty__message">{message}</p>
 		</div>
 	)
 }

package/src/ui/format-time.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest'
+import { formatFullDateTime, formatRelativeTime } from './format-time'
+
+/** An ISO timestamp `seconds` in the past, relative to now. */
+function agoIso(seconds: number): string {
+	return new Date(Date.now() - seconds * 1000).toISOString()
+}
+
+const TWO_HOURS = 2 * 60 * 60
+
+describe('formatRelativeTime', () => {
+	it('formats in English by default', () => {
+		expect(formatRelativeTime(agoIso(TWO_HOURS))).toBe(
+			new Intl.RelativeTimeFormat('en', { numeric: 'auto', style: 'short' }).format(-2, 'hour')
+		)
+	})
+
+	// `Byline` passes the UI's current translation locale; without this a localized app showed
+	// English timestamps under localized everything else.
+	it('formats in the given locale', () => {
+		const french = formatRelativeTime(agoIso(TWO_HOURS), 'fr')
+		expect(french).toBe(
+			new Intl.RelativeTimeFormat('fr', { numeric: 'auto', style: 'short' }).format(-2, 'hour')
+		)
+		expect(french).not.toBe(formatRelativeTime(agoIso(TWO_HOURS), 'en'))
+	})
+
+	// The parameter is optional, so undefined has to mean "the default", not "no locale".
+	it('treats an undefined locale as the default', () => {
+		expect(formatRelativeTime(agoIso(TWO_HOURS), undefined)).toBe(
+			formatRelativeTime(agoIso(TWO_HOURS))
+		)
+	})
+
+	it('reads under a minute as "now" in the given locale', () => {
+		expect(formatRelativeTime(agoIso(5), 'fr')).toBe(
+			new Intl.RelativeTimeFormat('fr', { numeric: 'auto', style: 'short' }).format(0, 'second')
+		)
+	})
+
+	it('returns nothing for an unparseable date', () => {
+		expect(formatRelativeTime('not a date', 'fr')).toBe('')
+	})
+})
+
+describe('formatFullDateTime', () => {
+	it('formats an ISO datetime as a full date and time', () => {
+		const iso = '2025-07-22T16:44:00.000Z'
+		expect(formatFullDateTime(iso)).toBe(
+			new Intl.DateTimeFormat('en', { dateStyle: 'full', timeStyle: 'short' }).format(new Date(iso))
+		)
+	})
+
+	it('formats in the given locale', () => {
+		const french = formatFullDateTime('2025-07-22T16:44:00.000Z', 'fr')
+		expect(french).toContain('juillet')
+		expect(french).not.toBe(formatFullDateTime('2025-07-22T16:44:00.000Z', 'en'))
+	})
+
+	// The parameter is optional, so undefined has to mean "the default", not "no locale".
+	it('treats an undefined locale as the default', () => {
+		const iso = '2025-07-22T16:44:00.000Z'
+		expect(formatFullDateTime(iso, undefined)).toBe(formatFullDateTime(iso))
+	})
+
+	it('returns an empty string for invalid dates', () => {
+		expect(formatFullDateTime('not a date')).toBe('')
+	})
+})

package/src/ui/format-time.ts

@@ -9,7 +9,7 @@ const DIVISIONS = [
 ] as const
 
 /**
- * Format an ISO datetime as relative time ("2 hours ago", "yesterday", "last week").
+ * Format an ISO datetime as short relative time ("2 hr. ago", "yesterday", "last wk.").
  * Locale-aware via Intl.RelativeTimeFormat.
  * @public
  */
@@ -17,8 +17,13 @@ export function formatRelativeTime(iso: string, locale = 'en'): string {
 	const then = new Date(iso).getTime()
 	if (Number.isNaN(then)) return ''
 
-	const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
+	const rtf = new Intl.RelativeTimeFormat(locale, { numeric: 'auto', style: 'short' })
 	let duration = (then - Date.now()) / 1000
+	// Under a minute is just "now" — with second granularity the label visibly ticks while
+	// typing a reply (every keystroke re-renders the card).
+	if (Math.abs(duration) < 60) {
+		return rtf.format(0, 'second')
+	}
 	for (const division of DIVISIONS) {
 		if (Math.abs(duration) < division.amount) {
 			return rtf.format(Math.round(duration), division.unit)
@@ -27,3 +32,23 @@ export function formatRelativeTime(iso: string, locale = 'en'): string {
 	}
 	return ''
 }
+
+// Cached per locale — comment cards re-render on every reply keystroke, and constructing a
+// DateTimeFormat is far more expensive than formatting with one.
+const fullDateTimeFormatters = new Map<string, Intl.DateTimeFormat>()
+
+/**
+ * Format an ISO datetime as a full date and time ("Tuesday, July 22, 2025 at 4:44 PM").
+ * Locale-aware via Intl.DateTimeFormat.
+ * @public
+ */
+export function formatFullDateTime(iso: string, locale = 'en'): string {
+	const date = new Date(iso)
+	if (Number.isNaN(date.getTime())) return ''
+	let formatter = fullDateTimeFormatters.get(locale)
+	if (!formatter) {
+		formatter = new Intl.DateTimeFormat(locale, { dateStyle: 'full', timeStyle: 'short' })
+		fullDateTimeFormatters.set(locale, formatter)
+	}
+	return formatter.format(date)
+}

package/src/ui/icons.tsx

@@ -0,0 +1,116 @@
+/* The commenting UI's inline icons, kept together so the set is visible in one place.
+ *
+ * Anything with an equivalent in tldraw's icon assets goes through `TldrawUiIcon` instead (the ⋯
+ * menu, the dismiss cross, the resolve button's check). What's left lives here because the asset
+ * set has no counterpart — a smiley, a send arrow, the eye pair, a filter — or because the asset
+ * reads wrong at the size it's needed, which is the case for both resolved checks below. Inline
+ * also means they render without an `AssetUrlsProvider` and without the consumer serving files.
+ *
+ * All internal — none are exported from the package. */
+
+/** The check inside a resolved comment pin. A drawn check, not the '✓' glyph — that character sits
+ * off-baseline and varies by font. Heavier and rounder than `CheckIcon`: it has to hold its weight
+ * against the pin's 28px filled face, where the asset check reads too light. */
+export function PinCheckIcon() {
+	return (
+		<svg
+			viewBox="0 0 24 24"
+			width="15"
+			height="15"
+			fill="none"
+			stroke="currentColor"
+			strokeWidth="2.5"
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			aria-hidden="true"
+		>
+			<path d="M4 12.5l5 5L20 6.5" />
+		</svg>
+	)
+}
+
+/** The check beside the "Resolved" label on a comments list row. Thinner than `PinCheckIcon` — it
+ * sits next to text at 12px, so it's drawn to match the label's weight rather than shout. */
+export 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>
+	)
+}
+
+/** The reaction picker's trigger. */
+export function SmileyIcon() {
+	return (
+		<svg width="15" height="15" viewBox="0 0 15 15" fill="none" aria-hidden="true">
+			<path
+				d="M7.49991 0.876892C3.84222 0.876892 0.877075 3.84204 0.877075 7.49972C0.877075 11.1574 3.84222 14.1226 7.49991 14.1226C11.1576 14.1226 14.1227 11.1574 14.1227 7.49972C14.1227 3.84204 11.1576 0.876892 7.49991 0.876892ZM1.82708 7.49972C1.82708 4.36671 4.36689 1.82689 7.49991 1.82689C10.6329 1.82689 13.1727 4.36671 13.1727 7.49972C13.1727 10.6327 10.6329 13.1726 7.49991 13.1726C4.36689 13.1726 1.82708 10.6327 1.82708 7.49972ZM5.03747 9.21395C4.87949 8.98746 4.56782 8.93193 4.34133 9.08991C4.11484 9.24789 4.05931 9.55956 4.21729 9.78605C4.93926 10.8211 6.14033 11.5 7.50004 11.5C8.85974 11.5 10.0608 10.8211 10.7828 9.78605C10.9408 9.55956 10.8852 9.24789 10.6587 9.08991C10.4323 8.93193 10.1206 8.98746 9.9626 9.21395C9.41963 9.99238 8.51907 10.5 7.50004 10.5C6.481 10.5 5.58044 9.99238 5.03747 9.21395ZM5.37503 6.84998C5.85828 6.84998 6.25003 6.45815 6.25003 5.97498C6.25003 5.4918 5.85828 5.09998 5.37503 5.09998C4.89179 5.09998 4.50003 5.4918 4.50003 5.97498C4.50003 6.45815 4.89179 6.84998 5.37503 6.84998ZM10.5 5.97498C10.5 6.45815 10.1083 6.84998 9.62503 6.84998C9.14179 6.84998 8.75003 6.45815 8.75003 5.97498C8.75003 5.4918 9.14179 5.09998 9.62503 5.09998C10.1083 5.09998 10.5 5.4918 10.5 5.97498Z"
+				fill="currentColor"
+				fillRule="evenodd"
+				clipRule="evenodd"
+			/>
+		</svg>
+	)
+}
+
+/** The composer's post button — an up arrow. */
+export function SendIcon() {
+	return (
+		<svg width="15" height="15" viewBox="0 0 15 15" fill="none" aria-hidden="true">
+			<path
+				d="M7.14645 2.14645C7.34171 1.95118 7.65829 1.95118 7.85355 2.14645L11.8536 6.14645C12.0488 6.34171 12.0488 6.65829 11.8536 6.85355C11.6583 7.04882 11.3417 7.04882 11.1464 6.85355L8 3.70711L8 12.5C8 12.7761 7.77614 13 7.5 13C7.22386 13 7 12.7761 7 12.5L7 3.70711L3.85355 6.85355C3.65829 7.04882 3.34171 7.04882 3.14645 6.85355C2.95118 6.65829 2.95118 6.34171 3.14645 6.14645L7.14645 2.14645Z"
+				fill="currentColor"
+				fillRule="evenodd"
+				clipRule="evenodd"
+			/>
+		</svg>
+	)
+}
+
+/** Comment pins are showing. Pairs with `EyeClosedIcon` — the two must stay the same family. */
+export function EyeOpenIcon() {
+	return (
+		<svg width="15" height="15" viewBox="0 0 15 15" fill="none" aria-hidden="true">
+			<path
+				d="M7.5 11C4.80285 11 2.52952 9.62184 1.09622 7.50001C2.52952 5.37816 4.80285 4 7.5 4C10.1971 4 12.4705 5.37816 13.9038 7.5C12.4705 9.62183 10.1971 11 7.5 11ZM7.5 3C4.30786 3 1.65639 4.70638 0.0760002 7.23501C-0.0253338 7.39715 -0.0253334 7.60288 0.0760014 7.76501C1.65639 10.2936 4.30786 12 7.5 12C10.6921 12 13.3436 10.2936 14.924 7.76501C15.0253 7.60288 15.0253 7.39715 14.924 7.23501C13.3436 4.70638 10.6921 3 7.5 3ZM7.5 9.5C8.60457 9.5 9.5 8.60457 9.5 7.5C9.5 6.39543 8.60457 5.5 7.5 5.5C6.39543 5.5 5.5 6.39543 5.5 7.5C5.5 8.60457 6.39543 9.5 7.5 9.5Z"
+				fill="currentColor"
+				fillRule="evenodd"
+				clipRule="evenodd"
+			/>
+		</svg>
+	)
+}
+
+/** Comment pins are hidden. */
+export function EyeClosedIcon() {
+	return (
+		<svg width="15" height="15" viewBox="0 0 15 15" fill="none" aria-hidden="true">
+			<path
+				d="M14.7649 6.07596C14.9991 6.22231 15.0703 6.53079 14.9239 6.76495C14.4849 7.46743 13.9632 8.10645 13.3702 8.66305L14.5712 9.86406C14.7664 10.0593 14.7664 10.3759 14.5712 10.5712C14.3759 10.7664 14.0593 10.7664 13.8641 10.5712L12.6011 9.30817C11.805 9.90283 10.9089 10.3621 9.93375 10.651L10.383 12.3277C10.4544 12.5944 10.2961 12.8685 10.0294 12.94C9.76267 13.0115 9.4885 12.8532 9.41704 12.5865L8.95917 10.8775C8.48743 10.958 8.00036 11 7.50001 11C6.99965 11 6.51257 10.958 6.04082 10.8775L5.58299 12.5864C5.51153 12.8532 5.23737 13.0115 4.97064 12.94C4.7039 12.8686 4.5456 12.5944 4.61706 12.3277L5.06625 10.651C4.09111 10.3621 3.19503 9.90282 2.39889 9.30815L1.1359 10.5712C0.940638 10.7664 0.624058 10.7664 0.428798 10.5712C0.233537 10.3759 0.233537 10.0593 0.428798 9.86405L1.62982 8.66303C1.03682 8.10643 0.515113 7.46742 0.0760677 6.76495C-0.0702867 6.53079 0.000898544 6.22231 0.235065 6.07596C0.469231 5.9296 0.777703 6.00079 0.924058 6.23496C1.40354 7.00213 1.989 7.68057 2.66233 8.2427C2.67315 8.25096 2.6837 8.25972 2.69397 8.26898C4.00897 9.35527 5.65537 10 7.50001 10C10.3078 10 12.6564 8.5063 14.076 6.23495C14.2223 6.00079 14.5308 5.9296 14.7649 6.07596Z"
+				fill="currentColor"
+				fillRule="evenodd"
+				clipRule="evenodd"
+			/>
+		</svg>
+	)
+}
+
+/** The sidebar's filter menu trigger. */
+export function FilterIcon() {
+	return (
+		<svg width="15" height="15" viewBox="0 0 15 15" fill="none" aria-hidden="true">
+			<path
+				d="M5.5 3C4.67157 3 4 3.67157 4 4.5C4 5.32843 4.67157 6 5.5 6C6.32843 6 7 5.32843 7 4.5C7 3.67157 6.32843 3 5.5 3ZM3 5C3.01671 5 3.03323 4.99918 3.04952 4.99758C3.28022 6.1399 4.28967 7 5.5 7C6.71033 7 7.71978 6.1399 7.95048 4.99758C7.96677 4.99918 7.98329 5 8 5H13.5C13.7761 5 14 4.77614 14 4.5C14 4.22386 13.7761 4 13.5 4H8C7.98329 4 7.96677 4.00082 7.95048 4.00242C7.71978 2.86009 6.71033 2 5.5 2C4.28967 2 3.28022 2.86009 3.04952 4.00242C3.03323 4.00082 3.01671 4 3 4H1.5C1.22386 4 1 4.22386 1 4.5C1 4.77614 1.22386 5 1.5 5H3ZM11.9505 10.9976C11.7198 12.1399 10.7103 13 9.5 13C8.28967 13 7.28022 12.1399 7.04952 10.9976C7.03323 10.9992 7.01671 11 7 11H1.5C1.22386 11 1 10.7761 1 10.5C1 10.2239 1.22386 10 1.5 10H7C7.01671 10 7.03323 10.0008 7.04952 10.0024C7.28022 8.8601 8.28967 8 9.5 8C10.7103 8 11.7198 8.8601 11.9505 10.0024C11.9668 10.0008 11.9833 10 12 10H13.5C13.7761 10 14 10.2239 14 10.5C14 10.7761 13.7761 11 13.5 11H12C11.9833 11 11.9668 10.9992 11.9505 10.9976ZM8 10.5C8 9.67157 8.67157 9 9.5 9C10.3284 9 11 9.67157 11 10.5C11 11.3284 10.3284 12 9.5 12C8.67157 12 8 11.3284 8 10.5Z"
+				fill="currentColor"
+				fillRule="evenodd"
+				clipRule="evenodd"
+			/>
+		</svg>
+	)
+}

package/src/ui/reaction-picker.tsx

@@ -0,0 +1,102 @@
+import { useCallback, useId, type ComponentType } from 'react'
+import {
+	TldrawUiButton,
+	TldrawUiDropdownMenuContent,
+	TldrawUiDropdownMenuRoot,
+	TldrawUiDropdownMenuTrigger,
+	tlmenus,
+	useMaybeEditor,
+	useTranslation,
+} from 'tldraw'
+import { EmojiPicker, type EmojiPickerProps } from './emoji-picker'
+import { SmileyIcon } from './icons'
+import { RenderReaction } from './reaction'
+
+/** @public */
+export interface ReactionPickerProps {
+	/** The emoji to offer. Defaults to `DEFAULT_REACTION_EMOJI`. */
+	emoji?: string[]
+	/** Emoji the current user has already reacted with; shown as pressed in the grid. */
+	selected?: string[]
+	/** Called when an emoji is chosen. */
+	onSelect?(emoji: string): void
+	/** How to draw each emoji token. Defaults to the token string (OS emoji font). */
+	renderReaction?: RenderReaction
+	/**
+	 * What the button opens — the thing that produces a token. Defaults to `EmojiPicker`, the grid of
+	 * emoji. Swap it for any component taking the same props to offer something else entirely (the
+	 * drawn reactions example replaces it with a canvas you draw in); the props are passed straight
+	 * through either way.
+	 */
+	palette?: ComponentType<EmojiPickerProps>
+	/**
+	 * Identifies the menu in tldraw's global menu registry, which keys open/closed state by id.
+	 * A thread renders one picker per comment, so this must differ per comment — sharing an id
+	 * makes every picker in the thread open at once. Defaults to a per-instance generated id;
+	 * pass one only for a stabler, more debuggable value.
+	 */
+	menuId?: string
+	/** Class for the trigger button. Defaults to the card-action style, matching the ⋯ button. */
+	className?: string
+}
+
+/**
+ * The add-reaction affordance: a smiley button that opens an emoji grid.
+ *
+ * Anchored to its own button rather than to the reactions row, so the menu keeps its position as
+ * reactions are added and the row reflows.
+ *
+ * Picking an emoji dismisses the grid — adding and removing alike, since either way the picker has
+ * done its job — and hands focus back to the trigger.
+ * @public @react
+ */
+export function ReactionPicker({
+	emoji,
+	selected,
+	onSelect,
+	renderReaction,
+	palette: Palette = EmojiPicker,
+	menuId,
+	className = 'tlui-cmt-thread__action',
+}: ReactionPickerProps) {
+	const msg = useTranslation()
+	const editor = useMaybeEditor()
+	// Unique per mounted picker unless the host supplies something stabler — see `menuId`.
+	const generatedId = useId()
+	const id = menuId ?? `comment-reactions-${generatedId}`
+
+	// The dropdown's open state lives in tldraw's global menu registry, so dropping the entry is
+	// what closes it. The palette's tokens are plain buttons — a swappable component, not radix
+	// menu items — so nothing dismisses the menu on its own.
+	const handleSelect = useCallback(
+		(value: string) => {
+			onSelect?.(value)
+			tlmenus.deleteOpenMenu(id, editor?.contextId)
+		},
+		[onSelect, id, editor]
+	)
+
+	return (
+		<TldrawUiDropdownMenuRoot id={id}>
+			<TldrawUiDropdownMenuTrigger>
+				<TldrawUiButton
+					type="icon"
+					tooltip={msg('comments.add-reaction')}
+					title={msg('comments.add-reaction')}
+					className={className}
+				>
+					<SmileyIcon />
+				</TldrawUiButton>
+			</TldrawUiDropdownMenuTrigger>
+			{/* left-aligned under the trigger, so the grid opens rightward off the card's edge */}
+			<TldrawUiDropdownMenuContent side="bottom" align="start" alignOffset={0} sideOffset={4}>
+				<Palette
+					emoji={emoji}
+					selected={selected}
+					onSelect={handleSelect}
+					renderReaction={renderReaction}
+				/>
+			</TldrawUiDropdownMenuContent>
+		</TldrawUiDropdownMenuRoot>
+	)
+}

package/src/ui/reaction.tsx

@@ -1,16 +1,135 @@
+import { ComponentType, ReactNode } from 'react'
+import { TldrawUiTooltip, useTranslation } from 'tldraw'
+import { ReactionReactor } from './reactions'
+
+/** Render a reaction token to its visual — the emoji glyph by default. @public */
+export type RenderReaction = (token: string) => ReactNode
+
+/** The default reaction renderer: emits the token string for the OS emoji font to draw. @public */
+export function defaultRenderReaction(token: string): ReactNode {
+	return token
+}
+
 /** @public */
 export interface ReactionProps {
 	emoji: string
 	count: number
 	active: boolean
+	/** How to draw the emoji token. Defaults to the token string (OS emoji font). */
+	renderReaction?: RenderReaction
+	/** Who reacted with this emoji, in reaction order — shown when the pill is hovered. */
+	reactors: ReactionReactor[]
+	/** Whether hovering shows the reactor list. Pass false to suppress it — e.g. while another
+	 *  popup menu on the comment is open. Defaults to true. */
+	enableHoverList?: boolean
+	/** The hover affordance for the pill, naming who reacted. It receives the reactors and the pill
+	 *  itself (as `children`) and returns the whole thing — so it owns the tooltip, its box, size,
+	 *  shape, and position, not just the text inside. Defaults to `DefaultReactionTooltip`, which
+	 *  hangs the built-in inline sentence below the pill. */
+	ReactionTooltip?: ComponentType<ReactionTooltipProps>
+	/** Called when the pill is pressed — toggles the current user's reaction. */
+	onClick?(): void
 }
 
-/** A single emoji reaction pill with a count, highlighted when the user reacted. @public @react */
-export function Reaction({ emoji, count, active }: ReactionProps) {
+/**
+ * A single emoji reaction pill with a count, highlighted when the user reacted. Hovering it shows a
+ * tooltip naming who reacted (the current user included), when `enableHoverList` is set.
+ * @public @react
+ */
+export function Reaction({
+	emoji,
+	count,
+	active,
+	reactors,
+	enableHoverList = true,
+	renderReaction = defaultRenderReaction,
+	ReactionTooltip = DefaultReactionTooltip,
+	onClick,
+}: ReactionProps) {
+	// An inert pill (no handler) is plain content, not a control — rendering it as a span keeps it
+	// valid inside an anchor row (e.g. a notification list item) and out of the tab order.
+	const Tag = onClick ? 'button' : 'span'
+	const pill = (
+		<Tag
+			className={active ? 'tlui-cmt-reaction tlui-cmt-reaction--active' : 'tlui-cmt-reaction'}
+			{...(onClick
+				? { type: 'button' as const, 'aria-pressed': active, onClick }
+				: { role: 'img' as const })}
+			// The emoji alone announces as its unicode name ("thumbs up"); pairing it with the count
+			// is what makes the pill's state legible to a screen reader. The inert span needs the
+			// img role for the label to be announced at all.
+			aria-label={`${emoji} ${count}`}
+		>
+			<span className="tlui-cmt-reaction__emoji">{renderReaction(emoji)}</span>
+			<span className="tlui-cmt-reaction__count">{count}</span>
+		</Tag>
+	)
+
+	// A bare pill when hovering is suppressed, or when there's no one to name.
+	if (!enableHoverList || reactors.length === 0) return pill
+
+	// Hand the whole hover affordance to the tooltip component: it wraps the pill and owns how the
+	// reactor list is presented.
+	return <ReactionTooltip reactors={reactors}>{pill}</ReactionTooltip>
+}
+
+/** @public */
+export interface ReactionTooltipProps {
+	/** Who reacted with this emoji, in reaction order. */
+	reactors: ReactionReactor[]
+	/** The reaction pill to wrap. Anchor the hover affordance to this and render it. */
+	children: ReactNode
+}
+
+/**
+ * The default reactor tooltip: hangs the built-in inline sentence (`DefaultReactionTooltipContent`)
+ * in a standard tooltip below the pill — the same tooltip the toolbar uses. Replace it via
+ * `CommentingComponents.ReactionTooltip` to present the reactor list any other way (a different box,
+ * avatars, a banner, anywhere on screen); it receives the pill as `children`.
+ * @public @react
+ */
+export function DefaultReactionTooltip({ reactors, children }: ReactionTooltipProps) {
 	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>
+		<TldrawUiTooltip side="bottom" content={<DefaultReactionTooltipContent reactors={reactors} />}>
+			{children}
+		</TldrawUiTooltip>
+	)
+}
+
+/**
+ * The default reactor sentence naming who reacted — up to three names spelled out, then "and N
+ * others" (e.g. "You reacted", "You and Bo reacted", "You, Bo and Ada reacted", "You, Bo, Ada and 2
+ * others reacted"). The wording lives in the `comments.reacted-*` translation strings so each locale
+ * controls the grammar. Exported so a custom `ReactionTooltip` can reuse it inside its own box.
+ * @public @react
+ */
+export function DefaultReactionTooltipContent({ reactors }: { reactors: ReactionReactor[] }) {
+	const msg = useTranslation()
+	const names = reactors.map((reactor) =>
+		reactor.you ? msg('comments.mention-you') : reactor.name
 	)
+	const [a, b, c] = names
+	switch (names.length) {
+		case 0:
+			return null
+		case 1:
+			return <>{msg('comments.reacted-1').replace('{a}', a)}</>
+		case 2:
+			return <>{msg('comments.reacted-2').replace('{a}', a).replace('{b}', b)}</>
+		case 3:
+			return <>{msg('comments.reacted-3').replace('{a}', a).replace('{b}', b).replace('{c}', c)}</>
+		default: {
+			const others = names.length - 3
+			const template = others === 1 ? 'comments.reacted-more-one' : 'comments.reacted-more'
+			return (
+				<>
+					{msg(template)
+						.replace('{a}', a)
+						.replace('{b}', b)
+						.replace('{c}', c)
+						.replace('{count}', String(others))}
+				</>
+			)
+		}
+	}
 }