From c88cd34ed9dfc10e2f38e856b68a78cf5e7eea6d Mon Sep 17 00:00:00 2001
From: Artem Nistuley <artem@harbourshare.com>
Date: Mon, 26 May 2025 22:51:02 +0300
Subject: [PATCH] floating page breaks

---
 package-lock.json                             |  29 ++++-
 packages/super-editor/package.json            |   6 +-
 .../assets/styles/extensions/pagination.css   |  20 ++-
 .../src/components/pagination-helpers.js      |   4 +-
 packages/super-editor/src/core/Editor.js      |   1 +
 .../dev/components/DeveloperPlayground.vue    |   9 ++
 .../src/extensions/pagination/pagination.js   | 114 ++++++++++++++++--
 packages/super-editor/vite.config.js          |   2 +-
 packages/superdoc/src/SuperDoc.vue            |   1 +
 packages/superdoc/src/core/SuperDoc.js        |   1 +
 .../src/dev/components/SuperdocDev.vue        |   5 +
 11 files changed, 178 insertions(+), 14 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index a66aa47525..34a0e1dd97 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -675,6 +675,31 @@
         "node": ">=12"
       }
     },
+    "node_modules/@floating-ui/core": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/@floating-ui/core/-/core-1.7.0.tgz",
+      "integrity": "sha512-FRdBLykrPPA6P76GGGqlex/e7fbe0F1ykgxHYNXQsH/iTEtjMj/f9bpY5oQqbjt5VgZvgz/uKXbGuROijh3VLA==",
+      "dev": true,
+      "dependencies": {
+        "@floating-ui/utils": "^0.2.9"
+      }
+    },
+    "node_modules/@floating-ui/dom": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/@floating-ui/dom/-/dom-1.7.0.tgz",
+      "integrity": "sha512-lGTor4VlXcesUMh1cupTUTDoCxMb0V6bm3CnxHzQcw8Eaf1jQbgQX4i02fYgT0vJ82tb5MZ4CZk1LRGkktJCzg==",
+      "dev": true,
+      "dependencies": {
+        "@floating-ui/core": "^1.7.0",
+        "@floating-ui/utils": "^0.2.9"
+      }
+    },
+    "node_modules/@floating-ui/utils": {
+      "version": "0.2.9",
+      "resolved": "https://registry.npmjs.org/@floating-ui/utils/-/utils-0.2.9.tgz",
+      "integrity": "sha512-MDWhGtE+eHw5JW7lq4qhc5yRLS11ERl1c7Z6Xd0a58DozHES6EnNNwUWbMiG4J9Cgj053Bhk8zvlhFYKVhULwg==",
+      "dev": true
+    },
     "node_modules/@harbour-enterprises/common": {
       "resolved": "shared/common",
       "link": true
@@ -14938,6 +14963,7 @@
         "xml-js": "^1.6.11"
       },
       "devDependencies": {
+        "@floating-ui/dom": "^1.7.0",
         "@playwright/test": "^1.51.0",
         "@vitejs/plugin-vue": "^5.0.4",
         "@vue/test-utils": "^2.4.6",
@@ -14952,6 +14978,7 @@
         "which": "^5.0.0"
       },
       "peerDependencies": {
+        "@floating-ui/dom": "^1.7.0",
         "naive-ui": "^2.38.2",
         "tippy.js": "^6.3.7",
         "vite-plugin-node-polyfills": "^0.22.0",
@@ -15265,7 +15292,7 @@
     },
     "packages/superdoc": {
       "name": "@harbour-enterprises/superdoc",
-      "version": "0.11.32",
+      "version": "0.11.37",
       "license": "AGPL-3.0",
       "dependencies": {
         "buffer-crc32": "^1.0.0",
diff --git a/packages/super-editor/package.json b/packages/super-editor/package.json
index e0ed687d72..5d2d635b25 100644
--- a/packages/super-editor/package.json
+++ b/packages/super-editor/package.json
@@ -73,7 +73,8 @@
     "tippy.js": "^6.3.7",
     "vite-plugin-node-polyfills": "^0.22.0",
     "y-prosemirror": "^1.2.12",
-    "yjs": "13.6.19"
+    "yjs": "13.6.19",
+    "@floating-ui/dom": "^1.7.0"
   },
   "devDependencies": {
     "@playwright/test": "^1.51.0",
@@ -87,6 +88,7 @@
     "vite": "^5.4.12",
     "vitest": "^1.6.1",
     "vue-draggable-next": "^2.2.1",
-    "which": "^5.0.0"
+    "which": "^5.0.0",
+    "@floating-ui/dom": "^1.7.0"
   }
 }
diff --git a/packages/super-editor/src/assets/styles/extensions/pagination.css b/packages/super-editor/src/assets/styles/extensions/pagination.css
index e0e59b33c5..ba463816be 100644
--- a/packages/super-editor/src/assets/styles/extensions/pagination.css
+++ b/packages/super-editor/src/assets/styles/extensions/pagination.css
@@ -1,3 +1,7 @@
+:root {
+  --sd-editor-separator-height: 18px;
+}
+
 .pagination-section-header {
   cursor: default;
 }
@@ -23,8 +27,8 @@
 .pagination-separator {
   position: relative;
   display: block;
-  height: 18px;
-  min-height: 18px;
+  height: var(--sd-editor-separator-height);
+  min-height: var(--sd-editor-separator-height);
   min-width: 100%;
   width: 100%;
   border-top: 1px solid #DBDBDB;
@@ -32,6 +36,18 @@
   cursor: default;
 }
 
+.pagination-separator--table {
+  border: 0;
+}
+
+.pagination-separator-floating {
+  position: fixed;
+  height: var(--sd-editor-separator-height);
+  border-top: 1px solid #DBDBDB;
+  border-bottom: 1px solid #DBDBDB;
+  pointer-events: none;
+}
+
 .pagination-inner {
   position: absolute;
   top: 0;
diff --git a/packages/super-editor/src/components/pagination-helpers.js b/packages/super-editor/src/components/pagination-helpers.js
index 9514badc5c..4dba7f511a 100644
--- a/packages/super-editor/src/components/pagination-helpers.js
+++ b/packages/super-editor/src/components/pagination-helpers.js
@@ -23,7 +23,9 @@ export function adjustPaginationBreaks(editorElem, editor) {
     if (!firstLeft) firstLeft = left;
     if (left !== firstLeft) {
       const diff = left - firstLeft;
+      // Note: elements with "position: fixed" do not work correctly with transform style.
+      // node.style.left = `${diff}px`;
       node.style.transform = `translateX(${diff}px)`;
     }
   });
-};
\ No newline at end of file
+};
diff --git a/packages/super-editor/src/core/Editor.js b/packages/super-editor/src/core/Editor.js
index c72e40543e..3d9677dc3c 100644
--- a/packages/super-editor/src/core/Editor.js
+++ b/packages/super-editor/src/core/Editor.js
@@ -191,6 +191,7 @@ export class Editor extends EventEmitter {
     lastSelection: null,
     suppressDefaultDocxStyles: false,
     jsonOverride: false,
+    paginationFloatingClass: null,
     onBeforeCreate: () => null,
     onCreate: () => null,
     onUpdate: () => null,
diff --git a/packages/super-editor/src/dev/components/DeveloperPlayground.vue b/packages/super-editor/src/dev/components/DeveloperPlayground.vue
index 6891e254df..5e7b9fcee6 100644
--- a/packages/super-editor/src/dev/components/DeveloperPlayground.vue
+++ b/packages/super-editor/src/dev/components/DeveloperPlayground.vue
@@ -178,6 +178,13 @@ onMounted(async () => {
 </style>
 
 <style scoped>
+.sd-toolbar {
+  width: 100%;
+  background: white;
+  position: relative;
+  z-index: 1;
+}
+
 .page-spacer {
   height: 11in;
   width: 60px;
@@ -199,6 +206,8 @@ onMounted(async () => {
 }
 
 .dev-app__layout {
+  display: flex;
+  flex-direction: column;
   width: 100%;
   height: 100vh;
 }
diff --git a/packages/super-editor/src/extensions/pagination/pagination.js b/packages/super-editor/src/extensions/pagination/pagination.js
index 3f0ad6ebfc..dc92155693 100644
--- a/packages/super-editor/src/extensions/pagination/pagination.js
+++ b/packages/super-editor/src/extensions/pagination/pagination.js
@@ -8,8 +8,13 @@ import { ImagePlaceholderPluginKey } from '@extensions/image/imageHelpers/imageP
 import { LinkedStylesPluginKey } from '@extensions/linked-styles/linked-styles.js';
 import { findParentNodeClosestToPos } from '@core/helpers/findParentNodeClosestToPos.js';
 import { generateDocxRandomId } from '../../core/helpers/index.js';
+import { computePosition, autoUpdate, hide } from '@floating-ui/dom';
+
+const SEPARATOR_CLASS = 'pagination-separator';
+const SEPARATOR_FLOATING_CLASS = 'pagination-separator-floating';
 
 const isDebugging = false;
+const cleanupFunctions = new Set();
 
 export const Pagination = Extension.create({
   name: 'pagination',
@@ -42,6 +47,7 @@ export const Pagination = Extension.create({
    */
   addPmPlugins() {
     const editor = this.editor;
+
     let isUpdating = false;
 
     // Used to prevent unnecessary transactions
@@ -129,7 +135,7 @@ export const Pagination = Extension.create({
         let previousDecorations = DecorationSet.empty;
 
         return {
-          update: (view) => {
+          update: (view, prevState) => {
             if (!shouldUpdate || isUpdating) return;
 
             isUpdating = true;
@@ -141,6 +147,7 @@ export const Pagination = Extension.create({
              */
             if (isDebugging) console.debug('--- Calling performUpdate ---')
             performUpdate(editor, view, previousDecorations);
+
             isUpdating = false;
             shouldUpdate = false;
           },
@@ -155,6 +162,10 @@ export const Pagination = Extension.create({
 
     return [paginationPlugin];
   },
+
+  onDestroy() {
+    cleanupFloatingSeparators();
+  },
 });
 
 /**
@@ -218,8 +229,9 @@ const getHeaderFooterId = (currentPageNumber, sectionType, editor, node = null)
  * @returns {void}
  */
 const performUpdate = (editor, view, previousDecorations) => {
-  const sectionData = editor.storage.pagination.sectionData;
+  const sectionData = editor.storage.pagination.sectionData;  
   const newDecorations = calculatePageBreaks(view, editor, sectionData);
+  const editorElement = editor.options.element;
 
   // Skip updating if decorations haven't changed
   if (!previousDecorations.eq(newDecorations)) {
@@ -229,7 +241,18 @@ const performUpdate = (editor, view, previousDecorations) => {
     );
 
     view.dispatch(updateTransaction);
-  }
+
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        cleanupFloatingSeparators();
+        const separators = [...editorElement.querySelectorAll(`.${SEPARATOR_CLASS}--table`)];
+        separators.forEach((separator) => {
+          const { cleanup } = createFloatingSeparator(separator, editor);
+          cleanupFunctions.add(cleanup);
+        });
+      });
+    });
+  };
 
   // Emit that pagination has been updated
   editor.emit('paginationUpdate');
@@ -370,8 +393,11 @@ function generateInternalPageBreaks(doc, view, editor, sectionData) {
 
     if (isHardBreakNode || shouldAddPageBreak) {
       const $currentPos = view.state.doc.resolve(currentPos);
+      const table = findParentNodeClosestToPos($currentPos, (node) => node.type.name === 'table');
       const tableRow = findParentNodeClosestToPos($currentPos, (node) => node.type.name === 'tableRow');
 
+      let isInTable = (table || tableRow) ? true : false;
+
       if (tableRow) {
         // If the node is in a table cell, then split the entire row.
         currentNode = tableRow.node;
@@ -408,7 +434,7 @@ function generateInternalPageBreaks(doc, view, editor, sectionData) {
       const pageSpacer = Decoration.widget(breakPos, spacingNode, { key: 'stable-key' });
       decorations.push(pageSpacer);
 
-      const pageBreak = createPageBreak({ editor, header, footer });
+      const pageBreak = createPageBreak({ editor, header, footer, isInTable });
       decorations.push(Decoration.widget(breakPos, pageBreak, { key: 'stable-key' }));
 
       // Check if we have a hard page break node
@@ -637,7 +663,7 @@ const onHeaderFooterDblClick = (editor, currentFocusedSectionEditor) => {
  * @param {HTMLElement} param0.footer The footer element
  * @returns {HTMLElement} The page break element
  */
-function createPageBreak({ editor, header, footer, footerBottom = null, isFirstHeader, isLastFooter }) {
+function createPageBreak({ editor, header, footer, footerBottom = null, isFirstHeader, isLastFooter, isInTable = false }) {
   const { pageSize, pageMargins } = editor.converter.pageStyles;
 
   let sectionHeight = 0;
@@ -661,9 +687,11 @@ function createPageBreak({ editor, header, footer, footerBottom = null, isFirstH
     const separatorHeight = 20;
     sectionHeight += separatorHeight;
     const separator = document.createElement('div');
-    separator.className = 'pagination-separator';
+    separator.classList.add(SEPARATOR_CLASS);
+    if (isInTable) {
+      separator.classList.add(`${SEPARATOR_CLASS}--table`);
+    }
     if (isDebugging) separator.style.backgroundColor = 'green';
-
     innerDiv.appendChild(separator);
   }
 
@@ -731,3 +759,75 @@ const onImageLoad = (editor) => {
     editor.view.dispatch(newTr);
   });
 };
+
+function createFloatingSeparator(separator, editor) {
+  const floatingSeparator = document.createElement('div');
+  floatingSeparator.classList.add(SEPARATOR_FLOATING_CLASS);
+  floatingSeparator.dataset.floatingSeparator = '';
+
+  const { paginationFloatingClass } = editor.options;
+  if (paginationFloatingClass) {
+    floatingSeparator.classList.add(paginationFloatingClass);
+  }
+
+  document.body.append(floatingSeparator);
+
+  const updatePosition = () => {
+    computePosition(separator, floatingSeparator, {
+      strategy: 'fixed',
+      placement: 'top-start',
+      middleware: [
+        hide({
+          padding: {
+            top: 21,
+            bottom: 21,
+          },
+        }),
+        {
+          name: 'copy',
+          fn: ({ elements }) => {
+            const rect = elements.reference.getBoundingClientRect();
+            return {
+              x: rect.left,
+              y: rect.top,
+              data: {
+                width: rect.width,
+                height: rect.height,
+              },
+            };
+          },
+        },
+      ],
+    }).then(({ x, y, middlewareData }) => { 
+      Object.assign(floatingSeparator.style, {
+        top: `${y}px`,
+        left: `${x}px`,
+        width: `${middlewareData.copy.width}px`,
+        height: `${middlewareData.copy.height}px`,
+        visibility: middlewareData.hide?.referenceHidden ? 'hidden' : 'visible',
+      });
+    });
+  };
+
+  const cleanup = autoUpdate(
+    separator,
+    floatingSeparator,
+    updatePosition,
+    // { animationFrame: true },
+  );
+
+  const extendedCleanup = () => {
+    floatingSeparator?.remove();
+    cleanup();
+  };
+
+  return { 
+    cleanup: extendedCleanup, 
+    updatePosition,
+  };
+}
+
+function cleanupFloatingSeparators() {
+  cleanupFunctions.forEach((cleanup) => cleanup());
+  cleanupFunctions.clear();
+}
diff --git a/packages/super-editor/vite.config.js b/packages/super-editor/vite.config.js
index 9e9e62fd23..787688f6d6 100644
--- a/packages/super-editor/vite.config.js
+++ b/packages/super-editor/vite.config.js
@@ -26,7 +26,7 @@ export default defineConfig(({ mode }) => {
       __APP_VERSION__: JSON.stringify(superdocVersion),
     },
     optimizeDeps: {
-      exclude: ['yjs', 'tippy.js']
+      exclude: ['yjs', 'tippy.js', '@floating-ui/dom']
     },
     build: {
       target: 'es2020',
diff --git a/packages/superdoc/src/SuperDoc.vue b/packages/superdoc/src/SuperDoc.vue
index 28caf53e06..93167a4972 100644
--- a/packages/superdoc/src/SuperDoc.vue
+++ b/packages/superdoc/src/SuperDoc.vue
@@ -257,6 +257,7 @@ const onEditorException = ({ error, editor }) => {
 const editorOptions = (doc) => {
   const options = {
     pagination: proxy.$superdoc.config.pagination,
+    paginationFloatingClass: proxy.$superdoc.config.paginationFloatingClass,
     documentId: doc.id,
     user: proxy.$superdoc.user,
     users: proxy.$superdoc.users,
diff --git a/packages/superdoc/src/core/SuperDoc.js b/packages/superdoc/src/core/SuperDoc.js
index 616c382cb6..b4476bb082 100644
--- a/packages/superdoc/src/core/SuperDoc.js
+++ b/packages/superdoc/src/core/SuperDoc.js
@@ -152,6 +152,7 @@ export class SuperDoc extends EventEmitter {
     title: 'SuperDoc',
     conversations: [],
     pagination: false, // Optional: Whether to show pagination in SuperEditors
+    paginationFloatingClass: null,
     isInternal: false,
 
     // toolbar config
diff --git a/packages/superdoc/src/dev/components/SuperdocDev.vue b/packages/superdoc/src/dev/components/SuperdocDev.vue
index 80c7b89ccc..0b6595b809 100644
--- a/packages/superdoc/src/dev/components/SuperdocDev.vue
+++ b/packages/superdoc/src/dev/components/SuperdocDev.vue
@@ -78,6 +78,7 @@ const init = async () => {
     //   },
     // ],
     // cspNonce: 'testnonce123',
+    paginationFloatingClass: 'sd-floating-page-break',
     modules: {
       comments: {
         // comments: sampleComments,
@@ -236,6 +237,10 @@ onMounted(async () => {
 <style>
 .sd-toolbar {
   width: 100%;
+  background: white;
+  position: relative;
+  z-index: 1;
+
 }
 .comments-panel {
   width: 320px;