@relevaince/mentions 0.3.2 → 0.5.0

package/dist/index.js

@@ -39,6 +39,7 @@ module.exports = __toCommonJS(index_exports);
 
 // src/components/MentionsInput.tsx
 var import_react5 = require("react");
+var import_react_dom = require("react-dom");
 var import_react6 = require("@tiptap/react");
 
 // src/hooks/useMentionsEditor.ts
@@ -64,6 +65,12 @@ var MentionNode = import_core.Node.create({
   atom: true,
   selectable: true,
   draggable: false,
+  addOptions() {
+    return {
+      onClickRef: void 0,
+      onHoverRef: void 0
+    };
+  },
   addAttributes() {
     return {
       id: {
@@ -96,11 +103,17 @@ var MentionNode = import_core.Node.create({
     const label = node.attrs.label;
     const prefix = DEFAULT_PREFIXES[entityType] ?? "@";
     const display = `${prefix}${label}`;
+    const hasClick = !!this.options.onClickRef?.current;
+    const extraAttrs = {};
+    if (hasClick) {
+      extraAttrs["data-mention-clickable"] = "";
+    }
     return [
       "span",
       (0, import_core.mergeAttributes)(HTMLAttributes, {
         "data-mention": "",
-        class: "mention-chip"
+        class: "mention-chip",
+        ...extraAttrs
       }),
       display
     ];
@@ -111,6 +124,58 @@ var MentionNode = import_core.Node.create({
     const prefix = DEFAULT_PREFIXES[entityType] ?? "@";
     return `${prefix}${label}`;
   },
+  addNodeView() {
+    const options = this.options;
+    return ({ node, HTMLAttributes }) => {
+      const entityType = node.attrs.entityType;
+      const label = node.attrs.label;
+      const id = node.attrs.id;
+      const prefix = DEFAULT_PREFIXES[entityType] ?? "@";
+      const dom = document.createElement("span");
+      Object.entries(
+        (0, import_core.mergeAttributes)(HTMLAttributes, {
+          "data-mention": "",
+          "data-type": entityType,
+          "data-id": id,
+          class: "mention-chip"
+        })
+      ).forEach(([key, val]) => {
+        if (val != null && val !== false) dom.setAttribute(key, String(val));
+      });
+      dom.textContent = `${prefix}${label}`;
+      if (options.onClickRef?.current) {
+        dom.setAttribute("data-mention-clickable", "");
+        dom.style.cursor = "pointer";
+      }
+      dom.addEventListener("click", (event) => {
+        const handler = options.onClickRef?.current;
+        if (handler) {
+          event.preventDefault();
+          event.stopPropagation();
+          handler({ id, type: entityType, label }, event);
+        }
+      });
+      let tooltip = null;
+      dom.addEventListener("mouseenter", () => {
+        const hoverFn = options.onHoverRef?.current;
+        if (!hoverFn) return;
+        const content = hoverFn({ id, type: entityType, label });
+        if (!content) return;
+        tooltip = document.createElement("div");
+        tooltip.setAttribute("data-mention-tooltip", "");
+        tooltip.textContent = typeof content === "string" ? content : "";
+        dom.style.position = "relative";
+        dom.appendChild(tooltip);
+      });
+      dom.addEventListener("mouseleave", () => {
+        if (tooltip && tooltip.parentNode) {
+          tooltip.parentNode.removeChild(tooltip);
+          tooltip = null;
+        }
+      });
+      return { dom };
+    };
+  },
   addKeyboardShortcuts() {
     return {
       Backspace: () => this.editor.commands.command(({ tr, state }) => {
@@ -143,7 +208,13 @@ function detectTrigger(text, cursorPos, docStartPos, triggers) {
       if (before.substring(i, i + trigger.length) === trigger) {
         if (i === 0 || /\s/.test(before[i - 1])) {
           const query = before.slice(i + trigger.length);
-          return { trigger, query, from: docStartPos + i, to: cursorPos };
+          return {
+            trigger,
+            query,
+            from: docStartPos + i,
+            to: cursorPos,
+            textBefore: before.slice(0, i)
+          };
         }
       }
     }
@@ -151,7 +222,7 @@ function detectTrigger(text, cursorPos, docStartPos, triggers) {
   return null;
 }
 var suggestionPluginKey = new import_state.PluginKey("mentionSuggestion");
-function createSuggestionExtension(triggers, callbacksRef) {
+function createSuggestionExtension(triggers, callbacksRef, allowTriggerRef) {
   return import_core2.Extension.create({
     name: "mentionSuggestion",
     priority: 200,
@@ -229,6 +300,20 @@ function createSuggestionExtension(triggers, callbacksRef) {
               const cursorPos = $pos.pos;
               const match = detectTrigger(blockText, cursorPos, blockStart, triggers);
               if (match) {
+                if (allowTriggerRef?.current) {
+                  const allowed = allowTriggerRef.current(match.trigger, {
+                    textBefore: match.textBefore
+                  });
+                  if (!allowed) {
+                    if (active) {
+                      active = false;
+                      lastQuery = null;
+                      lastTrigger = null;
+                      callbacksRef.current.onExit();
+                    }
+                    return;
+                  }
+                }
                 const range = { from: match.from, to: match.to };
                 const props = {
                   query: match.query,
@@ -286,11 +371,12 @@ function serializeParagraph(node) {
   if (!node.content) return "";
   return node.content.map((child) => {
     if (child.type === "mention") {
-      const { id, label, rootLabel } = child.attrs ?? {};
+      const { id, label, entityType, rootLabel } = child.attrs ?? {};
+      const idPart = entityType && entityType !== "unknown" ? `${entityType}:${id}` : id;
       if (rootLabel != null && rootLabel !== "") {
-        return `@${rootLabel}[${label}](${id})`;
+        return `@${rootLabel}[${label}](${idPart})`;
       }
-      return `@[${label}](${id})`;
+      return `@[${label}](${idPart})`;
     }
     return child.text ?? "";
   }).join("");
@@ -335,7 +421,7 @@ function extractParagraphText(node) {
 }
 
 // src/core/markdownParser.ts
-var MENTION_RE = /@(?:([^\[]+)\[)?\[([^\]]+)\]\((?:([^:)]+):)?([^)]+)\)/g;
+var MENTION_RE = /@([^\[@]*)\[([^\]]+)\]\((?:([^:)]+):)?([^)]+)\)/g;
 function parseFromMarkdown(markdown) {
   const lines = markdown.split("\n");
   const content = lines.map((line) => {
@@ -351,7 +437,7 @@ function parseLine(line) {
   let match;
   while ((match = MENTION_RE.exec(line)) !== null) {
     const fullMatch = match[0];
-    const rootLabel = match[1] ?? null;
+    const rootLabel = match[1] || null;
     const label = match[2];
     const entityType = match[3] ?? "unknown";
     const id = match[4];
@@ -397,27 +483,48 @@ function buildOutput(editor) {
     plainText: extractPlainText(json)
   };
 }
-function createSubmitExtension(onSubmitRef, clearOnSubmitRef) {
+function collectMentionTokens(doc) {
+  const tokens = [];
+  function walk(node) {
+    if (node.type === "mention" && node.attrs) {
+      tokens.push({
+        id: node.attrs.id,
+        type: node.attrs.entityType ?? node.attrs.type,
+        label: node.attrs.label
+      });
+    }
+    if (node.content) {
+      for (const child of node.content) walk(child);
+    }
+  }
+  walk(doc);
+  return tokens;
+}
+function createSubmitExtension(onSubmitRef, clearOnSubmitRef, submitKeyRef) {
   return import_core3.Extension.create({
     name: "submitShortcut",
     priority: 150,
     addKeyboardShortcuts() {
       return {
         "Mod-Enter": () => {
-          if (onSubmitRef.current) {
-            onSubmitRef.current(buildOutput(this.editor));
-            if (clearOnSubmitRef.current) {
-              this.editor.commands.clearContent(true);
+          const key = submitKeyRef.current;
+          if (key === "mod+enter" || key === "enter") {
+            if (onSubmitRef.current) {
+              onSubmitRef.current(buildOutput(this.editor));
+              if (clearOnSubmitRef.current) {
+                this.editor.commands.clearContent(true);
+              }
             }
+            return true;
           }
-          return true;
+          return false;
         }
       };
     }
   });
 }
 var enterSubmitPluginKey = new import_state2.PluginKey("enterSubmit");
-function createEnterExtension(onSubmitRef, clearOnSubmitRef) {
+function createEnterExtension(onSubmitRef, clearOnSubmitRef, submitKeyRef) {
   return import_core3.Extension.create({
     name: "enterSubmit",
     priority: 150,
@@ -429,6 +536,11 @@ function createEnterExtension(onSubmitRef, clearOnSubmitRef) {
           props: {
             handleKeyDown(_view, event) {
               if (event.key !== "Enter") return false;
+              const key = submitKeyRef.current;
+              if (key === "none") return false;
+              if (key === "mod+enter") {
+                return false;
+              }
               if (event.shiftKey) {
                 editor.commands.splitBlock();
                 return true;
@@ -448,6 +560,33 @@ function createEnterExtension(onSubmitRef, clearOnSubmitRef) {
     }
   });
 }
+var mentionRemovePluginKey = new import_state2.PluginKey("mentionRemove");
+function createMentionRemoveExtension(onMentionRemoveRef) {
+  return import_core3.Extension.create({
+    name: "mentionRemoveDetector",
+    priority: 100,
+    addProseMirrorPlugins() {
+      return [
+        new import_state2.Plugin({
+          key: mentionRemovePluginKey,
+          appendTransaction(transactions, oldState, newState) {
+            if (!onMentionRemoveRef.current) return null;
+            const oldMentions = collectMentionTokens(oldState.doc.toJSON());
+            const newMentions = collectMentionTokens(newState.doc.toJSON());
+            if (oldMentions.length <= newMentions.length) return null;
+            const newIds = new Set(newMentions.map((m) => m.id));
+            for (const m of oldMentions) {
+              if (!newIds.has(m.id)) {
+                onMentionRemoveRef.current(m);
+              }
+            }
+            return null;
+          }
+        })
+      ];
+    }
+  });
+}
 function useMentionsEditor({
   providers,
   value,
@@ -457,7 +596,15 @@ function useMentionsEditor({
   placeholder,
   autoFocus = false,
   editable = true,
-  callbacksRef
+  callbacksRef,
+  onFocus,
+  onBlur,
+  submitKey = "enter",
+  onMentionRemove,
+  onMentionClick,
+  onMentionHover,
+  allowTrigger,
+  validateMention
 }) {
   const onChangeRef = (0, import_react.useRef)(onChange);
   onChangeRef.current = onChange;
@@ -465,6 +612,23 @@ function useMentionsEditor({
   onSubmitRef.current = onSubmit;
   const clearOnSubmitRef = (0, import_react.useRef)(clearOnSubmit);
   clearOnSubmitRef.current = clearOnSubmit;
+  const onFocusRef = (0, import_react.useRef)(onFocus);
+  onFocusRef.current = onFocus;
+  const onBlurRef = (0, import_react.useRef)(onBlur);
+  onBlurRef.current = onBlur;
+  const submitKeyRef = (0, import_react.useRef)(submitKey);
+  submitKeyRef.current = submitKey;
+  const onMentionRemoveRef = (0, import_react.useRef)(onMentionRemove);
+  onMentionRemoveRef.current = onMentionRemove;
+  const onMentionClickRef = (0, import_react.useRef)(onMentionClick);
+  onMentionClickRef.current = onMentionClick;
+  const onMentionHoverRef = (0, import_react.useRef)(onMentionHover);
+  onMentionHoverRef.current = onMentionHover;
+  const allowTriggerRef = (0, import_react.useRef)(allowTrigger);
+  allowTriggerRef.current = allowTrigger;
+  const validateMentionRef = (0, import_react.useRef)(validateMention);
+  validateMentionRef.current = validateMention;
+  const internalMarkdownRef = (0, import_react.useRef)(null);
   const initialContent = (0, import_react.useMemo)(() => {
     if (!value) return void 0;
     return parseFromMarkdown(value);
@@ -476,16 +640,27 @@ function useMentionsEditor({
     [triggersKey]
   );
   const suggestionExtension = (0, import_react.useMemo)(
-    () => createSuggestionExtension(triggers, callbacksRef),
+    () => createSuggestionExtension(triggers, callbacksRef, allowTriggerRef),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [triggersKey]
   );
   const submitExt = (0, import_react.useMemo)(
-    () => createSubmitExtension(onSubmitRef, clearOnSubmitRef),
+    () => createSubmitExtension(onSubmitRef, clearOnSubmitRef, submitKeyRef),
     []
   );
   const enterExt = (0, import_react.useMemo)(
-    () => createEnterExtension(onSubmitRef, clearOnSubmitRef),
+    () => createEnterExtension(onSubmitRef, clearOnSubmitRef, submitKeyRef),
+    []
+  );
+  const mentionRemoveExt = (0, import_react.useMemo)(
+    () => createMentionRemoveExtension(onMentionRemoveRef),
+    []
+  );
+  const mentionNodeExt = (0, import_react.useMemo)(
+    () => MentionNode.configure({
+      onClickRef: onMentionClickRef,
+      onHoverRef: onMentionHoverRef
+    }),
     []
   );
   const editor = (0, import_react2.useEditor)({
@@ -504,10 +679,11 @@ function useMentionsEditor({
         placeholder: ({ editor: editor2 }) => editor2.isEmpty ? placeholder ?? "Type a message..." : "",
         showOnlyCurrent: true
       }),
-      MentionNode,
+      mentionNodeExt,
       suggestionExtension,
       submitExt,
-      enterExt
+      enterExt,
+      mentionRemoveExt
     ],
     content: initialContent,
     autofocus: autoFocus ? "end" : false,
@@ -518,7 +694,15 @@ function useMentionsEditor({
       }
     },
     onUpdate: ({ editor: editor2 }) => {
-      onChangeRef.current?.(buildOutput(editor2));
+      const output = buildOutput(editor2);
+      internalMarkdownRef.current = output.markdown;
+      onChangeRef.current?.(output);
+    },
+    onFocus: () => {
+      onFocusRef.current?.();
+    },
+    onBlur: () => {
+      onBlurRef.current?.();
     }
   });
   (0, import_react.useEffect)(() => {
@@ -526,6 +710,36 @@ function useMentionsEditor({
       editor.setEditable(editable);
     }
   }, [editor, editable]);
+  (0, import_react.useEffect)(() => {
+    if (!editor || value === void 0) return;
+    if (value === internalMarkdownRef.current) return;
+    const doc = parseFromMarkdown(value);
+    editor.commands.setContent(doc);
+    internalMarkdownRef.current = value;
+  }, [editor, value]);
+  (0, import_react.useEffect)(() => {
+    if (!editor || !validateMention) return;
+    const runValidation = async () => {
+      const doc = editor.getJSON();
+      const tokens = collectMentionTokens(doc);
+      const invalidIds = /* @__PURE__ */ new Set();
+      await Promise.all(
+        tokens.map(async (token) => {
+          const valid = await validateMention(token);
+          if (!valid) invalidIds.add(token.id);
+        })
+      );
+      editor.view.dom.querySelectorAll("[data-mention]").forEach((el) => {
+        const id = el.getAttribute("data-id");
+        if (id && invalidIds.has(id)) {
+          el.setAttribute("data-mention-invalid", "");
+        } else {
+          el.removeAttribute("data-mention-invalid");
+        }
+      });
+    };
+    runValidation();
+  }, [editor, validateMention]);
   const clear = (0, import_react.useCallback)(() => {
     editor?.commands.clearContent(true);
   }, [editor]);
@@ -534,6 +748,7 @@ function useMentionsEditor({
       if (!editor) return;
       const doc = parseFromMarkdown(markdown);
       editor.commands.setContent(doc);
+      internalMarkdownRef.current = markdown;
     },
     [editor]
   );
@@ -549,6 +764,27 @@ function useMentionsEditor({
 
 // src/hooks/useSuggestion.ts
 var import_react3 = require("react");
+
+// src/utils/debounce.ts
+function debounce(fn, ms) {
+  let timer = null;
+  const debounced = ((...args) => {
+    if (timer != null) clearTimeout(timer);
+    timer = setTimeout(() => {
+      timer = null;
+      fn(...args);
+    }, ms);
+  });
+  debounced.cancel = () => {
+    if (timer != null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+  return debounced;
+}
+
+// src/hooks/useSuggestion.ts
 var IDLE_STATE = {
   state: "idle",
   items: [],
@@ -559,16 +795,24 @@ var IDLE_STATE = {
   trigger: null,
   query: ""
 };
-function useSuggestion(providers) {
+function useSuggestion(providers, options = {}) {
   const [uiState, setUIState] = (0, import_react3.useState)(IDLE_STATE);
   const stateRef = (0, import_react3.useRef)(uiState);
   stateRef.current = uiState;
   const providersRef = (0, import_react3.useRef)(providers);
   providersRef.current = providers;
+  const onMentionAddRef = (0, import_react3.useRef)(options.onMentionAdd);
+  onMentionAddRef.current = options.onMentionAdd;
   const commandRef = (0, import_react3.useRef)(
     null
   );
   const providerRef = (0, import_react3.useRef)(null);
+  const debouncedFetchRef = (0, import_react3.useRef)(null);
+  (0, import_react3.useEffect)(() => {
+    return () => {
+      debouncedFetchRef.current?.cancel();
+    };
+  }, []);
   const fetchItems = (0, import_react3.useCallback)(
     async (provider, query, parent, useSearchAll) => {
       setUIState((prev) => ({ ...prev, loading: true, state: "loading" }));
@@ -599,6 +843,23 @@ function useSuggestion(providers) {
     },
     []
   );
+  const scheduleFetch = (0, import_react3.useCallback)(
+    (provider, query, parent, useSearchAll) => {
+      debouncedFetchRef.current?.cancel();
+      const ms = provider.debounceMs;
+      if (ms && ms > 0) {
+        setUIState((prev) => ({ ...prev, loading: true }));
+        const debouncedFn = debounce(() => {
+          fetchItems(provider, query, parent, useSearchAll);
+        }, ms);
+        debouncedFetchRef.current = debouncedFn;
+        debouncedFn();
+      } else {
+        fetchItems(provider, query, parent, useSearchAll);
+      }
+    },
+    [fetchItems]
+  );
   const onStart = (0, import_react3.useCallback)(
     (props) => {
       const provider = providersRef.current.find(
@@ -617,13 +878,31 @@ function useSuggestion(providers) {
         trigger: props.trigger,
         query: props.query
       });
+      if (!props.query.trim() && provider.getRecentItems) {
+        provider.getRecentItems().then((recentItems) => {
+          const tagged = recentItems.map((item) => ({
+            ...item,
+            group: item.group ?? "Recent"
+          }));
+          setUIState((prev) => ({
+            ...prev,
+            items: tagged,
+            loading: false,
+            state: "showing",
+            activeIndex: 0
+          }));
+        }).catch(() => {
+          scheduleFetch(provider, props.query);
+        });
+        return;
+      }
       if (props.query.trim() && provider.searchAll) {
-        fetchItems(provider, props.query, void 0, true);
+        scheduleFetch(provider, props.query, void 0, true);
       } else {
-        fetchItems(provider, props.query);
+        scheduleFetch(provider, props.query);
       }
     },
-    [fetchItems]
+    [scheduleFetch]
   );
   const onUpdate = (0, import_react3.useCallback)(
     (props) => {
@@ -647,14 +926,31 @@ function useSuggestion(providers) {
         }));
       }
       if (props.query.trim() && provider.searchAll) {
-        fetchItems(provider, props.query, void 0, true);
+        scheduleFetch(provider, props.query, void 0, true);
+      } else if (!props.query.trim() && provider.getRecentItems) {
+        provider.getRecentItems().then((recentItems) => {
+          const tagged = recentItems.map((item) => ({
+            ...item,
+            group: item.group ?? "Recent"
+          }));
+          setUIState((prev) => ({
+            ...prev,
+            items: tagged,
+            loading: false,
+            state: "showing",
+            activeIndex: 0
+          }));
+        }).catch(() => {
+          scheduleFetch(provider, props.query);
+        });
       } else {
-        fetchItems(provider, props.query);
+        scheduleFetch(provider, props.query);
       }
     },
-    [fetchItems]
+    [scheduleFetch]
   );
   const onExit = (0, import_react3.useCallback)(() => {
+    debouncedFetchRef.current?.cancel();
     providerRef.current = null;
     commandRef.current = null;
     setUIState(IDLE_STATE);
@@ -689,8 +985,8 @@ function useSuggestion(providers) {
         fetchItems(provider, "", selected);
         return;
       }
+      const rootLabel = current.breadcrumbs.length > 0 ? current.breadcrumbs[0].label : selected.rootLabel ?? null;
       if (commandRef.current) {
-        const rootLabel = current.breadcrumbs.length > 0 ? current.breadcrumbs[0].label : selected.rootLabel ?? null;
         commandRef.current({
           id: selected.id,
           label: selected.label,
@@ -698,6 +994,11 @@ function useSuggestion(providers) {
           rootLabel
         });
       }
+      onMentionAddRef.current?.({
+        id: selected.id,
+        type: selected.type,
+        label: selected.label
+      });
     },
     [fetchItems]
   );
@@ -722,6 +1023,7 @@ function useSuggestion(providers) {
     });
   }, [fetchItems]);
   const close = (0, import_react3.useCallback)(() => {
+    debouncedFetchRef.current?.cancel();
     setUIState(IDLE_STATE);
   }, []);
   const searchNested = (0, import_react3.useCallback)(
@@ -731,10 +1033,10 @@ function useSuggestion(providers) {
       const current = stateRef.current;
       const parent = current.breadcrumbs[current.breadcrumbs.length - 1];
       if (parent) {
-        fetchItems(provider, query, parent);
+        scheduleFetch(provider, query, parent);
       }
     },
-    [fetchItems]
+    [scheduleFetch]
   );
   const onKeyDown = (0, import_react3.useCallback)(
     ({ event }) => {
@@ -757,6 +1059,14 @@ function useSuggestion(providers) {
           }
           return true;
         }
+        case "Tab": {
+          event.preventDefault();
+          const selectedItem = current.items[current.activeIndex];
+          if (selectedItem) {
+            select(selectedItem);
+          }
+          return true;
+        }
         case "ArrowRight": {
           const activeItem = current.items[current.activeIndex];
           if (activeItem?.hasChildren) {
@@ -831,13 +1141,13 @@ function optionAttrs(id, selected, index) {
 
 // src/components/SuggestionList.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
-var LISTBOX_ID = "mentions-suggestion-listbox";
 function SuggestionList({
   items,
   activeIndex,
   breadcrumbs,
   loading,
   trigger,
+  query,
   clientRect,
   onSelect,
   onHover,
@@ -846,7 +1156,12 @@ function SuggestionList({
   onNavigateUp,
   onNavigateDown,
   onClose,
-  renderItem
+  onFocusEditor,
+  renderItem,
+  renderEmpty,
+  renderLoading,
+  renderGroupHeader,
+  listboxId
 }) {
   const listRef = (0, import_react4.useRef)(null);
   const searchInputRef = (0, import_react4.useRef)(null);
@@ -860,18 +1175,24 @@ function SuggestionList({
       prevBreadcrumbKey.current = breadcrumbKey;
     }
   }, [breadcrumbKey]);
+  const prevBreadcrumbsLen = (0, import_react4.useRef)(breadcrumbs.length);
   (0, import_react4.useEffect)(() => {
-    if (breadcrumbs.length > 0 && searchInputRef.current) {
+    if (prevBreadcrumbsLen.current > 0 && breadcrumbs.length === 0) {
+      onFocusEditor?.();
+    } else if (breadcrumbs.length > 0 && searchInputRef.current) {
       requestAnimationFrame(() => searchInputRef.current?.focus());
     }
-  }, [breadcrumbKey, breadcrumbs.length]);
+    prevBreadcrumbsLen.current = breadcrumbs.length;
+  }, [breadcrumbKey, breadcrumbs.length, onFocusEditor]);
   (0, import_react4.useEffect)(() => {
     if (!listRef.current) return;
     const active = listRef.current.querySelector('[aria-selected="true"]');
     active?.scrollIntoView({ block: "nearest" });
   }, [activeIndex]);
-  const style = usePopoverPosition(clientRect);
-  if (items.length === 0 && !loading) return null;
+  const { style, position } = usePopoverPosition(clientRect);
+  const activeQuery = breadcrumbs.length > 0 ? nestedQuery : query;
+  const showEmpty = !loading && items.length === 0 && activeQuery.trim().length > 0;
+  if (items.length === 0 && !loading && !showEmpty) return null;
   const handleSearchKeyDown = (e) => {
     switch (e.key) {
       case "ArrowDown":
@@ -891,8 +1212,23 @@ function SuggestionList({
       }
       case "Escape":
         e.preventDefault();
+        onFocusEditor?.();
         onClose?.();
         break;
+      case "ArrowLeft":
+        if (nestedQuery === "" || e.currentTarget.selectionStart === 0) {
+          e.preventDefault();
+          onGoBack();
+        }
+        break;
+      case "ArrowRight": {
+        const item = items[activeIndex];
+        if (item?.hasChildren) {
+          e.preventDefault();
+          onSelect(item);
+        }
+        break;
+      }
       case "Backspace":
         if (nestedQuery === "") {
           e.preventDefault();
@@ -901,11 +1237,13 @@ function SuggestionList({
         break;
     }
   };
+  const hasGroups = items.some((item) => item.group);
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
     "div",
     {
       "data-suggestions": "",
       "data-trigger": trigger,
+      "data-suggestions-position": position,
       style,
       ref: listRef,
       children: [
@@ -943,28 +1281,76 @@ function SuggestionList({
             spellCheck: false
           }
         ) }),
-        loading && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { "data-suggestion-loading": "", children: "Loading..." }),
-        !loading && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { ...listboxAttrs(LISTBOX_ID, `${trigger ?? ""} suggestions`), children: items.map((item, index) => {
-          const isActive = index === activeIndex;
-          const itemId = `mention-option-${item.id}`;
-          return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
-            "div",
-            {
-              ...optionAttrs(itemId, isActive, index),
-              "data-suggestion-item": "",
-              "data-suggestion-item-active": isActive ? "" : void 0,
-              "data-has-children": item.hasChildren ? "" : void 0,
-              onMouseEnter: () => onHover(index),
-              onClick: () => onSelect(item),
-              children: renderItem ? renderItem(item, depth) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DefaultSuggestionItem, { item })
-            },
-            item.id
-          );
-        }) })
+        loading && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { "data-suggestion-loading": "", children: renderLoading ? renderLoading() : "Loading..." }),
+        showEmpty && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { "data-suggestion-empty": "", children: renderEmpty ? renderEmpty(activeQuery) : "No results" }),
+        !loading && items.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { ...listboxAttrs(listboxId, `${trigger ?? ""} suggestions`), children: hasGroups ? renderGroupedItems(items, activeIndex, depth, onSelect, onHover, renderItem, renderGroupHeader) : items.map((item, index) => /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          SuggestionItem,
+          {
+            item,
+            index,
+            isActive: index === activeIndex,
+            depth,
+            onSelect,
+            onHover,
+            renderItem
+          },
+          item.id
+        )) })
       ]
     }
   );
 }
+function renderGroupedItems(items, activeIndex, depth, onSelect, onHover, renderItem, renderGroupHeader) {
+  const elements = [];
+  let lastGroup;
+  items.forEach((item, index) => {
+    if (item.group && item.group !== lastGroup) {
+      lastGroup = item.group;
+      elements.push(
+        /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { "data-suggestion-group-header": "", children: renderGroupHeader ? renderGroupHeader(item.group) : item.group }, `group-${item.group}`)
+      );
+    }
+    elements.push(
+      /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+        SuggestionItem,
+        {
+          item,
+          index,
+          isActive: index === activeIndex,
+          depth,
+          onSelect,
+          onHover,
+          renderItem
+        },
+        item.id
+      )
+    );
+  });
+  return elements;
+}
+function SuggestionItem({
+  item,
+  index,
+  isActive,
+  depth,
+  onSelect,
+  onHover,
+  renderItem
+}) {
+  const itemId = `mention-option-${item.id}`;
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+    "div",
+    {
+      ...optionAttrs(itemId, isActive, index),
+      "data-suggestion-item": "",
+      "data-suggestion-item-active": isActive ? "" : void 0,
+      "data-has-children": item.hasChildren ? "" : void 0,
+      onMouseEnter: () => onHover(index),
+      onClick: () => onSelect(item),
+      children: renderItem ? renderItem(item, depth) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)(DefaultSuggestionItem, { item })
+    }
+  );
+}
 function DefaultSuggestionItem({ item }) {
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(import_jsx_runtime.Fragment, { children: [
     item.icon && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { "data-suggestion-item-icon": "", children: item.icon }),
@@ -973,25 +1359,48 @@ function DefaultSuggestionItem({ item }) {
     item.hasChildren && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("span", { "data-suggestion-item-chevron": "", "aria-hidden": "true", children: "\u203A" })
   ] });
 }
+var POPOVER_HEIGHT_ESTIMATE = 280;
+var POPOVER_WIDTH_ESTIMATE = 360;
 function usePopoverPosition(clientRect) {
   if (!clientRect) {
-    return { display: "none" };
+    return { style: { display: "none" }, position: "below" };
   }
   const rect = clientRect();
   if (!rect) {
-    return { display: "none" };
+    return { style: { display: "none" }, position: "below" };
+  }
+  const viewportH = typeof window !== "undefined" ? window.innerHeight : 800;
+  const viewportW = typeof window !== "undefined" ? window.innerWidth : 1200;
+  const spaceBelow = viewportH - rect.bottom;
+  const shouldFlip = spaceBelow < POPOVER_HEIGHT_ESTIMATE && rect.top > spaceBelow;
+  let left = rect.left;
+  if (left + POPOVER_WIDTH_ESTIMATE > viewportW) {
+    left = Math.max(0, viewportW - POPOVER_WIDTH_ESTIMATE);
+  }
+  if (shouldFlip) {
+    return {
+      style: {
+        position: "fixed",
+        left: `${left}px`,
+        bottom: `${viewportH - rect.top + 4}px`,
+        zIndex: 50
+      },
+      position: "above"
+    };
   }
   return {
-    position: "fixed",
-    left: `${rect.left}px`,
-    top: `${rect.bottom + 4}px`,
-    zIndex: 50
+    style: {
+      position: "fixed",
+      left: `${left}px`,
+      top: `${rect.bottom + 4}px`,
+      zIndex: 50
+    },
+    position: "below"
   };
 }
 
 // src/components/MentionsInput.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
-var LISTBOX_ID2 = "mentions-suggestion-listbox";
 var MentionsInput = (0, import_react5.forwardRef)(
   function MentionsInput2({
     value,
@@ -1005,10 +1414,29 @@ var MentionsInput = (0, import_react5.forwardRef)(
     clearOnSubmit = true,
     maxLength,
     renderItem,
-    renderChip
+    renderChip,
+    renderEmpty,
+    renderLoading,
+    renderGroupHeader,
+    onFocus,
+    onBlur,
+    onMentionAdd,
+    onMentionRemove,
+    onMentionClick,
+    onMentionHover,
+    minHeight,
+    maxHeight,
+    submitKey = "enter",
+    allowTrigger,
+    validateMention,
+    portalContainer
   }, ref) {
-    const { uiState, actions, callbacksRef } = useSuggestion(providers);
-    const { editor, clear, setContent, focus } = useMentionsEditor({
+    const instanceId = (0, import_react5.useId)();
+    const listboxId = `mentions-listbox-${instanceId}`;
+    const { uiState, actions, callbacksRef } = useSuggestion(providers, {
+      onMentionAdd
+    });
+    const { editor, getOutput, clear, setContent, focus } = useMentionsEditor({
       providers,
       value,
       onChange,
@@ -1017,46 +1445,70 @@ var MentionsInput = (0, import_react5.forwardRef)(
       placeholder,
       autoFocus,
       editable: !disabled,
-      callbacksRef
+      callbacksRef,
+      onFocus,
+      onBlur,
+      submitKey,
+      onMentionRemove,
+      onMentionClick,
+      onMentionHover,
+      allowTrigger,
+      validateMention
     });
     (0, import_react5.useImperativeHandle)(
       ref,
-      () => ({ clear, setContent, focus }),
-      [clear, setContent, focus]
+      () => ({ clear, setContent, focus, getOutput }),
+      [clear, setContent, focus, getOutput]
     );
     const isExpanded = uiState.state !== "idle";
     const handleHover = (0, import_react5.useCallback)((index) => {
       void index;
     }, []);
+    const handleFocusEditor = (0, import_react5.useCallback)(() => {
+      editor?.commands.focus();
+    }, [editor]);
+    const editorStyle = {};
+    if (minHeight != null) editorStyle.minHeight = `${minHeight}px`;
+    if (maxHeight != null) {
+      editorStyle.maxHeight = `${maxHeight}px`;
+      editorStyle.overflowY = "auto";
+    }
+    const suggestionList = isExpanded ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
+      SuggestionList,
+      {
+        items: uiState.items,
+        activeIndex: uiState.activeIndex,
+        breadcrumbs: uiState.breadcrumbs,
+        loading: uiState.loading,
+        trigger: uiState.trigger,
+        query: uiState.query,
+        clientRect: uiState.clientRect,
+        onSelect: (item) => actions.select(item),
+        onHover: handleHover,
+        onGoBack: actions.goBack,
+        onSearchNested: actions.searchNested,
+        onNavigateUp: actions.navigateUp,
+        onNavigateDown: actions.navigateDown,
+        onClose: actions.close,
+        onFocusEditor: handleFocusEditor,
+        renderItem,
+        renderEmpty,
+        renderLoading,
+        renderGroupHeader,
+        listboxId
+      }
+    ) : null;
     return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
       "div",
       {
         className,
         "data-mentions-input": "",
         "data-disabled": disabled ? "" : void 0,
-        ...comboboxAttrs(isExpanded, LISTBOX_ID2),
+        ...comboboxAttrs(isExpanded, listboxId),
         "aria-activedescendant": isExpanded && uiState.items[uiState.activeIndex] ? `mention-option-${uiState.items[uiState.activeIndex].id}` : void 0,
         children: [
-          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_react6.EditorContent, { editor }),
-          isExpanded && /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(
-            SuggestionList,
-            {
-              items: uiState.items,
-              activeIndex: uiState.activeIndex,
-              breadcrumbs: uiState.breadcrumbs,
-              loading: uiState.loading,
-              trigger: uiState.trigger,
-              clientRect: uiState.clientRect,
-              onSelect: (item) => actions.select(item),
-              onHover: handleHover,
-              onGoBack: actions.goBack,
-              onSearchNested: actions.searchNested,
-              onNavigateUp: actions.navigateUp,
-              onNavigateDown: actions.navigateDown,
-              onClose: actions.close,
-              renderItem
-            }
-          )
+          /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { style: editorStyle, children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)(import_react6.EditorContent, { editor }) }),
+          portalContainer ? suggestionList && (0, import_react_dom.createPortal)(suggestionList, portalContainer) : suggestionList
         ]
       }
     );