@tiptap/extensions 3.27.2 → 3.27.3

package/src/placeholder/constants.ts

@@ -1,17 +1,8 @@
 import { PluginKey } from '@tiptap/pm/state'
-
-import type { ViewportState } from './types.js'
+import type { DecorationSet } from '@tiptap/pm/view'
 
 /** The default data attribute label */
 export const DEFAULT_DATA_ATTRIBUTE = 'placeholder'
 
-/** The plugin key used to store and read the placeholder viewport state */
-export const PLUGIN_KEY = new PluginKey<ViewportState>('tiptap__placeholder')
-
-/**
- * Extra pixels added above and below the visible viewport when computing the
- * range of nodes to decorate. Decorating slightly beyond the fold means a
- * node already has its placeholder before it scrolls into view, which hides
- * the latency introduced by the throttled viewport recompute.
- */
-export const VIEWPORT_OVERSCAN_PX = 200
+/** The plugin key used to store and read the placeholder decoration set */
+export const PLUGIN_KEY = new PluginKey<DecorationSet>('tiptap__placeholder')

package/src/placeholder/plugins/PlaceholderPlugin.ts

@@ -1,11 +1,12 @@
 import type { Editor } from '@tiptap/core'
 import { Plugin } from '@tiptap/pm/state'
+import { DecorationSet } from '@tiptap/pm/view'
 
 import { DEFAULT_DATA_ATTRIBUTE, PLUGIN_KEY } from '../constants.js'
 import type { PlaceholderOptions } from '../types.js'
 import { buildPlaceholderDecorations } from '../utils/buildPlaceholderDecorations.js'
+import { createPlaceholderStateField } from '../utils/placeholderStateField.js'
 import { preparePlaceholderAttribute } from '../utils/preparePlaceholderAttribute.js'
-import { createViewportPluginView, viewportPluginState } from '../utils/viewportTracking.js'
 
 export type CreatePluginOptions = {
   editor: Editor
@@ -23,13 +24,26 @@ export function createPlaceholderPlugin({ editor, options }: CreatePluginOptions
     ? `data-${preparePlaceholderAttribute(options.dataAttribute)}`
     : `data-${DEFAULT_DATA_ATTRIBUTE}`
 
+  const useResolvedPath = options.showOnlyCurrent && !options.includeChildren
+
   return new Plugin({
     key: PLUGIN_KEY,
-    state: viewportPluginState,
-    view: createViewportPluginView,
+    ...(useResolvedPath
+      ? {}
+      : {
+          state: createPlaceholderStateField({ editor, options, dataAttribute }),
+        }),
     props: {
-      decorations: ({ doc, selection }) =>
-        buildPlaceholderDecorations({ editor, options, dataAttribute, doc, selection }),
+      decorations: useResolvedPath
+        ? ({ doc, selection }) =>
+            buildPlaceholderDecorations({ editor, options, dataAttribute, doc, selection })
+        : state => {
+            if (options.showOnlyWhenEditable && !editor.isEditable) {
+              return DecorationSet.empty
+            }
+
+            return PLUGIN_KEY.getState(state) ?? DecorationSet.empty
+          },
     },
   })
 }

package/src/placeholder/types.ts

@@ -1,16 +1,6 @@
 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**

package/src/placeholder/utils/buildPlaceholderDecorations.ts

@@ -5,7 +5,6 @@ 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'
 
@@ -16,6 +15,68 @@ function resolveEmptyNodeClass(
   return typeof emptyNodeClass === 'function' ? emptyNodeClass(props) : emptyNodeClass
 }
 
+/**
+ * Scans a document range for empty textblocks that should receive placeholder
+ * decorations. Used by the slow path and incremental state updates.
+ */
+export function scanRangeForDecorations({
+  editor,
+  options,
+  dataAttribute,
+  doc,
+  selection,
+  from,
+  to,
+}: {
+  editor: Editor
+  options: PlaceholderOptions
+  dataAttribute: string
+  doc: Node
+  selection: Selection
+  from: number
+  to: number
+}): Decoration[] {
+  const { anchor } = selection
+  const decorations: Decoration[] = []
+  const isEmptyDoc = editor.isEmpty
+
+  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: {
+            emptyEditor: options.emptyEditorClass,
+            emptyNode: resolveEmptyNodeClass(options.emptyNodeClass, {
+              editor,
+              node,
+              pos,
+              hasAnchor,
+            }),
+          },
+          node,
+          pos,
+        }),
+      )
+    }
+
+    return options.includeChildren
+  })
+
+  return decorations
+}
+
 /**
  * Builds the placeholder decorations for the current document state.
  * @param options.editor - The editor instance.
@@ -86,43 +147,17 @@ export function buildPlaceholderDecorations({
       )
     }
   } 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: {
-              emptyEditor: options.emptyEditorClass,
-              emptyNode: resolveEmptyNodeClass(options.emptyNodeClass, {
-                editor,
-                node,
-                pos,
-                hasAnchor,
-              }),
-            },
-            node,
-            pos,
-          }),
-        )
-      }
-
-      return options.includeChildren
-    })
+    decorations.push(
+      ...scanRangeForDecorations({
+        editor,
+        options,
+        dataAttribute,
+        doc,
+        selection,
+        from: 0,
+        to: doc.content.size,
+      }),
+    )
   }
 
   return DecorationSet.create(doc, decorations)

package/src/placeholder/utils/index.ts

@@ -1,6 +1,3 @@
 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/placeholderStateField.ts

@@ -0,0 +1,204 @@
+import type { Editor } from '@tiptap/core'
+import { getChangedRanges } from '@tiptap/core'
+import type { Node } from '@tiptap/pm/model'
+import type { EditorState, StateField, Transaction } from '@tiptap/pm/state'
+import type { Selection } from '@tiptap/pm/state'
+import { DecorationSet } from '@tiptap/pm/view'
+
+import type { PlaceholderOptions } from '../types.js'
+import {
+  buildPlaceholderDecorations,
+  scanRangeForDecorations,
+} from './buildPlaceholderDecorations.js'
+import {
+  getTopLevelBlocksInRange,
+  mergeRanges,
+  resolveTopLevelRange,
+  toContentRelativeRange,
+} from './resolveTopLevelRange.js'
+
+/** Options passed to {@link createPlaceholderStateField}. */
+export type CreatePlaceholderStateFieldOptions = {
+  editor: Editor
+  options: PlaceholderOptions
+  dataAttribute: string
+}
+
+/**
+ * Expands a single changed range to the top-level blocks it touches.
+ * Also resolves blocks at range boundaries so split/merge edits update
+ * adjacent empty nodes (e.g. a new paragraph after Enter).
+ */
+function collectBlocksForChange(
+  doc: Node,
+  change: { from: number; to: number },
+): Array<{ from: number; to: number }> {
+  const ranges = getTopLevelBlocksInRange(doc, change.from, change.to)
+
+  ranges.push(toContentRelativeRange(doc, resolveTopLevelRange(doc, change.from)))
+
+  if (change.to > change.from) {
+    ranges.push(
+      toContentRelativeRange(
+        doc,
+        resolveTopLevelRange(doc, Math.min(change.to, doc.content.size + 1) - 1),
+      ),
+    )
+  } else if (change.from < doc.content.size + 1) {
+    ranges.push(
+      toContentRelativeRange(
+        doc,
+        resolveTopLevelRange(doc, Math.min(change.from + 1, doc.content.size)),
+      ),
+    )
+  }
+
+  return ranges
+}
+
+/**
+ * Collects content-relative top-level block ranges that need placeholder
+ * decorations recomputed after a transaction.
+ */
+function collectRescanRanges(
+  tr: Transaction,
+  oldState: EditorState,
+  newState: EditorState,
+): Array<{ from: number; to: number }> {
+  const ranges: Array<{ from: number; to: number }> = []
+
+  if (tr.docChanged) {
+    const changes = getChangedRanges(tr)
+
+    for (const change of changes) {
+      ranges.push(...collectBlocksForChange(newState.doc, change.newRange))
+    }
+  }
+
+  if (tr.selectionSet) {
+    ranges.push(
+      toContentRelativeRange(
+        newState.doc,
+        resolveTopLevelRange(newState.doc, tr.mapping.map(oldState.selection.anchor)),
+      ),
+    )
+    ranges.push(
+      toContentRelativeRange(
+        newState.doc,
+        resolveTopLevelRange(newState.doc, newState.selection.anchor),
+      ),
+    )
+  }
+
+  return mergeRanges(ranges)
+}
+
+/** Clamps a content-relative range to `[0, doc.content.size]`. */
+function clampRange(from: number, to: number, doc: Node): { from: number; to: number } {
+  const clampedFrom = Math.max(0, Math.min(from, doc.content.size))
+  const clampedTo = Math.max(clampedFrom, Math.min(to, doc.content.size))
+
+  return { from: clampedFrom, to: clampedTo }
+}
+
+/**
+ * Removes and rebuilds placeholder decorations within the given ranges.
+ * Only drops decorations fully contained in a range so mapped decorations
+ * on neighbouring blocks (e.g. at a block boundary) are kept intact.
+ */
+function updateDecorationsInRanges({
+  decorations,
+  ranges,
+  editor,
+  options,
+  dataAttribute,
+  doc,
+  selection,
+}: {
+  decorations: DecorationSet
+  ranges: Array<{ from: number; to: number }>
+  editor: Editor
+  options: PlaceholderOptions
+  dataAttribute: string
+  doc: Node
+  selection: Selection
+}): DecorationSet {
+  let next = decorations
+
+  for (const range of ranges) {
+    const { from, to } = clampRange(range.from, range.to, doc)
+    const existing = next
+      .find(from, to)
+      .filter(decoration => decoration.from >= from && decoration.to <= to)
+
+    if (existing.length) {
+      next = next.remove(existing)
+    }
+
+    const newDecos = scanRangeForDecorations({
+      editor,
+      options,
+      dataAttribute,
+      doc,
+      selection,
+      from,
+      to,
+    })
+
+    if (newDecos.length) {
+      next = next.add(doc, newDecos)
+    }
+  }
+
+  return next
+}
+
+/**
+ * Creates the incremental `StateField<DecorationSet>` used by the slow path
+ * (`showOnlyCurrent: false` or `includeChildren: true`).
+ *
+ * Decorations are mapped through each transaction and only recomputed for
+ * top-level blocks touched by document or selection changes.
+ * @param options.editor - The editor instance.
+ * @param options.options - The resolved placeholder options.
+ * @param options.dataAttribute - The prepared `data-*` attribute name.
+ * @returns A ProseMirror state field storing the placeholder decoration set.
+ */
+export function createPlaceholderStateField({
+  editor,
+  options,
+  dataAttribute,
+}: CreatePlaceholderStateFieldOptions): StateField<DecorationSet> {
+  return {
+    init(_config, state: EditorState) {
+      const decorations = buildPlaceholderDecorations({
+        editor,
+        options,
+        dataAttribute,
+        doc: state.doc,
+        selection: state.selection,
+      })
+
+      return decorations ?? DecorationSet.empty
+    },
+
+    apply(tr: Transaction, prev: DecorationSet, oldState: EditorState, newState: EditorState) {
+      if (!tr.docChanged && !tr.selectionSet) {
+        return prev
+      }
+
+      const mapped = prev.map(tr.mapping, tr.doc)
+      const ranges = collectRescanRanges(tr, oldState, newState)
+
+      return updateDecorationsInRanges({
+        decorations: mapped,
+        ranges,
+        editor,
+        options,
+        dataAttribute,
+        doc: newState.doc,
+        selection: newState.selection,
+      })
+    },
+  }
+}

package/src/placeholder/utils/resolveTopLevelRange.ts

@@ -0,0 +1,93 @@
+import type { Node } from '@tiptap/pm/model'
+
+/**
+ * Resolves a document position to the `[from, to)` range of its containing
+ * top-level block node in absolute document positions.
+ */
+export function resolveTopLevelRange(doc: Node, pos: number): { from: number; to: number } {
+  const resolved = doc.resolve(pos)
+
+  if (resolved.depth === 0) {
+    const node = resolved.nodeAfter ?? resolved.nodeBefore
+
+    if (!node) {
+      return { from: pos, to: pos }
+    }
+
+    const nodePos = resolved.nodeAfter ? pos : pos - node.nodeSize
+
+    return { from: nodePos, to: nodePos + node.nodeSize }
+  }
+
+  const topLevelPos = resolved.before(1)
+  const node = resolved.node(1)
+
+  return { from: topLevelPos, to: topLevelPos + node.nodeSize }
+}
+
+/**
+ * Converts an absolute document range to content-relative positions used by
+ * `Node#nodesBetween` and `Node#forEach` offsets.
+ */
+export function toContentRelativeRange(
+  doc: Node,
+  range: { from: number; to: number },
+): { from: number; to: number } {
+  return {
+    from: Math.max(0, range.from - 1),
+    to: Math.min(doc.content.size, range.to - 1),
+  }
+}
+
+/**
+ * Returns the top-level block ranges that intersect a document change range.
+ * Input `from`/`to` are absolute positions (e.g. from `getChangedRanges`).
+ * Returned ranges are content-relative, matching `Node#forEach` offsets.
+ */
+export function getTopLevelBlocksInRange(
+  doc: Node,
+  from: number,
+  to: number,
+): Array<{ from: number; to: number }> {
+  const ranges: Array<{ from: number; to: number }> = []
+
+  doc.forEach((node, offset) => {
+    const nodeStart = offset
+    const nodeEnd = nodeStart + node.nodeSize
+    const absNodeStart = nodeStart + 1
+    const absNodeEnd = nodeEnd + 1
+
+    if (absNodeStart < to && absNodeEnd > from) {
+      ranges.push({ from: nodeStart, to: nodeEnd })
+    }
+  })
+
+  return ranges
+}
+
+/**
+ * Sorts ranges by start position and merges overlapping or adjacent ranges.
+ */
+export function mergeRanges(
+  ranges: Array<{ from: number; to: number }>,
+): Array<{ from: number; to: number }> {
+  if (ranges.length === 0) {
+    return []
+  }
+
+  const sorted = [...ranges].sort((a, b) => a.from - b.from)
+  const merged: Array<{ from: number; to: number }> = [{ ...sorted[0] }]
+
+  for (let i = 1; i < sorted.length; i += 1) {
+    const last = merged[merged.length - 1]
+    const current = sorted[i]
+
+    if (current.from <= last.to) {
+      last.to = Math.max(last.to, current.to)
+    } else {
+      merged.push({ ...current })
+    }
+  }
+
+  return merged
+}

package/src/placeholder/utils/findScrollParent.ts

@@ -1,38 +0,0 @@
-/**
- * Checks if an element is scrollable by testing its overflow properties.
- * Elements with `overflow: hidden` or `overflow: clip` are intentionally
- * excluded — they clip content but don't emit scroll events.
- */
-function isScrollable(el: HTMLElement): boolean {
-  const style = getComputedStyle(el)
-  const overflow = `${style.overflow} ${style.overflowY} ${style.overflowX}`
-
-  return /auto|scroll|overlay/.test(overflow)
-}
-
-export function findScrollParent(element: HTMLElement): HTMLElement | Window {
-  let el: HTMLElement | null = element
-
-  while (el) {
-    if (isScrollable(el)) {
-      return el
-    }
-
-    // Check if we hit a Shadow DOM boundary. If so, jump to the shadow host
-    // and continue traversing the light DOM.
-    const parent = el.parentElement
-    if (!parent) {
-      const root = el.getRootNode()
-      if (root instanceof ShadowRoot) {
-        el = root.host as HTMLElement
-        continue
-      }
-
-      return window
-    }
-
-    el = parent
-  }
-
-  return window
-}

package/src/placeholder/utils/getViewportBoundaryPositions.ts

@@ -1,74 +0,0 @@
-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 }
-  }
-
-  return (container as HTMLElement).getBoundingClientRect()
-}
-
-/**
- * Computes the document positions bounding the currently visible viewport.
- */
-export function getViewportBoundaryPositions({
-  view,
-  scrollContainer,
-}: {
-  view: EditorView
-  scrollContainer?: HTMLElement | Window
-}): { top: number; bottom: number } | null {
-  const editorRect = view.dom.getBoundingClientRect()
-
-  // No usable layout — can't probe a coordinate inside the box.
-  if (editorRect.width <= 0 || editorRect.height <= 0) {
-    return null
-  }
-
-  const containerRect = scrollContainer
-    ? getContainerRect(scrollContainer)
-    : { top: 0, bottom: window.innerHeight }
-
-  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 scrolled fully out of its container so not measurable.
-    return null
-  }
-
-  // Probe the start edge (left in LTR, right in RTL), clamped inside the box
-  // so a too-narrow editor doesn't push the probe out.
-  const minX = editorRect.left + 1
-  const maxX = editorRect.right - 1
-
-  if (minX > maxX) {
-    return null
-  }
-
-  const isRTL = getComputedStyle(view.dom).direction === 'rtl'
-  const targetX = isRTL ? editorRect.right - 2 : editorRect.left + 2
-  const x = Math.min(Math.max(targetX, minX), maxX)
-
-  // Clamp the probe y inside the box so the overscan doesn't push it past the
-  // editor's own content (which would make `posAtCoords` null for no reason).
-  const probeTop = Math.max(visibleTop + 2, editorRect.top + 1)
-  const probeBottom = Math.min(visibleBottom - 2, editorRect.bottom - 1)
-
-  if (probeTop > probeBottom) {
-    return null
-  }
-
-  const topPos = view.posAtCoords({ left: x, top: probeTop })
-  const bottomPos = view.posAtCoords({ left: x, top: probeBottom })
-
-  // Null usually means occlusion (but can be benign). Either way it's
-  // unreliable, so freeze the previous window instead of decorating the whole doc.
-  if (!topPos || !bottomPos) {
-    return null
-  }
-
-  return { top: topPos.pos, bottom: bottomPos.pos }
-}

package/src/placeholder/utils/throttle.ts

@@ -1,28 +0,0 @@
-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[]) => {
-    if (timer) {
-      return
-    }
-
-    // Leading-edge: fire immediately, then prevent subsequent calls
-    // until the timer fires and resets.
-    fn(...args)
-    timer = setTimeout(() => {
-      timer = null
-    }, delay)
-  }) as T
-
-  const cancel = () => {
-    if (timer) {
-      clearTimeout(timer)
-      timer = null
-    }
-  }
-
-  return { call, cancel }
-}