@tiptap/extensions 3.0.0-next.3 → 3.0.0-next.5

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

@@ -0,0 +1,195 @@
+import { Extension } from '@tiptap/core'
+import { 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/history/history.ts

@@ -0,0 +1,86 @@
+import { Extension } from '@tiptap/core'
+import { history, redo, undo } from '@tiptap/pm/history'
+
+export interface HistoryOptions {
+  /**
+   * The amount of history events that are collected before the oldest events are discarded.
+   * @default 100
+   * @example 50
+   */
+  depth: number
+
+  /**
+   * The delay (in milliseconds) between changes after which a new group should be started.
+   * @default 500
+   * @example 1000
+   */
+  newGroupDelay: number
+}
+
+declare module '@tiptap/core' {
+  interface Commands<ReturnType> {
+    history: {
+      /**
+       * Undo recent changes
+       * @example editor.commands.undo()
+       */
+      undo: () => ReturnType
+      /**
+       * Reapply reverted changes
+       * @example editor.commands.redo()
+       */
+      redo: () => ReturnType
+    }
+  }
+}
+
+/**
+ * This extension allows you to undo and redo recent changes.
+ * @see https://www.tiptap.dev/api/extensions/history
+ *
+ * **Important**: If the `@tiptap/extension-collaboration` package is used, make sure to remove
+ * the `history` extension, as it is not compatible with the `collaboration` extension.
+ *
+ * `@tiptap/extension-collaboration` uses its own history implementation.
+ */
+export const History = Extension.create<HistoryOptions>({
+  name: 'history',
+
+  addOptions() {
+    return {
+      depth: 100,
+      newGroupDelay: 500,
+    }
+  },
+
+  addCommands() {
+    return {
+      undo:
+        () =>
+        ({ state, dispatch }) => {
+          return undo(state, dispatch)
+        },
+      redo:
+        () =>
+        ({ state, dispatch }) => {
+          return redo(state, dispatch)
+        },
+    }
+  },
+
+  addProseMirrorPlugins() {
+    return [history(this.options)]
+  },
+
+  addKeyboardShortcuts() {
+    return {
+      'Mod-z': () => this.editor.commands.undo(),
+      'Shift-Mod-z': () => this.editor.commands.redo(),
+      'Mod-y': () => this.editor.commands.redo(),
+
+      // Russian keyboard layouts
+      'Mod-я': () => this.editor.commands.undo(),
+      'Shift-Mod-я': () => this.editor.commands.redo(),
+    }
+  },
+})

package/src/history/index.ts

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

package/src/index.ts

@@ -1,5 +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 './history/index.js'
+export * from './placeholder/index.js'
 export * from './selection/index.js'
 export * from './trailing-node/index.js'

package/src/placeholder/index.ts

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

package/src/placeholder/placeholder.ts

@@ -0,0 +1,128 @@
+import { Editor, Extension, isNodeEmpty } from '@tiptap/core'
+import { 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)
+          },
+        },
+      }),
+    ]
+  },
+})