@ckeditor/ckeditor5-utils 35.3.2 → 35.4.0

package/src/dom/rect.js

@@ -19,29 +19,31 @@ export default class Rect {
     /**
      * Creates an instance of rect.
      *
-     *		// Rect of an HTMLElement.
-     *		const rectA = new Rect( document.body );
+     * ```ts
+     * // Rect of an HTMLElement.
+     * const rectA = new Rect( document.body );
      *
-     *		// Rect of a DOM Range.
-     *		const rectB = new Rect( document.getSelection().getRangeAt( 0 ) );
+     * // Rect of a DOM Range.
+     * const rectB = new Rect( document.getSelection().getRangeAt( 0 ) );
      *
-     *		// Rect of a window (web browser viewport).
-     *		const rectC = new Rect( window );
+     * // Rect of a window (web browser viewport).
+     * const rectC = new Rect( window );
      *
-     *		// Rect out of an object.
-     *		const rectD = new Rect( { top: 0, right: 10, bottom: 10, left: 0, width: 10, height: 10 } );
+     * // Rect out of an object.
+     * const rectD = new Rect( { top: 0, right: 10, bottom: 10, left: 0, width: 10, height: 10 } );
      *
-     *		// Rect out of another Rect instance.
-     *		const rectE = new Rect( rectD );
+     * // Rect out of another Rect instance.
+     * const rectE = new Rect( rectD );
      *
-     *		// Rect out of a ClientRect.
-     *		const rectF = new Rect( document.body.getClientRects().item( 0 ) );
+     * // Rect out of a ClientRect.
+     * const rectF = new Rect( document.body.getClientRects().item( 0 ) );
+     * ```
      *
      * **Note**: By default a rect of an HTML element includes its CSS borders and scrollbars (if any)
      * ant the rect of a `window` includes scrollbars too. Use {@link #excludeScrollbarsAndBorders}
      * to get the inner part of the rect.
      *
-     * @param {module:utils/dom/rect~RectSource} source A source object to create the rect.
+     * @param source A source object to create the rect.
      */
     constructor(source) {
         const isSourceRange = isRange(source);
@@ -88,7 +90,7 @@ export default class Rect {
     /**
      * Returns a clone of the rect.
      *
-     * @returns {module:utils/dom/rect~Rect} A cloned rect.
+     * @returns A cloned rect.
      */
     clone() {
         return new Rect(this);
@@ -96,9 +98,9 @@ export default class Rect {
     /**
      * Moves the rect so that its upper–left corner lands in desired `[ x, y ]` location.
      *
-     * @param {Number} x Desired horizontal location.
-     * @param {Number} y Desired vertical location.
-     * @returns {module:utils/dom/rect~Rect} A rect which has been moved.
+     * @param x Desired horizontal location.
+     * @param y Desired vertical location.
+     * @returns A rect which has been moved.
      */
     moveTo(x, y) {
         this.top = y;
@@ -110,9 +112,9 @@ export default class Rect {
     /**
      * Moves the rect in–place by a dedicated offset.
      *
-     * @param {Number} x A horizontal offset.
-     * @param {Number} y A vertical offset
-     * @returns {module:utils/dom/rect~Rect} A rect which has been moved.
+     * @param x A horizontal offset.
+     * @param y A vertical offset
+     * @returns A rect which has been moved.
      */
     moveBy(x, y) {
         this.top += y;
@@ -123,9 +125,6 @@ export default class Rect {
     }
     /**
      * Returns a new rect a a result of intersection with another rect.
-     *
-     * @param {module:utils/dom/rect~Rect} anotherRect
-     * @returns {module:utils/dom/rect~Rect|null}
      */
     getIntersection(anotherRect) {
         const rect = {
@@ -148,8 +147,7 @@ export default class Rect {
     /**
      * Returns the area of intersection with another rect.
      *
-     * @param {module:utils/dom/rect~Rect} anotherRect
-     * @returns {Number} Area of intersection.
+     * @returns Area of intersection.
      */
     getIntersectionArea(anotherRect) {
         const rect = this.getIntersection(anotherRect);
@@ -162,8 +160,6 @@ export default class Rect {
     }
     /**
      * Returns the area of the rect.
-     *
-     * @returns {Number}
      */
     getArea() {
         return this.width * this.height;
@@ -176,7 +172,7 @@ export default class Rect {
      * If there's no such visible rect, which is when the rect is limited by one or many of
      * the ancestors, `null` is returned.
      *
-     * @returns {module:utils/dom/rect~Rect|null} A visible rect instance or `null`, if there's none.
+     * @returns A visible rect instance or `null`, if there's none.
      */
     getVisible() {
         const source = this._source;
@@ -208,8 +204,8 @@ export default class Rect {
      * {@link #bottom}, {@link #width} and {@link #height}) are the equal in both rect
      * instances.
      *
-     * @param {module:utils/dom/rect~Rect} anotherRect A rect instance to compare with.
-     * @returns {Boolean} `true` when Rects are equal. `false` otherwise.
+     * @param anotherRect A rect instance to compare with.
+     * @returns `true` when Rects are equal. `false` otherwise.
      */
     isEqual(anotherRect) {
         for (const prop of rectProperties) {
@@ -222,8 +218,8 @@ export default class Rect {
     /**
      * Checks whether a rect fully contains another rect instance.
      *
-     * @param {module:utils/dom/rect~Rect} anotherRect
-     * @returns {Boolean} `true` if contains, `false` otherwise.
+     * @param anotherRect
+     * @returns `true` if contains, `false` otherwise.
      */
     contains(anotherRect) {
         const intersectRect = this.getIntersection(anotherRect);
@@ -235,7 +231,7 @@ export default class Rect {
      * * Borders are removed when {@link #_source} is an HTML element.
      * * Scrollbars are excluded from HTML elements and the `window`.
      *
-     * @returns {module:utils/dom/rect~Rect} A rect which has been updated.
+     * @returns A rect which has been updated.
      */
     excludeScrollbarsAndBorders() {
         const source = this._source;
@@ -271,8 +267,8 @@ export default class Rect {
     /**
      * Returns an array of rects of the given native DOM Range.
      *
-     * @param {Range} range A native DOM range.
-     * @returns {Array.<module:utils/dom/rect~Rect>} DOM Range rects.
+     * @param range A native DOM range.
+     * @returns DOM Range rects.
      */
     static getDomRangeRects(range) {
         const rects = [];
@@ -302,8 +298,8 @@ export default class Rect {
     /**
      * Returns a bounding rectangle that contains all the given `rects`.
      *
-     * @param {Iterable.<module:utils/dom/rect~Rect>} rects A list of rectangles that should be contained in the result rectangle.
-     * @returns {module:utils/dom/rect~Rect|null} Bounding rectangle or `null` if no `rects` were given.
+     * @param rects A list of rectangles that should be contained in the result rectangle.
+     * @returns Bounding rectangle or `null` if no `rects` were given.
      */
     static getBoundingRect(rects) {
         const boundingRectData = {
@@ -330,32 +326,26 @@ export default class Rect {
         return new Rect(boundingRectData);
     }
 }
-// Acquires all the rect properties from the passed source.
-//
-// @private
-// @param {module:utils/dom/rect~Rect} rect
-// @param {module:utils/dom/rect~RectLike} source
+/**
+ * Acquires all the rect properties from the passed source.
+ */
 function copyRectProperties(rect, source) {
     for (const p of rectProperties) {
         rect[p] = source[p];
     }
 }
-// Checks if provided object is a <body> HTML element.
-//
-// @private
-// @param {*} value
-// @returns {Boolean}
+/**
+ * Checks if provided object is a <body> HTML element.
+ */
 function isBody(value) {
     if (!isDomElement(value)) {
         return false;
     }
     return value === value.ownerDocument.body;
 }
-// Checks if provided object "looks like" a DOM Element and has API required by `Rect` class.
-//
-// @private
-// @param {*} value
-// @returns {Boolean}
+/**
+ * Checks if provided object "looks like" a DOM Element and has API required by `Rect` class.
+ */
 function isDomElement(value) {
     // Note: earlier we used `isElement()` from lodash library, however that function is less performant because
     // it makes complicated checks to make sure that given value is a DOM element.

package/src/dom/remove.js

@@ -8,7 +8,7 @@
 /**
  * Removes given node from parent.
  *
- * @param {Node} node Node to remove.
+ * @param node Node to remove.
  */
 export default function remove(node) {
     const parent = node.parentNode;

package/src/dom/resizeobserver.js

@@ -9,13 +9,15 @@ import global from './global';
 /**
  * A helper class which instances allow performing custom actions when native DOM elements are resized.
  *
- *		const editableElement = editor.editing.view.getDomRoot();
+ * ```ts
+ * const editableElement = editor.editing.view.getDomRoot();
  *
- *		const observer = new ResizeObserver( editableElement, entry => {
- *			console.log( 'The editable element has been resized in DOM.' );
- *			console.log( entry.target ); // -> editableElement
- *			console.log( entry.contentRect.width ); // -> e.g. '423px'
- *		} );
+ * const observer = new ResizeObserver( editableElement, entry => {
+ * 	console.log( 'The editable element has been resized in DOM.' );
+ * 	console.log( entry.target ); // -> editableElement
+ * 	console.log( entry.contentRect.width ); // -> e.g. '423px'
+ * } );
+ * ```
  *
  * It uses the [native DOM resize observer](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver)
  * under the hood.
@@ -24,9 +26,9 @@ export default class ResizeObserver {
     /**
      * Creates an instance of the `ResizeObserver` class.
      *
-     * @param {Element} element A DOM element that is to be observed for resizing. Note that
+     * @param element A DOM element that is to be observed for resizing. Note that
      * the element must be visible (i.e. not detached from DOM) for the observer to work.
-     * @param {Function} callback A function called when the observed element was resized. It passes
+     * @param callback A function called when the observed element was resized. It passes
      * the [`ResizeObserverEntry`](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry)
      * object with information about the resize event.
      */
@@ -49,11 +51,6 @@ export default class ResizeObserver {
     }
     /**
      * Registers a new resize callback for the DOM element.
-     *
-     * @private
-     * @static
-     * @param {Element} element
-     * @param {Function} callback
      */
     static _addElementCallback(element, callback) {
         if (!ResizeObserver._elementCallbacks) {
@@ -69,11 +66,6 @@ export default class ResizeObserver {
     /**
      * Removes a resize callback from the DOM element. If no callbacks are left
      * for the element, it removes the element from the native observer.
-     *
-     * @private
-     * @static
-     * @param {Element} element
-     * @param {Function} callback
      */
     static _deleteElementCallback(element, callback) {
         const callbacks = ResizeObserver._getElementCallbacks(element);
@@ -94,11 +86,6 @@ export default class ResizeObserver {
     }
     /**
      * Returns are registered resize callbacks for the DOM element.
-     *
-     * @private
-     * @static
-     * @param {Element} element
-     * @returns {Set.<Function>|null|undefined}
      */
     static _getElementCallbacks(element) {
         if (!ResizeObserver._elementCallbacks) {
@@ -108,9 +95,6 @@ export default class ResizeObserver {
     }
     /**
      * Creates the single native observer shared across all `ResizeObserver` instances.
-     *
-     * @private
-     * @static
      */
     static _createObserver() {
         ResizeObserver._observerInstance = new global.window.ResizeObserver(entries => {
@@ -127,19 +111,10 @@ export default class ResizeObserver {
 }
 /**
  * The single native observer instance shared across all {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
- *
- * @static
- * @private
- * @readonly
- * @property {Object|null}
  */
 ResizeObserver._observerInstance = null;
 /**
  * A mapping of native DOM elements and their callbacks shared across all
  * {@link module:utils/dom/resizeobserver~ResizeObserver} instances.
- *
- * @static
- * @private
- * @property {Map.<Element,Set>|null}
  */
 ResizeObserver._elementCallbacks = null;

package/src/dom/scroll.js

@@ -13,9 +13,9 @@ import isText from './istext';
  * This helper will scroll all `target` ancestors and the web browser viewport to reveal the target to
  * the user. If the `target` is already visible, nothing will happen.
  *
- * @param {Object} options
- * @param {HTMLElement|Range} options.target A target, which supposed to become visible to the user.
- * @param {Number} [options.viewportOffset] An offset from the edge of the viewport (in pixels)
+ * @param options
+ * @param options.target A target, which supposed to become visible to the user.
+ * @param options.viewportOffset An offset from the edge of the viewport (in pixels)
  * the `target` will be moved by when the viewport is scrolled. It enhances the user experience
  * by keeping the `target` some distance from the edge of the viewport and thus making it easier to
  * read or edit by the user.
@@ -76,7 +76,7 @@ export function scrollViewportToShowTarget({ target, viewportOffset = 0 }) {
  * Makes any page `HTMLElement` or `Range` (target) visible within its scrollable ancestors,
  * e.g. if they have `overflow: scroll` CSS style.
  *
- * @param {HTMLElement|Range} target A target, which supposed to become visible to the user.
+ * @param target A target, which supposed to become visible to the user.
  */
 export function scrollAncestorsToShowTarget(target) {
     const targetParent = getParentElement(target);
@@ -84,47 +84,56 @@ export function scrollAncestorsToShowTarget(target) {
         return new Rect(target);
     });
 }
-// Makes a given rect visible within its parent window.
-//
-// Note: Avoid the situation where the caret is still in the viewport, but totally
-// at the edge of it. In such situation, if it moved beyond the viewport in the next
-// action e.g. after paste, the scrolling would move it to the viewportOffset level
-// and it all would look like the caret visually moved up/down:
-//
-// 1.
-//		| foo[]
-//		|                                    <--- N px of space below the caret
-//		+---------------------------------...
-//
-// 2. *paste*
-// 3.
-//		|
-//		|
-//		+-foo-----------------------------...
-//		  bar[]                              <--- caret below viewport, scrolling...
-//
-// 4. *scrolling*
-// 5.
-//		|
-//		| foo
-//		| bar[]                              <--- caret precisely at the edge
-//		+---------------------------------...
-//
-// To prevent this, this method checks the rects moved by the viewportOffset to cover
-// the upper/lower edge of the viewport. It makes sure if the action repeats, there's
-// no twitching – it's a purely visual improvement:
-//
-// 5. (after fix)
-//		|
-//		| foo
-//		| bar[]
-//		|                                    <--- N px of space below the caret
-//		+---------------------------------...
-//
-// @private
-// @param {Window} window A window which is scrolled to reveal the rect.
-// @param {module:utils/dom/rect~Rect} rect A rect which is to be revealed.
-// @param {Number} viewportOffset See scrollViewportToShowTarget.
+/**
+ * Makes a given rect visible within its parent window.
+ *
+ * Note: Avoid the situation where the caret is still in the viewport, but totally
+ * at the edge of it. In such situation, if it moved beyond the viewport in the next
+ * action e.g. after paste, the scrolling would move it to the viewportOffset level
+ * and it all would look like the caret visually moved up/down:
+ *
+ * 1.
+ * ```
+ * | foo[]
+ * |                                    <--- N px of space below the caret
+ * +---------------------------------...
+ * ```
+ *
+ * 2. *paste*
+ * 3.
+ * ```
+ * |
+ * |
+ * +-foo-----------------------------...
+ *   bar[]                              <--- caret below viewport, scrolling...
+ * ```
+ *
+ * 4. *scrolling*
+ * 5.
+ * ```
+ * |
+ * | foo
+ * | bar[]                              <--- caret precisely at the edge
+ * +---------------------------------...
+ * ```
+ *
+ * To prevent this, this method checks the rects moved by the viewportOffset to cover
+ * the upper/lower edge of the viewport. It makes sure if the action repeats, there's
+ * no twitching – it's a purely visual improvement:
+ *
+ * 5. (after fix)
+ * ```
+ * |
+ * | foo
+ * | bar[]
+ * |                                    <--- N px of space below the caret
+ * +---------------------------------...
+ * ```
+ *
+ * @param window A window which is scrolled to reveal the rect.
+ * @param rect A rect which is to be revealed.
+ * @param viewportOffset See scrollViewportToShowTarget.
+ */
 function scrollWindowToShowRect(window, rect, viewportOffset) {
     const targetShiftedDownRect = rect.clone().moveBy(0, viewportOffset);
     const targetShiftedUpRect = rect.clone().moveBy(0, -viewportOffset);
@@ -149,11 +158,12 @@ function scrollWindowToShowRect(window, rect, viewportOffset) {
         window.scrollTo(scrollX, scrollY);
     }
 }
-// Recursively scrolls element ancestors to visually reveal a rect.
-//
-// @private
-// @param {HTMLElement} A parent The first ancestors to start scrolling.
-// @param {Function} getRect A function which returns the Rect, which is to be revealed.
+/**
+ * Recursively scrolls element ancestors to visually reveal a rect.
+ *
+ * @param parent A parent The first ancestors to start scrolling.
+ * @param getRect A function which returns the Rect, which is to be revealed.
+ */
 function scrollAncestorsToShowRect(parent, getRect) {
     const parentWindow = getWindow(parent);
     let parentRect, targetRect;
@@ -177,47 +187,33 @@ function scrollAncestorsToShowRect(parent, getRect) {
         parent = parent.parentNode;
     }
 }
-// Determines if a given `Rect` extends beyond the bottom edge of the second `Rect`.
-//
-// @private
-// @param {module:utils/dom/rect~Rect} firstRect
-// @param {module:utils/dom/rect~Rect} secondRect
-// @returns {Boolean}
+/**
+ * Determines if a given `Rect` extends beyond the bottom edge of the second `Rect`.
+ */
 function isBelow(firstRect, secondRect) {
     return firstRect.bottom > secondRect.bottom;
 }
-// Determines if a given `Rect` extends beyond the top edge of the second `Rect`.
-//
-// @private
-// @param {module:utils/dom/rect~Rect} firstRect
-// @param {module:utils/dom/rect~Rect} secondRect
-// @returns {Boolean}
+/**
+ * Determines if a given `Rect` extends beyond the top edge of the second `Rect`.
+ */
 function isAbove(firstRect, secondRect) {
     return firstRect.top < secondRect.top;
 }
-// Determines if a given `Rect` extends beyond the left edge of the second `Rect`.
-//
-// @private
-// @param {module:utils/dom/rect~Rect} firstRect
-// @param {module:utils/dom/rect~Rect} secondRect
-// @returns {Boolean}
+/**
+ * Determines if a given `Rect` extends beyond the left edge of the second `Rect`.
+ */
 function isLeftOf(firstRect, secondRect) {
     return firstRect.left < secondRect.left;
 }
-// Determines if a given `Rect` extends beyond the right edge of the second `Rect`.
-//
-// @private
-// @param {module:utils/dom/rect~Rect} firstRect
-// @param {module:utils/dom/rect~Rect} secondRect
-// @returns {Boolean}
+/**
+ * Determines if a given `Rect` extends beyond the right edge of the second `Rect`.
+ */
 function isRightOf(firstRect, secondRect) {
     return firstRect.right > secondRect.right;
 }
-// Returns the closest window of an element or range.
-//
-// @private
-// @param {HTMLElement|Range} elementOrRange
-// @returns {Window}
+/**
+ * Returns the closest window of an element or range.
+ */
 function getWindow(elementOrRange) {
     if (isRange(elementOrRange)) {
         return elementOrRange.startContainer.ownerDocument.defaultView;
@@ -226,11 +222,9 @@ function getWindow(elementOrRange) {
         return elementOrRange.ownerDocument.defaultView;
     }
 }
-// Returns the closest parent of an element or DOM range.
-//
-// @private
-// @param {HTMLElement|Range} elementOrRange
-// @returns {HTMLelement}
+/**
+ * Returns the closest parent of an element or DOM range.
+ */
 function getParentElement(elementOrRange) {
     if (isRange(elementOrRange)) {
         let parent = elementOrRange.commonAncestorContainer;
@@ -244,13 +238,13 @@ function getParentElement(elementOrRange) {
         return elementOrRange.parentNode;
     }
 }
-// Returns the rect of an element or range residing in an iframe.
-// The result rect is relative to the geometry of the passed window instance.
-//
-// @private
-// @param {HTMLElement|Range} target Element or range which rect should be returned.
-// @param {Window} relativeWindow A window the rect should be relative to.
-// @returns {module:utils/dom/rect~Rect}
+/**
+ * Returns the rect of an element or range residing in an iframe.
+ * The result rect is relative to the geometry of the passed window instance.
+ *
+ * @param target Element or range which rect should be returned.
+ * @param relativeWindow A window the rect should be relative to.
+ */
 function getRectRelativeToWindow(target, relativeWindow) {
     const targetWindow = getWindow(target);
     const rect = new Rect(target);

package/src/dom/setdatainelement.js

@@ -9,8 +9,8 @@
 /**
  * Sets data in a given element.
  *
- * @param {HTMLElement} el The element in which the data will be set.
- * @param {String} data The data string.
+ * @param el The element in which the data will be set.
+ * @param data The data string.
  */
 export default function setDataInElement(el, data) {
     if (el instanceof HTMLTextAreaElement) {

package/src/dom/tounit.js

@@ -9,17 +9,8 @@
  * Returns a helper function, which adds a desired trailing
  * `unit` to the passed value.
  *
- * @param {String} unit An unit like "px" or "em".
- * @returns {module:utils/dom/tounit~helper}
+ * @param unit An unit like "px" or "em".
  */
 export default function toUnit(unit) {
-    /**
-     * A function, which adds a pre–defined trailing `unit`
-     * to the passed `value`.
-     *
-     * @function helper
-     * @param {String|Number} value A value to be given the unit.
-     * @returns {String} A value with the trailing unit.
-     */
     return value => value + unit;
 }

package/src/elementreplacer.js

@@ -18,8 +18,8 @@ export default class ElementReplacer {
      *
      * The effect of this method can be reverted by {@link #restore}.
      *
-     * @param {HTMLElement} element The element to replace.
-     * @param {HTMLElement} [newElement] The replacement element. If not passed, then the `element` will just be hidden.
+     * @param element The element to replace.
+     * @param newElement The replacement element. If not passed, then the `element` will just be hidden.
      */
     replace(element, newElement) {
         this._replacedElements.push({ element, newElement });