testomatio-editor-blocks 0.4.77 → 0.4.79

package/package/editor/useMentionAutocomplete.js

@@ -0,0 +1,312 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/* eslint-disable react-refresh/only-export-components -- the hook colocates
+   with its private popup component; they are one cohesive module. */
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { applyMention, buildMentionInsertText, filterMentionItems, getMentionSources, normalizeMentionItems, parseActiveMention, } from "./mentionAutocomplete";
+const NAV_KEYS = new Set(["ArrowDown", "ArrowUp", "Enter", "Tab", "Escape"]);
+export function useMentionAutocomplete(options) {
+    const { textarea, sources: sourcesProp, enabled = true, attachKeyDown = true, searchDebounceMs = 150, } = options;
+    const getText = useCallback(() => { var _a; return (options.getText ? options.getText() : (_a = textarea === null || textarea === void 0 ? void 0 : textarea.value) !== null && _a !== void 0 ? _a : ""); }, [options, textarea]);
+    const setText = useCallback((text, caret) => {
+        if (options.setText) {
+            options.setText(text, caret);
+            return;
+        }
+        if (!textarea)
+            return;
+        textarea.value = text;
+        textarea.setSelectionRange(caret, caret);
+        textarea.dispatchEvent(new Event("input", { bubbles: true }));
+    }, [options, textarea]);
+    const [active, setActive] = useState(null);
+    const [items, setItems] = useState([]);
+    const [activeIndex, setActiveIndex] = useState(0);
+    const [loading, setLoading] = useState(false);
+    const [caretRect, setCaretRect] = useState(null);
+    // Latest committed active mention, for cheap change-detection in refresh().
+    const activeRef = useRef(null);
+    // Cache resolved static item lists per source so provider functions run once.
+    const staticCacheRef = useRef(new WeakMap());
+    // Cache async search results per `${prefix}::${query}`.
+    const searchCacheRef = useRef(new Map());
+    const sources = sourcesProp !== null && sourcesProp !== void 0 ? sourcesProp : getMentionSources();
+    const isOpen = enabled && active !== null;
+    const close = useCallback(() => {
+        activeRef.current = null;
+        setActive(null);
+        setItems([]);
+        setActiveIndex(0);
+        setLoading(false);
+    }, []);
+    /** Re-read the caret and (re)detect the active mention, ignoring no-op changes. */
+    const refresh = useCallback(() => {
+        var _a;
+        let next = null;
+        if (enabled && textarea && textarea.selectionStart === textarea.selectionEnd) {
+            next = parseActiveMention(getText(), (_a = textarea.selectionStart) !== null && _a !== void 0 ? _a : 0, sources);
+        }
+        const prev = activeRef.current;
+        const unchanged = (!next && !prev) ||
+            (!!next &&
+                !!prev &&
+                next.source === prev.source &&
+                next.token === prev.token &&
+                next.start === prev.start &&
+                next.end === prev.end);
+        if (unchanged)
+            return;
+        activeRef.current = next;
+        setActive(next);
+        if (next && textarea) {
+            setCaretRect(caretCoordinates(textarea, next.start));
+        }
+    }, [enabled, textarea, getText, sources]);
+    // Track input + caret movement.
+    useEffect(() => {
+        if (!textarea || !enabled)
+            return;
+        const onInput = () => refresh();
+        const onSelectionChange = () => {
+            if (document.activeElement === textarea)
+                refresh();
+        };
+        const onBlur = () => close();
+        textarea.addEventListener("input", onInput);
+        textarea.addEventListener("blur", onBlur);
+        document.addEventListener("selectionchange", onSelectionChange);
+        return () => {
+            textarea.removeEventListener("input", onInput);
+            textarea.removeEventListener("blur", onBlur);
+            document.removeEventListener("selectionchange", onSelectionChange);
+        };
+    }, [textarea, enabled, refresh, close]);
+    // Resolve items for the active mention (static filter or async search).
+    useEffect(() => {
+        var _a, _b;
+        if (!active)
+            return;
+        const { source, query } = active;
+        setActiveIndex(0);
+        const limit = (_a = source.limit) !== null && _a !== void 0 ? _a : 8;
+        // Async, server-backed source.
+        if (typeof source.search === "function") {
+            const minChars = (_b = source.minChars) !== null && _b !== void 0 ? _b : 0;
+            if (query.length < minChars) {
+                setItems([]);
+                setLoading(false);
+                return;
+            }
+            const key = `${source.prefix}::${query}`;
+            const cached = searchCacheRef.current.get(key);
+            if (cached) {
+                setItems(cached);
+                setLoading(false);
+                return;
+            }
+            let cancelled = false;
+            setLoading(true);
+            const timer = setTimeout(() => {
+                Promise.resolve(source.search(query))
+                    .then((result) => normalizeMentionItems(result).slice(0, limit))
+                    .then((resolved) => {
+                    searchCacheRef.current.set(key, resolved);
+                    if (!cancelled) {
+                        setItems(resolved);
+                        setLoading(false);
+                    }
+                })
+                    .catch((error) => {
+                    console.error("Mention search failed", error);
+                    if (!cancelled) {
+                        setItems([]);
+                        setLoading(false);
+                    }
+                });
+            }, searchDebounceMs);
+            return () => {
+                cancelled = true;
+                clearTimeout(timer);
+            };
+        }
+        // Static, in-memory source.
+        const resolveStatic = () => {
+            const cached = staticCacheRef.current.get(source);
+            if (cached)
+                return Promise.resolve(cached);
+            const input = source.items;
+            const raw = typeof input === "function" ? input() : input !== null && input !== void 0 ? input : [];
+            return Promise.resolve(raw).then((list) => {
+                const normalized = normalizeMentionItems(list);
+                staticCacheRef.current.set(source, normalized);
+                return normalized;
+            });
+        };
+        let cancelled = false;
+        resolveStatic().then((list) => {
+            if (!cancelled)
+                setItems(filterMentionItems(list, query, limit));
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [active, searchDebounceMs]);
+    const apply = useCallback((item) => {
+        if (!active)
+            return;
+        const insertText = buildMentionInsertText(active.source, item);
+        const result = applyMention(getText(), active, insertText);
+        close();
+        setText(result.text, result.caret);
+        // Return focus to the textarea after the value write settles.
+        requestAnimationFrame(() => {
+            textarea === null || textarea === void 0 ? void 0 : textarea.focus();
+            textarea === null || textarea === void 0 ? void 0 : textarea.setSelectionRange(result.caret, result.caret);
+        });
+    }, [active, getText, setText, close, textarea]);
+    const onKeyDown = useCallback((event) => {
+        var _a;
+        if (!isOpen || !NAV_KEYS.has(event.key))
+            return false;
+        if (event.key === "Escape") {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            close();
+            return true;
+        }
+        if (items.length === 0) {
+            // Swallow nav keys while open with no results only for Escape (handled).
+            // Let other keys through so typing/navigation still works.
+            return false;
+        }
+        if (event.key === "ArrowDown") {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            setActiveIndex((prev) => (prev + 1 >= items.length ? 0 : prev + 1));
+            return true;
+        }
+        if (event.key === "ArrowUp") {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            setActiveIndex((prev) => (prev - 1 < 0 ? items.length - 1 : prev - 1));
+            return true;
+        }
+        if (event.key === "Enter" || event.key === "Tab") {
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            apply((_a = items[activeIndex]) !== null && _a !== void 0 ? _a : items[0]);
+            return true;
+        }
+        return false;
+    }, [isOpen, items, activeIndex, apply, close]);
+    // Keep a fresh handler for the (optional) self-attached listener.
+    const handlerRef = useRef(onKeyDown);
+    handlerRef.current = onKeyDown;
+    useEffect(() => {
+        if (!textarea || !attachKeyDown || !enabled)
+            return;
+        const listener = (event) => {
+            handlerRef.current(event);
+        };
+        const opts = { capture: true };
+        textarea.addEventListener("keydown", listener, opts);
+        return () => textarea.removeEventListener("keydown", listener, opts);
+    }, [textarea, attachKeyDown, enabled]);
+    const overlay = isOpen ? (_jsx(MentionPopup, { active: active, items: items, activeIndex: activeIndex, loading: loading, caretRect: caretRect, onHover: setActiveIndex, onSelect: apply })) : null;
+    return { overlay, onKeyDown, isOpen, close };
+}
+function MentionPopup({ active, items, activeIndex, loading, caretRect, onHover, onSelect, }) {
+    var _a;
+    const listRef = useRef(null);
+    // Keep the highlighted item scrolled into view.
+    useLayoutEffect(() => {
+        var _a;
+        const el = (_a = listRef.current) === null || _a === void 0 ? void 0 : _a.querySelector('[data-active="true"]');
+        el === null || el === void 0 ? void 0 : el.scrollIntoView({ block: "nearest" });
+    }, [activeIndex, items]);
+    if (typeof document === "undefined")
+        return null;
+    const style = caretRect
+        ? { position: "fixed", left: caretRect.left, top: caretRect.bottom + 4 }
+        : { position: "fixed", left: 16, top: 16 };
+    const source = active.source;
+    const minChars = (_a = source.minChars) !== null && _a !== void 0 ? _a : 0;
+    const belowMin = typeof source.search === "function" && active.query.length < minChars;
+    return createPortal(_jsxs("div", { className: "bn-mention-popup", role: "listbox", style: style, ref: listRef, children: [source.label && (_jsxs("div", { className: "bn-mention-popup__header", children: [_jsxs("span", { className: "bn-mention-popup__prefix", children: ["@", source.prefix] }), _jsx("span", { className: "bn-mention-popup__label", children: source.label })] })), belowMin ? (_jsx("div", { className: "bn-mention-popup__status", children: "Keep typing to search\u2026" })) : loading ? (_jsx("div", { className: "bn-mention-popup__status", children: "Searching\u2026" })) : items.length === 0 ? (_jsx("div", { className: "bn-mention-popup__status", children: "No matches" })) : (items.map((item, index) => (_jsxs("button", { type: "button", role: "option", "data-active": index === activeIndex, "aria-selected": index === activeIndex, className: index === activeIndex
+                    ? "bn-mention-item bn-mention-item--active"
+                    : "bn-mention-item", 
+                // onMouseDown (not onClick) + preventDefault keeps the textarea focused.
+                onMouseDown: (event) => {
+                    event.preventDefault();
+                    onSelect(item);
+                }, onMouseEnter: () => onHover(index), tabIndex: -1, children: [_jsx("span", { className: "bn-mention-item__label", children: item.label }), item.detail && _jsx("span", { className: "bn-mention-item__detail", children: item.detail })] }, item.id))))] }), document.body);
+}
+/* ------------------------------------------------------------------ *
+ * Caret coordinates via the mirror-div technique. Works for any plain
+ * <textarea>; returns viewport (fixed) coordinates of the given index.
+ * ------------------------------------------------------------------ */
+const MIRROR_PROPS = [
+    "boxSizing",
+    "width",
+    "borderTopWidth",
+    "borderRightWidth",
+    "borderBottomWidth",
+    "borderLeftWidth",
+    "paddingTop",
+    "paddingRight",
+    "paddingBottom",
+    "paddingLeft",
+    "fontStyle",
+    "fontVariant",
+    "fontWeight",
+    "fontStretch",
+    "fontSize",
+    "fontSizeAdjust",
+    "lineHeight",
+    "fontFamily",
+    "textAlign",
+    "textTransform",
+    "textIndent",
+    "textDecoration",
+    "letterSpacing",
+    "wordSpacing",
+    "tabSize",
+    "whiteSpace",
+    "wordWrap",
+    "wordBreak",
+];
+function caretCoordinates(textarea, position) {
+    const rect = textarea.getBoundingClientRect();
+    const fallback = {
+        left: rect.left,
+        top: rect.top,
+        bottom: rect.bottom,
+        height: rect.height,
+    };
+    if (typeof document === "undefined")
+        return fallback;
+    const style = window.getComputedStyle(textarea);
+    const mirror = document.createElement("div");
+    const cs = mirror.style;
+    cs.position = "absolute";
+    cs.visibility = "hidden";
+    cs.whiteSpace = "pre-wrap";
+    cs.overflow = "hidden";
+    const sourceStyle = style;
+    const mirrorStyle = cs;
+    for (const prop of MIRROR_PROPS) {
+        mirrorStyle[prop] = sourceStyle[prop];
+    }
+    cs.width = `${textarea.clientWidth}px`;
+    const value = textarea.value;
+    mirror.textContent = value.slice(0, position);
+    const marker = document.createElement("span");
+    marker.textContent = value.slice(position) || ".";
+    mirror.appendChild(marker);
+    document.body.appendChild(mirror);
+    const lineHeight = parseFloat(style.lineHeight) || parseFloat(style.fontSize) * 1.2;
+    const left = rect.left + marker.offsetLeft - textarea.scrollLeft;
+    const top = rect.top + marker.offsetTop - textarea.scrollTop;
+    document.body.removeChild(mirror);
+    return { left, top, bottom: top + lineHeight, height: lineHeight };
+}

package/package/index.d.ts

@@ -8,6 +8,9 @@ export { tagBadgeExtension, TagBadgeExtension, TAGS_DETECT_REGEXP, detectTags, t
 export { blocksToMarkdown, markdownToBlocks, type CustomEditorBlock, type CustomPartialBlock, type MarkdownToBlocksOptions, } from "./editor/customMarkdownConverter";
 export { useStepAutocomplete, parseStepsFromJsonApi, setStepsFetcher, type StepSuggestion, type StepJsonApiDocument, type StepJsonApiResource, } from "./editor/stepAutocomplete";
 export { useStepImageUpload, setImageUploadHandler, type StepImageUploadHandler, } from "./editor/stepImageUpload";
+export { setMentionSources, getMentionSources, parseActiveMention, resolveMentionSource, buildMentionInsertText, applyMention, filterMentionItems, resolveMentionQuery, normalizeMentionItems, parseMentionsFromJsonApi, type MentionSource, type MentionItem, type MentionItemsInput, type MentionSearchResult, type ActiveMention, type MentionJsonApiDocument, type MentionJsonApiResource, } from "./editor/mentionAutocomplete";
+export { MentionMenu, type MentionMenuProps, } from "./editor/MentionMenu";
+export { useMentionAutocomplete, type UseMentionAutocompleteOptions, type UseMentionAutocompleteResult, } from "./editor/useMentionAutocomplete";
 export { setFileDisplayUrlResolver, resolveFileDisplayUrl, type FileDisplayUrlResolver, } from "./editor/fileDisplayUrl";
 export { createMarkdownPasteHandler } from "./editor/createMarkdownPasteHandler";
 export declare const testomatioEditorClassName = "markdown testomatio-editor";

package/package/index.js

@@ -8,6 +8,9 @@ export { tagBadgeExtension, TagBadgeExtension, TAGS_DETECT_REGEXP, detectTags, }
 export { blocksToMarkdown, markdownToBlocks, } from "./editor/customMarkdownConverter";
 export { useStepAutocomplete, parseStepsFromJsonApi, setStepsFetcher, } from "./editor/stepAutocomplete";
 export { useStepImageUpload, setImageUploadHandler, } from "./editor/stepImageUpload";
+export { setMentionSources, getMentionSources, parseActiveMention, resolveMentionSource, buildMentionInsertText, applyMention, filterMentionItems, resolveMentionQuery, normalizeMentionItems, parseMentionsFromJsonApi, } from "./editor/mentionAutocomplete";
+export { MentionMenu, } from "./editor/MentionMenu";
+export { useMentionAutocomplete, } from "./editor/useMentionAutocomplete";
 export { setFileDisplayUrlResolver, resolveFileDisplayUrl, } from "./editor/fileDisplayUrl";
 export { createMarkdownPasteHandler } from "./editor/createMarkdownPasteHandler";
 export const testomatioEditorClassName = "markdown testomatio-editor";

package/package/styles.css

@@ -1844,6 +1844,81 @@ html.dark .bn-step-editor--preview a.step-preview-link {
   color: var(--step-muted);
 }
 
+/* Universal @-mention autocomplete popup (portaled to <body>, fixed to caret). */
+.bn-mention-popup {
+  position: fixed;
+  min-width: 15rem;
+  max-width: 24rem;
+  background: var(--bg-white-opaque);
+  border-radius: 0.65rem;
+  border: 1px solid var(--step-border-light);
+  box-shadow: 0 18px 35px var(--shadow-medium);
+  padding: 0.25rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.1rem;
+  z-index: 9999;
+  max-height: 15rem;
+  overflow-y: auto;
+}
+
+.bn-mention-popup__header {
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+  padding: 0.3rem 0.6rem 0.35rem;
+  font-size: 0.72rem;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+  color: var(--step-muted);
+}
+
+.bn-mention-popup__prefix {
+  font-weight: 700;
+  color: var(--text-primary);
+}
+
+.bn-mention-popup__status {
+  padding: 0.5rem 0.75rem;
+  font-size: 0.85rem;
+  color: var(--step-muted);
+}
+
+.bn-mention-item {
+  border: none;
+  background: transparent;
+  border-radius: 0.5rem;
+  padding: 0.4rem 0.75rem;
+  text-align: left;
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+  gap: 0.75rem;
+  cursor: pointer;
+  color: var(--text-primary);
+  width: 100%;
+}
+
+.bn-mention-item:hover,
+.bn-mention-item--active {
+  background: var(--step-bg-light);
+}
+
+.bn-mention-item__label {
+  font-size: 0.92rem;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.bn-mention-item__detail {
+  font-size: 0.75rem;
+  font-weight: 500;
+  color: var(--step-muted);
+  white-space: nowrap;
+  flex-shrink: 0;
+}
+
 .bn-inline-image {
   display: block;
   max-width: 100%;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "testomatio-editor-blocks",
-  "version": "0.4.77",
+  "version": "0.4.79",
   "description": "Custom BlockNote schema, markdown conversion helpers, and UI for Testomatio-style test cases and steps.",
   "type": "module",
   "main": "./package/index.js",

package/src/App.tsx

@@ -23,6 +23,13 @@ import { customSchema, type CustomEditor } from "./editor/customSchema";
 import { tagBadgeExtension } from "./editor/tagBadge";
 import { setStepsFetcher, type StepJsonApiDocument } from "./editor/stepAutocomplete";
 import { setSnippetFetcher, type SnippetJsonApiDocument } from "./editor/snippetAutocomplete";
+import {
+  setMentionSources,
+  type MentionItem,
+  type MentionSearchResult,
+  type MentionSource,
+} from "./editor/mentionAutocomplete";
+import { MentionMenu } from "./editor/MentionMenu";
 import { setImageUploadHandler } from "./editor/stepImageUpload";
 import { canInsertStepOrSnippet, addStepsBlock, addSnippetBlock } from "./editor/blocks/step";
 import { addTestBlock } from "./editor/blocks/testMeta";
@@ -287,6 +294,73 @@ const DEMO_SNIPPET_FIXTURES: SnippetJsonApiDocument = {
   ],
 };
 
+const DEMO_USERS: MentionItem[] = [
+  { id: "u-davert", label: "davert", detail: "Michael Bodnarchuk" },
+  { id: "u-anna", label: "anna", detail: "Anna QA" },
+  { id: "u-taras", label: "taras", detail: "Taras Manager" },
+  { id: "u-siren", label: "siern", detail: "Sirena QA" },
+  { id: "u-bob", label: "bob", detail: "Bob Tester" },
+  { id: "u-carol", label: "carol", detail: "Carol Dev" },
+  { id: "u-dan", label: "dan", detail: "Dan Ops" },
+  { id: "u-eve", label: "eve", detail: "Eve Security" },
+];
+
+// Simulated "tests" API dataset — insertion uses the numeric id -> "@T{id}".
+const DEMO_TESTS: MentionItem[] = [
+  { id: "10231", label: "Login redirects to dashboard", detail: "#10231" },
+  { id: "10232", label: "Login rejects wrong password", detail: "#10232" },
+  { id: "10245", label: "Logout clears the session", detail: "#10245" },
+  { id: "10310", label: "Checkout applies discount code", detail: "#10310" },
+  { id: "10311", label: "Checkout blocks empty cart", detail: "#10311" },
+  { id: "10420", label: "Profile avatar upload", detail: "#10420" },
+  { id: "10421", label: "Profile email change requires confirm", detail: "#10421" },
+  { id: "10530", label: "Password reset sends email", detail: "#10530" },
+];
+
+const DEMO_SUITES: MentionItem[] = [
+  { id: "1001", label: "Authentication", detail: "#1001" },
+  { id: "1002", label: "Checkout flow", detail: "#1002" },
+  { id: "1003", label: "User profile", detail: "#1003" },
+  { id: "1004", label: "Notifications", detail: "#1004" },
+  { id: "1005", label: "Admin panel", detail: "#1005" },
+];
+
+const demoDelay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Demo @-mention config. Prefixes are fully data-driven: @T / @S hit a
+ * (simulated) API and insert an id token, while a bare @ filters the in-memory
+ * user list and inserts the handle.
+ */
+const DEMO_MENTION_SOURCES: MentionSource[] = [
+  {
+    prefix: "T",
+    label: "Tests",
+    search: async (query): Promise<MentionSearchResult> => {
+      await demoDelay(120); // simulate an API round-trip
+      const q = query.toLowerCase();
+      return DEMO_TESTS.filter((test) => test.label.toLowerCase().includes(q));
+    },
+    // default insert -> "@T{id}", e.g. "@T10231"
+  },
+  {
+    prefix: "S",
+    label: "Suites",
+    search: async (query): Promise<MentionSearchResult> => {
+      await demoDelay(120);
+      const q = query.toLowerCase();
+      return DEMO_SUITES.filter((suite) => suite.label.toLowerCase().includes(q));
+    },
+    // default insert -> "@S{id}", e.g. "@S1001"
+  },
+  {
+    prefix: "",
+    label: "Users",
+    items: DEMO_USERS,
+    insert: (item) => `@${item.label}`, // insert -> "@davert"
+  },
+];
+
 function CustomSlashMenu() {
   const editor = useBlockNoteEditor<Schema["blockSchema"], Schema["inlineContentSchema"], Schema["styleSchema"]>();
 
@@ -512,6 +586,7 @@ function App() {
     // Demo defaults: configure global handlers so the editor works without manual providers.
     setStepsFetcher(() => DEMO_STEP_FIXTURES);
     setSnippetFetcher(() => DEMO_SNIPPET_FIXTURES);
+    setMentionSources(DEMO_MENTION_SOURCES);
 
     const handler = editor?.uploadFile
       ? async (file: Blob) => {
@@ -538,6 +613,7 @@ function App() {
       setStepsFetcher(null);
       setSnippetFetcher(null);
       setImageUploadHandler(null);
+      setMentionSources(null);
     };
   }, [editor, uploadStepImage]);
 
@@ -675,6 +751,7 @@ function App() {
             className="markdown testomatio-editor"
           >
             <CustomSlashMenu />
+            <MentionMenu />
           </BlockNoteView>
         </div>
         <aside className="app__preview">

package/src/editor/MentionMenu.tsx

@@ -0,0 +1,46 @@
+import { SuggestionMenuController, useBlockNoteEditor } from "@blocknote/react";
+import type { DefaultReactSuggestionItem } from "@blocknote/react";
+import {
+  buildMentionInsertText,
+  getMentionSources,
+  resolveMentionQuery,
+  type MentionSource,
+} from "./mentionAutocomplete";
+
+export type MentionMenuProps = {
+  /** Sources to use. Falls back to the global registry (`setMentionSources`). */
+  sources?: MentionSource[];
+  /** Character that opens the menu. Default `@`. */
+  triggerCharacter?: string;
+};
+
+/**
+ * Universal `@`-mention menu for the main BlockNote editor. Render it as a child
+ * of `<BlockNoteView>`. On selection it inserts the source's token (e.g.
+ * `@T123456`, `@S98765`, `@username`) as inline text at the cursor.
+ *
+ *   <BlockNoteView editor={editor}>
+ *     <MentionMenu />
+ *   </BlockNoteView>
+ */
+export function MentionMenu({ sources: sourcesProp, triggerCharacter = "@" }: MentionMenuProps) {
+  const editor = useBlockNoteEditor();
+
+  const getItems = async (query: string): Promise<DefaultReactSuggestionItem[]> => {
+    const sources = sourcesProp ?? getMentionSources();
+    const resolved = await resolveMentionQuery(query, sources);
+    if (!resolved) return [];
+    const { source, items } = resolved;
+    return items.map((item) => ({
+      title: item.label,
+      subtext: item.detail ?? undefined,
+      onItemClick: () => {
+        // The controller has already removed the trigger + query text; we insert
+        // the token plus a trailing space so the caret is ready for more typing.
+        editor.insertInlineContent([buildMentionInsertText(source, item), " "]);
+      },
+    }));
+  };
+
+  return <SuggestionMenuController triggerCharacter={triggerCharacter} getItems={getItems} />;
+}