@tiptap/extensions 3.0.0-beta.0

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@tiptap/extensions",
+  "description": "various extensions for tiptap",
+  "version": "3.0.0-beta.0",
+  "homepage": "https://tiptap.dev",
+  "keywords": [
+    "tiptap",
+    "tiptap extension"
+  ],
+  "license": "MIT",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/ueberdosis"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./character-count": {
+      "types": {
+        "import": "./dist/character-count/index.d.ts",
+        "require": "./dist/character-count/index.d.cts"
+      },
+      "import": "./dist/character-count/index.js",
+      "require": "./dist/character-count/index.cjs"
+    },
+    "./drop-cursor": {
+      "types": {
+        "import": "./dist/drop-cursor/index.d.ts",
+        "require": "./dist/drop-cursor/index.d.cts"
+      },
+      "import": "./dist/drop-cursor/index.js",
+      "require": "./dist/drop-cursor/index.cjs"
+    },
+    "./focus": {
+      "types": {
+        "import": "./dist/focus/index.d.ts",
+        "require": "./dist/focus/index.d.cts"
+      },
+      "import": "./dist/focus/index.js",
+      "require": "./dist/focus/index.cjs"
+    },
+    "./gap-cursor": {
+      "types": {
+        "import": "./dist/gap-cursor/index.d.ts",
+        "require": "./dist/gap-cursor/index.d.cts"
+      },
+      "import": "./dist/gap-cursor/index.js",
+      "require": "./dist/gap-cursor/index.cjs"
+    },
+    "./undo-redo": {
+      "types": {
+        "import": "./dist/undo-redo/index.d.ts",
+        "require": "./dist/undo-redo/index.d.cts"
+      },
+      "import": "./dist/undo-redo/index.js",
+      "require": "./dist/undo-redo/index.cjs"
+    },
+    "./placeholder": {
+      "types": {
+        "import": "./dist/placeholder/index.d.ts",
+        "require": "./dist/placeholder/index.d.cts"
+      },
+      "import": "./dist/placeholder/index.js",
+      "require": "./dist/placeholder/index.cjs"
+    },
+    "./selection": {
+      "types": {
+        "import": "./dist/selection/index.d.ts",
+        "require": "./dist/selection/index.d.cts"
+      },
+      "import": "./dist/selection/index.js",
+      "require": "./dist/selection/index.cjs"
+    },
+    "./trailing-node": {
+      "types": {
+        "import": "./dist/trailing-node/index.d.ts",
+        "require": "./dist/trailing-node/index.d.cts"
+      },
+      "import": "./dist/trailing-node/index.js",
+      "require": "./dist/trailing-node/index.cjs"
+    }
+  },
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "src",
+    "dist"
+  ],
+  "devDependencies": {
+    "@tiptap/core": "^3.0.0-beta.0",
+    "@tiptap/pm": "^3.0.0-beta.0"
+  },
+  "peerDependencies": {
+    "@tiptap/core": "^3.0.0-beta.0",
+    "@tiptap/pm": "^3.0.0-beta.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ueberdosis/tiptap",
+    "directory": "packages/extension"
+  },
+  "scripts": {
+    "build": "tsup",
+    "lint": "prettier ./src/ --check && eslint --cache --quiet --no-error-on-unmatched-pattern ./src/"
+  }
+}

package/src/character-count/character-count.ts

@@ -0,0 +1,195 @@
+import { Extension } from '@tiptap/core'
+import type { Node as ProseMirrorNode } from '@tiptap/pm/model'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+
+export interface CharacterCountOptions {
+  /**
+   * The maximum number of characters that should be allowed. Defaults to `0`.
+   * @default null
+   * @example 180
+   */
+  limit: number | null | undefined
+  /**
+   * The mode by which the size is calculated. If set to `textSize`, the textContent of the document is used.
+   * If set to `nodeSize`, the nodeSize of the document is used.
+   * @default 'textSize'
+   * @example 'textSize'
+   */
+  mode: 'textSize' | 'nodeSize'
+  /**
+   * The text counter function to use. Defaults to a simple character count.
+   * @default (text) => text.length
+   * @example (text) => [...new Intl.Segmenter().segment(text)].length
+   */
+  textCounter: (text: string) => number
+  /**
+   * The word counter function to use. Defaults to a simple word count.
+   * @default (text) => text.split(' ').filter(word => word !== '').length
+   * @example (text) => text.split(/\s+/).filter(word => word !== '').length
+   */
+  wordCounter: (text: string) => number
+}
+
+export interface CharacterCountStorage {
+  /**
+   * Get the number of characters for the current document.
+   * @param options The options for the character count. (optional)
+   * @param options.node The node to get the characters from. Defaults to the current document.
+   * @param options.mode The mode by which the size is calculated. If set to `textSize`, the textContent of the document is used.
+   */
+  characters: (options?: { node?: ProseMirrorNode; mode?: 'textSize' | 'nodeSize' }) => number
+
+  /**
+   * Get the number of words for the current document.
+   * @param options The options for the character count. (optional)
+   * @param options.node The node to get the words from. Defaults to the current document.
+   */
+  words: (options?: { node?: ProseMirrorNode }) => number
+}
+
+declare module '@tiptap/core' {
+  interface Storage {
+    characterCount: CharacterCountStorage
+  }
+}
+
+/**
+ * This extension allows you to count the characters and words of your document.
+ * @see https://tiptap.dev/api/extensions/character-count
+ */
+export const CharacterCount = Extension.create<CharacterCountOptions, CharacterCountStorage>({
+  name: 'characterCount',
+
+  addOptions() {
+    return {
+      limit: null,
+      mode: 'textSize',
+      textCounter: text => text.length,
+      wordCounter: text => text.split(' ').filter(word => word !== '').length,
+    }
+  },
+
+  addStorage() {
+    return {
+      characters: () => 0,
+      words: () => 0,
+    }
+  },
+
+  onBeforeCreate() {
+    this.storage.characters = options => {
+      const node = options?.node || this.editor.state.doc
+      const mode = options?.mode || this.options.mode
+
+      if (mode === 'textSize') {
+        const text = node.textBetween(0, node.content.size, undefined, ' ')
+
+        return this.options.textCounter(text)
+      }
+
+      return node.nodeSize
+    }
+
+    this.storage.words = options => {
+      const node = options?.node || this.editor.state.doc
+      const text = node.textBetween(0, node.content.size, ' ', ' ')
+
+      return this.options.wordCounter(text)
+    }
+  },
+
+  addProseMirrorPlugins() {
+    let initialEvaluationDone = false
+
+    return [
+      new Plugin({
+        key: new PluginKey('characterCount'),
+        appendTransaction: (transactions, oldState, newState) => {
+          if (initialEvaluationDone) {
+            return
+          }
+
+          const limit = this.options.limit
+
+          if (limit === null || limit === undefined || limit === 0) {
+            initialEvaluationDone = true
+            return
+          }
+
+          const initialContentSize = this.storage.characters({ node: newState.doc })
+
+          if (initialContentSize > limit) {
+            const over = initialContentSize - limit
+            const from = 0
+            const to = over
+
+            console.warn(
+              `[CharacterCount] Initial content exceeded limit of ${limit} characters. Content was automatically trimmed.`,
+            )
+            const tr = newState.tr.deleteRange(from, to)
+
+            initialEvaluationDone = true
+            return tr
+          }
+
+          initialEvaluationDone = true
+        },
+        filterTransaction: (transaction, state) => {
+          const limit = this.options.limit
+
+          // Nothing has changed or no limit is defined. Ignore it.
+          if (!transaction.docChanged || limit === 0 || limit === null || limit === undefined) {
+            return true
+          }
+
+          const oldSize = this.storage.characters({ node: state.doc })
+          const newSize = this.storage.characters({ node: transaction.doc })
+
+          // Everything is in the limit. Good.
+          if (newSize <= limit) {
+            return true
+          }
+
+          // The limit has already been exceeded but will be reduced.
+          if (oldSize > limit && newSize > limit && newSize <= oldSize) {
+            return true
+          }
+
+          // The limit has already been exceeded and will be increased further.
+          if (oldSize > limit && newSize > limit && newSize > oldSize) {
+            return false
+          }
+
+          const isPaste = transaction.getMeta('paste')
+
+          // Block all exceeding transactions that were not pasted.
+          if (!isPaste) {
+            return false
+          }
+
+          // For pasted content, we try to remove the exceeding content.
+          const pos = transaction.selection.$head.pos
+          const over = newSize - limit
+          const from = pos - over
+          const to = pos
+
+          // It’s probably a bad idea to mutate transactions within `filterTransaction`
+          // but for now this is working fine.
+          transaction.deleteRange(from, to)
+
+          // In some situations, the limit will continue to be exceeded after trimming.
+          // This happens e.g. when truncating within a complex node (e.g. table)
+          // and ProseMirror has to close this node again.
+          // If this is the case, we prevent the transaction completely.
+          const updatedSize = this.storage.characters({ node: transaction.doc })
+
+          if (updatedSize > limit) {
+            return false
+          }
+
+          return true
+        },
+      }),
+    ]
+  },
+})

package/src/character-count/index.ts

@@ -0,0 +1 @@
+export * from './character-count.js'

package/src/drop-cursor/drop-cursor.ts

@@ -0,0 +1,47 @@
+import { Extension } from '@tiptap/core'
+import { dropCursor } from '@tiptap/pm/dropcursor'
+
+export interface DropcursorOptions {
+  /**
+   * The color of the drop cursor
+   * @default 'currentColor'
+   * @example 'red'
+   */
+  color: string | undefined
+
+  /**
+   * The width of the drop cursor
+   * @default 1
+   * @example 2
+   */
+  width: number | undefined
+
+  /**
+   * The class of the drop cursor
+   * @default undefined
+   * @example 'drop-cursor'
+   */
+  class: string | undefined
+}
+
+/**
+ * This extension allows you to add a drop cursor to your editor.
+ * A drop cursor is a line that appears when you drag and drop content
+ * in-between nodes.
+ * @see https://tiptap.dev/api/extensions/dropcursor
+ */
+export const Dropcursor = Extension.create<DropcursorOptions>({
+  name: 'dropCursor',
+
+  addOptions() {
+    return {
+      color: 'currentColor',
+      width: 1,
+      class: undefined,
+    }
+  },
+
+  addProseMirrorPlugins() {
+    return [dropCursor(this.options)]
+  },
+})

package/src/drop-cursor/index.ts

@@ -0,0 +1 @@
+export * from './drop-cursor.js'

package/src/focus/focus.ts

@@ -0,0 +1,110 @@
+import { Extension } from '@tiptap/core'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+
+export interface FocusOptions {
+  /**
+   * The class name that should be added to the focused node.
+   * @default 'has-focus'
+   * @example 'is-focused'
+   */
+  className: string
+
+  /**
+   * The mode by which the focused node is determined.
+   * - All: All nodes are marked as focused.
+   * - Deepest: Only the deepest node is marked as focused.
+   * - Shallowest: Only the shallowest node is marked as focused.
+   *
+   * @default 'all'
+   * @example 'deepest'
+   * @example 'shallowest'
+   */
+  mode: 'all' | 'deepest' | 'shallowest'
+}
+
+/**
+ * This extension allows you to add a class to the focused node.
+ * @see https://www.tiptap.dev/api/extensions/focus
+ */
+export const Focus = Extension.create<FocusOptions>({
+  name: 'focus',
+
+  addOptions() {
+    return {
+      className: 'has-focus',
+      mode: 'all',
+    }
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        key: new PluginKey('focus'),
+        props: {
+          decorations: ({ doc, selection }) => {
+            const { isEditable, isFocused } = this.editor
+            const { anchor } = selection
+            const decorations: Decoration[] = []
+
+            if (!isEditable || !isFocused) {
+              return DecorationSet.create(doc, [])
+            }
+
+            // Maximum Levels
+            let maxLevels = 0
+
+            if (this.options.mode === 'deepest') {
+              doc.descendants((node, pos) => {
+                if (node.isText) {
+                  return
+                }
+
+                const isCurrent = anchor >= pos && anchor <= pos + node.nodeSize - 1
+
+                if (!isCurrent) {
+                  return false
+                }
+
+                maxLevels += 1
+              })
+            }
+
+            // Loop through current
+            let currentLevel = 0
+
+            doc.descendants((node, pos) => {
+              if (node.isText) {
+                return false
+              }
+
+              const isCurrent = anchor >= pos && anchor <= pos + node.nodeSize - 1
+
+              if (!isCurrent) {
+                return false
+              }
+
+              currentLevel += 1
+
+              const outOfScope =
+                (this.options.mode === 'deepest' && maxLevels - currentLevel > 0) ||
+                (this.options.mode === 'shallowest' && currentLevel > 1)
+
+              if (outOfScope) {
+                return this.options.mode === 'deepest'
+              }
+
+              decorations.push(
+                Decoration.node(pos, pos + node.nodeSize, {
+                  class: this.options.className,
+                }),
+              )
+            })
+
+            return DecorationSet.create(doc, decorations)
+          },
+        },
+      }),
+    ]
+  },
+})

package/src/focus/index.ts

@@ -0,0 +1 @@
+export * from './focus.js'

package/src/gap-cursor/gap-cursor.ts

@@ -0,0 +1,47 @@
+import type { ParentConfig } from '@tiptap/core'
+import { callOrReturn, Extension, getExtensionField } from '@tiptap/core'
+import { gapCursor } from '@tiptap/pm/gapcursor'
+
+declare module '@tiptap/core' {
+  interface NodeConfig<Options, Storage> {
+    /**
+     * A function to determine whether the gap cursor is allowed at the current position. Must return `true` or `false`.
+     * @default null
+     */
+    allowGapCursor?:
+      | boolean
+      | null
+      | ((this: {
+          name: string
+          options: Options
+          storage: Storage
+          parent: ParentConfig<NodeConfig<Options>>['allowGapCursor']
+        }) => boolean | null)
+  }
+}
+
+/**
+ * This extension allows you to add a gap cursor to your editor.
+ * A gap cursor is a cursor that appears when you click on a place
+ * where no content is present, for example inbetween nodes.
+ * @see https://tiptap.dev/api/extensions/gapcursor
+ */
+export const Gapcursor = Extension.create({
+  name: 'gapCursor',
+
+  addProseMirrorPlugins() {
+    return [gapCursor()]
+  },
+
+  extendNodeSchema(extension) {
+    const context = {
+      name: extension.name,
+      options: extension.options,
+      storage: extension.storage,
+    }
+
+    return {
+      allowGapCursor: callOrReturn(getExtensionField(extension, 'allowGapCursor', context)) ?? null,
+    }
+  },
+})

package/src/gap-cursor/index.ts

@@ -0,0 +1 @@
+export * from './gap-cursor.js'

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from './character-count/index.js'
+export * from './drop-cursor/index.js'
+export * from './focus/index.js'
+export * from './gap-cursor/index.js'
+export * from './placeholder/index.js'
+export * from './selection/index.js'
+export * from './trailing-node/index.js'
+export * from './undo-redo/index.js'

package/src/placeholder/index.ts

@@ -0,0 +1 @@
+export * from './placeholder.js'

package/src/placeholder/placeholder.ts

@@ -0,0 +1,129 @@
+import type { Editor } from '@tiptap/core'
+import { Extension, isNodeEmpty } from '@tiptap/core'
+import type { Node as ProsemirrorNode } from '@tiptap/pm/model'
+import { Plugin, PluginKey } from '@tiptap/pm/state'
+import { Decoration, DecorationSet } from '@tiptap/pm/view'
+
+export interface PlaceholderOptions {
+  /**
+   * **The class name for the empty editor**
+   * @default 'is-editor-empty'
+   */
+  emptyEditorClass: string
+
+  /**
+   * **The class name for empty nodes**
+   * @default 'is-empty'
+   */
+  emptyNodeClass: string
+
+  /**
+   * **The placeholder content**
+   *
+   * You can use a function to return a dynamic placeholder or a string.
+   * @default 'Write something …'
+   */
+  placeholder:
+    | ((PlaceholderProps: { editor: Editor; node: ProsemirrorNode; pos: number; hasAnchor: boolean }) => string)
+    | string
+
+  /**
+   * **Checks if the placeholder should be only shown when the editor is editable.**
+   *
+   * If true, the placeholder will only be shown when the editor is editable.
+   * If false, the placeholder will always be shown.
+   * @default true
+   */
+  showOnlyWhenEditable: boolean
+
+  /**
+   * **Checks if the placeholder should be only shown when the current node is empty.**
+   *
+   * If true, the placeholder will only be shown when the current node is empty.
+   * If false, the placeholder will be shown when any node is empty.
+   * @default true
+   */
+  showOnlyCurrent: boolean
+
+  /**
+   * **Controls if the placeholder should be shown for all descendents.**
+   *
+   * If true, the placeholder will be shown for all descendents.
+   * If false, the placeholder will only be shown for the current node.
+   * @default false
+   */
+  includeChildren: boolean
+}
+
+/**
+ * This extension allows you to add a placeholder to your editor.
+ * A placeholder is a text that appears when the editor or a node is empty.
+ * @see https://www.tiptap.dev/api/extensions/placeholder
+ */
+export const Placeholder = Extension.create<PlaceholderOptions>({
+  name: 'placeholder',
+
+  addOptions() {
+    return {
+      emptyEditorClass: 'is-editor-empty',
+      emptyNodeClass: 'is-empty',
+      placeholder: 'Write something …',
+      showOnlyWhenEditable: true,
+      showOnlyCurrent: true,
+      includeChildren: false,
+    }
+  },
+
+  addProseMirrorPlugins() {
+    return [
+      new Plugin({
+        key: new PluginKey('placeholder'),
+        props: {
+          decorations: ({ doc, selection }) => {
+            const active = this.editor.isEditable || !this.options.showOnlyWhenEditable
+            const { anchor } = selection
+            const decorations: Decoration[] = []
+
+            if (!active) {
+              return null
+            }
+
+            const isEmptyDoc = this.editor.isEmpty
+
+            doc.descendants((node, pos) => {
+              const hasAnchor = anchor >= pos && anchor <= pos + node.nodeSize
+              const isEmpty = !node.isLeaf && isNodeEmpty(node)
+
+              if ((hasAnchor || !this.options.showOnlyCurrent) && isEmpty) {
+                const classes = [this.options.emptyNodeClass]
+
+                if (isEmptyDoc) {
+                  classes.push(this.options.emptyEditorClass)
+                }
+
+                const decoration = Decoration.node(pos, pos + node.nodeSize, {
+                  class: classes.join(' '),
+                  'data-placeholder':
+                    typeof this.options.placeholder === 'function'
+                      ? this.options.placeholder({
+                          editor: this.editor,
+                          node,
+                          pos,
+                          hasAnchor,
+                        })
+                      : this.options.placeholder,
+                })
+
+                decorations.push(decoration)
+              }
+
+              return this.options.includeChildren
+            })
+
+            return DecorationSet.create(doc, decorations)
+          },
+        },
+      }),
+    ]
+  },
+})

package/src/selection/index.ts

@@ -0,0 +1 @@
+export * from './selection.js'