@itsammarb/mention-editor 1.0.5 → 1.0.6

package/README.md

@@ -54,14 +54,19 @@ Hello <@a1b2c3d4-0000-0000-0000-000000000001>, welcome.
 | `value` | `string` | *(required)* | Wire-format content (controlled — the editor always reflects this string). |
 | `fields` | `{ id: string; label: string }[]` | *(required)* | Fields offered in the `@` suggestion menu; filter/localize before passing in — the component doesn't fetch or translate these itself. |
 | `onChange` | `(value: string) => void` | `undefined` | Called with the new wire-format string on every edit. Omit for a read-only display (combine with `disabled`). |
+| `onFocus` / `onBlur` | `(event: React.FocusEvent) => void` | `undefined` | Fired when the editable surface gains/loses focus — e.g. to trigger validation-on-blur in a form library. |
+| `onKeyDown` | `(event: React.KeyboardEvent) => void` | `undefined` | Called after the suggestion menu's own key handling (arrows/Tab/Enter/Escape) — e.g. to add a Cmd+Enter-to-submit shortcut. Check `event.defaultPrevented` if you need to know whether the menu already acted on the key. |
 | `dir` | `'ltr' \| 'rtl'` | `undefined` (browser infers) | Applied directly as the `dir` HTML attribute on the editable surface — required for correct caret movement and bidi layout with RTL content such as Arabic. |
 | `disabled` | `boolean` | `false` | Makes the editor read-only (`Editable`'s `readOnly`) and dims it via `opacity-60`. |
 | `isError` | `boolean` | `false` | Swaps the border to the invalid-state color (`border-red-500`). Purely visual — doesn't block typing. |
 | `placeholder` | `string` | `undefined` (no placeholder) | Shown only when the document is fully empty (a single empty paragraph) — see [Behavior notes](#behavior-notes). |
 | `rows` | `number` | `undefined` (intrinsic `min-h-11`, ~44px) | Sets `min-height` to `rows * 1.5em`, textarea-`rows`-equivalent. The editor still grows taller than this if content wraps to more lines. |
+| `maxLength` | `number` | `undefined` (no limit) | Caps the *visible* length — see [Length limits](#length-limits). |
 | `className` | `string` | `undefined` | Extra class name(s) appended to the root container, after the built-in ones — use this for layout (width, margin) or to override the built-in border/background. |
 | `colors` | `MentionEditorColors` | `undefined` (built-in defaults) | Per-instance color overrides — see [Theme colors](#theme-colors). Omitted keys keep their default. |
 
+`MentionEditor` also forwards a `ref` — see [Imperative handle](#imperative-handle).
+
 ## Exported utilities
 
 Everything importable from `@itsammarb/mention-editor`:
@@ -72,6 +77,8 @@ Everything importable from `@itsammarb/mention-editor`:
 | `MentionEditorProps` | type | Prop types for `MentionEditor`. |
 | `MentionFieldOption` | type | Shape of an entry in `fields`: `{ id: string; label: string }`. |
 | `MentionEditorColors` | type | Shape of the `colors` prop — see [Theme colors](#theme-colors). |
+| `MentionEditorHandle` | type | Shape of the imperative handle exposed via `ref` — see [Imperative handle](#imperative-handle). |
+| `getPlainTextLength(nodes: Descendant[]): number` | function | The same visible-length count `maxLength` enforces and the ref's `getPlainTextLength()` returns — each mention counts as `"@" + label.length`, not its wire-format id. |
 | `serialize(nodes: Descendant[]): string` | function | Converts a Slate `Descendant[]` tree to the wire-format string. Useful if you need to inspect/generate content outside the component (e.g. server-side). |
 | `deserialize(value: string, fields?: MentionFieldOption[]): Descendant[]` | function | Inverse of `serialize`. `fields` resolves each mention's label; an id not found in `fields` still renders, falling back to the raw id as its label. |
 | `serializeToDiscordMarkup` | function | Deprecated alias of `serialize`, kept for backwards compatibility with the pre-rename API. Prefer `serialize`. |
@@ -137,6 +144,37 @@ A `colors` value applies in both light and dark mode (the fallback is what diffe
 
 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/@itsammarb/mention-editor/dist` — but this is purely an opt-in extra, not required for the component to work or look right.
 
+## Imperative handle
+
+`MentionEditor` forwards a `ref` exposing:
+
+```tsx
+import { useRef } from 'react';
+import { MentionEditor, MentionEditorHandle } from '@itsammarb/mention-editor';
+
+const editorRef = useRef<MentionEditorHandle>(null);
+
+<MentionEditor ref={editorRef} value={value} fields={fields} onChange={setValue} />;
+
+editorRef.current?.focus();
+editorRef.current?.blur();
+editorRef.current?.getPlainTextLength(); // same count maxLength enforces against
+```
+
+There's no `value` getter on the handle since the component is fully controlled — read the current content from the `value` you already pass in (or `onChange`'s latest callback argument), not from the ref.
+
+## Length limits
+
+`maxLength` caps the *visible* length: each mention counts as `"@" + label.length`, not its (often much longer, GUID-based) wire-format id — so a 4-character mention label costs 5 toward the limit regardless of how long the underlying field id is. Typing or pasting past the limit is blocked (a paste that doesn't fully fit is truncated to what's left, not rejected outright); picking a mention from the suggestion menu that would push the total over the limit is skipped entirely rather than partially inserted.
+
+Content that's already over `maxLength` — e.g. because it was set that way via the controlled `value` prop, before a `maxLength` was added — is left alone and can still be edited or trimmed back down; only *growing* past the limit is blocked, so you're never left unable to delete your way back under it.
+
+`getPlainTextLength()` (exported standalone, and available on the [imperative handle](#imperative-handle)) returns the same count, e.g. for rendering a "120/280" counter next to the editor.
+
+## Accessibility
+
+The suggestion menu follows the ARIA listbox pattern: the menu has `role="listbox"`, each row has `role="option"` and `aria-selected`, and the editable surface carries `aria-haspopup="listbox"` plus (only while the menu is open) `aria-expanded`, `aria-controls`, and `aria-activedescendant` pointing at the keyboard-highlighted row. A search with zero matches keeps the menu open showing a "No matches" row instead of silently vanishing, so a screen reader user isn't left wondering whether the `@` did anything.
+
 ## Behavior notes
 
 Things that are fixed (not currently exposed as props), so you know what to expect rather than hunt for a setting:

package/dist/MentionEditor.d.ts

@@ -6,14 +6,30 @@ export interface MentionEditorProps {
     /** Already localized/filtered list of fields the consumer wants offered. */
     fields: MentionFieldOption[];
     onChange?: (value: string) => void;
+    onFocus?: (event: React.FocusEvent) => void;
+    onBlur?: (event: React.FocusEvent) => void;
+    /** Called after the suggestion menu's own key handling (arrows/Tab/Enter/Escape). */
+    onKeyDown?: (event: React.KeyboardEvent) => void;
     dir?: 'ltr' | 'rtl';
     disabled?: boolean;
     isError?: boolean;
     placeholder?: string;
     /** Approximate visible height, textarea-`rows`-equivalent. */
     rows?: number;
+    /**
+     * Caps the *visible* length (each mention counts as `"@" + label.length`,
+     * not its often-longer wire-format id) -- typing or pasting past this limit
+     * is blocked, but existing content already over it can still be edited/trimmed.
+     */
+    maxLength?: number;
     className?: string;
     /** Per-instance color overrides; omitted keys keep the built-in default. */
     colors?: MentionEditorColors;
 }
-export declare function MentionEditor(props: MentionEditorProps): React.JSX.Element;
+export interface MentionEditorHandle {
+    focus: () => void;
+    blur: () => void;
+    /** The same visible-length count `maxLength` is enforced against. */
+    getPlainTextLength: () => number;
+}
+export declare const MentionEditor: React.ForwardRefExoticComponent<MentionEditorProps & React.RefAttributes<MentionEditorHandle>>;

package/dist/MentionEditor.js

@@ -1,8 +1,41 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MentionEditor = MentionEditor;
+exports.MentionEditor = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
-const react_1 = require("react");
+const react_1 = __importStar(require("react"));
 const slate_1 = require("slate");
 const slate_react_1 = require("slate-react");
 const slate_history_1 = require("slate-history");
@@ -19,24 +52,38 @@ const EDITOR_COLOR_KEYS = [
     'mentionColor',
     'mentionBg',
 ];
-function MentionEditor(props) {
-    const { value, fields, onChange, dir, disabled = false, isError = false, placeholder, rows, className, colors, } = props;
+exports.MentionEditor = react_1.default.forwardRef(function MentionEditor(props, ref) {
+    const { value, fields, onChange, onFocus, onBlur, onKeyDown, dir, disabled = false, isError = false, placeholder, rows, maxLength, className, colors, } = props;
+    // Read via a ref (not captured in the `withMaxLength` closure directly) so
+    // changing `maxLength` doesn't require recreating the editor instance.
+    const maxLengthRef = (0, react_1.useRef)(maxLength);
+    maxLengthRef.current = maxLength;
     // `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 editor = (0, react_1.useMemo)(() => withMaxLength(withMentions((0, slate_history_1.withHistory)((0, slate_react_1.withReact)((0, slate_1.createEditor)()))), () => maxLengthRef.current), [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);
+    // Tracks the visible length of the current value, exposed via the ref's
+    // getPlainTextLength().
+    const plainLengthRef = (0, react_1.useRef)((0, serialize_1.getPlainTextLength)(slateValue));
     const [target, setTarget] = (0, react_1.useState)(null);
     const [index, setIndex] = (0, react_1.useState)(0);
     const [search, setSearch] = (0, react_1.useState)('');
+    (0, react_1.useImperativeHandle)(ref, () => ({
+        focus: () => slate_react_1.ReactEditor.focus(editor),
+        blur: () => slate_react_1.ReactEditor.blur(editor),
+        getPlainTextLength: () => plainLengthRef.current,
+    }), [editor]);
     if (value !== committedValue) {
         setCommittedValue(value);
         if (value !== lastEmittedRef.current) {
-            setSlateValue(value ? (0, serialize_1.deserialize)(value, fields) : types_1.INITIAL_VALUE);
+            const nextSlateValue = value ? (0, serialize_1.deserialize)(value, fields) : types_1.INITIAL_VALUE;
+            setSlateValue(nextSlateValue);
+            plainLengthRef.current = (0, serialize_1.getPlainTextLength)(nextSlateValue);
             setGeneration((g) => g + 1);
             setTarget(null);
             setSearch('');
@@ -87,6 +134,7 @@ function MentionEditor(props) {
     }, [target, editor, slateValue]);
     // --- CORE LOGIC: Trigger Detection ---
     const handleChange = (0, react_1.useCallback)((newValue) => {
+        plainLengthRef.current = (0, serialize_1.getPlainTextLength)(newValue);
         setSlateValue(newValue);
         const serialized = (0, serialize_1.serialize)(newValue);
         if (serialized !== lastEmittedRef.current) {
@@ -107,6 +155,16 @@ function MentionEditor(props) {
     // --- CORE LOGIC: Insertion ---
     const selectField = (0, react_1.useCallback)((selectedField) => {
         if (target) {
+            if (maxLength != null) {
+                // The target range is exactly "@" + the search text typed so far,
+                // so its plain length is always 1 + search.length -- compute what
+                // the total would be after swapping it for the mention, and skip
+                // the insert entirely rather than let it land over the limit.
+                const currentLength = (0, serialize_1.getPlainTextLength)(editor.children);
+                const projectedLength = currentLength - (1 + search.length) + (1 + selectedField.label.length);
+                if (projectedLength > maxLength)
+                    return;
+            }
             slate_1.Transforms.select(editor, target);
             slate_1.Transforms.delete(editor);
             slate_1.Transforms.insertNodes(editor, {
@@ -118,7 +176,7 @@ function MentionEditor(props) {
             slate_1.Transforms.move(editor, { distance: 1, unit: 'offset' });
             setTarget(null);
         }
-    }, [editor, target]);
+    }, [editor, target, maxLength, search]);
     // --- KEYBOARD NAVIGATION ---
     const handleKeyDown = (0, react_1.useCallback)((event) => {
         if (target) {
@@ -137,8 +195,10 @@ function MentionEditor(props) {
                 }
                 case 'Tab':
                 case 'Enter':
-                    event.preventDefault();
-                    selectField(filteredFields[index]);
+                    if (filteredFields.length > 0) {
+                        event.preventDefault();
+                        selectField(filteredFields[index]);
+                    }
                     break;
                 case 'Escape':
                     event.preventDefault();
@@ -146,7 +206,9 @@ function MentionEditor(props) {
                     break;
             }
         }
-    }, [target, index, filteredFields, selectField]);
+        onKeyDown === null || onKeyDown === void 0 ? void 0 : onKeyDown(event);
+    }, [target, index, filteredFields, selectField, onKeyDown]);
+    const menuId = (0, react_1.useId)();
     const rootClassName = [
         'mention-editor relative rounded-md border',
         'bg-(--mention-editor-bg,var(--color-white)) dark:bg-(--mention-editor-bg,var(--color-neutral-900))',
@@ -162,8 +224,8 @@ function MentionEditor(props) {
     // Set on the root: cascades naturally to Editable/mention/placeholder since
     // they're real DOM descendants (unlike the portaled menu -- see MentionMenu).
     const rootStyle = (0, colors_1.colorsToCssVars)(colors, EDITOR_COLOR_KEYS);
-    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, style: rootStyle, children: [(0, jsx_runtime_1.jsx)(slate_react_1.Editable, { className: "mention-editor__editable min-h-11 px-3 py-2 text-base leading-6 outline-none text-(--mention-editor-text-color,var(--color-gray-900)) dark:text-(--mention-editor-text-color,var(--color-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, colors: colors }))] }) }, generation));
-}
+    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, style: rootStyle, children: [(0, jsx_runtime_1.jsx)(slate_react_1.Editable, { className: "mention-editor__editable min-h-11 px-3 py-2 text-base leading-6 outline-none text-(--mention-editor-text-color,var(--color-gray-900)) dark:text-(--mention-editor-text-color,var(--color-gray-100))", style: editableStyle, dir: dir, readOnly: disabled, onKeyDown: handleKeyDown, onFocus: onFocus, onBlur: onBlur, placeholder: placeholder, renderElement: (elementProps) => (0, jsx_runtime_1.jsx)(Element, { ...elementProps }), renderPlaceholder: renderPlaceholder, "aria-haspopup": "listbox", "aria-expanded": !!target, "aria-controls": target ? menuId : undefined, "aria-activedescendant": target && filteredFields[index] ? (0, MentionMenu_1.getMenuOptionId)(menuId, filteredFields[index].id) : undefined }), target && ((0, jsx_runtime_1.jsx)(MentionMenu_1.MentionMenu, { id: menuId, fields: filteredFields, selectedIndex: index, onSelect: selectField, onHover: setIndex, targetRect: menuTargetRect, colors: colors }))] }) }, 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.
@@ -247,6 +309,51 @@ const withMentions = (editor) => {
     };
     return editor;
 };
+/**
+ * Enforces `maxLength` by letting an insertion happen normally and then
+ * trimming any resulting overflow off the end via a real `Transforms.delete`.
+ *
+ * The seemingly more obvious approach -- checking first and skipping the
+ * insertion entirely when it wouldn't fit -- doesn't work in this Slate
+ * version: typed input is reconciled by diffing the DOM *after* the native
+ * browser edit has already happened, not by intercepting and
+ * `preventDefault`-ing it beforehand. So refusing to call the real
+ * `insertText` still leaves the just-typed character sitting in the actual
+ * DOM, with no Slate operation left to reconcile it away. Inserting for real
+ * and then deleting the excess is itself a genuine operation, which Slate
+ * *does* correctly reconcile the DOM against.
+ *
+ * Covers typing (`insertText`), paste/drop (`insertFragment`), and new
+ * paragraphs (`insertBreak`); mention insertion goes through
+ * `Transforms.insertNodes` directly and is pre-checked separately in
+ * `selectField` instead, since skipping a discrete, deliberate action
+ * (picking a menu item) outright is the better UX there.
+ */
+const withMaxLength = (editor, getMaxLength) => {
+    const { insertText, insertFragment, insertBreak } = editor;
+    const trimToMaxLength = () => {
+        const maxLength = getMaxLength();
+        if (maxLength == null)
+            return;
+        const overBy = (0, serialize_1.getPlainTextLength)(editor.children) - maxLength;
+        if (overBy > 0) {
+            slate_1.Transforms.delete(editor, { unit: 'character', reverse: true, distance: overBy });
+        }
+    };
+    editor.insertText = (text, options) => {
+        insertText(text, options);
+        trimToMaxLength();
+    };
+    editor.insertFragment = (fragment, options) => {
+        insertFragment(fragment, options);
+        trimToMaxLength();
+    };
+    editor.insertBreak = () => {
+        insertBreak();
+        trimToMaxLength();
+    };
+    return editor;
+};
 // Renders Slate nodes into React components
 const Element = ({ attributes, children, element }) => {
     var _a;

package/dist/MentionMenu.d.ts

@@ -1,6 +1,8 @@
 import React from 'react';
 import { MentionFieldOption, MentionEditorColors } from './types';
 interface MentionMenuProps {
+    /** Element id; referenced by the editable's `aria-controls`. */
+    id: string;
     fields: MentionFieldOption[];
     selectedIndex: number;
     onSelect: (field: MentionFieldOption) => void;
@@ -8,5 +10,7 @@ interface MentionMenuProps {
     targetRect: DOMRect | null;
     colors?: MentionEditorColors;
 }
+/** Shared with `MentionEditor` so its `aria-activedescendant` points at the right row. */
+export declare const getMenuOptionId: (menuId: string, fieldId: string) => string;
 export declare const MentionMenu: React.FC<MentionMenuProps>;
 export {};

package/dist/MentionMenu.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MentionMenu = void 0;
+exports.MentionMenu = exports.getMenuOptionId = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_dom_1 = require("react-dom");
 const colors_1 = require("./colors");
@@ -10,8 +10,11 @@ const MENU_COLOR_KEYS = [
     'menuTextColor',
     'menuHighlightBg',
 ];
-const MentionMenu = ({ fields, selectedIndex, onSelect, onHover, targetRect, colors, }) => {
-    if (!targetRect || fields.length === 0)
+/** Shared with `MentionEditor` so its `aria-activedescendant` points at the right row. */
+const getMenuOptionId = (menuId, fieldId) => `${menuId}-option-${fieldId}`;
+exports.getMenuOptionId = getMenuOptionId;
+const MentionMenu = ({ id, fields, selectedIndex, onSelect, onHover, targetRect, colors, }) => {
+    if (!targetRect)
         return null;
     // Rendered into document.body via a portal and positioned with `fixed` using
     // raw viewport coordinates from getBoundingClientRect(). This is what makes
@@ -24,12 +27,12 @@ const MentionMenu = ({ fields, selectedIndex, onSelect, onHover, targetRect, col
     // `colors` has to be applied here too, not just on `.mention-editor` -- this
     // element is a portal child of `document.body`, a sibling of `.mention-editor`
     // in the real DOM, so it wouldn't inherit color overrides set there.
-    return (0, react_dom_1.createPortal)((0, jsx_runtime_1.jsx)("div", { className: "mention-editor__menu z-9999 w-70 max-h-75 overflow-y-auto rounded-md border py-1 shadow-lg border-(--mention-editor-menu-border-color,var(--color-gray-300)) dark:border-(--mention-editor-menu-border-color,var(--color-neutral-700)) bg-(--mention-editor-menu-bg,var(--color-white)) dark:bg-(--mention-editor-menu-bg,var(--color-neutral-800))", style: {
+    return (0, react_dom_1.createPortal)((0, jsx_runtime_1.jsx)("div", { id: id, role: "listbox", className: "mention-editor__menu z-9999 w-70 max-h-75 overflow-y-auto rounded-md border py-1 shadow-lg border-(--mention-editor-menu-border-color,var(--color-gray-300)) dark:border-(--mention-editor-menu-border-color,var(--color-neutral-700)) bg-(--mention-editor-menu-bg,var(--color-white)) dark:bg-(--mention-editor-menu-bg,var(--color-neutral-800))", style: {
             position: 'fixed',
             top: targetRect.bottom + 8,
             left: targetRect.left,
             ...(0, colors_1.colorsToCssVars)(colors, MENU_COLOR_KEYS),
-        }, children: fields.map((field, i) => ((0, jsx_runtime_1.jsx)("div", { className: 'mention-editor__menu-item cursor-pointer px-3 py-2' +
+        }, children: fields.length === 0 ? ((0, jsx_runtime_1.jsx)("div", { className: "mention-editor__menu-item cursor-default px-3 py-2 text-(--mention-editor-menu-text-color,var(--color-gray-900)) dark:text-(--mention-editor-menu-text-color,var(--color-gray-100)) opacity-60", children: "No matches" })) : (fields.map((field, i) => ((0, jsx_runtime_1.jsx)("div", { id: (0, exports.getMenuOptionId)(id, field.id), role: "option", "aria-selected": i === selectedIndex, className: 'mention-editor__menu-item cursor-pointer px-3 py-2' +
                 ' text-(--mention-editor-menu-text-color,var(--color-gray-900))' +
                 ' dark:text-(--mention-editor-menu-text-color,var(--color-gray-100))' +
                 (i === selectedIndex
@@ -38,6 +41,6 @@ const MentionMenu = ({ fields, selectedIndex, onSelect, onHover, targetRect, col
                     : ''), onClick: (e) => {
                 e.preventDefault();
                 onSelect(field);
-            }, onMouseDown: (e) => e.preventDefault(), onMouseEnter: () => onHover(i), children: field.label }, field.id))) }), document.body);
+            }, onMouseDown: (e) => e.preventDefault(), onMouseEnter: () => onHover(i), children: field.label }, field.id)))) }), document.body);
 };
 exports.MentionMenu = MentionMenu;

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,12 +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;
+exports.MENTION_CLOSE = exports.MENTION_OPEN = exports.INITIAL_VALUE = exports.getPlainTextLength = 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; } });
+Object.defineProperty(exports, "getPlainTextLength", { enumerable: true, get: function () { return serialize_1.getPlainTextLength; } });
 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; } });

package/dist/serialize.d.ts

@@ -11,6 +11,15 @@ import { MentionFieldOption } from './types';
 export declare const serialize: (nodes: Descendant[]) => string;
 /** @deprecated use {@link serialize} */
 export declare const serializeToDiscordMarkup: (nodes: Descendant[]) => string;
+/**
+ * Counts the *visible* length of the content -- each mention counts as
+ * `"@" + label.length`, not the length of its (often much longer, id-based)
+ * wire-format token. This is what `maxLength` enforces against, and what
+ * `MentionEditor`'s ref exposes via `getPlainTextLength()`: it matches what a
+ * user actually sees on screen, rather than penalizing them for a field with
+ * a long internal id.
+ */
+export declare const getPlainTextLength: (nodes: Descendant[]) => number;
 /**
  * Parses a wire format string back into a Slate `Descendant[]` value, resolving
  * each `<@id>` token against `fields` to recover its display label. Tokens whose

package/dist/serialize.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.deserialize = exports.serializeToDiscordMarkup = exports.serialize = void 0;
+exports.deserialize = exports.getPlainTextLength = 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';
@@ -30,6 +30,31 @@ const serializeInline = (node) => {
 };
 /** @deprecated use {@link serialize} */
 exports.serializeToDiscordMarkup = exports.serialize;
+/**
+ * Counts the *visible* length of the content -- each mention counts as
+ * `"@" + label.length`, not the length of its (often much longer, id-based)
+ * wire-format token. This is what `maxLength` enforces against, and what
+ * `MentionEditor`'s ref exposes via `getPlainTextLength()`: it matches what a
+ * user actually sees on screen, rather than penalizing them for a field with
+ * a long internal id.
+ */
+const getPlainTextLength = (nodes) => {
+    return nodes.reduce((total, node, i) => {
+        const paragraphBreak = i > 0 ? 1 : 0; // mirrors the '\n' serialize() joins paragraphs with
+        return total + paragraphBreak + paragraphPlainTextLength(node);
+    }, 0);
+};
+exports.getPlainTextLength = getPlainTextLength;
+const paragraphPlainTextLength = (node) => {
+    if (slate_1.Text.isText(node) || !('children' in node))
+        return 0;
+    return node.children.reduce((total, child) => total + inlinePlainTextLength(child), 0);
+};
+const inlinePlainTextLength = (node) => {
+    if (isMentionElement(node))
+        return 1 + node.field.label.length; // "@" + label
+    return node.text.length;
+};
 /**
  * Parses a wire format string back into a Slate `Descendant[]` value, resolving
  * each `<@id>` token against `fields` to recover its display label. Tokens whose

package/llms.txt

@@ -39,27 +39,33 @@ function Example() {
 | `value` | `string` | yes | Wire-format content; component is fully controlled. |
 | `fields` | `{ id: string; label: string }[]` | yes | Candidates for the `@` menu; already filtered/localized by the caller — no built-in fetching. |
 | `onChange` | `(value: string) => void` | no | Fires on every edit with the new wire string. |
+| `onFocus` / `onBlur` | `(event: React.FocusEvent) => void` | no | Fires on the editable surface gaining/losing focus. |
+| `onKeyDown` | `(event: React.KeyboardEvent) => void` | no | Called after the suggestion menu's own key handling. |
 | `dir` | `'ltr' \| 'rtl'` | no | Sets the real `dir` attribute on the editable surface; needed for correct RTL caret/bidi behavior. |
 | `disabled` | `boolean` | no, default `false` | Read-only + dimmed. |
 | `isError` | `boolean` | no, default `false` | Red border only; doesn't block input. |
 | `placeholder` | `string` | no | Shows only when the doc is exactly one empty paragraph. |
 | `rows` | `number` | no | `min-height = rows * 1.5em`, textarea-rows-equivalent; grows taller if content wraps further. |
+| `maxLength` | `number` | no | Caps the *visible* length (mention = `"@" + label.length`, not its id); blocks growth past the limit but never blocks shrinking, even if content is already over. |
 | `className` | `string` | no | Appended to the root container's class list. |
 | `colors` | `MentionEditorColors` | no | Per-instance color overrides; see Theme colors below. Omitted keys keep the default. |
 
+`MentionEditor` forwards a `ref`: `{ focus(): void; blur(): void; getPlainTextLength(): number }` (type: `MentionEditorHandle`). No value getter on it -- the component is controlled, read `value`/`onChange` instead.
+
 ## Other exports
 
-`MentionEditorProps` (type), `MentionFieldOption` (type), `MentionEditorColors` (type), `INITIAL_VALUE` (empty-doc Slate value), `MENTION_OPEN` / `MENTION_CLOSE` (the `'<@'` / `'>'` delimiter constants), `serializeToDiscordMarkup` (deprecated alias of `serialize`).
+`MentionEditorProps` (type), `MentionFieldOption` (type), `MentionEditorColors` (type), `MentionEditorHandle` (type), `getPlainTextLength(nodes: Descendant[]): number` (function; the same count `maxLength`/the ref use), `INITIAL_VALUE` (empty-doc Slate value), `MENTION_OPEN` / `MENTION_CLOSE` (the `'<@'` / `'>'` delimiter constants), `serializeToDiscordMarkup` (deprecated alias of `serialize`).
 
 ## Behavior that is fixed, not configurable via props
 
 - Trigger is always `@`; only fires at line-start or after whitespace (never mid-word, e.g. `user@`).
-- Suggestion menu shows top 10 case-insensitive substring matches on `label`.
+- Suggestion menu shows top 10 case-insensitive substring matches on `label`; zero matches keeps the menu open with a "No matches" row rather than closing it.
 - Menu keys: `↑`/`↓` navigate, `Tab`/`Enter` select, `Escape` dismiss.
 - Undo/redo (`Ctrl/Cmd+Z`) works via `slate-history`.
 - A mention is atomic: one Backspace immediately after it deletes the whole node, never a partial one.
 - Mentions get `unicode-bidi: isolate` so an embedded Latin/digit label can't flip surrounding RTL paragraph reordering.
 - Built-in `dark:` styling follows OS `prefers-color-scheme`, not a manually toggled `.dark` class (e.g. `next-themes`) — override the `.mention-editor*` classes directly if you need class-driven dark mode.
+- The suggestion menu has ARIA listbox/option roles, and the editable carries `aria-haspopup`/`aria-expanded`/`aria-controls`/`aria-activedescendant`.
 
 ## Styling hook classes (all normal, single-class specificity — a later rule wins)
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@itsammarb/mention-editor",
-	"version": "1.0.5",
+	"version": "1.0.6",
 	"description": "A Discord-style @mention rich-text editor built on Slate.js",
 	"license": "MIT",
 	"main": "dist/index.js",