@itsammarb/mention-editor 1.0.4 → 1.0.6

package/README.md

@@ -54,12 +54,18 @@ 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
 
@@ -70,6 +76,9 @@ Everything importable from `@itsammarb/mention-editor`:
 | `MentionEditor` | component | The editor itself; see [Props](#props). |
 | `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`. |
@@ -95,40 +104,77 @@ Override any of these by targeting the class directly in your own CSS, or via `c
 
 ### Theme colors
 
-Every color is also a CSS custom property, so you can retheme the whole component with a handful of variable declarations instead of overriding individual classes. Set them anywhere that's an ancestor of the whole page — `:root`, `html`, `body`, or a global stylesheet rule — **not** scoped to `.mention-editor` itself: the suggestion menu is rendered through a React portal directly into `document.body`, so it sits *outside* `.mention-editor` in the real DOM and wouldn't inherit a variable scoped there.
+Pass a `colors` prop to override any of the built-in colors, per instance — no external CSS needed:
 
-```css
-/* anywhere in your global CSS, loaded in any order relative to this package's styles.css */
-:root {
-  --mention-editor-mention-color: #16a34a; /* green mention text/underline */
-  --mention-editor-mention-bg: #dcfce7; /* optional pill-style highlight behind a mention */
-  --mention-editor-border-color: #db2777;
-  --mention-editor-menu-highlight-bg: #fde68a; /* selected/hovered suggestion row */
-}
+```tsx
+<MentionEditor
+  value={value}
+  fields={fields}
+  onChange={setValue}
+  colors={{
+    mentionColor: '#16a34a', // green mention text/underline
+    mentionBg: '#dcfce7', // optional pill-style highlight behind a mention
+    borderColor: '#db2777',
+    menuHighlightBg: '#fde68a', // selected/hovered suggestion row
+  }}
+/>
 ```
 
-| Variable | Controls | Light default | Dark default |
+Omitted keys keep their built-in default, and different instances on the same page can have entirely different `colors` without affecting each other — including each instance's own suggestion menu, even though the menu renders through a React portal into `document.body` (a sibling of the editor in the real DOM, not a descendant): `MentionEditor` forwards `colors` to it directly rather than relying on CSS inheritance.
+
+| `colors` key | Controls | Light default | Dark default |
 | --- | --- | --- | --- |
-| `--mention-editor-bg` | Editor container background | white | neutral-900 |
-| `--mention-editor-text-color` | Editor body text color | gray-900 | gray-100 |
-| `--mention-editor-border-color` | Container border (normal state) | gray-300 | neutral-700 |
-| `--mention-editor-border-color-error` | Container border when `isError` | red-500 | red-500 (same in both) |
-| `--mention-editor-placeholder-color` | Placeholder text color | gray-400 | neutral-500 |
-| `--mention-editor-mention-color` | A mention's text/underline color | blue-600 | blue-400 |
-| `--mention-editor-mention-bg` | Background behind a mention (e.g. a pill highlight) | transparent | transparent |
-| `--mention-editor-menu-bg` | Suggestion menu background | white | neutral-800 |
-| `--mention-editor-menu-border-color` | Suggestion menu border | gray-300 | neutral-700 |
-| `--mention-editor-menu-text-color` | Suggestion menu row text | gray-900 | gray-100 |
-| `--mention-editor-menu-highlight-bg` | Selected/hovered suggestion row background | indigo-50 | neutral-700 |
+| `bg` | Editor container background | white | neutral-900 |
+| `textColor` | Editor body text color | gray-900 | gray-100 |
+| `borderColor` | Container border (normal state) | gray-300 | neutral-700 |
+| `borderColorError` | Container border when `isError` | red-500 | red-500 (same in both) |
+| `placeholderColor` | Placeholder text color | gray-400 | neutral-500 |
+| `mentionColor` | A mention's text/underline color | blue-600 | blue-400 |
+| `mentionBg` | Background behind a mention (e.g. a pill highlight) | transparent | transparent |
+| `menuBg` | Suggestion menu background | white | neutral-800 |
+| `menuBorderColor` | Suggestion menu border | gray-300 | neutral-700 |
+| `menuTextColor` | Suggestion menu row text | gray-900 | gray-100 |
+| `menuHighlightBg` | Selected/hovered suggestion row background | indigo-50 | neutral-700 |
 
-Setting a variable applies it in both light and dark mode (the fallback is what differs by scheme, not the override) — if you want genuinely different override colors per scheme, redeclare the variable yourself inside your own `@media (prefers-color-scheme: dark)` block.
+A `colors` value applies in both light and dark mode (the fallback is what differs by scheme, not your override) — if you want genuinely different colors per scheme, read `window.matchMedia('(prefers-color-scheme: dark)')` (or your app's own dark-mode state) and pass a different `colors` object accordingly.
 
-These defaults aren't asserted anywhere as a real `:root` rule in this package's stylesheet — they're inline `var(--x, fallback)` fallbacks on each utility class instead. That's deliberate: a real default declaration and a consumer override would both be equal-specificity `:root` rules, so whichever stylesheet happened to load *last* would silently win regardless of intent. Reading the variable with an inline fallback means there's only ever one real assignment (yours, if you set one), so load order can't matter.
+**Dark mode**: the built-in dark defaults (used when `colors` doesn't set a given key) respond to the OS/browser's `prefers-color-scheme: dark`, *not* a manually-toggled `.dark` class (e.g. from `next-themes` or a similar library). If your app drives dark mode via a class rather than OS preference, either pass `colors` explicitly (bypassing the scheme-based default entirely), or drive it from your own dark-mode state as described above.
 
-**Dark mode**: the built-in dark defaults respond to the OS/browser's `prefers-color-scheme: dark`, *not* a manually-toggled `.dark` class (e.g. from `next-themes` or a similar library). If your app drives dark mode via a class rather than OS preference, set the variables above directly (they'll then apply regardless of scheme), or scope your own overrides under your app's dark-mode class selector.
+**Advanced — global CSS override**: under the hood, `colors` works by setting CSS custom properties (`--mention-editor-*`) inline. You can also set these directly in your own global CSS (`:root { --mention-editor-mention-color: ...; }`) as a page-wide fallback for instances that don't pass `colors` at all — an inline `colors` value always takes precedence over a global CSS one. Global CSS declarations must be scoped to `:root`/`html`/`body` (not `.mention-editor`) for the same portal reason as above.
 
 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

@@ -1,17 +1,35 @@
 import React from 'react';
-import { MentionFieldOption } from './types';
+import { MentionFieldOption, MentionEditorColors } 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;
+    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,32 +1,89 @@
 "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");
 const types_1 = require("./types");
 const serialize_1 = require("./serialize");
+const colors_1 = require("./colors");
 const MentionMenu_1 = require("./MentionMenu");
-function MentionEditor(props) {
-    const { value, fields, onChange, dir, disabled = false, isError = false, placeholder, rows, className, } = props;
+const EDITOR_COLOR_KEYS = [
+    'bg',
+    'textColor',
+    'borderColor',
+    'borderColorError',
+    'placeholderColor',
+    'mentionColor',
+    'mentionBg',
+];
+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('');
@@ -77,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) {
@@ -97,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, {
@@ -108,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) {
@@ -127,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();
@@ -136,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))',
@@ -149,8 +221,11 @@ function MentionEditor(props) {
         .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-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 }))] }) }, generation));
-}
+    // 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, 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.
@@ -234,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,11 +1,16 @@
 import React from 'react';
-import { MentionFieldOption } from './types';
+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;
     onHover: (index: number) => void;
     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,10 +1,20 @@
 "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 MentionMenu = ({ fields, selectedIndex, onSelect, onHover, targetRect, }) => {
-    if (!targetRect || fields.length === 0)
+const colors_1 = require("./colors");
+const MENU_COLOR_KEYS = [
+    'menuBg',
+    'menuBorderColor',
+    'menuTextColor',
+    'menuHighlightBg',
+];
+/** 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
@@ -13,11 +23,16 @@ const MentionMenu = ({ fields, selectedIndex, onSelect, onHover, targetRect, })
     // 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-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: {
+    //
+    // `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", { 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,
-        }, children: fields.map((field, i) => ((0, jsx_runtime_1.jsx)("div", { className: 'mention-editor__menu-item cursor-pointer px-3 py-2' +
+            ...(0, colors_1.colorsToCssVars)(colors, MENU_COLOR_KEYS),
+        }, 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
@@ -26,6 +41,6 @@ const MentionMenu = ({ fields, selectedIndex, onSelect, onHover, targetRect, })
                     : ''), 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/colors.d.ts

@@ -0,0 +1,9 @@
+import type { CSSProperties } from 'react';
+import { MentionEditorColors } from './types';
+/**
+ * Builds an inline `style` object setting only the CSS custom properties for
+ * the given keys that are actually present in `colors` -- omitted keys are
+ * left unset entirely, so the built-in fallback in the compiled CSS still
+ * applies for them.
+ */
+export declare const colorsToCssVars: (colors: MentionEditorColors | undefined, keys: (keyof MentionEditorColors)[]) => CSSProperties;

package/dist/colors.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.colorsToCssVars = void 0;
+// Maps each `colors` prop key to the CSS custom property the compiled
+// Tailwind classes read via `var(--x, <built-in fallback>)`. Setting the
+// property inline (rather than requiring a consumer to write global CSS)
+// wins over the fallback automatically -- and, being inline, wins regardless
+// of stylesheet load order, since there's no competing external rule to race.
+const COLOR_VARS = {
+    bg: '--mention-editor-bg',
+    textColor: '--mention-editor-text-color',
+    borderColor: '--mention-editor-border-color',
+    borderColorError: '--mention-editor-border-color-error',
+    placeholderColor: '--mention-editor-placeholder-color',
+    mentionColor: '--mention-editor-mention-color',
+    mentionBg: '--mention-editor-mention-bg',
+    menuBg: '--mention-editor-menu-bg',
+    menuBorderColor: '--mention-editor-menu-border-color',
+    menuTextColor: '--mention-editor-menu-text-color',
+    menuHighlightBg: '--mention-editor-menu-highlight-bg',
+};
+/**
+ * Builds an inline `style` object setting only the CSS custom properties for
+ * the given keys that are actually present in `colors` -- omitted keys are
+ * left unset entirely, so the built-in fallback in the compiled CSS still
+ * applies for them.
+ */
+const colorsToCssVars = (colors, keys) => {
+    if (!colors)
+        return {};
+    const style = {};
+    for (const key of keys) {
+        const value = colors[key];
+        if (value)
+            style[COLOR_VARS[key]] = value;
+    }
+    return style;
+};
+exports.colorsToCssVars = colorsToCssVars;

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 { MentionFieldOption } from './types';
+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/dist/types.d.ts

@@ -27,3 +27,16 @@ declare module 'slate' {
 export declare const INITIAL_VALUE: Descendant[];
 export declare const MENTION_OPEN = "<@";
 export declare const MENTION_CLOSE = ">";
+export interface MentionEditorColors {
+    bg?: string;
+    textColor?: string;
+    borderColor?: string;
+    borderColorError?: string;
+    placeholderColor?: string;
+    mentionColor?: string;
+    mentionBg?: string;
+    menuBg?: string;
+    menuBorderColor?: string;
+    menuTextColor?: string;
+    menuHighlightBg?: string;
+}

package/llms.txt

@@ -39,38 +39,43 @@ 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), `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)
 
 `.mention-editor` (root), `.mention-editor__editable`, `.mention-editor__paragraph`, `.mention-editor__mention`, `.mention-editor__menu`, `.mention-editor__menu-item`.
 
-## Theme colors (CSS custom properties)
-
-Set these at `:root`/`html`/`body` scope in your own global CSS (not scoped to `.mention-editor` — the suggestion menu portals to `document.body`, outside it) to retheme without touching classes:
+## Theme colors
 
-`--mention-editor-bg`, `--mention-editor-text-color`, `--mention-editor-border-color`, `--mention-editor-border-color-error`, `--mention-editor-placeholder-color`, `--mention-editor-mention-color`, `--mention-editor-mention-bg`, `--mention-editor-menu-bg`, `--mention-editor-menu-border-color`, `--mention-editor-menu-text-color`, `--mention-editor-menu-highlight-bg`.
+Use the `colors` prop, not CSS, to retheme -- e.g. `colors={{ mentionColor: '#16a34a', mentionBg: '#dcfce7', borderColor: '#db2777', menuHighlightBg: '#fde68a' }}`. Keys: `bg`, `textColor`, `borderColor`, `borderColorError`, `placeholderColor`, `mentionColor`, `mentionBg`, `menuBg`, `menuBorderColor`, `menuTextColor`, `menuHighlightBg`. Omitted keys keep the built-in default (which itself differs light vs. dark, following OS `prefers-color-scheme`). Each editor instance's `colors` is independent, and is correctly forwarded to that instance's own suggestion menu even though the menu renders through a React portal into `document.body`.
 
-Each has a light/dark default baked in as a `var(--x, fallback)` on the relevant utility class (no competing `:root` declaration in this package's own CSS), so setting one always wins regardless of stylesheet load order, and applies in both light and dark mode unless you scope your own override inside a `prefers-color-scheme` media query.
+Advanced: `colors` works by setting `--mention-editor-*` CSS custom properties inline; you can also set these directly in your own global CSS at `:root`/`html`/`body` scope (not `.mention-editor` -- the portaled menu sits outside it) as a page-wide fallback. An inline `colors` value always wins over a global CSS one.
 
 ## Full docs
 

package/package.json

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