@tiptap/suggestion 3.0.0 → 3.0.2-beta.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025, Tiptap GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,14 +1,18 @@
 # @tiptap/suggestion
+
 [![Version](https://img.shields.io/npm/v/@tiptap/suggestion.svg?label=version)](https://www.npmjs.com/package/@tiptap/suggestion)
 [![Downloads](https://img.shields.io/npm/dm/@tiptap/suggestion.svg)](https://npmcharts.com/compare/tiptap?minimal=true)
 [![License](https://img.shields.io/npm/l/@tiptap/suggestion.svg)](https://www.npmjs.com/package/@tiptap/suggestion)
 [![Sponsor](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub)](https://github.com/sponsors/ueberdosis)
 
 ## Introduction
-Tiptap is a headless wrapper around [ProseMirror](https://ProseMirror.net) – a toolkit for building rich text WYSIWYG editors, which is already in use at many well-known companies such as *New York Times*, *The Guardian* or *Atlassian*.
+
+Tiptap is a headless wrapper around [ProseMirror](https://ProseMirror.net) – a toolkit for building rich text WYSIWYG editors, which is already in use at many well-known companies such as _New York Times_, _The Guardian_ or _Atlassian_.
 
 ## Official Documentation
+
 Documentation can be found on the [Tiptap website](https://tiptap.dev).
 
 ## License
+
 Tiptap is open sourced software licensed under the [MIT license](https://github.com/ueberdosis/tiptap/blob/main/LICENSE.md).

package/dist/index.cjs

@@ -1,244 +1,279 @@
-'use strict';
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
-Object.defineProperty(exports, '__esModule', { value: true });
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Suggestion: () => Suggestion,
+  SuggestionPluginKey: () => SuggestionPluginKey,
+  default: () => index_default,
+  findSuggestionMatch: () => findSuggestionMatch
+});
+module.exports = __toCommonJS(index_exports);
 
-var state = require('@tiptap/pm/state');
-var view = require('@tiptap/pm/view');
-var core = require('@tiptap/core');
+// src/suggestion.ts
+var import_state = require("@tiptap/pm/state");
+var import_view = require("@tiptap/pm/view");
 
+// src/findSuggestionMatch.ts
+var import_core = require("@tiptap/core");
 function findSuggestionMatch(config) {
-    var _a;
-    const { char, allowSpaces, allowedPrefixes, startOfLine, $position, } = config;
-    const escapedChar = core.escapeForRegEx(char);
-    const suffix = new RegExp(`\\s${escapedChar}$`);
-    const prefix = startOfLine ? '^' : '';
-    const regexp = allowSpaces
-        ? new RegExp(`${prefix}${escapedChar}.*?(?=\\s${escapedChar}|$)`, 'gm')
-        : new RegExp(`${prefix}(?:^)?${escapedChar}[^\\s${escapedChar}]*`, 'gm');
-    const text = ((_a = $position.nodeBefore) === null || _a === void 0 ? void 0 : _a.isText) && $position.nodeBefore.text;
-    if (!text) {
-        return null;
-    }
-    const textFrom = $position.pos - text.length;
-    const match = Array.from(text.matchAll(regexp)).pop();
-    if (!match || match.input === undefined || match.index === undefined) {
-        return null;
-    }
-    // JavaScript doesn't have lookbehinds. This hacks a check that first character
-    // is a space or the start of the line
-    const matchPrefix = match.input.slice(Math.max(0, match.index - 1), match.index);
-    const matchPrefixIsAllowed = new RegExp(`^[${allowedPrefixes === null || allowedPrefixes === void 0 ? void 0 : allowedPrefixes.join('')}\0]?$`).test(matchPrefix);
-    if (allowedPrefixes !== null && !matchPrefixIsAllowed) {
-        return null;
-    }
-    // The absolute position of the match in the document
-    const from = textFrom + match.index;
-    let to = from + match[0].length;
-    // Edge case handling; if spaces are allowed and we're directly in between
-    // two triggers
-    if (allowSpaces && suffix.test(text.slice(to - 1, to + 1))) {
-        match[0] += ' ';
-        to += 1;
-    }
-    // If the $position is located within the matched substring, return that range
-    if (from < $position.pos && to >= $position.pos) {
-        return {
-            range: {
-                from,
-                to,
-            },
-            query: match[0].slice(char.length),
-            text: match[0],
-        };
-    }
+  var _a;
+  const { char, allowSpaces: allowSpacesOption, allowToIncludeChar, allowedPrefixes, startOfLine, $position } = config;
+  const allowSpaces = allowSpacesOption && !allowToIncludeChar;
+  const escapedChar = (0, import_core.escapeForRegEx)(char);
+  const suffix = new RegExp(`\\s${escapedChar}$`);
+  const prefix = startOfLine ? "^" : "";
+  const finalEscapedChar = allowToIncludeChar ? "" : escapedChar;
+  const regexp = allowSpaces ? new RegExp(`${prefix}${escapedChar}.*?(?=\\s${finalEscapedChar}|$)`, "gm") : new RegExp(`${prefix}(?:^)?${escapedChar}[^\\s${finalEscapedChar}]*`, "gm");
+  const text = ((_a = $position.nodeBefore) == null ? void 0 : _a.isText) && $position.nodeBefore.text;
+  if (!text) {
+    return null;
+  }
+  const textFrom = $position.pos - text.length;
+  const match = Array.from(text.matchAll(regexp)).pop();
+  if (!match || match.input === void 0 || match.index === void 0) {
     return null;
+  }
+  const matchPrefix = match.input.slice(Math.max(0, match.index - 1), match.index);
+  const matchPrefixIsAllowed = new RegExp(`^[${allowedPrefixes == null ? void 0 : allowedPrefixes.join("")}\0]?$`).test(matchPrefix);
+  if (allowedPrefixes !== null && !matchPrefixIsAllowed) {
+    return null;
+  }
+  const from = textFrom + match.index;
+  let to = from + match[0].length;
+  if (allowSpaces && suffix.test(text.slice(to - 1, to + 1))) {
+    match[0] += " ";
+    to += 1;
+  }
+  if (from < $position.pos && to >= $position.pos) {
+    return {
+      range: {
+        from,
+        to
+      },
+      query: match[0].slice(char.length),
+      text: match[0]
+    };
+  }
+  return null;
 }
 
-const SuggestionPluginKey = new state.PluginKey('suggestion');
-/**
- * This utility allows you to create suggestions.
- * @see https://tiptap.dev/api/utilities/suggestion
- */
-function Suggestion({ pluginKey = SuggestionPluginKey, editor, char = '@', allowSpaces = false, allowedPrefixes = [' '], startOfLine = false, decorationTag = 'span', decorationClass = 'suggestion', command = () => null, items = () => [], render = () => ({}), allow = () => true, findSuggestionMatch: findSuggestionMatch$1 = findSuggestionMatch, }) {
-    let props;
-    const renderer = render === null || render === void 0 ? void 0 : render();
-    const plugin = new state.Plugin({
-        key: pluginKey,
-        view() {
-            return {
-                update: async (view, prevState) => {
-                    var _a, _b, _c, _d, _e, _f, _g;
-                    const prev = (_a = this.key) === null || _a === void 0 ? void 0 : _a.getState(prevState);
-                    const next = (_b = this.key) === null || _b === void 0 ? void 0 : _b.getState(view.state);
-                    // See how the state changed
-                    const moved = prev.active && next.active && prev.range.from !== next.range.from;
-                    const started = !prev.active && next.active;
-                    const stopped = prev.active && !next.active;
-                    const changed = !started && !stopped && prev.query !== next.query;
-                    const handleStart = started;
-                    const handleChange = changed || moved;
-                    const handleExit = stopped;
-                    // Cancel when suggestion isn't active
-                    if (!handleStart && !handleChange && !handleExit) {
-                        return;
-                    }
-                    const state = handleExit && !handleStart ? prev : next;
-                    const decorationNode = view.dom.querySelector(`[data-decoration-id="${state.decorationId}"]`);
-                    props = {
-                        editor,
-                        range: state.range,
-                        query: state.query,
-                        text: state.text,
-                        items: [],
-                        command: commandProps => {
-                            return command({
-                                editor,
-                                range: state.range,
-                                props: commandProps,
-                            });
-                        },
-                        decorationNode,
-                        // virtual node for popper.js or tippy.js
-                        // this can be used for building popups without a DOM node
-                        clientRect: decorationNode
-                            ? () => {
-                                var _a;
-                                // because of `items` can be asynchrounous we’ll search for the current decoration node
-                                const { decorationId } = (_a = this.key) === null || _a === void 0 ? void 0 : _a.getState(editor.state); // eslint-disable-line
-                                const currentDecorationNode = view.dom.querySelector(`[data-decoration-id="${decorationId}"]`);
-                                return (currentDecorationNode === null || currentDecorationNode === void 0 ? void 0 : currentDecorationNode.getBoundingClientRect()) || null;
-                            }
-                            : null,
-                    };
-                    if (handleStart) {
-                        (_c = renderer === null || renderer === void 0 ? void 0 : renderer.onBeforeStart) === null || _c === void 0 ? void 0 : _c.call(renderer, props);
-                    }
-                    if (handleChange) {
-                        (_d = renderer === null || renderer === void 0 ? void 0 : renderer.onBeforeUpdate) === null || _d === void 0 ? void 0 : _d.call(renderer, props);
-                    }
-                    if (handleChange || handleStart) {
-                        props.items = await items({
-                            editor,
-                            query: state.query,
-                        });
-                    }
-                    if (handleExit) {
-                        (_e = renderer === null || renderer === void 0 ? void 0 : renderer.onExit) === null || _e === void 0 ? void 0 : _e.call(renderer, props);
-                    }
-                    if (handleChange) {
-                        (_f = renderer === null || renderer === void 0 ? void 0 : renderer.onUpdate) === null || _f === void 0 ? void 0 : _f.call(renderer, props);
-                    }
-                    if (handleStart) {
-                        (_g = renderer === null || renderer === void 0 ? void 0 : renderer.onStart) === null || _g === void 0 ? void 0 : _g.call(renderer, props);
-                    }
-                },
-                destroy: () => {
-                    var _a;
-                    if (!props) {
-                        return;
-                    }
-                    (_a = renderer === null || renderer === void 0 ? void 0 : renderer.onExit) === null || _a === void 0 ? void 0 : _a.call(renderer, props);
-                },
-            };
-        },
-        state: {
-            // Initialize the plugin's internal state.
-            init() {
-                const state = {
-                    active: false,
-                    range: {
-                        from: 0,
-                        to: 0,
-                    },
-                    query: null,
-                    text: null,
-                    composing: false,
-                };
-                return state;
-            },
-            // Apply changes to the plugin state from a view transaction.
-            apply(transaction, prev, _oldState, state) {
-                const { isEditable } = editor;
-                const { composing } = editor.view;
-                const { selection } = transaction;
-                const { empty, from } = selection;
-                const next = { ...prev };
-                next.composing = composing;
-                // We can only be suggesting if the view is editable, and:
-                //   * there is no selection, or
-                //   * a composition is active (see: https://github.com/ueberdosis/tiptap/issues/1449)
-                if (isEditable && (empty || editor.view.composing)) {
-                    // Reset active state if we just left the previous suggestion range
-                    if ((from < prev.range.from || from > prev.range.to) && !composing && !prev.composing) {
-                        next.active = false;
-                    }
-                    // Try to match against where our cursor currently is
-                    const match = findSuggestionMatch$1({
-                        char,
-                        allowSpaces,
-                        allowedPrefixes,
-                        startOfLine,
-                        $position: selection.$from,
-                    });
-                    const decorationId = `id_${Math.floor(Math.random() * 0xffffffff)}`;
-                    // If we found a match, update the current state to show it
-                    if (match && allow({
-                        editor, state, range: match.range, isActive: prev.active,
-                    })) {
-                        next.active = true;
-                        next.decorationId = prev.decorationId ? prev.decorationId : decorationId;
-                        next.range = match.range;
-                        next.query = match.query;
-                        next.text = match.text;
-                    }
-                    else {
-                        next.active = false;
-                    }
-                }
-                else {
-                    next.active = false;
-                }
-                // Make sure to empty the range if suggestion is inactive
-                if (!next.active) {
-                    next.decorationId = null;
-                    next.range = { from: 0, to: 0 };
-                    next.query = null;
-                    next.text = null;
-                }
-                return next;
-            },
-        },
-        props: {
-            // Call the keydown hook if suggestion is active.
-            handleKeyDown(view, event) {
-                var _a;
-                const { active, range } = plugin.getState(view.state);
-                if (!active) {
-                    return false;
-                }
-                return ((_a = renderer === null || renderer === void 0 ? void 0 : renderer.onKeyDown) === null || _a === void 0 ? void 0 : _a.call(renderer, { view, event, range })) || false;
-            },
-            // Setup decorator on the currently active suggestion.
-            decorations(state) {
-                const { active, range, decorationId } = plugin.getState(state);
-                if (!active) {
-                    return null;
-                }
-                return view.DecorationSet.create(state.doc, [
-                    view.Decoration.inline(range.from, range.to, {
-                        nodeName: decorationTag,
-                        class: decorationClass,
-                        'data-decoration-id': decorationId,
-                    }),
-                ]);
+// src/suggestion.ts
+var SuggestionPluginKey = new import_state.PluginKey("suggestion");
+function Suggestion({
+  pluginKey = SuggestionPluginKey,
+  editor,
+  char = "@",
+  allowSpaces = false,
+  allowToIncludeChar = false,
+  allowedPrefixes = [" "],
+  startOfLine = false,
+  decorationTag = "span",
+  decorationClass = "suggestion",
+  decorationContent = "",
+  decorationEmptyClass = "is-empty",
+  command = () => null,
+  items = () => [],
+  render = () => ({}),
+  allow = () => true,
+  findSuggestionMatch: findSuggestionMatch2 = findSuggestionMatch
+}) {
+  let props;
+  const renderer = render == null ? void 0 : render();
+  const plugin = new import_state.Plugin({
+    key: pluginKey,
+    view() {
+      return {
+        update: async (view, prevState) => {
+          var _a, _b, _c, _d, _e, _f, _g;
+          const prev = (_a = this.key) == null ? void 0 : _a.getState(prevState);
+          const next = (_b = this.key) == null ? void 0 : _b.getState(view.state);
+          const moved = prev.active && next.active && prev.range.from !== next.range.from;
+          const started = !prev.active && next.active;
+          const stopped = prev.active && !next.active;
+          const changed = !started && !stopped && prev.query !== next.query;
+          const handleStart = started || moved && changed;
+          const handleChange = changed || moved;
+          const handleExit = stopped || moved && changed;
+          if (!handleStart && !handleChange && !handleExit) {
+            return;
+          }
+          const state = handleExit && !handleStart ? prev : next;
+          const decorationNode = view.dom.querySelector(`[data-decoration-id="${state.decorationId}"]`);
+          props = {
+            editor,
+            range: state.range,
+            query: state.query,
+            text: state.text,
+            items: [],
+            command: (commandProps) => {
+              return command({
+                editor,
+                range: state.range,
+                props: commandProps
+              });
             },
+            decorationNode,
+            // virtual node for positioning
+            // this can be used for building popups without a DOM node
+            clientRect: decorationNode ? () => {
+              var _a2;
+              const { decorationId } = (_a2 = this.key) == null ? void 0 : _a2.getState(editor.state);
+              const currentDecorationNode = view.dom.querySelector(`[data-decoration-id="${decorationId}"]`);
+              return (currentDecorationNode == null ? void 0 : currentDecorationNode.getBoundingClientRect()) || null;
+            } : null
+          };
+          if (handleStart) {
+            (_c = renderer == null ? void 0 : renderer.onBeforeStart) == null ? void 0 : _c.call(renderer, props);
+          }
+          if (handleChange) {
+            (_d = renderer == null ? void 0 : renderer.onBeforeUpdate) == null ? void 0 : _d.call(renderer, props);
+          }
+          if (handleChange || handleStart) {
+            props.items = await items({
+              editor,
+              query: state.query
+            });
+          }
+          if (handleExit) {
+            (_e = renderer == null ? void 0 : renderer.onExit) == null ? void 0 : _e.call(renderer, props);
+          }
+          if (handleChange) {
+            (_f = renderer == null ? void 0 : renderer.onUpdate) == null ? void 0 : _f.call(renderer, props);
+          }
+          if (handleStart) {
+            (_g = renderer == null ? void 0 : renderer.onStart) == null ? void 0 : _g.call(renderer, props);
+          }
         },
-    });
-    return plugin;
+        destroy: () => {
+          var _a;
+          if (!props) {
+            return;
+          }
+          (_a = renderer == null ? void 0 : renderer.onExit) == null ? void 0 : _a.call(renderer, props);
+        }
+      };
+    },
+    state: {
+      // Initialize the plugin's internal state.
+      init() {
+        const state = {
+          active: false,
+          range: {
+            from: 0,
+            to: 0
+          },
+          query: null,
+          text: null,
+          composing: false
+        };
+        return state;
+      },
+      // Apply changes to the plugin state from a view transaction.
+      apply(transaction, prev, _oldState, state) {
+        const { isEditable } = editor;
+        const { composing } = editor.view;
+        const { selection } = transaction;
+        const { empty, from } = selection;
+        const next = { ...prev };
+        next.composing = composing;
+        if (isEditable && (empty || editor.view.composing)) {
+          if ((from < prev.range.from || from > prev.range.to) && !composing && !prev.composing) {
+            next.active = false;
+          }
+          const match = findSuggestionMatch2({
+            char,
+            allowSpaces,
+            allowToIncludeChar,
+            allowedPrefixes,
+            startOfLine,
+            $position: selection.$from
+          });
+          const decorationId = `id_${Math.floor(Math.random() * 4294967295)}`;
+          if (match && allow({
+            editor,
+            state,
+            range: match.range,
+            isActive: prev.active
+          })) {
+            next.active = true;
+            next.decorationId = prev.decorationId ? prev.decorationId : decorationId;
+            next.range = match.range;
+            next.query = match.query;
+            next.text = match.text;
+          } else {
+            next.active = false;
+          }
+        } else {
+          next.active = false;
+        }
+        if (!next.active) {
+          next.decorationId = null;
+          next.range = { from: 0, to: 0 };
+          next.query = null;
+          next.text = null;
+        }
+        return next;
+      }
+    },
+    props: {
+      // Call the keydown hook if suggestion is active.
+      handleKeyDown(view, event) {
+        var _a;
+        const { active, range } = plugin.getState(view.state);
+        if (!active) {
+          return false;
+        }
+        return ((_a = renderer == null ? void 0 : renderer.onKeyDown) == null ? void 0 : _a.call(renderer, { view, event, range })) || false;
+      },
+      // Setup decorator on the currently active suggestion.
+      decorations(state) {
+        const { active, range, decorationId, query } = plugin.getState(state);
+        if (!active) {
+          return null;
+        }
+        const isEmpty = !(query == null ? void 0 : query.length);
+        const classNames = [decorationClass];
+        if (isEmpty) {
+          classNames.push(decorationEmptyClass);
+        }
+        return import_view.DecorationSet.create(state.doc, [
+          import_view.Decoration.inline(range.from, range.to, {
+            nodeName: decorationTag,
+            class: classNames.join(" "),
+            "data-decoration-id": decorationId,
+            "data-decoration-content": decorationContent
+          })
+        ]);
+      }
+    }
+  });
+  return plugin;
 }
 
-exports.Suggestion = Suggestion;
-exports.SuggestionPluginKey = SuggestionPluginKey;
-exports.default = Suggestion;
-exports.findSuggestionMatch = findSuggestionMatch;
-//# sourceMappingURL=index.cjs.map
+// src/index.ts
+var index_default = Suggestion;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Suggestion,
+  SuggestionPluginKey,
+  findSuggestionMatch
+});
+//# sourceMappingURL=index.cjs.map