@relevaince/mentions 0.5.0 → 0.6.1

package/README.md

@@ -13,6 +13,7 @@ This is **not** a simple `@mention` dropdown. It is a resource-addressing langua
 - **Async providers** — fetch suggestions from any API
 - **Debounced fetching** — per-provider `debounceMs` prevents API floods
 - **Structured output** — returns `{ markdown, tokens, plainText }` on every change
+- **`useMentionsContent`** — hook that pairs `onChange` with reactive `output` and `hasContent` (e.g. disable submit until there is text)
 - **Markdown serialization** — `@[label](id)` token syntax for storage and LLM context
 - **Markdown parsing** — `extractFromMarkdown()` returns tokens + plain text from a markdown string
 - **Headless styling** — zero bundled CSS, style via `data-*` attributes with Tailwind or plain CSS
@@ -31,6 +32,7 @@ This is **not** a simple `@mention` dropdown. It is a resource-addressing langua
 - **Portal support** — render the dropdown into a custom container
 - **Tab to complete** — Tab selects the active suggestion
 - **Trigger gating** — `allowTrigger` to conditionally suppress the dropdown
+- **Streaming support** — stream AI-generated text into the editor with automatic mention parsing
 - **Multi-instance** — unique ARIA IDs per component instance
 
 ## Install
@@ -192,6 +194,8 @@ type MentionsOutput = {
 | `allowTrigger` | `(trigger, { textBefore }) => boolean` | — | Conditionally suppress the dropdown |
 | `validateMention` | `(token) => boolean \| Promise<boolean>` | — | Validate mentions; invalid ones get `data-mention-invalid` |
 | `portalContainer` | `HTMLElement` | — | Render dropdown into a custom DOM node |
+| `streaming` | `boolean` | `false` | Signals the editor is receiving streamed content (suppresses triggers, blocks user input, throttles onChange) |
+| `onStreamingComplete` | `(output: MentionsOutput) => void` | — | Fires once when `streaming` transitions from `true` to `false` with the final output |
 
 ## Imperative ref API
 
@@ -228,9 +232,100 @@ function Chat() {
 |--------|-----------|-------------|
 | `clear` | `() => void` | Clears all editor content |
 | `setContent` | `(markdown: string) => void` | Replaces content with a markdown string (mention tokens are parsed) |
+| `appendText` | `(text: string) => void` | Appends plain text at the end (no mention parsing — use for plain-text streaming) |
 | `focus` | `() => void` | Focuses the editor and places the cursor at the end |
 | `getOutput` | `() => MentionsOutput \| null` | Reads the current structured output without waiting for onChange |
 
+## Hooks
+
+### `useMentionsContent`
+
+Keeps the latest `MentionsOutput` in React state so UI can react to editor content. `ref.current.getOutput()` does not trigger re-renders; this hook wires `onChange` for you and exposes `hasContent` from trimmed `plainText`.
+
+```ts
+function useMentionsContent(): {
+  output: MentionsOutput | null;
+  onChange: (output: MentionsOutput) => void;
+  hasContent: boolean;
+};
+```
+
+**Submit button disabled when empty:**
+
+```tsx
+import { useRef } from "react";
+import {
+  MentionsInput,
+  useMentionsContent,
+  type MentionsInputHandle,
+} from "@relevaince/mentions";
+
+function Composer() {
+  const textareaRef = useRef<MentionsInputHandle>(null);
+  const { output, onChange, hasContent } = useMentionsContent();
+
+  function onSubmit() {
+    if (!output) return;
+    sendMessage(output);
+  }
+
+  return (
+    <>
+      <MentionsInput
+        ref={textareaRef}
+        providers={providers}
+        onChange={onChange}
+        onSubmit={onSubmit}
+      />
+      <button type="button" disabled={!hasContent} onClick={onSubmit}>
+        Send
+      </button>
+    </>
+  );
+}
+```
+
+## Streaming
+
+Stream AI-generated text into the editor while maintaining mention state. Set `streaming={true}` to enter streaming mode: the suggestion dropdown is suppressed, user keyboard/paste input is blocked, and `onChange` is throttled (~150 ms). Call `ref.current.setContent(accumulated)` on each chunk — completed mention tokens are parsed into chips automatically.
+
+```tsx
+const ref = useRef<MentionsInputHandle>(null);
+const [isStreaming, setIsStreaming] = useState(false);
+
+async function enhancePrompt() {
+  setIsStreaming(true);
+  let accumulated = "";
+
+  const stream = await fetchEnhancedPrompt(currentPrompt);
+  for await (const chunk of stream) {
+    accumulated += chunk;
+    ref.current?.setContent(accumulated);
+  }
+
+  setIsStreaming(false);
+}
+
+<MentionsInput
+  ref={ref}
+  streaming={isStreaming}
+  providers={providers}
+  onChange={handleChange}
+  onStreamingComplete={(output) => {
+    console.log("Final tokens:", output.tokens);
+  }}
+/>
+```
+
+**How it works:**
+
+1. Set `streaming={true}` — the editor enters streaming mode
+2. On each chunk, accumulate the full text and call `ref.current.setContent(accumulated)`
+3. Incomplete mention tokens (e.g. `@[NDA`) render as plain text until the full `@[label](id)` syntax is received, then snap into mention chips
+4. Set `streaming={false}` — the editor exits streaming mode, fires a final `onChange` and `onStreamingComplete`
+
+For plain-text-only streaming (no mention syntax in chunks), use `ref.current.appendText(chunk)` instead for better performance.
+
 ## Keyboard shortcuts
 
 | Key | Context | Action |

package/dist/index.d.mts

@@ -150,6 +150,17 @@ type MentionsInputProps = {
     validateMention?: (token: MentionToken) => boolean | Promise<boolean>;
     /** DOM element to portal the suggestion dropdown into. */
     portalContainer?: HTMLElement;
+    /**
+     * Signals the editor is receiving streamed content (e.g. from an AI).
+     * When `true`: suggestion triggers are suppressed, user keyboard/paste
+     * input is blocked, and `onChange` is throttled (~150 ms).
+     */
+    streaming?: boolean;
+    /**
+     * Fires once when `streaming` transitions from `true` to `false`
+     * with the final structured output.
+     */
+    onStreamingComplete?: (output: MentionsOutput) => void;
 };
 /**
  * Imperative handle exposed via `ref` on `<MentionsInput>`.
@@ -167,8 +178,10 @@ type MentionsInputProps = {
 type MentionsInputHandle = {
     /** Clear all editor content. */
     clear: () => void;
-    /** Replace editor content with a markdown string. */
+    /** Replace editor content with a markdown string. Mention tokens are parsed. */
     setContent: (markdown: string) => void;
+    /** Append plain text at the end of the document (no mention parsing). */
+    appendText: (text: string) => void;
     /** Focus the editor. */
     focus: () => void;
     /** Read the current structured output without waiting for onChange. */
@@ -184,6 +197,12 @@ type MentionsInputHandle = {
  */
 declare const MentionsInput: React.ForwardRefExoticComponent<MentionsInputProps & React.RefAttributes<MentionsInputHandle>>;
 
+declare function useMentionsContent(): {
+    output: MentionsOutput | null;
+    onChange: (o: MentionsOutput) => void;
+    hasContent: boolean;
+};
+
 /**
  * Serialize a Tiptap JSON document to a markdown string.
  *
@@ -217,4 +236,4 @@ declare function extractFromMarkdown(markdown: string): {
     plainText: string;
 };
 
-export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputHandle, type MentionsInputProps, type MentionsOutput, extractFromMarkdown, parseFromMarkdown, serializeToMarkdown };
+export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputHandle, type MentionsInputProps, type MentionsOutput, extractFromMarkdown, parseFromMarkdown, serializeToMarkdown, useMentionsContent };

package/dist/index.d.ts

@@ -150,6 +150,17 @@ type MentionsInputProps = {
     validateMention?: (token: MentionToken) => boolean | Promise<boolean>;
     /** DOM element to portal the suggestion dropdown into. */
     portalContainer?: HTMLElement;
+    /**
+     * Signals the editor is receiving streamed content (e.g. from an AI).
+     * When `true`: suggestion triggers are suppressed, user keyboard/paste
+     * input is blocked, and `onChange` is throttled (~150 ms).
+     */
+    streaming?: boolean;
+    /**
+     * Fires once when `streaming` transitions from `true` to `false`
+     * with the final structured output.
+     */
+    onStreamingComplete?: (output: MentionsOutput) => void;
 };
 /**
  * Imperative handle exposed via `ref` on `<MentionsInput>`.
@@ -167,8 +178,10 @@ type MentionsInputProps = {
 type MentionsInputHandle = {
     /** Clear all editor content. */
     clear: () => void;
-    /** Replace editor content with a markdown string. */
+    /** Replace editor content with a markdown string. Mention tokens are parsed. */
     setContent: (markdown: string) => void;
+    /** Append plain text at the end of the document (no mention parsing). */
+    appendText: (text: string) => void;
     /** Focus the editor. */
     focus: () => void;
     /** Read the current structured output without waiting for onChange. */
@@ -184,6 +197,12 @@ type MentionsInputHandle = {
  */
 declare const MentionsInput: React.ForwardRefExoticComponent<MentionsInputProps & React.RefAttributes<MentionsInputHandle>>;
 
+declare function useMentionsContent(): {
+    output: MentionsOutput | null;
+    onChange: (o: MentionsOutput) => void;
+    hasContent: boolean;
+};
+
 /**
  * Serialize a Tiptap JSON document to a markdown string.
  *
@@ -217,4 +236,4 @@ declare function extractFromMarkdown(markdown: string): {
     plainText: string;
 };
 
-export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputHandle, type MentionsInputProps, type MentionsOutput, extractFromMarkdown, parseFromMarkdown, serializeToMarkdown };
+export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputHandle, type MentionsInputProps, type MentionsOutput, extractFromMarkdown, parseFromMarkdown, serializeToMarkdown, useMentionsContent };

package/dist/index.js

@@ -33,7 +33,8 @@ __export(index_exports, {
   MentionsInput: () => MentionsInput,
   extractFromMarkdown: () => extractFromMarkdown,
   parseFromMarkdown: () => parseFromMarkdown,
-  serializeToMarkdown: () => serializeToMarkdown
+  serializeToMarkdown: () => serializeToMarkdown,
+  useMentionsContent: () => useMentionsContent
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -222,7 +223,7 @@ function detectTrigger(text, cursorPos, docStartPos, triggers) {
   return null;
 }
 var suggestionPluginKey = new import_state.PluginKey("mentionSuggestion");
-function createSuggestionExtension(triggers, callbacksRef, allowTriggerRef) {
+function createSuggestionExtension(triggers, callbacksRef, allowTriggerRef, streamingRef) {
   return import_core2.Extension.create({
     name: "mentionSuggestion",
     priority: 200,
@@ -273,6 +274,15 @@ function createSuggestionExtension(triggers, callbacksRef, allowTriggerRef) {
         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) {
@@ -587,6 +597,34 @@ function createMentionRemoveExtension(onMentionRemoveRef) {
     }
   });
 }
+var streamingBlockPluginKey = new import_state2.PluginKey("streamingBlock");
+function createStreamingBlockExtension(streamingRef) {
+  return import_core3.Extension.create({
+    name: "streamingBlock",
+    priority: 200,
+    addProseMirrorPlugins() {
+      return [
+        new import_state2.Plugin({
+          key: streamingBlockPluginKey,
+          props: {
+            handleKeyDown() {
+              return streamingRef.current;
+            },
+            handleKeyPress() {
+              return streamingRef.current;
+            },
+            handlePaste() {
+              return streamingRef.current;
+            },
+            handleDrop() {
+              return streamingRef.current;
+            }
+          }
+        })
+      ];
+    }
+  });
+}
 function useMentionsEditor({
   providers,
   value,
@@ -604,7 +642,9 @@ function useMentionsEditor({
   onMentionClick,
   onMentionHover,
   allowTrigger,
-  validateMention
+  validateMention,
+  streaming = false,
+  onStreamingComplete
 }) {
   const onChangeRef = (0, import_react.useRef)(onChange);
   onChangeRef.current = onChange;
@@ -628,6 +668,13 @@ function useMentionsEditor({
   allowTriggerRef.current = allowTrigger;
   const validateMentionRef = (0, import_react.useRef)(validateMention);
   validateMentionRef.current = validateMention;
+  const onStreamingCompleteRef = (0, import_react.useRef)(onStreamingComplete);
+  onStreamingCompleteRef.current = onStreamingComplete;
+  const streamingRef = (0, import_react.useRef)(streaming);
+  streamingRef.current = streaming;
+  const prevStreamingRef = (0, import_react.useRef)(streaming);
+  const throttleTimerRef = (0, import_react.useRef)(null);
+  const pendingOutputRef = (0, import_react.useRef)(null);
   const internalMarkdownRef = (0, import_react.useRef)(null);
   const initialContent = (0, import_react.useMemo)(() => {
     if (!value) return void 0;
@@ -640,7 +687,12 @@ function useMentionsEditor({
     [triggersKey]
   );
   const suggestionExtension = (0, import_react.useMemo)(
-    () => createSuggestionExtension(triggers, callbacksRef, allowTriggerRef),
+    () => createSuggestionExtension(
+      triggers,
+      callbacksRef,
+      allowTriggerRef,
+      streamingRef
+    ),
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [triggersKey]
   );
@@ -656,6 +708,10 @@ function useMentionsEditor({
     () => createMentionRemoveExtension(onMentionRemoveRef),
     []
   );
+  const streamingBlockExt = (0, import_react.useMemo)(
+    () => createStreamingBlockExtension(streamingRef),
+    []
+  );
   const mentionNodeExt = (0, import_react.useMemo)(
     () => MentionNode.configure({
       onClickRef: onMentionClickRef,
@@ -683,7 +739,8 @@ function useMentionsEditor({
       suggestionExtension,
       submitExt,
       enterExt,
-      mentionRemoveExt
+      mentionRemoveExt,
+      streamingBlockExt
     ],
     content: initialContent,
     autofocus: autoFocus ? "end" : false,
@@ -696,7 +753,20 @@ function useMentionsEditor({
     onUpdate: ({ editor: editor2 }) => {
       const output = buildOutput(editor2);
       internalMarkdownRef.current = output.markdown;
-      onChangeRef.current?.(output);
+      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?.();
@@ -705,6 +775,26 @@ function useMentionsEditor({
       onBlurRef.current?.();
     }
   });
+  (0, import_react.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]);
+  (0, import_react.useEffect)(() => {
+    return () => {
+      if (throttleTimerRef.current) {
+        clearTimeout(throttleTimerRef.current);
+      }
+    };
+  }, []);
   (0, import_react.useEffect)(() => {
     if (editor && editor.isEditable !== editable) {
       editor.setEditable(editable);
@@ -749,6 +839,20 @@ function useMentionsEditor({
       const doc = parseFromMarkdown(markdown);
       editor.commands.setContent(doc);
       internalMarkdownRef.current = markdown;
+      if (streamingRef.current) {
+        editor.commands.focus("end");
+      }
+    },
+    [editor]
+  );
+  const appendText = (0, import_react.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]
   );
@@ -759,7 +863,7 @@ 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
@@ -1429,14 +1533,16 @@ var MentionsInput = (0, import_react5.forwardRef)(
     submitKey = "enter",
     allowTrigger,
     validateMention,
-    portalContainer
+    portalContainer,
+    streaming,
+    onStreamingComplete
   }, ref) {
     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({
+    const { editor, getOutput, clear, setContent, appendText, focus } = useMentionsEditor({
       providers,
       value,
       onChange,
@@ -1453,12 +1559,14 @@ var MentionsInput = (0, import_react5.forwardRef)(
       onMentionClick,
       onMentionHover,
       allowTrigger,
-      validateMention
+      validateMention,
+      streaming,
+      onStreamingComplete
     });
     (0, import_react5.useImperativeHandle)(
       ref,
-      () => ({ clear, setContent, focus, getOutput }),
-      [clear, setContent, focus, getOutput]
+      () => ({ clear, setContent, appendText, focus, getOutput }),
+      [clear, setContent, appendText, focus, getOutput]
     );
     const isExpanded = uiState.state !== "idle";
     const handleHover = (0, import_react5.useCallback)((index) => {
@@ -1514,11 +1622,24 @@ var MentionsInput = (0, import_react5.forwardRef)(
     );
   }
 );
+
+// src/hooks/useMentionsContent.ts
+var import_react7 = require("react");
+function useMentionsContent() {
+  const [output, setOutput] = (0, import_react7.useState)(null);
+  const onChange = (0, import_react7.useCallback)((o) => setOutput(o), []);
+  return {
+    output,
+    onChange,
+    hasContent: (output?.plainText ?? "").trim().length > 0
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MentionsInput,
   extractFromMarkdown,
   parseFromMarkdown,
-  serializeToMarkdown
+  serializeToMarkdown,
+  useMentionsContent
 });
 //# sourceMappingURL=index.js.map