testomatio-editor-blocks 0.4.77 → 0.4.78

package/package/editor/mentionAutocomplete.js

@@ -0,0 +1,218 @@
+/**
+ * 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`.
+ */
+/* ------------------------------------------------------------------ *
+ * Global source registry (dependency-injection seam, mirrors the rest
+ * of the library's `setXFetcher` pattern).
+ * ------------------------------------------------------------------ */
+let globalSources = [];
+/** Register the mention sources used when a consumer doesn't pass `sources` explicitly. */
+export function setMentionSources(sources) {
+    globalSources = Array.isArray(sources) ? sources : [];
+}
+/** Read the globally-registered mention sources. */
+export function getMentionSources() {
+    return globalSources;
+}
+/* ------------------------------------------------------------------ *
+ * Pure logic
+ * ------------------------------------------------------------------ */
+const WHITESPACE = /\s/;
+/**
+ * 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 function resolveMentionSource(token, sources) {
+    var _a, _b;
+    let best = null;
+    for (const source of sources) {
+        const prefix = (_a = source.prefix) !== null && _a !== void 0 ? _a : "";
+        if (!token.startsWith(prefix))
+            continue;
+        if (best === null || prefix.length > ((_b = best.prefix) !== null && _b !== void 0 ? _b : "").length) {
+            best = source;
+        }
+    }
+    return best;
+}
+/**
+ * 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 function parseActiveMention(text, caret, sources) {
+    var _a;
+    if (!sources.length)
+        return null;
+    const pos = Math.max(0, Math.min(caret, text.length));
+    const before = text.slice(0, pos);
+    const at = before.lastIndexOf("@");
+    if (at === -1)
+        return null;
+    // The `@` must start a word: preceded by nothing or whitespace.
+    const charBefore = at === 0 ? "" : text[at - 1];
+    if (charBefore !== "" && !WHITESPACE.test(charBefore))
+        return null;
+    // The token is everything from just after `@` up to the caret. Whitespace
+    // ends a mention, so a caret past a space means we're no longer inside one.
+    const token = before.slice(at + 1);
+    if (WHITESPACE.test(token))
+        return null;
+    const source = resolveMentionSource(token, sources);
+    if (!source)
+        return null;
+    const prefix = (_a = source.prefix) !== null && _a !== void 0 ? _a : "";
+    return {
+        source,
+        prefix,
+        query: token.slice(prefix.length),
+        start: at,
+        end: pos,
+        token,
+    };
+}
+/** The text a chosen item inserts, honoring item/source overrides. */
+export function buildMentionInsertText(source, item) {
+    var _a;
+    if (typeof item.insertText === "string")
+        return item.insertText;
+    if (typeof source.insert === "function")
+        return source.insert(item, source);
+    return `@${(_a = source.prefix) !== null && _a !== void 0 ? _a : ""}${item.id}`;
+}
+/**
+ * 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 function applyMention(text, active, insertText) {
+    const before = text.slice(0, active.start);
+    const after = text.slice(active.end);
+    const hasLeadingSpace = after.length > 0 && WHITESPACE.test(after[0]);
+    const separator = hasLeadingSpace ? "" : " ";
+    return {
+        text: `${before}${insertText}${separator}${after}`,
+        // Land just past the single following space (added or pre-existing) so the
+        // caret is ready for the next word.
+        caret: before.length + insertText.length + 1,
+    };
+}
+/**
+ * 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 function filterMentionItems(items, query, limit = 8) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return items.slice(0, limit);
+    const scored = [];
+    items.forEach((item, order) => {
+        var _a, _b, _c;
+        const label = ((_a = item.label) !== null && _a !== void 0 ? _a : "").toLowerCase();
+        const id = String((_b = item.id) !== null && _b !== void 0 ? _b : "").toLowerCase();
+        const detail = ((_c = item.detail) !== null && _c !== void 0 ? _c : "").toString().toLowerCase();
+        let score = -1;
+        if (label.startsWith(q))
+            score = 0;
+        else if (label.includes(q))
+            score = 1;
+        else if (id.startsWith(q) || id.includes(q))
+            score = 2;
+        else if (detail.includes(q))
+            score = 3;
+        if (score >= 0)
+            scored.push({ item, score, order });
+    });
+    scored.sort((a, b) => (a.score - b.score) || (a.order - b.order));
+    return scored.slice(0, limit).map((s) => s.item);
+}
+/**
+ * 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 async function resolveMentionQuery(query, sources) {
+    var _a, _b, _c;
+    const source = resolveMentionSource(query, sources);
+    if (!source)
+        return null;
+    const prefix = (_a = source.prefix) !== null && _a !== void 0 ? _a : "";
+    const sub = query.slice(prefix.length);
+    const limit = (_b = source.limit) !== null && _b !== void 0 ? _b : 8;
+    if (typeof source.search === "function") {
+        const minChars = (_c = source.minChars) !== null && _c !== void 0 ? _c : 0;
+        if (sub.length < minChars)
+            return { source, items: [] };
+        const items = normalizeMentionItems(await source.search(sub)).slice(0, limit);
+        return { source, items };
+    }
+    const input = source.items;
+    const raw = typeof input === "function" ? await input() : input !== null && input !== void 0 ? input : [];
+    const items = filterMentionItems(normalizeMentionItems(raw), sub, limit);
+    return { source, items };
+}
+/* ------------------------------------------------------------------ *
+ * Normalization of async / JSON:API results into MentionItem[]
+ * ------------------------------------------------------------------ */
+export function parseMentionsFromJsonApi(document) {
+    const resources = Array.isArray(document) ? document : document === null || document === void 0 ? void 0 : document.data;
+    if (!Array.isArray(resources) || resources.length === 0)
+        return [];
+    return resources
+        .map((resource) => normalizeJsonApiResource(resource))
+        .filter((value) => Boolean(value));
+}
+/** Coerce any supported `search`/`items` result into a clean `MentionItem[]`. */
+export function normalizeMentionItems(result) {
+    if (!result)
+        return [];
+    if (Array.isArray(result)) {
+        if (result.length === 0)
+            return [];
+        if (isMentionItemArray(result))
+            return result;
+        return parseMentionsFromJsonApi(result);
+    }
+    return parseMentionsFromJsonApi(result);
+}
+function normalizeJsonApiResource(resource) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    if (!resource)
+        return null;
+    const attrs = (_a = resource.attributes) !== null && _a !== void 0 ? _a : {};
+    const id = resource.id;
+    if (id === null || id === undefined || id === "")
+        return null;
+    const label = (_e = (_d = (_c = (_b = attrs.title) !== null && _b !== void 0 ? _b : attrs.name) !== null && _c !== void 0 ? _c : attrs.label) !== null && _d !== void 0 ? _d : attrs.username) !== null && _e !== void 0 ? _e : String(id);
+    return {
+        id: String(id),
+        label: String(label),
+        detail: (_h = (_g = (_f = attrs.detail) !== null && _f !== void 0 ? _f : attrs.description) !== null && _g !== void 0 ? _g : attrs.email) !== null && _h !== void 0 ? _h : null,
+    };
+}
+function isMentionItemArray(value) {
+    const first = value[0];
+    return Boolean(first) && typeof (first === null || first === void 0 ? void 0 : first.label) === "string";
+}

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/MentionAutocomplete";
 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/MentionAutocomplete";
 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.78",
   "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">