@itsammarb/mention-editor 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ammar B.
+
+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,70 @@
+# @nexcore/mention-editor
+
+A Discord-style `@mention` rich-text editor built on [Slate.js](https://www.slatejs.org/). Mentions are atomic (void + inline) nodes: backspacing next to one deletes it whole, and the suggestion menu tracks the real caret position via `ReactEditor.toDOMRange`.
+
+## Install
+
+```sh
+npm install @nexcore/mention-editor slate slate-react slate-history
+```
+
+Peer dependencies: React 18 or 19, `slate` and `slate-react` `^0.94.0`. No Tailwind setup required on your end — see [Styling](#styling).
+
+## Usage
+
+```tsx
+import { MentionEditor } from '@nexcore/mention-editor';
+import '@nexcore/mention-editor/styles.css';
+
+const fields = [
+  { id: 'a1b2c3d4-0000-0000-0000-000000000001', label: 'Landlord Name' },
+  { id: 'a1b2c3d4-0000-0000-0000-000000000002', label: 'Monthly Rent' },
+];
+
+function ClauseEditor() {
+  const [value, setValue] = useState('Hello <@a1b2c3d4-0000-0000-0000-000000000001>, welcome.');
+
+  return (
+    <MentionEditor
+      value={value}
+      fields={fields}
+      onChange={setValue}
+      placeholder="Type @ to reference a field..."
+      dir="rtl" // or "ltr"; omit to let the browser infer it
+      rows={4}
+    />
+  );
+}
+```
+
+## Wire format
+
+`value` / `onChange` use a plain string, not a Slate document: mentions are written as the field's `id` wrapped in `<@` and `>`, e.g.:
+
+```
+Hello <@a1b2c3d4-0000-0000-0000-000000000001>, welcome.
+```
+
+`serialize`/`deserialize` (also exported) convert between this string and Slate's internal `Descendant[]` tree. `\n` in the string is a paragraph break. The closing `>` means any id shape works out of the box — no separate id-format configuration needed.
+
+## Props
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Wire-format content (controlled). |
+| `fields` | `{ id: string; label: string }[]` | Fields offered in the `@` suggestion menu; filter/localize before passing in. |
+| `onChange` | `(value: string) => void` | Called with the new wire-format string. |
+| `dir` | `'ltr' \| 'rtl'` | Applied to the editable surface for correct caret/bidi behavior. |
+| `disabled` | `boolean` | Makes the editor read-only. |
+| `isError` | `boolean` | Applies the invalid-state styling. |
+| `placeholder` | `string` | Shown when the editor is empty. |
+| `rows` | `number` | Approximate visible height, `<textarea rows>`-equivalent. |
+| `className` | `string` | Extra class name(s) on the root container. |
+
+## Styling
+
+The default look is authored with Tailwind utility classes internally, but compiled at *this package's* build time into a self-contained `dist/styles.css` — import it once (as shown above) and it works with zero Tailwind setup on your end, whether or not your app uses Tailwind at all. The compiled CSS deliberately excludes Tailwind's Preflight (base element reset), so it can't leak out and restyle your app's own `<h1>`, `<button>`, etc.
+
+Each rendered part also carries a stable class name (`.mention-editor`, `.mention-editor__editable`, `.mention-editor__mention`, `.mention-editor__menu`, `.mention-editor__menu-item`) for overrides or e2e test selectors. Pass `className` to add to the root container, or write CSS/Tailwind rules targeting these classes directly — they ship at normal specificity (single class selectors), so a later rule wins.
+
+If your own app happens to use Tailwind and you want to reuse its utility classes against this component's internal DOM (beyond what `className` on the root reaches), you can optionally point your app's Tailwind config/`@source` at `node_modules/@nexcore/mention-editor/dist` — but this is purely an opt-in extra, not required for the component to work or look right.

package/dist/MentionEditor.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import { MentionFieldOption } from './types';
+export interface MentionEditorProps {
+    /** Wire-format string, e.g. `"Hello <@a1b2c3d4-...>, pay rent."` */
+    value: string;
+    /** Already localized/filtered list of fields the consumer wants offered. */
+    fields: MentionFieldOption[];
+    onChange?: (value: string) => void;
+    dir?: 'ltr' | 'rtl';
+    disabled?: boolean;
+    isError?: boolean;
+    placeholder?: string;
+    /** Approximate visible height, textarea-`rows`-equivalent. */
+    rows?: number;
+    className?: string;
+}
+export declare function MentionEditor(props: MentionEditorProps): React.JSX.Element;

package/dist/MentionEditor.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MentionEditor = MentionEditor;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const slate_1 = require("slate");
+const slate_react_1 = require("slate-react");
+const slate_history_1 = require("slate-history");
+const types_1 = require("./types");
+const serialize_1 = require("./serialize");
+const MentionMenu_1 = require("./MentionMenu");
+function MentionEditor(props) {
+    const { value, fields, onChange, dir, disabled = false, isError = false, placeholder, rows, className, } = props;
+    // `generation` forces a full remount of the Slate editor instance whenever the
+    // `value` prop changes for a reason *other* than our own onChange echoing back
+    // down (e.g. the consumer swaps to editing a different record). See the
+    // render-time reset block below for the echo-vs-external distinction.
+    const [generation, setGeneration] = (0, react_1.useState)(0);
+    const editor = (0, react_1.useMemo)(() => withMentions((0, slate_history_1.withHistory)((0, slate_react_1.withReact)((0, slate_1.createEditor)()))), [generation]);
+    const lastEmittedRef = (0, react_1.useRef)(value);
+    const [committedValue, setCommittedValue] = (0, react_1.useState)(value);
+    const [slateValue, setSlateValue] = (0, react_1.useState)(() => value ? (0, serialize_1.deserialize)(value, fields) : types_1.INITIAL_VALUE);
+    const [target, setTarget] = (0, react_1.useState)(null);
+    const [index, setIndex] = (0, react_1.useState)(0);
+    const [search, setSearch] = (0, react_1.useState)('');
+    if (value !== committedValue) {
+        setCommittedValue(value);
+        if (value !== lastEmittedRef.current) {
+            setSlateValue(value ? (0, serialize_1.deserialize)(value, fields) : types_1.INITIAL_VALUE);
+            setGeneration((g) => g + 1);
+            setTarget(null);
+            setSearch('');
+            setIndex(0);
+            lastEmittedRef.current = value;
+        }
+    }
+    // Filter fields based on the search query
+    const filteredFields = (0, react_1.useMemo)(() => {
+        if (!search)
+            return fields.slice(0, 10); // Show top 10 if no search
+        return fields
+            .filter((field) => field.label.toLowerCase().includes(search.toLowerCase()))
+            .slice(0, 10);
+    }, [fields, search]);
+    // Calculate the DOM position for the popup menu. This has to run in a layout
+    // effect, *after* the DOM commits -- `target` and the text content it points
+    // into are usually set in the very same state update (the user just typed
+    // the character that both changed the content and opened the menu), so
+    // resolving the DOM range during render itself would run before the new
+    // text node exists, and silently fail.
+    const [menuTargetRect, setMenuTargetRect] = (0, react_1.useState)(null);
+    (0, react_1.useLayoutEffect)(() => {
+        if (!target) {
+            setMenuTargetRect(null);
+            return;
+        }
+        const recompute = () => {
+            try {
+                const domRange = slate_react_1.ReactEditor.toDOMRange(editor, target);
+                setMenuTargetRect(domRange.getBoundingClientRect());
+            }
+            catch (_a) {
+                setMenuTargetRect(null);
+            }
+        };
+        recompute();
+        // getBoundingClientRect() is viewport-relative, so it goes stale the
+        // moment any scrollable ancestor scrolls (capture phase catches that,
+        // since plain `scroll` events don't bubble) or the window resizes --
+        // recompute it fresh rather than trusting the last-known value.
+        window.addEventListener('scroll', recompute, true);
+        window.addEventListener('resize', recompute);
+        return () => {
+            window.removeEventListener('scroll', recompute, true);
+            window.removeEventListener('resize', recompute);
+        };
+    }, [target, editor, slateValue]);
+    // --- CORE LOGIC: Trigger Detection ---
+    const handleChange = (0, react_1.useCallback)((newValue) => {
+        setSlateValue(newValue);
+        const serialized = (0, serialize_1.serialize)(newValue);
+        if (serialized !== lastEmittedRef.current) {
+            lastEmittedRef.current = serialized;
+            setCommittedValue(serialized);
+            onChange === null || onChange === void 0 ? void 0 : onChange(serialized);
+        }
+        const mention = findMentionTrigger(editor);
+        if (mention) {
+            setTarget(mention.range);
+            setSearch(mention.search);
+            setIndex(0);
+        }
+        else {
+            setTarget(null);
+        }
+    }, [editor, onChange]);
+    // --- CORE LOGIC: Insertion ---
+    const selectField = (0, react_1.useCallback)((selectedField) => {
+        if (target) {
+            slate_1.Transforms.select(editor, target);
+            slate_1.Transforms.delete(editor);
+            slate_1.Transforms.insertNodes(editor, {
+                type: 'mention',
+                field: selectedField,
+                children: [{ text: '' }],
+            }, { select: true });
+            // Move cursor after the inserted void mention so the user can keep typing
+            slate_1.Transforms.move(editor, { distance: 1, unit: 'offset' });
+            setTarget(null);
+        }
+    }, [editor, target]);
+    // --- KEYBOARD NAVIGATION ---
+    const handleKeyDown = (0, react_1.useCallback)((event) => {
+        if (target) {
+            switch (event.key) {
+                case 'ArrowDown': {
+                    event.preventDefault();
+                    const nextIndex = index >= filteredFields.length - 1 ? 0 : index + 1;
+                    setIndex(nextIndex);
+                    break;
+                }
+                case 'ArrowUp': {
+                    event.preventDefault();
+                    const prevIndex = index <= 0 ? filteredFields.length - 1 : index - 1;
+                    setIndex(prevIndex);
+                    break;
+                }
+                case 'Tab':
+                case 'Enter':
+                    event.preventDefault();
+                    selectField(filteredFields[index]);
+                    break;
+                case 'Escape':
+                    event.preventDefault();
+                    setTarget(null);
+                    break;
+            }
+        }
+    }, [target, index, filteredFields, selectField]);
+    const rootClassName = [
+        'mention-editor relative rounded-md border bg-white dark:bg-neutral-900',
+        isError ? 'border-red-500' : 'border-gray-300 dark:border-neutral-700',
+        disabled && 'opacity-60',
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const editableStyle = rows ? { minHeight: `${rows * 1.5}em` } : undefined;
+    return ((0, jsx_runtime_1.jsx)(slate_react_1.Slate, { editor: editor, value: slateValue, onChange: handleChange, children: (0, jsx_runtime_1.jsxs)("div", { className: rootClassName, children: [(0, jsx_runtime_1.jsx)(slate_react_1.Editable, { className: "mention-editor__editable min-h-[44px] px-3 py-2 text-base leading-6 text-gray-900 outline-none dark:text-gray-100", style: editableStyle, dir: dir, readOnly: disabled, onKeyDown: handleKeyDown, placeholder: placeholder, renderElement: (elementProps) => (0, jsx_runtime_1.jsx)(Element, { ...elementProps }), renderPlaceholder: renderPlaceholder }), target && ((0, jsx_runtime_1.jsx)(MentionMenu_1.MentionMenu, { fields: filteredFields, selectedIndex: index, onSelect: selectField, onHover: setIndex, targetRect: menuTargetRect }))] }) }, generation));
+}
+// slate-react's default placeholder renders at a fixed dim-black opacity,
+// which reads poorly in dark mode. Overriding it lets the placeholder use
+// real (theme-aware) Tailwind colors at full opacity instead.
+const renderPlaceholder = ({ attributes, children }) => ((0, jsx_runtime_1.jsx)("span", { ...attributes, style: { ...attributes.style, opacity: 1 }, className: "text-gray-400 dark:text-neutral-500", children: children }));
+// --- TRIGGER DETECTION ---
+const MAX_MENTION_SEARCH_LENGTH = 50;
+/**
+ * Finds an in-progress `@search` token immediately before the cursor, if any.
+ *
+ * This deliberately walks backward one character at a time via
+ * `unit: 'character'` rather than `unit: 'word'`: Slate's word-unit movement
+ * skips *past* a lone trailing `@` to find the nearest real word, which makes
+ * it useless for detecting "the user just typed @ with nothing after it yet"
+ * -- exactly the moment this needs to fire. Character-unit stepping is the
+ * one primitive that behaves predictably here, including hopping over void
+ * mentions as a single atomic step.
+ *
+ * Recomputing the full range (both ends) on every keystroke -- rather than
+ * caching the anchor once and trusting a stale focus -- also means selecting
+ * a suggestion always deletes exactly the `@search` text typed so far, never
+ * leaving leftover characters behind.
+ */
+const findMentionTrigger = (editor) => {
+    const { selection } = editor;
+    if (!selection || !slate_1.Range.isCollapsed(selection))
+        return null;
+    const [start] = slate_1.Range.edges(selection);
+    let point = start;
+    let text = '';
+    for (let i = 0; i < MAX_MENTION_SEARCH_LENGTH; i++) {
+        const prev = slate_1.Editor.before(editor, point, { unit: 'character' });
+        if (!prev)
+            break;
+        const char = slate_1.Editor.string(editor, { anchor: prev, focus: point });
+        if (char === '' || /\s/.test(char))
+            break; // hit a void boundary or whitespace
+        text = char + text;
+        point = prev;
+        if (char === '@')
+            break;
+    }
+    if (!text.startsWith('@'))
+        return null;
+    // The '@' must be at the very start of the block or preceded by whitespace,
+    // never mid-word (e.g. "user@").
+    const charBeforeAt = slate_1.Editor.before(editor, point, { unit: 'character' });
+    if (charBeforeAt) {
+        const charBefore = slate_1.Editor.string(editor, { anchor: charBeforeAt, focus: point });
+        if (charBefore !== '' && !/\s/.test(charBefore))
+            return null;
+    }
+    return { range: { anchor: point, focus: start }, search: text.slice(1) };
+};
+// --- SLATE PLUGIN & RENDERERS ---
+// Extends the editor to handle specific mention behaviors (like deleting the whole node on backspace)
+const withMentions = (editor) => {
+    const { isInline, isVoid, deleteBackward } = editor;
+    editor.isInline = (element) => {
+        return element.type === 'mention' ? true : isInline(element);
+    };
+    editor.isVoid = (element) => {
+        return element.type === 'mention' ? true : isVoid(element);
+    };
+    // Custom delete behavior: if you backspace a mention, delete the whole thing
+    editor.deleteBackward = (...args) => {
+        const { selection } = editor;
+        if (selection && slate_1.Range.isCollapsed(selection)) {
+            const before = slate_1.Editor.before(editor, selection.anchor);
+            if (before) {
+                const [match] = Array.from(slate_1.Editor.nodes(editor, {
+                    at: before,
+                    match: (n) => n.type === 'mention',
+                }));
+                if (match) {
+                    slate_1.Transforms.delete(editor, { at: match[1] });
+                    return;
+                }
+            }
+        }
+        deleteBackward(...args);
+    };
+    return editor;
+};
+// Renders Slate nodes into React components
+const Element = ({ attributes, children, element }) => {
+    var _a;
+    switch (element.type) {
+        case 'mention':
+            return ((0, jsx_runtime_1.jsxs)("span", { ...attributes, contentEditable: false, className: "mention-editor__mention cursor-default text-blue-600 underline decoration-1 underline-offset-2 [unicode-bidi:isolate] dark:text-blue-400", children: ["@", (_a = element.field) === null || _a === void 0 ? void 0 : _a.label, children] }));
+        default:
+            return ((0, jsx_runtime_1.jsx)("p", { ...attributes, className: "mention-editor__paragraph m-0 [&+&]:mt-1", children: children }));
+    }
+};

package/dist/MentionMenu.d.ts

@@ -0,0 +1,11 @@
+import React from 'react';
+import { MentionFieldOption } from './types';
+interface MentionMenuProps {
+    fields: MentionFieldOption[];
+    selectedIndex: number;
+    onSelect: (field: MentionFieldOption) => void;
+    onHover: (index: number) => void;
+    targetRect: DOMRect | null;
+}
+export declare const MentionMenu: React.FC<MentionMenuProps>;
+export {};

package/dist/MentionMenu.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MentionMenu = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_dom_1 = require("react-dom");
+const MentionMenu = ({ fields, selectedIndex, onSelect, onHover, targetRect, }) => {
+    if (!targetRect || fields.length === 0)
+        return null;
+    // Rendered into document.body via a portal and positioned with `fixed` using
+    // raw viewport coordinates from getBoundingClientRect(). This is what makes
+    // the menu land correctly regardless of whether the editor sits inside a
+    // scrollable container, a `position: fixed` modal, or a modal nested inside
+    // another modal: portaling to <body> means there's no transformed/positioned
+    // ancestor between the menu and the viewport to throw off `fixed` coordinates.
+    // The caller (MentionEditor) keeps `targetRect` fresh across scroll/resize.
+    return (0, react_dom_1.createPortal)((0, jsx_runtime_1.jsx)("div", { className: "mention-editor__menu z-[9999] w-[280px] max-h-[300px] overflow-y-auto rounded-md border border-gray-300 bg-white py-1 shadow-lg dark:border-neutral-700 dark:bg-neutral-800", style: {
+            position: 'fixed',
+            top: targetRect.bottom + 8,
+            left: targetRect.left,
+        }, children: fields.map((field, i) => ((0, jsx_runtime_1.jsx)("div", { className: 'mention-editor__menu-item cursor-pointer px-3 py-2 text-gray-900 dark:text-gray-100' +
+                (i === selectedIndex ? ' bg-indigo-50 dark:bg-neutral-700' : ''), onClick: (e) => {
+                e.preventDefault();
+                onSelect(field);
+            }, onMouseDown: (e) => e.preventDefault(), onMouseEnter: () => onHover(i), children: field.label }, field.id))) }), document.body);
+};
+exports.MentionMenu = MentionMenu;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { MentionEditor } from './MentionEditor';
+export type { MentionEditorProps } from './MentionEditor';
+export { serialize, deserialize, serializeToDiscordMarkup } from './serialize';
+export type { MentionFieldOption } from './types';
+export { INITIAL_VALUE, MENTION_OPEN, MENTION_CLOSE } from './types';

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MENTION_CLOSE = exports.MENTION_OPEN = exports.INITIAL_VALUE = exports.serializeToDiscordMarkup = exports.deserialize = exports.serialize = exports.MentionEditor = void 0;
+var MentionEditor_1 = require("./MentionEditor");
+Object.defineProperty(exports, "MentionEditor", { enumerable: true, get: function () { return MentionEditor_1.MentionEditor; } });
+var serialize_1 = require("./serialize");
+Object.defineProperty(exports, "serialize", { enumerable: true, get: function () { return serialize_1.serialize; } });
+Object.defineProperty(exports, "deserialize", { enumerable: true, get: function () { return serialize_1.deserialize; } });
+Object.defineProperty(exports, "serializeToDiscordMarkup", { enumerable: true, get: function () { return serialize_1.serializeToDiscordMarkup; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "INITIAL_VALUE", { enumerable: true, get: function () { return types_1.INITIAL_VALUE; } });
+Object.defineProperty(exports, "MENTION_OPEN", { enumerable: true, get: function () { return types_1.MENTION_OPEN; } });
+Object.defineProperty(exports, "MENTION_CLOSE", { enumerable: true, get: function () { return types_1.MENTION_CLOSE; } });

package/dist/serialize.d.ts

@@ -0,0 +1,22 @@
+import { Descendant } from 'slate';
+import { MentionFieldOption } from './types';
+/**
+ * Serializes Slate content to the wire format string, e.g.
+ * `"Hello <@a1b2c3d4-...>, pay rent."`.
+ *
+ * Each top-level paragraph node becomes one line of output, joined by `\n` —
+ * `deserialize` treats every `\n` as a paragraph break (not a soft line break
+ * within a paragraph), so this is the inverse operation.
+ */
+export declare const serialize: (nodes: Descendant[]) => string;
+/** @deprecated use {@link serialize} */
+export declare const serializeToDiscordMarkup: (nodes: Descendant[]) => string;
+/**
+ * Parses a wire format string back into a Slate `Descendant[]` value, resolving
+ * each `<@id>` token against `fields` to recover its display label. Tokens whose
+ * id isn't found in `fields` still render (falling back to the raw id as the
+ * label) rather than being dropped, so content never silently loses a mention.
+ *
+ * Inverse of `serialize`: every `\n` in `value` starts a new paragraph node.
+ */
+export declare const deserialize: (value: string, fields?: MentionFieldOption[]) => Descendant[];

package/dist/serialize.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deserialize = exports.serializeToDiscordMarkup = exports.serialize = void 0;
+const slate_1 = require("slate");
+const types_1 = require("./types");
+const isMentionElement = (node) => !slate_1.Text.isText(node) && node.type === 'mention';
+const MENTION_TOKEN_REGEX = new RegExp(`${types_1.MENTION_OPEN}([^${types_1.MENTION_CLOSE}]+)${types_1.MENTION_CLOSE}`, 'g');
+/**
+ * Serializes Slate content to the wire format string, e.g.
+ * `"Hello <@a1b2c3d4-...>, pay rent."`.
+ *
+ * Each top-level paragraph node becomes one line of output, joined by `\n` —
+ * `deserialize` treats every `\n` as a paragraph break (not a soft line break
+ * within a paragraph), so this is the inverse operation.
+ */
+const serialize = (nodes) => {
+    return nodes.map(serializeParagraph).join('\n');
+};
+exports.serialize = serialize;
+const serializeParagraph = (node) => {
+    if (slate_1.Text.isText(node) || !('children' in node))
+        return '';
+    return node.children.map(serializeInline).join('');
+};
+const serializeInline = (node) => {
+    if (isMentionElement(node)) {
+        return `${types_1.MENTION_OPEN}${node.field.id}${types_1.MENTION_CLOSE}`;
+    }
+    return node.text;
+};
+/** @deprecated use {@link serialize} */
+exports.serializeToDiscordMarkup = exports.serialize;
+/**
+ * Parses a wire format string back into a Slate `Descendant[]` value, resolving
+ * each `<@id>` token against `fields` to recover its display label. Tokens whose
+ * id isn't found in `fields` still render (falling back to the raw id as the
+ * label) rather than being dropped, so content never silently loses a mention.
+ *
+ * Inverse of `serialize`: every `\n` in `value` starts a new paragraph node.
+ */
+const deserialize = (value, fields = []) => {
+    const fieldsById = new Map(fields.map((field) => [field.id, field]));
+    return value.split('\n').map((line) => {
+        return { type: 'paragraph', children: deserializeLine(line, fieldsById) };
+    });
+};
+exports.deserialize = deserialize;
+const deserializeLine = (line, fieldsById) => {
+    var _a;
+    // Slate requires every inline (void) element to be surrounded by text nodes,
+    // including at the start/end of the block and between two adjacent mentions.
+    // So every push below is unconditional, even when the slice is ''.
+    const children = [];
+    let lastIndex = 0;
+    MENTION_TOKEN_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MENTION_TOKEN_REGEX.exec(line))) {
+        children.push({ text: line.slice(lastIndex, match.index) });
+        const id = match[1];
+        const field = (_a = fieldsById.get(id)) !== null && _a !== void 0 ? _a : { id, label: id };
+        children.push({ type: 'mention', field, children: [{ text: '' }] });
+        lastIndex = match.index + match[0].length;
+    }
+    children.push({ text: line.slice(lastIndex) });
+    return children;
+};

package/dist/styles.css

@@ -0,0 +1,2 @@
+/*! tailwindcss v4.3.2 | MIT License | https://tailwindcss.com */
+@layer properties{@supports (((-webkit-hyphens:none)) and (not (margin-trim:inline))) or ((-moz-orient:inline) and (not (color:rgb(from red r g b)))){*,:before,:after,::backdrop{--tw-border-style:solid;--tw-leading:initial;--tw-shadow:0 0 #0000;--tw-shadow-color:initial;--tw-shadow-alpha:100%;--tw-inset-shadow:0 0 #0000;--tw-inset-shadow-color:initial;--tw-inset-shadow-alpha:100%;--tw-ring-color:initial;--tw-ring-shadow:0 0 #0000;--tw-inset-ring-color:initial;--tw-inset-ring-shadow:0 0 #0000;--tw-ring-inset:initial;--tw-ring-offset-width:0px;--tw-ring-offset-color:#fff;--tw-ring-offset-shadow:0 0 #0000;--tw-blur:initial;--tw-brightness:initial;--tw-contrast:initial;--tw-grayscale:initial;--tw-hue-rotate:initial;--tw-invert:initial;--tw-opacity:initial;--tw-saturate:initial;--tw-sepia:initial;--tw-drop-shadow:initial;--tw-drop-shadow-color:initial;--tw-drop-shadow-alpha:100%;--tw-drop-shadow-size:initial}}}:root,:host{--color-red-500:oklch(63.7% .237 25.331);--color-blue-400:oklch(70.7% .165 254.624);--color-blue-600:oklch(54.6% .245 262.881);--color-indigo-50:oklch(96.2% .018 272.314);--color-gray-100:oklch(96.7% .003 264.542);--color-gray-300:oklch(87.2% .01 258.338);--color-gray-400:oklch(70.7% .022 261.325);--color-gray-900:oklch(21% .034 264.665);--color-neutral-500:oklch(55.6% 0 0);--color-neutral-700:oklch(37.1% 0 0);--color-neutral-800:oklch(26.9% 0 0);--color-neutral-900:oklch(20.5% 0 0);--color-white:#fff;--spacing:.25rem;--text-base:1rem;--text-base--line-height:calc(1.5 / 1);--radius-md:.375rem}.visible{visibility:visible}.fixed{position:fixed}.relative{position:relative}.z-\[9999\]{z-index:9999}.m-0{margin:0}.block{display:block}.inline{display:inline}.max-h-\[300px\]{max-height:300px}.min-h-\[44px\]{min-height:44px}.w-\[280px\]{width:280px}.cursor-default{cursor:default}.cursor-pointer{cursor:pointer}.resize{resize:both}.overflow-y-auto{overflow-y:auto}.rounded-md{border-radius:var(--radius-md)}.border{border-style:var(--tw-border-style);border-width:1px}.border-gray-300{border-color:var(--color-gray-300)}.border-red-500{border-color:var(--color-red-500)}.bg-indigo-50{background-color:var(--color-indigo-50)}.bg-white{background-color:var(--color-white)}.px-3{padding-inline:calc(var(--spacing) * 3)}.py-1{padding-block:var(--spacing)}.py-2{padding-block:calc(var(--spacing) * 2)}.text-base{font-size:var(--text-base);line-height:var(--tw-leading,var(--text-base--line-height))}.leading-6{--tw-leading:calc(var(--spacing) * 6);line-height:calc(var(--spacing) * 6)}.text-blue-600{color:var(--color-blue-600)}.text-gray-400{color:var(--color-gray-400)}.text-gray-900{color:var(--color-gray-900)}.underline{text-decoration-line:underline}.decoration-1{text-decoration-thickness:1px}.underline-offset-2{text-underline-offset:2px}.opacity-60{opacity:.6}.shadow-lg{--tw-shadow:0 10px 15px -3px var(--tw-shadow-color,#0000001a), 0 4px 6px -4px var(--tw-shadow-color,#0000001a);box-shadow:var(--tw-inset-shadow), var(--tw-inset-ring-shadow), var(--tw-ring-offset-shadow), var(--tw-ring-shadow), var(--tw-shadow)}.blur{--tw-blur:blur(8px);filter:var(--tw-blur,) var(--tw-brightness,) var(--tw-contrast,) var(--tw-grayscale,) var(--tw-hue-rotate,) var(--tw-invert,) var(--tw-saturate,) var(--tw-sepia,) var(--tw-drop-shadow,)}.outline-none{--tw-outline-style:none;outline-style:none}.\[unicode-bidi\:isolate\]{unicode-bidi:isolate}@media (prefers-color-scheme:dark){.dark\:border-neutral-700{border-color:var(--color-neutral-700)}.dark\:bg-neutral-700{background-color:var(--color-neutral-700)}.dark\:bg-neutral-800{background-color:var(--color-neutral-800)}.dark\:bg-neutral-900{background-color:var(--color-neutral-900)}.dark\:text-blue-400{color:var(--color-blue-400)}.dark\:text-gray-100{color:var(--color-gray-100)}.dark\:text-neutral-500{color:var(--color-neutral-500)}}.\[\&\+\&\]\:mt-1+.\[\&\+\&\]\:mt-1{margin-top:var(--spacing)}@property --tw-border-style{syntax:"*";inherits:false;initial-value:solid}@property --tw-leading{syntax:"*";inherits:false}@property --tw-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-shadow-color{syntax:"*";inherits:false}@property --tw-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-inset-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-inset-shadow-color{syntax:"*";inherits:false}@property --tw-inset-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-ring-color{syntax:"*";inherits:false}@property --tw-ring-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-inset-ring-color{syntax:"*";inherits:false}@property --tw-inset-ring-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-ring-inset{syntax:"*";inherits:false}@property --tw-ring-offset-width{syntax:"<length>";inherits:false;initial-value:0}@property --tw-ring-offset-color{syntax:"*";inherits:false;initial-value:#fff}@property --tw-ring-offset-shadow{syntax:"*";inherits:false;initial-value:0 0 #0000}@property --tw-blur{syntax:"*";inherits:false}@property --tw-brightness{syntax:"*";inherits:false}@property --tw-contrast{syntax:"*";inherits:false}@property --tw-grayscale{syntax:"*";inherits:false}@property --tw-hue-rotate{syntax:"*";inherits:false}@property --tw-invert{syntax:"*";inherits:false}@property --tw-opacity{syntax:"*";inherits:false}@property --tw-saturate{syntax:"*";inherits:false}@property --tw-sepia{syntax:"*";inherits:false}@property --tw-drop-shadow{syntax:"*";inherits:false}@property --tw-drop-shadow-color{syntax:"*";inherits:false}@property --tw-drop-shadow-alpha{syntax:"<percentage>";inherits:false;initial-value:100%}@property --tw-drop-shadow-size{syntax:"*";inherits:false}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+import { BaseEditor, Descendant } from 'slate';
+import { ReactEditor } from 'slate-react';
+import { HistoryEditor } from 'slate-history';
+export interface MentionFieldOption {
+    id: string;
+    label: string;
+}
+export type CustomText = {
+    text: string;
+};
+export type MentionElement = {
+    type: 'mention';
+    field: MentionFieldOption;
+    children: CustomText[];
+};
+export type ParagraphElement = {
+    type: 'paragraph';
+    children: (CustomText | MentionElement)[];
+};
+declare module 'slate' {
+    interface CustomTypes {
+        Editor: BaseEditor & ReactEditor & HistoryEditor;
+        Element: ParagraphElement | MentionElement;
+        Text: CustomText;
+    }
+}
+export declare const INITIAL_VALUE: Descendant[];
+export declare const MENTION_OPEN = "<@";
+export declare const MENTION_CLOSE = ">";

package/dist/types.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MENTION_CLOSE = exports.MENTION_OPEN = exports.INITIAL_VALUE = void 0;
+exports.INITIAL_VALUE = [
+    {
+        type: 'paragraph',
+        children: [{ text: '' }],
+    },
+];
+// Delimiters wrapping a mention's id in the wire format, e.g. `<@a1b2c3d4-...>`.
+exports.MENTION_OPEN = '<@';
+exports.MENTION_CLOSE = '>';

package/package.json

@@ -0,0 +1,42 @@
+{
+	"name": "@itsammarb/mention-editor",
+	"version": "1.0.0",
+	"description": "A Discord-style @mention rich-text editor built on Slate.js",
+	"license": "MIT",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./styles.css": "./dist/styles.css"
+	},
+	"scripts": {
+		"build": "tsc && tailwindcss -i src/tailwind-entry.css -o dist/styles.css --minify",
+		"prepublishOnly": "npm run build",
+		"test": "vitest run"
+	},
+	"peerDependencies": {
+		"react": "^18.0.0 || ^19.0.0",
+		"react-dom": "^18.0.0 || ^19.0.0",
+		"slate": "^0.94.0",
+		"slate-react": "^0.94.0"
+	},
+	"devDependencies": {
+		"@tailwindcss/cli": "^4.3.2",
+		"@types/react": "^19.2.15",
+		"@types/react-dom": "^19.2.3",
+		"react": "^19.2.3",
+		"react-dom": "^19.2.3",
+		"slate": "^0.94.0",
+		"slate-history": "^0.93.0",
+		"slate-react": "^0.94.0",
+		"tailwindcss": "^4.3.2",
+		"typescript": "^5.0.0",
+		"vitest": "^4.1.10"
+	}
+}