@ckeditor/ckeditor5-utils 35.3.2 → 36.0.0

package/LICENSE.md

@@ -2,7 +2,7 @@ Software License Agreement
 ==========================
 
 **CKEditor 5 utilities** – https://github.com/ckeditor/ckeditor5-utils <br>
-Copyright (c) 2003-2022, [CKSource Holding sp. z o.o.](https://cksource.com) All rights reserved.
+Copyright (c) 2003-2023, [CKSource Holding sp. z o.o.](https://cksource.com) All rights reserved.
 
 Licensed under the terms of [GNU General Public License Version 2 or later](http://www.gnu.org/licenses/gpl.html).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-utils",
-  "version": "35.3.2",
+  "version": "36.0.0",
   "description": "Miscellaneous utilities used by CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -14,10 +14,10 @@
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-build-classic": "^35.3.2",
-    "@ckeditor/ckeditor5-editor-classic": "^35.3.2",
-    "@ckeditor/ckeditor5-core": "^35.3.2",
-    "@ckeditor/ckeditor5-engine": "^35.3.2",
+    "@ckeditor/ckeditor5-build-classic": "^36.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^36.0.0",
+    "@ckeditor/ckeditor5-core": "^36.0.0",
+    "@ckeditor/ckeditor5-engine": "^36.0.0",
     "@types/lodash-es": "^4.17.6",
     "typescript": "^4.8.4"
   },

package/src/areconnectedthroughproperties.js

@@ -1,17 +1,13 @@
 /**
- * @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/arestructuresconnected
+ * @module utils/areconnectedthroughproperties
  */
 /* globals EventTarget, Event */
 /**
  * Traverses both structures to find out whether there is a reference that is shared between both structures.
- *
- * @param {Object|Array} obj1
- * @param {Object|Array} obj2
- * @returns {Boolean}
  */
 export default function areConnectedThroughProperties(obj1, obj2) {
     if (obj1 === obj2 && isObject(obj1)) {
@@ -26,9 +22,11 @@ export default function areConnectedThroughProperties(obj1, obj2) {
     }
     return false;
 }
-// Traverses JS structure and stores all sub-nodes, including the head node.
-// It walks into each iterable structures with the `try catch` block to omit errors that might be thrown during
-// tree walking. All primitives, functions and built-ins are skipped.
+/**
+ * Traverses JS structure and stores all sub-nodes, including the head node.
+ * It walks into each iterable structures with the `try catch` block to omit errors that might be thrown during
+ * tree walking. All primitives, functions and built-ins are skipped.
+ */
 function getSubNodes(head) {
     const nodes = [head];
     // Nodes are stored to prevent infinite looping.

package/src/ckeditorerror.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
  */
 /**
@@ -24,57 +24,43 @@ export const DOCUMENTATION_URL = 'https://ckeditor.com/docs/ckeditor5/latest/sup
  * {@link module:utils/ckeditorerror~logError `logError()`}
  * to improve developers experience and let them see the a working editor as soon as possible.
  *
- *		/**
- *		 * Error thrown when a plugin cannot be loaded due to JavaScript errors, lack of plugins with a given name, etc.
- *		 *
- *		 * @error plugin-load
- *		 * @param pluginName The name of the plugin that could not be loaded.
- *		 * @param moduleName The name of the module which tried to load this plugin.
- *		 * /
- *		throw new CKEditorError( 'plugin-load', {
- *			pluginName: 'foo',
- *			moduleName: 'bar'
- *		} );
- *
- * @extends Error
+ * ```ts
+ * /**
+ *  * Error thrown when a plugin cannot be loaded due to JavaScript errors, lack of plugins with a given name, etc.
+ *  *
+ *  * @error plugin-load
+ *  * @param pluginName The name of the plugin that could not be loaded.
+ *  * @param moduleName The name of the module which tried to load this plugin.
+ *  *\/
+ * throw new CKEditorError( 'plugin-load', {
+ * 	pluginName: 'foo',
+ * 	moduleName: 'bar'
+ * } );
+ * ```
  */
 export default class CKEditorError extends Error {
     /**
      * Creates an instance of the CKEditorError class.
      *
-     * @param {String} errorName The error id in an `error-name` format. A link to this error documentation page will be added
+     * @param errorName The error id in an `error-name` format. A link to this error documentation page will be added
      * to the thrown error's `message`.
-     * @param {Object|null} context A context of the error by which the {@link module:watchdog/watchdog~Watchdog watchdog}
+     * @param context A context of the error by which the {@link module:watchdog/watchdog~Watchdog watchdog}
      * is able to determine which editor crashed. It should be an editor instance or a property connected to it. It can be also
      * a `null` value if the editor should not be restarted in case of the error (e.g. during the editor initialization).
      * The error context should be checked using the `areConnectedThroughProperties( editor, context )` utility
      * to check if the object works as the context.
-     * @param {Object} [data] Additional data describing the error. A stringified version of this object
+     * @param data Additional data describing the error. A stringified version of this object
      * will be appended to the error message, so the data are quickly visible in the console. The original
      * data object will also be later available under the {@link #data} property.
      */
     constructor(errorName, context, data) {
         super(getErrorMessage(errorName, data));
-        /**
-         * @type {String}
-         */
         this.name = 'CKEditorError';
-        /**
-         * A context of the error by which the Watchdog is able to determine which editor crashed.
-         *
-         * @type {Object|null}
-         */
         this.context = context;
-        /**
-         * The additional error data passed to the constructor. Undefined if none was passed.
-         *
-         * @type {Object|undefined}
-         */
         this.data = data;
     }
     /**
      * Checks if the error is of the `CKEditorError` type.
-     * @returns {Boolean}
      */
     is(type) {
         return type === 'CKEditorError';
@@ -84,9 +70,8 @@ export default class CKEditorError extends Error {
      * It is useful when combined with the {@link module:watchdog/watchdog~Watchdog} feature, which can restart the editor in case
      * of a {@link module:utils/ckeditorerror~CKEditorError} error.
      *
-     * @static
-     * @param {Error} err The error to rethrow.
-     * @param {Object} context An object connected through properties with the editor instance. This context will be used
+     * @param err The error to rethrow.
+     * @param context An object connected through properties with the editor instance. This context will be used
      * by the watchdog to verify which editor should be restarted.
      */
     static rethrowUnexpectedError(err, context) {
@@ -113,20 +98,22 @@ export default class CKEditorError extends Error {
  * Logs a warning to the console with a properly formatted message and adds a link to the documentation.
  * Use whenever you want to log a warning to the console.
  *
- *		/**
- *		 * There was a problem processing the configuration of the toolbar. The item with the given
- *		 * name does not exist, so it was omitted when rendering the toolbar.
- *		 *
- *		 * @error toolbarview-item-unavailable
- *		 * @param {String} name The name of the component.
- *		 * /
- *		logWarning( 'toolbarview-item-unavailable', { name } );
+ * ```ts
+ * /**
+ *  * There was a problem processing the configuration of the toolbar. The item with the given
+ *  * name does not exist, so it was omitted when rendering the toolbar.
+ *  *
+ *  * @error toolbarview-item-unavailable
+ *  * @param {String} name The name of the component.
+ *  *\/
+ * logWarning( 'toolbarview-item-unavailable', { name } );
+ * ```
  *
  * See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to throw an error and when to log
  * a warning or an error to the console.
  *
- * @param {String} errorName The error name to be logged.
- * @param {Object} [data] Additional data to be logged.
+ * @param errorName The error name to be logged.
+ * @param data Additional data to be logged.
  */
 export function logWarning(errorName, data) {
     console.warn(...formatConsoleArguments(errorName, data));
@@ -135,39 +122,36 @@ export function logWarning(errorName, data) {
  * Logs an error to the console with a properly formatted message and adds a link to the documentation.
  * Use whenever you want to log an error to the console.
  *
- *		/**
- *		 * There was a problem processing the configuration of the toolbar. The item with the given
- *		 * name does not exist, so it was omitted when rendering the toolbar.
- *		 *
- *		 * @error toolbarview-item-unavailable
- *		 * @param {String} name The name of the component.
- *		 * /
- *		 logError( 'toolbarview-item-unavailable', { name } );
+ * ```ts
+ * /**
+ *  * There was a problem processing the configuration of the toolbar. The item with the given
+ *  * name does not exist, so it was omitted when rendering the toolbar.
+ *  *
+ *  * @error toolbarview-item-unavailable
+ *  * @param {String} name The name of the component.
+ *  *\/
+ *  logError( 'toolbarview-item-unavailable', { name } );
+ * ```
  *
  * **Note**: In most cases logging a warning using {@link module:utils/ckeditorerror~logWarning} is enough.
  *
  * See also {@link module:utils/ckeditorerror~CKEditorError} for an explanation when to use each method.
  *
- * @param {String} errorName The error name to be logged.
- * @param {Object} [data] Additional data to be logged.
+ * @param errorName The error name to be logged.
+ * @param data Additional data to be logged.
  */
 export function logError(errorName, data) {
     console.error(...formatConsoleArguments(errorName, data));
 }
-// Returns formatted link to documentation message.
-//
-// @private
-// @param {String} errorName
-// @returns {string}
+/**
+ * Returns formatted link to documentation message.
+ */
 function getLinkToDocumentationMessage(errorName) {
     return `\nRead more: ${DOCUMENTATION_URL}#error-${errorName}`;
 }
-// Returns formatted error message.
-//
-// @private
-// @param {String} errorName
-// @param {Object} [data]
-// @returns {string}
+/**
+ * Returns formatted error message.
+ */
 function getErrorMessage(errorName, data) {
     const processedObjects = new WeakSet();
     const circularReferencesReplacer = (key, value) => {
@@ -183,12 +167,9 @@ function getErrorMessage(errorName, data) {
     const documentationLink = getLinkToDocumentationMessage(errorName);
     return errorName + stringifiedData + documentationLink;
 }
-// Returns formatted console error arguments.
-//
-// @private
-// @param {String} errorName
-// @param {Object} [data]
-// @returns {Array}
+/**
+ * Returns formatted console error arguments.
+ */
 function formatConsoleArguments(errorName, data) {
     const documentationMessage = getLinkToDocumentationMessage(errorName);
     return data ? [errorName, data, documentationMessage] : [errorName, documentationMessage];