@ckeditor/ckeditor5-utils 0.0.0-internal-20241017.0

package/src/difftochanges.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @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
+ */
+import type { DiffResult } from './diff.js';
+/**
+ * @module utils/difftochanges
+ */
+/**
+ * Creates a set of changes which need to be applied to the input in order to transform
+ * it into the output. This function can be used with strings or arrays.
+ *
+ * ```ts
+ * const input = Array.from( 'abc' );
+ * const output = Array.from( 'xaby' );
+ * const changes = diffToChanges( diff( input, output ), output );
+ *
+ * changes.forEach( change => {
+ * 	if ( change.type == 'insert' ) {
+ * 		input.splice( change.index, 0, ...change.values );
+ * 	} else if ( change.type == 'delete' ) {
+ * 		input.splice( change.index, change.howMany );
+ * 	}
+ * } );
+ *
+ * input.join( '' ) == output.join( '' ); // -> true
+ * ```
+ *
+ * @typeParam T The type of output array element.
+ * @param diff Result of {@link module:utils/diff~diff}.
+ * @param output The string or array which was passed as diff's output.
+ * @returns Set of changes (insert or delete) which need to be applied to the input
+ * in order to transform it into the output.
+ */
+export default function diffToChanges<T>(diff: ReadonlyArray<DiffResult>, output: ArrayLike<T>): Array<Change<T>>;
+/**
+ * An object describing insertion change.
+ *
+ * @typeParam T The type of output array element.
+ */
+export interface InsertChange<T> {
+    type: 'insert';
+    index: number;
+    values: Array<T>;
+}
+/**
+ * An object describing deletion change.
+ */
+export interface DeleteChange {
+    type: 'delete';
+    index: number;
+    howMany: number;
+}
+/**
+ * The element of the result of {@link module:utils/difftochanges~diffToChanges} function.
+ *
+ * @typeParam T The type of output array element.
+ */
+export type Change<T> = InsertChange<T> | DeleteChange;

package/src/difftochanges.js

@@ -0,0 +1,79 @@
+/**
+ * @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/difftochanges
+ */
+/**
+ * Creates a set of changes which need to be applied to the input in order to transform
+ * it into the output. This function can be used with strings or arrays.
+ *
+ * ```ts
+ * const input = Array.from( 'abc' );
+ * const output = Array.from( 'xaby' );
+ * const changes = diffToChanges( diff( input, output ), output );
+ *
+ * changes.forEach( change => {
+ * 	if ( change.type == 'insert' ) {
+ * 		input.splice( change.index, 0, ...change.values );
+ * 	} else if ( change.type == 'delete' ) {
+ * 		input.splice( change.index, change.howMany );
+ * 	}
+ * } );
+ *
+ * input.join( '' ) == output.join( '' ); // -> true
+ * ```
+ *
+ * @typeParam T The type of output array element.
+ * @param diff Result of {@link module:utils/diff~diff}.
+ * @param output The string or array which was passed as diff's output.
+ * @returns Set of changes (insert or delete) which need to be applied to the input
+ * in order to transform it into the output.
+ */
+export default function diffToChanges(diff, output) {
+    const changes = [];
+    let index = 0;
+    let lastOperation = null;
+    diff.forEach(change => {
+        if (change == 'equal') {
+            pushLast();
+            index++;
+        }
+        else if (change == 'insert') {
+            if (lastOperation && lastOperation.type == 'insert') {
+                lastOperation.values.push(output[index]);
+            }
+            else {
+                pushLast();
+                lastOperation = {
+                    type: 'insert',
+                    index,
+                    values: [output[index]]
+                };
+            }
+            index++;
+        }
+        else /* if ( change == 'delete' ) */ {
+            if (lastOperation && lastOperation.type == 'delete') {
+                lastOperation.howMany++;
+            }
+            else {
+                pushLast();
+                lastOperation = {
+                    type: 'delete',
+                    index,
+                    howMany: 1
+                };
+            }
+        }
+    });
+    pushLast();
+    return changes;
+    function pushLast() {
+        if (lastOperation) {
+            changes.push(lastOperation);
+            lastOperation = null;
+        }
+    }
+}

package/src/dom/createelement.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @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
+ */
+/**
+ * Attributes to be applied to the HTML element.
+ */
+type HTMLElementAttributes = {
+    readonly [key: string]: string;
+};
+/**
+ * Attributes to be applied to the SVG element.
+ */
+type SVGElementAttributes = HTMLElementAttributes & {
+    xmlns: string;
+};
+/**
+ * Element or elements that will be added to the created element as children. Strings will be automatically turned into Text nodes.
+ */
+type ChildrenElements = Node | string | Iterable<Node | string>;
+/**
+ * Creates an SVG element with attributes and children elements.
+ *
+ * ```ts
+ * createElement( document, 'mask', { xmlns: 'http://www.w3.org/2000/svg' } ); // <mask>
+ * createElement( document, 'mask', { xmlns: 'http://www.w3.org/2000/svg', id: 'foo' } ); // <mask id="foo">
+ * createElement( document, 'mask', { xmlns: 'http://www.w3.org/2000/svg' }, 'foo' ); // <mask>foo</mask>
+ * createElement( document, 'mask', { xmlns: 'http://www.w3.org/2000/svg' }, [ createElement(...) ] ); // <mask><...></mask>
+ * ```
+ *
+ * @label SVG_ELEMENT
+ * @param doc Document used to create the element.
+ * @param name Name of the SVG element.
+ * @param attributes Object where keys represent attribute keys and values represent attribute values.
+ * @param children Child or any iterable of children. Strings will be automatically turned into Text nodes.
+ * @returns SVG element.
+ */
+export default function createElement<T extends keyof SVGElementTagNameMap>(doc: Document, name: T, attributes: SVGElementAttributes, children?: ChildrenElements): SVGElementTagNameMap[T];
+/**
+ * Creates an HTML element with attributes and children elements.
+ *
+ * ```ts
+ * createElement( document, 'p' ); // <p>
+ * createElement( document, 'p', { class: 'foo' } ); // <p class="foo">
+ * createElement( document, 'p', null, 'foo' ); // <p>foo</p>
+ * createElement( document, 'p', null, [ createElement(...) ] ); // <p><...></p>
+ * ```
+ *
+ * @label HTML_ELEMENT
+ * @param doc Document used to create the element.
+ * @param name Name of the HTML element.
+ * @param attributes Object where keys represent attribute keys and values represent attribute values.
+ * @param children Child or any iterable of children. Strings will be automatically turned into Text nodes.
+ * @returns HTML element.
+ */
+export default function createElement<T extends keyof HTMLElementTagNameMap>(doc: Document, name: T, attributes?: HTMLElementAttributes, children?: ChildrenElements): HTMLElementTagNameMap[T];
+export {};

package/src/dom/createelement.js

@@ -0,0 +1,40 @@
+/**
+ * @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/createelement
+ */
+import isIterable from '../isiterable.js';
+import { isString } from 'lodash-es';
+/**
+ * Creates an HTML or SVG element with attributes and children elements.
+ *
+ * ```ts
+ * createElement( document, 'p' ); // <p>
+ * createElement( document, 'mask', { xmlns: 'http://www.w3.org/2000/svg' } ); // <mask>
+ * ```
+ *
+ * @param doc Document used to create the element.
+ * @param name Name of the element.
+ * @param attributes Object where keys represent attribute keys and values represent attribute values.
+ * @param children Child or any iterable of children. Strings will be automatically turned into Text nodes.
+ * @returns HTML or SVG element.
+ */
+export default function createElement(doc, name, attributes = {}, children = []) {
+    const namespace = attributes && attributes.xmlns;
+    const element = namespace ? doc.createElementNS(namespace, name) : doc.createElement(name);
+    for (const key in attributes) {
+        element.setAttribute(key, attributes[key]);
+    }
+    if (isString(children) || !isIterable(children)) {
+        children = [children];
+    }
+    for (let child of children) {
+        if (isString(child)) {
+            child = doc.createTextNode(child);
+        }
+        element.appendChild(child);
+    }
+    return element;
+}

package/src/dom/emittermixin.d.ts

@@ -0,0 +1,142 @@
+/**
+ * @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/emittermixin
+ */
+import { type Emitter, type CallbackOptions, type BaseEvent, type GetCallback } from '../emittermixin.js';
+import type EventInfo from '../eventinfo.js';
+import type { Constructor, Mixed } from '../mix.js';
+/**
+ * Mixin that injects the DOM events API into its host. It provides the API
+ * compatible with {@link module:utils/emittermixin~Emitter}.
+ *
+ * This function creates a class that inherits from the provided `base` and implements `Emitter` interface.
+ *
+ * DOM emitter mixin is by default available in the {@link module:ui/view~View} class,
+ * but it can also be mixed into any other class:
+ *
+ * ```ts
+ * import DomEmitterMixin from '../utils/dom/emittermixin.js';
+ *
+ * class BaseClass { ... }
+ *
+ * class SomeView extends DomEmitterMixin( BaseClass ) {}
+ *
+ * const view = new SomeView();
+ * view.listenTo( domElement, ( evt, domEvt ) => {
+ * 	console.log( evt, domEvt );
+ * } );
+ * ```
+ *
+ * @label EXTENDS
+ */
+export default function DomEmitterMixin<Base extends Constructor<Emitter>>(base: Base): Mixed<Base, DomEmitter>;
+/**
+ * Mixin that injects the DOM events API into its host. It provides the API
+ * compatible with {@link module:utils/emittermixin~Emitter}.
+ *
+ * This function creates a class that implements `Emitter` interface.
+ *
+ * DOM emitter mixin is by default available in the {@link module:ui/view~View} class,
+ * but it can also be mixed into any other class:
+ *
+ * ```ts
+ * import DomEmitterMixin from '../utils/dom/emittermixin.js';
+ *
+ * class SomeView extends DomEmitterMixin() {}
+ *
+ * const view = new SomeView();
+ * view.listenTo( domElement, ( evt, domEvt ) => {
+ * 	console.log( evt, domEvt );
+ * } );
+ * ```
+ *
+ * @label NO_ARGUMENTS
+ */
+export default function DomEmitterMixin(): {
+    new (): DomEmitter;
+    prototype: DomEmitter;
+};
+export interface DomEventMap extends HTMLElementEventMap, WindowEventMap {
+}
+/**
+ * Interface representing classes which mix in {@link module:utils/dom/emittermixin~DomEmitterMixin}.
+ *
+ * Can be easily implemented by a class by mixing the {@link module:utils/dom/emittermixin~DomEmitterMixin} mixin.
+ *
+ * ```ts
+ * class MyClass extends DomEmitterMixin( OtherBaseClass ) {
+ * 	// This class now implements the `Emitter` interface.
+ * }
+ * ```
+ */
+export interface DomEmitter extends Emitter {
+    /**
+     * Registers a callback function to be executed when an event is fired in a specific Emitter or DOM Node.
+     * It is backwards compatible with {@link module:utils/emittermixin~Emitter#listenTo}.
+     *
+     * @label HTML_EMITTER
+     * @param emitter The object that fires the event.
+     * @param event The name of the event.
+     * @param callback The function to be called on event.
+     * @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.
+     */
+    listenTo<K extends keyof DomEventMap>(emitter: Node | Window, event: K, callback: (this: this, ev: EventInfo, event: DomEventMap[K]) => void, options?: CallbackOptions & {
+        readonly useCapture?: boolean;
+        readonly usePassive?: boolean;
+    }): void;
+    /**
+     * Registers a callback function to be executed when an event is fired in a specific (emitter) object.
+     *
+     * Events can be grouped in namespaces using `:`.
+     * When namespaced event is fired, it additionally fires all callbacks for that namespace.
+     *
+     * ```ts
+     * // myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
+     * myEmitter.on( 'myGroup', genericCallback );
+     * myEmitter.on( 'myGroup:myEvent', specificCallback );
+     *
+     * // genericCallback is fired.
+     * myEmitter.fire( 'myGroup' );
+     * // both genericCallback and specificCallback are fired.
+     * myEmitter.fire( 'myGroup:myEvent' );
+     * // genericCallback is fired even though there are no callbacks for "foo".
+     * myEmitter.fire( 'myGroup:foo' );
+     * ```
+     *
+     * An event callback can {@link module:utils/eventinfo~EventInfo#stop stop the event} and
+     * set the {@link module:utils/eventinfo~EventInfo#return return value} of the {@link #fire} method.
+     *
+     * @label DOM_EMITTER
+     * @typeParam TEvent The type describing the event. See {@link module:utils/emittermixin~BaseEvent}.
+     * @param emitter The object that fires the event.
+     * @param event The name of the event.
+     * @param callback The function to be called on event.
+     * @param options Additional options.
+     */
+    listenTo<TEvent extends BaseEvent>(emitter: Emitter, event: TEvent['name'], callback: GetCallback<TEvent>, options?: CallbackOptions): void;
+    /**
+     * Stops listening for events. It can be used at different levels:
+     * It is backwards compatible with {@link module:utils/emittermixin~Emitter#listenTo}.
+     *
+     * * To stop listening to a specific callback.
+     * * To stop listening to a specific event.
+     * * To stop listening to all events fired by a specific object.
+     * * To stop listening to all events fired by all objects.
+     *
+     * @label DOM_STOP
+     * @param emitter The object to stop listening to.
+     * If omitted, stops it for all objects.
+     * @param event (Requires the `emitter`) The name of the event to stop listening to. If omitted, stops it
+     * for all events from `emitter`.
+     * @param callback (Requires the `event`) The function to be removed from the call list for the given
+     * `event`.
+     */
+    stopListening(emitter?: Emitter | Node | Window, event?: string, callback?: Function): void;
+}

package/src/dom/emittermixin.js

@@ -0,0 +1,239 @@
+/**
+ * @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/emittermixin
+ */
+import EmitterMixin, { _getEmitterListenedTo, _setEmitterId } from '../emittermixin.js';
+import uid from '../uid.js';
+import isNode from './isnode.js';
+import isWindow from './iswindow.js';
+const defaultEmitterClass = /* #__PURE__ */ DomEmitterMixin(/* #__PURE__ */ EmitterMixin());
+export default 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)) {
+                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)) {
+                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;
+}
+// Backward compatibility with `mix`
+([
+    '_getProxyEmitter', '_getAllProxyEmitters',
+    'on', 'once', 'off', 'listenTo',
+    'stopListening', 'fire', 'delegate', 'stopDelegating',
+    '_addEventListener', '_removeEventListener'
+]).forEach(key => {
+    DomEmitterMixin[key] = defaultEmitterClass.prototype[key];
+});
+/**
+ * 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() {
+    /**
+     * @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;
+    }
+    /**
+     * 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.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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
+ */
+/**
+ * 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 default function findClosestScrollableAncestor(domElement: HTMLElement): HTMLElement | null;

package/src/dom/findclosestscrollableancestor.js

@@ -0,0 +1,31 @@
+/**
+ * @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/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 default 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.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @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/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 default function getAncestors(node: Node): Array<Node>;