@ckeditor/ckeditor5-core 36.0.0 → 37.0.0-alpha.0

package/README.md

@@ -10,7 +10,7 @@ This package implements CKEditor 5's core editor architecture — a set of c
 
 ## Documentation
 
-For general introduction see the [Overview of CKEditor 5 framework](https://ckeditor.com/docs/ckeditor5/latest/framework/guides/overview.html) guide and then the [core editor architecture guide](https://ckeditor.com/docs/ckeditor5/latest/framework/guides/architecture/core-editor-architecture.html).
+For general introduction see the [Overview of CKEditor 5 framework](https://ckeditor.com/docs/ckeditor5/latest/framework/index.html) guide and then the [core editor architecture guide](https://ckeditor.com/docs/ckeditor5/latest/framework/architecture/core-editor-architecture.html).
 
 Additionally, see the [`@ckeditor/ckeditor5-core` package](https://ckeditor.com/docs/ckeditor5/latest/api/core.html) page in [CKEditor 5 documentation](https://ckeditor.com/docs/ckeditor5/latest/) for even more information.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-core",
-  "version": "36.0.0",
+  "version": "37.0.0-alpha.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": "^36.0.0",
-    "@ckeditor/ckeditor5-utils": "^36.0.0",
+    "@ckeditor/ckeditor5-engine": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-utils": "^37.0.0-alpha.0",
     "lodash-es": "^4.17.15"
   },
   "devDependencies": {
-    "@ckeditor/ckeditor5-autoformat": "^36.0.0",
-    "@ckeditor/ckeditor5-basic-styles": "^36.0.0",
-    "@ckeditor/ckeditor5-block-quote": "^36.0.0",
-    "@ckeditor/ckeditor5-editor-classic": "^36.0.0",
-    "@ckeditor/ckeditor5-essentials": "^36.0.0",
-    "@ckeditor/ckeditor5-heading": "^36.0.0",
-    "@ckeditor/ckeditor5-image": "^36.0.0",
-    "@ckeditor/ckeditor5-indent": "^36.0.0",
-    "@ckeditor/ckeditor5-link": "^36.0.0",
-    "@ckeditor/ckeditor5-list": "^36.0.0",
-    "@ckeditor/ckeditor5-media-embed": "^36.0.0",
-    "@ckeditor/ckeditor5-paragraph": "^36.0.0",
-    "@ckeditor/ckeditor5-table": "^36.0.0",
-    "@ckeditor/ckeditor5-ui": "^36.0.0",
+    "@ckeditor/ckeditor5-autoformat": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-basic-styles": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-block-quote": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-editor-classic": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-essentials": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-heading": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-image": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-indent": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-link": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-list": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-media-embed": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-paragraph": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-table": "^37.0.0-alpha.0",
+    "@ckeditor/ckeditor5-ui": "^37.0.0-alpha.0",
     "typescript": "^4.8.4",
     "webpack": "^5.58.1",
     "webpack-cli": "^4.9.0"
@@ -70,5 +70,6 @@
   "scripts": {
     "build": "tsc -p ./tsconfig.release.json",
     "postversion": "npm run build"
-  }
+  },
+  "types": "src/index.d.ts"
 }

package/src/command.d.ts

@@ -0,0 +1,178 @@
+/**
+ * @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 core/command
+ */
+import { type DecoratedMethodEvent } from '@ckeditor/ckeditor5-utils';
+import type Editor from './editor/editor';
+declare const Command_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+};
+/**
+ * Base class for the CKEditor commands.
+ *
+ * Commands are the main way to manipulate the editor contents and state. They are mostly used by UI elements (or by other
+ * commands) to make changes in the model. Commands are available in every part of the code that has access to
+ * the {@link module:core/editor/editor~Editor editor} instance.
+ *
+ * Instances of registered commands can be retrieved from {@link module:core/editor/editor~Editor#commands `editor.commands`}.
+ * The easiest way to execute a command is through {@link module:core/editor/editor~Editor#execute `editor.execute()`}.
+ *
+ * By default, commands are disabled when the editor is in the {@link module:core/editor/editor~Editor#isReadOnly read-only} mode
+ * but commands with the {@link module:core/command~Command#affectsData `affectsData`} flag set to `false` will not be disabled.
+ */
+export default class Command extends Command_base {
+    /**
+     * The editor on which this command will be used.
+     */
+    readonly editor: Editor;
+    /**
+     * The value of the command. A given command class should define what it represents for it.
+     *
+     * For example, the `'bold'` command's value indicates whether the selection starts in a bolded text.
+     * And the value of the `'link'` command may be an object with link details.
+     *
+     * It is possible for a command to have no value (e.g. for stateless actions such as `'uploadImage'`).
+     *
+     * A given command class should control this value by overriding the {@link #refresh `refresh()`} method.
+     *
+     * @observable
+     * @readonly
+     */
+    value: unknown;
+    /**
+     * Flag indicating whether a command is enabled or disabled.
+     * A disabled command will do nothing when executed.
+     *
+     * A given command class should control this value by overriding the {@link #refresh `refresh()`} method.
+     *
+     * It is possible to disable a command "from outside" using {@link #forceDisabled} method.
+     *
+     * @observable
+     * @readonly
+     */
+    isEnabled: boolean;
+    /**
+     * A flag indicating whether a command execution changes the editor data or not.
+     *
+     * @see #affectsData
+     */
+    private _affectsData;
+    /**
+     * Holds identifiers for {@link #forceDisabled} mechanism.
+     */
+    private readonly _disableStack;
+    /**
+     * Creates a new `Command` instance.
+     *
+     * @param editor The editor on which this command will be used.
+     */
+    constructor(editor: Editor);
+    /**
+     * A flag indicating whether a command execution changes the editor data or not.
+     *
+     * Commands with `affectsData` set to `false` will not be automatically disabled in
+     * the {@link module:core/editor/editor~Editor#isReadOnly read-only mode} and
+     * {@glink features/read-only#related-features other editor modes} with restricted user write permissions.
+     *
+     * **Note:** You do not have to set it for your every command. It is `true` by default.
+     *
+     * @default true
+     */
+    get affectsData(): boolean;
+    protected set affectsData(affectsData: boolean);
+    /**
+     * Refreshes the command. The command should update its {@link #isEnabled} and {@link #value} properties
+     * in this method.
+     *
+     * This method is automatically called when
+     * {@link module:engine/model/document~Document#event:change any changes are applied to the document}.
+     */
+    refresh(): void;
+    /**
+     * Disables the command.
+     *
+     * Command may be disabled by multiple features or algorithms (at once). When disabling a command, unique id should be passed
+     * (e.g. the feature name). The same identifier should be used when {@link #clearForceDisabled enabling back} the command.
+     * The command becomes enabled only after all features {@link #clearForceDisabled enabled it back}.
+     *
+     * Disabling and enabling a command:
+     *
+     * ```ts
+     * command.isEnabled; // -> true
+     * command.forceDisabled( 'MyFeature' );
+     * command.isEnabled; // -> false
+     * command.clearForceDisabled( 'MyFeature' );
+     * command.isEnabled; // -> true
+     * ```
+     *
+     * Command disabled by multiple features:
+     *
+     * ```ts
+     * command.forceDisabled( 'MyFeature' );
+     * command.forceDisabled( 'OtherFeature' );
+     * command.clearForceDisabled( 'MyFeature' );
+     * command.isEnabled; // -> false
+     * command.clearForceDisabled( 'OtherFeature' );
+     * command.isEnabled; // -> true
+     * ```
+     *
+     * Multiple disabling with the same identifier is redundant:
+     *
+     * ```ts
+     * command.forceDisabled( 'MyFeature' );
+     * command.forceDisabled( 'MyFeature' );
+     * command.clearForceDisabled( 'MyFeature' );
+     * command.isEnabled; // -> true
+     * ```
+     *
+     * **Note:** some commands or algorithms may have more complex logic when it comes to enabling or disabling certain commands,
+     * so the command might be still disabled after {@link #clearForceDisabled} was used.
+     *
+     * @param id Unique identifier for disabling. Use the same id when {@link #clearForceDisabled enabling back} the command.
+     */
+    forceDisabled(id: string): void;
+    /**
+     * Clears forced disable previously set through {@link #forceDisabled}. See {@link #forceDisabled}.
+     *
+     * @param id Unique identifier, equal to the one passed in {@link #forceDisabled} call.
+     */
+    clearForceDisabled(id: string): void;
+    /**
+     * Executes the command.
+     *
+     * A command may accept parameters. They will be passed from {@link module:core/editor/editor~Editor#execute `editor.execute()`}
+     * to the command.
+     *
+     * The `execute()` method will automatically abort when the command is disabled ({@link #isEnabled} is `false`).
+     * This behavior is implemented by a high priority listener to the {@link #event:execute} event.
+     *
+     * In order to see how to disable a command from "outside" see the {@link #isEnabled} documentation.
+     *
+     * This method may return a value, which would be forwarded all the way down to the
+     * {@link module:core/editor/editor~Editor#execute `editor.execute()`}.
+     *
+     * @fires execute
+     */
+    execute(...args: Array<unknown>): unknown;
+    /**
+     * Destroys the command.
+     */
+    destroy(): void;
+}
+/**
+ * Event fired by the {@link ~Command#execute} method. The command action is a listener to this event so it's
+ * possible to change/cancel the behavior of the command by listening to this event.
+ *
+ * See {@link module:utils/observablemixin~Observable#decorate} for more information and samples.
+ *
+ * **Note:** This event is fired even if command is disabled. However, it is automatically blocked
+ * by a high priority listener in order to prevent command execution.
+ *
+ * @eventName execute
+ */
+export type CommandExecuteEvent = DecoratedMethodEvent<Command, 'execute'>;
+export {};

package/src/command.js

@@ -18,99 +18,19 @@ import { ObservableMixin } from '@ckeditor/ckeditor5-utils';
  *
  * By default, commands are disabled when the editor is in the {@link module:core/editor/editor~Editor#isReadOnly read-only} mode
  * but commands with the {@link module:core/command~Command#affectsData `affectsData`} flag set to `false` will not be disabled.
- *
- * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class Command extends ObservableMixin() {
     /**
      * Creates a new `Command` instance.
      *
-     * @param {module:core/editor/editor~Editor} editor The editor on which this command will be used.
+     * @param editor The editor on which this command will be used.
      */
     constructor(editor) {
         super();
-        /**
-         * The editor on which this command will be used.
-         *
-         * @readonly
-         * @member {module:core/editor/editor~Editor}
-         */
         this.editor = editor;
-        /**
-         * The value of the command. A given command class should define what it represents for it.
-         *
-         * For example, the `'bold'` command's value indicates whether the selection starts in a bolded text.
-         * And the value of the `'link'` command may be an object with link details.
-         *
-         * It is possible for a command to have no value (e.g. for stateless actions such as `'uploadImage'`).
-         *
-         * A given command class should control this value by overriding the {@link #refresh `refresh()`} method.
-         *
-         * @observable
-         * @readonly
-         * @member #value
-         */
         this.set('value', undefined);
-        /**
-         * Flag indicating whether a command is enabled or disabled.
-         * A disabled command will do nothing when executed.
-         *
-         * A given command class should control this value by overriding the {@link #refresh `refresh()`} method.
-         *
-         * It is possible to disable a command "from outside". For instance, in your integration you may want to disable
-         * a certain set of commands for the time being. To do that, you can use the fact that `isEnabled` is observable
-         * and it fires the `set:isEnabled` event every time anyone tries to modify its value:
-         *
-         *		function disableCommand( cmd ) {
-         *			cmd.on( 'set:isEnabled', forceDisable, { priority: 'highest' } );
-         *
-         *			cmd.isEnabled = false;
-         *
-         *			// Make it possible to enable the command again.
-         *			return () => {
-         *				cmd.off( 'set:isEnabled', forceDisable );
-         *				cmd.refresh();
-         *			};
-         *
-         *			function forceDisable( evt ) {
-         *				evt.return = false;
-         *				evt.stop();
-         *			}
-         *		}
-         *
-         *		// Usage:
-         *
-         *		// Disabling the command.
-         *		const enableBold = disableCommand( editor.commands.get( 'bold' ) );
-         *
-         *		// Enabling the command again.
-         *		enableBold();
-         *
-         * @observable
-         * @readonly
-         * @member {Boolean} #isEnabled
-         */
         this.set('isEnabled', false);
-        /**
-         * A flag indicating whether a command execution changes the editor data or not.
-         *
-         * Commands with `affectsData` set to `false` will not be automatically disabled in
-         * the {@link module:core/editor/editor~Editor#isReadOnly read-only mode} and
-         * {@glink features/read-only#related-features other editor modes} with restricted user write permissions.
-         *
-         * **Note:** You do not have to set it for your every command. It is `true` by default.
-         *
-         * @readonly
-         * @default true
-         * @member {Boolean} #affectsData
-         */
         this._affectsData = true;
-        /**
-         * Holds identifiers for {@link #forceDisabled} mechanism.
-         *
-         * @type {Set.<String>}
-         * @private
-         */
         this._disableStack = new Set();
         this.decorate('execute');
         // By default every command is refreshed when changes are applied to the model.
@@ -132,6 +52,17 @@ export default class Command extends ObservableMixin() {
             }
         });
     }
+    /**
+     * A flag indicating whether a command execution changes the editor data or not.
+     *
+     * Commands with `affectsData` set to `false` will not be automatically disabled in
+     * the {@link module:core/editor/editor~Editor#isReadOnly read-only mode} and
+     * {@glink features/read-only#related-features other editor modes} with restricted user write permissions.
+     *
+     * **Note:** You do not have to set it for your every command. It is `true` by default.
+     *
+     * @default true
+     */
     get affectsData() {
         return this._affectsData;
     }
@@ -157,32 +88,38 @@ export default class Command extends ObservableMixin() {
      *
      * Disabling and enabling a command:
      *
-     *		command.isEnabled; // -> true
-     *		command.forceDisabled( 'MyFeature' );
-     *		command.isEnabled; // -> false
-     *		command.clearForceDisabled( 'MyFeature' );
-     *		command.isEnabled; // -> true
+     * ```ts
+     * command.isEnabled; // -> true
+     * command.forceDisabled( 'MyFeature' );
+     * command.isEnabled; // -> false
+     * command.clearForceDisabled( 'MyFeature' );
+     * command.isEnabled; // -> true
+     * ```
      *
      * Command disabled by multiple features:
      *
-     *		command.forceDisabled( 'MyFeature' );
-     *		command.forceDisabled( 'OtherFeature' );
-     *		command.clearForceDisabled( 'MyFeature' );
-     *		command.isEnabled; // -> false
-     *		command.clearForceDisabled( 'OtherFeature' );
-     *		command.isEnabled; // -> true
+     * ```ts
+     * command.forceDisabled( 'MyFeature' );
+     * command.forceDisabled( 'OtherFeature' );
+     * command.clearForceDisabled( 'MyFeature' );
+     * command.isEnabled; // -> false
+     * command.clearForceDisabled( 'OtherFeature' );
+     * command.isEnabled; // -> true
+     * ```
      *
      * Multiple disabling with the same identifier is redundant:
      *
-     *		command.forceDisabled( 'MyFeature' );
-     *		command.forceDisabled( 'MyFeature' );
-     *		command.clearForceDisabled( 'MyFeature' );
-     *		command.isEnabled; // -> true
+     * ```ts
+     * command.forceDisabled( 'MyFeature' );
+     * command.forceDisabled( 'MyFeature' );
+     * command.clearForceDisabled( 'MyFeature' );
+     * command.isEnabled; // -> true
+     * ```
      *
      * **Note:** some commands or algorithms may have more complex logic when it comes to enabling or disabling certain commands,
      * so the command might be still disabled after {@link #clearForceDisabled} was used.
      *
-     * @param {String} id Unique identifier for disabling. Use the same id when {@link #clearForceDisabled enabling back} the command.
+     * @param id Unique identifier for disabling. Use the same id when {@link #clearForceDisabled enabling back} the command.
      */
     forceDisabled(id) {
         this._disableStack.add(id);
@@ -194,7 +131,7 @@ export default class Command extends ObservableMixin() {
     /**
      * Clears forced disable previously set through {@link #forceDisabled}. See {@link #forceDisabled}.
      *
-     * @param {String} id Unique identifier, equal to the one passed in {@link #forceDisabled} call.
+     * @param id Unique identifier, equal to the one passed in {@link #forceDisabled} call.
      */
     clearForceDisabled(id) {
         this._disableStack.delete(id);
@@ -227,7 +164,9 @@ export default class Command extends ObservableMixin() {
         this.stopListening();
     }
 }
-// Helper function that forces command to be disabled.
+/**
+ * Helper function that forces command to be disabled.
+ */
 function forceDisable(evt) {
     evt.return = false;
     evt.stop();

package/src/commandcollection.d.ts

@@ -0,0 +1,83 @@
+/**
+ * @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
+ */
+import type Command from './command';
+/**
+ * Collection of commands. Its instance is available in {@link module:core/editor/editor~Editor#commands `editor.commands`}.
+ */
+export default class CommandCollection implements Iterable<[string, Command]> {
+    /**
+     * Command map.
+     */
+    private _commands;
+    /**
+     * Creates collection instance.
+     */
+    constructor();
+    /**
+     * Registers a new command.
+     *
+     * @param commandName The name of the command.
+     */
+    add<TName extends string>(commandName: TName, command: CommandsMap[TName]): void;
+    /**
+     * Retrieves a command from the collection.
+     *
+     * @param commandName The name of the command.
+     */
+    get<TName extends string>(commandName: TName): CommandsMap[TName] | undefined;
+    /**
+     * Executes a command.
+     *
+     * @param commandName The name of the command.
+     * @param commandParams Command parameters.
+     * @returns The value returned by the {@link module:core/command~Command#execute `command.execute()`}.
+     */
+    execute<TName extends string>(commandName: TName, ...commandParams: Parameters<CommandsMap[TName]['execute']>): ReturnType<CommandsMap[TName]['execute']>;
+    /**
+     * Returns iterator of command names.
+     */
+    names(): IterableIterator<string>;
+    /**
+     * Returns iterator of command instances.
+     */
+    commands(): IterableIterator<Command>;
+    /**
+     * Iterable interface.
+     *
+     * Returns `[ commandName, commandInstance ]` pairs.
+     */
+    [Symbol.iterator](): Iterator<[string, Command]>;
+    /**
+     * Destroys all collection commands.
+     */
+    destroy(): void;
+}
+/**
+ * Helper type that maps command names to their types.
+ * It is meant to be extended with module augmentation.
+ *
+ * ```ts
+ * class MyCommand extends Command {
+ * 	public execute( parameter: A ): B {
+ * 		// ...
+ * 	}
+ * }
+ *
+ * declare module '@ckeditor/ckeditor5-core' {
+ * 	interface CommandsMap {
+ * 		myCommand: MyCommand;
+ * 	}
+ * }
+ *
+ * // Returns `MyCommand | undefined`.
+ * const myCommand = editor.commands.get( 'myCommand' );
+ *
+ * // Expects `A` type as parameter and returns `B`.
+ * const value = editor.commands.execute( 'myCommand', new A() );
+ * ```
+ */
+export interface CommandsMap {
+    [name: string]: Command;
+}

package/src/commandcollection.js

@@ -14,19 +14,12 @@ export default class CommandCollection {
      * Creates collection instance.
      */
     constructor() {
-        /**
-         * Command map.
-         *
-         * @private
-         * @member {Map}
-         */
         this._commands = new Map();
     }
     /**
      * Registers a new command.
      *
-     * @param {String} commandName The name of the command.
-     * @param {module:core/command~Command} command
+     * @param commandName The name of the command.
      */
     add(commandName, command) {
         this._commands.set(commandName, command);
@@ -34,8 +27,7 @@ export default class CommandCollection {
     /**
      * Retrieves a command from the collection.
      *
-     * @param {String} commandName The name of the command.
-     * @returns {module:core/command~Command}
+     * @param commandName The name of the command.
      */
     get(commandName) {
         return this._commands.get(commandName);
@@ -43,35 +35,31 @@ export default class CommandCollection {
     /**
      * Executes a command.
      *
-     * @param {String} commandName The name of the command.
-     * @param {*} [...commandParams] Command parameters.
-     * @returns {*} The value returned by the {@link module:core/command~Command#execute `command.execute()`}.
+     * @param commandName The name of the command.
+     * @param commandParams Command parameters.
+     * @returns The value returned by the {@link module:core/command~Command#execute `command.execute()`}.
      */
-    execute(commandName, ...args) {
+    execute(commandName, ...commandParams) {
         const command = this.get(commandName);
         if (!command) {
             /**
              * Command does not exist.
              *
              * @error commandcollection-command-not-found
-             * @param {String} commandName Name of the command.
+             * @param commandName Name of the command.
              */
             throw new CKEditorError('commandcollection-command-not-found', this, { commandName });
         }
-        return command.execute(...args);
+        return command.execute(...commandParams);
     }
     /**
      * Returns iterator of command names.
-     *
-     * @returns {Iterable.<String>}
      */
     *names() {
         yield* this._commands.keys();
     }
     /**
      * Returns iterator of command instances.
-     *
-     * @returns {Iterable.<module:core/command~Command>}
      */
     *commands() {
         yield* this._commands.values();
@@ -80,8 +68,6 @@ export default class CommandCollection {
      * Iterable interface.
      *
      * Returns `[ commandName, commandInstance ]` pairs.
-     *
-     * @returns {Iterator.<Array>}
      */
     [Symbol.iterator]() {
         return this._commands[Symbol.iterator]();