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

package/src/dom/emittermixin.js

@@ -1,237 +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/emittermixin
- */
-import { EmitterMixin, _getEmitterListenedTo, _setEmitterId } from '../emittermixin.js';
-import { uid } from '../uid.js';
-import { isNode } from './isnode.js';
-import { isWindow } from './iswindow.js';
-import { global } from './global.js';
-const defaultEmitterClass = /* #__PURE__ */ DomEmitterMixin(/* #__PURE__ */ EmitterMixin());
-export function DomEmitterMixin(base) {
-    if (!base) {
-        return defaultEmitterClass;
-    }
-    class Mixin extends base {
-        listenTo(emitter, event, callback, options = {}) {
-            // Check if emitter is an instance of DOM Node. If so, use corresponding ProxyEmitter (or create one if not existing).
-            if (isNode(emitter) || isWindow(emitter) || emitter instanceof global.window.EventTarget) {
-                const proxyOptions = {
-                    capture: !!options.useCapture,
-                    passive: !!options.usePassive
-                };
-                const proxyEmitter = this._getProxyEmitter(emitter, proxyOptions) || new ProxyEmitter(emitter, proxyOptions);
-                this.listenTo(proxyEmitter, event, callback, options);
-            }
-            else {
-                // Execute parent class method with Emitter (or ProxyEmitter) instance.
-                super.listenTo(emitter, event, callback, options);
-            }
-        }
-        stopListening(emitter, event, callback) {
-            // Check if the emitter is an instance of DOM Node. If so, forward the call to the corresponding ProxyEmitters.
-            if (isNode(emitter) || isWindow(emitter) || emitter instanceof global.window.EventTarget) {
-                const proxyEmitters = this._getAllProxyEmitters(emitter);
-                for (const proxy of proxyEmitters) {
-                    this.stopListening(proxy, event, callback);
-                }
-            }
-            else {
-                // Execute parent class method with Emitter (or ProxyEmitter) instance.
-                super.stopListening(emitter, event, callback);
-            }
-        }
-        /**
-         * Retrieves ProxyEmitter instance for given DOM Node residing in this Host and given options.
-         *
-         * @param node DOM Node of the ProxyEmitter.
-         * @param options Additional options.
-         * @param options.useCapture Indicates that events of this type will be dispatched to the registered
-         * listener before being dispatched to any EventTarget beneath it in the DOM tree.
-         * @param options.usePassive Indicates that the function specified by listener will never call preventDefault()
-         * and prevents blocking browser's main thread by this event handler.
-         * @returns ProxyEmitter instance bound to the DOM Node.
-         */
-        _getProxyEmitter(node, options) {
-            return _getEmitterListenedTo(this, getProxyEmitterId(node, options));
-        }
-        /**
-         * Retrieves all the ProxyEmitter instances for given DOM Node residing in this Host.
-         *
-         * @param node DOM Node of the ProxyEmitter.
-         */
-        _getAllProxyEmitters(node) {
-            return [
-                { capture: false, passive: false },
-                { capture: false, passive: true },
-                { capture: true, passive: false },
-                { capture: true, passive: true }
-            ].map(options => this._getProxyEmitter(node, options)).filter(proxy => !!proxy);
-        }
-    }
-    return Mixin;
-}
-/**
- * Creates a ProxyEmitter instance. Such an instance is a bridge between a DOM Node firing events
- * and any Host listening to them. It is backwards compatible with {@link module:utils/emittermixin~Emitter#on}.
- * There is a separate instance for each combination of modes (useCapture & usePassive). The mode is concatenated with
- * UID stored in HTMLElement to give each instance unique identifier.
- *
- *                                  listenTo( click, ... )
- *                    +-----------------------------------------+
- *                    |              stopListening( ... )       |
- *     +----------------------------+                           |             addEventListener( click, ... )
- *     | Host                       |                           |   +---------------------------------------------+
- *     +----------------------------+                           |   |       removeEventListener( click, ... )     |
- *     | _listeningTo: {            |                +----------v-------------+                                   |
- *     |   UID+mode: {              |                | ProxyEmitter           |                                   |
- *     |     emitter: ProxyEmitter, |                +------------------------+                      +------------v----------+
- *     |     callbacks: {           |                | events: {              |                      | Node (HTMLElement)    |
- *     |       click: [ callbacks ] |                |   click: [ callbacks ] |                      +-----------------------+
- *     |     }                      |                | },                     |                      | data-ck-expando: UID  |
- *     |   }                        |                | _domNode: Node,        |                      +-----------------------+
- *     | }                          |                | _domListeners: {},     |                                   |
- *     | +------------------------+ |                | _emitterId: UID+mode   |                                   |
- *     | | DomEmitterMixin        | |                +--------------^---------+                                   |
- *     | +------------------------+ |                           |   |                                             |
- *     +--------------^-------------+                           |   +---------------------------------------------+
- *                    |                                         |                  click (DOM Event)
- *                    +-----------------------------------------+
- *                                fire( click, DOM Event )
- */
-class ProxyEmitter extends /* #__PURE__ */ EmitterMixin() {
-    _domNode;
-    _options;
-    /**
-     * @param node DOM Node that fires events.
-     * @param options Additional options.
-     * @param options.useCapture Indicates that events of this type will be dispatched to the registered
-     * listener before being dispatched to any EventTarget beneath it in the DOM tree.
-     * @param options.usePassive Indicates that the function specified by listener will never call preventDefault()
-     * and prevents blocking browser's main thread by this event handler.
-     */
-    constructor(node, options) {
-        super();
-        // Set emitter ID to match DOM Node "expando" property.
-        _setEmitterId(this, getProxyEmitterId(node, options));
-        // Remember the DOM Node this ProxyEmitter is bound to.
-        this._domNode = node;
-        // And given options.
-        this._options = options;
-    }
-    /**
-     * Collection of native DOM listeners.
-     */
-    _domListeners;
-    /**
-     * Registers a callback function to be executed when an event is fired.
-     *
-     * It attaches a native DOM listener to the DOM Node. When fired,
-     * a corresponding Emitter event will also fire with DOM Event object as an argument.
-     *
-     * **Note**: This is automatically called by the
-     * {@link module:utils/emittermixin~Emitter#listenTo `Emitter#listenTo()`}.
-     *
-     * @param event The name of the event.
-     */
-    attach(event) {
-        // If the DOM Listener for given event already exist it is pointless
-        // to attach another one.
-        if (this._domListeners && this._domListeners[event]) {
-            return;
-        }
-        const domListener = this._createDomListener(event);
-        // Attach the native DOM listener to DOM Node.
-        this._domNode.addEventListener(event, domListener, this._options);
-        if (!this._domListeners) {
-            this._domListeners = {};
-        }
-        // Store the native DOM listener in this ProxyEmitter. It will be helpful
-        // when stopping listening to the event.
-        this._domListeners[event] = domListener;
-    }
-    /**
-     * Stops executing the callback on the given event.
-     *
-     * **Note**: This is automatically called by the
-     * {@link module:utils/emittermixin~Emitter#stopListening `Emitter#stopListening()`}.
-     *
-     * @param event The name of the event.
-     */
-    detach(event) {
-        let events;
-        // Remove native DOM listeners which are orphans. If no callbacks
-        // are awaiting given event, detach native DOM listener from DOM Node.
-        // See: {@link attach}.
-        if (this._domListeners[event] && (!(events = this._events[event]) || !events.callbacks.length)) {
-            this._domListeners[event].removeListener();
-        }
-    }
-    /**
-     * Adds callback to emitter for given event.
-     *
-     * @internal
-     * @param event The name of the event.
-     * @param callback The function to be called on event.
-     * @param options Additional options.
-     */
-    _addEventListener(event, callback, options) {
-        this.attach(event);
-        EmitterMixin().prototype._addEventListener.call(this, event, callback, options);
-    }
-    /**
-     * Removes callback from emitter for given event.
-     *
-     * @internal
-     * @param event The name of the event.
-     * @param callback The function to stop being called.
-     */
-    _removeEventListener(event, callback) {
-        EmitterMixin().prototype._removeEventListener.call(this, event, callback);
-        this.detach(event);
-    }
-    /**
-     * Creates a native DOM listener callback. When the native DOM event
-     * is fired it will fire corresponding event on this ProxyEmitter.
-     * Note: A native DOM Event is passed as an argument.
-     *
-     * @param event The name of the event.
-     * @returns The DOM listener callback.
-     */
-    _createDomListener(event) {
-        const domListener = (domEvt) => {
-            this.fire(event, domEvt);
-        };
-        // Supply the DOM listener callback with a function that will help
-        // detach it from the DOM Node, when it is no longer necessary.
-        // See: {@link detach}.
-        domListener.removeListener = () => {
-            this._domNode.removeEventListener(event, domListener, this._options);
-            delete this._domListeners[event];
-        };
-        return domListener;
-    }
-}
-/**
- * Gets an unique DOM Node identifier. The identifier will be set if not defined.
- *
- * @returns UID for given DOM Node.
- */
-function getNodeUID(node) {
-    return node['data-ck-expando'] || (node['data-ck-expando'] = uid());
-}
-/**
- * Gets id of the ProxyEmitter for the given node.
- */
-function getProxyEmitterId(node, options) {
-    let id = getNodeUID(node);
-    for (const option of Object.keys(options).sort()) {
-        if (options[option]) {
-            id += '-' + option;
-        }
-    }
-    return id;
-}

package/src/dom/findclosestscrollableancestor.js

@@ -1,31 +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/findclosestscrollableancestor
- */
-import { global } from './global.js';
-/**
- * Returns the closest scrollable ancestor of a DOM element.
- *
- * @param domElement DOM element.
- * @returns First ancestor of `domElement` that is scrollable or null if such ancestor doesn't exist.
- */
-export function findClosestScrollableAncestor(domElement) {
-    let element = domElement.parentElement;
-    if (!element) {
-        return null;
-    }
-    while (element.tagName != 'BODY') {
-        const overflow = element.style.overflowY || global.window.getComputedStyle(element).overflowY;
-        if (overflow === 'auto' || overflow === 'scroll') {
-            break;
-        }
-        element = element.parentElement;
-        if (!element) {
-            return null;
-        }
-    }
-    return element;
-}

package/src/dom/getancestors.js

@@ -1,26 +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/getancestors
- */
-/**
- * Returns all ancestors of given DOM node, starting from the top-most (root). Includes the given node itself. If the
- * node is a part of `DocumentFragment` that `DocumentFragment` will be returned. In contrary, if the node is
- * appended to a `Document`, that `Document` will not be returned (algorithms operating on DOM tree care for `Document#documentElement`
- * at most, which will be returned).
- *
- * @param node DOM node.
- * @returns Array of given `node` parents.
- */
-export function getAncestors(node) {
-    const nodes = [];
-    let currentNode = node;
-    // We are interested in `Node`s `DocumentFragment`s only.
-    while (currentNode && currentNode.nodeType != Node.DOCUMENT_NODE) {
-        nodes.unshift(currentNode);
-        currentNode = currentNode.parentNode;
-    }
-    return nodes;
-}

package/src/dom/getborderwidths.js

@@ -1,24 +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/getborderwidths
- */
-/**
- * Returns an object containing CSS border widths of a specified HTML element.
- *
- * @param element An element which has CSS borders.
- * @returns An object containing `top`, `left`, `right` and `bottom` properties
- * with numerical values of the `border-[top,left,right,bottom]-width` CSS styles.
- */
-export function getBorderWidths(element) {
-    // Call getComputedStyle on the window the element document belongs to.
-    const style = element.ownerDocument.defaultView.getComputedStyle(element);
-    return {
-        top: parseInt(style.borderTopWidth, 10),
-        right: parseInt(style.borderRightWidth, 10),
-        bottom: parseInt(style.borderBottomWidth, 10),
-        left: parseInt(style.borderLeftWidth, 10)
-    };
-}

package/src/dom/getcommonancestor.js

@@ -1,25 +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/getcommonancestor
- */
-import { getAncestors } from './getancestors.js';
-/**
- * Searches and returns the lowest common ancestor of two given nodes.
- *
- * @param nodeA First node.
- * @param nodeB Second node.
- * @returns Lowest common ancestor of both nodes or `null` if nodes do not have a common ancestor.
- */
-export function getCommonAncestor(nodeA, nodeB) {
-    const ancestorsA = getAncestors(nodeA);
-    const ancestorsB = getAncestors(nodeB);
-    let i = 0;
-    // It does not matter which array is shorter.
-    while (ancestorsA[i] == ancestorsB[i] && ancestorsA[i]) {
-        i++;
-    }
-    return i === 0 ? null : ancestorsA[i - 1];
-}

package/src/dom/getdatafromelement.js

@@ -1,19 +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/getdatafromelement
- */
-/**
- * Gets data from a given source element.
- *
- * @param el The element from which the data will be retrieved.
- * @returns The data string.
- */
-export function getDataFromElement(el) {
-    if (el instanceof HTMLTextAreaElement) {
-        return el.value;
-    }
-    return el.innerHTML;
-}

package/src/dom/getpositionedancestor.js

@@ -1,22 +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/getpositionedancestor
- */
-import { global } from './global.js';
-/**
- * For a given element, returns the nearest ancestor element which CSS position is not "static".
- *
- * @param element The native DOM element to be checked.
- */
-export function getPositionedAncestor(element) {
-    if (!element || !element.parentNode) {
-        return null;
-    }
-    if (element.offsetParent === global.document.body) {
-        return null;
-    }
-    return element.offsetParent;
-}

package/src/dom/getrangefrommouseevent.js

@@ -1,33 +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/getrangefrommouseevent
- */
-/**
- * Returns a DOM range from a given point specified by a mouse event.
- *
- * @param domEvent The mouse event.
- * @returns The DOM range.
- */
-export function getRangeFromMouseEvent(domEvent) {
-    if (!domEvent.target) {
-        return null;
-    }
-    const domDoc = domEvent.target.ownerDocument;
-    const x = domEvent.clientX;
-    const y = domEvent.clientY;
-    let domRange = null;
-    // Webkit & Blink.
-    if (domDoc.caretRangeFromPoint && domDoc.caretRangeFromPoint(x, y)) {
-        domRange = domDoc.caretRangeFromPoint(x, y);
-    }
-    // FF.
-    else if (domEvent.rangeParent) {
-        domRange = domDoc.createRange();
-        domRange.setStart(domEvent.rangeParent, domEvent.rangeOffset);
-        domRange.collapse(true);
-    }
-    return domRange;
-}

package/src/dom/getvisualviewportoffset.js

@@ -1,21 +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/getvisualviewportoffset
- */
-import { global } from './global.js';
-import { env } from '../env.js';
-/**
- * Returns the visual viewport offsets to adjust elements with `position: fixed` style.
- */
-export function getVisualViewportOffset() {
-    const visualViewport = global.window.visualViewport;
-    if (!visualViewport || !(env.isiOS || env.isSafari)) {
-        return { left: 0, top: 0 };
-    }
-    const left = Math.max(Math.round(visualViewport.offsetLeft), 0);
-    const top = Math.max(Math.round(visualViewport.offsetTop), 0);
-    return { left, top };
-}

package/src/dom/global.js

@@ -1,35 +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
- */
-/**
- * A helper (module) giving an access to the global DOM objects such as `window` and
- * `document`. Accessing these objects using this helper allows easy and bulletproof
- * testing, i.e. stubbing native properties:
- *
- * ```ts
- * import { global } from 'ckeditor5/utils';
- *
- * // This stub will work for any code using global module.
- * testUtils.sinon.stub( global, 'window', {
- * 	innerWidth: 10000
- * } );
- *
- * console.log( global.window.innerWidth );
- * ```
- */
-let globalVar; // named globalVar instead of global: https://github.com/ckeditor/ckeditor5/issues/12971
-// In some environments window and document API might not be available.
-try {
-    globalVar = { window, document };
-}
-catch {
-    // It's not possible to mock a window object to simulate lack of a window object without writing extremely convoluted code.
-    /* istanbul ignore next -- @preserve */
-    // Let's cast it to not change module's API.
-    // We only handle this so loading editor in environments without window and document doesn't fail.
-    // For better DX we shouldn't introduce mixed types and require developers to check the type manually.
-    // This module should not be used on purpose in any environment outside browser.
-    globalVar = { window: {}, document: {} };
-}
-export { globalVar as global };

package/src/dom/indexof.js

@@ -1,21 +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/indexof
- */
-/**
- * Returns index of the node in the parent element.
- *
- * @param node Node which index is tested.
- * @returns Index of the node in the parent element. Returns 0 if node has no parent.
- */
-export function indexOf(node) {
-    let index = 0;
-    while (node.previousSibling) {
-        node = node.previousSibling;
-        index++;
-    }
-    return index;
-}

package/src/dom/insertat.js

@@ -1,17 +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/insertat
- */
-/**
- * Inserts node to the parent at given index.
- *
- * @param parentElement Parent element.
- * @param index Insertions index.
- * @param nodeToInsert Node to insert.
- */
-export function insertAt(parentElement, index, nodeToInsert) {
-    parentElement.insertBefore(nodeToInsert, parentElement.childNodes[index] || null);
-}

package/src/dom/iscomment.js

@@ -1,13 +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/iscomment
- */
-/**
- * Checks whether the object is a native DOM Comment node.
- */
-export function isComment(obj) {
-    return obj && obj.nodeType === Node.COMMENT_NODE;
-}

package/src/dom/isnode.js

@@ -1,21 +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/isnode
- */
-/**
- * Checks if the object is a native DOM Node.
- */
-export function isNode(obj) {
-    if (obj) {
-        if (obj.defaultView) {
-            return obj instanceof obj.defaultView.Document;
-        }
-        else if (obj.ownerDocument && obj.ownerDocument.defaultView) {
-            return obj instanceof obj.ownerDocument.defaultView.Node;
-        }
-    }
-    return false;
-}

package/src/dom/isrange.js

@@ -1,13 +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/isrange
- */
-/**
- * Checks if the object is a native DOM Range.
- */
-export function isRange(obj) {
-    return Object.prototype.toString.apply(obj) == '[object Range]';
-}

package/src/dom/istext.js

@@ -1,13 +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/istext
- */
-/**
- * Checks if the object is a native DOM Text node.
- */
-export function isText(obj) {
-    return Object.prototype.toString.call(obj) == '[object Text]';
-}

package/src/dom/isvalidattributename.js

@@ -1,22 +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/isvalidattributename
- */
-import { global } from './global.js';
-/**
- * Checks if the given attribute name is valid in terms of HTML.
- *
- * @param name Attribute name.
- */
-export function isValidAttributeName(name) {
-    try {
-        global.document.createAttribute(name);
-    }
-    catch {
-        return false;
-    }
-    return true;
-}

package/src/dom/isvisible.js

@@ -1,30 +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/isvisible
- */
-import { isText } from './istext.js';
-/**
- * Checks whether the element is visible to the user in DOM:
- *
- * * connected to the root of the document,
- * * has no `display: none`,
- * * has no ancestors with `display: none`.
- *
- * **Note**: This helper does not check whether the element is hidden by cropping, overflow, etc..
- * To check that, use {@link module:utils/dom/rect~Rect} instead.
- */
-export function isVisible(element) {
-    if (!element) {
-        return false;
-    }
-    if (isText(element)) {
-        return isVisible(element.parentElement);
-    }
-    if (element.getClientRects) {
-        return !!(element.getClientRects().length);
-    }
-    return false;
-}

package/src/dom/iswindow.js

@@ -1,22 +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/iswindow
- */
-/**
- * Checks if the object is a native DOM Window.
- */
-export function isWindow(obj) {
-    const stringifiedObject = Object.prototype.toString.apply(obj);
-    // Returns `true` for the `window` object in browser environments.
-    if (stringifiedObject == '[object Window]') {
-        return true;
-    }
-    // Returns `true` for the `window` object in the Electron environment.
-    if (stringifiedObject == '[object global]') {
-        return true;
-    }
-    return false;
-}