@ckeditor/ckeditor5-utils 0.0.0-internal-20241017.0

package/src/dom/resizeobserver.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * A helper class which instances allow performing custom actions when native DOM elements are resized.
+ *
+ * ```ts
+ * 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 {
+    /**
+     * The element observed by this observer.
+     */
+    private readonly _element;
+    /**
+     * The callback executed each time {@link #_element} is resized.
+     */
+    private readonly _callback;
+    /**
+     * The single native observer instance shared across all {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
+     */
+    private static _observerInstance;
+    /**
+     * A mapping of native DOM elements and their callbacks shared across all
+     * {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
+     */
+    private static _elementCallbacks;
+    /**
+     * Creates an instance of the `ResizeObserver` class.
+     *
+     * @param 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 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: Element, callback: (entry: ResizeObserverEntry) => void);
+    /**
+     * The element observed by this observer.
+     */
+    get element(): Element;
+    /**
+     * Destroys the observer which disables the `callback` passed to the {@link #constructor}.
+     */
+    destroy(): void;
+    /**
+     * Registers a new resize callback for the DOM element.
+     */
+    private static _addElementCallback;
+    /**
+     * 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 _deleteElementCallback;
+    /**
+     * Returns are registered resize callbacks for the DOM element.
+     */
+    private static _getElementCallbacks;
+    /**
+     * Creates the single native observer shared across all `ResizeObserver` instances.
+     */
+    private static _createObserver;
+}

package/src/dom/resizeobserver.js

@@ -0,0 +1,127 @@
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+/**
+ * A helper class which instances allow performing custom actions when native DOM elements are resized.
+ *
+ * ```ts
+ * 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.
+ */
+class ResizeObserver {
+    /**
+     * Creates an instance of the `ResizeObserver` class.
+     *
+     * @param 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 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);
+    }
+    /**
+     * The element observed by this observer.
+     */
+    get element() {
+        return this._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.
+     */
+    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.
+     */
+    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.
+     */
+    static _getElementCallbacks(element) {
+        if (!ResizeObserver._elementCallbacks) {
+            return null;
+        }
+        return ResizeObserver._elementCallbacks.get(element);
+    }
+    /**
+     * Creates the single native observer shared across all `ResizeObserver` instances.
+     */
+    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.
+ */
+ResizeObserver._observerInstance = null;
+/**
+ * A mapping of native DOM elements and their callbacks shared across all
+ * {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
+ */
+ResizeObserver._elementCallbacks = null;
+export default ResizeObserver;

package/src/dom/scroll.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @license Copyright (c) 2003-2024, 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 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 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<T extends boolean, U extends IfTrue<T>>({ target, viewportOffset, ancestorOffset, alignToTop, forceScroll }: {
+    readonly target: HTMLElement | Range;
+    readonly viewportOffset?: number | {
+        top: number;
+        bottom: number;
+        left: number;
+        right: 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.
+ * @param limiterElement The outermost ancestor that should be scrolled. If specified, it can prevent
+ * scrolling the whole page.
+ */
+export declare function scrollAncestorsToShowTarget(target: HTMLElement | Range, ancestorOffset?: number, limiterElement?: HTMLElement): void;
+export {};

package/src/dom/scroll.js

@@ -0,0 +1,383 @@
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import Rect from './rect.js';
+import isText from './istext.js';
+/**
+ * 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 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 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, ancestorOffset = 0, alignToTop, forceScroll }) {
+    const targetWindow = getWindow(target);
+    let currentWindow = targetWindow;
+    let currentFrame = null;
+    viewportOffset = normalizeViewportOffset(viewportOffset);
+    // 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({
+            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({
+            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
+            // 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 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.
+ * @param limiterElement The outermost ancestor that should be scrolled. If specified, it can prevent
+ * scrolling the whole page.
+ */
+export function scrollAncestorsToShowTarget(target, ancestorOffset, limiterElement) {
+    const targetParent = getParentElement(target);
+    scrollAncestorsToShowRect({
+        parent: targetParent,
+        getRect: () => new Rect(target),
+        ancestorOffset,
+        limiterElement
+    });
+}
+/**
+ * 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
+ * +---------------------------------...
+ * ```
+ *
+ * @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, alignToTop, forceScroll, viewportOffset }) {
+    const targetShiftedDownRect = rect.clone().moveBy(0, viewportOffset.bottom);
+    const targetShiftedUpRect = rect.clone().moveBy(0, -viewportOffset.top);
+    const viewportRect = new Rect(window).excludeScrollbarsAndBorders();
+    const rects = [targetShiftedUpRect, targetShiftedDownRect];
+    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.top;
+    }
+    else if (!allRectsFitInViewport) {
+        if (isAbove(targetShiftedUpRect, viewportRect)) {
+            scrollY -= viewportRect.top - rect.top + viewportOffset.top;
+        }
+        else if (isBelow(targetShiftedDownRect, viewportRect)) {
+            if (alignToTop) {
+                scrollY += rect.top - viewportRect.top - viewportOffset.top;
+            }
+            else {
+                scrollY += rect.bottom - viewportRect.bottom + viewportOffset.bottom;
+            }
+        }
+    }
+    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)) {
+            scrollX -= viewportRect.left - rect.left + viewportOffset.left;
+        }
+        else if (isRightOf(rect, viewportRect)) {
+            scrollX += rect.right - viewportRect.right + viewportOffset.right;
+        }
+    }
+    if (scrollX != initialScrollX || scrollY !== initialScrollY) {
+        window.scrollTo(scrollX, scrollY);
+    }
+}
+/**
+ * Recursively scrolls element ancestors to visually reveal a rect.
+ *
+ * @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`
+ * @param options.limiterElement The outermost ancestor that should be scrolled. Defaults to the `<body>` element.
+ */
+function scrollAncestorsToShowRect({ parent, getRect, alignToTop, forceScroll, ancestorOffset = 0, limiterElement }) {
+    const parentWindow = getWindow(parent);
+    const forceScrollToTop = alignToTop && forceScroll;
+    let parentRect, targetRect, targetFitsInTarget;
+    const limiter = limiterElement || parentWindow.document.body;
+    while (parent != limiter) {
+        targetRect = getRect();
+        parentRect = new Rect(parent).excludeScrollbarsAndBorders();
+        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 + ancestorOffset;
+            }
+            else if (isBelow(targetRect, parentRect)) {
+                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 + ancestorOffset;
+            }
+            else if (isRightOf(targetRect, parentRect)) {
+                parent.scrollLeft += targetRect.right - parentRect.right + ancestorOffset;
+            }
+        }
+        parent = parent.parentNode;
+    }
+}
+/**
+ * Determines if a given `Rect` extends beyond the bottom edge of the second `Rect`.
+ */
+function isBelow(firstRect, secondRect) {
+    return firstRect.bottom > secondRect.bottom;
+}
+/**
+ * Determines if a given `Rect` extends beyond the top edge of the second `Rect`.
+ */
+function isAbove(firstRect, secondRect) {
+    return firstRect.top < secondRect.top;
+}
+/**
+ * Determines if a given `Rect` extends beyond the left edge of the second `Rect`.
+ */
+function isLeftOf(firstRect, secondRect) {
+    return firstRect.left < secondRect.left;
+}
+/**
+ * Determines if a given `Rect` extends beyond the right edge of the second `Rect`.
+ */
+function isRightOf(firstRect, secondRect) {
+    return firstRect.right > secondRect.right;
+}
+/**
+ * Returns the closest window of an element or range.
+ */
+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.
+ */
+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.
+ *
+ * @param target Element or range which rect should be returned.
+ * @param relativeWindow A window the rect should be relative to.
+ */
+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;
+}
+/**
+ * A helper that explodes the `viewportOffset` configuration if defined as a plain number into an object
+ * with `top`, `bottom`, `left`, and `right` properties.
+ *
+ * If an object value is passed, this helper will pass it through.
+ *
+ * @param viewportOffset Viewport offset to be normalized.
+ */
+function normalizeViewportOffset(viewportOffset) {
+    if (typeof viewportOffset === 'number') {
+        return {
+            top: viewportOffset,
+            bottom: viewportOffset,
+            left: viewportOffset,
+            right: viewportOffset
+        };
+    }
+    return viewportOffset;
+}

package/src/dom/setdatainelement.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license Copyright (c) 2003-2024, 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
+ */
+/**
+ * Sets data in a given element.
+ *
+ * @param el The element in which the data will be set.
+ * @param data The data string.
+ */
+export default function setDataInElement(el: HTMLElement, data: string): void;