@editorjs-mentions/plugin 0.1.4

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 editorjs-mentions contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,148 @@
+# @editorjs-mentions/plugin
+
+[![Last Commit](https://img.shields.io/github/last-commit/pmalirz/editorjs-mentions?style=flat-square)](https://github.com/pmalirz/editorjs-mentions)
+[![npm latest](https://img.shields.io/npm/v/%40editorjs-mentions%2Fplugin/latest?style=flat-square)](https://www.npmjs.com/package/@editorjs-mentions/plugin)
+[![License](https://img.shields.io/github/license/pmalirz/editorjs-mentions?style=flat-square)](https://github.com/pmalirz/editorjs-mentions/blob/main/LICENSE)
+[![Open Issues](https://img.shields.io/github/issues/pmalirz/editorjs-mentions?style=flat-square)](https://github.com/pmalirz/editorjs-mentions/issues)
+[![Editor.js 2.x](https://img.shields.io/badge/Editor.js-2.x-0ea5e9?style=flat-square)](https://www.npmjs.com/package/@editorjs/editorjs)
+
+Mentions autocomplete plugin for Editor.js with:
+
+- configurable trigger symbols
+- pluggable provider API
+- structured mention serialization (`text + entities`) for stable backend IDs
+- mention tooltip with optional link
+- metadata-preserving copy/paste in Editor.js
+
+![Mentions autocomplete example](docs/mentions-example-autocomplete.png)
+
+## Install
+
+```bash
+npm i @editorjs-mentions/plugin
+```
+
+## Quick Start
+
+```ts
+import { EditorJSMentions, createRestMentionProvider } from "@editorjs-mentions/plugin";
+
+const mentions = new EditorJSMentions({
+  holder: "editor",
+  triggerSymbols: ["@"],
+  mentionRenderContext: { currentUserId: "u-1002" },
+  renderMention: ({ item, defaultText, element, context }) => {
+    const ctx = context as { currentUserId?: string } | undefined;
+    const isCurrentUser = ctx?.currentUserId === item.id;
+    element.textContent = defaultText;
+    element.style.fontWeight = isCurrentUser ? "700" : "400";
+  },
+  provider: createRestMentionProvider({
+    endpoint: "http://localhost:3001/api/mentions/users"
+  })
+});
+
+mentions.setMentionRenderContext({ currentUserId: "u-1001" });
+
+// mentions.destroy();
+```
+
+## Config
+
+- `holder: string | HTMLElement` - Editor.js holder element or id.
+- `provider` - mention source function/object (required).
+- `triggerSymbols?: string[]` - defaults to `["@"]`.
+- `maxResults?: number` - defaults to `8`.
+- `minChars?: number` - defaults to `0`.
+- `debounceMs?: number` - defaults to `160`.
+- `className?: string` - custom dropdown class.
+- `onSelect?: (item) => void`.
+- `renderItem?: (item) => string` - custom item renderer.
+- `renderMention?: (args) => void` - customize rendered mention anchor (style/content/classes).
+- `mentionRenderContext?: unknown` - dynamic context available in `renderMention`.
+
+## Data Model
+
+```ts
+type MentionItem = {
+  id: string;
+  displayName: string;
+  description?: string;
+  image?: string;
+  link?: string;
+};
+```
+
+## Save/Load with Stable IDs
+
+Serialize editor output before sending to backend:
+
+```ts
+import { encodeMentionsInOutput, decodeMentionsInOutput } from "@editorjs-mentions/plugin";
+
+const nativeOutput = await editor.save();
+const payloadForServer = encodeMentionsInOutput(nativeOutput);
+
+// later when loading existing content:
+const payloadFromServer = await fetch(...).then((r) => r.json());
+const payloadForEditor = decodeMentionsInOutput(payloadFromServer);
+```
+
+Example stored paragraph:
+
+```json
+{
+  "type": "paragraph",
+  "data": {
+    "text": "@John Doe @Raj Patel",
+    "entities": [
+      {
+        "type": "mention",
+        "id": "u-1001",
+        "displayName": "John Doe",
+        "start": 0,
+        "end": 9,
+        "description": "Engineering",
+        "link": "https://example.local/users/u-1001"
+      }
+    ]
+  }
+}
+```
+
+## Runtime Styling Updates
+
+Use ID-based context and re-render mentions when app state changes:
+
+```ts
+mentions.setMentionRenderContext({ currentUserId: loggedUser.id });
+mentions.refreshMentionRendering();
+```
+
+`renderMention` receives:
+
+```ts
+{
+  item: MentionItem;              // full mention metadata (id, displayName, ...)
+  trigger: string;                // matched trigger, e.g. "@"
+  defaultText: string;            // default visible text, e.g. "@John Doe"
+  element: HTMLAnchorElement;     // mention DOM element to customize
+  source: "insert" | "paste" | "refresh";
+  context?: unknown;              // mentionRenderContext passed by app
+}
+```
+
+## Clipboard Notes
+
+- In-editor copy/paste keeps mention structure via custom clipboard payload + HTML normalization.
+- Pasting into external apps falls back to plain text representation (for example `@John Doe`).
+
+## Public API
+
+- `new EditorJSMentions(config)`
+- `destroy()`
+- `setMentionRenderContext(context: unknown)`
+- `refreshMentionRendering()`
+- `createRestMentionProvider(options)`
+- `encodeMentionsInOutput(output)`
+- `decodeMentionsInOutput(output)`

package/dist/index.d.mts

@@ -0,0 +1,169 @@
+/** Single mention candidate returned by provider and rendered in editor content. */
+type MentionItem = {
+    /** Stable backend identifier used for persistence and server-side processing. */
+    id: string;
+    /** User-visible label rendered in autocomplete and mention chip text. */
+    displayName: string;
+    /** Optional secondary text displayed in dropdown and tooltip. */
+    description?: string;
+    /** Optional avatar/icon URL shown in dropdown and tooltip. */
+    image?: string;
+    /** Optional external URL shown in mention details tooltip. */
+    link?: string;
+};
+/** Query payload passed to mention providers during autocomplete lookup. */
+type MentionQuery = {
+    /** Trigger symbol that started this query, e.g. "@". */
+    trigger: string;
+    /** Text typed after the trigger. */
+    query: string;
+    /** Maximum number of results requested by the plugin. */
+    limit: number;
+};
+/** Function-style mention provider contract. */
+type MentionProviderFn = (query: MentionQuery) => Promise<MentionItem[]>;
+/** Object-style mention provider contract. */
+type MentionProviderObject = {
+    search: MentionProviderFn;
+};
+/** Supported mention provider shapes. */
+type MentionProvider = MentionProviderFn | MentionProviderObject;
+/** Origin of a mention render call. */
+type MentionRenderSource = "insert" | "paste" | "refresh";
+/** Parameters passed to `renderMention` customization hook. */
+type MentionRenderArgs = {
+    /** Mention metadata associated with the rendered element. */
+    item: MentionItem;
+    /** Trigger symbol used for this mention. */
+    trigger: string;
+    /** Default display text, typically `${trigger}${displayName}`. */
+    defaultText: string;
+    /** Mention anchor element that can be styled/customized by integrator. */
+    element: HTMLAnchorElement;
+    /** Render reason, useful for conditional logic. */
+    source: MentionRenderSource;
+    /** Arbitrary app context provided through plugin config/update API. */
+    context?: unknown;
+};
+/** Main plugin configuration. */
+type MentionsConfig = {
+    /** Editor.js holder element or element id. */
+    holder: string | HTMLElement;
+    /** Data source for autocomplete candidates. */
+    provider: MentionProvider;
+    /** Trigger symbols that activate mention lookup. Defaults to `["@"]`. */
+    triggerSymbols?: string[];
+    /** Maximum autocomplete results. */
+    maxResults?: number;
+    /** Minimum query length after trigger before provider call. */
+    minChars?: number;
+    /** Debounce in milliseconds for provider calls. */
+    debounceMs?: number;
+    /** Optional custom dropdown root class name. */
+    className?: string;
+    /** Callback fired when mention is selected and inserted. */
+    onSelect?: (item: MentionItem) => void;
+    /** Custom HTML renderer for dropdown rows. */
+    renderItem?: (item: MentionItem) => string;
+    /** Hook to customize mention anchor rendering/styling in editor content. */
+    renderMention?: (args: MentionRenderArgs) => void;
+    /** Mutable external context consumed by `renderMention`. */
+    mentionRenderContext?: unknown;
+};
+/**
+ * Persisted mention entity stored alongside plain text content.
+ *
+ * @example
+ * {
+ *   "type": "mention",
+ *   "id": "u-1002",
+ *   "displayName": "Joanna Smith",
+ *   "start": 0,
+ *   "end": 13,
+ *   "trigger": "@",
+ *   "description": "Product Management",
+ *   "image": "https://example.com/avatars/u-1002.png",
+ *   "link": "https://example.local/users/u-1002"
+ * }
+ */
+type MentionEntity = {
+    type: "mention";
+    /** Stable backend identifier. */
+    id: string;
+    /** Display name at time of serialization. */
+    displayName: string;
+    /** Start offset (inclusive) in plain text. */
+    start: number;
+    /** End offset (exclusive) in plain text. */
+    end: number;
+    /** Trigger symbol used for rendering. */
+    trigger?: string;
+    /** Optional metadata copied from mention source. */
+    description?: string;
+    image?: string;
+    link?: string;
+};
+/** Minimal Editor.js block shape used by serializer helpers. */
+type EditorJSBlockLike = {
+    id?: string;
+    type: string;
+    data: Record<string, unknown>;
+};
+/** Minimal Editor.js output shape used by serializer helpers. */
+type EditorJSOutputLike = {
+    time?: number;
+    version?: string;
+    blocks: EditorJSBlockLike[];
+};
+
+declare class EditorJSMentions {
+    private holder;
+    private config;
+    private provider;
+    private dropdown;
+    private debounceTimer;
+    private requestSerial;
+    private activeContext;
+    private destroyed;
+    private tooltipRoot;
+    constructor(config: MentionsConfig);
+    setMentionRenderContext(context: unknown): void;
+    refreshMentionRendering(): void;
+    destroy(): void;
+    private bind;
+    private onClick;
+    private onDocumentMouseDown;
+    private onInput;
+    private onCopy;
+    private onCut;
+    private onPaste;
+    private onKeyDown;
+    private handleCopyOrCut;
+    private evaluateAndFetch;
+    private readActiveContext;
+    private selectMention;
+    private showTooltip;
+    private hideTooltip;
+    private readMentionFromElement;
+    private applyMentionRendering;
+    private getCaretRect;
+}
+
+type RestProviderOptions = {
+    endpoint: string;
+    queryParam?: string;
+    triggerParam?: string;
+    limitParam?: string;
+    fetchInit?: RequestInit;
+    mapResponse?: (json: unknown) => MentionItem[];
+};
+declare function createRestMentionProvider(options: RestProviderOptions): MentionProviderFn;
+
+declare function encodeMentionsInOutput(output: EditorJSOutputLike): EditorJSOutputLike;
+declare function decodeMentionsInOutput(output: EditorJSOutputLike): EditorJSOutputLike;
+declare function encodeMentionsFromHtml(html: string): {
+    text: string;
+    entities: MentionEntity[];
+};
+
+export { type EditorJSBlockLike, EditorJSMentions, type EditorJSOutputLike, type MentionEntity, type MentionItem, type MentionProvider, type MentionProviderFn, type MentionProviderObject, type MentionQuery, type MentionRenderArgs, type MentionRenderSource, type MentionsConfig, createRestMentionProvider, decodeMentionsInOutput, encodeMentionsFromHtml, encodeMentionsInOutput };

package/dist/index.d.ts

@@ -0,0 +1,169 @@
+/** Single mention candidate returned by provider and rendered in editor content. */
+type MentionItem = {
+    /** Stable backend identifier used for persistence and server-side processing. */
+    id: string;
+    /** User-visible label rendered in autocomplete and mention chip text. */
+    displayName: string;
+    /** Optional secondary text displayed in dropdown and tooltip. */
+    description?: string;
+    /** Optional avatar/icon URL shown in dropdown and tooltip. */
+    image?: string;
+    /** Optional external URL shown in mention details tooltip. */
+    link?: string;
+};
+/** Query payload passed to mention providers during autocomplete lookup. */
+type MentionQuery = {
+    /** Trigger symbol that started this query, e.g. "@". */
+    trigger: string;
+    /** Text typed after the trigger. */
+    query: string;
+    /** Maximum number of results requested by the plugin. */
+    limit: number;
+};
+/** Function-style mention provider contract. */
+type MentionProviderFn = (query: MentionQuery) => Promise<MentionItem[]>;
+/** Object-style mention provider contract. */
+type MentionProviderObject = {
+    search: MentionProviderFn;
+};
+/** Supported mention provider shapes. */
+type MentionProvider = MentionProviderFn | MentionProviderObject;
+/** Origin of a mention render call. */
+type MentionRenderSource = "insert" | "paste" | "refresh";
+/** Parameters passed to `renderMention` customization hook. */
+type MentionRenderArgs = {
+    /** Mention metadata associated with the rendered element. */
+    item: MentionItem;
+    /** Trigger symbol used for this mention. */
+    trigger: string;
+    /** Default display text, typically `${trigger}${displayName}`. */
+    defaultText: string;
+    /** Mention anchor element that can be styled/customized by integrator. */
+    element: HTMLAnchorElement;
+    /** Render reason, useful for conditional logic. */
+    source: MentionRenderSource;
+    /** Arbitrary app context provided through plugin config/update API. */
+    context?: unknown;
+};
+/** Main plugin configuration. */
+type MentionsConfig = {
+    /** Editor.js holder element or element id. */
+    holder: string | HTMLElement;
+    /** Data source for autocomplete candidates. */
+    provider: MentionProvider;
+    /** Trigger symbols that activate mention lookup. Defaults to `["@"]`. */
+    triggerSymbols?: string[];
+    /** Maximum autocomplete results. */
+    maxResults?: number;
+    /** Minimum query length after trigger before provider call. */
+    minChars?: number;
+    /** Debounce in milliseconds for provider calls. */
+    debounceMs?: number;
+    /** Optional custom dropdown root class name. */
+    className?: string;
+    /** Callback fired when mention is selected and inserted. */
+    onSelect?: (item: MentionItem) => void;
+    /** Custom HTML renderer for dropdown rows. */
+    renderItem?: (item: MentionItem) => string;
+    /** Hook to customize mention anchor rendering/styling in editor content. */
+    renderMention?: (args: MentionRenderArgs) => void;
+    /** Mutable external context consumed by `renderMention`. */
+    mentionRenderContext?: unknown;
+};
+/**
+ * Persisted mention entity stored alongside plain text content.
+ *
+ * @example
+ * {
+ *   "type": "mention",
+ *   "id": "u-1002",
+ *   "displayName": "Joanna Smith",
+ *   "start": 0,
+ *   "end": 13,
+ *   "trigger": "@",
+ *   "description": "Product Management",
+ *   "image": "https://example.com/avatars/u-1002.png",
+ *   "link": "https://example.local/users/u-1002"
+ * }
+ */
+type MentionEntity = {
+    type: "mention";
+    /** Stable backend identifier. */
+    id: string;
+    /** Display name at time of serialization. */
+    displayName: string;
+    /** Start offset (inclusive) in plain text. */
+    start: number;
+    /** End offset (exclusive) in plain text. */
+    end: number;
+    /** Trigger symbol used for rendering. */
+    trigger?: string;
+    /** Optional metadata copied from mention source. */
+    description?: string;
+    image?: string;
+    link?: string;
+};
+/** Minimal Editor.js block shape used by serializer helpers. */
+type EditorJSBlockLike = {
+    id?: string;
+    type: string;
+    data: Record<string, unknown>;
+};
+/** Minimal Editor.js output shape used by serializer helpers. */
+type EditorJSOutputLike = {
+    time?: number;
+    version?: string;
+    blocks: EditorJSBlockLike[];
+};
+
+declare class EditorJSMentions {
+    private holder;
+    private config;
+    private provider;
+    private dropdown;
+    private debounceTimer;
+    private requestSerial;
+    private activeContext;
+    private destroyed;
+    private tooltipRoot;
+    constructor(config: MentionsConfig);
+    setMentionRenderContext(context: unknown): void;
+    refreshMentionRendering(): void;
+    destroy(): void;
+    private bind;
+    private onClick;
+    private onDocumentMouseDown;
+    private onInput;
+    private onCopy;
+    private onCut;
+    private onPaste;
+    private onKeyDown;
+    private handleCopyOrCut;
+    private evaluateAndFetch;
+    private readActiveContext;
+    private selectMention;
+    private showTooltip;
+    private hideTooltip;
+    private readMentionFromElement;
+    private applyMentionRendering;
+    private getCaretRect;
+}
+
+type RestProviderOptions = {
+    endpoint: string;
+    queryParam?: string;
+    triggerParam?: string;
+    limitParam?: string;
+    fetchInit?: RequestInit;
+    mapResponse?: (json: unknown) => MentionItem[];
+};
+declare function createRestMentionProvider(options: RestProviderOptions): MentionProviderFn;
+
+declare function encodeMentionsInOutput(output: EditorJSOutputLike): EditorJSOutputLike;
+declare function decodeMentionsInOutput(output: EditorJSOutputLike): EditorJSOutputLike;
+declare function encodeMentionsFromHtml(html: string): {
+    text: string;
+    entities: MentionEntity[];
+};
+
+export { type EditorJSBlockLike, EditorJSMentions, type EditorJSOutputLike, type MentionEntity, type MentionItem, type MentionProvider, type MentionProviderFn, type MentionProviderObject, type MentionQuery, type MentionRenderArgs, type MentionRenderSource, type MentionsConfig, createRestMentionProvider, decodeMentionsInOutput, encodeMentionsFromHtml, encodeMentionsInOutput };