fix(editor): prevent scroll-to-top when clicking toolbar buttons (#2236)

* fix(editor): prevent scroll-to-top when clicking toolbar buttons (SD-1780)

Toolbar buttons had tabindex="0" but no mousedown prevention, so
clicking them caused the browser to transfer focus away from the
hidden ProseMirror editor. The subsequent refocus triggered
ProseMirror's selectionToDOM, and the browser asynchronously scrolled
to make the DOM selection visible inside the hidden editor at
position:fixed top:0. This only manifested when the window was the
scroll container (not a div with overflow:auto).

Two fixes applied:

1. Toolbar mousedown preventDefault for non-input elements. This is
   the standard pattern used by ProseMirror's example editor, Tiptap,
   and most WYSIWYG editors. It keeps the PM editor focused throughout
   toolbar interactions.

2. requestAnimationFrame safety net in wrapHiddenEditorFocus. After
   the synchronous scroll restoration, a RAF callback catches any
   async browser scroll caused by layout reflow post-focus.

* fix(editor): cancel focus-scroll RAF on intentional scroll

Store the RAF handle from wrapHiddenEditorFocus on the instance and
cancel it when scrollToPosition is called. Prevents the safety net
from undoing intentional scrolls like search navigation.

* test(editor): exercise RAF scroll-restore callback in focus wrapping test

The previous test only verified that requestAnimationFrame was
scheduled but never invoked the callback. Now we capture the RAF
callback, simulate async scroll drift (scrollY changing between
focus call and RAF execution), and verify scrollTo is called to
restore the original position.

Author: tupizz

packages/super-editor/src/components/toolbar/Toolbar.vue

@@ -77,10 +77,32 @@ const handleCommand = ({ item, argument, option }) => {
 const restoreSelection = () => {
   proxy.$toolbar.activeEditor?.commands?.restoreSelection();
 };
+
+/**
+ * Prevents the browser's default focus-transfer behavior when clicking toolbar buttons.
+ *
+ * Without this, clicking a toolbar button moves focus from the hidden ProseMirror editor
+ * to the toolbar button element. The subsequent refocus of the PM editor can trigger
+ * browser-native scroll adjustments that jump the page to the top — especially when
+ * the window (not a div) is the scroll container.
+ *
+ * Input elements are excluded so they still receive native focus and cursor placement.
+ */
+const handleToolbarMousedown = (e) => {
+  if (e.target.closest('input, textarea, [contenteditable="true"]')) return;
+  e.preventDefault();
+};
 </script>
 
 <template>
-  <div class="superdoc-toolbar" :key="toolbarKey" role="toolbar" aria-label="Toolbar" data-editor-ui-surface>
+  <div
+    class="superdoc-toolbar"
+    :key="toolbarKey"
+    role="toolbar"
+    aria-label="Toolbar"
+    data-editor-ui-surface
+    @mousedown="handleToolbarMousedown"
+  >
     <ButtonGroup
       tabindex="0"
       v-if="showLeftSide"

packages/super-editor/src/core/presentation-editor/PresentationEditor.ts

@@ -286,6 +286,7 @@ export class PresentationEditor extends EventEmitter {
   #errorBannerMessage: HTMLElement | null = null;
   #renderScheduled = false;
   #pendingDocChange = false;
+  #focusScrollRafId: number | null = null;
   #pendingMapping: Mapping | null = null;
   #isRerendering = false;
   #selectionSync = new SelectionSyncCoordinator();
@@ -775,6 +776,21 @@ export class PresentationEditor extends EventEmitter {
       if (win.scrollX !== beforeX || win.scrollY !== beforeY) {
         win.scrollTo(beforeX, beforeY);
       }
+
+      // Safety net: the browser may asynchronously scroll after ProseMirror's
+      // selectionToDOM() modifies the DOM selection inside the hidden editor.
+      // A single requestAnimationFrame catches this post-layout scroll.
+      // The RAF ID is stored so scrollToPosition() can cancel it — otherwise
+      // intentional scrolls (e.g. search navigation) would be undone.
+      if (this.#focusScrollRafId != null) {
+        win.cancelAnimationFrame(this.#focusScrollRafId);
+      }
+      this.#focusScrollRafId = win.requestAnimationFrame(() => {
+        this.#focusScrollRafId = null;
+        if (win.scrollX !== beforeX || win.scrollY !== beforeY) {
+          win.scrollTo(beforeX, beforeY);
+        }
+      });
     };
   }
 
@@ -2148,6 +2164,14 @@ export class PresentationEditor extends EventEmitter {
     pos: number,
     options: { block?: 'start' | 'center' | 'end' | 'nearest'; behavior?: ScrollBehavior } = {},
   ): boolean {
+    // Cancel any pending focus-scroll RAF so this intentional scroll is not undone
+    // by the wrapHiddenEditorFocus safety net (e.g. search navigation after focus).
+    if (this.#focusScrollRafId != null) {
+      const win = this.#visibleHost.ownerDocument?.defaultView;
+      if (win) win.cancelAnimationFrame(this.#focusScrollRafId);
+      this.#focusScrollRafId = null;
+    }
+
     const activeEditor = this.getActiveEditor();
     const doc = activeEditor?.state?.doc;
     if (!doc) return false;
@@ -2523,6 +2547,15 @@ export class PresentationEditor extends EventEmitter {
       }, 'Layout RAF');
     }
 
+    // Cancel pending focus-scroll safety net RAF
+    if (this.#focusScrollRafId != null) {
+      safeCleanup(() => {
+        const win = this.#visibleHost?.ownerDocument?.defaultView ?? window;
+        win.cancelAnimationFrame(this.#focusScrollRafId!);
+        this.#focusScrollRafId = null;
+      }, 'Focus scroll RAF');
+    }
+
     // Cancel pending decoration sync RAF
     if (this.#decorationSyncRafHandle != null) {
       safeCleanup(() => {

packages/super-editor/src/core/presentation-editor/tests/PresentationEditor.focusWrapping.test.ts

@@ -355,6 +355,52 @@ describe('PresentationEditor - Focus Wrapping (#wrapHiddenEditorFocus)', () => {
         editor.editor.view.focus();
       }).not.toThrow();
     });
+
+    it('schedules requestAnimationFrame that restores scroll on async drift', () => {
+      editor = new PresentationEditor({
+        element: container,
+        documentId: 'test-doc',
+        pageSize: { w: 612, h: 792 },
+      });
+
+      // Capture the RAF callback so we can invoke it manually
+      let rafCallback: FrameRequestCallback | null = null;
+      const rafSpy = vi.spyOn(window, 'requestAnimationFrame').mockImplementation((cb) => {
+        rafCallback = cb;
+        return 1;
+      });
+      const scrollToSpy = vi.spyOn(window, 'scrollTo').mockImplementation(() => {});
+
+      // At focus time, scrollX=0 scrollY=0 → captured as beforeX=0 beforeY=0
+      editor.editor.view.focus();
+
+      expect(rafSpy).toHaveBeenCalledTimes(1);
+      expect(rafCallback).not.toBeNull();
+
+      // Simulate the browser async-scrolling to the hidden editor (drift from 0 to 500)
+      Object.defineProperty(window, 'scrollY', { value: 500, configurable: true });
+
+      // Run the RAF callback — it should detect drift and restore to beforeY=0
+      rafCallback!(0);
+      expect(scrollToSpy).toHaveBeenCalledWith(0, 0);
+    });
+
+    it('cancels focus-scroll RAF when scrollToPosition is called', () => {
+      editor = new PresentationEditor({
+        element: container,
+        documentId: 'test-doc',
+        pageSize: { w: 612, h: 792 },
+      });
+
+      const cancelSpy = vi.spyOn(window, 'cancelAnimationFrame');
+
+      editor.editor.view.focus();
+
+      // scrollToPosition will fail (no layout) but should still cancel the RAF
+      editor.scrollToPosition(0);
+
+      expect(cancelSpy).toHaveBeenCalled();
+    });
   });
 
   describe('mock detection', () => {