@relevaince/mentions 0.2.2 → 0.3.0

package/README.md

@@ -8,9 +8,12 @@ This is **not** a simple `@mention` dropdown. It is a resource-addressing langua
 
 - **Multiple trigger characters** — `@`, `#`, `:`, or any custom trigger
 - **Nested suggestions** — drill into workspaces, then pick a file inside
+- **Cross-group search** — `searchAll` finds items across every level with a single query
+- **Nested search** — search input inside the dropdown to filter children in real time
 - **Async providers** — fetch suggestions from any API
 - **Structured output** — returns `{ markdown, tokens, plainText }` on every change
 - **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
 - **Accessible** — full ARIA combobox pattern with keyboard navigation
 - **SSR compatible** — safe for Next.js with `"use client"` directive
@@ -78,7 +81,7 @@ type MentionToken = {
 
 ### MentionProvider
 
-Register one provider per trigger character. Each provider fetches suggestions and optionally supports nested drill-down:
+Register one provider per trigger character. Each provider fetches suggestions and optionally supports nested drill-down and cross-group search:
 
 ```ts
 type MentionProvider = {
@@ -86,9 +89,12 @@ type MentionProvider = {
   name: string;                                               // human label
   getRootItems: (query: string) => Promise<MentionItem[]>;
   getChildren?: (parent: MentionItem, query: string) => Promise<MentionItem[]>;
+  searchAll?: (query: string) => Promise<MentionItem[]>;      // flat search across all levels
 };
 ```
 
+When `searchAll` is provided, typing a non-empty query at the root level will call `searchAll` instead of `getRootItems`, returning a flat list of results from every level (root items and their children).
+
 ### MentionItem
 
 Items returned by providers:
@@ -102,9 +108,12 @@ type MentionItem = {
   description?: string;    // secondary text
   hasChildren?: boolean;   // when true, selecting drills into a child level
   data?: unknown;
+  rootLabel?: string;      // parent label for flat search results (used in serialization)
 };
 ```
 
+Set `rootLabel` on items returned by `searchAll` that originate from a nested level. This ensures correct `@rootLabel[label](id)` serialization.
+
 ### MentionsOutput
 
 Structured output returned on every change and submit:
@@ -124,7 +133,7 @@ type MentionsOutput = {
 | `value` | `string` | — | Initial markdown content with `@[label](id)` tokens |
 | `providers` | `MentionProvider[]` | **required** | Suggestion providers, one per trigger |
 | `onChange` | `(output: MentionsOutput) => void` | — | Called on every content change |
-| `onSubmit` | `(output: MentionsOutput) => void` | — | Called on Enter / Cmd+Enter |
+| `onSubmit` | `(output: MentionsOutput) => void` | — | Called on Enter or Cmd+Enter |
 | `placeholder` | `string` | `"Type a message..."` | Placeholder text |
 | `autoFocus` | `boolean` | `false` | Focus editor on mount |
 | `disabled` | `boolean` | `false` | Disable editing |
@@ -132,7 +141,6 @@ type MentionsOutput = {
 | `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
@@ -194,14 +202,21 @@ The killer feature. When a `MentionItem` has `hasChildren: true`, selecting it d
 :web       → choose provider  → type query
 ```
 
+When inside a nested level, a search input appears in the dropdown. Type to filter children in real time. Press `Backspace` on an empty search input to go back one level.
+
 Keyboard navigation:
 
-| Key | Action |
-|-----|--------|
-| `↑` `↓` | Navigate suggestions |
-| `Enter` `→` | Select / drill into children |
-| `←` `Backspace` | Go back one level |
-| `Escape` | Close suggestions |
+| Key | Context | Action |
+|-----|---------|--------|
+| `↑` `↓` | Suggestions open | Navigate suggestions |
+| `Enter` | Suggestions open | Select / drill into children |
+| `→` | Suggestions open | Drill into children (if item has children) |
+| `←` | Nested level | Go back one level |
+| `Backspace` | Nested level, empty search | Go back one level |
+| `Escape` | Suggestions open | Close suggestions |
+| `Enter` | Editor (no suggestions) | Submit message |
+| `Shift+Enter` | Editor | New line |
+| `Cmd/Ctrl+Enter` | Editor | Submit message |
 
 ## Markdown format
 
@@ -214,13 +229,24 @@ Mentions serialize to a compact token syntax:
 Use the standalone helpers for server-side processing:
 
 ```ts
-import { serializeToMarkdown, parseFromMarkdown } from "@relevaince/mentions";
+import {
+  serializeToMarkdown,
+  parseFromMarkdown,
+  extractFromMarkdown,
+} from "@relevaince/mentions";
 
 // Parse markdown into a Tiptap-compatible JSON document
 const doc = parseFromMarkdown("Check @[NDA](contract:c_44) for risks");
 
 // Serialize a Tiptap JSON document back to markdown
 const md = serializeToMarkdown(doc);
+
+// Extract tokens and plain text directly from a markdown string
+const { tokens, plainText } = extractFromMarkdown(
+  "Summarize @Marketing[Q4 Strategy.pdf](file:file_1) for the team"
+);
+// tokens  → [{ id: "file_1", type: "file", label: "Q4 Strategy.pdf" }]
+// plainText → "Summarize Q4 Strategy.pdf for the team"
 ```
 
 ## Styling
@@ -238,6 +264,8 @@ Zero bundled CSS. Every element exposes `data-*` attributes for styling:
 [data-suggestion-item]              { /* each item */ }
 [data-suggestion-item-active]       { /* highlighted item */ }
 [data-suggestion-breadcrumb]        { /* breadcrumb bar (nested) */ }
+[data-suggestion-search]            { /* search input wrapper (nested) */ }
+[data-suggestion-search-input]      { /* search input field */ }
 [data-suggestion-loading]           { /* loading indicator */ }
 ```
 
@@ -269,9 +297,9 @@ Example with Tailwind:
   ├── Tiptap Editor (ProseMirror)
   │     ├── MentionNode Extension    — inline atom nodes with id/label/type
   │     ├── Suggestion Plugin        — multi-trigger detection + popover callbacks
-  │     ├── Submit Extension         — Enter / Cmd+Enter handling
-  │     └── Markdown Serializer      — doc ↔ @[label](id) format
-  └── SuggestionList (React)         — headless popover with ARIA
+  │     ├── Enter/Submit Extension   — Enter submits, Shift+Enter new line
+  │     └── Markdown Parser/Serializer — doc ↔ @[label](id) + extractFromMarkdown
+  └── SuggestionList (React)         — headless popover with ARIA + nested search
 ```
 
 Consumers interact with a single React component. Tiptap and ProseMirror are internal implementation details.

package/dist/index.d.mts

@@ -19,6 +19,12 @@ type MentionItem = {
     hasChildren?: boolean;
     /** Optional payload carried through to `MentionToken.data`. */
     data?: unknown;
+    /**
+     * Root parent label for items returned by `searchAll`.
+     * Used for correct `@rootLabel[label](id)` serialization when the
+     * item originates from a nested level.
+     */
+    rootLabel?: string;
 };
 /**
  * Hierarchical suggestion source registered per trigger character.
@@ -36,6 +42,12 @@ type MentionProvider = {
     getRootItems: (query: string) => Promise<MentionItem[]>;
     /** Fetch child suggestions when the user drills into `parent`. */
     getChildren?: (parent: MentionItem, query: string) => Promise<MentionItem[]>;
+    /**
+     * Flat search across **all** items, including nested children.
+     * When provided and the user types a non-empty query at root level,
+     * results from `searchAll` are shown instead of `getRootItems`.
+     */
+    searchAll?: (query: string) => Promise<MentionItem[]>;
 };
 
 /**
@@ -152,5 +164,24 @@ declare function serializeToMarkdown(doc: JSONContent): string;
  * into a Tiptap-compatible JSON document.
  */
 declare function parseFromMarkdown(markdown: string): JSONContent;
+/**
+ * Parse a markdown string and extract structured data from it.
+ *
+ * This is a convenience wrapper that combines `parseFromMarkdown`,
+ * `extractTokens`, and `extractPlainText` into a single call.
+ *
+ * @example
+ * ```ts
+ * const { tokens, plainText } = extractFromMarkdown(
+ *   "Check @Marketing[Q4 Strategy.pdf](file_1) for details"
+ * );
+ * // tokens → [{ id: "file_1", type: "unknown", label: "Q4 Strategy.pdf" }]
+ * // plainText → "Check Q4 Strategy.pdf for details"
+ * ```
+ */
+declare function extractFromMarkdown(markdown: string): {
+    tokens: MentionToken[];
+    plainText: string;
+};
 
-export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputHandle, type MentionsInputProps, type MentionsOutput, parseFromMarkdown, serializeToMarkdown };
+export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputHandle, type MentionsInputProps, type MentionsOutput, extractFromMarkdown, parseFromMarkdown, serializeToMarkdown };

package/dist/index.d.ts

@@ -19,6 +19,12 @@ type MentionItem = {
     hasChildren?: boolean;
     /** Optional payload carried through to `MentionToken.data`. */
     data?: unknown;
+    /**
+     * Root parent label for items returned by `searchAll`.
+     * Used for correct `@rootLabel[label](id)` serialization when the
+     * item originates from a nested level.
+     */
+    rootLabel?: string;
 };
 /**
  * Hierarchical suggestion source registered per trigger character.
@@ -36,6 +42,12 @@ type MentionProvider = {
     getRootItems: (query: string) => Promise<MentionItem[]>;
     /** Fetch child suggestions when the user drills into `parent`. */
     getChildren?: (parent: MentionItem, query: string) => Promise<MentionItem[]>;
+    /**
+     * Flat search across **all** items, including nested children.
+     * When provided and the user types a non-empty query at root level,
+     * results from `searchAll` are shown instead of `getRootItems`.
+     */
+    searchAll?: (query: string) => Promise<MentionItem[]>;
 };
 
 /**
@@ -152,5 +164,24 @@ declare function serializeToMarkdown(doc: JSONContent): string;
  * into a Tiptap-compatible JSON document.
  */
 declare function parseFromMarkdown(markdown: string): JSONContent;
+/**
+ * Parse a markdown string and extract structured data from it.
+ *
+ * This is a convenience wrapper that combines `parseFromMarkdown`,
+ * `extractTokens`, and `extractPlainText` into a single call.
+ *
+ * @example
+ * ```ts
+ * const { tokens, plainText } = extractFromMarkdown(
+ *   "Check @Marketing[Q4 Strategy.pdf](file_1) for details"
+ * );
+ * // tokens → [{ id: "file_1", type: "unknown", label: "Q4 Strategy.pdf" }]
+ * // plainText → "Check Q4 Strategy.pdf for details"
+ * ```
+ */
+declare function extractFromMarkdown(markdown: string): {
+    tokens: MentionToken[];
+    plainText: string;
+};
 
-export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputHandle, type MentionsInputProps, type MentionsOutput, parseFromMarkdown, serializeToMarkdown };
+export { type MentionItem, type MentionProvider, type MentionToken, MentionsInput, type MentionsInputHandle, type MentionsInputProps, type MentionsOutput, extractFromMarkdown, parseFromMarkdown, serializeToMarkdown };

package/dist/index.js

@@ -31,6 +31,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   MentionsInput: () => MentionsInput,
+  extractFromMarkdown: () => extractFromMarkdown,
   parseFromMarkdown: () => parseFromMarkdown,
   serializeToMarkdown: () => serializeToMarkdown
 });
@@ -46,6 +47,7 @@ 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");
+var import_state2 = require("@tiptap/pm/state");
 
 // src/core/mentionExtension.ts
 var import_core = require("@tiptap/core");
@@ -152,6 +154,7 @@ var suggestionPluginKey = new import_state.PluginKey("mentionSuggestion");
 function createSuggestionExtension(triggers, callbacksRef) {
   return import_core2.Extension.create({
     name: "mentionSuggestion",
+    priority: 200,
     addProseMirrorPlugins() {
       const editor = this.editor;
       let active = false;
@@ -380,6 +383,13 @@ function parseLine(line) {
   }
   return nodes;
 }
+function extractFromMarkdown(markdown) {
+  const doc = parseFromMarkdown(markdown);
+  return {
+    tokens: extractTokens(doc),
+    plainText: extractPlainText(doc)
+  };
+}
 
 // src/hooks/useMentionsEditor.ts
 function buildOutput(editor) {
@@ -393,6 +403,7 @@ function buildOutput(editor) {
 function createSubmitExtension(onSubmitRef, clearOnSubmitRef) {
   return import_core3.Extension.create({
     name: "submitShortcut",
+    priority: 150,
     addKeyboardShortcuts() {
       return {
         "Mod-Enter": () => {
@@ -408,22 +419,35 @@ function createSubmitExtension(onSubmitRef, clearOnSubmitRef) {
     }
   });
 }
+var enterSubmitPluginKey = new import_state2.PluginKey("enterSubmit");
 function createEnterExtension(onSubmitRef, clearOnSubmitRef) {
   return import_core3.Extension.create({
     name: "enterSubmit",
-    priority: 50,
-    addKeyboardShortcuts() {
-      return {
-        Enter: () => {
-          if (onSubmitRef.current) {
-            onSubmitRef.current(buildOutput(this.editor));
-            if (clearOnSubmitRef.current) {
-              this.editor.commands.clearContent(true);
+    priority: 150,
+    addProseMirrorPlugins() {
+      const editor = this.editor;
+      return [
+        new import_state2.Plugin({
+          key: enterSubmitPluginKey,
+          props: {
+            handleKeyDown(_view, event) {
+              if (event.key !== "Enter") return false;
+              if (event.shiftKey) {
+                editor.commands.splitBlock();
+                return true;
+              }
+              if (event.metaKey || event.ctrlKey) return false;
+              if (onSubmitRef.current) {
+                onSubmitRef.current(buildOutput(editor));
+                if (clearOnSubmitRef.current) {
+                  editor.commands.clearContent(true);
+                }
+              }
+              return true;
             }
           }
-          return true;
-        }
-      };
+        })
+      ];
     }
   });
 }
@@ -476,10 +500,12 @@ function useMentionsEditor({
         bulletList: false,
         orderedList: false,
         listItem: false,
-        horizontalRule: false
+        horizontalRule: false,
+        hardBreak: false
       }),
       import_extension_placeholder.default.configure({
-        placeholder: placeholder ?? "Type a message..."
+        placeholder: placeholder ?? "Type a message...",
+        showOnlyCurrent: false
       }),
       MentionNode,
       suggestionExtension,
@@ -547,10 +573,17 @@ function useSuggestion(providers) {
   );
   const providerRef = (0, import_react3.useRef)(null);
   const fetchItems = (0, import_react3.useCallback)(
-    async (provider, query, parent) => {
+    async (provider, query, parent, useSearchAll) => {
       setUIState((prev) => ({ ...prev, loading: true, state: "loading" }));
       try {
-        const items = parent && provider.getChildren ? await provider.getChildren(parent, query) : await provider.getRootItems(query);
+        let items;
+        if (useSearchAll && provider.searchAll) {
+          items = await provider.searchAll(query);
+        } else if (parent && provider.getChildren) {
+          items = await provider.getChildren(parent, query);
+        } else {
+          items = await provider.getRootItems(query);
+        }
         setUIState((prev) => ({
           ...prev,
           items,
@@ -587,7 +620,11 @@ function useSuggestion(providers) {
         trigger: props.trigger,
         query: props.query
       });
-      fetchItems(provider, props.query);
+      if (props.query.trim() && provider.searchAll) {
+        fetchItems(provider, props.query, void 0, true);
+      } else {
+        fetchItems(provider, props.query);
+      }
     },
     [fetchItems]
   );
@@ -596,12 +633,25 @@ function useSuggestion(providers) {
       const provider = providerRef.current;
       if (!provider) return;
       commandRef.current = props.command;
-      setUIState((prev) => ({
-        ...prev,
-        clientRect: props.clientRect,
-        query: props.query
-      }));
-      if (stateRef.current.breadcrumbs.length === 0) {
+      const current = stateRef.current;
+      if (current.breadcrumbs.length > 0) {
+        setUIState((prev) => ({
+          ...prev,
+          breadcrumbs: [],
+          clientRect: props.clientRect,
+          query: props.query,
+          activeIndex: 0
+        }));
+      } else {
+        setUIState((prev) => ({
+          ...prev,
+          clientRect: props.clientRect,
+          query: props.query
+        }));
+      }
+      if (props.query.trim() && provider.searchAll) {
+        fetchItems(provider, props.query, void 0, true);
+      } else {
         fetchItems(provider, props.query);
       }
     },
@@ -643,7 +693,7 @@ function useSuggestion(providers) {
         return;
       }
       if (commandRef.current) {
-        const rootLabel = current.breadcrumbs.length > 0 ? current.breadcrumbs[0].label : null;
+        const rootLabel = current.breadcrumbs.length > 0 ? current.breadcrumbs[0].label : selected.rootLabel ?? null;
         commandRef.current({
           id: selected.id,
           label: selected.label,
@@ -677,6 +727,18 @@ function useSuggestion(providers) {
   const close = (0, import_react3.useCallback)(() => {
     setUIState(IDLE_STATE);
   }, []);
+  const searchNested = (0, import_react3.useCallback)(
+    (query) => {
+      const provider = providerRef.current;
+      if (!provider) return;
+      const current = stateRef.current;
+      const parent = current.breadcrumbs[current.breadcrumbs.length - 1];
+      if (parent) {
+        fetchItems(provider, query, parent);
+      }
+    },
+    [fetchItems]
+  );
   const onKeyDown = (0, import_react3.useCallback)(
     ({ event }) => {
       const current = stateRef.current;
@@ -736,7 +798,8 @@ function useSuggestion(providers) {
     navigateDown,
     select,
     goBack,
-    close
+    close,
+    searchNested
   };
   return { uiState, actions, callbacksRef };
 }
@@ -782,10 +845,29 @@ function SuggestionList({
   onSelect,
   onHover,
   onGoBack,
+  onSearchNested,
+  onNavigateUp,
+  onNavigateDown,
+  onClose,
   renderItem
 }) {
   const listRef = (0, import_react4.useRef)(null);
+  const searchInputRef = (0, import_react4.useRef)(null);
   const depth = breadcrumbs.length;
+  const [nestedQuery, setNestedQuery] = (0, import_react4.useState)("");
+  const breadcrumbKey = breadcrumbs.map((b) => b.id).join("/");
+  const prevBreadcrumbKey = (0, import_react4.useRef)(breadcrumbKey);
+  (0, import_react4.useEffect)(() => {
+    if (prevBreadcrumbKey.current !== breadcrumbKey) {
+      setNestedQuery("");
+      prevBreadcrumbKey.current = breadcrumbKey;
+    }
+  }, [breadcrumbKey]);
+  (0, import_react4.useEffect)(() => {
+    if (breadcrumbs.length > 0 && searchInputRef.current) {
+      requestAnimationFrame(() => searchInputRef.current?.focus());
+    }
+  }, [breadcrumbKey, breadcrumbs.length]);
   (0, import_react4.useEffect)(() => {
     if (!listRef.current) return;
     const active = listRef.current.querySelector('[aria-selected="true"]');
@@ -793,6 +875,35 @@ function SuggestionList({
   }, [activeIndex]);
   const style = usePopoverPosition(clientRect);
   if (items.length === 0 && !loading) return null;
+  const handleSearchKeyDown = (e) => {
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        onNavigateDown?.();
+        break;
+      case "ArrowUp":
+        e.preventDefault();
+        onNavigateUp?.();
+        break;
+      case "Enter": {
+        e.preventDefault();
+        e.stopPropagation();
+        const selectedItem = items[activeIndex];
+        if (selectedItem) onSelect(selectedItem);
+        break;
+      }
+      case "Escape":
+        e.preventDefault();
+        onClose?.();
+        break;
+      case "Backspace":
+        if (nestedQuery === "") {
+          e.preventDefault();
+          onGoBack();
+        }
+        break;
+    }
+  };
   return /* @__PURE__ */ (0, import_jsx_runtime.jsxs)(
     "div",
     {
@@ -817,6 +928,24 @@ function SuggestionList({
             crumb.label
           ] }, crumb.id))
         ] }),
+        breadcrumbs.length > 0 && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { "data-suggestion-search": "", children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
+          "input",
+          {
+            ref: searchInputRef,
+            type: "text",
+            "data-suggestion-search-input": "",
+            placeholder: "Search...",
+            value: nestedQuery,
+            onChange: (e) => {
+              const q = e.target.value;
+              setNestedQuery(q);
+              onSearchNested?.(q);
+            },
+            onKeyDown: handleSearchKeyDown,
+            autoComplete: "off",
+            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;
@@ -899,7 +1028,8 @@ var MentionsInput = (0, import_react5.forwardRef)(
       [clear, setContent, focus]
     );
     const isExpanded = uiState.state !== "idle";
-    const handleHover = (0, import_react5.useCallback)((_index) => {
+    const handleHover = (0, import_react5.useCallback)((index) => {
+      void index;
     }, []);
     return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)(
       "div",
@@ -923,6 +1053,10 @@ var MentionsInput = (0, import_react5.forwardRef)(
               onSelect: (item) => actions.select(item),
               onHover: handleHover,
               onGoBack: actions.goBack,
+              onSearchNested: actions.searchNested,
+              onNavigateUp: actions.navigateUp,
+              onNavigateDown: actions.navigateDown,
+              onClose: actions.close,
               renderItem
             }
           )
@@ -934,6 +1068,7 @@ var MentionsInput = (0, import_react5.forwardRef)(
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MentionsInput,
+  extractFromMarkdown,
   parseFromMarkdown,
   serializeToMarkdown
 });