@tldraw/mentions 0.0.0-bootstrap

package/dist-esm/mention-suggestion.mjs.map

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

package/dist-esm/mention.mjs

@@ -0,0 +1,11 @@
+import { jsxs } from "react/jsx-runtime";
+function Mention({ name }) {
+  return /* @__PURE__ */ jsxs("span", { className: "tlui-cmt-mention", children: [
+    "@",
+    name
+  ] });
+}
+export {
+  Mention
+};
+//# sourceMappingURL=mention.mjs.map

package/dist-esm/mention.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/mention.tsx"],
+  "sourcesContent": ["/** @public */\nexport interface MentionProps {\n\tname: string\n}\n\n/** An \\@-mention pill for referencing a person. @public @react */\nexport function Mention({ name }: MentionProps) {\n\treturn <span className=\"tlui-cmt-mention\">@{name}</span>\n}\n"],
+  "mappings": "AAOQ;AADD,SAAS,QAAQ,EAAE,KAAK,GAAiB;AAC/C,SAAO,qBAAC,UAAK,WAAU,oBAAmB;AAAA;AAAA,IAAE;AAAA,KAAK;AAClD;",
+  "names": []
+}

package/mentions.css

@@ -0,0 +1,108 @@
+/* avatar — a person's image, or a single-initial coloured circle. Shared by the mention picker and,
+   via @tldraw/commenting, the comment UI. */
+.tlui-cmt-avatar {
+	width: 28px;
+	height: 28px;
+	border-radius: 50%;
+	background: var(--tl-color-selected);
+	color: #fff;
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	font-size: 11px;
+	font-weight: 600;
+	flex-shrink: 0;
+}
+
+.tlui-cmt-avatar--image {
+	object-fit: cover;
+	background: none;
+}
+
+/* mention pill */
+.tlui-cmt-mention {
+	color: var(--tl-color-selected);
+	font-weight: 600;
+	background: color-mix(in srgb, var(--tl-color-selected) 12%, transparent);
+	padding: 0 4px;
+	border-radius: 4px;
+}
+
+/* mention picker */
+.tlui-cmt-mention-list {
+	display: flex;
+	flex-direction: column;
+	gap: 1px;
+	padding: 4px;
+	width: 100%;
+	box-sizing: border-box;
+	max-height: 260px;
+	overflow-y: auto;
+	color: var(--tl-color-text-1, #1d1d1d);
+	background: var(--tl-color-panel, #fff);
+	border: 1px solid var(--tl-color-divider, rgba(0, 0, 0, 0.08));
+	border-radius: 10px;
+	box-shadow: var(--tl-shadow-2, 0 2px 12px rgba(0, 0, 0, 0.14));
+}
+
+.tlui-cmt-mention-list__item {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	padding: 6px 8px;
+	border: none;
+	background: transparent;
+	border-radius: 6px;
+	cursor: pointer;
+	text-align: left;
+	color: var(--tl-color-text-1);
+	font: inherit;
+}
+
+.tlui-cmt-mention-list__item--active,
+.tlui-cmt-mention-list__item:hover {
+	background: var(--tl-color-muted-2, rgba(0, 0, 0, 0.06));
+}
+
+.tlui-cmt-mention-list__text {
+	display: flex;
+	flex-direction: column;
+	min-width: 0;
+	line-height: 1.3;
+}
+
+.tlui-cmt-mention-list__name {
+	font-size: 13px;
+	font-weight: 500;
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+
+.tlui-cmt-mention-list__you {
+	margin-left: 4px;
+	font-weight: 400;
+	color: var(--tl-color-text-3);
+}
+
+.tlui-cmt-mention-list__secondary {
+	font-size: 12px;
+	color: var(--tl-color-text-3);
+	white-space: nowrap;
+	overflow: hidden;
+	text-overflow: ellipsis;
+}
+
+.tlui-cmt-mention-list--empty {
+	padding: 8px 10px;
+	width: 100%;
+	box-sizing: border-box;
+	color: var(--tl-color-text-3);
+	font-size: 13px;
+}
+
+/* the @-picker popup — anchored under the editor field, positioned by the suggestion plugin */
+.tlui-cmt-mention-popup {
+	position: fixed;
+	z-index: var(--tl-layer-menus);
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@tldraw/mentions",
+  "description": "tldraw @-mention picker and TipTap node, shared by commenting and shape rich text.",
+  "version": "0.0.0-bootstrap",
+  "author": {
+    "name": "tldraw Inc.",
+    "email": "hello@tldraw.com"
+  },
+  "homepage": "https://tldraw.dev",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tldraw/tldraw"
+  },
+  "bugs": {
+    "url": "https://github.com/tldraw/tldraw/issues"
+  },
+  "main": "dist-cjs/index.js",
+  "style": "./mentions.css",
+  "files": [
+    "mentions.css",
+    "dist-esm",
+    "dist-cjs",
+    "src"
+  ],
+  "scripts": {
+    "test-ci": "yarn run -T vitest run --passWithNoTests",
+    "test": "yarn run -T vitest --passWithNoTests",
+    "test-coverage": "yarn run -T vitest run --coverage --passWithNoTests",
+    "build": "yarn run -T tsx ../../internal/scripts/build-package.ts",
+    "build-api": "yarn run -T tsx ../../internal/scripts/build-api.ts",
+    "prepack": "yarn run -T tsx ../../internal/scripts/prepack.ts",
+    "postpack": "../../internal/scripts/postpack.sh",
+    "pack-tarball": "yarn pack",
+    "lint": "yarn run -T tsx ../../internal/scripts/lint.ts"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.1",
+    "react-dom": "^19.2.1"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.2.1",
+    "react-dom": "^18.2.0 || ^19.2.1"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "dependencies": {
+    "@tiptap/core": "^3.12.1",
+    "@tiptap/extension-mention": "3.13.0",
+    "@tiptap/pm": "^3.12.1",
+    "@tiptap/react": "^3.12.1",
+    "@tiptap/suggestion": "3.13.0",
+    "@tldraw/utils": "5.2.5",
+    "tldraw": "5.2.5"
+  },
+  "module": "dist-esm/index.mjs",
+  "source": "src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./dist-esm/index.mjs",
+      "require": "./dist-cjs/index.js"
+    },
+    "./mentions.css": "./mentions.css"
+  }
+}

package/src/avatar.tsx

@@ -0,0 +1,35 @@
+import { getFirstCharacter } from 'tldraw'
+import { CommentAuthor } from './comment-author'
+
+/** @public */
+export interface AvatarProps {
+	author: CommentAuthor
+}
+
+function initial(name: string) {
+	return (getFirstCharacter(name.trim()) || '?').toUpperCase()
+}
+
+/** A person's avatar — their image if provided, otherwise a single-initial coloured circle.
+ * @public @react */
+export function Avatar({ author }: AvatarProps) {
+	if (author.image) {
+		return (
+			<img
+				className="tlui-cmt-avatar tlui-cmt-avatar--image"
+				src={author.image}
+				alt=""
+				aria-hidden="true"
+			/>
+		)
+	}
+	return (
+		<div
+			className="tlui-cmt-avatar"
+			aria-hidden="true"
+			style={author.color ? { backgroundColor: author.color } : undefined}
+		>
+			{initial(author.name)}
+		</div>
+	)
+}

package/src/comment-author.ts

@@ -0,0 +1,15 @@
+import { JsonObject } from 'tldraw'
+
+/** A comment author's display identity, resolved from an author id.
+ * @public */
+export interface CommentAuthor {
+	name: string
+	/** The author's color (any CSS color) — colors their avatar and pins.
+	 *  Omit for the default tint. */
+	color?: string
+	/** Avatar image URL. When set, avatars show the image instead of the colored initial;
+	 *  the canvas pin keeps the initial-on-color. */
+	image?: string
+	/** User-defined metadata for the author, never read by the toolkit (like a shape's `meta`). */
+	meta?: JsonObject
+}

package/src/index.ts

@@ -0,0 +1,25 @@
+import { registerTldrawLibraryVersion } from '@tldraw/utils'
+
+// Presentational mention components. These are tldraw-independent and can be used to build custom
+// mention UI.
+export { Avatar, type AvatarProps } from './avatar'
+export { type CommentAuthor } from './comment-author'
+export { Mention, type MentionProps } from './mention'
+export { MentionList, type MentionListProps, type MentionMember } from './mention-list'
+
+// The TipTap mention node + `@`-picker suggestion. Add the node to a rich-text editor's extensions
+// (comments composer, shape rich text) to render mention pills and — when a suggestion is provided —
+// drive the picker.
+export { createMentionExtension, type MentionExtensionOptions } from './mention-extension'
+export {
+	createMentionSuggestion,
+	filterMentionMembers,
+	isMentionPickerOpen,
+	type MentionSuggestionOptions,
+} from './mention-suggestion'
+
+registerTldrawLibraryVersion(
+	(globalThis as any).TLDRAW_LIBRARY_NAME,
+	(globalThis as any).TLDRAW_LIBRARY_VERSION,
+	(globalThis as any).TLDRAW_LIBRARY_MODULES
+)

package/src/mention-extension.test.ts

@@ -0,0 +1,41 @@
+import { generateHTML } from '@tiptap/core'
+import { getTipTapDefaultExtensions } from 'tldraw'
+import { describe, expect, it } from 'vitest'
+import { createMentionExtension } from './mention-extension'
+
+// The exact render path shape text uses: tldraw's default rich-text extensions plus the mention
+// node, run through TipTap's `generateHTML` (what `renderHtmlFromRichText` does under the hood).
+const render = (body: any, resolveName?: (id: string) => string | undefined) =>
+	generateHTML(body, [...getTipTapDefaultExtensions(), createMentionExtension({ resolveName })])
+
+const doc = (...content: any[]) => ({ type: 'doc', content }) as any
+const para = (...content: any[]) => ({ type: 'paragraph', content })
+const text = (value: string) => ({ type: 'text', text: value })
+const mention = (id: string, label?: string) => ({ type: 'mention', attrs: { id, label } })
+
+describe('createMentionExtension', () => {
+	it('renders a mention node as a pill carrying its member id', () => {
+		const html = render(doc(para(text('hi '), mention('ada', 'Ada'))))
+		expect(html).toContain('tlui-cmt-mention')
+		expect(html).toContain('data-mention-id="ada"')
+	})
+
+	it('resolves the id to the current name, not the label frozen at insert time', () => {
+		const html = render(doc(para(mention('ada', 'Ada'))), (id) =>
+			id === 'ada' ? 'Ada Lovelace' : undefined
+		)
+		expect(html).toContain('@Ada Lovelace')
+		expect(html).not.toContain('@Ada<')
+	})
+
+	it('falls back to the stored label when the id can not be resolved', () => {
+		const html = render(doc(para(mention('ghost', 'Ada'))), () => undefined)
+		expect(html).toContain('@Ada')
+	})
+
+	it('escapes a resolved name so it can never inject markup', () => {
+		const html = render(doc(para(mention('ada'))), () => '<img src=x onerror=alert(1)>')
+		expect(html).not.toContain('<img')
+		expect(html).toContain('&lt;img')
+	})
+})

package/src/mention-extension.ts

@@ -0,0 +1,51 @@
+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 ?? ''
+}
+
+/** @public */
+export interface MentionExtensionOptions {
+	/**
+	 * Resolve a member id to its current display name — for the read-only render paths, and for the
+	 * editor while a mention is displayed. 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 editing (omit on read-only render paths). */
+	suggestion?: MentionOptions['suggestion']
+}
+
+/**
+ * The \@-mention node — TipTap's `Mention` configured to render as a `.tlui-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 an editor passes a `suggestion` (the `@`
+ * picker). Shape rich text passes both — the same extension both edits and renders. The node schema
+ * is identical either way — only these two levers differ.
+ * @public
+ */
+export function createMentionExtension({ resolveName, suggestion }: MentionExtensionOptions = {}) {
+	return Mention.configure({
+		HTMLAttributes: { class: 'tlui-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/mention-list.tsx

@@ -0,0 +1,103 @@
+import { ReactNode } from 'react'
+import { useTranslation } from 'tldraw'
+import { Avatar } from './avatar'
+import { CommentAuthor } from './comment-author'
+
+/** A person the composer's \@-mention picker can offer: a {@link CommentAuthor} plus its id and
+ * picker-only display fields. @public */
+export interface MentionMember extends CommentAuthor {
+	id: 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 author={member} />
+			<span className="tlui-cmt-mention-list__text">
+				<span className="tlui-cmt-mention-list__name">
+					{member.name}
+					{member.you && (
+						<span className="tlui-cmt-mention-list__you">{`(${msg('comments.mention-you')})`}</span>
+					)}
+				</span>
+				{member.secondary && (
+					<span className="tlui-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="tlui-cmt-mention-list tlui-cmt-mention-list--empty">
+				{emptyLabel ?? msg('comments.mention-no-matches')}
+			</div>
+		)
+	}
+	return (
+		<div className="tlui-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
+								? 'tlui-cmt-mention-list__item tlui-cmt-mention-list__item--active'
+								: 'tlui-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/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([])
+	})
+})