@itsammarb/mention-editor 1.0.4 → 1.0.5

package/README.md

@@ -60,6 +60,7 @@ Hello <@a1b2c3d4-0000-0000-0000-000000000001>, welcome.
 | `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. |
 | `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. |
 
 ## Exported utilities
 
@@ -70,6 +71,7 @@ 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). |
 | `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,37 +97,43 @@ 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 |
-
-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.
-
-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 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.
+| `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 |
+
+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.
+
+**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.
+
+**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.
 

package/dist/MentionEditor.d.ts

@@ -1,5 +1,5 @@
 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;
@@ -13,5 +13,7 @@ export interface MentionEditorProps {
     /** Approximate visible height, textarea-`rows`-equivalent. */
     rows?: 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;

package/dist/MentionEditor.js

@@ -8,9 +8,19 @@ 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");
+const EDITOR_COLOR_KEYS = [
+    'bg',
+    'textColor',
+    'borderColor',
+    'borderColorError',
+    'placeholderColor',
+    'mentionColor',
+    'mentionBg',
+];
 function MentionEditor(props) {
-    const { value, fields, onChange, dir, disabled = false, isError = false, placeholder, rows, className, } = props;
+    const { value, fields, onChange, dir, disabled = false, isError = false, placeholder, rows, className, colors, } = 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
@@ -149,7 +159,10 @@ 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, 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));
 }
 // slate-react's default placeholder renders at a fixed dim-black opacity,
 // which reads poorly in dark mode. Overriding it lets the placeholder use

package/dist/MentionMenu.d.ts

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

package/dist/MentionMenu.js

@@ -3,7 +3,14 @@ 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, }) => {
+const colors_1 = require("./colors");
+const MENU_COLOR_KEYS = [
+    'menuBg',
+    'menuBorderColor',
+    'menuTextColor',
+    'menuHighlightBg',
+];
+const MentionMenu = ({ fields, selectedIndex, onSelect, onHover, targetRect, colors, }) => {
     if (!targetRect || fields.length === 0)
         return null;
     // Rendered into document.body via a portal and positioned with `fixed` using
@@ -13,10 +20,15 @@ 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.
+    //
+    // `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: {
             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' +
                 ' text-(--mention-editor-menu-text-color,var(--color-gray-900))' +
                 ' dark:text-(--mention-editor-menu-text-color,var(--color-gray-100))' +

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 { MentionFieldOption, MentionEditorColors } from './types';
 export { INITIAL_VALUE, MENTION_OPEN, MENTION_CLOSE } from './types';

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

@@ -45,10 +45,11 @@ function Example() {
 | `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. |
 | `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. |
 
 ## 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), `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
 
@@ -64,13 +65,11 @@ function Example() {
 
 `.mention-editor` (root), `.mention-editor__editable`, `.mention-editor__paragraph`, `.mention-editor__mention`, `.mention-editor__menu`, `.mention-editor__menu-item`.
 
-## Theme colors (CSS custom properties)
+## Theme colors
 
-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:
+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`.
 
-`--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`.
-
-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.5",
 	"description": "A Discord-style @mention rich-text editor built on Slate.js",
 	"license": "MIT",
 	"main": "dist/index.js",