@ckeditor/ckeditor5-utils 37.0.0-alpha.2 → 37.0.0-alpha.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-utils",
-  "version": "37.0.0-alpha.2",
+  "version": "37.0.0-alpha.3",
   "description": "Miscellaneous utilities used by CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -14,10 +14,10 @@
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-build-classic": "^37.0.0-alpha.2",
-    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.2",
-    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.2",
-    "@ckeditor/ckeditor5-engine": "^37.0.0-alpha.2",
+    "@ckeditor/ckeditor5-build-classic": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-core": "^37.0.0-alpha.3",
+    "@ckeditor/ckeditor5-engine": "^37.0.0-alpha.3",
     "@types/lodash-es": "^4.17.6",
     "typescript": "^4.8.4"
   },

package/src/dom/scroll.d.ts

@@ -2,26 +2,65 @@
  * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
+type IfTrue<T> = T extends true ? true : never;
 /**
  * Makes any page `HTMLElement` or `Range` (`target`) visible inside the browser viewport.
  * This helper will scroll all `target` ancestors and the web browser viewport to reveal the target to
  * the user. If the `target` is already visible, nothing will happen.
  *
- * @param options
+ * @param options Additional configuration of the scrolling behavior.
  * @param options.target A target, which supposed to become visible to the user.
  * @param options.viewportOffset An offset from the edge of the viewport (in pixels)
- * the `target` will be moved by when the viewport is scrolled. It enhances the user experience
+ * the `target` will be moved by if the viewport is scrolled. It enhances the user experience
  * by keeping the `target` some distance from the edge of the viewport and thus making it easier to
  * read or edit by the user.
+ * @param options.ancestorOffset An offset from the boundary of scrollable ancestors (if any)
+ * the `target` will be moved by if the viewport is scrolled. It enhances the user experience
+ * by keeping the `target` some distance from the edge of the ancestors and thus making it easier to
+ * read or edit by the user.
+ * @param options.alignToTop When set `true`, the helper will make sure the `target` is scrolled up
+ * to the top boundary of the viewport and/or scrollable ancestors if scrolled up. When not set
+ * (default), the `target` will be revealed by scrolling as little as possible. This option will
+ * not affect `targets` that must be scrolled down because they will appear at the top of the boundary
+ * anyway.
+ *
+ * ```
+ *                                             scrollViewportToShowTarget() with            scrollViewportToShowTarget() with
+ *          Initial state                        alignToTop unset (default)                        alignToTop = true
+ *
+ * ┌────────────────────────────────┬─┐       ┌────────────────────────────────┬─┐        ┌────────────────────────────────┬─┐
+ * │                                │▲│       │                                │▲│        │   [ Target to be revealed ]    │▲│
+ * │                                │ │       │                                │ │        │                                │ │
+ * │                                │█│       │                                │ │        │                                │ │
+ * │                                │█│       │                                │ │        │                                │ │
+ * │                                │ │       │                                │█│        │                                │ │
+ * │                                │ │       │                                │█│        │                                │█│
+ * │                                │ │       │                                │ │        │                                │█│
+ * │                                │▼│       │   [ Target to be revealed ]    │▼│        │                                │▼│
+ * └────────────────────────────────┴─┘       └────────────────────────────────┴─┘        └────────────────────────────────┴─┘
+ *
+ *
+ *     [ Target to be revealed ]
+ *```
+ *
+ * @param options.forceScroll When set `true`, the `target` will be aligned to the top of the viewport
+ * and scrollable ancestors whether it is already visible or not. This option will only work when `alignToTop`
+ * is `true`
  */
-export declare function scrollViewportToShowTarget({ target, viewportOffset }: {
+export declare function scrollViewportToShowTarget<T extends boolean, U extends IfTrue<T>>({ target, viewportOffset, ancestorOffset, alignToTop, forceScroll }: {
     readonly target: HTMLElement | Range;
     readonly viewportOffset?: number;
+    readonly ancestorOffset?: number;
+    readonly alignToTop?: T;
+    readonly forceScroll?: U;
 }): void;
 /**
  * Makes any page `HTMLElement` or `Range` (target) visible within its scrollable ancestors,
  * e.g. if they have `overflow: scroll` CSS style.
  *
  * @param target A target, which supposed to become visible to the user.
+ * @param ancestorOffset An offset between the target and the boundary of scrollable ancestors
+ * to be maintained while scrolling.
  */
-export declare function scrollAncestorsToShowTarget(target: HTMLElement | Range): void;
+export declare function scrollAncestorsToShowTarget(target: HTMLElement | Range, ancestorOffset?: number): void;
+export {};

package/src/dom/scroll.js

@@ -13,14 +13,46 @@ import isText from './istext';
  * This helper will scroll all `target` ancestors and the web browser viewport to reveal the target to
  * the user. If the `target` is already visible, nothing will happen.
  *
- * @param options
+ * @param options Additional configuration of the scrolling behavior.
  * @param options.target A target, which supposed to become visible to the user.
  * @param options.viewportOffset An offset from the edge of the viewport (in pixels)
- * the `target` will be moved by when the viewport is scrolled. It enhances the user experience
+ * the `target` will be moved by if the viewport is scrolled. It enhances the user experience
  * by keeping the `target` some distance from the edge of the viewport and thus making it easier to
  * read or edit by the user.
+ * @param options.ancestorOffset An offset from the boundary of scrollable ancestors (if any)
+ * the `target` will be moved by if the viewport is scrolled. It enhances the user experience
+ * by keeping the `target` some distance from the edge of the ancestors and thus making it easier to
+ * read or edit by the user.
+ * @param options.alignToTop When set `true`, the helper will make sure the `target` is scrolled up
+ * to the top boundary of the viewport and/or scrollable ancestors if scrolled up. When not set
+ * (default), the `target` will be revealed by scrolling as little as possible. This option will
+ * not affect `targets` that must be scrolled down because they will appear at the top of the boundary
+ * anyway.
+ *
+ * ```
+ *                                             scrollViewportToShowTarget() with            scrollViewportToShowTarget() with
+ *          Initial state                        alignToTop unset (default)                        alignToTop = true
+ *
+ * ┌────────────────────────────────┬─┐       ┌────────────────────────────────┬─┐        ┌────────────────────────────────┬─┐
+ * │                                │▲│       │                                │▲│        │   [ Target to be revealed ]    │▲│
+ * │                                │ │       │                                │ │        │                                │ │
+ * │                                │█│       │                                │ │        │                                │ │
+ * │                                │█│       │                                │ │        │                                │ │
+ * │                                │ │       │                                │█│        │                                │ │
+ * │                                │ │       │                                │█│        │                                │█│
+ * │                                │ │       │                                │ │        │                                │█│
+ * │                                │▼│       │   [ Target to be revealed ]    │▼│        │                                │▼│
+ * └────────────────────────────────┴─┘       └────────────────────────────────┴─┘        └────────────────────────────────┴─┘
+ *
+ *
+ *     [ Target to be revealed ]
+ *```
+ *
+ * @param options.forceScroll When set `true`, the `target` will be aligned to the top of the viewport
+ * and scrollable ancestors whether it is already visible or not. This option will only work when `alignToTop`
+ * is `true`
  */
-export function scrollViewportToShowTarget({ target, viewportOffset = 0 }) {
+export function scrollViewportToShowTarget({ target, viewportOffset = 0, ancestorOffset = 0, alignToTop, forceScroll }) {
     const targetWindow = getWindow(target);
     let currentWindow = targetWindow;
     let currentFrame = null;
@@ -40,18 +72,30 @@ export function scrollViewportToShowTarget({ target, viewportOffset = 0 }) {
             firstAncestorToScroll = getParentElement(currentFrame);
         }
         // Scroll the target's ancestors first. Once done, scrolling the viewport is easy.
-        scrollAncestorsToShowRect(firstAncestorToScroll, () => {
-            // Note: If the target does not belong to the current window **directly**,
-            // i.e. it resides in an iframe belonging to the window, obtain the target's rect
-            // in the coordinates of the current window. By default, a Rect returns geometry
-            // relative to the current window's viewport. To make it work in a parent window,
-            // it must be shifted.
-            return getRectRelativeToWindow(target, currentWindow);
+        scrollAncestorsToShowRect({
+            parent: firstAncestorToScroll,
+            getRect: () => {
+                // Note: If the target does not belong to the current window **directly**,
+                // i.e. it resides in an iframe belonging to the window, obtain the target's rect
+                // in the coordinates of the current window. By default, a Rect returns geometry
+                // relative to the current window's viewport. To make it work in a parent window,
+                // it must be shifted.
+                return getRectRelativeToWindow(target, currentWindow);
+            },
+            alignToTop,
+            ancestorOffset,
+            forceScroll
         });
         // Obtain the rect of the target after it has been scrolled within its ancestors.
         // It's time to scroll the viewport.
         const targetRect = getRectRelativeToWindow(target, currentWindow);
-        scrollWindowToShowRect(currentWindow, targetRect, viewportOffset);
+        scrollWindowToShowRect({
+            window: currentWindow,
+            rect: targetRect,
+            viewportOffset,
+            alignToTop,
+            forceScroll
+        });
         if (currentWindow.parent != currentWindow) {
             // Keep the reference to the <iframe> element the "previous current window" was
             // rendered within. It will be useful to re–calculate the rect of the target
@@ -77,11 +121,15 @@ export function scrollViewportToShowTarget({ target, viewportOffset = 0 }) {
  * e.g. if they have `overflow: scroll` CSS style.
  *
  * @param target A target, which supposed to become visible to the user.
+ * @param ancestorOffset An offset between the target and the boundary of scrollable ancestors
+ * to be maintained while scrolling.
  */
-export function scrollAncestorsToShowTarget(target) {
+export function scrollAncestorsToShowTarget(target, ancestorOffset) {
     const targetParent = getParentElement(target);
-    scrollAncestorsToShowRect(targetParent, () => {
-        return new Rect(target);
+    scrollAncestorsToShowRect({
+        parent: targetParent,
+        getRect: () => new Rect(target),
+        ancestorOffset
     });
 }
 /**
@@ -130,23 +178,45 @@ export function scrollAncestorsToShowTarget(target) {
  * +---------------------------------...
  * ```
  *
- * @param window A window which is scrolled to reveal the rect.
- * @param rect A rect which is to be revealed.
- * @param viewportOffset See scrollViewportToShowTarget.
+ * @param options Additional configuration of the scrolling behavior.
+ * @param options.window A window which is scrolled to reveal the rect.
+ * @param options.rect A rect which is to be revealed.
+ * @param options.viewportOffset An offset from the edge of the viewport (in pixels) the `rect` will be
+ * moved by if the viewport is scrolled.
+ * @param options.alignToTop When set `true`, the helper will make sure the `rect` is scrolled up
+ * to the top boundary of the viewport if scrolled up. When not set (default), the `rect` will be
+ * revealed by scrolling as little as possible. This option will not affect rects that must be scrolled
+ * down because they will appear at the top of the boundary anyway.
+ * @param options.forceScroll When set `true`, the `rect` will be aligned to the top of the viewport
+ * whether it is already visible or not. This option will only work when `alignToTop` is `true`
  */
-function scrollWindowToShowRect(window, rect, viewportOffset) {
+function scrollWindowToShowRect({ window, rect, alignToTop, forceScroll, viewportOffset }) {
     const targetShiftedDownRect = rect.clone().moveBy(0, viewportOffset);
     const targetShiftedUpRect = rect.clone().moveBy(0, -viewportOffset);
     const viewportRect = new Rect(window).excludeScrollbarsAndBorders();
     const rects = [targetShiftedUpRect, targetShiftedDownRect];
-    if (!rects.every(rect => viewportRect.contains(rect))) {
-        let { scrollX, scrollY } = window;
+    const forceScrollToTop = alignToTop && forceScroll;
+    const allRectsFitInViewport = rects.every(rect => viewportRect.contains(rect));
+    let { scrollX, scrollY } = window;
+    const initialScrollX = scrollX;
+    const initialScrollY = scrollY;
+    if (forceScrollToTop) {
+        scrollY -= (viewportRect.top - rect.top) + viewportOffset;
+    }
+    else if (!allRectsFitInViewport) {
         if (isAbove(targetShiftedUpRect, viewportRect)) {
             scrollY -= viewportRect.top - rect.top + viewportOffset;
         }
         else if (isBelow(targetShiftedDownRect, viewportRect)) {
-            scrollY += rect.bottom - viewportRect.bottom + viewportOffset;
+            if (alignToTop) {
+                scrollY += rect.top - viewportRect.top - viewportOffset;
+            }
+            else {
+                scrollY += rect.bottom - viewportRect.bottom + viewportOffset;
+            }
         }
+    }
+    if (!allRectsFitInViewport) {
         // TODO: Web browsers scroll natively to place the target in the middle
         // of the viewport. It's not a very popular case, though.
         if (isLeftOf(rect, viewportRect)) {
@@ -155,33 +225,57 @@ function scrollWindowToShowRect(window, rect, viewportOffset) {
         else if (isRightOf(rect, viewportRect)) {
             scrollX += rect.right - viewportRect.right + viewportOffset;
         }
+    }
+    if (scrollX != initialScrollX || scrollY !== initialScrollY) {
         window.scrollTo(scrollX, scrollY);
     }
 }
 /**
  * Recursively scrolls element ancestors to visually reveal a rect.
  *
- * @param parent A parent The first ancestors to start scrolling.
- * @param getRect A function which returns the Rect, which is to be revealed.
+ * @param options Additional configuration of the scrolling behavior.
+ * @param options.parent The first parent ancestor to start scrolling.
+ * @param options.getRect A function which returns the Rect, which is to be revealed.
+ * @param options.ancestorOffset An offset from the boundary of scrollable ancestors (if any)
+ * the `Rect` instance will be moved by if the viewport is scrolled.
+ * @param options.alignToTop When set `true`, the helper will make sure the `Rect` instance is scrolled up
+ * to the top boundary of the scrollable ancestors if scrolled up. When not set (default), the `rect`
+ * will be revealed by scrolling as little as possible. This option will not affect rects that must be
+ * scrolled down because they will appear at the top of the boundary
+ * anyway.
+ * @param options.forceScroll When set `true`, the `rect` will be aligned to the top of scrollable ancestors
+ * whether it is already visible or not. This option will only work when `alignToTop` is `true`
  */
-function scrollAncestorsToShowRect(parent, getRect) {
+function scrollAncestorsToShowRect({ parent, getRect, alignToTop, forceScroll, ancestorOffset = 0 }) {
     const parentWindow = getWindow(parent);
-    let parentRect, targetRect;
+    const forceScrollToTop = alignToTop && forceScroll;
+    let parentRect, targetRect, targetFitsInTarget;
     while (parent != parentWindow.document.body) {
         targetRect = getRect();
         parentRect = new Rect(parent).excludeScrollbarsAndBorders();
-        if (!parentRect.contains(targetRect)) {
+        targetFitsInTarget = parentRect.contains(targetRect);
+        if (forceScrollToTop) {
+            parent.scrollTop -= (parentRect.top - targetRect.top) + ancestorOffset;
+        }
+        else if (!targetFitsInTarget) {
             if (isAbove(targetRect, parentRect)) {
-                parent.scrollTop -= parentRect.top - targetRect.top;
+                parent.scrollTop -= parentRect.top - targetRect.top + ancestorOffset;
             }
             else if (isBelow(targetRect, parentRect)) {
-                parent.scrollTop += targetRect.bottom - parentRect.bottom;
+                if (alignToTop) {
+                    parent.scrollTop += targetRect.top - parentRect.top - ancestorOffset;
+                }
+                else {
+                    parent.scrollTop += targetRect.bottom - parentRect.bottom + ancestorOffset;
+                }
             }
+        }
+        if (!targetFitsInTarget) {
             if (isLeftOf(targetRect, parentRect)) {
-                parent.scrollLeft -= parentRect.left - targetRect.left;
+                parent.scrollLeft -= parentRect.left - targetRect.left + ancestorOffset;
             }
             else if (isRightOf(targetRect, parentRect)) {
-                parent.scrollLeft += targetRect.right - parentRect.right;
+                parent.scrollLeft += targetRect.right - parentRect.right + ancestorOffset;
             }
         }
         parent = parent.parentNode;