@domternal/extension-mention 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,181 @@
+import { CommandSpec, Node } from '@domternal/core';
+import { NodeType, Node as Node$1, DOMOutputSpec } from '@domternal/pm/model';
+import { EditorState, Plugin } from '@domternal/pm/state';
+import { EditorView } from '@domternal/pm/view';
+
+/**
+ * Mention Suggestion Plugin
+ *
+ * Headless ProseMirror plugin that watches for trigger characters (e.g. '@', '#'),
+ * tracks the query, supports async item fetching with debounce, and calls render
+ * callbacks so framework wrappers can display a dropdown picker.
+ *
+ * Adapted from the emoji suggestion plugin with additions:
+ * - Async items support with 150ms debounce
+ * - Multiple plugin instances (one per trigger, unique PluginKey)
+ * - Inline decoration on active trigger+query range
+ * - invalidNodes context check
+ * - appendText after insertion
+ */
+
+/** A single mention item returned by the items() callback. */
+interface MentionItem {
+    /** Unique identifier (e.g., user ID, tag slug). */
+    id: string;
+    /** Display text (e.g., "John Doe", "feature-request"). */
+    label: string;
+    /** Allow extra data (avatar URL, email, role, etc.). */
+    [key: string]: unknown;
+}
+/** Configuration for a single mention trigger. */
+interface MentionTrigger {
+    /** Trigger character. Default: '@' */
+    char: string;
+    /** Unique name for this trigger type (e.g., 'user', 'tag'). */
+    name: string;
+    /** Fetch items matching a query. Supports sync and async (Promise). */
+    items: (props: {
+        query: string;
+        trigger: MentionTrigger;
+    }) => MentionItem[] | Promise<MentionItem[]>;
+    /** Render callbacks for the suggestion popup. */
+    render?: () => MentionSuggestionRenderer;
+    /** Minimum query length before showing suggestions. Default: 0 */
+    minQueryLength?: number;
+    /** Allow spaces in query. Default: false */
+    allowSpaces?: boolean;
+    /** Text to append after mention insertion. Default: ' ' (space) */
+    appendText?: string;
+    /** Node types where suggestion should NOT activate (e.g. ['codeBlock']). Default: [] */
+    invalidNodes?: string[];
+    /** Debounce delay in ms for items() calls. Use >0 for async/API-backed items. Default: 0 (immediate) */
+    debounce?: number;
+    /** CSS class for the inline decoration on the active trigger+query range. Default: 'mention-suggestion' */
+    decorationClass?: string;
+    /** HTML tag for the inline decoration element. Default: 'span' */
+    decorationTag?: string;
+    /**
+     * Controls whether the suggestion should be shown. Return `false` to suppress.
+     * Useful for collaboration (suppress suggestions triggered by remote cursors)
+     * or any custom logic based on editor state.
+     */
+    shouldShow?: (props: {
+        state: EditorState;
+        view: EditorView;
+    }) => boolean;
+}
+/** Props passed to suggestion renderer callbacks. */
+interface MentionSuggestionProps {
+    /** Current query string (text after trigger char). */
+    query: string;
+    /** Document range of the trigger + query (for replacement). */
+    range: {
+        from: number;
+        to: number;
+    };
+    /** Filtered mention items matching the query. */
+    items: MentionItem[];
+    /** Call to insert a mention and close the suggestion. */
+    command: (item: MentionItem) => void;
+    /** Returns the client rect of the cursor for positioning the popup. */
+    clientRect: (() => DOMRect | null) | null;
+}
+/** Render callbacks for the suggestion popup. */
+interface MentionSuggestionRenderer {
+    /** Called when suggestion is first activated. */
+    onStart: (props: MentionSuggestionProps) => void;
+    /** Called when query or items change. */
+    onUpdate: (props: MentionSuggestionProps) => void;
+    /** Called when suggestion is deactivated. */
+    onExit: () => void;
+    /** Called on keydown — return true to prevent default editor handling. */
+    onKeyDown: (event: KeyboardEvent) => boolean;
+}
+interface SuggestionPluginOptions {
+    trigger: MentionTrigger;
+    nodeType: NodeType | null;
+}
+/**
+ * Creates a ProseMirror plugin for mention suggestion/autocomplete.
+ * One plugin instance per trigger.
+ */
+declare function createMentionSuggestionPlugin(options: SuggestionPluginOptions): Plugin;
+/**
+ * Programmatically dismiss the mention suggestion for a given trigger.
+ * Dispatches a meta transaction to reset the plugin state.
+ */
+declare function dismissMentionSuggestion(view: EditorView, triggerName: string): void;
+
+/**
+ * Mention Node Extension
+ *
+ * Inline atom node for @mentions with multi-trigger support,
+ * headless suggestion plugin, async item fetching, and configurable rendering.
+ *
+ * @example
+ * ```ts
+ * import { Mention } from '@domternal/extension-mention';
+ *
+ * const editor = new Editor({
+ *   extensions: [
+ *     Mention.configure({
+ *       suggestion: {
+ *         char: '@',
+ *         name: 'user',
+ *         items: ({ query }) => users.filter(u => u.label.includes(query)),
+ *         render: createMentionRenderer,
+ *       },
+ *     }),
+ *   ],
+ * });
+ *
+ * // Insert mention programmatically
+ * editor.commands.insertMention({ id: '1', label: 'Alice' });
+ * ```
+ */
+
+declare module '@domternal/core' {
+    interface RawCommands {
+        insertMention: CommandSpec<[attrs: {
+            id: string;
+            label: string;
+            type?: string;
+        }]>;
+        deleteMention: CommandSpec<[id?: string]>;
+    }
+}
+interface MentionOptions {
+    /** Single trigger config (shorthand). Ignored if `triggers` is non-empty. */
+    suggestion: MentionTrigger | null;
+    /** Multiple trigger configs. Takes precedence over `suggestion`. */
+    triggers: MentionTrigger[];
+    /** Delete trigger char alongside mention on Backspace. Default: false */
+    deleteTriggerWithBackspace: boolean;
+    /** Custom render for HTML output (e.g. render as <a>). */
+    renderHTML: ((props: {
+        node: Node$1;
+        options: MentionOptions;
+        HTMLAttributes: Record<string, unknown>;
+    }) => DOMOutputSpec) | null;
+    /** Custom render for plain text output. */
+    renderText: ((props: {
+        node: Node$1;
+        options: MentionOptions;
+    }) => string) | null;
+    /** HTML attributes for the mention element. */
+    HTMLAttributes: Record<string, unknown>;
+}
+interface MentionStorage {
+    /** Find all mention nodes in the document. */
+    findMentions: () => {
+        id: string;
+        label: string;
+        type: string;
+        pos: number;
+    }[];
+    /** @internal Trigger name → char lookup map. */
+    _triggerCharMap: Map<string, string>;
+}
+declare const Mention: Node<MentionOptions, MentionStorage>;
+
+export { Mention, type MentionItem, type MentionOptions, type MentionStorage, type MentionSuggestionProps, type MentionSuggestionRenderer, type MentionTrigger, createMentionSuggestionPlugin, Mention as default, dismissMentionSuggestion };

package/dist/index.d.ts

@@ -0,0 +1,181 @@
+import { CommandSpec, Node } from '@domternal/core';
+import { NodeType, Node as Node$1, DOMOutputSpec } from '@domternal/pm/model';
+import { EditorState, Plugin } from '@domternal/pm/state';
+import { EditorView } from '@domternal/pm/view';
+
+/**
+ * Mention Suggestion Plugin
+ *
+ * Headless ProseMirror plugin that watches for trigger characters (e.g. '@', '#'),
+ * tracks the query, supports async item fetching with debounce, and calls render
+ * callbacks so framework wrappers can display a dropdown picker.
+ *
+ * Adapted from the emoji suggestion plugin with additions:
+ * - Async items support with 150ms debounce
+ * - Multiple plugin instances (one per trigger, unique PluginKey)
+ * - Inline decoration on active trigger+query range
+ * - invalidNodes context check
+ * - appendText after insertion
+ */
+
+/** A single mention item returned by the items() callback. */
+interface MentionItem {
+    /** Unique identifier (e.g., user ID, tag slug). */
+    id: string;
+    /** Display text (e.g., "John Doe", "feature-request"). */
+    label: string;
+    /** Allow extra data (avatar URL, email, role, etc.). */
+    [key: string]: unknown;
+}
+/** Configuration for a single mention trigger. */
+interface MentionTrigger {
+    /** Trigger character. Default: '@' */
+    char: string;
+    /** Unique name for this trigger type (e.g., 'user', 'tag'). */
+    name: string;
+    /** Fetch items matching a query. Supports sync and async (Promise). */
+    items: (props: {
+        query: string;
+        trigger: MentionTrigger;
+    }) => MentionItem[] | Promise<MentionItem[]>;
+    /** Render callbacks for the suggestion popup. */
+    render?: () => MentionSuggestionRenderer;
+    /** Minimum query length before showing suggestions. Default: 0 */
+    minQueryLength?: number;
+    /** Allow spaces in query. Default: false */
+    allowSpaces?: boolean;
+    /** Text to append after mention insertion. Default: ' ' (space) */
+    appendText?: string;
+    /** Node types where suggestion should NOT activate (e.g. ['codeBlock']). Default: [] */
+    invalidNodes?: string[];
+    /** Debounce delay in ms for items() calls. Use >0 for async/API-backed items. Default: 0 (immediate) */
+    debounce?: number;
+    /** CSS class for the inline decoration on the active trigger+query range. Default: 'mention-suggestion' */
+    decorationClass?: string;
+    /** HTML tag for the inline decoration element. Default: 'span' */
+    decorationTag?: string;
+    /**
+     * Controls whether the suggestion should be shown. Return `false` to suppress.
+     * Useful for collaboration (suppress suggestions triggered by remote cursors)
+     * or any custom logic based on editor state.
+     */
+    shouldShow?: (props: {
+        state: EditorState;
+        view: EditorView;
+    }) => boolean;
+}
+/** Props passed to suggestion renderer callbacks. */
+interface MentionSuggestionProps {
+    /** Current query string (text after trigger char). */
+    query: string;
+    /** Document range of the trigger + query (for replacement). */
+    range: {
+        from: number;
+        to: number;
+    };
+    /** Filtered mention items matching the query. */
+    items: MentionItem[];
+    /** Call to insert a mention and close the suggestion. */
+    command: (item: MentionItem) => void;
+    /** Returns the client rect of the cursor for positioning the popup. */
+    clientRect: (() => DOMRect | null) | null;
+}
+/** Render callbacks for the suggestion popup. */
+interface MentionSuggestionRenderer {
+    /** Called when suggestion is first activated. */
+    onStart: (props: MentionSuggestionProps) => void;
+    /** Called when query or items change. */
+    onUpdate: (props: MentionSuggestionProps) => void;
+    /** Called when suggestion is deactivated. */
+    onExit: () => void;
+    /** Called on keydown — return true to prevent default editor handling. */
+    onKeyDown: (event: KeyboardEvent) => boolean;
+}
+interface SuggestionPluginOptions {
+    trigger: MentionTrigger;
+    nodeType: NodeType | null;
+}
+/**
+ * Creates a ProseMirror plugin for mention suggestion/autocomplete.
+ * One plugin instance per trigger.
+ */
+declare function createMentionSuggestionPlugin(options: SuggestionPluginOptions): Plugin;
+/**
+ * Programmatically dismiss the mention suggestion for a given trigger.
+ * Dispatches a meta transaction to reset the plugin state.
+ */
+declare function dismissMentionSuggestion(view: EditorView, triggerName: string): void;
+
+/**
+ * Mention Node Extension
+ *
+ * Inline atom node for @mentions with multi-trigger support,
+ * headless suggestion plugin, async item fetching, and configurable rendering.
+ *
+ * @example
+ * ```ts
+ * import { Mention } from '@domternal/extension-mention';
+ *
+ * const editor = new Editor({
+ *   extensions: [
+ *     Mention.configure({
+ *       suggestion: {
+ *         char: '@',
+ *         name: 'user',
+ *         items: ({ query }) => users.filter(u => u.label.includes(query)),
+ *         render: createMentionRenderer,
+ *       },
+ *     }),
+ *   ],
+ * });
+ *
+ * // Insert mention programmatically
+ * editor.commands.insertMention({ id: '1', label: 'Alice' });
+ * ```
+ */
+
+declare module '@domternal/core' {
+    interface RawCommands {
+        insertMention: CommandSpec<[attrs: {
+            id: string;
+            label: string;
+            type?: string;
+        }]>;
+        deleteMention: CommandSpec<[id?: string]>;
+    }
+}
+interface MentionOptions {
+    /** Single trigger config (shorthand). Ignored if `triggers` is non-empty. */
+    suggestion: MentionTrigger | null;
+    /** Multiple trigger configs. Takes precedence over `suggestion`. */
+    triggers: MentionTrigger[];
+    /** Delete trigger char alongside mention on Backspace. Default: false */
+    deleteTriggerWithBackspace: boolean;
+    /** Custom render for HTML output (e.g. render as <a>). */
+    renderHTML: ((props: {
+        node: Node$1;
+        options: MentionOptions;
+        HTMLAttributes: Record<string, unknown>;
+    }) => DOMOutputSpec) | null;
+    /** Custom render for plain text output. */
+    renderText: ((props: {
+        node: Node$1;
+        options: MentionOptions;
+    }) => string) | null;
+    /** HTML attributes for the mention element. */
+    HTMLAttributes: Record<string, unknown>;
+}
+interface MentionStorage {
+    /** Find all mention nodes in the document. */
+    findMentions: () => {
+        id: string;
+        label: string;
+        type: string;
+        pos: number;
+    }[];
+    /** @internal Trigger name → char lookup map. */
+    _triggerCharMap: Map<string, string>;
+}
+declare const Mention: Node<MentionOptions, MentionStorage>;
+
+export { Mention, type MentionItem, type MentionOptions, type MentionStorage, type MentionSuggestionProps, type MentionSuggestionRenderer, type MentionTrigger, createMentionSuggestionPlugin, Mention as default, dismissMentionSuggestion };