@tiptap/extensions 3.23.5 → 3.24.0

package/src/placeholder/constants.ts

@@ -0,0 +1,17 @@
+import { PluginKey } from '@tiptap/pm/state'
+
+import type { ViewportState } from './types.js'
+
+/** 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

package/src/placeholder/index.ts

@@ -1 +1,4 @@
+export { DEFAULT_DATA_ATTRIBUTE, PLUGIN_KEY } from './constants.js'
 export * from './placeholder.js'
+export * from './types.js'
+export { preparePlaceholderAttribute } from './utils/preparePlaceholderAttribute.js'

package/src/placeholder/placeholder.ts

@@ -1,93 +1,8 @@
-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'
+import { Extension } from '@tiptap/core'
 
-/**
- * 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 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 data-attribute used for the placeholder label**
-   * Will be prepended with `data-` and converted to kebab-case and cleaned of special characters.
-   * @default 'placeholder'
-   */
-  dataAttribute: 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
-}
+import { DEFAULT_DATA_ATTRIBUTE } from './constants.js'
+import { createPlaceholderPlugin } from './plugins/PlaceholderPlugin.js'
+import type { PlaceholderOptions } from './types.js'
 
 /**
  * This extension allows you to add a placeholder to your editor.
@@ -110,63 +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({
-        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 (!node.type.isTextblock) {
-                return this.options.includeChildren
-              }
-
-              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(' '),
-                  [dataAttribute]:
-                    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)
-          },
-        },
-      }),
-    ]
+    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

@@ -0,0 +1,75 @@
+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**
+   * @default 'is-editor-empty'
+   */
+  emptyEditorClass: string
+
+  /**
+   * **The class name for empty nodes**
+   * @default 'is-empty'
+   */
+  emptyNodeClass: string
+
+  /**
+   * **The data-attribute used for the placeholder label**
+   * Will be prepended with `data-` and converted to kebab-case and cleaned of special characters.
+   * @default 'placeholder'
+   */
+  dataAttribute: 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 descendants.**
+   *
+   * If true, the placeholder will be shown for all descendants.
+   * If false, the placeholder will only be shown for the current node.
+   * @default false
+   */
+  includeChildren: boolean
+}

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/createPlaceholderDecoration.ts

@@ -0,0 +1,61 @@
+import type { Editor } from '@tiptap/core'
+import type { Node } from '@tiptap/pm/model'
+import { Decoration } from '@tiptap/pm/view'
+
+import type { PlaceholderOptions } from '../types.js'
+
+/**
+ * Creates a ProseMirror node decoration that applies a placeholder
+ * CSS class and data attribute to an empty node.
+ * @param options.editor - The editor instance
+ * @param options.pos - The position of the node in the document
+ * @param options.node - The ProseMirror node
+ * @param options.isEmptyDoc - Whether the entire document is empty
+ * @param options.hasAnchor - Whether the selection anchor is within the node
+ * @param options.dataAttribute - The data attribute name (e.g. `data-placeholder`)
+ * @param options.classes - CSS classes for empty nodes and the empty editor
+ * @param options.placeholder - The placeholder text or a function that returns it
+ * @returns A ProseMirror node decoration with placeholder classes and data attribute
+ */
+export function createPlaceholderDecoration(options: {
+  editor: Editor
+  pos: number
+  node: Node
+  isEmptyDoc: boolean
+  hasAnchor: boolean
+  dataAttribute: string
+  classes: {
+    emptyEditor: PlaceholderOptions['emptyEditorClass']
+    emptyNode: PlaceholderOptions['emptyNodeClass']
+  }
+  placeholder: PlaceholderOptions['placeholder']
+}) {
+  const {
+    editor,
+    placeholder,
+    dataAttribute,
+    pos,
+    node,
+    isEmptyDoc,
+    hasAnchor,
+    classes: { emptyNode, emptyEditor },
+  } = options
+  const classes = [emptyNode]
+
+  if (isEmptyDoc) {
+    classes.push(emptyEditor)
+  }
+
+  return Decoration.node(pos, pos + node.nodeSize, {
+    class: classes.join(' '),
+    [dataAttribute]:
+      typeof placeholder === 'function'
+        ? placeholder({
+            editor,
+            node,
+            pos,
+            hasAnchor,
+          })
+        : placeholder,
+  })
+}

package/src/placeholder/utils/findScrollParent.ts

@@ -0,0 +1,38 @@
+/**
+ * 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

@@ -0,0 +1,49 @@
+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 }
+  }
+
+  return (container as HTMLElement).getBoundingClientRect()
+}
+
+export function getViewportBoundaryPositions({
+  doc,
+  view,
+  scrollContainer,
+}: {
+  doc: Node
+  view: EditorView
+  scrollContainer?: HTMLElement | Window
+}) {
+  const editorRect = view.dom.getBoundingClientRect()
+  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 not visible — fall back to full document range
+    return { top: 0, bottom: doc.content.size }
+  }
+
+  // Pick the x-coordinate based on text direction. In LTR the content
+  // starts at the left edge; in RTL it starts at the right edge.
+  // Clamp to ensure the coordinate stays inside the editor bounds.
+  const isRTL = getComputedStyle(view.dom).direction === 'rtl'
+  const x = isRTL ? Math.max(editorRect.right - 2, editorRect.left + 2) : editorRect.left + 2
+
+  const topPos = view.posAtCoords({ left: x, top: visibleTop + 2 })
+  const bottomPos = view.posAtCoords({ left: x, top: visibleBottom - 2 })
+
+  return {
+    top: topPos ? topPos.pos : 0,
+    bottom: bottomPos ? bottomPos.pos : doc.content.size,
+  }
+}

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

@@ -0,0 +1,28 @@
+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 }
+}