@tiptap/extensions 3.23.6 → 3.24.0

package/src/placeholder/placeholder.ts

@@ -1,42 +1,8 @@
-import { Extension, isNodeEmpty } from '@tiptap/core'
-import { Plugin, PluginKey } from '@tiptap/pm/state'
-import type { Decoration } from '@tiptap/pm/view'
-import { DecorationSet } from '@tiptap/pm/view'
+import { Extension } from '@tiptap/core'
 
+import { DEFAULT_DATA_ATTRIBUTE } from './constants.js'
+import { createPlaceholderPlugin } from './plugins/PlaceholderPlugin.js'
 import type { PlaceholderOptions } from './types.js'
-import { createPlaceholderDecoration } from './utils/createPlaceholderDecoration.js'
-import { findScrollParent } from './utils/findScrollParent.js'
-import { getViewportBoundaryPositions } from './utils/getViewportBoundaryPositions.js'
-import { throttle } from './utils/throttle.js'
-
-/**
- * The default data attribute label
- */
-const DEFAULT_DATA_ATTRIBUTE = 'placeholder'
-
-/**
- * Prepares the placeholder attribute by ensuring it is properly formatted.
- * @param attr - The placeholder attribute string.
- * @returns The prepared placeholder attribute string.
- */
-export function preparePlaceholderAttribute(attr: string): string {
-  return (
-    attr
-      // replace whitespace with dashes
-      .replace(/\s+/g, '-')
-      // replace non-alphanumeric  characters
-      // or special chars like $, %, &, etc.
-      // but not dashes
-      .replace(/[^a-zA-Z0-9-]/g, '')
-      // and replace any numeric character at the start
-      .replace(/^[0-9-]+/, '')
-      // and finally replace any stray, leading dashes
-      .replace(/^-+/, '')
-      .toLowerCase()
-  )
-}
-
-export const PLUGIN_KEY = new PluginKey('tiptap__placeholder')
 
 /**
  * This extension allows you to add a placeholder to your editor.
@@ -59,168 +25,6 @@ export const Placeholder = Extension.create<PlaceholderOptions>({
   },
 
   addProseMirrorPlugins() {
-    const dataAttribute = this.options.dataAttribute
-      ? `data-${preparePlaceholderAttribute(this.options.dataAttribute)}`
-      : `data-${DEFAULT_DATA_ATTRIBUTE}`
-
-    return [
-      new Plugin({
-        state: {
-          init() {
-            return {
-              // null means "no viewport info yet" — decoration callback falls
-              // back to full document scan until the scroll handler fires.
-              topPos: null as number | null,
-              bottomPos: null as number | null,
-            }
-          },
-          apply(tr, prev) {
-            const meta = tr.getMeta(PLUGIN_KEY) as { positions?: { top: number; bottom: number } } | undefined
-
-            if (meta?.positions) {
-              return {
-                topPos: meta.positions.top,
-                bottomPos: meta.positions.bottom,
-              }
-            }
-
-            if (!tr.docChanged) {
-              return prev
-            }
-
-            // Preserve last known viewport positions across transactions.
-            // Without this, every keystroke resets back to a full document
-            // scan, defeating the viewport optimisation.
-            // Only map when we have actual positions — null means "no viewport
-            // info yet" and should stay null to fall back to full doc scan.
-            return {
-              topPos: prev.topPos !== null ? tr.mapping.map(prev.topPos) : null,
-              bottomPos: prev.bottomPos !== null ? tr.mapping.map(prev.bottomPos) : null,
-            }
-          },
-        },
-        key: PLUGIN_KEY,
-        view(view) {
-          const scrollContainer = findScrollParent(view.dom)
-
-          const computeAndDispatch = () => {
-            const positions = getViewportBoundaryPositions({
-              view,
-              doc: view.state.doc,
-              scrollContainer,
-            })
-
-            const prev = PLUGIN_KEY.getState(view.state)
-            if (prev.topPos === positions.top && prev.bottomPos === positions.bottom) {
-              return
-            }
-
-            const tr = view.state.tr
-              .setMeta(PLUGIN_KEY, { positions })
-              // Flag this transaction so the update() method can detect
-              // it and avoid re-entrant computation.
-              .setMeta('tiptap__viewportUpdate', true)
-            view.dispatch(tr)
-          }
-
-          const { call: throttledUpdate, cancel: cancelThrottle } = throttle(computeAndDispatch, 250)
-          const scrollParent = scrollContainer
-
-          scrollParent.addEventListener('scroll', throttledUpdate, { passive: true })
-
-          // Fire once to populate initial viewport (bypass throttle)
-          computeAndDispatch()
-
-          return {
-            update(_, prevState) {
-              // Skip re-entry: the dispatch inside computeAndDispatch would
-              // trigger this update again, but the doc didn't change so the
-              // size guard catches that. The meta flag is an extra safeguard.
-              if (view.state.doc.content.size !== prevState.doc.content.size) {
-                computeAndDispatch()
-              }
-            },
-            destroy: () => {
-              cancelThrottle()
-              scrollParent.removeEventListener('scroll', throttledUpdate)
-            },
-          }
-        },
-        props: {
-          decorations: ({ doc, selection }) => {
-            const active = this.editor.isEditable || !this.options.showOnlyWhenEditable
-
-            if (!active) {
-              return null
-            }
-
-            const { anchor } = selection
-            const decorations: Decoration[] = []
-            const isEmptyDoc = this.editor.isEmpty
-
-            const useResolvedPath = this.options.showOnlyCurrent && !this.options.includeChildren
-
-            if (useResolvedPath) {
-              const resolved = doc.resolve(anchor)
-
-              if (resolved.depth > 0) {
-                const node = resolved.node(1)
-                const nodeStart = resolved.before(1)
-
-                if (node.type.isTextblock && isNodeEmpty(node)) {
-                  const hasAnchor = anchor >= nodeStart && anchor <= nodeStart + node.nodeSize
-                  const decoration = createPlaceholderDecoration({
-                    node,
-                    dataAttribute,
-                    hasAnchor,
-                    placeholder: this.options.placeholder,
-                    classes: {
-                      emptyEditor: this.options.emptyEditorClass,
-                      emptyNode: this.options.emptyNodeClass,
-                    },
-                    editor: this.editor,
-                    isEmptyDoc,
-                    pos: resolved.before(1),
-                  })
-
-                  decorations.push(decoration)
-                }
-              }
-            } else {
-              const pluginState = PLUGIN_KEY.getState(this.editor.state)
-              const from = pluginState.topPos ?? 0
-              const to = pluginState.bottomPos ?? doc.content.size
-
-              doc.nodesBetween(from, to, (node, pos) => {
-                const hasAnchor = anchor >= pos && anchor <= pos + node.nodeSize
-                const isEmpty = !node.isLeaf && isNodeEmpty(node)
-
-                if (!node.type.isTextblock) {
-                  return this.options.includeChildren
-                }
-
-                if ((hasAnchor || !this.options.showOnlyCurrent) && isEmpty) {
-                  const decoration = createPlaceholderDecoration({
-                    classes: { emptyEditor: this.options.emptyEditorClass, emptyNode: this.options.emptyNodeClass },
-                    editor: this.editor,
-                    isEmptyDoc,
-                    dataAttribute,
-                    hasAnchor,
-                    placeholder: this.options.placeholder,
-                    node,
-                    pos,
-                  })
-                  decorations.push(decoration)
-                }
-
-                return this.options.includeChildren
-              })
-            }
-
-            return DecorationSet.create(doc, decorations)
-          },
-        },
-      }),
-    ]
+    return [createPlaceholderPlugin({ editor: this.editor, options: this.options })]
   },
 })

package/src/placeholder/plugins/PlaceholderPlugin.ts

@@ -0,0 +1,35 @@
+import type { Editor } from '@tiptap/core'
+import { Plugin } from '@tiptap/pm/state'
+
+import { DEFAULT_DATA_ATTRIBUTE, PLUGIN_KEY } from '../constants.js'
+import type { PlaceholderOptions } from '../types.js'
+import { buildPlaceholderDecorations } from '../utils/buildPlaceholderDecorations.js'
+import { preparePlaceholderAttribute } from '../utils/preparePlaceholderAttribute.js'
+import { createViewportPluginView, viewportPluginState } from '../utils/viewportTracking.js'
+
+export type CreatePluginOptions = {
+  editor: Editor
+  options: PlaceholderOptions
+}
+
+/**
+ * Creates the ProseMirror plugin that renders placeholder decorations.
+ * @param options.editor - The editor instance.
+ * @param options.options - The resolved placeholder options.
+ * @returns The configured placeholder plugin.
+ */
+export function createPlaceholderPlugin({ editor, options }: CreatePluginOptions) {
+  const dataAttribute = options.dataAttribute
+    ? `data-${preparePlaceholderAttribute(options.dataAttribute)}`
+    : `data-${DEFAULT_DATA_ATTRIBUTE}`
+
+  return new Plugin({
+    key: PLUGIN_KEY,
+    state: viewportPluginState,
+    view: createViewportPluginView,
+    props: {
+      decorations: ({ doc, selection }) =>
+        buildPlaceholderDecorations({ editor, options, dataAttribute, doc, selection }),
+    },
+  })
+}

package/src/placeholder/types.ts

@@ -1,6 +1,16 @@
 import type { Editor } from '@tiptap/core'
 import type { Node as ProsemirrorNode } from '@tiptap/pm/model'
 
+/**
+ * The viewport positions tracked by the placeholder plugin.
+ * `null` means "no viewport info yet" — the decoration callback falls back to
+ * a full document scan until the scroll handler fires.
+ */
+export interface ViewportState {
+  topPos: number | null
+  bottomPos: number | null
+}
+
 export interface PlaceholderOptions {
   /**
    * **The class name for the empty editor**
@@ -28,7 +38,12 @@ export interface PlaceholderOptions {
    * @default 'Write something …'
    */
   placeholder:
-    | ((PlaceholderProps: { editor: Editor; node: ProsemirrorNode; pos: number; hasAnchor: boolean }) => string)
+    | ((PlaceholderProps: {
+        editor: Editor
+        node: ProsemirrorNode
+        pos: number
+        hasAnchor: boolean
+      }) => string)
     | string
 
   /**

package/src/placeholder/utils/buildPlaceholderDecorations.ts

@@ -0,0 +1,111 @@
+import type { Editor } from '@tiptap/core'
+import { isNodeEmpty } from '@tiptap/core'
+import type { Node } from '@tiptap/pm/model'
+import type { Selection } from '@tiptap/pm/state'
+import type { Decoration } from '@tiptap/pm/view'
+import { DecorationSet } from '@tiptap/pm/view'
+
+import { PLUGIN_KEY } from '../constants.js'
+import type { PlaceholderOptions } from '../types.js'
+import { createPlaceholderDecoration } from './createPlaceholderDecoration.js'
+
+/**
+ * Builds the placeholder decorations for the current document state.
+ * @param options.editor - The editor instance.
+ * @param options.options - The resolved placeholder options.
+ * @param options.dataAttribute - The prepared `data-*` attribute name.
+ * @param options.doc - The current document node.
+ * @param options.selection - The current selection.
+ * @returns A decoration set, or `null` when no placeholders should be shown.
+ */
+export function buildPlaceholderDecorations({
+  editor,
+  options,
+  dataAttribute,
+  doc,
+  selection,
+}: {
+  editor: Editor
+  options: PlaceholderOptions
+  dataAttribute: string
+  doc: Node
+  selection: Selection
+}): DecorationSet | null {
+  const active = editor.isEditable || !options.showOnlyWhenEditable
+
+  if (!active) {
+    return null
+  }
+
+  const { anchor } = selection
+  const decorations: Decoration[] = []
+  const isEmptyDoc = editor.isEmpty
+
+  const classes = {
+    emptyEditor: options.emptyEditorClass,
+    emptyNode: options.emptyNodeClass,
+  }
+
+  const useResolvedPath = options.showOnlyCurrent && !options.includeChildren
+
+  if (useResolvedPath) {
+    const resolved = doc.resolve(anchor)
+
+    // When the selection spans the whole document (e.g. an `AllSelection`
+    // after Cmd+A), the anchor resolves to the document level (depth 0). In
+    // that case the relevant textblock is the node directly after the
+    // position rather than an ancestor. otherwise the placeholder would
+    // disappear after selecting all and deleting.
+    const node = resolved.depth > 0 ? resolved.node(1) : resolved.nodeAfter
+    const nodeStart = resolved.depth > 0 ? resolved.before(1) : anchor
+
+    if (node && node.type.isTextblock && isNodeEmpty(node)) {
+      const hasAnchor = anchor >= nodeStart && anchor <= nodeStart + node.nodeSize
+
+      decorations.push(
+        createPlaceholderDecoration({
+          editor,
+          isEmptyDoc,
+          dataAttribute,
+          hasAnchor,
+          placeholder: options.placeholder,
+          classes,
+          node,
+          pos: nodeStart,
+        }),
+      )
+    }
+  } else {
+    const pluginState = PLUGIN_KEY.getState(editor.state)
+    const from = pluginState?.topPos ?? 0
+    const to = pluginState?.bottomPos ?? doc.content.size
+
+    doc.nodesBetween(from, to, (node, pos) => {
+      const hasAnchor = anchor >= pos && anchor <= pos + node.nodeSize
+      const isEmpty = !node.isLeaf && isNodeEmpty(node)
+
+      if (!node.type.isTextblock) {
+        return options.includeChildren
+      }
+
+      if ((hasAnchor || !options.showOnlyCurrent) && isEmpty) {
+        decorations.push(
+          createPlaceholderDecoration({
+            editor,
+            isEmptyDoc,
+            dataAttribute,
+            hasAnchor,
+            placeholder: options.placeholder,
+            classes,
+            node,
+            pos,
+          }),
+        )
+      }
+
+      return options.includeChildren
+    })
+  }
+
+  return DecorationSet.create(doc, decorations)
+}

package/src/placeholder/utils/getViewportBoundaryPositions.ts

@@ -1,6 +1,8 @@
 import type { Node } from '@tiptap/pm/model'
 import type { EditorView } from '@tiptap/pm/view'
 
+import { VIEWPORT_OVERSCAN_PX } from '../constants.js'
+
 function getContainerRect(container: HTMLElement | Window): { top: number; bottom: number } {
   if (container === window) {
     return { top: 0, bottom: window.innerHeight }
@@ -19,10 +21,12 @@ export function getViewportBoundaryPositions({
   scrollContainer?: HTMLElement | Window
 }) {
   const editorRect = view.dom.getBoundingClientRect()
-  const containerRect = scrollContainer ? getContainerRect(scrollContainer) : { top: 0, bottom: window.innerHeight }
+  const containerRect = scrollContainer
+    ? getContainerRect(scrollContainer)
+    : { top: 0, bottom: window.innerHeight }
 
-  const visibleTop = Math.max(editorRect.top, containerRect.top)
-  const visibleBottom = Math.min(editorRect.bottom, containerRect.bottom)
+  const visibleTop = Math.max(editorRect.top, containerRect.top) - VIEWPORT_OVERSCAN_PX
+  const visibleBottom = Math.min(editorRect.bottom, containerRect.bottom) + VIEWPORT_OVERSCAN_PX
 
   if (visibleTop >= visibleBottom) {
     // Editor is not visible — fall back to full document range

package/src/placeholder/utils/index.ts

@@ -0,0 +1,6 @@
+export * from './buildPlaceholderDecorations.js'
+export * from './createPlaceholderDecoration.js'
+export * from './findScrollParent.js'
+export * from './getViewportBoundaryPositions.js'
+export * from './preparePlaceholderAttribute.js'
+export * from './viewportTracking.js'

package/src/placeholder/utils/preparePlaceholderAttribute.ts

@@ -0,0 +1,21 @@
+/**
+ * Prepares the placeholder attribute by ensuring it is properly formatted.
+ * @param attr - The placeholder attribute string.
+ * @returns The prepared placeholder attribute string.
+ */
+export function preparePlaceholderAttribute(attr: string): string {
+  return (
+    attr
+      // replace whitespace with dashes
+      .replace(/\s+/g, '-')
+      // replace non-alphanumeric  characters
+      // or special chars like $, %, &, etc.
+      // but not dashes
+      .replace(/[^a-zA-Z0-9-]/g, '')
+      // and replace any numeric character at the start
+      .replace(/^[0-9-]+/, '')
+      // and finally replace any stray, leading dashes
+      .replace(/^-+/, '')
+      .toLowerCase()
+  )
+}

package/src/placeholder/utils/throttle.ts

@@ -1,4 +1,7 @@
-export function throttle<T extends (...args: any[]) => void>(fn: T, delay: number): { call: T; cancel: () => void } {
+export function throttle<T extends (...args: any[]) => void>(
+  fn: T,
+  delay: number,
+): { call: T; cancel: () => void } {
   let timer: ReturnType<typeof setTimeout> | null = null
 
   const call = ((...args: any[]) => {

package/src/placeholder/utils/viewportTracking.ts

@@ -0,0 +1,118 @@
+import type { EditorState, PluginView, StateField, Transaction } from '@tiptap/pm/state'
+import type { EditorView } from '@tiptap/pm/view'
+
+import { PLUGIN_KEY } from '../constants.js'
+import type { ViewportState } from '../types.js'
+import { findScrollParent } from './findScrollParent.js'
+import { getViewportBoundaryPositions } from './getViewportBoundaryPositions.js'
+
+/**
+ * The plugin `state` config that tracks the visible viewport boundaries so the
+ * decoration callback only scans the nodes currently on screen.
+ */
+export const viewportPluginState: StateField<ViewportState> = {
+  /**
+   * Initialises the viewport state with no known positions.
+   * @returns The initial viewport state.
+   */
+  init(): ViewportState {
+    return { topPos: null, bottomPos: null }
+  },
+
+  /**
+   * Updates the viewport state from incoming transactions.
+   * @param tr - The transaction being applied.
+   * @param prev - The previous viewport state.
+   * @returns The next viewport state.
+   */
+  apply(tr: Transaction, prev: ViewportState): ViewportState {
+    const meta = tr.getMeta(PLUGIN_KEY) as
+      | { positions?: { top: number; bottom: number } }
+      | undefined
+
+    if (meta?.positions) {
+      return { topPos: meta.positions.top, bottomPos: meta.positions.bottom }
+    }
+
+    if (!tr.docChanged) {
+      return prev
+    }
+
+    // Preserve last known viewport positions across transactions.
+    // Without this, every keystroke resets back to a full document
+    // scan, defeating the viewport optimisation.
+    // Only map when we have actual positions — null means "no viewport
+    // info yet" and should stay null to fall back to full doc scan.
+    return {
+      topPos: prev.topPos !== null ? tr.mapping.map(prev.topPos) : null,
+      bottomPos: prev.bottomPos !== null ? tr.mapping.map(prev.bottomPos) : null,
+    }
+  },
+}
+
+/**
+ * Creates the plugin `view` that recomputes the visible viewport on scroll and
+ * document size changes, dispatching the result into the plugin state.
+ * @param view - The editor view the plugin is attached to.
+ * @returns A plugin view with `update` and `destroy` handlers.
+ */
+export function createViewportPluginView(view: EditorView): PluginView {
+  const scrollContainer = findScrollParent(view.dom)
+
+  const computeAndDispatch = () => {
+    const positions = getViewportBoundaryPositions({
+      view,
+      doc: view.state.doc,
+      scrollContainer,
+    })
+
+    const prev = PLUGIN_KEY.getState(view.state)
+    if (prev?.topPos === positions.top && prev?.bottomPos === positions.bottom) {
+      return
+    }
+
+    const tr = view.state.tr.setMeta(PLUGIN_KEY, { positions })
+    view.dispatch(tr)
+  }
+
+  // rAF-based scheduler with interval guard (150ms → ~6–7 Hz) used by
+  // scroll events and update(). The overscan margin hides the extra
+  // latency. When the guard blocks, the callback reschedules itself so
+  // the trailing position is always captured.
+  let frame: number | null = null
+  let lastCompute = 0
+  const MIN_SCROLL_INTERVAL = 150
+
+  const scheduleFrame = () => {
+    if (frame !== null) return
+    frame = requestAnimationFrame(() => {
+      frame = null
+      const now = performance.now()
+      if (now - lastCompute >= MIN_SCROLL_INTERVAL) {
+        lastCompute = now
+        computeAndDispatch()
+      } else {
+        scheduleFrame()
+      }
+    })
+  }
+
+  scrollContainer.addEventListener('scroll', scheduleFrame, { passive: true })
+
+  // Fire once to populate initial viewport
+  computeAndDispatch()
+
+  return {
+    update(_view: EditorView, prevState: EditorState) {
+      if (view.state.doc.content.size !== prevState.doc.content.size) {
+        scheduleFrame()
+      }
+    },
+    destroy: () => {
+      if (frame !== null) {
+        cancelAnimationFrame(frame)
+      }
+      scrollContainer.removeEventListener('scroll', scheduleFrame)
+    },
+  }
+}

package/src/trailing-node/trailing-node.ts

@@ -4,7 +4,13 @@ import { Plugin, PluginKey } from '@tiptap/pm/state'
 
 export const skipTrailingNodeMeta = 'skipTrailingNode'
 
-function nodeEqualsType({ types, node }: { types: NodeType | NodeType[]; node: Node | null | undefined }) {
+function nodeEqualsType({
+  types,
+  node,
+}: {
+  types: NodeType | NodeType[]
+  node: Node | null | undefined
+}) {
   return (node && Array.isArray(types) && types.includes(node.type)) || node?.type === types
 }
 
@@ -46,7 +52,9 @@ export const TrailingNode = Extension.create<TrailingNodeOptions>({
   addProseMirrorPlugins() {
     const plugin = new PluginKey(this.name)
     const defaultNode =
-      this.options.node || this.editor.schema.topNodeType.contentMatch.defaultType?.name || 'paragraph'
+      this.options.node ||
+      this.editor.schema.topNodeType.contentMatch.defaultType?.name ||
+      'paragraph'
 
     const disabledNodes = Object.entries(this.editor.schema.nodes)
       .map(([, value]) => value)