@ckeditor/ckeditor5-utils 35.3.2 → 36.0.0

package/src/dom/resizeobserver.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
@@ -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

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
@@ -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

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
@@ -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

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
@@ -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

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
@@ -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 });

package/src/emittermixin.js

@@ -1,11 +1,10 @@
 /**
- * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
 /**
  * @module utils/emittermixin
  */
-/* eslint-disable new-cap */
 import EventInfo from './eventinfo';
 import uid from './uid';
 import priorities from './priorities';
@@ -16,18 +15,11 @@ import CKEditorError from './ckeditorerror';
 const _listeningTo = Symbol('listeningTo');
 const _emitterId = Symbol('emitterId');
 const _delegations = Symbol('delegations');
-/**
- * Mixin that injects the {@link ~Emitter events API} into its host.
- *
- * Read more about the concept of emitters in the:
- * * {@glink framework/guides/architecture/core-editor-architecture#event-system-and-observables Event system and observables}
- * section of the {@glink framework/guides/architecture/core-editor-architecture Core editor architecture} guide.
- * * {@glink framework/guides/deep-dive/event-system Event system} deep dive guide.
- *
- * @mixin EmitterMixin
- * @implements module:utils/emittermixin~Emitter
- */
+const defaultEmitterClass = EmitterMixin(Object);
 export default function EmitterMixin(base) {
+    if (!base) {
+        return defaultEmitterClass;
+    }
     class Mixin extends base {
         on(event, callback, options) {
             this.listenTo(this, event, callback, options);
@@ -250,24 +242,21 @@ export default function EmitterMixin(base) {
     }
     return Mixin;
 }
-export const Emitter = EmitterMixin(Object);
 // Backward compatibility with `mix`
 ([
     'on', 'once', 'off', 'listenTo',
     'stopListening', 'fire', 'delegate', 'stopDelegating',
     '_addEventListener', '_removeEventListener'
 ]).forEach(key => {
-    EmitterMixin[key] = Emitter.prototype[key];
+    EmitterMixin[key] = defaultEmitterClass.prototype[key];
 });
 /**
  * Checks if `listeningEmitter` listens to an emitter with given `listenedToEmitterId` and if so, returns that emitter.
  * If not, returns `null`.
  *
  * @internal
- * @protected
- * @param {module:utils/emittermixin~Emitter} listeningEmitter An emitter that listens.
- * @param {String} listenedToEmitterId Unique emitter id of emitter listened to.
- * @returns {module:utils/emittermixin~Emitter|null}
+ * @param listeningEmitter An emitter that listens.
+ * @param listenedToEmitterId Unique emitter id of emitter listened to.
  */
 export function _getEmitterListenedTo(listeningEmitter, listenedToEmitterId) {
     const listeningTo = listeningEmitter[_listeningTo];
@@ -282,9 +271,8 @@ export function _getEmitterListenedTo(listeningEmitter, listenedToEmitterId) {
  * **Note:** `_emitterId` can be set only once.
  *
  * @internal
- * @protected
- * @param {module:utils/emittermixin~Emitter} emitter An emitter for which id will be set.
- * @param {String} [id] Unique id to set. If not passed, random unique id will be set.
+ * @param emitter An emitter for which id will be set.
+ * @param id Unique id to set. If not passed, random unique id will be set.
  */
 export function _setEmitterId(emitter, id) {
     if (!emitter[_emitterId]) {
@@ -295,16 +283,16 @@ export function _setEmitterId(emitter, id) {
  * Returns emitter's unique id.
  *
  * @internal
- * @protected
- * @param {module:utils/emittermixin~Emitter} emitter An emitter which id will be returned.
- * @returns {String|undefined}
+ * @param emitter An emitter which id will be returned.
  */
 export function _getEmitterId(emitter) {
     return emitter[_emitterId];
 }
-// Gets the internal `_events` property of the given object.
-// `_events` property store all lists with callbacks for registered event names.
-// If there were no events registered on the object, empty `_events` object is created.
+/**
+ * Gets the internal `_events` property of the given object.
+ * `_events` property store all lists with callbacks for registered event names.
+ * If there were no events registered on the object, empty `_events` object is created.
+ */
 function getEvents(source) {
     if (!source._events) {
         Object.defineProperty(source, '_events', {
@@ -313,18 +301,22 @@ function getEvents(source) {
     }
     return source._events;
 }
-// Creates event node for generic-specific events relation architecture.
+/**
+ * Creates event node for generic-specific events relation architecture.
+ */
 function makeEventNode() {
     return {
         callbacks: [],
         childEvents: []
     };
 }
-// Creates an architecture for generic-specific events relation.
-// If needed, creates all events for given eventName, i.e. if the first registered event
-// is foo:bar:abc, it will create foo:bar:abc, foo:bar and foo event and tie them together.
-// It also copies callbacks from more generic events to more specific events when
-// specific events are created.
+/**
+ * Creates an architecture for generic-specific events relation.
+ * If needed, creates all events for given eventName, i.e. if the first registered event
+ * is foo:bar:abc, it will create foo:bar:abc, foo:bar and foo event and tie them together.
+ * It also copies callbacks from more generic events to more specific events when
+ * specific events are created.
+ */
 function createEventNamespace(source, eventName) {
     const events = getEvents(source);
     // First, check if the event we want to add to the structure already exists.
@@ -375,9 +367,11 @@ function createEventNamespace(source, eventName) {
         events[name].childEvents.push(childEventName);
     }
 }
-// Gets an array containing callbacks list for a given event and it's more specific events.
-// I.e. if given event is foo:bar and there is also foo:bar:abc event registered, this will
-// return callback list of foo:bar and foo:bar:abc (but not foo).
+/**
+ * Gets an array containing callbacks list for a given event and it's more specific events.
+ * I.e. if given event is foo:bar and there is also foo:bar:abc event registered, this will
+ * return callback list of foo:bar and foo:bar:abc (but not foo).
+ */
 function getCallbacksListsForNamespace(source, eventName) {
     const eventNode = getEvents(source)[eventName];
     if (!eventNode) {
@@ -390,9 +384,11 @@ function getCallbacksListsForNamespace(source, eventName) {
     }
     return callbacksLists;
 }
-// Get the list of callbacks for a given event, but only if there any callbacks have been registered.
-// If there are no callbacks registered for given event, it checks if this is a specific event and looks
-// for callbacks for it's more generic version.
+/**
+ * Get the list of callbacks for a given event, but only if there any callbacks have been registered.
+ * If there are no callbacks registered for given event, it checks if this is a specific event and looks
+ * for callbacks for it's more generic version.
+ */
 function getCallbacksForEvent(source, eventName) {
     let event;
     if (!source._events || !(event = source._events[eventName]) || !event.callbacks.length) {
@@ -409,13 +405,13 @@ function getCallbacksForEvent(source, eventName) {
     }
     return event.callbacks;
 }
-// Fires delegated events for given map of destinations.
-//
-// @private
-// * @param {Map.<utils.Emitter>} destinations A map containing
-// `[ {@link module:utils/emittermixin~Emitter}, "event name" ]` pair destinations.
-// * @param {utils.EventInfo} eventInfo The original event info object.
-// * @param {Array.<*>} fireArgs Arguments the original event was fired with.
+/**
+ * Fires delegated events for given map of destinations.
+ *
+ * @param destinations A map containing `[ {@link module:utils/emittermixin~Emitter}, "event name" ]` pair destinations.
+ * @param eventInfo The original event info object.
+ * @param fireArgs Arguments the original event was fired with.
+ */
 function fireDelegatedEvents(destinations, eventInfo, fireArgs) {
     for (let [emitter, name] of destinations) {
         if (!name) {
@@ -429,7 +425,9 @@ function fireDelegatedEvents(destinations, eventInfo, fireArgs) {
         emitter.fire(delegatedInfo, ...fireArgs);
     }
 }
-// Helper for registering event callback on the emitter.
+/**
+ * Helper for registering event callback on the emitter.
+ */
 function addEventListener(listener, emitter, event, callback, options) {
     if (emitter._addEventListener) {
         emitter._addEventListener(event, callback, options);
@@ -440,7 +438,9 @@ function addEventListener(listener, emitter, event, callback, options) {
         (listener._addEventListener).call(emitter, event, callback, options);
     }
 }
-// Helper for removing event callback from the emitter.
+/**
+ * Helper for removing event callback from the emitter.
+ */
 function removeEventListener(listener, emitter, event, callback) {
     if (emitter._removeEventListener) {
         emitter._removeEventListener(event, callback);