@ckeditor/ckeditor5-core 33.0.0 → 34.0.0

package/README.md

@@ -3,7 +3,8 @@ CKEditor 5 core editor architecture
 
 [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-core.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-core)
 [![Coverage Status](https://coveralls.io/repos/github/ckeditor/ckeditor5/badge.svg?branch=master)](https://coveralls.io/github/ckeditor/ckeditor5?branch=master)
-[![Build Status](https://travis-ci.com/ckeditor/ckeditor5.svg?branch=master)](https://travis-ci.com/ckeditor/ckeditor5)
+[![Build Status](https://travis-ci.com/ckeditor/ckeditor5.svg?branch=master)](https://app.travis-ci.com/github/ckeditor/ckeditor5)
+![Dependency Status](https://img.shields.io/librariesio/release/npm/@ckeditor/ckeditor5-core)
 
 This package implements CKEditor 5's core editor architecture — a set of classes and interfaces which glue everything together.
 

package/lang/translations/en-au.po

@@ -26,7 +26,7 @@ msgstr "Remove colour"
 
 msgctxt "The label used by a button next to the color palette in the color picker that restores the default value if the default table properties are specified."
 msgid "Restore default"
-msgstr ""
+msgstr "Restore default"
 
 msgctxt "Label for the Save button."
 msgid "Save"

package/lang/translations/hr.po

@@ -26,7 +26,7 @@ msgstr "Ukloni boju"
 
 msgctxt "The label used by a button next to the color palette in the color picker that restores the default value if the default table properties are specified."
 msgid "Restore default"
-msgstr ""
+msgstr "Vrati tvorničke postavke"
 
 msgctxt "Label for the Save button."
 msgid "Save"

package/lang/translations/jv.po

@@ -0,0 +1,41 @@
+# Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
+#
+#                                     !!! IMPORTANT !!!
+#
+#         Before you edit this file, please keep in mind that contributing to the project
+#                translations is possible ONLY via the Transifex online service.
+#
+#         To submit your translations, visit https://www.transifex.com/ckeditor/ckeditor5.
+#
+#                   To learn more, check out the official contributor's guide:
+#     https://ckeditor.com/docs/ckeditor5/latest/framework/guides/contributing/contributing.html
+#
+msgid ""
+msgstr ""
+"Language-Team: Javanese (https://www.transifex.com/ckeditor/teams/11143/jv/)\n"
+"Language: jv\n"
+"Plural-Forms: nplurals=1; plural=0;\n"
+
+msgctxt "Label for the Cancel button."
+msgid "Cancel"
+msgstr "Batal"
+
+msgctxt "The label used by a button next to the color palette in the color picker that removes the color (resets it to an empty value, example usages in font color or table properties)."
+msgid "Remove color"
+msgstr "Busek warni"
+
+msgctxt "The label used by a button next to the color palette in the color picker that restores the default value if the default table properties are specified."
+msgid "Restore default"
+msgstr "Mangsulaken default"
+
+msgctxt "Label for the Save button."
+msgid "Save"
+msgstr "Rimat"
+
+msgctxt "Label of a toolbar button which reveals more toolbar items."
+msgid "Show more items"
+msgstr "Tampilaken langkung kathah"
+
+msgctxt "Label for an ‘X of Y’ status of a typical next/previous navigation. For instance, ‘Page 5 of 20’ or 'Search result 5 of 20'."
+msgid "%0 of %1"
+msgstr "%0 saking %1"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-core",
-  "version": "33.0.0",
+  "version": "34.0.0",
   "description": "The core architecture of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "wysiwyg",
@@ -23,25 +23,25 @@
   ],
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-engine": "^33.0.0",
-    "@ckeditor/ckeditor5-ui": "^33.0.0",
-    "@ckeditor/ckeditor5-utils": "^33.0.0",
+    "@ckeditor/ckeditor5-engine": "^34.0.0",
+    "@ckeditor/ckeditor5-ui": "^34.0.0",
+    "@ckeditor/ckeditor5-utils": "^34.0.0",
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-autoformat": "^33.0.0",
-    "@ckeditor/ckeditor5-basic-styles": "^33.0.0",
-    "@ckeditor/ckeditor5-block-quote": "^33.0.0",
-    "@ckeditor/ckeditor5-editor-classic": "^33.0.0",
-    "@ckeditor/ckeditor5-essentials": "^33.0.0",
-    "@ckeditor/ckeditor5-heading": "^33.0.0",
-    "@ckeditor/ckeditor5-image": "^33.0.0",
-    "@ckeditor/ckeditor5-indent": "^33.0.0",
-    "@ckeditor/ckeditor5-link": "^33.0.0",
-    "@ckeditor/ckeditor5-list": "^33.0.0",
-    "@ckeditor/ckeditor5-media-embed": "^33.0.0",
-    "@ckeditor/ckeditor5-paragraph": "^33.0.0",
-    "@ckeditor/ckeditor5-table": "^33.0.0"
+    "@ckeditor/ckeditor5-autoformat": "^34.0.0",
+    "@ckeditor/ckeditor5-basic-styles": "^34.0.0",
+    "@ckeditor/ckeditor5-block-quote": "^34.0.0",
+    "@ckeditor/ckeditor5-editor-classic": "^34.0.0",
+    "@ckeditor/ckeditor5-essentials": "^34.0.0",
+    "@ckeditor/ckeditor5-heading": "^34.0.0",
+    "@ckeditor/ckeditor5-image": "^34.0.0",
+    "@ckeditor/ckeditor5-indent": "^34.0.0",
+    "@ckeditor/ckeditor5-link": "^34.0.0",
+    "@ckeditor/ckeditor5-list": "^34.0.0",
+    "@ckeditor/ckeditor5-media-embed": "^34.0.0",
+    "@ckeditor/ckeditor5-paragraph": "^34.0.0",
+    "@ckeditor/ckeditor5-table": "^34.0.0"
   },
   "engines": {
     "node": ">=14.0.0",

package/src/editor/editor.js

@@ -108,6 +108,14 @@ export default class Editor {
 		 */
 		this.t = this.locale.t;
 
+		/**
+		 * A set of lock IDs for the {@link #isReadOnly} getter.
+		 *
+		 * @private
+		 * @type {Set.<String|Symbol>}
+		 */
+		this._readOnlyLocks = new Set();
+
 		/**
 		 * Commands registered to the editor.
 		 *
@@ -142,21 +150,6 @@ export default class Editor {
 		this.once( 'ready', () => ( this.state = 'ready' ), { priority: 'high' } );
 		this.once( 'destroy', () => ( this.state = 'destroyed' ), { priority: 'high' } );
 
-		/**
-		 * Defines whether this editor is in read-only mode.
-		 *
-		 * In read-only mode the editor {@link #commands commands} are disabled so it is not possible
-		 * to modify the document by using them. Also, the editable element(s) become non-editable.
-		 *
-		 * In order to make the editor read-only, you can set this value directly:
-		 *
-		 *		editor.isReadOnly = true;
-		 *
-		 * @observable
-		 * @member {Boolean} #isReadOnly
-		 */
-		this.set( 'isReadOnly', false );
-
 		/**
 		 * The editor's model.
 		 *
@@ -229,6 +222,122 @@ export default class Editor {
 		this.keystrokes.listenTo( this.editing.view.document );
 	}
 
+	/**
+	 * Defines whether the editor is in the read-only mode.
+	 *
+	 * In read-only mode the editor {@link #commands commands} are disabled so it is not possible
+	 * to modify the document by using them. Also, the editable element(s) become non-editable.
+	 *
+	 * In order to make the editor read-only, you need to call the {@link #enableReadOnlyMode} method:
+	 *
+	 *		editor.enableReadOnlyMode( 'feature-id' );
+	 *
+     * Later, to turn off the read-only mode, call {@link #disableReadOnlyMode}:
+	 *
+	 * 		editor.disableReadOnlyMode( 'feature-id' );
+	 *
+	 * @readonly
+	 * @observable
+	 * @member {Boolean} #isReadOnly
+	 */
+	get isReadOnly() {
+		return this._readOnlyLocks.size > 0;
+	}
+
+	set isReadOnly( value ) {
+		/**
+		 * `Editor#isReadOnly` does not have a setter and should be set using `Editor#enableReadOnlyMode( lockId )` and
+		 * `Editor#disableReadOnlyMode( lockId )`.
+		 *
+		 * @error editor-isreadonly-has-no-setter
+		 */
+		throw new CKEditorError( 'editor-isreadonly-has-no-setter' );
+	}
+
+	/**
+	 * Turns on the read-only mode in the editor.
+	 *
+	 * Editor can be switched to or out of the read-only mode by many features, under various circumstances. The editor supports locking
+	 * mechanism for the read-only mode. It enables easy control over the read-only mode when many features wants to turn it on or off at
+	 * the same time, without conflicting with each other. It guarantees that you will not make the editor editable accidentally (which
+	 * could lead to errors).
+	 *
+	 * Each read-only mode request is identified by a unique id (also called "lock"). If multiple plugins requested to turn on the
+	 * read-only mode, then, the editor will become editable only after all these plugins turn the read-only mode off (using the same ids).
+	 *
+	 * Note, that you cannot force the editor to disable the read-only mode if other plugins set it.
+	 *
+	 * After the first `enableReadOnlyMode()` call, the {@link #isReadOnly `isReadOnly` property} will be set to `true`:
+	 *
+	 *		editor.isReadOnly; // `false`.
+	 * 		editor.enableReadOnlyMode( 'my-feature-id' );
+	 * 		editor.isReadOnly; // `true`.
+	 *
+	 * You can turn off the read-only mode ("clear the lock") using the {@link #disableReadOnlyMode `disableReadOnlyMode()`} method:
+	 *
+	 * 		editor.enableReadOnlyMode( 'my-feature-id' );
+	 * 		// ...
+	 * 		editor.disableReadOnlyMode( 'my-feature-id' );
+	 * 		editor.isReadOnly; // `false`.
+	 *
+	 * All "locks" need to be removed to enable editing:
+	 *
+	 * 		editor.enableReadOnlyMode( 'my-feature-id' );
+	 * 		editor.enableReadOnlyMode( 'my-other-feature-id' );
+	 * 		// ...
+	 * 		editor.disableReadOnlyMode( 'my-feature-id' );
+	 * 		editor.isReadOnly; // `true`.
+	 * 		editor.disableReadOnlyMode( 'my-other-feature-id' );
+	 * 		editor.isReadOnly; // `false`.
+	 *
+	 * @param {String|Symbol} lockId A unique ID for setting the editor to the read-only state.
+	 */
+	enableReadOnlyMode( lockId ) {
+		if ( typeof lockId !== 'string' && typeof lockId !== 'symbol' ) {
+			/**
+			 * The lock ID is missing or it is not a string or symbol.
+			 *
+			 * @error editor-read-only-lock-id-invalid
+			 */
+			throw new CKEditorError( 'editor-read-only-lock-id-invalid', null, { lockId } );
+		}
+
+		if ( this._readOnlyLocks.has( lockId ) ) {
+			return;
+		}
+
+		this._readOnlyLocks.add( lockId );
+
+		if ( this._readOnlyLocks.size === 1 ) {
+			// Manually fire the `change:isReadOnly` event as only getter is provided.
+			this.fire( 'change:isReadOnly', 'isReadOnly', true, false );
+		}
+	}
+
+	/**
+	 * Removes the read-only lock from the editor with given lock ID.
+	 *
+	 * When no lock is present on the editor anymore, then the {@link #isReadOnly `isReadOnly` property} will be set to `false`.
+	 *
+	 * @param {String|Symbol} lockId The lock ID for setting the editor to the read-only state.
+	 */
+	disableReadOnlyMode( lockId ) {
+		if ( typeof lockId !== 'string' && typeof lockId !== 'symbol' ) {
+			throw new CKEditorError( 'editor-read-only-lock-id-invalid', null, { lockId } );
+		}
+
+		if ( !this._readOnlyLocks.has( lockId ) ) {
+			return;
+		}
+
+		this._readOnlyLocks.delete( lockId );
+
+		if ( this._readOnlyLocks.size === 0 ) {
+			// Manually fire the `change:isReadOnly` event as only getter is provided.
+			this.fire( 'change:isReadOnly', 'isReadOnly', false, true );
+		}
+	}
+
 	/**
 	 * Loads and initializes plugins specified in the configuration.
 	 *
@@ -361,7 +470,7 @@ mix( Editor, ObservableMixin );
  * This error is thrown when trying to pass a `<textarea>` element to a `create()` function of an editor class.
  *
  * The only editor type which can be initialized on `<textarea>` elements is
- * the {@glink builds/guides/predefined-builds/overview#classic-editor classic editor}.
+ * the {@glink installation/advanced/alternative-setups/predefined-builds#classic-editor classic editor}.
  * This editor hides the passed element and inserts its own UI next to it. Other types of editors reuse the passed element as their root
  * editable element and therefore `<textarea>` is not appropriate for them. Use a `<div>` or another text container instead:
  *

package/src/editor/editorconfig.jsdoc

@@ -24,7 +24,7 @@
  *			.then( ... )
  *			.catch( ... );
  *
- * Check the {@glink builds/guides/integration/configuration Configuration guide} for more information
+ * Check the {@glink installation/advanced/alternative-setups/predefined-builds Configuration guide} for more information
  * about setting configuration options.
  *
  * @interface EditorConfig
@@ -66,7 +66,7 @@
 /**
  * The list of plugins to load.
  *
- * If you use an {@glink builds/guides/predefined-builds/overview editor build} you can define the list of plugins to load
+ * If you use an {@glink installation/advanced/alternative-setups/predefined-builds editor build} you can define the list of plugins to load
  * using the names of plugins that are available:
  *
  *		const config = {
@@ -98,7 +98,7 @@
 
 /**
  * The list of additional plugins to load along those already available in the
- * {@glink builds/guides/predefined-builds/overview editor build}. It extends the {@link #plugins `plugins`} configuration.
+ * {@glink installation/advanced/alternative-setups/predefined-builds editor build}. It extends the {@link #plugins `plugins`} configuration.
  *
  *		function MyPlugin( editor ) {
  *			// ...
@@ -110,7 +110,7 @@
  *
  * **Note:** This configuration works only for simple plugins which utilize the
  * {@link module:core/plugin~PluginInterface plugin interface} and have no dependencies. To extend a
- * build with complex features, create a {@glink builds/guides/development/custom-builds custom build}.
+ * build with complex features, create a {@glink installation/getting-started/quick-start#creating-custom-builds-with-online-builder custom build}.
  *
  * **Note:** Make sure you include the new features in you toolbar configuration. Learn more
  * about the {@glink features/toolbar/toolbar toolbar setup}.
@@ -119,7 +119,7 @@
  */
 
 /**
- * The list of plugins which should not be loaded despite being available in an {@glink builds/guides/predefined-builds/overview editor build}.
+ * The list of plugins which should not be loaded despite being available in an {@glink installation/advanced/alternative-setups/predefined-builds editor build}.
  *
  *		const config = {
  *			removePlugins: [ 'Bold', 'Italic' ]

package/src/multicommand.js

@@ -5,6 +5,8 @@
 
 import Command from './command';
 
+import insertToPriorityArray from '@ckeditor/ckeditor5-utils/src/inserttopriorityarray';
+
 /**
  * @module core/multicommand
  */
@@ -14,16 +16,17 @@ import Command from './command';
  *
  * This command is used to proxy multiple commands. The multi-command is enabled when
  * at least one of its registered child commands is enabled.
- * When executing a multi-command the first command that is enabled will be executed.
+ * When executing a multi-command the first enabled command with highest priority will be executed.
  *
  *		const multiCommand = new MultiCommand( editor );
  *
  *		const commandFoo = new Command( editor );
  *		const commandBar = new Command( editor );
  *
- *		// Register child commands.
+ *		// Register a child command.
  *		multiCommand.registerChildCommand( commandFoo );
- *		multiCommand.registerChildCommand( commandBar );
+ *		// Register a child command with a low priority.
+ *		multiCommand.registerChildCommand( commandBar, { priority: 'low' } );
  *
  *		// Enable one of the commands.
  *		commandBar.isEnabled = true;
@@ -40,12 +43,12 @@ export default class MultiCommand extends Command {
 		super( editor );
 
 		/**
-		 * Registered child commands.
+		 * Registered child commands definitions.
 		 *
-		 * @type {Array.<module:core/command~Command>}
+		 * @type {Array.<Object>}
 		 * @private
 		 */
-		this._childCommands = [];
+		this._childCommandsDefinitions = [];
 	}
 
 	/**
@@ -56,23 +59,25 @@ export default class MultiCommand extends Command {
 	}
 
 	/**
-	 * Executes the first of it registered child commands.
+	 * Executes the first enabled command which has the highest priority of all registered child commands.
 	 *
 	 * @returns {*} The value returned by the {@link module:core/command~Command#execute `command.execute()`}.
 	 */
 	execute( ...args ) {
 		const command = this._getFirstEnabledCommand();
 
-		return command != null && command.execute( args );
+		return !!command && command.execute( args );
 	}
 
 	/**
 	 * Registers a child command.
 	 *
 	 * @param {module:core/command~Command} command
+	 * @param {Object} options An object with configuration options.
+	 * @param {module:utils/priorities~PriorityString} [options.priority='normal'] Priority of a command to register.
 	 */
-	registerChildCommand( command ) {
-		this._childCommands.push( command );
+	registerChildCommand( command, options = { priority: 'normal' } ) {
+		insertToPriorityArray( this._childCommandsDefinitions, { command, priority: options.priority } );
 
 		// Change multi command enabled state when one of registered commands changes state.
 		command.on( 'change:isEnabled', () => this._checkEnabled() );
@@ -90,12 +95,14 @@ export default class MultiCommand extends Command {
 	}
 
 	/**
-	 * Returns a first enabled command or undefined if none of them is enabled.
+	 * Returns a first enabled command with the highest priority or `undefined` if none of them is enabled.
 	 *
 	 * @returns {module:core/command~Command|undefined}
 	 * @private
 	 */
 	_getFirstEnabledCommand() {
-		return this._childCommands.find( command => command.isEnabled );
+		const commandDefinition = this._childCommandsDefinitions.find( ( { command } ) => command.isEnabled );
+
+		return commandDefinition && commandDefinition.command;
 	}
 }

package/src/pendingactions.js

@@ -48,7 +48,7 @@ import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
  *
  * This plugin is used by features like {@link module:upload/filerepository~FileRepository} to register their ongoing actions
  * and by features like {@link module:autosave/autosave~Autosave} to detect whether there are any ongoing actions.
- * Read more about saving the data in the {@glink builds/guides/integration/saving-data Saving and getting data} guide.
+ * Read more about saving the data in the {@glink installation/advanced/saving-data Saving and getting data} guide.
  *
  * @extends module:core/contextplugin~ContextPlugin
  */

package/src/plugincollection.js

@@ -324,7 +324,7 @@ export default class PluginCollection {
 				 *
 				 * Soft requirements were introduced in version 26.0.0. If you happen to stumble upon this error
 				 * when upgrading to version 26.0.0, read also the
-				 * {@glink builds/guides/migration/migration-to-26 Migration to 26.0.0} guide.
+				 * {@glink updating/migration-to-26 Migration to 26.0.0} guide.
 				 *
 				 * @error plugincollection-soft-required
 				 * @param {String} missingPlugin The name of the required plugin.
@@ -344,16 +344,17 @@ export default class PluginCollection {
 			 * This is usually done in CKEditor 5 builds by setting the {@link module:core/editor/editor~Editor.builtinPlugins}
 			 * property.
 			 *
-			 * **If you see this warning when using one of the {@glink builds/index CKEditor 5 Builds}**, it means
-			 * that you try to enable a plugin which was not included in that build. This may be due to a typo
+			 * **If you see this warning when using one of the {@glink installation/advanced/alternative-setups/predefined-builds
+			 * CKEditor 5 Builds}**,
+			 * it means that you try to enable a plugin which was not included in that build. This may be due to a typo
 			 * in the plugin name or simply because that plugin is not a part of this build. In the latter scenario,
-			 * read more about {@glink builds/guides/development/custom-builds custom builds}.
+			 * read more about {@glink installation/getting-started/quick-start custom builds}.
 			 *
 			 * **If you see this warning when using one of the editor creators directly** (not a build), then it means
 			 * that you tried loading plugins by name. However, unlike CKEditor 4, CKEditor 5 does not implement a "plugin loader".
 			 * This means that CKEditor 5 does not know where to load the plugin modules from. Therefore, you need to
 			 * provide each plugin through a reference (as a constructor function). Check out the examples in
-			 * {@glink builds/guides/integration/advanced-setup#scenario-2-building-from-source "Building from source"}.
+			 * {@glink installation/advanced/alternative-setups/integrating-from-source "Building from source"}.
 			 *
 			 * @error plugincollection-plugin-not-found
 			 * @param {String} plugin The name of the plugin which could not be loaded.
@@ -576,7 +577,7 @@ export default class PluginCollection {
 			 * They are already built into that editor build and now get added for the second time as dependencies
 			 * of the plugin you are installing.
 			 *
-			 * Read more about {@glink builds/guides/integration/installing-plugins installing plugins}.
+			 * Read more about {@glink installation/getting-started/installing-plugins installing plugins}.
 			 *
 			 * @error plugincollection-plugin-name-conflict
 			 * @param {String} pluginName The duplicated plugin name.