@relevaince/mentions 0.3.3 → 0.6.0

package/dist/index.mjs

@@ -1,5 +1,6 @@
 // src/components/MentionsInput.tsx
-import { forwardRef, useCallback as useCallback3, useImperativeHandle } from "react";
+import { forwardRef, useCallback as useCallback3, useId, useImperativeHandle } from "react";
+import { createPortal } from "react-dom";
 import { EditorContent } from "@tiptap/react";
 
 // src/hooks/useMentionsEditor.ts
@@ -25,6 +26,12 @@ var MentionNode = Node.create({
   atom: true,
   selectable: true,
   draggable: false,
+  addOptions() {
+    return {
+      onClickRef: void 0,
+      onHoverRef: void 0
+    };
+  },
   addAttributes() {
     return {
       id: {
@@ -57,11 +64,17 @@ var MentionNode = 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",
       mergeAttributes(HTMLAttributes, {
         "data-mention": "",
-        class: "mention-chip"
+        class: "mention-chip",
+        ...extraAttrs
       }),
       display
     ];
@@ -72,6 +85,58 @@ var MentionNode = 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(
+        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 }) => {
@@ -104,7 +169,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)
+          };
         }
       }
     }
@@ -112,7 +183,7 @@ function detectTrigger(text, cursorPos, docStartPos, triggers) {
   return null;
 }
 var suggestionPluginKey = new PluginKey("mentionSuggestion");
-function createSuggestionExtension(triggers, callbacksRef) {
+function createSuggestionExtension(triggers, callbacksRef, allowTriggerRef, streamingRef) {
   return Extension.create({
     name: "mentionSuggestion",
     priority: 200,
@@ -163,6 +234,15 @@ function createSuggestionExtension(triggers, callbacksRef) {
         view() {
           return {
             update(view, _prevState) {
+              if (streamingRef?.current) {
+                if (active) {
+                  active = false;
+                  lastQuery = null;
+                  lastTrigger = null;
+                  callbacksRef.current.onExit();
+                }
+                return;
+              }
               const { state } = view;
               const { selection } = state;
               if (!selection.empty) {
@@ -190,6 +270,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,
@@ -359,27 +453,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 Extension2.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 PluginKey2("enterSubmit");
-function createEnterExtension(onSubmitRef, clearOnSubmitRef) {
+function createEnterExtension(onSubmitRef, clearOnSubmitRef, submitKeyRef) {
   return Extension2.create({
     name: "enterSubmit",
     priority: 150,
@@ -391,6 +506,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;
@@ -410,6 +530,61 @@ function createEnterExtension(onSubmitRef, clearOnSubmitRef) {
     }
   });
 }
+var mentionRemovePluginKey = new PluginKey2("mentionRemove");
+function createMentionRemoveExtension(onMentionRemoveRef) {
+  return Extension2.create({
+    name: "mentionRemoveDetector",
+    priority: 100,
+    addProseMirrorPlugins() {
+      return [
+        new Plugin2({
+          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;
+          }
+        })
+      ];
+    }
+  });
+}
+var streamingBlockPluginKey = new PluginKey2("streamingBlock");
+function createStreamingBlockExtension(streamingRef) {
+  return Extension2.create({
+    name: "streamingBlock",
+    priority: 200,
+    addProseMirrorPlugins() {
+      return [
+        new Plugin2({
+          key: streamingBlockPluginKey,
+          props: {
+            handleKeyDown() {
+              return streamingRef.current;
+            },
+            handleKeyPress() {
+              return streamingRef.current;
+            },
+            handlePaste() {
+              return streamingRef.current;
+            },
+            handleDrop() {
+              return streamingRef.current;
+            }
+          }
+        })
+      ];
+    }
+  });
+}
 function useMentionsEditor({
   providers,
   value,
@@ -419,7 +594,17 @@ function useMentionsEditor({
   placeholder,
   autoFocus = false,
   editable = true,
-  callbacksRef
+  callbacksRef,
+  onFocus,
+  onBlur,
+  submitKey = "enter",
+  onMentionRemove,
+  onMentionClick,
+  onMentionHover,
+  allowTrigger,
+  validateMention,
+  streaming = false,
+  onStreamingComplete
 }) {
   const onChangeRef = useRef(onChange);
   onChangeRef.current = onChange;
@@ -427,6 +612,30 @@ function useMentionsEditor({
   onSubmitRef.current = onSubmit;
   const clearOnSubmitRef = useRef(clearOnSubmit);
   clearOnSubmitRef.current = clearOnSubmit;
+  const onFocusRef = useRef(onFocus);
+  onFocusRef.current = onFocus;
+  const onBlurRef = useRef(onBlur);
+  onBlurRef.current = onBlur;
+  const submitKeyRef = useRef(submitKey);
+  submitKeyRef.current = submitKey;
+  const onMentionRemoveRef = useRef(onMentionRemove);
+  onMentionRemoveRef.current = onMentionRemove;
+  const onMentionClickRef = useRef(onMentionClick);
+  onMentionClickRef.current = onMentionClick;
+  const onMentionHoverRef = useRef(onMentionHover);
+  onMentionHoverRef.current = onMentionHover;
+  const allowTriggerRef = useRef(allowTrigger);
+  allowTriggerRef.current = allowTrigger;
+  const validateMentionRef = useRef(validateMention);
+  validateMentionRef.current = validateMention;
+  const onStreamingCompleteRef = useRef(onStreamingComplete);
+  onStreamingCompleteRef.current = onStreamingComplete;
+  const streamingRef = useRef(streaming);
+  streamingRef.current = streaming;
+  const prevStreamingRef = useRef(streaming);
+  const throttleTimerRef = useRef(null);
+  const pendingOutputRef = useRef(null);
+  const internalMarkdownRef = useRef(null);
   const initialContent = useMemo(() => {
     if (!value) return void 0;
     return parseFromMarkdown(value);
@@ -438,16 +647,36 @@ function useMentionsEditor({
     [triggersKey]
   );
   const suggestionExtension = useMemo(
-    () => createSuggestionExtension(triggers, callbacksRef),
+    () => createSuggestionExtension(
+      triggers,
+      callbacksRef,
+      allowTriggerRef,
+      streamingRef
+    ),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [triggersKey]
   );
   const submitExt = useMemo(
-    () => createSubmitExtension(onSubmitRef, clearOnSubmitRef),
+    () => createSubmitExtension(onSubmitRef, clearOnSubmitRef, submitKeyRef),
     []
   );
   const enterExt = useMemo(
-    () => createEnterExtension(onSubmitRef, clearOnSubmitRef),
+    () => createEnterExtension(onSubmitRef, clearOnSubmitRef, submitKeyRef),
+    []
+  );
+  const mentionRemoveExt = useMemo(
+    () => createMentionRemoveExtension(onMentionRemoveRef),
+    []
+  );
+  const streamingBlockExt = useMemo(
+    () => createStreamingBlockExtension(streamingRef),
+    []
+  );
+  const mentionNodeExt = useMemo(
+    () => MentionNode.configure({
+      onClickRef: onMentionClickRef,
+      onHoverRef: onMentionHoverRef
+    }),
     []
   );
   const editor = useEditor({
@@ -466,10 +695,12 @@ function useMentionsEditor({
         placeholder: ({ editor: editor2 }) => editor2.isEmpty ? placeholder ?? "Type a message..." : "",
         showOnlyCurrent: true
       }),
-      MentionNode,
+      mentionNodeExt,
       suggestionExtension,
       submitExt,
-      enterExt
+      enterExt,
+      mentionRemoveExt,
+      streamingBlockExt
     ],
     content: initialContent,
     autofocus: autoFocus ? "end" : false,
@@ -480,14 +711,85 @@ function useMentionsEditor({
       }
     },
     onUpdate: ({ editor: editor2 }) => {
-      onChangeRef.current?.(buildOutput(editor2));
+      const output = buildOutput(editor2);
+      internalMarkdownRef.current = output.markdown;
+      if (streamingRef.current) {
+        pendingOutputRef.current = output;
+        if (!throttleTimerRef.current) {
+          throttleTimerRef.current = setTimeout(() => {
+            throttleTimerRef.current = null;
+            if (pendingOutputRef.current) {
+              onChangeRef.current?.(pendingOutputRef.current);
+              pendingOutputRef.current = null;
+            }
+          }, 150);
+        }
+      } else {
+        onChangeRef.current?.(output);
+      }
+    },
+    onFocus: () => {
+      onFocusRef.current?.();
+    },
+    onBlur: () => {
+      onBlurRef.current?.();
     }
   });
+  useEffect(() => {
+    if (prevStreamingRef.current && !streaming && editor) {
+      if (throttleTimerRef.current) {
+        clearTimeout(throttleTimerRef.current);
+        throttleTimerRef.current = null;
+      }
+      const output = buildOutput(editor);
+      onChangeRef.current?.(output);
+      onStreamingCompleteRef.current?.(output);
+      pendingOutputRef.current = null;
+    }
+    prevStreamingRef.current = streaming;
+  }, [streaming, editor]);
+  useEffect(() => {
+    return () => {
+      if (throttleTimerRef.current) {
+        clearTimeout(throttleTimerRef.current);
+      }
+    };
+  }, []);
   useEffect(() => {
     if (editor && editor.isEditable !== editable) {
       editor.setEditable(editable);
     }
   }, [editor, editable]);
+  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]);
+  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 = useCallback(() => {
     editor?.commands.clearContent(true);
   }, [editor]);
@@ -496,6 +798,21 @@ function useMentionsEditor({
       if (!editor) return;
       const doc = parseFromMarkdown(markdown);
       editor.commands.setContent(doc);
+      internalMarkdownRef.current = markdown;
+      if (streamingRef.current) {
+        editor.commands.focus("end");
+      }
+    },
+    [editor]
+  );
+  const appendText = useCallback(
+    (text) => {
+      if (!editor) return;
+      const endPos = editor.state.doc.content.size - 1;
+      editor.commands.insertContentAt(endPos, text);
+      if (streamingRef.current) {
+        editor.commands.focus("end");
+      }
     },
     [editor]
   );
@@ -506,11 +823,32 @@ function useMentionsEditor({
     if (!editor) return null;
     return buildOutput(editor);
   }, [editor]);
-  return { editor, getOutput, clear, setContent, focus };
+  return { editor, getOutput, clear, setContent, appendText, focus };
+}
+
+// src/hooks/useSuggestion.ts
+import { useCallback as useCallback2, useEffect as useEffect2, useRef as useRef2, useState } from "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
-import { useCallback as useCallback2, useRef as useRef2, useState } from "react";
 var IDLE_STATE = {
   state: "idle",
   items: [],
@@ -521,16 +859,24 @@ var IDLE_STATE = {
   trigger: null,
   query: ""
 };
-function useSuggestion(providers) {
+function useSuggestion(providers, options = {}) {
   const [uiState, setUIState] = useState(IDLE_STATE);
   const stateRef = useRef2(uiState);
   stateRef.current = uiState;
   const providersRef = useRef2(providers);
   providersRef.current = providers;
+  const onMentionAddRef = useRef2(options.onMentionAdd);
+  onMentionAddRef.current = options.onMentionAdd;
   const commandRef = useRef2(
     null
   );
   const providerRef = useRef2(null);
+  const debouncedFetchRef = useRef2(null);
+  useEffect2(() => {
+    return () => {
+      debouncedFetchRef.current?.cancel();
+    };
+  }, []);
   const fetchItems = useCallback2(
     async (provider, query, parent, useSearchAll) => {
       setUIState((prev) => ({ ...prev, loading: true, state: "loading" }));
@@ -561,6 +907,23 @@ function useSuggestion(providers) {
     },
     []
   );
+  const scheduleFetch = useCallback2(
+    (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 = useCallback2(
     (props) => {
       const provider = providersRef.current.find(
@@ -579,13 +942,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 = useCallback2(
     (props) => {
@@ -609,14 +990,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 = useCallback2(() => {
+    debouncedFetchRef.current?.cancel();
     providerRef.current = null;
     commandRef.current = null;
     setUIState(IDLE_STATE);
@@ -651,8 +1049,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,
@@ -660,6 +1058,11 @@ function useSuggestion(providers) {
           rootLabel
         });
       }
+      onMentionAddRef.current?.({
+        id: selected.id,
+        type: selected.type,
+        label: selected.label
+      });
     },
     [fetchItems]
   );
@@ -684,6 +1087,7 @@ function useSuggestion(providers) {
     });
   }, [fetchItems]);
   const close = useCallback2(() => {
+    debouncedFetchRef.current?.cancel();
     setUIState(IDLE_STATE);
   }, []);
   const searchNested = useCallback2(
@@ -693,10 +1097,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 = useCallback2(
     ({ event }) => {
@@ -719,6 +1123,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) {
@@ -764,7 +1176,7 @@ function useSuggestion(providers) {
 }
 
 // src/components/SuggestionList.tsx
-import { useEffect as useEffect2, useRef as useRef3, useState as useState2 } from "react";
+import { useEffect as useEffect3, useRef as useRef3, useState as useState2 } from "react";
 
 // src/utils/ariaHelpers.ts
 function comboboxAttrs(expanded, listboxId) {
@@ -793,13 +1205,13 @@ function optionAttrs(id, selected, index) {
 
 // src/components/SuggestionList.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
-var LISTBOX_ID = "mentions-suggestion-listbox";
 function SuggestionList({
   items,
   activeIndex,
   breadcrumbs,
   loading,
   trigger,
+  query,
   clientRect,
   onSelect,
   onHover,
@@ -808,7 +1220,12 @@ function SuggestionList({
   onNavigateUp,
   onNavigateDown,
   onClose,
-  renderItem
+  onFocusEditor,
+  renderItem,
+  renderEmpty,
+  renderLoading,
+  renderGroupHeader,
+  listboxId
 }) {
   const listRef = useRef3(null);
   const searchInputRef = useRef3(null);
@@ -816,24 +1233,30 @@ function SuggestionList({
   const [nestedQuery, setNestedQuery] = useState2("");
   const breadcrumbKey = breadcrumbs.map((b) => b.id).join("/");
   const prevBreadcrumbKey = useRef3(breadcrumbKey);
-  useEffect2(() => {
+  useEffect3(() => {
     if (prevBreadcrumbKey.current !== breadcrumbKey) {
       setNestedQuery("");
       prevBreadcrumbKey.current = breadcrumbKey;
     }
   }, [breadcrumbKey]);
-  useEffect2(() => {
-    if (breadcrumbs.length > 0 && searchInputRef.current) {
+  const prevBreadcrumbsLen = useRef3(breadcrumbs.length);
+  useEffect3(() => {
+    if (prevBreadcrumbsLen.current > 0 && breadcrumbs.length === 0) {
+      onFocusEditor?.();
+    } else if (breadcrumbs.length > 0 && searchInputRef.current) {
       requestAnimationFrame(() => searchInputRef.current?.focus());
     }
-  }, [breadcrumbKey, breadcrumbs.length]);
-  useEffect2(() => {
+    prevBreadcrumbsLen.current = breadcrumbs.length;
+  }, [breadcrumbKey, breadcrumbs.length, onFocusEditor]);
+  useEffect3(() => {
     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":
@@ -853,8 +1276,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();
@@ -863,11 +1301,13 @@ function SuggestionList({
         break;
     }
   };
+  const hasGroups = items.some((item) => item.group);
   return /* @__PURE__ */ jsxs(
     "div",
     {
       "data-suggestions": "",
       "data-trigger": trigger,
+      "data-suggestions-position": position,
       style,
       ref: listRef,
       children: [
@@ -905,28 +1345,76 @@ function SuggestionList({
             spellCheck: false
           }
         ) }),
-        loading && /* @__PURE__ */ jsx("div", { "data-suggestion-loading": "", children: "Loading..." }),
-        !loading && /* @__PURE__ */ jsx("div", { ...listboxAttrs(LISTBOX_ID, `${trigger ?? ""} suggestions`), children: items.map((item, index) => {
-          const isActive = index === activeIndex;
-          const itemId = `mention-option-${item.id}`;
-          return /* @__PURE__ */ 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__ */ jsx(DefaultSuggestionItem, { item })
-            },
-            item.id
-          );
-        }) })
+        loading && /* @__PURE__ */ jsx("div", { "data-suggestion-loading": "", children: renderLoading ? renderLoading() : "Loading..." }),
+        showEmpty && /* @__PURE__ */ jsx("div", { "data-suggestion-empty": "", children: renderEmpty ? renderEmpty(activeQuery) : "No results" }),
+        !loading && items.length > 0 && /* @__PURE__ */ jsx("div", { ...listboxAttrs(listboxId, `${trigger ?? ""} suggestions`), children: hasGroups ? renderGroupedItems(items, activeIndex, depth, onSelect, onHover, renderItem, renderGroupHeader) : items.map((item, index) => /* @__PURE__ */ 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__ */ jsx("div", { "data-suggestion-group-header": "", children: renderGroupHeader ? renderGroupHeader(item.group) : item.group }, `group-${item.group}`)
+      );
+    }
+    elements.push(
+      /* @__PURE__ */ 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__ */ 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__ */ jsx(DefaultSuggestionItem, { item })
+    }
+  );
+}
 function DefaultSuggestionItem({ item }) {
   return /* @__PURE__ */ jsxs(Fragment, { children: [
     item.icon && /* @__PURE__ */ jsx("span", { "data-suggestion-item-icon": "", children: item.icon }),
@@ -935,25 +1423,48 @@ function DefaultSuggestionItem({ item }) {
     item.hasChildren && /* @__PURE__ */ 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
 import { jsx as jsx2, jsxs as jsxs2 } from "react/jsx-runtime";
-var LISTBOX_ID2 = "mentions-suggestion-listbox";
 var MentionsInput = forwardRef(
   function MentionsInput2({
     value,
@@ -967,10 +1478,31 @@ var MentionsInput = forwardRef(
     clearOnSubmit = true,
     maxLength,
     renderItem,
-    renderChip
+    renderChip,
+    renderEmpty,
+    renderLoading,
+    renderGroupHeader,
+    onFocus,
+    onBlur,
+    onMentionAdd,
+    onMentionRemove,
+    onMentionClick,
+    onMentionHover,
+    minHeight,
+    maxHeight,
+    submitKey = "enter",
+    allowTrigger,
+    validateMention,
+    portalContainer,
+    streaming,
+    onStreamingComplete
   }, ref) {
-    const { uiState, actions, callbacksRef } = useSuggestion(providers);
-    const { editor, clear, setContent, focus } = useMentionsEditor({
+    const instanceId = useId();
+    const listboxId = `mentions-listbox-${instanceId}`;
+    const { uiState, actions, callbacksRef } = useSuggestion(providers, {
+      onMentionAdd
+    });
+    const { editor, getOutput, clear, setContent, appendText, focus } = useMentionsEditor({
       providers,
       value,
       onChange,
@@ -979,46 +1511,72 @@ var MentionsInput = forwardRef(
       placeholder,
       autoFocus,
       editable: !disabled,
-      callbacksRef
+      callbacksRef,
+      onFocus,
+      onBlur,
+      submitKey,
+      onMentionRemove,
+      onMentionClick,
+      onMentionHover,
+      allowTrigger,
+      validateMention,
+      streaming,
+      onStreamingComplete
     });
     useImperativeHandle(
       ref,
-      () => ({ clear, setContent, focus }),
-      [clear, setContent, focus]
+      () => ({ clear, setContent, appendText, focus, getOutput }),
+      [clear, setContent, appendText, focus, getOutput]
     );
     const isExpanded = uiState.state !== "idle";
     const handleHover = useCallback3((index) => {
       void index;
     }, []);
+    const handleFocusEditor = useCallback3(() => {
+      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__ */ jsx2(
+      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__ */ jsxs2(
       "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__ */ jsx2(EditorContent, { editor }),
-          isExpanded && /* @__PURE__ */ jsx2(
-            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__ */ jsx2("div", { style: editorStyle, children: /* @__PURE__ */ jsx2(EditorContent, { editor }) }),
+          portalContainer ? suggestionList && createPortal(suggestionList, portalContainer) : suggestionList
         ]
       }
     );