@ckeditor/ckeditor5-utils 34.2.0 → 35.0.0

package/src/dom/emittermixin.js

@@ -1,341 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module utils/dom/emittermixin
- */
-
-import { default as EmitterMixin, _getEmitterListenedTo, _setEmitterId } from '../emittermixin';
-import uid from '../uid';
-import isNode from './isnode';
-import isWindow from './iswindow';
-import { extend } from 'lodash-es';
-
-/**
- * Mixin that injects the DOM events API into its host. It provides the API
- * compatible with {@link module:utils/emittermixin~EmitterMixin}.
- *
- * 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:
- *
- *		import mix from '../utils/mix.js';
- *		import DomEmitterMixin from '../utils/dom/emittermixin.js';
- *
- *		class SomeView {}
- *		mix( SomeView, DomEmitterMixin );
- *
- *		const view = new SomeView();
- *		view.listenTo( domElement, ( evt, domEvt ) => {
- *			console.log( evt, domEvt );
- *		} );
- *
- * @mixin EmitterMixin
- * @mixes module:utils/emittermixin~EmitterMixin
- * @implements module:utils/dom/emittermixin~Emitter
- */
-const DomEmitterMixin = extend( {}, EmitterMixin, {
-	/**
-	 * 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~EmitterMixin#listenTo}.
-	 *
-	 * @param {module:utils/emittermixin~Emitter|Node} emitter The object that fires the event.
-	 * @param {String} event The name of the event.
-	 * @param {Function} callback The function to be called on event.
-	 * @param {Object} [options={}] Additional options.
-	 * @param {module:utils/priorities~PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
-	 * the priority value the sooner the callback will be fired. Events having the same priority are called in the
-	 * order they were added.
-	 * @param {Boolean} [options.useCapture=false] 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 {Boolean} [options.usePassive=false] Indicates that the function specified by listener will never call preventDefault()
-	 * and prevents blocking browser's main thread by this event handler.
-	 */
-	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.
-			EmitterMixin.listenTo.call( this, emitter, event, callback, options );
-		}
-	},
-
-	/**
-	 * Stops listening for events. It can be used at different levels:
-	 * It is backwards compatible with {@link module:utils/emittermixin~EmitterMixin#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 object.
-	 *
-	 * @param {module:utils/emittermixin~Emitter|Node} [emitter] The object to stop listening to. If omitted, stops it for all objects.
-	 * @param {String} [event] (Requires the `emitter`) The name of the event to stop listening to. If omitted, stops it
-	 * for all events from `emitter`.
-	 * @param {Function} [callback] (Requires the `event`) The function to be removed from the call list for the given
-	 * `event`.
-	 */
-	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.
-			EmitterMixin.stopListening.call( this, emitter, event, callback );
-		}
-	},
-
-	/**
-	 * Retrieves ProxyEmitter instance for given DOM Node residing in this Host and given options.
-	 *
-	 * @private
-	 * @param {Node} node DOM Node of the ProxyEmitter.
-	 * @param {Object} [options] Additional options.
-	 * @param {Boolean} [options.useCapture=false] 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 {Boolean} [options.usePassive=false] Indicates that the function specified by listener will never call preventDefault()
-	 * and prevents blocking browser's main thread by this event handler.
-	 * @returns {module:utils/dom/emittermixin~ProxyEmitter|null} 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.
-	 *
-	 * @private
-	 * @param {Node} node DOM Node of the ProxyEmitter.
-	 * @returns {Array.<module:utils/dom/emittermixin~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 );
-	}
-} );
-
-export default DomEmitterMixin;
-
-/**
- * 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~EmitterMixin#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 )
- *
- * @mixes module:utils/emittermixin~EmitterMixin
- * @implements module:utils/dom/emittermixin~Emitter
- * @private
- */
-class ProxyEmitter {
-	/**
-	 * @param {Node} node DOM Node that fires events.
-	 * @param {Object} [options] Additional options.
-	 * @param {Boolean} [options.useCapture=false] 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 {Boolean} [options.usePassive=false] 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 ) {
-		// 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;
-	}
-}
-
-extend( ProxyEmitter.prototype, EmitterMixin, {
-	/**
-	 * Collection of native DOM listeners.
-	 *
-	 * @private
-	 * @member {Object} module:utils/dom/emittermixin~ProxyEmitter#_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~EmitterMixin#listenTo `EmitterMixin#listenTo()`}.
-	 *
-	 * @method module:utils/dom/emittermixin~ProxyEmitter#attach
-	 * @param {String} 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~EmitterMixin#stopListening `EmitterMixin#stopListening()`}.
-	 *
-	 * @method module:utils/dom/emittermixin~ProxyEmitter#detach
-	 * @param {String} 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.
-	 *
-	 * @protected
-	 * @method module:utils/dom/emittermixin~ProxyEmitter#_addEventListener
-	 * @param {String} event The name of the event.
-	 * @param {Function} callback The function to be called on event.
-	 * @param {Object} [options={}] Additional options.
-	 * @param {module:utils/priorities~PriorityString|Number} [options.priority='normal'] The priority of this event callback. The higher
-	 * the priority value the sooner the callback will be fired. Events having the same priority are called in the
-	 * order they were added.
-	 */
-	_addEventListener( event, callback, options ) {
-		this.attach( event );
-		EmitterMixin._addEventListener.call( this, event, callback, options );
-	},
-
-	/**
-	 * Removes callback from emitter for given event.
-	 *
-	 * @protected
-	 * @method module:utils/dom/emittermixin~ProxyEmitter#_removeEventListener
-	 * @param {String} event The name of the event.
-	 * @param {Function} callback The function to stop being called.
-	 */
-	_removeEventListener( event, callback ) {
-		EmitterMixin._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.
-	 *
-	 * @private
-	 * @method module:utils/dom/emittermixin~ProxyEmitter#_createDomListener
-	 * @param {String} event The name of the event.
-	 * @returns {Function} 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.
-//
-// @private
-// @param {Node} node
-// @returns {String} 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.
-//
-// Combines DOM Node identifier and additional options.
-//
-// @private
-// @param {Node} node
-// @param {Object} options Additional options.
-// @returns {String} ProxyEmitter id.
-function getProxyEmitterId( node, options ) {
-	let id = getNodeUID( node );
-
-	for ( const option of Object.keys( options ).sort() ) {
-		if ( options[ option ] ) {
-			id += '-' + option;
-		}
-	}
-
-	return id;
-}
-
-/**
- * Interface representing classes which mix in {@link module:utils/dom/emittermixin~EmitterMixin}.
- *
- * @interface Emitter
- */

package/src/dom/getancestors.js

@@ -1,31 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/* globals Node */
-
-/**
- * @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} node DOM node.
- * @returns {Array.<Node|DocumentFragment>} Array of given `node` parents.
- */
-export default function getAncestors( node ) {
-	const nodes = [];
-
-	// We are interested in `Node`s `DocumentFragment`s only.
-	while ( node && node.nodeType != Node.DOCUMENT_NODE ) {
-		nodes.unshift( node );
-		node = node.parentNode;
-	}
-
-	return nodes;
-}

package/src/dom/getborderwidths.js

@@ -1,27 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module utils/dom/getborderwidths
- */
-
-/**
- * Returns an object containing CSS border widths of a specified HTML element.
- *
- * @param {HTMLElement} element An element which has CSS borders.
- * @returns {Object} An object containing `top`, `left`, `right` and `bottom` properties
- * with numerical values of the `border-[top,left,right,bottom]-width` CSS styles.
- */
-export default 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,31 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module utils/dom/getcommonancestor
- */
-
-import getAncestors from './getancestors';
-
-/**
- * Searches and returns the lowest common ancestor of two given nodes.
- *
- * @param {Node} nodeA First node.
- * @param {Node} nodeB Second node.
- * @returns {Node|DocumentFragment|Document|null} Lowest common ancestor of both nodes or `null` if nodes do not have a common ancestor.
- */
-export default 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,24 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/* globals HTMLTextAreaElement */
-
-/**
- * @module utils/dom/getdatafromelement
- */
-
-/**
- * Gets data from a given source element.
- *
- * @param {HTMLElement} el The element from which the data will be retrieved.
- * @returns {String} The data string.
- */
-export default function getDataFromElement( el ) {
-	if ( el instanceof HTMLTextAreaElement ) {
-		return el.value;
-	}
-
-	return el.innerHTML;
-}

package/src/dom/getpositionedancestor.js

@@ -1,28 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module utils/dom/getpositionedancestor
- */
-
-import global from './global';
-
-/**
- * For a given element, returns the nearest ancestor element which CSS position is not "static".
- *
- * @param {HTMLElement} element The native DOM element to be checked.
- * @returns {HTMLElement|null}
- */
-export default function getPositionedAncestor( element ) {
-	if ( !element || !element.parentNode ) {
-		return null;
-	}
-
-	if ( element.offsetParent === global.document.body ) {
-		return null;
-	}
-
-	return element.offsetParent;
-}

package/src/dom/global.js

@@ -1,26 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/* globals window, document */
-
-/**
- * @module utils/dom/global
- */
-
-/**
- * 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:
- *
- *		import global from 'ckeditor5/utils/dom/global.js';
- *
- *		// This stub will work for any code using global module.
- *		testUtils.sinon.stub( global, 'window', {
- *			innerWidth: 10000
- *		} );
- *
- *		console.log( global.window.innerWidth );
- */
-export default { window, document };

package/src/dom/indexof.js

@@ -1,25 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module utils/dom/indexof
- */
-
-/**
- * Returns index of the node in the parent element.
- *
- * @param {Node} node Node which index is tested.
- * @returns {Number} Index of the node in the parent element. Returns 0 if node has no parent.
- */
-export default function indexOf( node ) {
-	let index = 0;
-
-	while ( node.previousSibling ) {
-		node = node.previousSibling;
-		index++;
-	}
-
-	return index;
-}

package/src/dom/insertat.js

@@ -1,19 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module utils/dom/insertat
- */
-
-/**
- * Inserts node to the parent at given index.
- *
- * @param {Element} parentElement Parent element.
- * @param {Number} index Insertions index.
- * @param {Node} nodeToInsert Node to insert.
- */
-export default function insertAt( parentElement, index, nodeToInsert ) {
-	parentElement.insertBefore( nodeToInsert, parentElement.childNodes[ index ] || null );
-}

package/src/dom/iscomment.js

@@ -1,20 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/* globals Node */
-
-/**
- * @module utils/dom/iscomment
- */
-
-/**
- * Checks whether the object is a native DOM Comment node.
- *
- * @param {*} obj
- * @returns {Boolean}
- */
-export default function isComment( obj ) {
-	return obj && obj.nodeType === Node.COMMENT_NODE;
-}

package/src/dom/isnode.js

@@ -1,26 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module utils/dom/isnode
- */
-
-/**
- * Checks if the object is a native DOM Node.
- *
- * @param {*} obj
- * @returns {Boolean}
- */
-export default 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,18 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module utils/dom/isrange
- */
-
-/**
- * Checks if the object is a native DOM Range.
- *
- * @param {*} obj
- * @returns {Boolean}
- */
-export default function isRange( obj ) {
-	return Object.prototype.toString.apply( obj ) == '[object Range]';
-}

package/src/dom/istext.js

@@ -1,18 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module utils/dom/istext
- */
-
-/**
- * Checks if the object is a native DOM Text node.
- *
- * @param {*} obj
- * @returns {Boolean}
- */
-export default function isText( obj ) {
-	return Object.prototype.toString.call( obj ) == '[object Text]';
-}

package/src/dom/isvisible.js

@@ -1,25 +0,0 @@
-/**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-
-/**
- * @module utils/dom/isvisible
- */
-
-/**
- * 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.
- *
- * @param {HTMLElement|null|undefined} element
- * @returns {Boolean}
- */
-export default function isVisible( element ) {
-	return !!( element && element.getClientRects && element.getClientRects().length );
-}