@tiptap/extensions 3.23.5 → 3.23.6

package/dist/placeholder/index.js

@@ -1,11 +1,118 @@
 // src/placeholder/placeholder.ts
 import { Extension, isNodeEmpty } from "@tiptap/core";
 import { Plugin, PluginKey } from "@tiptap/pm/state";
-import { Decoration, DecorationSet } from "@tiptap/pm/view";
+import { DecorationSet } from "@tiptap/pm/view";
+
+// src/placeholder/utils/createPlaceholderDecoration.ts
+import { Decoration } from "@tiptap/pm/view";
+function createPlaceholderDecoration(options) {
+  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
+  });
+}
+
+// src/placeholder/utils/findScrollParent.ts
+function isScrollable(el) {
+  const style = getComputedStyle(el);
+  const overflow = `${style.overflow} ${style.overflowY} ${style.overflowX}`;
+  return /auto|scroll|overlay/.test(overflow);
+}
+function findScrollParent(element) {
+  let el = element;
+  while (el) {
+    if (isScrollable(el)) {
+      return el;
+    }
+    const parent = el.parentElement;
+    if (!parent) {
+      const root = el.getRootNode();
+      if (root instanceof ShadowRoot) {
+        el = root.host;
+        continue;
+      }
+      return window;
+    }
+    el = parent;
+  }
+  return window;
+}
+
+// src/placeholder/utils/getViewportBoundaryPositions.ts
+function getContainerRect(container) {
+  if (container === window) {
+    return { top: 0, bottom: window.innerHeight };
+  }
+  return container.getBoundingClientRect();
+}
+function getViewportBoundaryPositions({
+  doc,
+  view,
+  scrollContainer
+}) {
+  const editorRect = view.dom.getBoundingClientRect();
+  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);
+  if (visibleTop >= visibleBottom) {
+    return { top: 0, bottom: doc.content.size };
+  }
+  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
+  };
+}
+
+// src/placeholder/utils/throttle.ts
+function throttle(fn, delay) {
+  let timer = null;
+  const call = ((...args) => {
+    if (timer) {
+      return;
+    }
+    fn(...args);
+    timer = setTimeout(() => {
+      timer = null;
+    }, delay);
+  });
+  const cancel = () => {
+    if (timer) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  };
+  return { call, cancel };
+}
+
+// src/placeholder/placeholder.ts
 var DEFAULT_DATA_ATTRIBUTE = "placeholder";
 function preparePlaceholderAttribute(attr) {
   return attr.replace(/\s+/g, "-").replace(/[^a-zA-Z0-9-]/g, "").replace(/^[0-9-]+/, "").replace(/^-+/, "").toLowerCase();
 }
+var PLUGIN_KEY = new PluginKey("tiptap__placeholder");
 var Placeholder = Extension.create({
   name: "placeholder",
   addOptions() {
@@ -23,40 +130,124 @@ var Placeholder = Extension.create({
     const dataAttribute = this.options.dataAttribute ? `data-${preparePlaceholderAttribute(this.options.dataAttribute)}` : `data-${DEFAULT_DATA_ATTRIBUTE}`;
     return [
       new Plugin({
-        key: new PluginKey("placeholder"),
+        state: {
+          init() {
+            return {
+              // null means "no viewport info yet" — decoration callback falls
+              // back to full document scan until the scroll handler fires.
+              topPos: null,
+              bottomPos: null
+            };
+          },
+          apply(tr, prev) {
+            const meta = tr.getMeta(PLUGIN_KEY);
+            if (meta == null ? void 0 : meta.positions) {
+              return {
+                topPos: meta.positions.top,
+                bottomPos: meta.positions.bottom
+              };
+            }
+            if (!tr.docChanged) {
+              return prev;
+            }
+            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 }).setMeta("tiptap__viewportUpdate", true);
+            view.dispatch(tr);
+          };
+          const { call: throttledUpdate, cancel: cancelThrottle } = throttle(computeAndDispatch, 250);
+          const scrollParent = scrollContainer;
+          scrollParent.addEventListener("scroll", throttledUpdate, { passive: true });
+          computeAndDispatch();
+          return {
+            update(_, prevState) {
+              if (view.state.doc.content.size !== prevState.doc.content.size) {
+                computeAndDispatch();
+              }
+            },
+            destroy: () => {
+              cancelThrottle();
+              scrollParent.removeEventListener("scroll", throttledUpdate);
+            }
+          };
+        },
         props: {
           decorations: ({ doc, selection }) => {
+            var _a, _b;
             const active = this.editor.isEditable || !this.options.showOnlyWhenEditable;
-            const { anchor } = selection;
-            const decorations = [];
             if (!active) {
               return null;
             }
+            const { anchor } = selection;
+            const decorations = [];
             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;
+            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);
+                }
               }
-              if ((hasAnchor || !this.options.showOnlyCurrent) && isEmpty) {
-                const classes = [this.options.emptyNodeClass];
-                if (isEmptyDoc) {
-                  classes.push(this.options.emptyEditorClass);
+            } else {
+              const pluginState = PLUGIN_KEY.getState(this.editor.state);
+              const from = (_a = pluginState.topPos) != null ? _a : 0;
+              const to = (_b = pluginState.bottomPos) != null ? _b : 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;
                 }
-                const decoration = Decoration.node(pos, pos + node.nodeSize, {
-                  class: classes.join(" "),
-                  [dataAttribute]: typeof this.options.placeholder === "function" ? this.options.placeholder({
+                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,
-                    hasAnchor
-                  }) : this.options.placeholder
-                });
-                decorations.push(decoration);
-              }
-              return this.options.includeChildren;
-            });
+                    pos
+                  });
+                  decorations.push(decoration);
+                }
+                return this.options.includeChildren;
+              });
+            }
             return DecorationSet.create(doc, decorations);
           }
         }
@@ -65,6 +256,7 @@ var Placeholder = Extension.create({
   }
 });
 export {
+  PLUGIN_KEY,
   Placeholder,
   preparePlaceholderAttribute
 };

package/dist/placeholder/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/placeholder/placeholder.ts"],"sourcesContent":["import type { Editor } from '@tiptap/core'\nimport { Extension, isNodeEmpty } from '@tiptap/core'\nimport type { Node as ProsemirrorNode } from '@tiptap/pm/model'\nimport { Plugin, PluginKey } from '@tiptap/pm/state'\nimport { Decoration, DecorationSet } from '@tiptap/pm/view'\n\n/**\n * The default data attribute label\n */\nconst DEFAULT_DATA_ATTRIBUTE = 'placeholder'\n\n/**\n * Prepares the placeholder attribute by ensuring it is properly formatted.\n * @param attr - The placeholder attribute string.\n * @returns The prepared placeholder attribute string.\n */\nexport function preparePlaceholderAttribute(attr: string): string {\n  return (\n    attr\n      // replace whitespace with dashes\n      .replace(/\\s+/g, '-')\n      // replace non-alphanumeric  characters\n      // or special chars like $, %, &, etc.\n      // but not dashes\n      .replace(/[^a-zA-Z0-9-]/g, '')\n      // and replace any numeric character at the start\n      .replace(/^[0-9-]+/, '')\n      // and finally replace any stray, leading dashes\n      .replace(/^-+/, '')\n      .toLowerCase()\n  )\n}\n\nexport interface PlaceholderOptions {\n  /**\n   * **The class name for the empty editor**\n   * @default 'is-editor-empty'\n   */\n  emptyEditorClass: string\n\n  /**\n   * **The class name for empty nodes**\n   * @default 'is-empty'\n   */\n  emptyNodeClass: string\n\n  /**\n   * **The data-attribute used for the placeholder label**\n   * Will be prepended with `data-` and converted to kebab-case and cleaned of special characters.\n   * @default 'placeholder'\n   */\n  dataAttribute: string\n\n  /**\n   * **The placeholder content**\n   *\n   * You can use a function to return a dynamic placeholder or a string.\n   * @default 'Write something …'\n   */\n  placeholder:\n    | ((PlaceholderProps: { editor: Editor; node: ProsemirrorNode; pos: number; hasAnchor: boolean }) => string)\n    | string\n\n  /**\n   * **Checks if the placeholder should be only shown when the editor is editable.**\n   *\n   * If true, the placeholder will only be shown when the editor is editable.\n   * If false, the placeholder will always be shown.\n   * @default true\n   */\n  showOnlyWhenEditable: boolean\n\n  /**\n   * **Checks if the placeholder should be only shown when the current node is empty.**\n   *\n   * If true, the placeholder will only be shown when the current node is empty.\n   * If false, the placeholder will be shown when any node is empty.\n   * @default true\n   */\n  showOnlyCurrent: boolean\n\n  /**\n   * **Controls if the placeholder should be shown for all descendents.**\n   *\n   * If true, the placeholder will be shown for all descendents.\n   * If false, the placeholder will only be shown for the current node.\n   * @default false\n   */\n  includeChildren: boolean\n}\n\n/**\n * This extension allows you to add a placeholder to your editor.\n * A placeholder is a text that appears when the editor or a node is empty.\n * @see https://www.tiptap.dev/api/extensions/placeholder\n */\nexport const Placeholder = Extension.create<PlaceholderOptions>({\n  name: 'placeholder',\n\n  addOptions() {\n    return {\n      emptyEditorClass: 'is-editor-empty',\n      emptyNodeClass: 'is-empty',\n      dataAttribute: DEFAULT_DATA_ATTRIBUTE,\n      placeholder: 'Write something …',\n      showOnlyWhenEditable: true,\n      showOnlyCurrent: true,\n      includeChildren: false,\n    }\n  },\n\n  addProseMirrorPlugins() {\n    const dataAttribute = this.options.dataAttribute\n      ? `data-${preparePlaceholderAttribute(this.options.dataAttribute)}`\n      : `data-${DEFAULT_DATA_ATTRIBUTE}`\n\n    return [\n      new Plugin({\n        key: new PluginKey('placeholder'),\n        props: {\n          decorations: ({ doc, selection }) => {\n            const active = this.editor.isEditable || !this.options.showOnlyWhenEditable\n            const { anchor } = selection\n            const decorations: Decoration[] = []\n\n            if (!active) {\n              return null\n            }\n\n            const isEmptyDoc = this.editor.isEmpty\n\n            doc.descendants((node, pos) => {\n              const hasAnchor = anchor >= pos && anchor <= pos + node.nodeSize\n              const isEmpty = !node.isLeaf && isNodeEmpty(node)\n\n              if (!node.type.isTextblock) {\n                return this.options.includeChildren\n              }\n\n              if ((hasAnchor || !this.options.showOnlyCurrent) && isEmpty) {\n                const classes = [this.options.emptyNodeClass]\n\n                if (isEmptyDoc) {\n                  classes.push(this.options.emptyEditorClass)\n                }\n\n                const decoration = Decoration.node(pos, pos + node.nodeSize, {\n                  class: classes.join(' '),\n                  [dataAttribute]:\n                    typeof this.options.placeholder === 'function'\n                      ? this.options.placeholder({\n                          editor: this.editor,\n                          node,\n                          pos,\n                          hasAnchor,\n                        })\n                      : this.options.placeholder,\n                })\n\n                decorations.push(decoration)\n              }\n\n              return this.options.includeChildren\n            })\n\n            return DecorationSet.create(doc, decorations)\n          },\n        },\n      }),\n    ]\n  },\n})\n"],"mappings":";AACA,SAAS,WAAW,mBAAmB;AAEvC,SAAS,QAAQ,iBAAiB;AAClC,SAAS,YAAY,qBAAqB;AAK1C,IAAM,yBAAyB;AAOxB,SAAS,4BAA4B,MAAsB;AAChE,SACE,KAEG,QAAQ,QAAQ,GAAG,EAInB,QAAQ,kBAAkB,EAAE,EAE5B,QAAQ,YAAY,EAAE,EAEtB,QAAQ,OAAO,EAAE,EACjB,YAAY;AAEnB;AAiEO,IAAM,cAAc,UAAU,OAA2B;AAAA,EAC9D,MAAM;AAAA,EAEN,aAAa;AACX,WAAO;AAAA,MACL,kBAAkB;AAAA,MAClB,gBAAgB;AAAA,MAChB,eAAe;AAAA,MACf,aAAa;AAAA,MACb,sBAAsB;AAAA,MACtB,iBAAiB;AAAA,MACjB,iBAAiB;AAAA,IACnB;AAAA,EACF;AAAA,EAEA,wBAAwB;AACtB,UAAM,gBAAgB,KAAK,QAAQ,gBAC/B,QAAQ,4BAA4B,KAAK,QAAQ,aAAa,CAAC,KAC/D,QAAQ,sBAAsB;AAElC,WAAO;AAAA,MACL,IAAI,OAAO;AAAA,QACT,KAAK,IAAI,UAAU,aAAa;AAAA,QAChC,OAAO;AAAA,UACL,aAAa,CAAC,EAAE,KAAK,UAAU,MAAM;AACnC,kBAAM,SAAS,KAAK,OAAO,cAAc,CAAC,KAAK,QAAQ;AACvD,kBAAM,EAAE,OAAO,IAAI;AACnB,kBAAM,cAA4B,CAAC;AAEnC,gBAAI,CAAC,QAAQ;AACX,qBAAO;AAAA,YACT;AAEA,kBAAM,aAAa,KAAK,OAAO;AAE/B,gBAAI,YAAY,CAAC,MAAM,QAAQ;AAC7B,oBAAM,YAAY,UAAU,OAAO,UAAU,MAAM,KAAK;AACxD,oBAAM,UAAU,CAAC,KAAK,UAAU,YAAY,IAAI;AAEhD,kBAAI,CAAC,KAAK,KAAK,aAAa;AAC1B,uBAAO,KAAK,QAAQ;AAAA,cACtB;AAEA,mBAAK,aAAa,CAAC,KAAK,QAAQ,oBAAoB,SAAS;AAC3D,sBAAM,UAAU,CAAC,KAAK,QAAQ,cAAc;AAE5C,oBAAI,YAAY;AACd,0BAAQ,KAAK,KAAK,QAAQ,gBAAgB;AAAA,gBAC5C;AAEA,sBAAM,aAAa,WAAW,KAAK,KAAK,MAAM,KAAK,UAAU;AAAA,kBAC3D,OAAO,QAAQ,KAAK,GAAG;AAAA,kBACvB,CAAC,aAAa,GACZ,OAAO,KAAK,QAAQ,gBAAgB,aAChC,KAAK,QAAQ,YAAY;AAAA,oBACvB,QAAQ,KAAK;AAAA,oBACb;AAAA,oBACA;AAAA,oBACA;AAAA,kBACF,CAAC,IACD,KAAK,QAAQ;AAAA,gBACrB,CAAC;AAED,4BAAY,KAAK,UAAU;AAAA,cAC7B;AAEA,qBAAO,KAAK,QAAQ;AAAA,YACtB,CAAC;AAED,mBAAO,cAAc,OAAO,KAAK,WAAW;AAAA,UAC9C;AAAA,QACF;AAAA,MACF,CAAC;AAAA,IACH;AAAA,EACF;AACF,CAAC;","names":[]}
+{"version":3,"sources":["../../src/placeholder/placeholder.ts","../../src/placeholder/utils/createPlaceholderDecoration.ts","../../src/placeholder/utils/findScrollParent.ts","../../src/placeholder/utils/getViewportBoundaryPositions.ts","../../src/placeholder/utils/throttle.ts"],"sourcesContent":["import { Extension, isNodeEmpty } from '@tiptap/core'\nimport { Plugin, PluginKey } from '@tiptap/pm/state'\nimport type { Decoration } from '@tiptap/pm/view'\nimport { DecorationSet } from '@tiptap/pm/view'\n\nimport type { PlaceholderOptions } from './types.js'\nimport { createPlaceholderDecoration } from './utils/createPlaceholderDecoration.js'\nimport { findScrollParent } from './utils/findScrollParent.js'\nimport { getViewportBoundaryPositions } from './utils/getViewportBoundaryPositions.js'\nimport { throttle } from './utils/throttle.js'\n\n/**\n * The default data attribute label\n */\nconst DEFAULT_DATA_ATTRIBUTE = 'placeholder'\n\n/**\n * Prepares the placeholder attribute by ensuring it is properly formatted.\n * @param attr - The placeholder attribute string.\n * @returns The prepared placeholder attribute string.\n */\nexport function preparePlaceholderAttribute(attr: string): string {\n  return (\n    attr\n      // replace whitespace with dashes\n      .replace(/\\s+/g, '-')\n      // replace non-alphanumeric  characters\n      // or special chars like $, %, &, etc.\n      // but not dashes\n      .replace(/[^a-zA-Z0-9-]/g, '')\n      // and replace any numeric character at the start\n      .replace(/^[0-9-]+/, '')\n      // and finally replace any stray, leading dashes\n      .replace(/^-+/, '')\n      .toLowerCase()\n  )\n}\n\nexport const PLUGIN_KEY = new PluginKey('tiptap__placeholder')\n\n/**\n * This extension allows you to add a placeholder to your editor.\n * A placeholder is a text that appears when the editor or a node is empty.\n * @see https://www.tiptap.dev/api/extensions/placeholder\n */\nexport const Placeholder = Extension.create<PlaceholderOptions>({\n  name: 'placeholder',\n\n  addOptions() {\n    return {\n      emptyEditorClass: 'is-editor-empty',\n      emptyNodeClass: 'is-empty',\n      dataAttribute: DEFAULT_DATA_ATTRIBUTE,\n      placeholder: 'Write something …',\n      showOnlyWhenEditable: true,\n      showOnlyCurrent: true,\n      includeChildren: false,\n    }\n  },\n\n  addProseMirrorPlugins() {\n    const dataAttribute = this.options.dataAttribute\n      ? `data-${preparePlaceholderAttribute(this.options.dataAttribute)}`\n      : `data-${DEFAULT_DATA_ATTRIBUTE}`\n\n    return [\n      new Plugin({\n        state: {\n          init() {\n            return {\n              // null means \"no viewport info yet\" — decoration callback falls\n              // back to full document scan until the scroll handler fires.\n              topPos: null as number | null,\n              bottomPos: null as number | null,\n            }\n          },\n          apply(tr, prev) {\n            const meta = tr.getMeta(PLUGIN_KEY) as { positions?: { top: number; bottom: number } } | undefined\n\n            if (meta?.positions) {\n              return {\n                topPos: meta.positions.top,\n                bottomPos: meta.positions.bottom,\n              }\n            }\n\n            if (!tr.docChanged) {\n              return prev\n            }\n\n            // Preserve last known viewport positions across transactions.\n            // Without this, every keystroke resets back to a full document\n            // scan, defeating the viewport optimisation.\n            // Only map when we have actual positions — null means \"no viewport\n            // info yet\" and should stay null to fall back to full doc scan.\n            return {\n              topPos: prev.topPos !== null ? tr.mapping.map(prev.topPos) : null,\n              bottomPos: prev.bottomPos !== null ? tr.mapping.map(prev.bottomPos) : null,\n            }\n          },\n        },\n        key: PLUGIN_KEY,\n        view(view) {\n          const scrollContainer = findScrollParent(view.dom)\n\n          const computeAndDispatch = () => {\n            const positions = getViewportBoundaryPositions({\n              view,\n              doc: view.state.doc,\n              scrollContainer,\n            })\n\n            const prev = PLUGIN_KEY.getState(view.state)\n            if (prev.topPos === positions.top && prev.bottomPos === positions.bottom) {\n              return\n            }\n\n            const tr = view.state.tr\n              .setMeta(PLUGIN_KEY, { positions })\n              // Flag this transaction so the update() method can detect\n              // it and avoid re-entrant computation.\n              .setMeta('tiptap__viewportUpdate', true)\n            view.dispatch(tr)\n          }\n\n          const { call: throttledUpdate, cancel: cancelThrottle } = throttle(computeAndDispatch, 250)\n          const scrollParent = scrollContainer\n\n          scrollParent.addEventListener('scroll', throttledUpdate, { passive: true })\n\n          // Fire once to populate initial viewport (bypass throttle)\n          computeAndDispatch()\n\n          return {\n            update(_, prevState) {\n              // Skip re-entry: the dispatch inside computeAndDispatch would\n              // trigger this update again, but the doc didn't change so the\n              // size guard catches that. The meta flag is an extra safeguard.\n              if (view.state.doc.content.size !== prevState.doc.content.size) {\n                computeAndDispatch()\n              }\n            },\n            destroy: () => {\n              cancelThrottle()\n              scrollParent.removeEventListener('scroll', throttledUpdate)\n            },\n          }\n        },\n        props: {\n          decorations: ({ doc, selection }) => {\n            const active = this.editor.isEditable || !this.options.showOnlyWhenEditable\n\n            if (!active) {\n              return null\n            }\n\n            const { anchor } = selection\n            const decorations: Decoration[] = []\n            const isEmptyDoc = this.editor.isEmpty\n\n            const useResolvedPath = this.options.showOnlyCurrent && !this.options.includeChildren\n\n            if (useResolvedPath) {\n              const resolved = doc.resolve(anchor)\n\n              if (resolved.depth > 0) {\n                const node = resolved.node(1)\n                const nodeStart = resolved.before(1)\n\n                if (node.type.isTextblock && isNodeEmpty(node)) {\n                  const hasAnchor = anchor >= nodeStart && anchor <= nodeStart + node.nodeSize\n                  const decoration = createPlaceholderDecoration({\n                    node,\n                    dataAttribute,\n                    hasAnchor,\n                    placeholder: this.options.placeholder,\n                    classes: {\n                      emptyEditor: this.options.emptyEditorClass,\n                      emptyNode: this.options.emptyNodeClass,\n                    },\n                    editor: this.editor,\n                    isEmptyDoc,\n                    pos: resolved.before(1),\n                  })\n\n                  decorations.push(decoration)\n                }\n              }\n            } else {\n              const pluginState = PLUGIN_KEY.getState(this.editor.state)\n              const from = pluginState.topPos ?? 0\n              const to = pluginState.bottomPos ?? doc.content.size\n\n              doc.nodesBetween(from, to, (node, pos) => {\n                const hasAnchor = anchor >= pos && anchor <= pos + node.nodeSize\n                const isEmpty = !node.isLeaf && isNodeEmpty(node)\n\n                if (!node.type.isTextblock) {\n                  return this.options.includeChildren\n                }\n\n                if ((hasAnchor || !this.options.showOnlyCurrent) && isEmpty) {\n                  const decoration = createPlaceholderDecoration({\n                    classes: { emptyEditor: this.options.emptyEditorClass, emptyNode: this.options.emptyNodeClass },\n                    editor: this.editor,\n                    isEmptyDoc,\n                    dataAttribute,\n                    hasAnchor,\n                    placeholder: this.options.placeholder,\n                    node,\n                    pos,\n                  })\n                  decorations.push(decoration)\n                }\n\n                return this.options.includeChildren\n              })\n            }\n\n            return DecorationSet.create(doc, decorations)\n          },\n        },\n      }),\n    ]\n  },\n})\n","import type { Editor } from '@tiptap/core'\nimport type { Node } from '@tiptap/pm/model'\nimport { Decoration } from '@tiptap/pm/view'\n\nimport type { PlaceholderOptions } from '../types.js'\n\n/**\n * Creates a ProseMirror node decoration that applies a placeholder\n * CSS class and data attribute to an empty node.\n * @param options.editor - The editor instance\n * @param options.pos - The position of the node in the document\n * @param options.node - The ProseMirror node\n * @param options.isEmptyDoc - Whether the entire document is empty\n * @param options.hasAnchor - Whether the selection anchor is within the node\n * @param options.dataAttribute - The data attribute name (e.g. `data-placeholder`)\n * @param options.classes - CSS classes for empty nodes and the empty editor\n * @param options.placeholder - The placeholder text or a function that returns it\n * @returns A ProseMirror node decoration with placeholder classes and data attribute\n */\nexport function createPlaceholderDecoration(options: {\n  editor: Editor\n  pos: number\n  node: Node\n  isEmptyDoc: boolean\n  hasAnchor: boolean\n  dataAttribute: string\n  classes: {\n    emptyEditor: PlaceholderOptions['emptyEditorClass']\n    emptyNode: PlaceholderOptions['emptyNodeClass']\n  }\n  placeholder: PlaceholderOptions['placeholder']\n}) {\n  const {\n    editor,\n    placeholder,\n    dataAttribute,\n    pos,\n    node,\n    isEmptyDoc,\n    hasAnchor,\n    classes: { emptyNode, emptyEditor },\n  } = options\n  const classes = [emptyNode]\n\n  if (isEmptyDoc) {\n    classes.push(emptyEditor)\n  }\n\n  return Decoration.node(pos, pos + node.nodeSize, {\n    class: classes.join(' '),\n    [dataAttribute]:\n      typeof placeholder === 'function'\n        ? placeholder({\n            editor,\n            node,\n            pos,\n            hasAnchor,\n          })\n        : placeholder,\n  })\n}\n","/**\n * Checks if an element is scrollable by testing its overflow properties.\n * Elements with `overflow: hidden` or `overflow: clip` are intentionally\n * excluded — they clip content but don't emit scroll events.\n */\nfunction isScrollable(el: HTMLElement): boolean {\n  const style = getComputedStyle(el)\n  const overflow = `${style.overflow} ${style.overflowY} ${style.overflowX}`\n\n  return /auto|scroll|overlay/.test(overflow)\n}\n\nexport function findScrollParent(element: HTMLElement): HTMLElement | Window {\n  let el: HTMLElement | null = element\n\n  while (el) {\n    if (isScrollable(el)) {\n      return el\n    }\n\n    // Check if we hit a Shadow DOM boundary. If so, jump to the shadow host\n    // and continue traversing the light DOM.\n    const parent = el.parentElement\n    if (!parent) {\n      const root = el.getRootNode()\n      if (root instanceof ShadowRoot) {\n        el = root.host as HTMLElement\n        continue\n      }\n\n      return window\n    }\n\n    el = parent\n  }\n\n  return window\n}\n","import type { Node } from '@tiptap/pm/model'\nimport type { EditorView } from '@tiptap/pm/view'\n\nfunction getContainerRect(container: HTMLElement | Window): { top: number; bottom: number } {\n  if (container === window) {\n    return { top: 0, bottom: window.innerHeight }\n  }\n\n  return (container as HTMLElement).getBoundingClientRect()\n}\n\nexport function getViewportBoundaryPositions({\n  doc,\n  view,\n  scrollContainer,\n}: {\n  doc: Node\n  view: EditorView\n  scrollContainer?: HTMLElement | Window\n}) {\n  const editorRect = view.dom.getBoundingClientRect()\n  const containerRect = scrollContainer ? getContainerRect(scrollContainer) : { top: 0, bottom: window.innerHeight }\n\n  const visibleTop = Math.max(editorRect.top, containerRect.top)\n  const visibleBottom = Math.min(editorRect.bottom, containerRect.bottom)\n\n  if (visibleTop >= visibleBottom) {\n    // Editor is not visible — fall back to full document range\n    return { top: 0, bottom: doc.content.size }\n  }\n\n  // Pick the x-coordinate based on text direction. In LTR the content\n  // starts at the left edge; in RTL it starts at the right edge.\n  // Clamp to ensure the coordinate stays inside the editor bounds.\n  const isRTL = getComputedStyle(view.dom).direction === 'rtl'\n  const x = isRTL ? Math.max(editorRect.right - 2, editorRect.left + 2) : editorRect.left + 2\n\n  const topPos = view.posAtCoords({ left: x, top: visibleTop + 2 })\n  const bottomPos = view.posAtCoords({ left: x, top: visibleBottom - 2 })\n\n  return {\n    top: topPos ? topPos.pos : 0,\n    bottom: bottomPos ? bottomPos.pos : doc.content.size,\n  }\n}\n","export function throttle<T extends (...args: any[]) => void>(fn: T, delay: number): { call: T; cancel: () => void } {\n  let timer: ReturnType<typeof setTimeout> | null = null\n\n  const call = ((...args: any[]) => {\n    if (timer) {\n      return\n    }\n\n    // Leading-edge: fire immediately, then prevent subsequent calls\n    // until the timer fires and resets.\n    fn(...args)\n    timer = setTimeout(() => {\n      timer = null\n    }, delay)\n  }) as T\n\n  const cancel = () => {\n    if (timer) {\n      clearTimeout(timer)\n      timer = null\n    }\n  }\n\n  return { call, cancel }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiptap/extensions",
   "description": "various extensions for tiptap",
-  "version": "3.23.5",
+  "version": "3.23.6",
   "homepage": "https://tiptap.dev",
   "keywords": [
     "tiptap",
@@ -95,12 +95,12 @@
     "dist"
   ],
   "devDependencies": {
-    "@tiptap/core": "^3.23.5",
-    "@tiptap/pm": "^3.23.5"
+    "@tiptap/pm": "^3.23.6",
+    "@tiptap/core": "^3.23.6"
   },
   "peerDependencies": {
-    "@tiptap/core": "3.23.5",
-    "@tiptap/pm": "3.23.5"
+    "@tiptap/core": "3.23.6",
+    "@tiptap/pm": "3.23.6"
   },
   "repository": {
     "type": "git",

package/src/placeholder/index.ts

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

package/src/placeholder/placeholder.ts

@@ -1,8 +1,13 @@
-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 type { Decoration } from '@tiptap/pm/view'
+import { DecorationSet } from '@tiptap/pm/view'
+
+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
@@ -31,63 +36,7 @@ export function preparePlaceholderAttribute(attr: string): string {
   )
 }
 
-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
-}
+export const PLUGIN_KEY = new PluginKey('tiptap__placeholder')
 
 /**
  * This extension allows you to add a placeholder to your editor.
@@ -116,52 +65,157 @@ export const Placeholder = Extension.create<PlaceholderOptions>({
 
     return [
       new Plugin({
-        key: new PluginKey('placeholder'),
+        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
-            const { anchor } = selection
-            const decorations: Decoration[] = []
 
             if (!active) {
               return null
             }
 
+            const { anchor } = selection
+            const decorations: Decoration[] = []
             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
+            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
 
-              if ((hasAnchor || !this.options.showOnlyCurrent) && isEmpty) {
-                const classes = [this.options.emptyNodeClass]
+              doc.nodesBetween(from, to, (node, pos) => {
+                const hasAnchor = anchor >= pos && anchor <= pos + node.nodeSize
+                const isEmpty = !node.isLeaf && isNodeEmpty(node)
 
-                if (isEmptyDoc) {
-                  classes.push(this.options.emptyEditorClass)
+                if (!node.type.isTextblock) {
+                  return this.options.includeChildren
                 }
 
-                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)
-              }
+                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 this.options.includeChildren
+              })
+            }
 
             return DecorationSet.create(doc, decorations)
           },