mentionize 0.0.1 → 0.0.3

package/README.md

@@ -1,10 +1,13 @@
 # Mentionize
 
-A React library for building mention inputs with support for multiple triggers, async search, and full customization. It provides a transparent textarea overlaid on a highlighted div to display mentions, and a dropdown for suggestions. With zero dependencies.
+A React library for building mention inputs with support for multiple triggers, async search, and full customization. It provides a transparent textarea overlaid on a highlighted div to display mentions, and a dropdown for suggestions. With zero dependencies other than React.
 
 ## Install
 
 ```bash
+npm install react
+npm install react-dom
+
 npm install mentionize
 ```
 
@@ -57,12 +60,14 @@ Defines how a trigger character activates suggestions and how mentions are seria
 | `displayText` | `(item: T) => string` | Converts an item to its visible text |
 | `serialize` | `(item: T) => string` | Converts an item to its serialized form in the raw value |
 | `pattern` | `RegExp` | Regex to detect serialized mentions (must use global flag) |
-| `parseMatch` | `(match: RegExpExecArray) => { displayText: string; key: string }` | Parses a regex match back into display text and key |
+| `parseMatch` | `(match: RegExpExecArray) => { displayText: string; key: string; item?: T }` | Parses a regex match back into display text and key. Optionally returns `item` to seed the engine cache. |
 | `options?` | `T[]` | Static options array (client-side filtering) |
 | `onSearch?` | `(query: string, page: number) => Promise<{ items: T[]; hasMore: boolean }>` | Async search with pagination |
 | `renderOption?` | `(item: T, highlighted: boolean) => ReactNode` | Custom option rendering |
-| `renderMention?` | `(displayText: string) => ReactNode` | Custom mention highlight rendering |
-| `mentionClassName?` | `string` | CSS class for highlighted mentions in the overlay |
+| `optionClassName?` | `string \| ((item: T) => string)` | CSS class for dropdown options, or a function for conditional styling per item |
+| `renderMention?` | `(displayText: string, item?: unknown) => ReactNode` | Custom mention highlight rendering |
+| `mentionClassName?` | `string \| ((mention: MentionItemData) => string)` | CSS class for highlighted mentions, or a function for conditional styling |
+| `onSelect?` | `(item: T) => Promise<string \| null> \| string \| null` | Action trigger: runs instead of inserting a mention. Returns text to insert or null to cancel. |
 
 ### `MentionInputProps`
 
@@ -81,7 +86,10 @@ Defines how a trigger character activates suggestions and how mentions are seria
 | `highlighterClassName?` | `string` | Highlighter overlay className |
 | `dropdownClassName?` | `string` | Dropdown className |
 | `dropdownWidth?` | `number` | Dropdown width in pixels (default: 250) |
+| `loadingText?` | `string` | Text shown while loading async results (default: `"Loading..."`) |
 | `renderDropdown?` | `(props: DropdownRenderProps) => ReactNode` | Full custom dropdown rendering |
+| `aria-label?` | `string` | Accessible label for the textarea |
+| `aria-describedby?` | `string` | ID of an element describing the textarea |
 
 ## Multiple Triggers
 
@@ -112,6 +120,43 @@ const trigger: MentionTrigger<User> = {
 };
 ```
 
+## Cache Seeding via `parseMatch`
+
+By default the engine only recognizes mentions whose items are already cached (from `options`, `onSearch` results, or previous selections). When a mention is injected externally — for example by a `/` command picker or when loading initial content containing mentions for items that haven't been searched yet — the cache may not contain the underlying item, so the mention won't be highlighted or serialized.
+
+To solve this, `parseMatch` can optionally return an `item` field. When present, the engine seeds its internal cache with that item during raw-to-visible parsing, making the mention immediately detectable:
+
+```tsx
+const modelTrigger: MentionTrigger<Model> = {
+  trigger: "@",
+  displayText: (model) => model.label,
+  serialize: (model) => `@[${model.label}](model:${model.id})`,
+  pattern: /@\[([^\]]+)\]\(model:([^)]+)\)/g,
+  parseMatch: (match) => {
+    const id = match[2]!;
+    const label = match[1]!;
+    // Look up the item from your own data source
+    const cached = myModelCache.get(id);
+    return {
+      displayText: label,
+      key: id,
+      item: cached, // if defined, seeds the engine cache
+    };
+  },
+  onSearch: async (query, page) => {
+    const res = await fetch(`/api/models?q=${query}&page=${page}`);
+    return res.json();
+  },
+};
+```
+
+This is useful when:
+- A command picker (e.g. `/` trigger with `onSelect`) injects a mention into the input
+- The input is initialized with raw text containing mentions for items not in `options`
+- Items are known at parse time but haven't been searched via `onSearch` yet
+
+The `item` field is optional and fully backward-compatible — existing `parseMatch` implementations that only return `displayText` and `key` continue to work unchanged.
+
 ## Headless Usage
 
 Use `useMentionEngine` directly for full control over rendering:
@@ -125,13 +170,14 @@ const engine = useMentionEngine({
   onChange: setValue,
 });
 
-// engine.visible        - display text
-// engine.mentions       - active mentions with positions
-// engine.activeTrigger  - currently active trigger (or null)
-// engine.filteredOptions - filtered suggestions
+// engine.visible          - display text
+// engine.mentions         - active mentions with positions
+// engine.activeTrigger    - currently active trigger (or null)
+// engine.filteredOptions  - filtered suggestions
 // engine.handleTextChange(text, caretPos)
 // engine.handleKeyDown(event, textarea)
 // engine.selectOption(item, textarea)
+// engine.getItemForMention(triggerChar, key) - look up cached item for a mention
 ```
 
 ## Styling
@@ -148,6 +194,69 @@ Mentionize uses a transparent textarea overlaid on a highlighted div. Apply styl
 />
 ```
 
+### Conditional Mention Styling
+
+Use a function for `mentionClassName` to style mentions dynamically based on the underlying item data:
+
+```tsx
+import type { MentionItemData } from "mentionize";
+
+const userTrigger: MentionTrigger<User> = {
+  trigger: "@",
+  mentionClassName: (mention: MentionItemData) => {
+    const user = mention.item as User;
+    switch (user?.role) {
+      case "Engineer": return "mention-engineer";
+      case "Designer": return "mention-designer";
+      case "PM":       return "mention-pm";
+      default:         return "mention-user";
+    }
+  },
+  // Apply the same conditional styling to dropdown options
+  optionClassName: (user) => {
+    switch (user.role) {
+      case "Engineer": return "mention-engineer";
+      case "Designer": return "mention-designer";
+      case "PM":       return "mention-pm";
+      default:         return "mention-user";
+    }
+  },
+  // ...other config
+};
+```
+
+The `MentionItemData` object contains `key`, `displayText`, `trigger`, and `item` (the original cached item). Use `optionClassName` (string or function receiving the item directly) to apply matching styles to dropdown options.
+
+### Action Triggers
+
+Use `onSelect` to create triggers that run an action instead of inserting a mention. The callback receives the selected item and returns a string to insert as plain text, or `null` to cancel:
+
+```tsx
+const commandTrigger: MentionTrigger<Command> = {
+  trigger: "/",
+  displayText: (cmd) => cmd.label,
+  // serialize/pattern/parseMatch still needed for the dropdown
+  serialize: (cmd) => `/[${cmd.label}](cmd:${cmd.id})`,
+  pattern: /\/\[([^\]]+)\]\(cmd:([^)]+)\)/g,
+  parseMatch: (match) => ({ displayText: match[1]!, key: match[2]! }),
+  options: [
+    { id: "date", label: "Insert Date" },
+    { id: "emoji", label: "Pick Emoji" },
+  ],
+  onSelect: async (cmd) => {
+    if (cmd.id === "date") return new Date().toLocaleDateString();
+    if (cmd.id === "emoji") {
+      // simulate async work
+      await new Promise((r) => setTimeout(r, 500));
+      return "🎉";
+    }
+    return null; // cancel — nothing inserted
+  },
+};
+```
+
+When `onSelect` is defined, selecting an option calls the function instead of inserting a mention. The trigger text and query are replaced by the returned string.
+
 Per-trigger mention highlights can be styled via `mentionClassName`:
 
 ```tsx

package/dist/cjs/MentionDropdown.d.ts

@@ -8,6 +8,7 @@ interface MentionDropdownProps {
     onSelect: (item: unknown) => void;
     onLoadMore?: () => void;
     loading: boolean;
+    loadingText?: string;
     position: CaretPosition;
     width: number;
     className?: string;

package/dist/cjs/MentionHighlighter.d.ts

@@ -5,6 +5,7 @@ interface MentionHighlighterProps {
     mentions: ActiveMention[];
     triggers: MentionTrigger<any>[];
     textareaRef: React.RefObject<HTMLTextAreaElement | null>;
+    getItemForMention?: (triggerChar: string, key: string) => unknown;
     className?: string;
     style?: React.CSSProperties;
 }

package/dist/cjs/index.d.ts

@@ -3,4 +3,4 @@ export { MentionHighlighter } from "./MentionHighlighter.tsx";
 export { MentionDropdown } from "./MentionDropdown.tsx";
 export { useMentionEngine } from "./useMentionEngine.ts";
 export { useCaretPosition } from "./useCaretPosition.ts";
-export type { MentionTrigger, MentionInputProps, ActiveMention, DropdownRenderProps, CaretPosition, } from "./types.ts";
+export type { MentionTrigger, MentionItemData, MentionInputProps, ActiveMention, DropdownRenderProps, CaretPosition, } from "./types.ts";

package/dist/cjs/index.js

@@ -64,6 +64,7 @@ var MentionDropdown = ({
   onSelect,
   onLoadMore,
   loading,
+  loadingText,
   position,
   width,
   className
@@ -118,10 +119,12 @@ var MentionDropdown = ({
     children: [
       items.map((item, i) => {
         const isHighlighted = i === highlightedIndex;
+        const optCls = typeof trigger.optionClassName === "function" ? trigger.optionClassName(item) : trigger.optionClassName;
         if (trigger.renderOption) {
           return /* @__PURE__ */ jsx_dev_runtime.jsxDEV("div", {
             role: "option",
             "aria-selected": isHighlighted,
+            className: optCls,
             "data-mentionize-option-index": i,
             "data-mentionize-option-highlighted": isHighlighted || undefined,
             onMouseEnter: () => onHighlight(i),
@@ -132,6 +135,7 @@ var MentionDropdown = ({
         return /* @__PURE__ */ jsx_dev_runtime.jsxDEV("div", {
           role: "option",
           "aria-selected": isHighlighted,
+          className: optCls,
           "data-mentionize-option-index": i,
           "data-mentionize-option": "",
           "data-mentionize-option-highlighted": isHighlighted || undefined,
@@ -142,7 +146,7 @@ var MentionDropdown = ({
       }),
       loading && /* @__PURE__ */ jsx_dev_runtime.jsxDEV("div", {
         "data-mentionize-loading": "",
-        children: "Loading..."
+        children: loadingText ?? "Loading..."
       }, undefined, false, undefined, this),
       onLoadMore && !loading && /* @__PURE__ */ jsx_dev_runtime.jsxDEV("div", {
         ref: sentinelRef,
@@ -172,6 +176,7 @@ var MentionHighlighter = ({
   mentions,
   triggers,
   textareaRef,
+  getItemForMention,
   className,
   style
 }) => {
@@ -192,9 +197,9 @@ var MentionHighlighter = ({
     const sorted = mentions.slice().sort((a, b) => a.start - b.start);
     if (!sorted.length)
       return textToNodes(visible);
-    const classMap = new Map;
+    const triggerMap = new Map;
     for (const t of triggers) {
-      classMap.set(t.trigger, t.mentionClassName ?? "mentionize-mention");
+      triggerMap.set(t.trigger, t);
     }
     const nodes = [];
     let last = 0;
@@ -204,7 +209,21 @@ var MentionHighlighter = ({
         nodes.push(...textToNodes(visible.slice(last, m.start)));
       }
       const mentionText = visible.slice(m.start, m.end);
-      const cls = classMap.get(m.trigger) ?? "mentionize-mention";
+      const t = triggerMap.get(m.trigger);
+      let cls = "mentionize-mention";
+      if (t) {
+        if (typeof t.mentionClassName === "function") {
+          const item = getItemForMention?.(m.trigger, m.key) ?? null;
+          cls = t.mentionClassName({
+            key: m.key,
+            displayText: m.displayText,
+            trigger: m.trigger,
+            item
+          });
+        } else if (t.mentionClassName) {
+          cls = t.mentionClassName;
+        }
+      }
       nodes.push(import_react2.default.createElement("span", {
         key: `mention-${i}`,
         className: cls,
@@ -217,7 +236,7 @@ var MentionHighlighter = ({
       nodes.push(...textToNodes(visible.slice(last)));
     }
     return nodes;
-  }, [visible, mentions, triggers]);
+  }, [visible, mentions, triggers, getItemForMention]);
   import_react2.useLayoutEffect(() => {
     const el = ref.current;
     if (!el)
@@ -446,7 +465,11 @@ function useMentionEngine(options) {
         parts.push(result.slice(lastIndex, m.index));
         const parsed = t.parseMatch(m);
         const cache = getCache(t.trigger);
-        if (!cache.has(parsed.key)) {
+        if (parsed.item !== undefined) {
+          if (!cache.has(parsed.key) || cache.get(parsed.key) === null) {
+            cache.set(parsed.key, parsed.item);
+          }
+        } else if (!cache.has(parsed.key)) {
           cache.set(parsed.key, null);
         }
         parts.push(t.trigger + parsed.displayText);
@@ -618,10 +641,41 @@ function useMentionEngine(options) {
       setActiveTrigger(null);
     }
   }, [detectActiveTrigger, emitSync]);
+  const getItemForMention = import_react4.useCallback((triggerChar, key) => {
+    const cache = getCache(triggerChar);
+    return cache.get(key) ?? null;
+  }, []);
   const selectOption = import_react4.useCallback((item, textarea) => {
     if (!activeTrigger)
       return;
     const t = activeTrigger.trigger;
+    if (t.onSelect) {
+      const before2 = visible.slice(0, activeTrigger.startPos);
+      const after2 = visible.slice(textarea.selectionStart);
+      const savedStartPos = activeTrigger.startPos;
+      setActiveTrigger(null);
+      const result = t.onSelect(item);
+      const applyResult = (value) => {
+        if (value !== null) {
+          const newVis2 = before2 + value + after2;
+          const pos2 = savedStartPos + value.length;
+          caretPosRef.current = pos2;
+          setVisible(newVis2);
+          emitSync(newVis2);
+        } else {
+          const newVis2 = before2 + after2;
+          caretPosRef.current = savedStartPos;
+          setVisible(newVis2);
+          emitSync(newVis2);
+        }
+      };
+      if (result instanceof Promise) {
+        result.then(applyResult);
+      } else {
+        applyResult(result);
+      }
+      return;
+    }
     const cache = getCache(t.trigger);
     const key = getItemKey(t, item);
     cache.set(key, item);
@@ -699,7 +753,8 @@ function useMentionEngine(options) {
     loadMore,
     rawToVisible,
     visibleToRaw,
-    caretPosRef
+    caretPosRef,
+    getItemForMention
   };
 }
 function getItemKey(trigger, item) {
@@ -739,6 +794,7 @@ var MentionInput = import_react5.forwardRef(({
   highlighterClassName,
   dropdownClassName,
   dropdownWidth = 250,
+  loadingText,
   renderDropdown,
   "aria-label": ariaLabel,
   "aria-describedby": ariaDescribedBy
@@ -811,6 +867,7 @@ var MentionInput = import_react5.forwardRef(({
         mentions: engine.mentions,
         triggers,
         textareaRef,
+        getItemForMention: engine.getItemForMention,
         className: highlighterClassName,
         style: SHARED_STYLE
       }, undefined, false, undefined, this),
@@ -868,6 +925,7 @@ var MentionInput = import_react5.forwardRef(({
         onSelect: handleSelect,
         onLoadMore: engine.searchHasMore ? engine.loadMore : undefined,
         loading: engine.searchLoading,
+        loadingText,
         position: dropdownPos,
         width: dropdownWidth,
         className: dropdownClassName
@@ -877,5 +935,5 @@ var MentionInput = import_react5.forwardRef(({
 });
 MentionInput.displayName = "MentionInput";
 
-//# debugId=2D34F896A558FE4664756E2164756E21
+//# debugId=B71F10C79A7CF6EF64756E2164756E21
 //# sourceMappingURL=index.js.map