@relevaince/mentions 0.3.3 → 0.6.0

package/README.md

@@ -11,12 +11,28 @@ This is **not** a simple `@mention` dropdown. It is a resource-addressing langua
 - **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
+- **Debounced fetching** — per-provider `debounceMs` prevents API floods
 - **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
+- **Grouped suggestions** — section items under headers (e.g. "Active", "Pending")
+- **Recently used items** — show recent mentions when the query is empty
+- **Empty state** — customizable "No results" message
+- **Mention lifecycle** — `onMentionAdd` / `onMentionRemove` callbacks
+- **Mention interaction** — `onMentionClick` / `onMentionHover` handlers on chips
+- **Mention validation** — mark stale/invalid mentions with `validateMention`
+- **Controlled value** — reactive `value` prop for external content updates
+- **Auto-resize** — `minHeight` / `maxHeight` for growing editor
+- **Submit key customization** — choose Enter, Cmd+Enter, or none
+- **Edge-aware popover** — flips above when near viewport bottom
+- **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
 
@@ -38,6 +54,7 @@ import { MentionsInput, type MentionProvider } from "@relevaince/mentions";
 const workspaceProvider: MentionProvider = {
   trigger: "@",
   name: "Workspaces",
+  debounceMs: 200,
   async getRootItems(query) {
     const res = await fetch(`/api/workspaces?q=${query}`);
     return res.json();
@@ -46,6 +63,10 @@ const workspaceProvider: MentionProvider = {
     const res = await fetch(`/api/workspaces/${parent.id}/files?q=${query}`);
     return res.json();
   },
+  async getRecentItems() {
+    const res = await fetch("/api/workspaces/recent");
+    return res.json();
+  },
 };
 
 function Chat() {
@@ -58,7 +79,11 @@ function Chat() {
         console.log(output.plainText); // "Summarize Marketing"
       }}
       onSubmit={(output) => sendMessage(output)}
+      onMentionAdd={(token) => console.log("Added:", token)}
+      onMentionRemove={(token) => console.log("Removed:", token)}
       placeholder="Ask anything..."
+      minHeight={40}
+      maxHeight={200}
     />
   );
 }
@@ -81,19 +106,29 @@ type MentionToken = {
 
 ### MentionProvider
 
-Register one provider per trigger character. Each provider fetches suggestions and optionally supports nested drill-down and cross-group search:
+Register one provider per trigger character. Each provider fetches suggestions and optionally supports nested drill-down, cross-group search, debouncing, and recent items:
 
 ```ts
 type MentionProvider = {
-  trigger: string;                                            // "@", "#", ":"
-  name: string;                                               // human label
+  trigger: string;
+  name: string;
   getRootItems: (query: string) => Promise<MentionItem[]>;
   getChildren?: (parent: MentionItem, query: string) => Promise<MentionItem[]>;
-  searchAll?: (query: string) => Promise<MentionItem[]>;      // flat search across all levels
+  searchAll?: (query: string) => Promise<MentionItem[]>;
+  debounceMs?: number;
+  getRecentItems?: () => Promise<MentionItem[]>;
 };
 ```
 
-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).
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `trigger` | `string` | Yes | Character(s) that activate this provider |
+| `name` | `string` | Yes | Human-readable name for ARIA labels |
+| `getRootItems` | `(query) => Promise<MentionItem[]>` | Yes | Top-level suggestions |
+| `getChildren` | `(parent, query) => Promise<MentionItem[]>` | No | Child suggestions for drill-down |
+| `searchAll` | `(query) => Promise<MentionItem[]>` | No | Flat search across all levels |
+| `debounceMs` | `number` | No | Delay before fetching (prevents API floods) |
+| `getRecentItems` | `() => Promise<MentionItem[]>` | No | Recently used items, shown on empty query |
 
 ### MentionItem
 
@@ -104,15 +139,16 @@ type MentionItem = {
   id: string;
   type: string;
   label: string;
-  icon?: ReactNode;        // rendered before the label
-  description?: string;    // secondary text
-  hasChildren?: boolean;   // when true, selecting drills into a child level
+  icon?: ReactNode;
+  description?: string;
+  hasChildren?: boolean;
   data?: unknown;
-  rootLabel?: string;      // parent label for flat search results (used in serialization)
+  rootLabel?: string;
+  group?: string;          // group items under section headers
 };
 ```
 
-Set `rootLabel` on items returned by `searchAll` that originate from a nested level. This ensures correct `@rootLabel[label](id)` serialization.
+Set `group` on items to render them under section headers in the dropdown (e.g. "Active", "Pending", "Recent").
 
 ### MentionsOutput
 
@@ -120,9 +156,9 @@ Structured output returned on every change and submit:
 
 ```ts
 type MentionsOutput = {
-  markdown: string;        // "@[Marketing](ws_123) summarize files"
-  tokens: MentionToken[];  // [{ id: "ws_123", type: "workspace", label: "Marketing" }]
-  plainText: string;       // "Marketing summarize files"
+  markdown: string;
+  tokens: MentionToken[];
+  plainText: string;
 };
 ```
 
@@ -130,22 +166,39 @@ type MentionsOutput = {
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `value` | `string` | — | Initial markdown content with `@[label](id)` tokens |
+| `value` | `string` | — | Controlled markdown content (reactive — updates editor on change) |
 | `providers` | `MentionProvider[]` | **required** | Suggestion providers, one per trigger |
 | `onChange` | `(output: MentionsOutput) => void` | — | Called on every content change |
-| `onSubmit` | `(output: MentionsOutput) => void` | — | Called on Enter or Cmd+Enter |
+| `onSubmit` | `(output: MentionsOutput) => void` | — | Called on submit shortcut |
 | `placeholder` | `string` | `"Type a message..."` | Placeholder text |
 | `autoFocus` | `boolean` | `false` | Focus editor on mount |
 | `disabled` | `boolean` | `false` | Disable editing |
 | `className` | `string` | — | CSS class on the wrapper |
 | `maxLength` | `number` | — | Max plain text character count |
+| `clearOnSubmit` | `boolean` | `true` | Auto-clear after `onSubmit` |
+| `submitKey` | `"enter" \| "mod+enter" \| "none"` | `"enter"` | Which key combo triggers submit |
+| `minHeight` | `number` | — | Minimum editor height in px |
+| `maxHeight` | `number` | — | Maximum editor height in px (enables scroll) |
+| `onFocus` | `() => void` | — | Called when editor gains focus |
+| `onBlur` | `() => void` | — | Called when editor loses focus |
+| `onMentionAdd` | `(token: MentionToken) => void` | — | Called when a mention is inserted |
+| `onMentionRemove` | `(token: MentionToken) => void` | — | Called when a mention is deleted |
+| `onMentionClick` | `(token: MentionToken, event: MouseEvent) => void` | — | Called when a mention chip is clicked |
+| `onMentionHover` | `(token: MentionToken) => ReactNode` | — | Return content for a hover tooltip |
 | `renderItem` | `(item, depth) => ReactNode` | — | Custom suggestion item renderer |
-| `clearOnSubmit` | `boolean` | `true` | Auto-clear the editor after `onSubmit` fires |
 | `renderChip` | `(token) => ReactNode` | — | Custom inline mention chip renderer |
+| `renderEmpty` | `(query: string) => ReactNode` | — | Custom empty state (no results) |
+| `renderLoading` | `() => ReactNode` | — | Custom loading indicator |
+| `renderGroupHeader` | `(group: string) => ReactNode` | — | Custom section header renderer |
+| `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
 
-`MentionsInput` supports `forwardRef` for programmatic control. This is essential for flows like clearing after submit, injecting prompts from a library, or "Enhance Prompt" features.
+`MentionsInput` supports `forwardRef` for programmatic control:
 
 ```tsx
 import { useRef } from "react";
@@ -158,16 +211,15 @@ function Chat() {
     <>
       <MentionsInput ref={ref} providers={providers} />
 
-      <button onClick={() => ref.current?.clear()}>
-        Clear
-      </button>
-
+      <button onClick={() => ref.current?.clear()}>Clear</button>
       <button onClick={() => {
         ref.current?.setContent("Summarize @[NDA](contract:c_1) risks");
         ref.current?.focus();
-      }}>
-        Use Prompt
-      </button>
+      }}>Use Prompt</button>
+      <button onClick={() => {
+        const output = ref.current?.getOutput();
+        console.log(output?.tokens);
+      }}>Read Output</button>
     </>
   );
 }
@@ -179,43 +231,64 @@ 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 |
 
-### Auto-clear on submit
+## Streaming
 
-By default, the editor clears itself after `onSubmit` fires. Disable with `clearOnSubmit={false}` if you want to manage clearing yourself:
+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
-  onSubmit={(output) => sendMessage(output)}
-  clearOnSubmit={false}  // don't auto-clear
+  ref={ref}
+  streaming={isStreaming}
+  providers={providers}
+  onChange={handleChange}
+  onStreamingComplete={(output) => {
+    console.log("Final tokens:", output.tokens);
+  }}
 />
 ```
 
-## Nested mentions
-
-The killer feature. When a `MentionItem` has `hasChildren: true`, selecting it drills into the next level using `provider.getChildren()`:
+**How it works:**
 
-```
-@workspace → choose workspace → choose file inside workspace
-@contract  → choose contract  → choose clause
-:web       → choose provider  → type query
-```
+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`
 
-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.
+For plain-text-only streaming (no mention syntax in chunks), use `ref.current.appendText(chunk)` instead for better performance.
 
-Keyboard navigation:
+## Keyboard shortcuts
 
 | Key | Context | Action |
 |-----|---------|--------|
 | `↑` `↓` | Suggestions open | Navigate suggestions |
 | `Enter` | Suggestions open | Select / drill into children |
+| `Tab` | Suggestions open | Select the active suggestion |
 | `→` | 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 |
+| `Enter` | Editor (default `submitKey`) | Submit message |
+| `Shift+Enter` | Editor (default `submitKey`) | New line |
 | `Cmd/Ctrl+Enter` | Editor | Submit message |
 
 ## Markdown format
@@ -224,6 +297,7 @@ Mentions serialize to a compact token syntax:
 
 ```
 @[Marketing Workspace](ws_123) summarize the latest files
+@Marketing[Q4 Strategy.pdf](file:file_1) review this document
 ```
 
 Use the standalone helpers for server-side processing:
@@ -235,38 +309,38 @@ import {
   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
 
-Zero bundled CSS. Every element exposes `data-*` attributes for styling:
+Zero bundled CSS. Every element exposes `data-*` attributes:
 
 ```css
-/* Mention chips inside the editor */
-[data-mention]                      { /* base chip */ }
-[data-mention][data-type="workspace"] { /* workspace chip */ }
-[data-mention][data-type="contract"]  { /* contract chip */ }
+/* Mention chips */
+[data-mention]                         { /* base chip */ }
+[data-mention][data-type="workspace"]  { /* workspace chip */ }
+[data-mention][data-type="contract"]   { /* contract chip */ }
+[data-mention-clickable]               { /* clickable chip (when onMentionClick set) */ }
+[data-mention-invalid]                 { /* invalid/stale mention */ }
+[data-mention-tooltip]                 { /* hover tooltip container */ }
 
 /* Suggestion popover */
-[data-suggestions]                  { /* popover wrapper */ }
-[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 */ }
+[data-suggestions]                     { /* popover wrapper */ }
+[data-suggestions-position="above"]    { /* when popover flips above */ }
+[data-suggestions-position="below"]    { /* when popover is below */ }
+[data-suggestion-item]                 { /* each item */ }
+[data-suggestion-item-active]          { /* highlighted item */ }
+[data-suggestion-group-header]         { /* group section header */ }
+[data-suggestion-empty]                { /* "no results" state */ }
+[data-suggestion-loading]              { /* loading indicator */ }
+[data-suggestion-breadcrumb]           { /* breadcrumb bar (nested) */ }
+[data-suggestion-search]               { /* search input wrapper */ }
+[data-suggestion-search-input]         { /* search input field */ }
 ```
 
 Example with Tailwind:
@@ -288,6 +362,18 @@ Example with Tailwind:
 [data-suggestion-item-active] {
   @apply bg-neutral-100;
 }
+
+[data-suggestion-group-header] {
+  @apply px-3 py-1 text-[10px] font-semibold text-neutral-400 uppercase tracking-wider;
+}
+
+[data-suggestion-empty] {
+  @apply px-3 py-2 text-xs text-neutral-400 italic;
+}
+
+[data-mention-invalid] {
+  @apply opacity-50 line-through;
+}
 ```
 
 ## Architecture
@@ -295,30 +381,31 @@ Example with Tailwind:
 ```
 <MentionsInput>
   ├── Tiptap Editor (ProseMirror)
-  │     ├── MentionNode Extension    — inline atom nodes with id/label/type
-  │     ├── Suggestion Plugin        — multi-trigger detection + popover callbacks
-  │     ├── Enter/Submit Extension   — Enter submits, Shift+Enter new line
+  │     ├── MentionNode Extension    — inline atom nodes with id/label/type + click/hover
+  │     ├── Suggestion Plugin        — multi-trigger detection + allowTrigger gating
+  │     ├── Enter/Submit Extension   — configurable submit key (Enter/Mod+Enter/none)
+  │     ├── Mention Remove Detector  — transaction-based onMentionRemove
   │     └── Markdown Parser/Serializer — doc ↔ @[label](id) + extractFromMarkdown
-  └── SuggestionList (React)         — headless popover with ARIA + nested search
+  └── SuggestionList (React)         — headless popover with ARIA, groups, edge-aware positioning
 ```
 
-Consumers interact with a single React component. Tiptap and ProseMirror are internal implementation details.
+## Testing
+
+```bash
+npm test           # run all tests
+npm run test:watch # watch mode
+```
 
 ## Development
 
 ```bash
-# Install dependencies
-npm install
-
-# Build the library
-npm run build
+npm install        # install dependencies
+npm run build      # build the library
+npm test           # run tests
 
-# Run the demo app
-cd demo && npm install && npx vite
+cd demo && npm install && npx vite  # run the demo app
 ```
 
-The demo app registers mock providers for workspaces, contracts, and web search. It displays live structured output below the editor.
-
 ## License
 
 MIT

package/dist/index.d.mts

@@ -25,6 +25,8 @@ type MentionItem = {
      * item originates from a nested level.
      */
     rootLabel?: string;
+    /** Optional group name for sectioned suggestion lists. Items with the same group are grouped together. */
+    group?: string;
 };
 /**
  * Hierarchical suggestion source registered per trigger character.
@@ -48,6 +50,10 @@ type MentionProvider = {
      * results from `searchAll` are shown instead of `getRootItems`.
      */
     searchAll?: (query: string) => Promise<MentionItem[]>;
+    /** Debounce delay in ms before fetching suggestions. `0` or `undefined` means no debounce. */
+    debounceMs?: number;
+    /** Fetch recently used items, shown when the query is empty. Items are auto-grouped under "Recent". */
+    getRecentItems?: () => Promise<MentionItem[]>;
 };
 
 /**
@@ -112,6 +118,49 @@ type MentionsInputProps = {
     renderItem?: (item: MentionItem, depth: number) => ReactNode;
     /** Custom renderer for inline mention chips. */
     renderChip?: (token: MentionToken) => ReactNode;
+    /** Custom renderer for empty suggestion state. Receives the current query. */
+    renderEmpty?: (query: string) => ReactNode;
+    /** Custom renderer for the suggestion loading indicator. */
+    renderLoading?: () => ReactNode;
+    /** Custom renderer for suggestion group section headers. */
+    renderGroupHeader?: (group: string) => ReactNode;
+    /** Called when the editor gains focus. */
+    onFocus?: () => void;
+    /** Called when the editor loses focus. */
+    onBlur?: () => void;
+    /** Called when a mention token is inserted. */
+    onMentionAdd?: (token: MentionToken) => void;
+    /** Called when a mention token is removed. */
+    onMentionRemove?: (token: MentionToken) => void;
+    /** Called when a mention chip is clicked. */
+    onMentionClick?: (token: MentionToken, event: MouseEvent) => void;
+    /** Return a ReactNode to show as a tooltip when hovering over a mention chip. */
+    onMentionHover?: (token: MentionToken) => ReactNode;
+    /** Minimum height of the editor in pixels. */
+    minHeight?: number;
+    /** Maximum height of the editor in pixels. Enables scrolling. */
+    maxHeight?: number;
+    /** Which key combo triggers `onSubmit`. Defaults to `"enter"`. */
+    submitKey?: "enter" | "mod+enter" | "none";
+    /** Conditionally suppress the suggestion dropdown. Return `false` to block. */
+    allowTrigger?: (trigger: string, context: {
+        textBefore: string;
+    }) => boolean;
+    /** Validate existing mentions. Return `false` to mark as invalid. */
+    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>`.
@@ -123,15 +172,20 @@ type MentionsInputProps = {
  * ref.current.clear();
  * ref.current.setContent("Hello @[Marketing](ws_123)");
  * ref.current.focus();
+ * ref.current.getOutput(); // { markdown, tokens, plainText }
  * ```
  */
 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. */
+    getOutput: () => MentionsOutput | null;
 };
 
 /**
@@ -140,14 +194,6 @@ type MentionsInputHandle = {
  * 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 const MentionsInput: React.ForwardRefExoticComponent<MentionsInputProps & React.RefAttributes<MentionsInputHandle>>;
 

package/dist/index.d.ts

@@ -25,6 +25,8 @@ type MentionItem = {
      * item originates from a nested level.
      */
     rootLabel?: string;
+    /** Optional group name for sectioned suggestion lists. Items with the same group are grouped together. */
+    group?: string;
 };
 /**
  * Hierarchical suggestion source registered per trigger character.
@@ -48,6 +50,10 @@ type MentionProvider = {
      * results from `searchAll` are shown instead of `getRootItems`.
      */
     searchAll?: (query: string) => Promise<MentionItem[]>;
+    /** Debounce delay in ms before fetching suggestions. `0` or `undefined` means no debounce. */
+    debounceMs?: number;
+    /** Fetch recently used items, shown when the query is empty. Items are auto-grouped under "Recent". */
+    getRecentItems?: () => Promise<MentionItem[]>;
 };
 
 /**
@@ -112,6 +118,49 @@ type MentionsInputProps = {
     renderItem?: (item: MentionItem, depth: number) => ReactNode;
     /** Custom renderer for inline mention chips. */
     renderChip?: (token: MentionToken) => ReactNode;
+    /** Custom renderer for empty suggestion state. Receives the current query. */
+    renderEmpty?: (query: string) => ReactNode;
+    /** Custom renderer for the suggestion loading indicator. */
+    renderLoading?: () => ReactNode;
+    /** Custom renderer for suggestion group section headers. */
+    renderGroupHeader?: (group: string) => ReactNode;
+    /** Called when the editor gains focus. */
+    onFocus?: () => void;
+    /** Called when the editor loses focus. */
+    onBlur?: () => void;
+    /** Called when a mention token is inserted. */
+    onMentionAdd?: (token: MentionToken) => void;
+    /** Called when a mention token is removed. */
+    onMentionRemove?: (token: MentionToken) => void;
+    /** Called when a mention chip is clicked. */
+    onMentionClick?: (token: MentionToken, event: MouseEvent) => void;
+    /** Return a ReactNode to show as a tooltip when hovering over a mention chip. */
+    onMentionHover?: (token: MentionToken) => ReactNode;
+    /** Minimum height of the editor in pixels. */
+    minHeight?: number;
+    /** Maximum height of the editor in pixels. Enables scrolling. */
+    maxHeight?: number;
+    /** Which key combo triggers `onSubmit`. Defaults to `"enter"`. */
+    submitKey?: "enter" | "mod+enter" | "none";
+    /** Conditionally suppress the suggestion dropdown. Return `false` to block. */
+    allowTrigger?: (trigger: string, context: {
+        textBefore: string;
+    }) => boolean;
+    /** Validate existing mentions. Return `false` to mark as invalid. */
+    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>`.
@@ -123,15 +172,20 @@ type MentionsInputProps = {
  * ref.current.clear();
  * ref.current.setContent("Hello @[Marketing](ws_123)");
  * ref.current.focus();
+ * ref.current.getOutput(); // { markdown, tokens, plainText }
  * ```
  */
 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. */
+    getOutput: () => MentionsOutput | null;
 };
 
 /**
@@ -140,14 +194,6 @@ type MentionsInputHandle = {
  * 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 const MentionsInput: React.ForwardRefExoticComponent<MentionsInputProps & React.RefAttributes<MentionsInputHandle>>;