@ckeditor/ckeditor5-utils 35.0.0 → 35.0.1

package/src/dom/remove.js

@@ -0,0 +1,18 @@
+/**
+ * @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/remove
+ */
+/**
+ * Removes given node from parent.
+ *
+ * @param {Node} node Node to remove.
+ */
+export default function remove(node) {
+    const parent = node.parentNode;
+    if (parent) {
+        parent.removeChild(node);
+    }
+}

package/src/dom/resizeobserver.js

@@ -0,0 +1,145 @@
+/**
+ * @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/resizeobserver
+ */
+import global from './global';
+/**
+ * A helper class which instances allow performing custom actions when native DOM elements are resized.
+ *
+ *		const editableElement = editor.editing.view.getDomRoot();
+ *
+ *		const observer = new ResizeObserver( editableElement, entry => {
+ *			console.log( 'The editable element has been resized in DOM.' );
+ *			console.log( entry.target ); // -> editableElement
+ *			console.log( entry.contentRect.width ); // -> e.g. '423px'
+ *		} );
+ *
+ * It uses the [native DOM resize observer](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)
+ * under the hood.
+ */
+export default class ResizeObserver {
+    /**
+     * Creates an instance of the `ResizeObserver` class.
+     *
+     * @param {Element} element A DOM element that is to be observed for resizing. Note that
+     * the element must be visible (i.e. not detached from DOM) for the observer to work.
+     * @param {Function} callback A function called when the observed element was resized. It passes
+     * the [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry)
+     * object with information about the resize event.
+     */
+    constructor(element, callback) {
+        // **Note**: For the maximum performance, this class ensures only a single instance of the native
+        // observer is used no matter how many instances of this class were created.
+        if (!ResizeObserver._observerInstance) {
+            ResizeObserver._createObserver();
+        }
+        this._element = element;
+        this._callback = callback;
+        ResizeObserver._addElementCallback(element, callback);
+        ResizeObserver._observerInstance.observe(element);
+    }
+    /**
+     * Destroys the observer which disables the `callback` passed to the {@link #constructor}.
+     */
+    destroy() {
+        ResizeObserver._deleteElementCallback(this._element, this._callback);
+    }
+    /**
+     * Registers a new resize callback for the DOM element.
+     *
+     * @private
+     * @static
+     * @param {Element} element
+     * @param {Function} callback
+     */
+    static _addElementCallback(element, callback) {
+        if (!ResizeObserver._elementCallbacks) {
+            ResizeObserver._elementCallbacks = new Map();
+        }
+        let callbacks = ResizeObserver._elementCallbacks.get(element);
+        if (!callbacks) {
+            callbacks = new Set();
+            ResizeObserver._elementCallbacks.set(element, callbacks);
+        }
+        callbacks.add(callback);
+    }
+    /**
+     * Removes a resize callback from the DOM element. If no callbacks are left
+     * for the element, it removes the element from the native observer.
+     *
+     * @private
+     * @static
+     * @param {Element} element
+     * @param {Function} callback
+     */
+    static _deleteElementCallback(element, callback) {
+        const callbacks = ResizeObserver._getElementCallbacks(element);
+        // Remove the element callback. Check if exist first in case someone
+        // called destroy() twice.
+        if (callbacks) {
+            callbacks.delete(callback);
+            // If no callbacks left for the element, also remove the element.
+            if (!callbacks.size) {
+                ResizeObserver._elementCallbacks.delete(element);
+                ResizeObserver._observerInstance.unobserve(element);
+            }
+        }
+        if (ResizeObserver._elementCallbacks && !ResizeObserver._elementCallbacks.size) {
+            ResizeObserver._observerInstance = null;
+            ResizeObserver._elementCallbacks = null;
+        }
+    }
+    /**
+     * Returns are registered resize callbacks for the DOM element.
+     *
+     * @private
+     * @static
+     * @param {Element} element
+     * @returns {Set.<Function>|null|undefined}
+     */
+    static _getElementCallbacks(element) {
+        if (!ResizeObserver._elementCallbacks) {
+            return null;
+        }
+        return ResizeObserver._elementCallbacks.get(element);
+    }
+    /**
+     * Creates the single native observer shared across all `ResizeObserver` instances.
+     *
+     * @private
+     * @static
+     */
+    static _createObserver() {
+        ResizeObserver._observerInstance = new global.window.ResizeObserver(entries => {
+            for (const entry of entries) {
+                const callbacks = ResizeObserver._getElementCallbacks(entry.target);
+                if (callbacks) {
+                    for (const callback of callbacks) {
+                        callback(entry);
+                    }
+                }
+            }
+        });
+    }
+}
+/**
+ * The single native observer instance shared across all {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
+ *
+ * @static
+ * @private
+ * @readonly
+ * @property {Object|null}
+ */
+ResizeObserver._observerInstance = null;
+/**
+ * A mapping of native DOM elements and their callbacks shared across all
+ * {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
+ *
+ * @static
+ * @private
+ * @property {Map.<Element,Set>|null}
+ */
+ResizeObserver._elementCallbacks = null;

package/src/dom/scroll.js

@@ -0,0 +1,270 @@
+/**
+ * @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';
+/**
+ * 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;
+        }
+    }
+}
+/**
+ * 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);
+    });
+}
+// Makes a given rect visible within its parent window.
+//
+// Note: Avoid the situation where the caret is still in the viewport, but totally
+// at the edge of it. In such situation, if it moved beyond the viewport in the next
+// action e.g. after paste, the scrolling would move it to the viewportOffset level
+// and it all would look like the caret visually moved up/down:
+//
+// 1.
+//		| foo[]
+//		|                                    <--- N px of space below the caret
+//		+---------------------------------...
+//
+// 2. *paste*
+// 3.
+//		|
+//		|
+//		+-foo-----------------------------...
+//		  bar[]                              <--- caret below viewport, scrolling...
+//
+// 4. *scrolling*
+// 5.
+//		|
+//		| foo
+//		| bar[]                              <--- caret precisely at the edge
+//		+---------------------------------...
+//
+// To prevent this, this method checks the rects moved by the viewportOffset to cover
+// the upper/lower edge of the viewport. It makes sure if the action repeats, there's
+// no twitching – it's a purely visual improvement:
+//
+// 5. (after fix)
+//		|
+//		| foo
+//		| bar[]
+//		|                                    <--- N px of space below the caret
+//		+---------------------------------...
+//
+// @private
+// @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);
+    }
+}
+// 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;
+    }
+}
+// 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
+// @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
+// @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
+// @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
+// @returns {Boolean}
+function isRightOf(firstRect, secondRect) {
+    return firstRect.right > secondRect.right;
+}
+// Returns the closest window of an element or range.
+//
+// @private
+// @param {HTMLElement|Range} elementOrRange
+// @returns {Window}
+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} 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;
+    }
+}
+// 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.
+//
+// @private
+// @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;
+}

package/src/dom/setdatainelement.js

@@ -0,0 +1,20 @@
+/**
+ * @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;
+}

package/src/dom/tounit.js

@@ -0,0 +1,25 @@
+/**
+ * @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.
+ *
+ * @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 {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

@@ -0,0 +1,43 @@
+/**
+ * @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() {
+        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 = [];
+    }
+}