@relevaince/mentions 0.1.0 → 0.2.1

package/README.md

@@ -131,8 +131,59 @@ type MentionsOutput = {
 | `className` | `string` | — | CSS class on the wrapper |
 | `maxLength` | `number` | — | Max plain text character count |
 | `renderItem` | `(item, depth) => ReactNode` | — | Custom suggestion item renderer |
+| `clearOnSubmit` | `boolean` | `true` | Auto-clear the editor after `onSubmit` fires |
+| `renderItem` | `(item, depth) => ReactNode` | — | Custom suggestion item renderer |
 | `renderChip` | `(token) => ReactNode` | — | Custom inline mention chip renderer |
 
+## Imperative ref API
+
+`MentionsInput` supports `forwardRef` for programmatic control. This is essential for flows like clearing after submit, injecting prompts from a library, or "Enhance Prompt" features.
+
+```tsx
+import { useRef } from "react";
+import { MentionsInput, type MentionsInputHandle } from "@relevaince/mentions";
+
+function Chat() {
+  const ref = useRef<MentionsInputHandle>(null);
+
+  return (
+    <>
+      <MentionsInput ref={ref} providers={providers} />
+
+      <button onClick={() => ref.current?.clear()}>
+        Clear
+      </button>
+
+      <button onClick={() => {
+        ref.current?.setContent("Summarize @[NDA](contract:c_1) risks");
+        ref.current?.focus();
+      }}>
+        Use Prompt
+      </button>
+    </>
+  );
+}
+```
+
+### Handle methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `clear` | `() => void` | Clears all editor content |
+| `setContent` | `(markdown: string) => void` | Replaces content with a markdown string (mention tokens are parsed) |
+| `focus` | `() => void` | Focuses the editor and places the cursor at the end |
+
+### Auto-clear on submit
+
+By default, the editor clears itself after `onSubmit` fires. Disable with `clearOnSubmit={false}` if you want to manage clearing yourself:
+
+```tsx
+<MentionsInput
+  onSubmit={(output) => sendMessage(output)}
+  clearOnSubmit={false}  // don't auto-clear
+/>
+```
+
 ## Nested mentions
 
 The killer feature. When a `MentionItem` has `hasChildren: true`, selecting it drills into the next level using `provider.getChildren()`:

package/dist/index.d.mts

@@ -1,5 +1,4 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
+import React, { ReactNode } from 'react';
 import { JSONContent } from '@tiptap/core';
 
 /**
@@ -93,6 +92,8 @@ type MentionsInputProps = {
     className?: string;
     /** Called when the user presses Enter (or Cmd+Enter). */
     onSubmit?: (output: MentionsOutput) => void;
+    /** Automatically clear the editor after `onSubmit` fires. Defaults to `true`. */
+    clearOnSubmit?: boolean;
     /** Maximum character count (plain text length). */
     maxLength?: number;
     /** Custom renderer for suggestion list items. */
@@ -100,6 +101,26 @@ type MentionsInputProps = {
     /** Custom renderer for inline mention chips. */
     renderChip?: (token: MentionToken) => ReactNode;
 };
+/**
+ * Imperative handle exposed via `ref` on `<MentionsInput>`.
+ *
+ * ```tsx
+ * const ref = useRef<MentionsInputHandle>(null);
+ * <MentionsInput ref={ref} ... />
+ *
+ * ref.current.clear();
+ * ref.current.setContent("Hello @[Marketing](ws_123)");
+ * ref.current.focus();
+ * ```
+ */
+type MentionsInputHandle = {
+    /** Clear all editor content. */
+    clear: () => void;
+    /** Replace editor content with a markdown string. */
+    setContent: (markdown: string) => void;
+    /** Focus the editor. */
+    focus: () => void;
+};
 
 /**
  * `<MentionsInput>` — the single public component.
@@ -107,8 +128,16 @@ type MentionsInputProps = {
  * A structured text editor with typed entity tokens.
  * Consumers register `providers` for each trigger character,
  * and receive structured output via `onChange` and `onSubmit`.
+ *
+ * Supports an imperative ref handle for programmatic control:
+ * ```tsx
+ * const ref = useRef<MentionsInputHandle>(null);
+ * ref.current.clear();
+ * ref.current.setContent("@[Marketing](ws_123) summarize");
+ * ref.current.focus();
+ * ```
  */
-declare function MentionsInput({ value, providers, onChange, placeholder, autoFocus, disabled, className, onSubmit, maxLength, renderItem, renderChip, }: MentionsInputProps): react_jsx_runtime.JSX.Element;
+declare const MentionsInput: React.ForwardRefExoticComponent<MentionsInputProps & React.RefAttributes<MentionsInputHandle>>;
 
 /**
  * Serialize a Tiptap JSON document to a markdown string.
@@ -124,4 +153,4 @@ declare function serializeToMarkdown(doc: JSONContent): string;
  */
 declare function parseFromMarkdown(markdown: string): JSONContent;
 
-export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputProps, type MentionsOutput, parseFromMarkdown, serializeToMarkdown };
+export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputHandle, type MentionsInputProps, type MentionsOutput, parseFromMarkdown, serializeToMarkdown };

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
+import React, { ReactNode } from 'react';
 import { JSONContent } from '@tiptap/core';
 
 /**
@@ -93,6 +92,8 @@ type MentionsInputProps = {
     className?: string;
     /** Called when the user presses Enter (or Cmd+Enter). */
     onSubmit?: (output: MentionsOutput) => void;
+    /** Automatically clear the editor after `onSubmit` fires. Defaults to `true`. */
+    clearOnSubmit?: boolean;
     /** Maximum character count (plain text length). */
     maxLength?: number;
     /** Custom renderer for suggestion list items. */
@@ -100,6 +101,26 @@ type MentionsInputProps = {
     /** Custom renderer for inline mention chips. */
     renderChip?: (token: MentionToken) => ReactNode;
 };
+/**
+ * Imperative handle exposed via `ref` on `<MentionsInput>`.
+ *
+ * ```tsx
+ * const ref = useRef<MentionsInputHandle>(null);
+ * <MentionsInput ref={ref} ... />
+ *
+ * ref.current.clear();
+ * ref.current.setContent("Hello @[Marketing](ws_123)");
+ * ref.current.focus();
+ * ```
+ */
+type MentionsInputHandle = {
+    /** Clear all editor content. */
+    clear: () => void;
+    /** Replace editor content with a markdown string. */
+    setContent: (markdown: string) => void;
+    /** Focus the editor. */
+    focus: () => void;
+};
 
 /**
  * `<MentionsInput>` — the single public component.
@@ -107,8 +128,16 @@ type MentionsInputProps = {
  * A structured text editor with typed entity tokens.
  * Consumers register `providers` for each trigger character,
  * and receive structured output via `onChange` and `onSubmit`.
+ *
+ * Supports an imperative ref handle for programmatic control:
+ * ```tsx
+ * const ref = useRef<MentionsInputHandle>(null);
+ * ref.current.clear();
+ * ref.current.setContent("@[Marketing](ws_123) summarize");
+ * ref.current.focus();
+ * ```
  */
-declare function MentionsInput({ value, providers, onChange, placeholder, autoFocus, disabled, className, onSubmit, maxLength, renderItem, renderChip, }: MentionsInputProps): react_jsx_runtime.JSX.Element;
+declare const MentionsInput: React.ForwardRefExoticComponent<MentionsInputProps & React.RefAttributes<MentionsInputHandle>>;
 
 /**
  * Serialize a Tiptap JSON document to a markdown string.
@@ -124,4 +153,4 @@ declare function serializeToMarkdown(doc: JSONContent): string;
  */
 declare function parseFromMarkdown(markdown: string): JSONContent;
 
-export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputProps, type MentionsOutput, parseFromMarkdown, serializeToMarkdown };
+export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputHandle, type MentionsInputProps, type MentionsOutput, parseFromMarkdown, serializeToMarkdown };

package/dist/index.js

@@ -44,6 +44,7 @@ var import_react6 = require("@tiptap/react");
 var import_react = require("react");
 var import_react2 = require("@tiptap/react");
 var import_starter_kit = __toESM(require("@tiptap/starter-kit"));
+var import_extension_placeholder = __toESM(require("@tiptap/extension-placeholder"));
 var import_core3 = require("@tiptap/core");
 
 // src/core/mentionExtension.ts
@@ -369,19 +370,25 @@ function parseLine(line) {
 }
 
 // src/hooks/useMentionsEditor.ts
-function createSubmitExtension(onSubmitRef) {
+function buildOutput(editor) {
+  const json = editor.getJSON();
+  return {
+    markdown: serializeToMarkdown(json),
+    tokens: extractTokens(json),
+    plainText: extractPlainText(json)
+  };
+}
+function createSubmitExtension(onSubmitRef, clearOnSubmitRef) {
   return import_core3.Extension.create({
     name: "submitShortcut",
     addKeyboardShortcuts() {
       return {
         "Mod-Enter": () => {
           if (onSubmitRef.current) {
-            const json = this.editor.getJSON();
-            onSubmitRef.current({
-              markdown: serializeToMarkdown(json),
-              tokens: extractTokens(json),
-              plainText: extractPlainText(json)
-            });
+            onSubmitRef.current(buildOutput(this.editor));
+            if (clearOnSubmitRef.current) {
+              this.editor.commands.clearContent(true);
+            }
           }
           return true;
         }
@@ -389,7 +396,7 @@ function createSubmitExtension(onSubmitRef) {
     }
   });
 }
-function createEnterExtension(onSubmitRef) {
+function createEnterExtension(onSubmitRef, clearOnSubmitRef) {
   return import_core3.Extension.create({
     name: "enterSubmit",
     priority: 50,
@@ -397,12 +404,10 @@ function createEnterExtension(onSubmitRef) {
       return {
         Enter: () => {
           if (onSubmitRef.current) {
-            const json = this.editor.getJSON();
-            onSubmitRef.current({
-              markdown: serializeToMarkdown(json),
-              tokens: extractTokens(json),
-              plainText: extractPlainText(json)
-            });
+            onSubmitRef.current(buildOutput(this.editor));
+            if (clearOnSubmitRef.current) {
+              this.editor.commands.clearContent(true);
+            }
           }
           return true;
         }
@@ -415,6 +420,7 @@ function useMentionsEditor({
   value,
   onChange,
   onSubmit,
+  clearOnSubmit = true,
   placeholder,
   autoFocus = false,
   editable = true,
@@ -424,6 +430,8 @@ function useMentionsEditor({
   onChangeRef.current = onChange;
   const onSubmitRef = (0, import_react.useRef)(onSubmit);
   onSubmitRef.current = onSubmit;
+  const clearOnSubmitRef = (0, import_react.useRef)(clearOnSubmit);
+  clearOnSubmitRef.current = clearOnSubmit;
   const initialContent = (0, import_react.useMemo)(() => {
     if (!value) return void 0;
     return parseFromMarkdown(value);
@@ -439,8 +447,14 @@ function useMentionsEditor({
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [triggersKey]
   );
-  const submitExt = (0, import_react.useMemo)(() => createSubmitExtension(onSubmitRef), []);
-  const enterExt = (0, import_react.useMemo)(() => createEnterExtension(onSubmitRef), []);
+  const submitExt = (0, import_react.useMemo)(
+    () => createSubmitExtension(onSubmitRef, clearOnSubmitRef),
+    []
+  );
+  const enterExt = (0, import_react.useMemo)(
+    () => createEnterExtension(onSubmitRef, clearOnSubmitRef),
+    []
+  );
   const editor = (0, import_react2.useEditor)({
     extensions: [
       import_starter_kit.default.configure({
@@ -452,6 +466,9 @@ function useMentionsEditor({
         listItem: false,
         horizontalRule: false
       }),
+      import_extension_placeholder.default.configure({
+        placeholder: placeholder ?? "Type a message..."
+      }),
       MentionNode,
       suggestionExtension,
       submitExt,
@@ -462,17 +479,11 @@ function useMentionsEditor({
     editable,
     editorProps: {
       attributes: {
-        "data-placeholder": placeholder ?? "",
         class: "mentions-editor"
       }
     },
     onUpdate: ({ editor: editor2 }) => {
-      const json = editor2.getJSON();
-      onChangeRef.current?.({
-        markdown: serializeToMarkdown(json),
-        tokens: extractTokens(json),
-        plainText: extractPlainText(json)
-      });
+      onChangeRef.current?.(buildOutput(editor2));
     }
   });
   (0, import_react.useEffect)(() => {
@@ -480,16 +491,25 @@ function useMentionsEditor({
       editor.setEditable(editable);
     }
   }, [editor, editable]);
+  const clear = (0, import_react.useCallback)(() => {
+    editor?.commands.clearContent(true);
+  }, [editor]);
+  const setContent = (0, import_react.useCallback)(
+    (markdown) => {
+      if (!editor) return;
+      const doc = parseFromMarkdown(markdown);
+      editor.commands.setContent(doc);
+    },
+    [editor]
+  );
+  const focus = (0, import_react.useCallback)(() => {
+    editor?.commands.focus("end");
+  }, [editor]);
   const getOutput = (0, import_react.useCallback)(() => {
     if (!editor) return null;
-    const json = editor.getJSON();
-    return {
-      markdown: serializeToMarkdown(json),
-      tokens: extractTokens(json),
-      plainText: extractPlainText(json)
-    };
+    return buildOutput(editor);
   }, [editor]);
-  return { editor, getOutput };
+  return { editor, getOutput, clear, setContent, focus };
 }
 
 // src/hooks/useSuggestion.ts
@@ -832,62 +852,71 @@ function usePopoverPosition(clientRect) {
 // src/components/MentionsInput.tsx
 var import_jsx_runtime2 = require("react/jsx-runtime");
 var LISTBOX_ID2 = "mentions-suggestion-listbox";
-function MentionsInput({
-  value,
-  providers,
-  onChange,
-  placeholder = "Type a message...",
-  autoFocus = false,
-  disabled = false,
-  className,
-  onSubmit,
-  maxLength,
-  renderItem,
-  renderChip
-}) {
-  const { uiState, actions, callbacksRef } = useSuggestion(providers);
-  const { editor } = useMentionsEditor({
-    providers,
+var MentionsInput = (0, import_react5.forwardRef)(
+  function MentionsInput2({
     value,
+    providers,
     onChange,
+    placeholder = "Type a message...",
+    autoFocus = false,
+    disabled = false,
+    className,
     onSubmit,
-    placeholder,
-    autoFocus,
-    editable: !disabled,
-    callbacksRef
-  });
-  const isExpanded = uiState.state !== "idle";
-  const handleHover = (0, import_react5.useCallback)((index) => {
-  }, []);
-  return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
-    "div",
-    {
-      className,
-      "data-mentions-input": "",
-      "data-disabled": disabled ? "" : void 0,
-      ...comboboxAttrs(isExpanded, LISTBOX_ID2),
-      "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,
-            renderItem
-          }
-        )
-      ]
-    }
-  );
-}
+    clearOnSubmit = true,
+    maxLength,
+    renderItem,
+    renderChip
+  }, ref) {
+    const { uiState, actions, callbacksRef } = useSuggestion(providers);
+    const { editor, clear, setContent, focus } = useMentionsEditor({
+      providers,
+      value,
+      onChange,
+      onSubmit,
+      clearOnSubmit,
+      placeholder,
+      autoFocus,
+      editable: !disabled,
+      callbacksRef
+    });
+    (0, import_react5.useImperativeHandle)(
+      ref,
+      () => ({ clear, setContent, focus }),
+      [clear, setContent, focus]
+    );
+    const isExpanded = uiState.state !== "idle";
+    const handleHover = (0, import_react5.useCallback)((_index) => {
+    }, []);
+    return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
+      "div",
+      {
+        className,
+        "data-mentions-input": "",
+        "data-disabled": disabled ? "" : void 0,
+        ...comboboxAttrs(isExpanded, LISTBOX_ID2),
+        "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,
+              renderItem
+            }
+          )
+        ]
+      }
+    );
+  }
+);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MentionsInput,