@ckeditor/ckeditor5-utils 47.6.1 → 48.0.0-alpha.1

package/src/dom/rect.js

@@ -1,498 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @module utils/dom/rect
- */
-import { isRange } from './isrange.js';
-import { isWindow } from './iswindow.js';
-import { getBorderWidths } from './getborderwidths.js';
-import { isText } from './istext.js';
-import { getPositionedAncestor } from './getpositionedancestor.js';
-import { global } from './global.js';
-const RECT_PROPERTIES = ['top', 'right', 'bottom', 'left', 'width', 'height'];
-const POSITIONING_VALUES = new Set(['relative', 'absolute', 'fixed', 'sticky']);
-/**
- * A helper class representing a `ClientRect` object, e.g. value returned by
- * the native `object.getBoundingClientRect()` method. Provides a set of methods
- * to manipulate the rect and compare it against other rect instances.
- */
-export class Rect {
-    /**
-     * The "top" value of the rect.
-     *
-     * @readonly
-     */
-    top;
-    /**
-     * The "right" value of the rect.
-     *
-     * @readonly
-     */
-    right;
-    /**
-     * The "bottom" value of the rect.
-     *
-     * @readonly
-     */
-    bottom;
-    /**
-     * The "left" value of the rect.
-     *
-     * @readonly
-     */
-    left;
-    /**
-     * The "width" value of the rect.
-     *
-     * @readonly
-     */
-    width;
-    /**
-     * The "height" value of the rect.
-     *
-     * @readonly
-     */
-    height;
-    /**
-     * The object this rect is for.
-     *
-     * @readonly
-     */
-    _source;
-    /**
-     * Creates an instance of rect.
-     *
-     * ```ts
-     * // Rect of an HTMLElement.
-     * const rectA = new Rect( document.body );
-     *
-     * // Rect of a DOM Range.
-     * const rectB = new Rect( document.getSelection().getRangeAt( 0 ) );
-     *
-     * // Rect of a window (web browser viewport).
-     * const rectC = new Rect( window );
-     *
-     * // Rect out of an object.
-     * const rectD = new Rect( { top: 0, right: 10, bottom: 10, left: 0, width: 10, height: 10 } );
-     *
-     * // Rect out of another Rect instance.
-     * const rectE = new Rect( rectD );
-     *
-     * // Rect out of a ClientRect.
-     * const rectF = new Rect( document.body.getClientRects().item( 0 ) );
-     * ```
-     *
-     * **Note**: By default a rect of an HTML element includes its CSS borders and scrollbars (if any)
-     * ant the rect of a `window` includes scrollbars too. Use {@link #excludeScrollbarsAndBorders}
-     * to get the inner part of the rect.
-     *
-     * @param source A source object to create the rect.
-     */
-    constructor(source) {
-        const isSourceRange = isRange(source);
-        Object.defineProperty(this, '_source', {
-            // If the source is a Rect instance, copy it's #_source.
-            value: source._source || source,
-            writable: true,
-            enumerable: false
-        });
-        if (isDomElement(source) || isSourceRange) {
-            // The `Rect` class depends on `getBoundingClientRect` and `getClientRects` DOM methods. If the source
-            // of a rect in an HTML element or a DOM range but it does not belong to any rendered DOM tree, these methods
-            // will fail to obtain the geometry and the rect instance makes little sense to the features using it.
-            // To get rid of this warning make sure the source passed to the constructor is a descendant of `window.document.body`.
-            // @if CK_DEBUG // const sourceNode = isSourceRange ? source.startContainer : source;
-            // @if CK_DEBUG // if ( !sourceNode.ownerDocument || !sourceNode.ownerDocument.body.contains( sourceNode ) ) {
-            // @if CK_DEBUG // 	console.warn(
-            // @if CK_DEBUG // 		'rect-source-not-in-dom: The source of this rect does not belong to any rendered DOM tree.',
-            // @if CK_DEBUG // 		{ source } );
-            // @if CK_DEBUG // }
-            if (isSourceRange) {
-                const rangeRects = Rect.getDomRangeRects(source);
-                copyRectProperties(this, Rect.getBoundingRect(rangeRects));
-            }
-            else {
-                copyRectProperties(this, source.getBoundingClientRect());
-            }
-        }
-        else if (isWindow(source)) {
-            const { innerWidth, innerHeight } = source;
-            copyRectProperties(this, {
-                top: 0,
-                right: innerWidth,
-                bottom: innerHeight,
-                left: 0,
-                width: innerWidth,
-                height: innerHeight
-            });
-        }
-        else {
-            copyRectProperties(this, source);
-        }
-    }
-    /**
-     * Returns a clone of the rect.
-     *
-     * @returns A cloned rect.
-     */
-    clone() {
-        return new Rect(this);
-    }
-    /**
-     * Moves the rect so that its upper–left corner lands in desired `[ x, y ]` location.
-     *
-     * @param x Desired horizontal location.
-     * @param y Desired vertical location.
-     * @returns A rect which has been moved.
-     */
-    moveTo(x, y) {
-        this.top = y;
-        this.right = x + this.width;
-        this.bottom = y + this.height;
-        this.left = x;
-        return this;
-    }
-    /**
-     * Moves the rect in–place by a dedicated offset.
-     *
-     * @param x A horizontal offset.
-     * @param y A vertical offset
-     * @returns A rect which has been moved.
-     */
-    moveBy(x, y) {
-        this.top += y;
-        this.right += x;
-        this.left += x;
-        this.bottom += y;
-        return this;
-    }
-    /**
-     * Returns a new rect a a result of intersection with another rect.
-     */
-    getIntersection(anotherRect) {
-        const rect = {
-            top: Math.max(this.top, anotherRect.top),
-            right: Math.min(this.right, anotherRect.right),
-            bottom: Math.min(this.bottom, anotherRect.bottom),
-            left: Math.max(this.left, anotherRect.left),
-            width: 0,
-            height: 0
-        };
-        rect.width = rect.right - rect.left;
-        rect.height = rect.bottom - rect.top;
-        if (rect.width < 0 || rect.height < 0) {
-            return null;
-        }
-        else {
-            const newRect = new Rect(rect);
-            newRect._source = this._source;
-            return newRect;
-        }
-    }
-    /**
-     * Returns the area of intersection with another rect.
-     *
-     * @returns Area of intersection.
-     */
-    getIntersectionArea(anotherRect) {
-        const rect = this.getIntersection(anotherRect);
-        if (rect) {
-            return rect.getArea();
-        }
-        else {
-            return 0;
-        }
-    }
-    /**
-     * Returns the area of the rect.
-     */
-    getArea() {
-        return this.width * this.height;
-    }
-    /**
-     * Returns a new rect, a part of the original rect, which is actually visible to the user and is relative to the,`body`,
-     * e.g. an original rect cropped by parent element rects which have `overflow` set in CSS
-     * other than `"visible"`.
-     *
-     * If there's no such visible rect, which is when the rect is limited by one or many of
-     * the ancestors, `null` is returned.
-     *
-     * **Note**: This method does not consider the boundaries of the viewport (window).
-     * To get a rect cropped by all ancestors and the viewport, use an intersection such as:
-     *
-     * ```ts
-     * const visibleInViewportRect = new Rect( window ).getIntersection( new Rect( source ).getVisible() );
-     * ```
-     *
-     * @returns A visible rect instance or `null`, if there's none.
-     */
-    getVisible() {
-        const source = this._source;
-        let visibleRect = this.clone();
-        // There's no ancestor to crop <body> with the overflow.
-        if (isBody(source)) {
-            return visibleRect;
-        }
-        let child = source;
-        let parent = source.parentNode || source.commonAncestorContainer;
-        let lastPositionedChildElement;
-        // Check the ancestors all the way up to the <body>.
-        while (parent && !isBody(parent)) {
-            const isNonClippingParent = getElementOverflow(parent) === 'visible';
-            if (isPositioned(child)) {
-                lastPositionedChildElement = child;
-            }
-            // 1. If a parent has overflow: visible, it can be safely skipped in consideration for any parent-child configuration.
-            // 2. If a parent has any other overflow (it clips), for the actual clipping to happen the following must be true:
-            // * the last positioned child must have `position: absolute`,
-            // * the parent must have a position other than `position: static`.
-            //
-            // https://github.com/ckeditor/ckeditor5/issues/14107.
-            if (isNonClippingParent ||
-                (lastPositionedChildElement && getElementPosition(lastPositionedChildElement) === 'absolute' && !isPositioned(parent))) {
-                child = parent;
-                parent = parent.parentNode;
-                continue;
-            }
-            const parentRect = new Rect(parent);
-            const intersectionRect = visibleRect.getIntersection(parentRect);
-            if (intersectionRect) {
-                if (intersectionRect.getArea() < visibleRect.getArea()) {
-                    // Reduce the visible rect to the intersection.
-                    visibleRect = intersectionRect;
-                }
-            }
-            else {
-                // There's no intersection, the rect is completely invisible.
-                return null;
-            }
-            child = parent;
-            parent = parent.parentNode;
-        }
-        return visibleRect;
-    }
-    /**
-     * Checks if all property values ({@link #top}, {@link #left}, {@link #right},
-     * {@link #bottom}, {@link #width} and {@link #height}) are the equal in both rect
-     * instances.
-     *
-     * @param anotherRect A rect instance to compare with.
-     * @returns `true` when Rects are equal. `false` otherwise.
-     */
-    isEqual(anotherRect) {
-        for (const prop of RECT_PROPERTIES) {
-            if (this[prop] !== anotherRect[prop]) {
-                return false;
-            }
-        }
-        return true;
-    }
-    /**
-     * Checks whether a rect fully contains another rect instance.
-     *
-     * @param anotherRect
-     * @returns `true` if contains, `false` otherwise.
-     */
-    contains(anotherRect) {
-        const intersectRect = this.getIntersection(anotherRect);
-        return !!(intersectRect && intersectRect.isEqual(anotherRect));
-    }
-    /**
-     * Recalculates screen coordinates to coordinates relative to the positioned ancestor offset.
-     */
-    toAbsoluteRect() {
-        const { scrollX, scrollY } = global.window;
-        const absoluteRect = this.clone().moveBy(scrollX, scrollY);
-        if (isDomElement(absoluteRect._source)) {
-            const positionedAncestor = getPositionedAncestor(absoluteRect._source);
-            if (positionedAncestor) {
-                shiftRectToCompensatePositionedAncestor(absoluteRect, positionedAncestor);
-            }
-        }
-        return absoluteRect;
-    }
-    /**
-     * Excludes scrollbars and CSS borders from the rect.
-     *
-     * * Borders are removed when {@link #_source} is an HTML element.
-     * * Scrollbars are excluded from HTML elements and the `window`.
-     *
-     * @returns A rect which has been updated.
-     */
-    excludeScrollbarsAndBorders() {
-        const source = this._source;
-        let scrollBarWidth, scrollBarHeight, direction;
-        if (isWindow(source)) {
-            scrollBarWidth = source.innerWidth - source.document.documentElement.clientWidth;
-            scrollBarHeight = source.innerHeight - source.document.documentElement.clientHeight;
-            direction = source.getComputedStyle(source.document.documentElement).direction;
-        }
-        else {
-            const borderWidths = getBorderWidths(source);
-            scrollBarWidth = source.offsetWidth - source.clientWidth - borderWidths.left - borderWidths.right;
-            scrollBarHeight = source.offsetHeight - source.clientHeight - borderWidths.top - borderWidths.bottom;
-            direction = source.ownerDocument.defaultView.getComputedStyle(source).direction;
-            this.left += borderWidths.left;
-            this.top += borderWidths.top;
-            this.right -= borderWidths.right;
-            this.bottom -= borderWidths.bottom;
-            this.width = this.right - this.left;
-            this.height = this.bottom - this.top;
-        }
-        this.width -= scrollBarWidth;
-        if (direction === 'ltr') {
-            this.right -= scrollBarWidth;
-        }
-        else {
-            this.left += scrollBarWidth;
-        }
-        this.height -= scrollBarHeight;
-        this.bottom -= scrollBarHeight;
-        return this;
-    }
-    /**
-     * Returns an array of rects of the given native DOM Range.
-     *
-     * @param range A native DOM range.
-     * @returns DOM Range rects.
-     */
-    static getDomRangeRects(range) {
-        const rects = [];
-        // Safari does not iterate over ClientRectList using for...of loop.
-        const clientRects = Array.from(range.getClientRects());
-        if (clientRects.length) {
-            for (const rect of clientRects) {
-                const r = new Rect(rect);
-                // Point the rect source to the DOM range instead of of the DOM client rect to allow proper clipping,
-                // in `Rect#getVisible()` method.
-                r._source = range;
-                rects.push(r);
-            }
-        }
-        // If there's no client rects for the Range, use parent container's bounding rect
-        // instead and adjust rect's width to simulate the actual geometry of such range.
-        // https://github.com/ckeditor/ckeditor5-utils/issues/153
-        // https://github.com/ckeditor/ckeditor5-ui/issues/317
-        else {
-            let startContainer = range.startContainer;
-            if (isText(startContainer)) {
-                startContainer = startContainer.parentNode;
-            }
-            const rect = new Rect(startContainer.getBoundingClientRect());
-            rect.right = rect.left;
-            rect.width = 0;
-            rects.push(rect);
-        }
-        return rects;
-    }
-    /**
-     * Returns a bounding rectangle that contains all the given `rects`.
-     *
-     * @param rects A list of rectangles that should be contained in the result rectangle.
-     * @returns Bounding rectangle or `null` if no `rects` were given.
-     */
-    static getBoundingRect(rects) {
-        const boundingRectData = {
-            left: Number.POSITIVE_INFINITY,
-            top: Number.POSITIVE_INFINITY,
-            right: Number.NEGATIVE_INFINITY,
-            bottom: Number.NEGATIVE_INFINITY,
-            width: 0,
-            height: 0
-        };
-        let rectangleCount = 0;
-        for (const rect of rects) {
-            rectangleCount++;
-            boundingRectData.left = Math.min(boundingRectData.left, rect.left);
-            boundingRectData.top = Math.min(boundingRectData.top, rect.top);
-            boundingRectData.right = Math.max(boundingRectData.right, rect.right);
-            boundingRectData.bottom = Math.max(boundingRectData.bottom, rect.bottom);
-        }
-        if (rectangleCount == 0) {
-            return null;
-        }
-        boundingRectData.width = boundingRectData.right - boundingRectData.left;
-        boundingRectData.height = boundingRectData.bottom - boundingRectData.top;
-        return new Rect(boundingRectData);
-    }
-}
-/**
- * Acquires all the rect properties from the passed source.
- */
-function copyRectProperties(rect, source) {
-    for (const p of RECT_PROPERTIES) {
-        rect[p] = source[p];
-    }
-}
-/**
- * Checks if provided object is a <body> HTML element.
- */
-function isBody(value) {
-    if (!isDomElement(value)) {
-        return false;
-    }
-    return value === value.ownerDocument.body;
-}
-/**
- * Checks if provided object "looks like" a DOM Element and has API required by `Rect` class.
- */
-function isDomElement(value) {
-    // Note: earlier we used `isElement()` from lodash library, however that function is less performant because
-    // it makes complicated checks to make sure that given value is a DOM element.
-    return value !== null && typeof value === 'object' && value.nodeType === 1 && typeof value.getBoundingClientRect === 'function';
-}
-/**
- * Returns the value of the `position` style of an `HTMLElement`.
- */
-function getElementPosition(element) {
-    return element.ownerDocument.defaultView.getComputedStyle(element).position;
-}
-/**
- * Returns the value of the `overflow` style of an `HTMLElement` or a `Range`.
- */
-function getElementOverflow(element) {
-    return element instanceof HTMLElement ? element.ownerDocument.defaultView.getComputedStyle(element).overflow : 'visible';
-}
-/**
- * Checks if the given node is positioned in any other way than `position: static`.
- */
-function isPositioned(node) {
-    return node instanceof HTMLElement && POSITIONING_VALUES.has(getElementPosition(node));
-}
-/**
- * For a given absolute Rect coordinates object and a positioned element ancestor, it updates its
- * coordinates that make up for the position and the scroll of the ancestor.
- *
- * This is necessary because while Rects (and DOMRects) are relative to the browser's viewport, their coordinates
- * are used in real–life to position elements with `position: absolute`, which are scoped by any positioned
- * (and scrollable) ancestors.
- */
-function shiftRectToCompensatePositionedAncestor(rect, positionedElementAncestor) {
-    const ancestorPosition = new Rect(positionedElementAncestor);
-    const ancestorBorderWidths = getBorderWidths(positionedElementAncestor);
-    let moveX = 0;
-    let moveY = 0;
-    // (https://github.com/ckeditor/ckeditor5-ui-default/issues/126)
-    // If there's some positioned ancestor of the panel, then its `Rect` must be taken into
-    // consideration. `Rect` is always relative to the viewport while `position: absolute` works
-    // with respect to that positioned ancestor.
-    moveX -= ancestorPosition.left;
-    moveY -= ancestorPosition.top;
-    // (https://github.com/ckeditor/ckeditor5-utils/issues/139)
-    // If there's some positioned ancestor of the panel, not only its position must be taken into
-    // consideration (see above) but also its internal scrolls. Scroll have an impact here because `Rect`
-    // is relative to the viewport (it doesn't care about scrolling), while `position: absolute`
-    // must compensate that scrolling.
-    moveX += positionedElementAncestor.scrollLeft;
-    moveY += positionedElementAncestor.scrollTop;
-    // (https://github.com/ckeditor/ckeditor5-utils/issues/139)
-    // If there's some positioned ancestor of the panel, then its `Rect` includes its CSS `borderWidth`
-    // while `position: absolute` positioning does not consider it.
-    // E.g. `{ position: absolute, top: 0, left: 0 }` means upper left corner of the element,
-    // not upper-left corner of its border.
-    moveX -= ancestorBorderWidths.left;
-    moveY -= ancestorBorderWidths.top;
-    rect.moveBy(moveX, moveY);
-}

package/src/dom/remove.js

@@ -1,18 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @module utils/dom/remove
- */
-/**
- * Removes given node from parent.
- *
- * @param node Node to remove.
- */
-export function remove(node) {
-    const parent = node.parentNode;
-    if (parent) {
-        parent.removeChild(node);
-    }
-}

package/src/dom/resizeobserver.js

@@ -1,134 +0,0 @@
-/**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-/**
- * @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.
- */
-export class ResizeObserver {
-    /**
-     * The element observed by this observer.
-     */
-    _element;
-    /**
-     * The callback executed each time {@link #_element} is resized.
-     */
-    _callback;
-    /**
-     * The single native observer instance shared across all {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
-     */
-    static _observerInstance = null;
-    /**
-     * A mapping of native DOM elements and their callbacks shared across all
-     * {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
-     */
-    static _elementCallbacks = null;
-    /**
-     * 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);
-                    }
-                }
-            }
-        });
-    }
-}