@ckeditor/ckeditor5-utils 35.3.2 → 35.4.0

package/src/dom/global.js

@@ -2,23 +2,21 @@
  * @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';
+ * ```ts
+ * import { global } from 'ckeditor5/utils';
  *
- *		// This stub will work for any code using global module.
- *		testUtils.sinon.stub( global, 'window', {
- *			innerWidth: 10000
- *		} );
+ * // This stub will work for any code using global module.
+ * testUtils.sinon.stub( global, 'window', {
+ * 	innerWidth: 10000
+ * } );
  *
- *		console.log( global.window.innerWidth );
+ * console.log( global.window.innerWidth );
+ * ```
  */
 let global;
 // In some environments window and document API might not be available.

package/src/dom/indexof.js

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

package/src/dom/insertat.js

@@ -8,9 +8,9 @@
 /**
  * Inserts node to the parent at given index.
  *
- * @param {Element} parentElement Parent element.
- * @param {Number} index Insertions index.
- * @param {Node} nodeToInsert Node to insert.
+ * @param parentElement Parent element.
+ * @param index Insertions index.
+ * @param nodeToInsert Node to insert.
  */
 export default function insertAt(parentElement, index, nodeToInsert) {
     parentElement.insertBefore(nodeToInsert, parentElement.childNodes[index] || null);

package/src/dom/iscomment.js

@@ -8,9 +8,6 @@
  */
 /**
  * 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

@@ -7,9 +7,6 @@
  */
 /**
  * Checks if the object is a native DOM Node.
- *
- * @param {*} obj
- * @returns {Boolean}
  */
 export default function isNode(obj) {
     if (obj) {

package/src/dom/isrange.js

@@ -7,9 +7,6 @@
  */
 /**
  * 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

@@ -7,9 +7,6 @@
  */
 /**
  * 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

@@ -14,9 +14,6 @@
  *
  * **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);

package/src/dom/iswindow.js

@@ -7,9 +7,6 @@
  */
 /**
  * Checks if the object is a native DOM Window.
- *
- * @param {*} obj
- * @returns {Boolean}
  */
 export default function isWindow(obj) {
     const stringifiedObject = Object.prototype.toString.apply(obj);

package/src/dom/position.js

@@ -10,70 +10,71 @@ import Rect from './rect';
 import getPositionedAncestor from './getpositionedancestor';
 import getBorderWidths from './getborderwidths';
 import { isFunction } from 'lodash-es';
-// @if CK_DEBUG_POSITION // import { RectDrawer } from '@ckeditor/ckeditor5-minimap/src/utils';
+// @if CK_DEBUG_POSITION // const { RectDrawer } = require( '@ckeditor/ckeditor5-minimap/src/utils' );
 /**
  * Calculates the `position: absolute` coordinates of a given element so it can be positioned with respect to the
  * target in the visually most efficient way, taking various restrictions like viewport or limiter geometry
  * into consideration.
  *
- *		// The element which is to be positioned.
- *		const element = document.body.querySelector( '#toolbar' );
+ * ```ts
+ * // The element which is to be positioned.
+ * const element = document.body.querySelector( '#toolbar' );
  *
- *		// A target to which the element is positioned relatively.
- *		const target = document.body.querySelector( '#container' );
+ * // A target to which the element is positioned relatively.
+ * const target = document.body.querySelector( '#container' );
  *
- *		// Finding the optimal coordinates for the positioning.
- *		const { left, top, name } = getOptimalPosition( {
- *			element: element,
- *			target: target,
+ * // Finding the optimal coordinates for the positioning.
+ * const { left, top, name } = getOptimalPosition( {
+ * 	element: element,
+ * 	target: target,
  *
- * 			// The algorithm will chose among these positions to meet the requirements such
- * 			// as "limiter" element or "fitInViewport", set below. The positions are considered
- * 			// in the order of the array.
- *			positions: [
- *				//
- *			 	//	[ Target ]
- *				//	+-----------------+
- *				//	|     Element     |
- *				//	+-----------------+
- *				//
- *				targetRect => ( {
- *					top: targetRect.bottom,
- *					left: targetRect.left,
- *					name: 'mySouthEastPosition'
- *				} ),
+ * 	// The algorithm will chose among these positions to meet the requirements such
+ * 	// as "limiter" element or "fitInViewport", set below. The positions are considered
+ * 	// in the order of the array.
+ * 	positions: [
+ * 		//
+ * 	 	//	[ Target ]
+ * 		//	+-----------------+
+ * 		//	|     Element     |
+ * 		//	+-----------------+
+ * 		//
+ * 		targetRect => ( {
+ * 			top: targetRect.bottom,
+ * 			left: targetRect.left,
+ * 			name: 'mySouthEastPosition'
+ * 		} ),
  *
- *				//
- *				//	+-----------------+
- *				//	|     Element     |
- *				//	+-----------------+
- *				//	[ Target ]
- *				//
- *				( targetRect, elementRect ) => ( {
- *					top: targetRect.top - elementRect.height,
- *					left: targetRect.left,
- *					name: 'myNorthEastPosition'
- *				} )
- *			],
+ * 		//
+ * 		//	+-----------------+
+ * 		//	|     Element     |
+ * 		//	+-----------------+
+ * 		//	[ Target ]
+ * 		//
+ * 		( targetRect, elementRect ) => ( {
+ * 			top: targetRect.top - elementRect.height,
+ * 			left: targetRect.left,
+ * 			name: 'myNorthEastPosition'
+ * 		} )
+ * 	],
  *
- *			// Find a position such guarantees the element remains within visible boundaries of <body>.
- *			limiter: document.body,
+ * 	// Find a position such guarantees the element remains within visible boundaries of <body>.
+ * 	limiter: document.body,
  *
- *			// Find a position such guarantees the element remains within visible boundaries of the browser viewport.
- *			fitInViewport: true
- *		} );
+ * 	// Find a position such guarantees the element remains within visible boundaries of the browser viewport.
+ * 	fitInViewport: true
+ * } );
  *
- *		// The best position which fits into document.body and the viewport. May be useful
- *		// to set proper class on the `element`.
- *		console.log( name ); // -> "myNorthEastPosition"
+ * // The best position which fits into document.body and the viewport. May be useful
+ * // to set proper class on the `element`.
+ * console.log( name ); // -> "myNorthEastPosition"
  *
- *		// Using the absolute coordinates which has been found to position the element
- *		// as in the diagram depicting the "myNorthEastPosition" position.
- *		element.style.top = top;
- *		element.style.left = left;
+ * // Using the absolute coordinates which has been found to position the element
+ * // as in the diagram depicting the "myNorthEastPosition" position.
+ * element.style.top = top;
+ * element.style.left = left;
+ * ```
  *
- * @param {module:utils/dom/position~Options} options The input data and configuration of the helper.
- * @returns {module:utils/dom/position~Position}
+ * @param options The input data and configuration of the helper.
  */
 export function getOptimalPosition({ element, target, positions, limiter, fitInViewport, viewportOffsetConfig }) {
     // If the {@link module:utils/dom/position~Options#target} is a function, use what it returns.
@@ -113,11 +114,9 @@ export function getOptimalPosition({ element, target, positions, limiter, fitInV
     }
     return bestPosition;
 }
-// Returns a viewport `Rect` shrunk by the viewport offset config from all sides.
-//
-// @private
-// @param {Object} An object containing viewportOffset config.
-// @returns {module:utils/dom/rect~Rect} A shrunken rect of the viewport.
+/**
+ * Returns a viewport `Rect` shrunk by the viewport offset config from all sides.
+ */
 function getConstrainedViewportRect(viewportOffsetConfig) {
     viewportOffsetConfig = Object.assign({ top: 0, bottom: 0, left: 0, right: 0 }, viewportOffsetConfig);
     const viewportRect = new Rect(global.window);
@@ -127,21 +126,10 @@ function getConstrainedViewportRect(viewportOffsetConfig) {
     viewportRect.height -= viewportOffsetConfig.bottom;
     return viewportRect;
 }
-// For a given array of positioning functions, returns such that provides the best
-// fit of the `elementRect` into the `limiterRect` and `viewportRect`.
-//
-// @private
-//
-// @param {module:utils/dom/position~Options#positions} positions Functions returning
-// {@link module:utils/dom/position~Position}to be checked, in the order of preference.
-// @param {Object} options
-// @param {module:utils/dom/rect~Rect} options.elementRect The positioned element rect.
-// @param {module:utils/dom/rect~Rect} options.targetRect The target element rect.
-// @param {module:utils/dom/rect~Rect} options.viewportRect The viewport rect.
-// @param {module:utils/dom/rect~Rect} [options.limiterRect] The limiter rect.
-// @param {HTMLElement|null} [options.positionedElementAncestor] Nearest element ancestor element which CSS position is not "static".
-//
-// @returns {module:utils/dom/position~Position|null} An array containing the name of the position and it's rect.
+/**
+ * For a given array of positioning functions, returns such that provides the best
+ * fit of the `elementRect` into the `limiterRect` and `viewportRect`.
+ */
 function getBestPosition(positions, options) {
     const { elementRect } = options;
     // This is when element is fully visible.
@@ -169,17 +157,14 @@ function getBestPosition(positions, options) {
     }
     return bestPosition;
 }
-// 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.
-//
-// @private
-//
-// @param {module:utils/dom/rect~Rect} rect A rect with absolute rect coordinates.
-// @param {HTMLElement} positionedElementAncestor An ancestor element that should be considered.
+/**
+ * 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 = getRectForAbsolutePositioning(new Rect(positionedElementAncestor));
     const ancestorBorderWidths = getBorderWidths(positionedElementAncestor);
@@ -207,34 +192,34 @@ function shiftRectToCompensatePositionedAncestor(rect, positionedElementAncestor
     moveY -= ancestorBorderWidths.top;
     rect.moveBy(moveX, moveY);
 }
-// DOMRect (also Rect) works in a scroll–independent geometry but `position: absolute` doesn't.
-// This function converts Rect to `position: absolute` coordinates.
-//
-// @private
-// @param {module:utils/dom/rect~Rect} rect A rect to be converted.
-// @returns {module:utils/dom/rect~Rect} Object containing `left` and `top` properties, in absolute coordinates.
+/**
+ * DOMRect (also Rect) works in a scroll–independent geometry but `position: absolute` doesn't.
+ * This function converts Rect to `position: absolute` coordinates.
+ */
 function getRectForAbsolutePositioning(rect) {
     const { scrollX, scrollY } = global.window;
     return rect.clone().moveBy(scrollX, scrollY);
 }
-// A position class which instances are created and used by the {@link module:utils/dom/position~getOptimalPosition} helper.
-//
-// {@link module:utils/dom/position~Position#top} and {@link module:utils/dom/position~Position#left} properties of the position instance
-// translate directly to the `top` and `left` properties in CSS "`position: absolute` coordinate system". If set on the positioned element
-// in DOM, they will make it display it in the right place in the viewport.
-// @private
-// @implements {Position}
+/**
+ * A position class which instances are created and used by the {@link module:utils/dom/position~getOptimalPosition} helper.
+ *
+ * {@link module:utils/dom/position~Position#top} and {@link module:utils/dom/position~Position#left} properties of the position instance
+ * translate directly to the `top` and `left` properties in CSS "`position: absolute` coordinate system". If set on the positioned element
+ * in DOM, they will make it display it in the right place in the viewport.
+ */
 class PositionObject {
-    // Creates an instance of the {@link module:utils/dom/position~PositionObject} class.
-    //
-    // @param {module:utils/dom/position~PositioningFunction} positioningFunction function The function that defines the expected
-    // coordinates the positioned element should move to.
-    // @param {Object} [options] options object.
-    // @param {module:utils/dom/rect~Rect} options.elementRect The positioned element rect.
-    // @param {module:utils/dom/rect~Rect} options.targetRect The target element rect.
-    // @param {module:utils/dom/rect~Rect|null} options.viewportRect The viewport rect.
-    // @param {module:utils/dom/rect~Rect} [options.limiterRect] The limiter rect.
-    // @param {HTMLElement|null} [options.positionedElementAncestor] Nearest element ancestor element which CSS position is not "static".
+    /**
+     * Creates an instance of the {@link module:utils/dom/position~PositionObject} class.
+     *
+     * @param positioningFunction function The function that defines the expected
+     * coordinates the positioned element should move to.
+     * @param options options object.
+     * @param options.elementRect The positioned element rect.
+     * @param options.targetRect The target element rect.
+     * @param options.viewportRect The viewport rect.
+     * @param options.limiterRect The limiter rect.
+     * @param options.positionedElementAncestor Nearest element ancestor element which CSS position is not "static".
+     */
     constructor(positioningFunction, options) {
         const positioningFunctionOutput = positioningFunction(options.targetRect, options.elementRect, options.viewportRect);
         // Nameless position for a function that didn't participate.
@@ -247,26 +232,23 @@ class PositionObject {
         this._positioningFunctionCorrdinates = { left, top };
         this._options = options;
     }
-    // The left value in pixels in the CSS `position: absolute` coordinate system.
-    // Set it on the positioned element in DOM to move it to the position.
-    //
-    // @readonly
-    // @type {Number}
+    /**
+     * The left value in pixels in the CSS `position: absolute` coordinate system.
+     * Set it on the positioned element in DOM to move it to the position.
+     */
     get left() {
         return this._absoluteRect.left;
     }
-    // The top value in pixels in the CSS `position: absolute` coordinate system.
-    // Set it on the positioned element in DOM to move it to the position.
-    //
-    // @readonly
-    // @type {Number}
+    /**
+     * The top value in pixels in the CSS `position: absolute` coordinate system.
+     * Set it on the positioned element in DOM to move it to the position.
+     */
     get top() {
         return this._absoluteRect.top;
     }
-    // An intersection area between positioned element and limiter within viewport constraints.
-    //
-    // @readonly
-    // @type {Number}
+    /**
+     * An intersection area between positioned element and limiter within viewport constraints.
+     */
     get limiterIntersectionArea() {
         const limiterRect = this._options.limiterRect;
         if (limiterRect) {
@@ -286,10 +268,9 @@ class PositionObject {
         }
         return 0;
     }
-    // An intersection area between positioned element and viewport.
-    //
-    // @readonly
-    // @type {Number}
+    /**
+     * An intersection area between positioned element and viewport.
+     */
     get viewportIntersectionArea() {
         const viewportRect = this._options.viewportRect;
         if (viewportRect) {
@@ -297,12 +278,10 @@ class PositionObject {
         }
         return 0;
     }
-    // An already positioned element rect. A clone of the element rect passed to the constructor
-    // but placed in the viewport according to the positioning function.
-    //
-    // @private
-    // @readonly
-    // @type {module:utils/dom/rect~Rect}
+    /**
+     * An already positioned element rect. A clone of the element rect passed to the constructor
+     * but placed in the viewport according to the positioning function.
+     */
     get _rect() {
         if (this._cachedRect) {
             return this._cachedRect;
@@ -310,11 +289,9 @@ class PositionObject {
         this._cachedRect = this._options.elementRect.clone().moveTo(this._positioningFunctionCorrdinates.left, this._positioningFunctionCorrdinates.top);
         return this._cachedRect;
     }
-    // An already absolutely positioned element rect. See ({@link #_rect}).
-    //
-    // @private
-    // @readonly
-    // @type {module:utils/dom/rect~Rect}
+    /**
+     * An already absolutely positioned element rect. See ({@link #_rect}).
+     */
     get _absoluteRect() {
         if (this._cachedAbsoluteRect) {
             return this._cachedAbsoluteRect;