@ckeditor/ckeditor5-utils 34.2.0 → 35.1.0

package/src/dom/scroll.js

@@ -2,107 +2,88 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
 /**
  * @module utils/dom/scroll
  */
-
 import isRange from './isrange';
 import Rect from './rect';
 import isText from './istext';
-
-const utils = {};
-
 /**
  * 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 {Object} options
  * @param {HTMLElement|Range} options.target A target, which supposed to become visible to the user.
  * @param {Number} [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
  * by keeping the `target` some distance from the edge of the viewport and thus making it easier to
  * read or edit by the user.
  */
-export function scrollViewportToShowTarget( { target, viewportOffset = 0 } ) {
-	const targetWindow = getWindow( target );
-	let currentWindow = targetWindow;
-	let currentFrame = null;
-
-	// Iterate over all windows, starting from target's parent window up to window#top.
-	while ( currentWindow ) {
-		let firstAncestorToScroll;
-
-		// Let's scroll target's ancestors first to reveal it. Then, once the ancestor scrolls
-		// settled down, the algorithm can eventually scroll the viewport of the current window.
-		//
-		// Note: If the current window is target's **original** window (e.g. the first one),
-		// start scrolling the closest parent of the target. If not, scroll the closest parent
-		// of an iframe that resides in the current window.
-		if ( currentWindow == targetWindow ) {
-			firstAncestorToScroll = getParentElement( target );
-		} else {
-			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 );
-		} );
-
-		// 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 );
-
-		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
-			// in the parent window's relative geometry. The target's rect must be shifted
-			// by it's iframe's position.
-			currentFrame = currentWindow.frameElement;
-			currentWindow = currentWindow.parent;
-
-			// If the current window has some parent but frameElement is inaccessible, then they have
-			// different domains/ports and, due to security reasons, accessing and scrolling
-			// the parent window won't be possible.
-			// See https://github.com/ckeditor/ckeditor5/issues/930.
-			if ( !currentFrame ) {
-				return;
-			}
-		} else {
-			currentWindow = null;
-		}
-	}
+export function scrollViewportToShowTarget({ target, viewportOffset = 0 }) {
+    const targetWindow = getWindow(target);
+    let currentWindow = targetWindow;
+    let currentFrame = null;
+    // Iterate over all windows, starting from target's parent window up to window#top.
+    while (currentWindow) {
+        let firstAncestorToScroll;
+        // Let's scroll target's ancestors first to reveal it. Then, once the ancestor scrolls
+        // settled down, the algorithm can eventually scroll the viewport of the current window.
+        //
+        // Note: If the current window is target's **original** window (e.g. the first one),
+        // start scrolling the closest parent of the target. If not, scroll the closest parent
+        // of an iframe that resides in the current window.
+        if (currentWindow == targetWindow) {
+            firstAncestorToScroll = getParentElement(target);
+        }
+        else {
+            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);
+        });
+        // 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);
+        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
+            // in the parent window's relative geometry. The target's rect must be shifted
+            // by it's iframe's position.
+            currentFrame = currentWindow.frameElement;
+            currentWindow = currentWindow.parent;
+            // If the current window has some parent but frameElement is inaccessible, then they have
+            // different domains/ports and, due to security reasons, accessing and scrolling
+            // the parent window won't be possible.
+            // See https://github.com/ckeditor/ckeditor5/issues/930.
+            if (!currentFrame) {
+                return;
+            }
+        }
+        else {
+            currentWindow = null;
+        }
+    }
 }
-
 /**
  * Makes any page `HTMLElement` or `Range` (target) visible within its scrollable ancestors,
  * e.g. if they have `overflow: scroll` CSS style.
  *
  * @param {HTMLElement|Range} target A target, which supposed to become visible to the user.
  */
-export function scrollAncestorsToShowTarget( target ) {
-	const targetParent = getParentElement( target );
-
-	scrollAncestorsToShowRect( targetParent, () => {
-		return new Rect( target );
-	} );
+export function scrollAncestorsToShowTarget(target) {
+    const targetParent = getParentElement(target);
+    scrollAncestorsToShowRect(targetParent, () => {
+        return new Rect(target);
+    });
 }
-
-// TODO: Using a property value shorthand in the top of the file
-// causes JSDoc to throw errors. See https://github.com/cksource/docs-builder/issues/75.
-Object.assign( utils, {
-	scrollViewportToShowTarget,
-	scrollAncestorsToShowTarget
-} );
-
 // Makes a given rect visible within its parent window.
 //
 // Note: Avoid the situation where the caret is still in the viewport, but totally
@@ -144,134 +125,125 @@ Object.assign( utils, {
 // @param {Window} window A window which is scrolled to reveal the rect.
 // @param {module:utils/dom/rect~Rect} rect A rect which is to be revealed.
 // @param {Number} viewportOffset See scrollViewportToShowTarget.
-function scrollWindowToShowRect( window, rect, 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;
-
-		if ( isAbove( targetShiftedUpRect, viewportRect ) ) {
-			scrollY -= viewportRect.top - rect.top + viewportOffset;
-		} else if ( isBelow( targetShiftedDownRect, viewportRect ) ) {
-			scrollY += rect.bottom - viewportRect.bottom + viewportOffset;
-		}
-
-		// 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 ) ) {
-			scrollX -= viewportRect.left - rect.left + viewportOffset;
-		} else if ( isRightOf( rect, viewportRect ) ) {
-			scrollX += rect.right - viewportRect.right + viewportOffset;
-		}
-
-		window.scrollTo( scrollX, scrollY );
-	}
+function scrollWindowToShowRect(window, rect, 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;
+        if (isAbove(targetShiftedUpRect, viewportRect)) {
+            scrollY -= viewportRect.top - rect.top + viewportOffset;
+        }
+        else if (isBelow(targetShiftedDownRect, viewportRect)) {
+            scrollY += rect.bottom - viewportRect.bottom + viewportOffset;
+        }
+        // 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)) {
+            scrollX -= viewportRect.left - rect.left + viewportOffset;
+        }
+        else if (isRightOf(rect, viewportRect)) {
+            scrollX += rect.right - viewportRect.right + viewportOffset;
+        }
+        window.scrollTo(scrollX, scrollY);
+    }
 }
-
 // Recursively scrolls element ancestors to visually reveal a rect.
 //
 // @private
 // @param {HTMLElement} A parent The first ancestors to start scrolling.
 // @param {Function} getRect A function which returns the Rect, which is to be revealed.
-function scrollAncestorsToShowRect( parent, getRect ) {
-	const parentWindow = getWindow( parent );
-	let parentRect, targetRect;
-
-	while ( parent != parentWindow.document.body ) {
-		targetRect = getRect();
-		parentRect = new Rect( parent ).excludeScrollbarsAndBorders();
-
-		if ( !parentRect.contains( targetRect ) ) {
-			if ( isAbove( targetRect, parentRect ) ) {
-				parent.scrollTop -= parentRect.top - targetRect.top;
-			} else if ( isBelow( targetRect, parentRect ) ) {
-				parent.scrollTop += targetRect.bottom - parentRect.bottom;
-			}
-
-			if ( isLeftOf( targetRect, parentRect ) ) {
-				parent.scrollLeft -= parentRect.left - targetRect.left;
-			} else if ( isRightOf( targetRect, parentRect ) ) {
-				parent.scrollLeft += targetRect.right - parentRect.right;
-			}
-		}
-
-		parent = parent.parentNode;
-	}
+function scrollAncestorsToShowRect(parent, getRect) {
+    const parentWindow = getWindow(parent);
+    let parentRect, targetRect;
+    while (parent != parentWindow.document.body) {
+        targetRect = getRect();
+        parentRect = new Rect(parent).excludeScrollbarsAndBorders();
+        if (!parentRect.contains(targetRect)) {
+            if (isAbove(targetRect, parentRect)) {
+                parent.scrollTop -= parentRect.top - targetRect.top;
+            }
+            else if (isBelow(targetRect, parentRect)) {
+                parent.scrollTop += targetRect.bottom - parentRect.bottom;
+            }
+            if (isLeftOf(targetRect, parentRect)) {
+                parent.scrollLeft -= parentRect.left - targetRect.left;
+            }
+            else if (isRightOf(targetRect, parentRect)) {
+                parent.scrollLeft += targetRect.right - parentRect.right;
+            }
+        }
+        parent = parent.parentNode;
+    }
 }
-
 // Determines if a given `Rect` extends beyond the bottom edge of the second `Rect`.
 //
 // @private
 // @param {module:utils/dom/rect~Rect} firstRect
 // @param {module:utils/dom/rect~Rect} secondRect
-function isBelow( firstRect, secondRect ) {
-	return firstRect.bottom > secondRect.bottom;
+// @returns {Boolean}
+function isBelow(firstRect, secondRect) {
+    return firstRect.bottom > secondRect.bottom;
 }
-
 // Determines if a given `Rect` extends beyond the top edge of the second `Rect`.
 //
 // @private
 // @param {module:utils/dom/rect~Rect} firstRect
 // @param {module:utils/dom/rect~Rect} secondRect
-function isAbove( firstRect, secondRect ) {
-	return firstRect.top < secondRect.top;
+// @returns {Boolean}
+function isAbove(firstRect, secondRect) {
+    return firstRect.top < secondRect.top;
 }
-
 // Determines if a given `Rect` extends beyond the left edge of the second `Rect`.
 //
 // @private
 // @param {module:utils/dom/rect~Rect} firstRect
 // @param {module:utils/dom/rect~Rect} secondRect
-function isLeftOf( firstRect, secondRect ) {
-	return firstRect.left < secondRect.left;
+// @returns {Boolean}
+function isLeftOf(firstRect, secondRect) {
+    return firstRect.left < secondRect.left;
 }
-
 // Determines if a given `Rect` extends beyond the right edge of the second `Rect`.
 //
 // @private
 // @param {module:utils/dom/rect~Rect} firstRect
 // @param {module:utils/dom/rect~Rect} secondRect
-function isRightOf( firstRect, secondRect ) {
-	return firstRect.right > secondRect.right;
+// @returns {Boolean}
+function isRightOf(firstRect, secondRect) {
+    return firstRect.right > secondRect.right;
 }
-
 // Returns the closest window of an element or range.
 //
 // @private
-// @param {HTMLElement|Range} firstRect
+// @param {HTMLElement|Range} elementOrRange
 // @returns {Window}
-function getWindow( elementOrRange ) {
-	if ( isRange( elementOrRange ) ) {
-		return elementOrRange.startContainer.ownerDocument.defaultView;
-	} else {
-		return elementOrRange.ownerDocument.defaultView;
-	}
+function getWindow(elementOrRange) {
+    if (isRange(elementOrRange)) {
+        return elementOrRange.startContainer.ownerDocument.defaultView;
+    }
+    else {
+        return elementOrRange.ownerDocument.defaultView;
+    }
 }
-
 // Returns the closest parent of an element or DOM range.
 //
 // @private
-// @param {HTMLElement|Range} firstRect
+// @param {HTMLElement|Range} elementOrRange
 // @returns {HTMLelement}
-function getParentElement( elementOrRange ) {
-	if ( isRange( elementOrRange ) ) {
-		let parent = elementOrRange.commonAncestorContainer;
-
-		// If a Range is attached to the Text, use the closest element ancestor.
-		if ( isText( parent ) ) {
-			parent = parent.parentNode;
-		}
-
-		return parent;
-	} else {
-		return elementOrRange.parentNode;
-	}
+function getParentElement(elementOrRange) {
+    if (isRange(elementOrRange)) {
+        let parent = elementOrRange.commonAncestorContainer;
+        // If a Range is attached to the Text, use the closest element ancestor.
+        if (isText(parent)) {
+            parent = parent.parentNode;
+        }
+        return parent;
+    }
+    else {
+        return elementOrRange.parentNode;
+    }
 }
-
 // Returns the rect of an element or range residing in an iframe.
 // The result rect is relative to the geometry of the passed window instance.
 //
@@ -279,24 +251,20 @@ function getParentElement( elementOrRange ) {
 // @param {HTMLElement|Range} target Element or range which rect should be returned.
 // @param {Window} relativeWindow A window the rect should be relative to.
 // @returns {module:utils/dom/rect~Rect}
-function getRectRelativeToWindow( target, relativeWindow ) {
-	const targetWindow = getWindow( target );
-	const rect = new Rect( target );
-
-	if ( targetWindow === relativeWindow ) {
-		return rect;
-	} else {
-		let currentWindow = targetWindow;
-
-		while ( currentWindow != relativeWindow ) {
-			const frame = currentWindow.frameElement;
-			const frameRect = new Rect( frame ).excludeScrollbarsAndBorders();
-
-			rect.moveBy( frameRect.left, frameRect.top );
-
-			currentWindow = currentWindow.parent;
-		}
-	}
-
-	return rect;
+function getRectRelativeToWindow(target, relativeWindow) {
+    const targetWindow = getWindow(target);
+    const rect = new Rect(target);
+    if (targetWindow === relativeWindow) {
+        return rect;
+    }
+    else {
+        let currentWindow = targetWindow;
+        while (currentWindow != relativeWindow) {
+            const frame = currentWindow.frameElement;
+            const frameRect = new Rect(frame).excludeScrollbarsAndBorders();
+            rect.moveBy(frameRect.left, frameRect.top);
+            currentWindow = currentWindow.parent;
+        }
+    }
+    return rect;
 }

package/src/dom/setdatainelement.js

@@ -2,23 +2,19 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
 /**
  * @module utils/dom/setdatainelement
  */
-
 /* globals HTMLTextAreaElement */
-
 /**
  * Sets data in a given element.
  *
  * @param {HTMLElement} el The element in which the data will be set.
  * @param {String} data The data string.
  */
-export default function setDataInElement( el, data ) {
-	if ( el instanceof HTMLTextAreaElement ) {
-		el.value = data;
-	}
-
-	el.innerHTML = data;
+export default function setDataInElement(el, data) {
+    if (el instanceof HTMLTextAreaElement) {
+        el.value = data;
+    }
+    el.innerHTML = data;
 }

package/src/dom/tounit.js

@@ -2,11 +2,9 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
 /**
  * @module utils/dom/tounit
  */
-
 /**
  * Returns a helper function, which adds a desired trailing
  * `unit` to the passed value.
@@ -14,14 +12,14 @@
  * @param {String} unit An unit like "px" or "em".
  * @returns {module:utils/dom/tounit~helper}
  */
-export default function toUnit( unit ) {
-	/**
-	 * A function, which adds a pre–defined trailing `unit`
-	 * to the passed `value`.
-	 *
-	 * @function helper
- 	 * @param {*} value A value to be given the unit.
- 	 * @returns {String} A value with the trailing unit.
-	 */
-	return value => value + unit;
+export default function toUnit(unit) {
+    /**
+     * A function, which adds a pre–defined trailing `unit`
+     * to the passed `value`.
+     *
+     * @function helper
+     * @param {String|Number} value A value to be given the unit.
+     * @returns {String} A value with the trailing unit.
+     */
+    return value => value + unit;
 }

package/src/elementreplacer.js

@@ -2,56 +2,42 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
 /**
  * @module utils/elementreplacer
  */
-
 /**
  * Utility class allowing to hide existing HTML elements or replace them with given ones in a way that doesn't remove
  * the original elements from the DOM.
  */
 export default class ElementReplacer {
-	constructor() {
-		/**
-		 * The elements replaced by {@link #replace} and their replacements.
-		 *
-		 * @private
-		 * @member {Array.<Object>}
-		 */
-		this._replacedElements = [];
-	}
-
-	/**
-	 * Hides the `element` and, if specified, inserts the the given element next to it.
-	 *
-	 * The effect of this method can be reverted by {@link #restore}.
-	 *
-	 * @param {HTMLElement} element The element to replace.
-	 * @param {HTMLElement} [newElement] The replacement element. If not passed, then the `element` will just be hidden.
-	 */
-	replace( element, newElement ) {
-		this._replacedElements.push( { element, newElement } );
-
-		element.style.display = 'none';
-
-		if ( newElement ) {
-			element.parentNode.insertBefore( newElement, element.nextSibling );
-		}
-	}
-
-	/**
-	 * Restores what {@link #replace} did.
-	 */
-	restore() {
-		this._replacedElements.forEach( ( { element, newElement } ) => {
-			element.style.display = '';
-
-			if ( newElement ) {
-				newElement.remove();
-			}
-		} );
-
-		this._replacedElements = [];
-	}
+    constructor() {
+        this._replacedElements = [];
+    }
+    /**
+     * Hides the `element` and, if specified, inserts the the given element next to it.
+     *
+     * The effect of this method can be reverted by {@link #restore}.
+     *
+     * @param {HTMLElement} element The element to replace.
+     * @param {HTMLElement} [newElement] The replacement element. If not passed, then the `element` will just be hidden.
+     */
+    replace(element, newElement) {
+        this._replacedElements.push({ element, newElement });
+        element.style.display = 'none';
+        if (newElement) {
+            element.parentNode.insertBefore(newElement, element.nextSibling);
+        }
+    }
+    /**
+     * Restores what {@link #replace} did.
+     */
+    restore() {
+        this._replacedElements.forEach(({ element, newElement }) => {
+            element.style.display = '';
+            if (newElement) {
+                newElement.remove();
+            }
+        });
+        this._replacedElements = [];
+    }
 }