@tiptap/extensions 3.23.5 → 3.24.0

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { Extension, ParentConfig, Editor } from '@tiptap/core';
 import { Node } from '@tiptap/pm/model';
+import { PluginKey } from '@tiptap/pm/state';
 
 interface CharacterCountOptions {
     /**
@@ -142,11 +143,14 @@ declare module '@tiptap/core' {
 declare const Gapcursor: Extension<any, any>;
 
 /**
- * Prepares the placeholder attribute by ensuring it is properly formatted.
- * @param attr - The placeholder attribute string.
- * @returns The prepared placeholder attribute string.
+ * 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.
  */
-declare function preparePlaceholderAttribute(attr: string): string;
+interface ViewportState {
+    topPos: number | null;
+    bottomPos: number | null;
+}
 interface PlaceholderOptions {
     /**
      * **The class name for the empty editor**
@@ -193,14 +197,20 @@ interface PlaceholderOptions {
      */
     showOnlyCurrent: boolean;
     /**
-     * **Controls if the placeholder should be shown for all descendents.**
+     * **Controls if the placeholder should be shown for all descendants.**
      *
-     * If true, the placeholder will be shown for all descendents.
+     * 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;
 }
+
+/** The default data attribute label */
+declare const DEFAULT_DATA_ATTRIBUTE = "placeholder";
+/** The plugin key used to store and read the placeholder viewport state */
+declare const PLUGIN_KEY: PluginKey<ViewportState>;
+
 /**
  * This extension allows you to add a placeholder to your editor.
  * A placeholder is a text that appears when the editor or a node is empty.
@@ -208,6 +218,13 @@ interface PlaceholderOptions {
  */
 declare const Placeholder: Extension<PlaceholderOptions, any>;
 
+/**
+ * Prepares the placeholder attribute by ensuring it is properly formatted.
+ * @param attr - The placeholder attribute string.
+ * @returns The prepared placeholder attribute string.
+ */
+declare function preparePlaceholderAttribute(attr: string): string;
+
 type SelectionOptions = {
     /**
      * The class name that should be added to the selected text.
@@ -289,4 +306,4 @@ declare module '@tiptap/core' {
  */
 declare const UndoRedo: Extension<UndoRedoOptions, any>;
 
-export { CharacterCount, type CharacterCountOptions, type CharacterCountStorage, Dropcursor, type DropcursorOptions, Focus, type FocusOptions, Gapcursor, Placeholder, type PlaceholderOptions, Selection, type SelectionOptions, TrailingNode, type TrailingNodeOptions, UndoRedo, type UndoRedoOptions, preparePlaceholderAttribute, skipTrailingNodeMeta };
+export { CharacterCount, type CharacterCountOptions, type CharacterCountStorage, DEFAULT_DATA_ATTRIBUTE, Dropcursor, type DropcursorOptions, Focus, type FocusOptions, Gapcursor, PLUGIN_KEY, Placeholder, type PlaceholderOptions, Selection, type SelectionOptions, TrailingNode, type TrailingNodeOptions, UndoRedo, type UndoRedoOptions, type ViewportState, preparePlaceholderAttribute, skipTrailingNodeMeta };

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { Extension, ParentConfig, Editor } from '@tiptap/core';
 import { Node } from '@tiptap/pm/model';
+import { PluginKey } from '@tiptap/pm/state';
 
 interface CharacterCountOptions {
     /**
@@ -142,11 +143,14 @@ declare module '@tiptap/core' {
 declare const Gapcursor: Extension<any, any>;
 
 /**
- * Prepares the placeholder attribute by ensuring it is properly formatted.
- * @param attr - The placeholder attribute string.
- * @returns The prepared placeholder attribute string.
+ * 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.
  */
-declare function preparePlaceholderAttribute(attr: string): string;
+interface ViewportState {
+    topPos: number | null;
+    bottomPos: number | null;
+}
 interface PlaceholderOptions {
     /**
      * **The class name for the empty editor**
@@ -193,14 +197,20 @@ interface PlaceholderOptions {
      */
     showOnlyCurrent: boolean;
     /**
-     * **Controls if the placeholder should be shown for all descendents.**
+     * **Controls if the placeholder should be shown for all descendants.**
      *
-     * If true, the placeholder will be shown for all descendents.
+     * 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;
 }
+
+/** The default data attribute label */
+declare const DEFAULT_DATA_ATTRIBUTE = "placeholder";
+/** The plugin key used to store and read the placeholder viewport state */
+declare const PLUGIN_KEY: PluginKey<ViewportState>;
+
 /**
  * This extension allows you to add a placeholder to your editor.
  * A placeholder is a text that appears when the editor or a node is empty.
@@ -208,6 +218,13 @@ interface PlaceholderOptions {
  */
 declare const Placeholder: Extension<PlaceholderOptions, any>;
 
+/**
+ * Prepares the placeholder attribute by ensuring it is properly formatted.
+ * @param attr - The placeholder attribute string.
+ * @returns The prepared placeholder attribute string.
+ */
+declare function preparePlaceholderAttribute(attr: string): string;
+
 type SelectionOptions = {
     /**
      * The class name that should be added to the selected text.
@@ -289,4 +306,4 @@ declare module '@tiptap/core' {
  */
 declare const UndoRedo: Extension<UndoRedoOptions, any>;
 
-export { CharacterCount, type CharacterCountOptions, type CharacterCountStorage, Dropcursor, type DropcursorOptions, Focus, type FocusOptions, Gapcursor, Placeholder, type PlaceholderOptions, Selection, type SelectionOptions, TrailingNode, type TrailingNodeOptions, UndoRedo, type UndoRedoOptions, preparePlaceholderAttribute, skipTrailingNodeMeta };
+export { CharacterCount, type CharacterCountOptions, type CharacterCountStorage, DEFAULT_DATA_ATTRIBUTE, Dropcursor, type DropcursorOptions, Focus, type FocusOptions, Gapcursor, PLUGIN_KEY, Placeholder, type PlaceholderOptions, Selection, type SelectionOptions, TrailingNode, type TrailingNodeOptions, UndoRedo, type UndoRedoOptions, type ViewportState, preparePlaceholderAttribute, skipTrailingNodeMeta };

package/dist/index.js

@@ -202,14 +202,271 @@ var Gapcursor = Extension4.create({
   }
 });
 
-// src/placeholder/placeholder.ts
-import { Extension as Extension5, isNodeEmpty } from "@tiptap/core";
-import { Plugin as Plugin3, PluginKey as PluginKey3 } from "@tiptap/pm/state";
-import { Decoration as Decoration2, DecorationSet as DecorationSet2 } from "@tiptap/pm/view";
+// src/placeholder/constants.ts
+import { PluginKey as PluginKey3 } from "@tiptap/pm/state";
 var DEFAULT_DATA_ATTRIBUTE = "placeholder";
+var PLUGIN_KEY = new PluginKey3("tiptap__placeholder");
+var VIEWPORT_OVERSCAN_PX = 200;
+
+// src/placeholder/placeholder.ts
+import { Extension as Extension5 } from "@tiptap/core";
+
+// src/placeholder/plugins/PlaceholderPlugin.ts
+import { Plugin as Plugin3 } from "@tiptap/pm/state";
+
+// src/placeholder/utils/buildPlaceholderDecorations.ts
+import { isNodeEmpty } from "@tiptap/core";
+import { DecorationSet as DecorationSet2 } from "@tiptap/pm/view";
+
+// src/placeholder/utils/createPlaceholderDecoration.ts
+import { Decoration as Decoration2 } 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 Decoration2.node(pos, pos + node.nodeSize, {
+    class: classes.join(" "),
+    [dataAttribute]: typeof placeholder === "function" ? placeholder({
+      editor,
+      node,
+      pos,
+      hasAnchor
+    }) : placeholder
+  });
+}
+
+// src/placeholder/utils/buildPlaceholderDecorations.ts
+function buildPlaceholderDecorations({
+  editor,
+  options,
+  dataAttribute,
+  doc,
+  selection
+}) {
+  var _a, _b;
+  const active = editor.isEditable || !options.showOnlyWhenEditable;
+  if (!active) {
+    return null;
+  }
+  const { anchor } = selection;
+  const decorations = [];
+  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);
+    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 = (_a = pluginState == null ? void 0 : pluginState.topPos) != null ? _a : 0;
+    const to = (_b = pluginState == null ? void 0 : 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 options.includeChildren;
+      }
+      if ((hasAnchor || !options.showOnlyCurrent) && isEmpty) {
+        decorations.push(
+          createPlaceholderDecoration({
+            editor,
+            isEmptyDoc,
+            dataAttribute,
+            hasAnchor,
+            placeholder: options.placeholder,
+            classes,
+            node,
+            pos
+          })
+        );
+      }
+      return options.includeChildren;
+    });
+  }
+  return DecorationSet2.create(doc, decorations);
+}
+
+// src/placeholder/utils/preparePlaceholderAttribute.ts
 function preparePlaceholderAttribute(attr) {
   return attr.replace(/\s+/g, "-").replace(/[^a-zA-Z0-9-]/g, "").replace(/^[0-9-]+/, "").replace(/^-+/, "").toLowerCase();
 }
+
+// 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) - VIEWPORT_OVERSCAN_PX;
+  const visibleBottom = Math.min(editorRect.bottom, containerRect.bottom) + VIEWPORT_OVERSCAN_PX;
+  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/viewportTracking.ts
+var viewportPluginState = {
+  /**
+   * Initialises the viewport state with no known positions.
+   * @returns The initial viewport state.
+   */
+  init() {
+    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, 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
+    };
+  }
+};
+function createViewportPluginView(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 == null ? void 0 : prev.topPos) === positions.top && (prev == null ? void 0 : prev.bottomPos) === positions.bottom) {
+      return;
+    }
+    const tr = view.state.tr.setMeta(PLUGIN_KEY, { positions });
+    view.dispatch(tr);
+  };
+  let frame = 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 });
+  computeAndDispatch();
+  return {
+    update(_view, prevState) {
+      if (view.state.doc.content.size !== prevState.doc.content.size) {
+        scheduleFrame();
+      }
+    },
+    destroy: () => {
+      if (frame !== null) {
+        cancelAnimationFrame(frame);
+      }
+      scrollContainer.removeEventListener("scroll", scheduleFrame);
+    }
+  };
+}
+
+// src/placeholder/plugins/PlaceholderPlugin.ts
+function createPlaceholderPlugin({ editor, options }) {
+  const dataAttribute = options.dataAttribute ? `data-${preparePlaceholderAttribute(options.dataAttribute)}` : `data-${DEFAULT_DATA_ATTRIBUTE}`;
+  return new Plugin3({
+    key: PLUGIN_KEY,
+    state: viewportPluginState,
+    view: createViewportPluginView,
+    props: {
+      decorations: ({ doc, selection }) => buildPlaceholderDecorations({ editor, options, dataAttribute, doc, selection })
+    }
+  });
+}
+
+// src/placeholder/placeholder.ts
 var Placeholder = Extension5.create({
   name: "placeholder",
   addOptions() {
@@ -224,48 +481,7 @@ var Placeholder = Extension5.create({
     };
   },
   addProseMirrorPlugins() {
-    const dataAttribute = this.options.dataAttribute ? `data-${preparePlaceholderAttribute(this.options.dataAttribute)}` : `data-${DEFAULT_DATA_ATTRIBUTE}`;
-    return [
-      new Plugin3({
-        key: new PluginKey3("placeholder"),
-        props: {
-          decorations: ({ doc, selection }) => {
-            const active = this.editor.isEditable || !this.options.showOnlyWhenEditable;
-            const { anchor } = selection;
-            const decorations = [];
-            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 = Decoration2.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 DecorationSet2.create(doc, decorations);
-          }
-        }
-      })
-    ];
+    return [createPlaceholderPlugin({ editor: this.editor, options: this.options })];
   }
 });
 
@@ -306,7 +522,10 @@ var Selection = Extension6.create({
 import { Extension as Extension7 } from "@tiptap/core";
 import { Plugin as Plugin5, PluginKey as PluginKey5 } from "@tiptap/pm/state";
 var skipTrailingNodeMeta = "skipTrailingNode";
-function nodeEqualsType({ types, node }) {
+function nodeEqualsType({
+  types,
+  node
+}) {
   return node && Array.isArray(types) && types.includes(node.type) || (node == null ? void 0 : node.type) === types;
 }
 var TrailingNode = Extension7.create({
@@ -396,9 +615,11 @@ var UndoRedo = Extension8.create({
 });
 export {
   CharacterCount,
+  DEFAULT_DATA_ATTRIBUTE,
   Dropcursor,
   Focus,
   Gapcursor,
+  PLUGIN_KEY,
   Placeholder,
   Selection,
   TrailingNode,