@tiptap/extension-link 3.0.0 → 3.0.2-beta.0

package/src/link.ts

@@ -1,12 +1,12 @@
-import {
-  Mark, markPasteRule, mergeAttributes, PasteRuleMatch,
-} from '@tiptap/core'
-import { Plugin } from '@tiptap/pm/state'
+import type { PasteRuleMatch } from '@tiptap/core'
+import { Mark, markPasteRule, mergeAttributes } from '@tiptap/core'
+import type { Plugin } from '@tiptap/pm/state'
 import { find, registerCustomProtocol, reset } from 'linkifyjs'
 
 import { autolink } from './helpers/autolink.js'
 import { clickHandler } from './helpers/clickHandler.js'
 import { pasteHandler } from './helpers/pasteHandler.js'
+import { UNICODE_WHITESPACE_REGEX_GLOBAL } from './helpers/whitespace.js'
 
 export interface LinkProtocolOptions {
   /**
@@ -15,17 +15,23 @@ export interface LinkProtocolOptions {
    * @example 'ftp'
    * @example 'git'
    */
-  scheme: string;
+  scheme: string
 
   /**
    * If enabled, it allows optional slashes after the protocol.
    * @default false
    * @example true
    */
-  optionalSlashes?: boolean;
+  optionalSlashes?: boolean
 }
 
-export const pasteRegex = /https?:\/\/(?:www\.)?[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z]{2,}\b(?:[-a-zA-Z0-9@:%._+~#=?!&/]*)(?:[-a-zA-Z0-9@:%._+~#=?!&/]*)/gi
+export const pasteRegex =
+  /https?:\/\/(?:www\.)?[-a-zA-Z0-9@:%._+~#=]{1,256}\.[a-zA-Z]{2,}\b(?:[-a-zA-Z0-9@:%._+~#=?!&/]*)(?:[-a-zA-Z0-9@:%._+~#=?!&/]*)/gi
+
+/**
+ * @deprecated The default behavior is now to open links when the editor is not editable.
+ */
+type DeprecatedOpenWhenNotEditable = 'whenNotEditable'
 
 export interface LinkOptions {
   /**
@@ -51,9 +57,14 @@ export interface LinkOptions {
    * If enabled, links will be opened on click.
    * @default true
    * @example false
-   * @example 'whenNotEditable'
    */
-  openOnClick: boolean
+  openOnClick: boolean | DeprecatedOpenWhenNotEditable
+  /**
+   * If enabled, the link will be selected when clicked.
+   * @default false
+   * @example true
+   */
+  enableClickSelection: boolean
   /**
    * Adds a link to the current selection if the pasted content only contains an url.
    * @default true
@@ -69,11 +80,52 @@ export interface LinkOptions {
   HTMLAttributes: Record<string, any>
 
   /**
+   * @deprecated Use the `shouldAutoLink` option instead.
    * A validation function that modifies link verification for the auto linker.
    * @param url - The url to be validated.
    * @returns - True if the url is valid, false otherwise.
    */
   validate: (url: string) => boolean
+
+  /**
+   * A validation function which is used for configuring link verification for preventing XSS attacks.
+   * Only modify this if you know what you're doing.
+   *
+   * @returns {boolean} `true` if the URL is valid, `false` otherwise.
+   *
+   * @example
+   * isAllowedUri: (url, { defaultValidate, protocols, defaultProtocol }) => {
+   * return url.startsWith('./') || defaultValidate(url)
+   * }
+   */
+  isAllowedUri: (
+    /**
+     * The URL to be validated.
+     */
+    url: string,
+    ctx: {
+      /**
+       * The default validation function.
+       */
+      defaultValidate: (url: string) => boolean
+      /**
+       * An array of allowed protocols for the URL (e.g., "http", "https"). As defined in the `protocols` option.
+       */
+      protocols: Array<LinkProtocolOptions | string>
+      /**
+       * A string that represents the default protocol (e.g., 'http'). As defined in the `defaultProtocol` option.
+       */
+      defaultProtocol: string
+    },
+  ) => boolean
+
+  /**
+   * Determines whether a valid link should be automatically linked in the content.
+   *
+   * @param {string} url - The URL that has already been validated.
+   * @returns {boolean} - True if the link should be auto-linked; false if it should not be auto-linked.
+   */
+  shouldAutoLink: (url: string) => boolean
 }
 
 declare module '@tiptap/core' {
@@ -84,13 +136,23 @@ declare module '@tiptap/core' {
        * @param attributes The link attributes
        * @example editor.commands.setLink({ href: 'https://tiptap.dev' })
        */
-      setLink: (attributes: { href: string; target?: string | null; rel?: string | null; class?: string | null }) => ReturnType
+      setLink: (attributes: {
+        href: string
+        target?: string | null
+        rel?: string | null
+        class?: string | null
+      }) => ReturnType
       /**
        * Toggle a link mark
        * @param attributes The link attributes
        * @example editor.commands.toggleLink({ href: 'https://tiptap.dev' })
        */
-      toggleLink: (attributes: { href: string; target?: string | null; rel?: string | null; class?: string | null }) => ReturnType
+      toggleLink: (attributes?: {
+        href: string
+        target?: string | null
+        rel?: string | null
+        class?: string | null
+      }) => ReturnType
       /**
        * Unset a link mark
        * @example editor.commands.unsetLink()
@@ -100,13 +162,29 @@ declare module '@tiptap/core' {
   }
 }
 
-// From DOMPurify
-// https://github.com/cure53/DOMPurify/blob/main/src/regexp.js
-const ATTR_WHITESPACE = /[\u0000-\u0020\u00A0\u1680\u180E\u2000-\u2029\u205F\u3000]/g // eslint-disable-line no-control-regex
-const IS_ALLOWED_URI = /^(?:(?:(?:f|ht)tps?|mailto|tel|callto|sms|cid|xmpp):|[^a-z]|[a-z+.\-]+(?:[^a-z+.\-:]|$))/i // eslint-disable-line no-useless-escape
+export function isAllowedUri(uri: string | undefined, protocols?: LinkOptions['protocols']) {
+  const allowedProtocols: string[] = ['http', 'https', 'ftp', 'ftps', 'mailto', 'tel', 'callto', 'sms', 'cid', 'xmpp']
 
-function isAllowedUri(uri: string | undefined) {
-  return !uri || uri.replace(ATTR_WHITESPACE, '').match(IS_ALLOWED_URI)
+  if (protocols) {
+    protocols.forEach(protocol => {
+      const nextProtocol = typeof protocol === 'string' ? protocol : protocol.scheme
+
+      if (nextProtocol) {
+        allowedProtocols.push(nextProtocol)
+      }
+    })
+  }
+
+  return (
+    !uri ||
+    uri.replace(UNICODE_WHITESPACE_REGEX_GLOBAL, '').match(
+      new RegExp(
+        // eslint-disable-next-line no-useless-escape
+        `^(?:(?:${allowedProtocols.join('|')}):|[^a-z]|[a-z0-9+.\-]+(?:[^a-z+.\-:]|$))`,
+        'i',
+      ),
+    )
+  )
 }
 
 /**
@@ -123,6 +201,11 @@ export const Link = Mark.create<LinkOptions>({
   exitable: true,
 
   onCreate() {
+    if (this.options.validate && !this.options.shouldAutoLink) {
+      // Copy the validate function to the shouldAutoLink option
+      this.options.shouldAutoLink = this.options.validate
+      console.warn('The `validate` option is deprecated. Rename to the `shouldAutoLink` option instead.')
+    }
     this.options.protocols.forEach(protocol => {
       if (typeof protocol === 'string') {
         registerCustomProtocol(protocol)
@@ -143,6 +226,7 @@ export const Link = Mark.create<LinkOptions>({
   addOptions() {
     return {
       openOnClick: true,
+      enableClickSelection: false,
       linkOnPaste: true,
       autolink: true,
       protocols: [],
@@ -152,7 +236,9 @@ export const Link = Mark.create<LinkOptions>({
         rel: 'noopener noreferrer nofollow',
         class: null,
       },
+      isAllowedUri: (url, ctx) => !!isAllowedUri(url, ctx.protocols),
       validate: url => !!url,
+      shouldAutoLink: url => !!url,
     }
   },
 
@@ -160,6 +246,9 @@ export const Link = Mark.create<LinkOptions>({
     return {
       href: {
         default: null,
+        parseHTML(element) {
+          return element.getAttribute('href')
+        },
       },
       target: {
         default: this.options.HTMLAttributes.target,
@@ -174,23 +263,38 @@ export const Link = Mark.create<LinkOptions>({
   },
 
   parseHTML() {
-    return [{
-      tag: 'a[href]',
-      getAttrs: dom => {
-        const href = (dom as HTMLElement).getAttribute('href')
-
-        // prevent XSS attacks
-        if (!href || !isAllowedUri(href)) {
-          return false
-        }
-        return { href }
+    return [
+      {
+        tag: 'a[href]',
+        getAttrs: dom => {
+          const href = (dom as HTMLElement).getAttribute('href')
+
+          // prevent XSS attacks
+          if (
+            !href ||
+            !this.options.isAllowedUri(href, {
+              defaultValidate: url => !!isAllowedUri(url, this.options.protocols),
+              protocols: this.options.protocols,
+              defaultProtocol: this.options.defaultProtocol,
+            })
+          ) {
+            return false
+          }
+          return null
+        },
       },
-    }]
+    ]
   },
 
   renderHTML({ HTMLAttributes }) {
     // prevent XSS attacks
-    if (!isAllowedUri(HTMLAttributes.href)) {
+    if (
+      !this.options.isAllowedUri(HTMLAttributes.href, {
+        defaultValidate: href => !!isAllowedUri(href, this.options.protocols),
+        protocols: this.options.protocols,
+        defaultProtocol: this.options.defaultProtocol,
+      })
+    ) {
       // strip out the href
       return ['a', mergeAttributes(this.options.HTMLAttributes, { ...HTMLAttributes, href: '' }), 0]
     }
@@ -201,12 +305,39 @@ export const Link = Mark.create<LinkOptions>({
   addCommands() {
     return {
       setLink:
-        attributes => ({ chain }) => {
+        attributes =>
+        ({ chain }) => {
+          const { href } = attributes
+
+          if (
+            !this.options.isAllowedUri(href, {
+              defaultValidate: url => !!isAllowedUri(url, this.options.protocols),
+              protocols: this.options.protocols,
+              defaultProtocol: this.options.defaultProtocol,
+            })
+          ) {
+            return false
+          }
+
           return chain().setMark(this.name, attributes).setMeta('preventAutolink', true).run()
         },
 
       toggleLink:
-        attributes => ({ chain }) => {
+        attributes =>
+        ({ chain }) => {
+          const { href } = attributes || {}
+
+          if (
+            href &&
+            !this.options.isAllowedUri(href, {
+              defaultValidate: url => !!isAllowedUri(url, this.options.protocols),
+              protocols: this.options.protocols,
+              defaultProtocol: this.options.defaultProtocol,
+            })
+          ) {
+            return false
+          }
+
           return chain()
             .toggleMark(this.name, attributes, { extendEmptyMarkRange: true })
             .setMeta('preventAutolink', true)
@@ -214,11 +345,9 @@ export const Link = Mark.create<LinkOptions>({
         },
 
       unsetLink:
-        () => ({ chain }) => {
-          return chain()
-            .unsetMark(this.name, { extendEmptyMarkRange: true })
-            .setMeta('preventAutolink', true)
-            .run()
+        () =>
+        ({ chain }) => {
+          return chain().unsetMark(this.name, { extendEmptyMarkRange: true }).setMeta('preventAutolink', true).run()
         },
     }
   },
@@ -230,17 +359,27 @@ export const Link = Mark.create<LinkOptions>({
           const foundLinks: PasteRuleMatch[] = []
 
           if (text) {
-            const { validate } = this.options
-            const links = find(text).filter(item => item.isLink && validate(item.value))
+            const { protocols, defaultProtocol } = this.options
+            const links = find(text).filter(
+              item =>
+                item.isLink &&
+                this.options.isAllowedUri(item.value, {
+                  defaultValidate: href => !!isAllowedUri(href, protocols),
+                  protocols,
+                  defaultProtocol,
+                }),
+            )
 
             if (links.length) {
-              links.forEach(link => (foundLinks.push({
-                text: link.value,
-                data: {
-                  href: link.href,
-                },
-                index: link.start,
-              })))
+              links.forEach(link =>
+                foundLinks.push({
+                  text: link.value,
+                  data: {
+                    href: link.href,
+                  },
+                  index: link.start,
+                }),
+              )
             }
           }
 
@@ -258,21 +397,30 @@ export const Link = Mark.create<LinkOptions>({
 
   addProseMirrorPlugins() {
     const plugins: Plugin[] = []
+    const { protocols, defaultProtocol } = this.options
 
     if (this.options.autolink) {
       plugins.push(
         autolink({
           type: this.type,
           defaultProtocol: this.options.defaultProtocol,
-          validate: this.options.validate,
+          validate: url =>
+            this.options.isAllowedUri(url, {
+              defaultValidate: href => !!isAllowedUri(href, protocols),
+              protocols,
+              defaultProtocol,
+            }),
+          shouldAutoLink: this.options.shouldAutoLink,
         }),
       )
     }
 
-    if (this.options.openOnClick) {
+    if (this.options.openOnClick === true) {
       plugins.push(
         clickHandler({
           type: this.type,
+          editor: this.editor,
+          enableClickSelection: this.options.enableClickSelection,
         }),
       )
     }