testomatio-editor-blocks 0.4.76 → 0.4.78

package/package/editor/MentionAutocomplete.d.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from "react";
+import { type MentionSource } from "./mentionAutocomplete";
+export type UseMentionAutocompleteOptions = {
+    /** The textarea the mentions are typed into (e.g. an OverType instance's textarea). */
+    textarea: HTMLTextAreaElement | null;
+    /** Reads the current full text. Defaults to `textarea.value`. */
+    getText?: () => string;
+    /**
+     * Writes the full text back and positions the caret. Defaults to mutating
+     * `textarea.value` directly; pass a custom writer when a wrapper (OverType,
+     * a controlled component) owns the value.
+     */
+    setText?: (text: string, caret: number) => void;
+    /** Sources to use. Falls back to the global registry (`setMentionSources`). */
+    sources?: MentionSource[];
+    /** Master switch; when false the popup never opens. Default true. */
+    enabled?: boolean;
+    /**
+     * When true (default) the hook attaches its own capture-phase keydown listener
+     * to the textarea. Set false to drive navigation yourself via the returned
+     * `onKeyDown` (useful when another handler must take priority ordering).
+     */
+    attachKeyDown?: boolean;
+    /** Debounce (ms) before an async `search` runs. Default 150. */
+    searchDebounceMs?: number;
+};
+export type UseMentionAutocompleteResult = {
+    /** Render this somewhere in the tree; it portals the popup to `document.body`. */
+    overlay: ReactNode;
+    /**
+     * Feed keydown events here when `attachKeyDown` is false. Returns true when the
+     * event was consumed (it also calls preventDefault / stopImmediatePropagation).
+     */
+    onKeyDown: (event: KeyboardEvent) => boolean;
+    isOpen: boolean;
+    close: () => void;
+};
+export declare function useMentionAutocomplete(options: UseMentionAutocompleteOptions): UseMentionAutocompleteResult;

package/package/editor/MentionAutocomplete.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/editor/MentionMenu.d.ts

@@ -0,0 +1,17 @@
+import { 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 declare function MentionMenu({ sources: sourcesProp, triggerCharacter }: MentionMenuProps): import("react/jsx-runtime").JSX.Element;

package/package/editor/MentionMenu.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SuggestionMenuController, useBlockNoteEditor } from "@blocknote/react";
+import { buildMentionInsertText, getMentionSources, resolveMentionQuery, } from "./mentionAutocomplete";
+/**
+ * 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 = "@" }) {
+    const editor = useBlockNoteEditor();
+    const getItems = async (query) => {
+        const sources = sourcesProp !== null && sourcesProp !== void 0 ? sourcesProp : getMentionSources();
+        const resolved = await resolveMentionQuery(query, sources);
+        if (!resolved)
+            return [];
+        const { source, items } = resolved;
+        return items.map((item) => {
+            var _a;
+            return ({
+                title: item.label,
+                subtext: (_a = item.detail) !== null && _a !== void 0 ? _a : 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 _jsx(SuggestionMenuController, { triggerCharacter: triggerCharacter, getItems: getItems });
+}

package/package/editor/customMarkdownConverter.js

@@ -379,7 +379,20 @@ function serializeBlock(block, ctx, orderedIndex, stepIndex) {
                 return lines;
             }
             lines.push(`<!-- ${kind}`);
-            fields.forEach((field) => lines.push(`${field.key}: ${field.value}`));
+            fields.forEach((field) => {
+                // List-valued keys (e.g. `issues`) are written back as a YAML list to
+                // preserve the backend's format. The single panel field holds the items
+                // comma-separated, so split them back out into `  - item` lines.
+                if (LIST_META_KEYS.has(field.key.trim().toLowerCase())) {
+                    const items = field.value.split(",").map((s) => s.trim()).filter(Boolean);
+                    if (items.length) {
+                        lines.push(`${field.key}:`);
+                        items.forEach((item) => lines.push(`  - ${item}`));
+                        return;
+                    }
+                }
+                lines.push(`${field.key}: ${field.value}`);
+            });
             lines.push("-->");
             return lines;
         }
@@ -1210,12 +1223,26 @@ function parseParagraph(lines, index) {
     };
 }
 const META_COMMENT_OPEN_REGEX = /^<!--\s*(test|suite)(?=\s|-->|$)/i;
+// Keys whose value is a YAML-style list (`key:` followed by indented `- item`
+// lines) in the testomat.io comment format — e.g. `issues` holding URLs. These
+// round-trip back to a list on serialize; everything else stays a flat line.
+const LIST_META_KEYS = new Set(["issues"]);
 function metaFieldsFromBody(bodyLines) {
     const fields = [];
     for (const raw of bodyLines) {
         const line = raw.trim();
         if (!line)
             continue;
+        // YAML list item: belongs to the most recent `key:` field. The whole item
+        // (e.g. `https://github.com/...`) is kept verbatim — because we catch the
+        // list line before the colon check, URLs with `://` are never split.
+        if (line === "-" || line.startsWith("- ")) {
+            const item = line.slice(1).trim();
+            const current = fields[fields.length - 1];
+            if (current && item)
+                current.items.push(item);
+            continue;
+        }
         const colon = line.indexOf(":");
         // "Each line is `key: value`; lines without `:` are ignored."
         if (colon === -1)
@@ -1224,9 +1251,13 @@ function metaFieldsFromBody(bodyLines) {
         const value = line.slice(colon + 1).trim();
         if (!key)
             continue;
-        fields.push({ key, value });
+        fields.push({ key, value, items: [] });
     }
-    return fields;
+    // A field with collected list items → value is the items joined by ", ".
+    return fields.map(({ key, value, items }) => ({
+        key,
+        value: items.length ? items.join(", ") : value,
+    }));
 }
 function parseMetaComment(lines, index) {
     const first = lines[index];

package/package/editor/mentionAutocomplete.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Universal, prefix-based `@`-mention autocomplete.
+ *
+ * A single mechanism that turns typed tokens like `@`, `@T`, `@S` into inserted
+ * references such as `@T123456`, `@S98765`, or `@username`. Which list is shown
+ * (and what gets inserted) is decided by a configurable set of {@link MentionSource}s,
+ * each keyed by the characters that follow the `@`:
+ *
+ *   { prefix: "T", search: (q) => api.findTests(q) }        // @T -> fetch tests -> "@T123456"
+ *   { prefix: "S", search: (q) => api.findSuites(q) }       // @S -> fetch suites -> "@S98765"
+ *   { prefix: "",  items: users, insert: (u) => `@${u.label}` } // @  -> filter users -> "@john"
+ *
+ * This file is intentionally DOM-free: it holds only the pure logic (matching,
+ * source resolution, filtering, token building) plus the global source registry.
+ * The React wiring lives in `MentionAutocomplete.tsx`.
+ */
+export type MentionItem = {
+    /** Stable identifier. For test/suite sources this is what gets inserted (`@T{id}`). */
+    id: string;
+    /** Primary text shown in the popup and used for client-side filtering. */
+    label: string;
+    /** Optional secondary text (e.g. `#123`, an email, a description). */
+    detail?: string | null;
+    /**
+     * Optional explicit text to insert for this specific item. When omitted the
+     * source's `insert` builder (or the default `@{prefix}{id}`) is used.
+     */
+    insertText?: string;
+    /** Sources may carry arbitrary extra data through to their renderers. */
+    [key: string]: unknown;
+};
+/** Static item list, or a (possibly async) provider of one. */
+export type MentionItemsInput = MentionItem[] | (() => MentionItem[] | Promise<MentionItem[]>);
+/** Result of an async `search`. May be raw items or a JSON:API document. */
+export type MentionSearchResult = MentionItem[] | MentionJsonApiDocument | MentionJsonApiResource[] | null | undefined;
+export type MentionSource = {
+    /**
+     * Characters that must appear immediately after `@` to select this source.
+     * Use `""` for the default/fallback source (e.g. usernames on a bare `@`).
+     * Matching is case-sensitive and longest-prefix wins, so `@T` routes to the
+     * `"T"` source rather than the `""` source.
+     */
+    prefix: string;
+    /** Human label for the popup header / grouping (e.g. "Tests", "Users"). */
+    label?: string;
+    /**
+     * Static list (or provider). Filtered client-side by the typed query. Use
+     * this for data already in memory, like the list of project members.
+     */
+    items?: MentionItemsInput;
+    /**
+     * Async fetcher invoked with the typed query (the text after the prefix).
+     * Use this for server-backed lookups like tests (`@T`) and suites (`@S`).
+     */
+    search?: (query: string) => Promise<MentionSearchResult> | MentionSearchResult;
+    /**
+     * Builds the text inserted when an item is chosen. Defaults to
+     * `@{prefix}{id}` (so a test with id `123456` becomes `@T123456`).
+     */
+    insert?: (item: MentionItem, source: MentionSource) => string;
+    /** Minimum query length before `search` runs. Default 0 (fires on empty query). */
+    minChars?: number;
+    /** Max items shown. Default 8. */
+    limit?: number;
+};
+/** A currently-active mention detected at the caret. */
+export type ActiveMention = {
+    source: MentionSource;
+    /** Matched prefix (e.g. "T", "S", or ""). */
+    prefix: string;
+    /** Text typed after the prefix (what `search`/filter receives). */
+    query: string;
+    /** Index of the `@` in the source text. */
+    start: number;
+    /** Caret index (exclusive end of the token being edited). */
+    end: number;
+    /** Full token text between `@` (exclusive) and the caret, i.e. `prefix + query`. */
+    token: string;
+};
+export type MentionJsonApiAttributes = {
+    title?: string | null;
+    name?: string | null;
+    label?: string | null;
+    username?: string | null;
+    email?: string | null;
+    description?: string | null;
+    detail?: string | null;
+    [key: string]: unknown;
+};
+export type MentionJsonApiResource = {
+    id?: string | number | null;
+    type?: string | null;
+    attributes?: MentionJsonApiAttributes | null;
+};
+export type MentionJsonApiDocument = {
+    data?: MentionJsonApiResource[] | null;
+};
+/** Register the mention sources used when a consumer doesn't pass `sources` explicitly. */
+export declare function setMentionSources(sources: MentionSource[] | null): void;
+/** Read the globally-registered mention sources. */
+export declare function getMentionSources(): MentionSource[];
+/**
+ * Pick the source whose `prefix` matches the start of `token`. Longest prefix
+ * wins; the empty-prefix source is the ultimate fallback. Returns `null` when
+ * nothing matches (e.g. `@T` typed but only a `""` source is registered and it
+ * is absent).
+ */
+export declare function resolveMentionSource(token: string, sources: MentionSource[]): MentionSource | null;
+/**
+ * Detect the mention being edited at `caret` within `text`.
+ *
+ * A mention is the run of non-whitespace characters after an `@` that sits at
+ * the start of the text or immediately after whitespace (so emails like
+ * `a@b.com` never trigger). Returns `null` when the caret is not inside such a
+ * token or no source matches.
+ */
+export declare function parseActiveMention(text: string, caret: number, sources: MentionSource[]): ActiveMention | null;
+/** The text a chosen item inserts, honoring item/source overrides. */
+export declare function buildMentionInsertText(source: MentionSource, item: MentionItem): string;
+export type MentionApplication = {
+    /** The full text after replacing the active token with the inserted mention. */
+    text: string;
+    /** Caret position after insertion (after the token and its trailing space). */
+    caret: number;
+};
+/**
+ * Replace the active mention token in `text` with `insertText`, adding a single
+ * trailing space so the caret lands ready for the next word and the freshly
+ * inserted `@…` token does not immediately re-trigger the popup.
+ */
+export declare function applyMention(text: string, active: Pick<ActiveMention, "start" | "end">, insertText: string): MentionApplication;
+/**
+ * Rank static items against a query: label starts-with beats label contains,
+ * which beats id matches. Case-insensitive. An empty query returns the head of
+ * the list unchanged.
+ */
+export declare function filterMentionItems(items: MentionItem[], query: string, limit?: number): MentionItem[];
+/**
+ * Route a typed query (everything after the trigger char, e.g. `T123` or `bob`)
+ * to its source and resolve the items to show. Handles prefix stripping,
+ * `minChars`, async `search`, static `items` (incl. provider functions),
+ * normalization, and the `limit`. Returns `null` when no source matches.
+ *
+ * Shared by both mention frontends (the textarea hook and the BlockNote menu).
+ */
+export declare function resolveMentionQuery(query: string, sources: MentionSource[]): Promise<{
+    source: MentionSource;
+    items: MentionItem[];
+} | null>;
+export declare function parseMentionsFromJsonApi(document: MentionJsonApiDocument | MentionJsonApiResource[] | null | undefined): MentionItem[];
+/** Coerce any supported `search`/`items` result into a clean `MentionItem[]`. */
+export declare function normalizeMentionItems(result: MentionSearchResult): MentionItem[];