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

package/src/editor/utils/securesourceelement.js

@@ -2,17 +2,17 @@
  * @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 { CKEditorError } from '@ckeditor/ckeditor5-utils';
 /**
  * @module core/editor/utils/securesourceelement
  */
+import { CKEditorError } from '@ckeditor/ckeditor5-utils';
 /**
  * Marks the source element on which the editor was initialized. This prevents other editor instances from using this element.
  *
  * Running multiple editor instances on the same source element causes various issues and it is
  * crucial this helper is called as soon as the source element is known to prevent collisions.
  *
- * @param {module:core/editor/editor~Editor} editor Editor instance.
+ * @param editor Editor instance.
  */
 export default function secureSourceElement(editor) {
     const sourceElement = editor.sourceElement;
@@ -28,7 +28,7 @@ export default function secureSourceElement(editor) {
          * created with an unique DOM element.
          *
          * @error editor-source-element-already-used
-         * @param {HTMLElement} element DOM element that caused the collision.
+         * @param element DOM element that caused the collision.
          */
         throw new CKEditorError('editor-source-element-already-used', editor);
     }

package/src/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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
+ */
+export { default as Plugin, type PluginDependencies, type PluginConstructor } from './plugin';
+export { default as Command, type CommandExecuteEvent } from './command';
+export { default as MultiCommand } from './multicommand';
+export type { CommandsMap } from './commandcollection';
+export type { PluginsMap, default as PluginCollection } from './plugincollection';
+export { default as Context, type ContextConfig } from './context';
+export { default as ContextPlugin, type ContextPluginDependencies } from './contextplugin';
+export { type EditingKeystrokeCallback } from './editingkeystrokehandler';
+export { default as Editor, type EditorReadyEvent, type EditorDestroyEvent } from './editor/editor';
+export type { EditorConfig, LanguageConfig, ToolbarConfig, ToolbarConfigItem } from './editor/editorconfig';
+export { default as attachToForm } from './editor/utils/attachtoform';
+export { default as DataApiMixin, type DataApi } from './editor/utils/dataapimixin';
+export { default as ElementApiMixin, type ElementApi } from './editor/utils/elementapimixin';
+export { default as secureSourceElement } from './editor/utils/securesourceelement';
+export { default as PendingActions, type PendingAction } from './pendingactions';
+export declare const icons: {
+    bold: string;
+    cancel: string;
+    caption: string;
+    check: string;
+    cog: string;
+    eraser: string;
+    image: string;
+    lowVision: string;
+    importExport: string;
+    paragraph: string;
+    plus: string;
+    text: string;
+    alignBottom: string;
+    alignMiddle: string;
+    alignTop: string;
+    alignLeft: string;
+    alignCenter: string;
+    alignRight: string;
+    alignJustify: string;
+    objectLeft: string;
+    objectCenter: string;
+    objectRight: string;
+    objectFullWidth: string;
+    objectInline: string;
+    objectBlockLeft: string;
+    objectBlockRight: string;
+    objectSizeFull: string;
+    objectSizeLarge: string;
+    objectSizeSmall: string;
+    objectSizeMedium: string;
+    pencil: string;
+    pilcrow: string;
+    quote: string;
+    threeVerticalDots: string;
+};

package/src/multicommand.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @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/multicommand
+ */
+import Command from './command';
+import { type PriorityString } from '@ckeditor/ckeditor5-utils';
+/**
+ * A CKEditor command that aggregates other commands.
+ *
+ * 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 enabled command with highest priority will be executed.
+ *
+ * ```ts
+ * const multiCommand = new MultiCommand( editor );
+ *
+ * const commandFoo = new Command( editor );
+ * const commandBar = new Command( editor );
+ *
+ * // Register a child command.
+ * multiCommand.registerChildCommand( commandFoo );
+ * // Register a child command with a low priority.
+ * multiCommand.registerChildCommand( commandBar, { priority: 'low' } );
+ *
+ * // Enable one of the commands.
+ * commandBar.isEnabled = true;
+ *
+ * multiCommand.execute(); // Will execute commandBar.
+ * ```
+ */
+export default class MultiCommand extends Command {
+    /**
+     * Registered child commands definitions.
+     */
+    private _childCommandsDefinitions;
+    /**
+     * @inheritDoc
+     */
+    refresh(): void;
+    /**
+     * 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: Array<unknown>): unknown;
+    /**
+     * Registers a child command.
+     *
+     * @param options An object with configuration options.
+     * @param options.priority Priority of a command to register.
+     */
+    registerChildCommand(command: Command, options?: {
+        priority?: PriorityString;
+    }): void;
+    /**
+     * Checks if any of child commands is enabled.
+     */
+    private _checkEnabled;
+    /**
+     * Returns a first enabled command with the highest priority or `undefined` if none of them is enabled.
+     */
+    private _getFirstEnabledCommand;
+}

package/src/multicommand.js

@@ -2,11 +2,11 @@
  * @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 Command from './command';
-import { insertToPriorityArray } from '@ckeditor/ckeditor5-utils';
 /**
  * @module core/multicommand
  */
+import Command from './command';
+import { insertToPriorityArray } from '@ckeditor/ckeditor5-utils';
 /**
  * A CKEditor command that aggregates other commands.
  *
@@ -14,34 +14,28 @@ import { insertToPriorityArray } from '@ckeditor/ckeditor5-utils';
  * at least one of its registered child commands is enabled.
  * 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 );
+ * ```ts
+ * const multiCommand = new MultiCommand( editor );
  *
- *		// Register a child command.
- *		multiCommand.registerChildCommand( commandFoo );
- *		// Register a child command with a low priority.
- *		multiCommand.registerChildCommand( commandBar, { priority: 'low' } );
+ * const commandFoo = new Command( editor );
+ * const commandBar = new Command( editor );
  *
- *		// Enable one of the commands.
- *		commandBar.isEnabled = true;
+ * // Register a child command.
+ * multiCommand.registerChildCommand( commandFoo );
+ * // Register a child command with a low priority.
+ * multiCommand.registerChildCommand( commandBar, { priority: 'low' } );
  *
- *		multiCommand.execute(); // Will execute commandBar.
+ * // Enable one of the commands.
+ * commandBar.isEnabled = true;
  *
- * @extends module:core/command~Command
+ * multiCommand.execute(); // Will execute commandBar.
+ * ```
  */
 export default class MultiCommand extends Command {
-    /**
-     * @inheritDoc
-     */
-    constructor(editor) {
-        super(editor);
+    constructor() {
+        super(...arguments);
         /**
          * Registered child commands definitions.
-         *
-         * @type {Array.<Object>}
-         * @private
          */
         this._childCommandsDefinitions = [];
     }
@@ -54,7 +48,7 @@ export default class MultiCommand extends Command {
     /**
      * 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()`}.
+     * @returns The value returned by the {@link module:core/command~Command#execute `command.execute()`}.
      */
     execute(...args) {
         const command = this._getFirstEnabledCommand();
@@ -63,9 +57,8 @@ export default class MultiCommand extends Command {
     /**
      * 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.
+     * @param options An object with configuration options.
+     * @param options.priority Priority of a command to register.
      */
     registerChildCommand(command, options = {}) {
         insertToPriorityArray(this._childCommandsDefinitions, { command, priority: options.priority || 'normal' });
@@ -75,17 +68,12 @@ export default class MultiCommand extends Command {
     }
     /**
      * Checks if any of child commands is enabled.
-     *
-     * @private
      */
     _checkEnabled() {
         this.isEnabled = !!this._getFirstEnabledCommand();
     }
     /**
      * 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() {
         const commandDefinition = this._childCommandsDefinitions.find(({ command }) => command.isEnabled);

package/src/pendingactions.d.ts

@@ -0,0 +1,122 @@
+/**
+ * @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/pendingactions
+ */
+import ContextPlugin from './contextplugin';
+import { type CollectionAddEvent, type CollectionRemoveEvent, type Observable } from '@ckeditor/ckeditor5-utils';
+/**
+ * The list of pending editor actions.
+ *
+ * This plugin should be used to synchronise plugins that execute long-lasting actions
+ * (e.g. file upload) with the editor integration. It gives the developer who integrates the editor
+ * an easy way to check if there are any actions pending whenever such information is needed.
+ * All plugins that register a pending action also provide a message about the action that is ongoing
+ * which can be displayed to the user. This lets them decide if they want to interrupt the action or wait.
+ *
+ * Adding and updating a pending action:
+ *
+ * ```ts
+ * const pendingActions = editor.plugins.get( 'PendingActions' );
+ * const action = pendingActions.add( 'Upload in progress: 0%.' );
+ *
+ * // You can update the message:
+ * action.message = 'Upload in progress: 10%.';
+ * ```
+ *
+ * Removing a pending action:
+ *
+ * ```ts
+ * const pendingActions = editor.plugins.get( 'PendingActions' );
+ * const action = pendingActions.add( 'Unsaved changes.' );
+ *
+ * pendingActions.remove( action );
+ * ```
+ *
+ * Getting pending actions:
+ *
+ * ```ts
+ * const pendingActions = editor.plugins.get( 'PendingActions' );
+ *
+ * const action1 = pendingActions.add( 'Action 1' );
+ * const action2 = pendingActions.add( 'Action 2' );
+ *
+ * pendingActions.first; // Returns action1
+ * Array.from( pendingActions ); // Returns [ action1, action2 ]
+ * ```
+ *
+ * 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 installation/getting-started/getting-and-setting-data Saving and getting data} guide.
+ */
+export default class PendingActions extends ContextPlugin implements Iterable<PendingAction> {
+    /**
+     * Defines whether there is any registered pending action.
+     *
+     * @readonly
+     * @observable
+     */
+    hasAny: boolean;
+    /**
+     * A list of pending actions.
+     */
+    private _actions;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): 'PendingActions';
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Adds an action to the list of pending actions.
+     *
+     * This method returns an action object with an observable message property.
+     * The action object can be later used in the {@link #remove} method. It also allows you to change the message.
+     *
+     * @param message The action message.
+     * @returns An observable object that represents a pending action.
+     */
+    add(message: string): PendingAction;
+    /**
+     * Removes an action from the list of pending actions.
+     *
+     * @param action An action object.
+     */
+    remove(action: PendingAction): void;
+    /**
+     * Returns the first action from the list or null if the list is empty
+     *
+     * @returns The pending action object.
+     */
+    get first(): PendingAction | null;
+    /**
+     * Iterable interface.
+     */
+    [Symbol.iterator](): Iterator<PendingAction>;
+}
+export interface PendingAction extends Observable {
+    message: string;
+}
+/**
+ * Fired when an action is added to the list.
+ *
+ * @eventName add
+ * @param action The added action.
+ */
+export type PendingActionsAddEvent = CollectionAddEvent<PendingAction>;
+/**
+ * Fired when an action is removed from the list.
+ *
+ * @eventName remove
+ * @param action The removed action.
+ */
+export type PendingActionsRemoveEvent = CollectionRemoveEvent<PendingAction>;
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [PendingActions.pluginName]: PendingActions;
+    }
+}

package/src/pendingactions.js

@@ -18,34 +18,38 @@ import { CKEditorError, Collection, ObservableMixin } from '@ckeditor/ckeditor5-
  *
  * Adding and updating a pending action:
  *
- * 		const pendingActions = editor.plugins.get( 'PendingActions' );
- * 		const action = pendingActions.add( 'Upload in progress: 0%.' );
+ * ```ts
+ * const pendingActions = editor.plugins.get( 'PendingActions' );
+ * const action = pendingActions.add( 'Upload in progress: 0%.' );
  *
- *		// You can update the message:
- * 		action.message = 'Upload in progress: 10%.';
+ * // You can update the message:
+ * action.message = 'Upload in progress: 10%.';
+ * ```
  *
  * Removing a pending action:
  *
- * 		const pendingActions = editor.plugins.get( 'PendingActions' );
- * 		const action = pendingActions.add( 'Unsaved changes.' );
+ * ```ts
+ * const pendingActions = editor.plugins.get( 'PendingActions' );
+ * const action = pendingActions.add( 'Unsaved changes.' );
  *
- * 		pendingActions.remove( action );
+ * pendingActions.remove( action );
+ * ```
  *
  * Getting pending actions:
  *
- * 		const pendingActions = editor.plugins.get( 'PendingActions' );
+ * ```ts
+ * const pendingActions = editor.plugins.get( 'PendingActions' );
  *
- * 		const action1 = pendingActions.add( 'Action 1' );
- * 		const action2 = pendingActions.add( 'Action 2' );
+ * const action1 = pendingActions.add( 'Action 1' );
+ * const action2 = pendingActions.add( 'Action 2' );
  *
- * 		pendingActions.first; // Returns action1
- * 		Array.from( pendingActions ); // Returns [ action1, action2 ]
+ * pendingActions.first; // Returns action1
+ * Array.from( pendingActions ); // Returns [ action1, action2 ]
+ * ```
  *
  * 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 installation/getting-started/getting-and-setting-data Saving and getting data} guide.
- *
- * @extends module:core/contextplugin~ContextPlugin
  */
 export default class PendingActions extends ContextPlugin {
     /**
@@ -58,20 +62,7 @@ export default class PendingActions extends ContextPlugin {
      * @inheritDoc
      */
     init() {
-        /**
-         * Defines whether there is any registered pending action.
-         *
-         * @readonly
-         * @observable
-         * @member {Boolean} #hasAny
-         */
         this.set('hasAny', false);
-        /**
-         * A list of pending actions.
-         *
-         * @private
-         * @type {module:utils/collection~Collection}
-         */
         this._actions = new Collection({ idProperty: '_id' });
         this._actions.delegate('add', 'remove').to(this);
     }
@@ -81,8 +72,8 @@ export default class PendingActions extends ContextPlugin {
      * This method returns an action object with an observable message property.
      * The action object can be later used in the {@link #remove} method. It also allows you to change the message.
      *
-     * @param {String} message The action message.
-     * @returns {Object} An observable object that represents a pending action.
+     * @param message The action message.
+     * @returns An observable object that represents a pending action.
      */
     add(message) {
         if (typeof message !== 'string') {
@@ -102,7 +93,7 @@ export default class PendingActions extends ContextPlugin {
     /**
      * Removes an action from the list of pending actions.
      *
-     * @param {Object} action An action object.
+     * @param action An action object.
      */
     remove(action) {
         this._actions.remove(action);
@@ -111,15 +102,13 @@ export default class PendingActions extends ContextPlugin {
     /**
      * Returns the first action from the list or null if the list is empty
      *
-     * returns {Object|null} The pending action object.
+     * @returns The pending action object.
      */
     get first() {
         return this._actions.get(0);
     }
     /**
      * Iterable interface.
-     *
-     * @returns {Iterable.<*>}
      */
     [Symbol.iterator]() {
         return this._actions[Symbol.iterator]();