Auto detect scrolling container

core/quill.ts

@@ -16,6 +16,7 @@ import Module from './module';
 import Selection, { Range } from './selection';
 import Composition from './composition';
 import Theme, { ThemeConstructor } from './theme';
+import scrollRectIntoView, { Rect } from './utils/scrollRectIntoView';
 
 const debug = logger('quill');
 
@@ -30,7 +31,6 @@ interface Options {
   container?: HTMLElement | string;
   placeholder?: string;
   bounds?: HTMLElement | string | null;
-  scrollingContainer?: HTMLElement | string | null;
   modules?: Record<string, unknown>;
 }
 
@@ -40,7 +40,6 @@ interface ExpandedOptions extends Omit<Options, 'theme'> {
   container: HTMLElement;
   modules: Record<string, unknown>;
   bounds?: HTMLElement | null;
-  scrollingContainer?: HTMLElement | null;
 }
 
 class Quill {
@@ -50,7 +49,6 @@ class Quill {
     placeholder: '',
     readOnly: false,
     registry: globalRegistry,
-    scrollingContainer: null,
     theme: 'default',
   };
   static events = Emitter.events;
@@ -129,7 +127,6 @@ class Quill {
     }
   }
 
-  scrollingContainer: HTMLElement;
   container: HTMLElement;
   root: HTMLDivElement;
   scroll: Scroll;
@@ -163,7 +160,6 @@ class Quill {
     instances.set(this.container, this);
     this.root = this.addContainer('ql-editor');
     this.root.classList.add('ql-blank');
-    this.scrollingContainer = this.options.scrollingContainer || this.root;
     this.emitter = new Emitter();
     // @ts-expect-error TODO: fix BlotConstructor
     const ScrollBlot = this.options.registry.query(
@@ -287,11 +283,11 @@ class Quill {
     this.container.classList.toggle('ql-disabled', !enabled);
   }
 
-  focus() {
-    const { scrollTop } = this.scrollingContainer;
+  focus(options: { preventScroll?: boolean } = {}) {
     this.selection.focus();
-    this.scrollingContainer.scrollTop = scrollTop;
-    this.scrollIntoView();
+    if (!options.preventScroll) {
+      this.scrollSelectionIntoView();
+    }
   }
 
   format(
@@ -618,8 +614,30 @@ class Quill {
     );
   }
 
+  scrollRectIntoView(rect: Rect) {
+    scrollRectIntoView(this.root, rect);
+  }
+
+  /**
+   * @deprecated Use Quill#scrollSelectionIntoView() instead.
+   */
   scrollIntoView() {
-    this.selection.scrollIntoView(this.scrollingContainer);
+    console.warn(
+      'Quill#scrollIntoView() has been deprecated and will be removed in the near future. Please use Quill#scrollSelectionIntoView() instead.',
+    );
+    this.scrollSelectionIntoView();
+  }
+
+  /**
+   * Scroll the current selection into the visible area.
+   * If the selection is already visible, no scrolling will occur.
+   */
+  scrollSelectionIntoView() {
+    const range = this.selection.lastRange;
+    const bounds = range && this.selection.getBounds(range.index, range.length);
+    if (bounds) {
+      this.scrollRectIntoView(bounds);
+    }
   }
 
   setContents(
@@ -658,7 +676,7 @@ class Quill {
       [index, length, , source] = overload(index, length, source);
       this.selection.setRange(new Range(Math.max(0, index), length), source);
       if (source !== Emitter.sources.SILENT) {
-        this.scrollIntoView();
+        this.scrollSelectionIntoView();
       }
     }
   }
@@ -758,7 +776,7 @@ function expandConfig(
     themeConfig,
     expandedConfig,
   );
-  ['bounds', 'container', 'scrollingContainer'].forEach(key => {
+  ['bounds', 'container'].forEach(key => {
     if (typeof expandedConfig[key] === 'string') {
       expandedConfig[key] = document.querySelector(expandedConfig[key]);
     }

core/selection.ts

@@ -127,7 +127,7 @@ class Selection {
 
   focus() {
     if (this.hasFocus()) return;
-    this.root.focus();
+    this.root.focus({ preventScroll: true });
     this.setRange(this.savedRange);
   }
 
@@ -328,19 +328,6 @@ class Selection {
     ];
   }
 
-  scrollIntoView(scrollingContainer: Element) {
-    const range = this.lastRange;
-    if (range == null) return;
-    const bounds = this.getBounds(range.index, range.length);
-    if (bounds == null) return;
-    const scrollBounds = scrollingContainer.getBoundingClientRect();
-    if (bounds.top < scrollBounds.top) {
-      scrollingContainer.scrollTop -= scrollBounds.top - bounds.top;
-    } else if (bounds.bottom > scrollBounds.bottom) {
-      scrollingContainer.scrollTop += bounds.bottom - scrollBounds.bottom;
-    }
-  }
-
   setNativeRange(
     startNode: Node | null,
     startOffset?: number,
@@ -361,7 +348,7 @@ class Selection {
     const selection = document.getSelection();
     if (selection == null) return;
     if (startNode != null) {
-      if (!this.hasFocus()) this.root.focus();
+      if (!this.hasFocus()) this.root.focus({ preventScroll: true });
       const { native } = this.getNativeRange() || {};
       if (
         native == null ||

core/utils/scrollRectIntoView.ts

@@ -0,0 +1,127 @@
+export type Rect = {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+};
+
+const getParentElement = (element: Node): Element | null =>
+  element.parentElement || (element.getRootNode() as ShadowRoot).host || null;
+
+const getElementRect = (element: Element): Rect => {
+  const rect = element.getBoundingClientRect();
+  const scaleX =
+    ('offsetWidth' in element &&
+      Math.abs(rect.width) / (element as HTMLElement).offsetWidth) ||
+    1;
+  const scaleY =
+    ('offsetHeight' in element &&
+      Math.abs(rect.height) / (element as HTMLElement).offsetHeight) ||
+    1;
+  return {
+    top: rect.top,
+    right: rect.left + element.clientWidth * scaleX,
+    bottom: rect.top + element.clientHeight * scaleY,
+    left: rect.left,
+  };
+};
+
+const paddingValueToInt = (value: string) => {
+  const number = parseInt(value, 10);
+  return Number.isNaN(number) ? 0 : number;
+};
+
+// Follow the steps described in https://www.w3.org/TR/cssom-view-1/#element-scrolling-members,
+// assuming that the scroll option is set to 'nearest'.
+const getScrollDistance = (
+  targetStart: number,
+  targetEnd: number,
+  scrollStart: number,
+  scrollEnd: number,
+  scrollPaddingStart: number,
+  scrollPaddingEnd: number,
+) => {
+  if (targetStart < scrollStart && targetEnd > scrollEnd) {
+    return 0;
+  }
+
+  if (targetStart < scrollStart) {
+    return -(scrollStart - targetStart + scrollPaddingStart);
+  }
+
+  if (targetEnd > scrollEnd) {
+    return targetEnd - targetStart > scrollEnd - scrollStart
+      ? targetStart + scrollPaddingStart - scrollStart
+      : targetEnd - scrollEnd + scrollPaddingEnd;
+  }
+  return 0;
+};
+
+const scrollRectIntoView = (root: HTMLElement, targetRect: Rect) => {
+  const document = root.ownerDocument;
+
+  let rect = targetRect;
+
+  let current: Element | null = root;
+  while (current) {
+    const isDocumentBody = current === document.body;
+    const bounding = isDocumentBody
+      ? {
+          top: 0,
+          right:
+            window.visualViewport?.width ??
+            document.documentElement.clientWidth,
+          bottom:
+            window.visualViewport?.height ??
+            document.documentElement.clientHeight,
+          left: 0,
+        }
+      : getElementRect(current);
+
+    const style = getComputedStyle(current);
+    const scrollDistanceX = getScrollDistance(
+      rect.left,
+      rect.right,
+      bounding.left,
+      bounding.right,
+      paddingValueToInt(style.scrollPaddingLeft),
+      paddingValueToInt(style.scrollPaddingRight),
+    );
+    const scrollDistanceY = getScrollDistance(
+      rect.top,
+      rect.bottom,
+      bounding.top,
+      bounding.bottom,
+      paddingValueToInt(style.scrollPaddingTop),
+      paddingValueToInt(style.scrollPaddingBottom),
+    );
+    if (scrollDistanceX || scrollDistanceY) {
+      if (isDocumentBody) {
+        document.defaultView?.scrollBy(scrollDistanceX, scrollDistanceY);
+      } else {
+        const { scrollLeft, scrollTop } = current;
+        if (scrollDistanceY) {
+          current.scrollTop += scrollDistanceY;
+        }
+        if (scrollDistanceX) {
+          current.scrollLeft += scrollDistanceX;
+        }
+        const scrolledLeft = current.scrollLeft - scrollLeft;
+        const scrolledTop = current.scrollTop - scrollTop;
+        rect = {
+          left: rect.left - scrolledLeft,
+          top: rect.top - scrolledTop,
+          right: rect.right - scrolledLeft,
+          bottom: rect.bottom - scrolledTop,
+        };
+      }
+    }
+
+    current =
+      isDocumentBody || style.position === 'fixed'
+        ? null
+        : getParentElement(current);
+  }
+};
+
+export default scrollRectIntoView;

modules/clipboard.ts

@@ -218,7 +218,7 @@ class Clipboard extends Module<ClipboardOptions> {
       delta.length() - range.length,
       Quill.sources.SILENT,
     );
-    this.quill.scrollIntoView();
+    this.quill.scrollSelectionIntoView();
   }
 
   prepareMatching(container: Element, nodeMatches: WeakMap<Node, Matcher[]>) {

modules/keyboard.ts

@@ -460,7 +460,7 @@ const defaultOptions: KeyboardOptions = {
           .retain(1, { list: 'unchecked' });
         this.quill.updateContents(delta, Quill.sources.USER);
         this.quill.setSelection(range.index + 1, Quill.sources.SILENT);
-        this.quill.scrollIntoView();
+        this.quill.scrollSelectionIntoView();
       },
     },
     'header enter': {
@@ -478,7 +478,7 @@ const defaultOptions: KeyboardOptions = {
           .retain(1, { header: null });
         this.quill.updateContents(delta, Quill.sources.USER);
         this.quill.setSelection(range.index + 1, Quill.sources.SILENT);
-        this.quill.scrollIntoView();
+        this.quill.scrollSelectionIntoView();
       },
     },
     'table backspace': {

package.json

@@ -16,6 +16,7 @@
     "website"
   ],
   "dependencies": {
+    "compute-scroll-into-view": "3.0.3",
     "eventemitter3": "^4.0.7",
     "lodash.clonedeep": "^4.5.0",
     "lodash.isequal": "^4.5.0",