@tiptap/extension-mention 2.22.3 → 2.23.1

package/src/mention.ts

@@ -1,7 +1,11 @@
+import type { Editor } from '@tiptap/core'
 import { mergeAttributes, Node } from '@tiptap/core'
-import { DOMOutputSpec, Node as ProseMirrorNode } from '@tiptap/pm/model'
-import { PluginKey } from '@tiptap/pm/state'
-import Suggestion, { SuggestionOptions } from '@tiptap/suggestion'
+import type { DOMOutputSpec } from '@tiptap/pm/model'
+import { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import type { SuggestionOptions } from '@tiptap/suggestion'
+import Suggestion from '@tiptap/suggestion'
+
+import { getSuggestionOptions } from './utils/get-default-suggestion-attributes.js'
 
 // See `addAttributes` below
 export interface MentionNodeAttrs {
@@ -14,10 +18,15 @@ export interface MentionNodeAttrs {
    * The label to be rendered by the editor as the displayed text for this mentioned
    * item, if provided. Stored as a `data-label` attribute. See `renderLabel`.
    */
-  label?: string | null;
+  label?: string | null
+  /**
+   * The character that triggers the suggestion, stored as
+   * `data-mention-suggestion-char` attribute.
+   */
+  mentionSuggestionChar?: string
 }
 
-export type MentionOptions<SuggestionItem = any, Attrs extends Record<string, any> = MentionNodeAttrs> = {
+export interface MentionOptions<SuggestionItem = any, Attrs extends Record<string, any> = MentionNodeAttrs> {
   /**
    * The HTML attributes for a mention node.
    * @default {}
@@ -32,7 +41,11 @@ export type MentionOptions<SuggestionItem = any, Attrs extends Record<string, an
    * @returns The label
    * @example ({ options, node }) => `${options.suggestion.char}${node.attrs.label ?? node.attrs.id}`
    */
-  renderLabel?: (props: { options: MentionOptions<SuggestionItem, Attrs>; node: ProseMirrorNode }) => string
+  renderLabel?: (props: {
+    options: MentionOptions<SuggestionItem, Attrs>
+    node: ProseMirrorNode
+    suggestion: SuggestionOptions | null
+  }) => string
 
   /**
    * A function to render the text of a mention.
@@ -40,7 +53,11 @@ export type MentionOptions<SuggestionItem = any, Attrs extends Record<string, an
    * @returns The text
    * @example ({ options, node }) => `${options.suggestion.char}${node.attrs.label ?? node.attrs.id}`
    */
-  renderText: (props: { options: MentionOptions<SuggestionItem, Attrs>; node: ProseMirrorNode }) => string
+  renderText: (props: {
+    options: MentionOptions<SuggestionItem, Attrs>
+    node: ProseMirrorNode
+    suggestion: SuggestionOptions | null
+  }) => string
 
   /**
    * A function to render the HTML of a mention.
@@ -48,7 +65,11 @@ export type MentionOptions<SuggestionItem = any, Attrs extends Record<string, an
    * @returns The HTML as a ProseMirror DOM Output Spec
    * @example ({ options, node }) => ['span', { 'data-type': 'mention' }, `${options.suggestion.char}${node.attrs.label ?? node.attrs.id}`]
    */
-  renderHTML: (props: { options: MentionOptions<SuggestionItem, Attrs>; node: ProseMirrorNode }) => DOMOutputSpec
+  renderHTML: (props: {
+    options: MentionOptions<SuggestionItem, Attrs>
+    node: ProseMirrorNode
+    suggestion: SuggestionOptions | null
+  }) => DOMOutputSpec
 
   /**
    * Whether to delete the trigger character with backspace.
@@ -57,18 +78,73 @@ export type MentionOptions<SuggestionItem = any, Attrs extends Record<string, an
   deleteTriggerWithBackspace: boolean
 
   /**
-   * The suggestion options.
+   * The suggestion options, when you want to support multiple triggers.
+   *
+   * With this parameter, you can define multiple types of mention. For example, you can use the `@` character
+   * to mention users and the `#` character to mention tags.
+   *
+   * @default [{ char: '@', pluginKey: MentionPluginKey }]
+   * @example [{ char: '@', pluginKey: MentionPluginKey }, { char: '#', pluginKey: new PluginKey('hashtag') }]
+   */
+  suggestions: Array<Omit<SuggestionOptions<SuggestionItem, Attrs>, 'editor'>>
+
+  /**
+   * The suggestion options, when you want to support only one trigger. To support multiple triggers, use the
+   * `suggestions` parameter instead.
+   *
    * @default {}
    * @example { char: '@', pluginKey: MentionPluginKey, command: ({ editor, range, props }) => { ... } }
    */
   suggestion: Omit<SuggestionOptions<SuggestionItem, Attrs>, 'editor'>
 }
 
+interface GetSuggestionsOptions {
+  editor?: Editor
+  options: MentionOptions
+  name: string
+}
+
+/**
+ * Returns the suggestions for the mention extension.
+ *
+ * @param options The extension options
+ * @returns the suggestions
+ */
+function getSuggestions(options: GetSuggestionsOptions) {
+  return (options.options.suggestions.length ? options.options.suggestions : [options.options.suggestion]).map(
+    suggestion => getSuggestionOptions({
+      // @ts-ignore `editor` can be `undefined` when converting the document to HTML with the HTML utility
+      editor: options.editor,
+      overrideSuggestionOptions: suggestion,
+      extensionName: options.name,
+      char: suggestion.char,
+    }),
+  )
+}
+
 /**
- * The plugin key for the mention plugin.
- * @default 'mention'
+ * Returns the suggestion options of the mention that has a given character trigger. If not
+ * found, it returns the first suggestion.
+ *
+ * @param options The extension options
+ * @param char The character that triggers the mention
+ * @returns The suggestion options
  */
-export const MentionPluginKey = new PluginKey('mention')
+function getSuggestionFromChar(options: GetSuggestionsOptions, char: string) {
+  const suggestions = getSuggestions(options)
+
+  const suggestion = suggestions.find(s => s.char === char)
+
+  if (suggestion) {
+    return suggestion
+  }
+
+  if (suggestions.length) {
+    return suggestions[0]
+  }
+
+  return null
+}
 
 /**
  * This extension allows you to insert mentions into the editor.
@@ -82,56 +158,19 @@ export const Mention = Node.create<MentionOptions>({
   addOptions() {
     return {
       HTMLAttributes: {},
-      renderText({ options, node }) {
-        return `${options.suggestion.char}${node.attrs.label ?? node.attrs.id}`
+      renderText({ node, suggestion }) {
+        return `${suggestion?.char ?? '@'}${node.attrs.label ?? node.attrs.id}`
       },
       deleteTriggerWithBackspace: false,
-      renderHTML({ options, node }) {
+      renderHTML({ options, node, suggestion }) {
         return [
           'span',
           mergeAttributes(this.HTMLAttributes, options.HTMLAttributes),
-          `${options.suggestion.char}${node.attrs.label ?? node.attrs.id}`,
+          `${suggestion?.char ?? '@'}${node.attrs.label ?? node.attrs.id}`,
         ]
       },
-      suggestion: {
-        char: '@',
-        pluginKey: MentionPluginKey,
-        command: ({ editor, range, props }) => {
-          // increase range.to by one when the next node is of type "text"
-          // and starts with a space character
-          const nodeAfter = editor.view.state.selection.$to.nodeAfter
-          const overrideSpace = nodeAfter?.text?.startsWith(' ')
-
-          if (overrideSpace) {
-            range.to += 1
-          }
-
-          editor
-            .chain()
-            .focus()
-            .insertContentAt(range, [
-              {
-                type: this.name,
-                attrs: props,
-              },
-              {
-                type: 'text',
-                text: ' ',
-              },
-            ])
-            .run()
-
-          // get reference to `window` object from editor element, to support cross-frame JS usage
-          editor.view.dom.ownerDocument.defaultView?.getSelection()?.collapseToEnd()
-        },
-        allow: ({ state, range }) => {
-          const $from = state.doc.resolve(range.from)
-          const type = state.schema.nodes[this.name]
-          const allow = !!$from.parent.type.contentMatch.matchType(type)
-
-          return allow
-        },
-      },
+      suggestions: [],
+      suggestion: {},
     }
   },
 
@@ -172,6 +211,17 @@ export const Mention = Node.create<MentionOptions>({
           }
         },
       },
+
+      // When there are multiple types of mentions, this attribute helps distinguish them
+      mentionSuggestionChar: {
+        default: '@',
+        parseHTML: element => element.getAttribute('data-mention-suggestion-char'),
+        renderHTML: attributes => {
+          return {
+            'data-mention-suggestion-char': attributes.mentionSuggestionChar,
+          }
+        },
+      },
     }
   },
 
@@ -184,6 +234,8 @@ export const Mention = Node.create<MentionOptions>({
   },
 
   renderHTML({ node, HTMLAttributes }) {
+    const suggestion = getSuggestionFromChar(this, node.attrs.mentionSuggestionChar)
+
     if (this.options.renderLabel !== undefined) {
       console.warn('renderLabel is deprecated use renderText and renderHTML instead')
       return [
@@ -192,15 +244,22 @@ export const Mention = Node.create<MentionOptions>({
         this.options.renderLabel({
           options: this.options,
           node,
+          suggestion,
         }),
       ]
     }
     const mergedOptions = { ...this.options }
 
-    mergedOptions.HTMLAttributes = mergeAttributes({ 'data-type': this.name }, this.options.HTMLAttributes, HTMLAttributes)
+    mergedOptions.HTMLAttributes = mergeAttributes(
+      { 'data-type': this.name },
+      this.options.HTMLAttributes,
+      HTMLAttributes,
+    )
+
     const html = this.options.renderHTML({
       options: mergedOptions,
       node,
+      suggestion,
     })
 
     if (typeof html === 'string') {
@@ -214,17 +273,18 @@ export const Mention = Node.create<MentionOptions>({
   },
 
   renderText({ node }) {
+    const args = {
+      options: this.options,
+      node,
+      suggestion: getSuggestionFromChar(this, node.attrs.mentionSuggestionChar),
+    }
+
     if (this.options.renderLabel !== undefined) {
       console.warn('renderLabel is deprecated use renderText and renderHTML instead')
-      return this.options.renderLabel({
-        options: this.options,
-        node,
-      })
+      return this.options.renderLabel(args)
     }
-    return this.options.renderText({
-      options: this.options,
-      node,
-    })
+
+    return this.options.renderText(args)
   },
 
   addKeyboardShortcuts() {
@@ -251,17 +311,34 @@ export const Mention = Node.create<MentionOptions>({
           }
         })
 
+        // Store node and position for later use
+        let mentionNode = new ProseMirrorNode()
+        let mentionPos = 0
+
+        state.doc.nodesBetween(anchor - 1, anchor, (node, pos) => {
+          if (node.type.name === this.name) {
+            isMention = true
+            mentionNode = node
+            mentionPos = pos
+            return false
+          }
+        })
+
+        if (isMention) {
+          tr.insertText(
+            this.options.deleteTriggerWithBackspace ? '' : mentionNode.attrs.mentionSuggestionChar,
+            mentionPos,
+            mentionPos + mentionNode.nodeSize,
+          )
+        }
+
         return isMention
       }),
     }
   },
 
   addProseMirrorPlugins() {
-    return [
-      Suggestion({
-        editor: this.editor,
-        ...this.options.suggestion,
-      }),
-    ]
+    // Create a plugin for each suggestion configuration
+    return getSuggestions(this).map(Suggestion)
   },
 })

package/src/utils/get-default-suggestion-attributes.ts

@@ -0,0 +1,89 @@
+import type { Editor } from '@tiptap/core'
+import { PluginKey } from '@tiptap/pm/state'
+import type { SuggestionOptions } from '@tiptap/suggestion'
+
+/**
+ * Arguments for the `getSuggestionOptions` function
+ * @see getSuggestionOptions
+ */
+export interface GetSuggestionOptionsOptions {
+  /**
+   * The Tiptap editor instance.
+   */
+  editor: Editor
+  /**
+   * The suggestion options configuration provided to the
+   * `Mention` extension.
+   */
+  overrideSuggestionOptions: Omit<SuggestionOptions, 'editor'>
+  /**
+   * The name of the Mention extension
+   */
+  extensionName: string
+  /**
+   * The character that triggers the suggestion.
+   * @default '@'
+   */
+  char?: string
+}
+
+/**
+ * Returns the suggestion options for a trigger of the Mention extension. These
+ * options are used to create a `Suggestion` ProseMirror plugin. Each plugin lets
+ * you define a different trigger that opens the Mention menu. For example,
+ * you can define a `@` trigger to mention users and a `#` trigger to mention
+ * tags.
+ *
+ * @param param0 The configured options for the suggestion
+ * @returns
+ */
+export function getSuggestionOptions({
+  editor: tiptapEditor,
+  overrideSuggestionOptions,
+  extensionName,
+  char = '@',
+}: GetSuggestionOptionsOptions): SuggestionOptions {
+  const pluginKey = new PluginKey()
+
+  return {
+    editor: tiptapEditor,
+    char,
+    pluginKey,
+    command: ({ editor, range, props }: { editor: any; range: any; props: any }) => {
+      // increase range.to by one when the next node is of type "text"
+      // and starts with a space character
+      const nodeAfter = editor.view.state.selection.$to.nodeAfter
+      const overrideSpace = nodeAfter?.text?.startsWith(' ')
+
+      if (overrideSpace) {
+        range.to += 1
+      }
+
+      editor
+        .chain()
+        .focus()
+        .insertContentAt(range, [
+          {
+            type: extensionName,
+            attrs: { ...props, mentionSuggestionChar: char },
+          },
+          {
+            type: 'text',
+            text: ' ',
+          },
+        ])
+        .run()
+
+      // get reference to `window` object from editor element, to support cross-frame JS usage
+      editor.view.dom.ownerDocument.defaultView?.getSelection()?.collapseToEnd()
+    },
+    allow: ({ state, range }: { state: any; range: any }) => {
+      const $from = state.doc.resolve(range.from)
+      const type = state.schema.nodes[extensionName]
+      const allow = !!$from.parent.type.contentMatch.matchType(type)
+
+      return allow
+    },
+    ...overrideSuggestionOptions,
+  }
+}