@ckeditor/ckeditor5-core 40.0.0 → 40.2.0

package/src/context.js

@@ -1,225 +1,225 @@
-/**
- * @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/context
- */
-import { Config, Collection, CKEditorError, Locale } from '@ckeditor/ckeditor5-utils';
-import PluginCollection from './plugincollection';
-/**
- * Provides a common, higher-level environment for solutions that use multiple {@link module:core/editor/editor~Editor editors}
- * or plugins that work outside the editor. Use it instead of {@link module:core/editor/editor~Editor.create `Editor.create()`}
- * in advanced application integrations.
- *
- * All configuration options passed to a context will be used as default options for the editor instances initialized in that context.
- *
- * {@link module:core/contextplugin~ContextPlugin Context plugins} passed to a context instance will be shared among all
- * editor instances initialized in this context. These will be the same plugin instances for all the editors.
- *
- * **Note:** The context can only be initialized with {@link module:core/contextplugin~ContextPlugin context plugins}
- * (e.g. [comments](https://ckeditor.com/collaboration/comments/)). Regular {@link module:core/plugin~Plugin plugins} require an
- * editor instance to work and cannot be added to a context.
- *
- * **Note:** You can add a context plugin to an editor instance, though.
- *
- * If you are using multiple editor instances on one page and use any context plugins, create a context to share the configuration and
- * plugins among these editors. Some plugins will use the information about all existing editors to better integrate between them.
- *
- * If you are using plugins that do not require an editor to work (e.g. [comments](https://ckeditor.com/collaboration/comments/)),
- * enable and configure them using the context.
- *
- * If you are using only a single editor on each page, use {@link module:core/editor/editor~Editor.create `Editor.create()`} instead.
- * In such a case, a context instance will be created by the editor instance in a transparent way.
- *
- * See {@link ~Context.create `Context.create()`} for usage examples.
- */
-export default class Context {
-    /**
-     * Creates a context instance with a given configuration.
-     *
-     * Usually not to be used directly. See the static {@link module:core/context~Context.create `create()`} method.
-     *
-     * @param config The context configuration.
-     */
-    constructor(config) {
-        /**
-         * Reference to the editor which created the context.
-         * Null when the context was created outside of the editor.
-         *
-         * It is used to destroy the context when removing the editor that has created the context.
-         */
-        this._contextOwner = null;
-        this.config = new Config(config, this.constructor.defaultConfig);
-        const availablePlugins = this.constructor.builtinPlugins;
-        this.config.define('plugins', availablePlugins);
-        this.plugins = new PluginCollection(this, availablePlugins);
-        const languageConfig = this.config.get('language') || {};
-        this.locale = new Locale({
-            uiLanguage: typeof languageConfig === 'string' ? languageConfig : languageConfig.ui,
-            contentLanguage: this.config.get('language.content')
-        });
-        this.t = this.locale.t;
-        this.editors = new Collection();
-    }
-    /**
-     * Loads and initializes plugins specified in the configuration.
-     *
-     * @returns A promise which resolves once the initialization is completed, providing an array of loaded plugins.
-     */
-    initPlugins() {
-        const plugins = this.config.get('plugins') || [];
-        const substitutePlugins = this.config.get('substitutePlugins') || [];
-        // Plugins for substitution should be checked as well.
-        for (const Plugin of plugins.concat(substitutePlugins)) {
-            if (typeof Plugin != 'function') {
-                /**
-                 * Only a constructor function is allowed as a {@link module:core/contextplugin~ContextPlugin context plugin}.
-                 *
-                 * @error context-initplugins-constructor-only
-                 */
-                throw new CKEditorError('context-initplugins-constructor-only', null, { Plugin });
-            }
-            if (Plugin.isContextPlugin !== true) {
-                /**
-                 * Only a plugin marked as a {@link module:core/contextplugin~ContextPlugin.isContextPlugin context plugin}
-                 * is allowed to be used with a context.
-                 *
-                 * @error context-initplugins-invalid-plugin
-                 */
-                throw new CKEditorError('context-initplugins-invalid-plugin', null, { Plugin });
-            }
-        }
-        return this.plugins.init(plugins, [], substitutePlugins);
-    }
-    /**
-     * Destroys the context instance and all editors used with the context,
-     * releasing all resources used by the context.
-     *
-     * @returns A promise that resolves once the context instance is fully destroyed.
-     */
-    destroy() {
-        return Promise.all(Array.from(this.editors, editor => editor.destroy()))
-            .then(() => this.plugins.destroy());
-    }
-    /**
-     * Adds a reference to the editor which is used with this context.
-     *
-     * When the given editor has created the context, the reference to this editor will be stored
-     * as a {@link ~Context#_contextOwner}.
-     *
-     * This method should only be used by the editor.
-     *
-     * @internal
-     * @param isContextOwner Stores the given editor as a context owner.
-     */
-    _addEditor(editor, isContextOwner) {
-        if (this._contextOwner) {
-            /**
-             * Cannot add multiple editors to the context which is created by the editor.
-             *
-             * @error context-addeditor-private-context
-             */
-            throw new CKEditorError('context-addeditor-private-context');
-        }
-        this.editors.add(editor);
-        if (isContextOwner) {
-            this._contextOwner = editor;
-        }
-    }
-    /**
-     * Removes a reference to the editor which was used with this context.
-     * When the context was created by the given editor, the context will be destroyed.
-     *
-     * This method should only be used by the editor.
-     *
-     * @internal
-     * @return A promise that resolves once the editor is removed from the context or when the context was destroyed.
-     */
-    _removeEditor(editor) {
-        if (this.editors.has(editor)) {
-            this.editors.remove(editor);
-        }
-        if (this._contextOwner === editor) {
-            return this.destroy();
-        }
-        return Promise.resolve();
-    }
-    /**
-     * Returns the context configuration which will be copied to the editors created using this context.
-     *
-     * The configuration returned by this method has the plugins configuration removed — plugins are shared with all editors
-     * through another mechanism.
-     *
-     * This method should only be used by the editor.
-     *
-     * @internal
-     * @returns Configuration as a plain object.
-     */
-    _getEditorConfig() {
-        const result = {};
-        for (const name of this.config.names()) {
-            if (!['plugins', 'removePlugins', 'extraPlugins'].includes(name)) {
-                result[name] = this.config.get(name);
-            }
-        }
-        return result;
-    }
-    /**
-     * Creates and initializes a new context instance.
-     *
-     * ```ts
-     * const commonConfig = { ... }; // Configuration for all the plugins and editors.
-     * const editorPlugins = [ ... ]; // Regular plugins here.
-     *
-     * Context
-     * 	.create( {
-     * 		// Only context plugins here.
-     * 		plugins: [ ... ],
-     *
-     * 		// Configure the language for all the editors (it cannot be overwritten).
-     * 		language: { ... },
-     *
-     * 		// Configuration for context plugins.
-     * 		comments: { ... },
-     * 		...
-     *
-     * 		// Default configuration for editor plugins.
-     * 		toolbar: { ... },
-     * 		image: { ... },
-     * 		...
-     * 	} )
-     * 	.then( context => {
-     * 		const promises = [];
-     *
-     * 		promises.push( ClassicEditor.create(
-     * 			document.getElementById( 'editor1' ),
-     * 			{
-     * 				editorPlugins,
-     * 				context
-     * 			}
-     * 		) );
-     *
-     * 		promises.push( ClassicEditor.create(
-     * 			document.getElementById( 'editor2' ),
-     * 			{
-     * 				editorPlugins,
-     * 				context,
-     * 				toolbar: { ... } // You can overwrite the configuration of the context.
-     * 			}
-     * 		) );
-     *
-     * 		return Promise.all( promises );
-     * 	} );
-     * ```
-     *
-     * @param config The context configuration.
-     * @returns A promise resolved once the context is ready. The promise resolves with the created context instance.
-     */
-    static create(config) {
-        return new Promise(resolve => {
-            const context = new this(config);
-            resolve(context.initPlugins().then(() => context));
-        });
-    }
-}
+/**
+ * @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/context
+ */
+import { Config, Collection, CKEditorError, Locale } from '@ckeditor/ckeditor5-utils';
+import PluginCollection from './plugincollection';
+/**
+ * Provides a common, higher-level environment for solutions that use multiple {@link module:core/editor/editor~Editor editors}
+ * or plugins that work outside the editor. Use it instead of {@link module:core/editor/editor~Editor.create `Editor.create()`}
+ * in advanced application integrations.
+ *
+ * All configuration options passed to a context will be used as default options for the editor instances initialized in that context.
+ *
+ * {@link module:core/contextplugin~ContextPlugin Context plugins} passed to a context instance will be shared among all
+ * editor instances initialized in this context. These will be the same plugin instances for all the editors.
+ *
+ * **Note:** The context can only be initialized with {@link module:core/contextplugin~ContextPlugin context plugins}
+ * (e.g. [comments](https://ckeditor.com/collaboration/comments/)). Regular {@link module:core/plugin~Plugin plugins} require an
+ * editor instance to work and cannot be added to a context.
+ *
+ * **Note:** You can add a context plugin to an editor instance, though.
+ *
+ * If you are using multiple editor instances on one page and use any context plugins, create a context to share the configuration and
+ * plugins among these editors. Some plugins will use the information about all existing editors to better integrate between them.
+ *
+ * If you are using plugins that do not require an editor to work (e.g. [comments](https://ckeditor.com/collaboration/comments/)),
+ * enable and configure them using the context.
+ *
+ * If you are using only a single editor on each page, use {@link module:core/editor/editor~Editor.create `Editor.create()`} instead.
+ * In such a case, a context instance will be created by the editor instance in a transparent way.
+ *
+ * See {@link ~Context.create `Context.create()`} for usage examples.
+ */
+export default class Context {
+    /**
+     * Creates a context instance with a given configuration.
+     *
+     * Usually not to be used directly. See the static {@link module:core/context~Context.create `create()`} method.
+     *
+     * @param config The context configuration.
+     */
+    constructor(config) {
+        /**
+         * Reference to the editor which created the context.
+         * Null when the context was created outside of the editor.
+         *
+         * It is used to destroy the context when removing the editor that has created the context.
+         */
+        this._contextOwner = null;
+        this.config = new Config(config, this.constructor.defaultConfig);
+        const availablePlugins = this.constructor.builtinPlugins;
+        this.config.define('plugins', availablePlugins);
+        this.plugins = new PluginCollection(this, availablePlugins);
+        const languageConfig = this.config.get('language') || {};
+        this.locale = new Locale({
+            uiLanguage: typeof languageConfig === 'string' ? languageConfig : languageConfig.ui,
+            contentLanguage: this.config.get('language.content')
+        });
+        this.t = this.locale.t;
+        this.editors = new Collection();
+    }
+    /**
+     * Loads and initializes plugins specified in the configuration.
+     *
+     * @returns A promise which resolves once the initialization is completed, providing an array of loaded plugins.
+     */
+    initPlugins() {
+        const plugins = this.config.get('plugins') || [];
+        const substitutePlugins = this.config.get('substitutePlugins') || [];
+        // Plugins for substitution should be checked as well.
+        for (const Plugin of plugins.concat(substitutePlugins)) {
+            if (typeof Plugin != 'function') {
+                /**
+                 * Only a constructor function is allowed as a {@link module:core/contextplugin~ContextPlugin context plugin}.
+                 *
+                 * @error context-initplugins-constructor-only
+                 */
+                throw new CKEditorError('context-initplugins-constructor-only', null, { Plugin });
+            }
+            if (Plugin.isContextPlugin !== true) {
+                /**
+                 * Only a plugin marked as a {@link module:core/contextplugin~ContextPlugin.isContextPlugin context plugin}
+                 * is allowed to be used with a context.
+                 *
+                 * @error context-initplugins-invalid-plugin
+                 */
+                throw new CKEditorError('context-initplugins-invalid-plugin', null, { Plugin });
+            }
+        }
+        return this.plugins.init(plugins, [], substitutePlugins);
+    }
+    /**
+     * Destroys the context instance and all editors used with the context,
+     * releasing all resources used by the context.
+     *
+     * @returns A promise that resolves once the context instance is fully destroyed.
+     */
+    destroy() {
+        return Promise.all(Array.from(this.editors, editor => editor.destroy()))
+            .then(() => this.plugins.destroy());
+    }
+    /**
+     * Adds a reference to the editor which is used with this context.
+     *
+     * When the given editor has created the context, the reference to this editor will be stored
+     * as a {@link ~Context#_contextOwner}.
+     *
+     * This method should only be used by the editor.
+     *
+     * @internal
+     * @param isContextOwner Stores the given editor as a context owner.
+     */
+    _addEditor(editor, isContextOwner) {
+        if (this._contextOwner) {
+            /**
+             * Cannot add multiple editors to the context which is created by the editor.
+             *
+             * @error context-addeditor-private-context
+             */
+            throw new CKEditorError('context-addeditor-private-context');
+        }
+        this.editors.add(editor);
+        if (isContextOwner) {
+            this._contextOwner = editor;
+        }
+    }
+    /**
+     * Removes a reference to the editor which was used with this context.
+     * When the context was created by the given editor, the context will be destroyed.
+     *
+     * This method should only be used by the editor.
+     *
+     * @internal
+     * @return A promise that resolves once the editor is removed from the context or when the context was destroyed.
+     */
+    _removeEditor(editor) {
+        if (this.editors.has(editor)) {
+            this.editors.remove(editor);
+        }
+        if (this._contextOwner === editor) {
+            return this.destroy();
+        }
+        return Promise.resolve();
+    }
+    /**
+     * Returns the context configuration which will be copied to the editors created using this context.
+     *
+     * The configuration returned by this method has the plugins configuration removed – plugins are shared with all editors
+     * through another mechanism.
+     *
+     * This method should only be used by the editor.
+     *
+     * @internal
+     * @returns Configuration as a plain object.
+     */
+    _getEditorConfig() {
+        const result = {};
+        for (const name of this.config.names()) {
+            if (!['plugins', 'removePlugins', 'extraPlugins'].includes(name)) {
+                result[name] = this.config.get(name);
+            }
+        }
+        return result;
+    }
+    /**
+     * Creates and initializes a new context instance.
+     *
+     * ```ts
+     * const commonConfig = { ... }; // Configuration for all the plugins and editors.
+     * const editorPlugins = [ ... ]; // Regular plugins here.
+     *
+     * Context
+     * 	.create( {
+     * 		// Only context plugins here.
+     * 		plugins: [ ... ],
+     *
+     * 		// Configure the language for all the editors (it cannot be overwritten).
+     * 		language: { ... },
+     *
+     * 		// Configuration for context plugins.
+     * 		comments: { ... },
+     * 		...
+     *
+     * 		// Default configuration for editor plugins.
+     * 		toolbar: { ... },
+     * 		image: { ... },
+     * 		...
+     * 	} )
+     * 	.then( context => {
+     * 		const promises = [];
+     *
+     * 		promises.push( ClassicEditor.create(
+     * 			document.getElementById( 'editor1' ),
+     * 			{
+     * 				editorPlugins,
+     * 				context
+     * 			}
+     * 		) );
+     *
+     * 		promises.push( ClassicEditor.create(
+     * 			document.getElementById( 'editor2' ),
+     * 			{
+     * 				editorPlugins,
+     * 				context,
+     * 				toolbar: { ... } // You can overwrite the configuration of the context.
+     * 			}
+     * 		) );
+     *
+     * 		return Promise.all( promises );
+     * 	} );
+     * ```
+     *
+     * @param config The context configuration.
+     * @returns A promise resolved once the context is ready. The promise resolves with the created context instance.
+     */
+    static create(config) {
+        return new Promise(resolve => {
+            const context = new this(config);
+            resolve(context.initPlugins().then(() => context));
+        });
+    }
+}

package/src/contextplugin.d.ts

@@ -1,61 +1,61 @@
-/**
- * @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/contextplugin
- */
-import { type Collection, type Config, type Locale, type LocaleTranslate } from '@ckeditor/ckeditor5-utils';
-import type Editor from './editor/editor';
-import type { EditorConfig } from './editor/editorconfig';
-import type Context from './context';
-import type { PluginDependencies, PluginInterface } from './plugin';
-import type PluginCollection from './plugincollection';
-declare const ContextPlugin_base: {
-    new (): import("@ckeditor/ckeditor5-utils").Observable;
-    prototype: import("@ckeditor/ckeditor5-utils").Observable;
-};
-/**
- * The base class for {@link module:core/context~Context} plugin classes.
- *
- * A context plugin can either be initialized for an {@link module:core/editor/editor~Editor editor} or for
- * a {@link module:core/context~Context context}. In other words, it can either
- * work within one editor instance or with one or more editor instances that use a single context.
- * It is the context plugin's role to implement handling for both modes.
- *
- * There are a few rules for interaction between the editor plugins and context plugins:
- *
- * * A context plugin can require another context plugin.
- * * An {@link module:core/plugin~Plugin editor plugin} can require a context plugin.
- * * A context plugin MUST NOT require an {@link module:core/plugin~Plugin editor plugin}.
- */
-export default class ContextPlugin extends ContextPlugin_base implements PluginInterface {
-    /**
-     * The context or editor instance.
-     */
-    readonly context: ContextInterface;
-    /**
-     * Creates a new plugin instance.
-     */
-    constructor(context: Context | Editor);
-    /**
-     * @inheritDoc
-     */
-    destroy(): void;
-    /**
-     * @inheritDoc
-     */
-    static get isContextPlugin(): true;
-}
-/**
- * The common interface of {@link module:core/context~Context} and {@link module:core/editor/editor~Editor}.
- */
-export interface ContextInterface {
-    config: Config<Omit<EditorConfig, 'plugins' | 'substitutePlugins' | 'removePlugins' | 'extraPlugins'>>;
-    plugins: PluginCollection<Context | Editor>;
-    locale: Locale;
-    t: LocaleTranslate;
-    editors?: Collection<Editor>;
-}
-export type ContextPluginDependencies = PluginDependencies<Context | Editor>;
-export {};
+/**
+ * @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/contextplugin
+ */
+import { type Collection, type Config, type Locale, type LocaleTranslate } from '@ckeditor/ckeditor5-utils';
+import type Editor from './editor/editor';
+import type { EditorConfig } from './editor/editorconfig';
+import type Context from './context';
+import type { PluginDependencies, PluginInterface } from './plugin';
+import type PluginCollection from './plugincollection';
+declare const ContextPlugin_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Observable;
+    prototype: import("@ckeditor/ckeditor5-utils").Observable;
+};
+/**
+ * The base class for {@link module:core/context~Context} plugin classes.
+ *
+ * A context plugin can either be initialized for an {@link module:core/editor/editor~Editor editor} or for
+ * a {@link module:core/context~Context context}. In other words, it can either
+ * work within one editor instance or with one or more editor instances that use a single context.
+ * It is the context plugin's role to implement handling for both modes.
+ *
+ * There are a few rules for interaction between the editor plugins and context plugins:
+ *
+ * * A context plugin can require another context plugin.
+ * * An {@link module:core/plugin~Plugin editor plugin} can require a context plugin.
+ * * A context plugin MUST NOT require an {@link module:core/plugin~Plugin editor plugin}.
+ */
+export default class ContextPlugin extends ContextPlugin_base implements PluginInterface {
+    /**
+     * The context or editor instance.
+     */
+    readonly context: ContextInterface;
+    /**
+     * Creates a new plugin instance.
+     */
+    constructor(context: Context | Editor);
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * @inheritDoc
+     */
+    static get isContextPlugin(): true;
+}
+/**
+ * The common interface of {@link module:core/context~Context} and {@link module:core/editor/editor~Editor}.
+ */
+export interface ContextInterface {
+    config: Config<Omit<EditorConfig, 'plugins' | 'substitutePlugins' | 'removePlugins' | 'extraPlugins'>>;
+    plugins: PluginCollection<Context | Editor>;
+    locale: Locale;
+    t: LocaleTranslate;
+    editors?: Collection<Editor>;
+}
+export type ContextPluginDependencies = PluginDependencies<Context | Editor>;
+export {};

package/src/contextplugin.js

@@ -1,43 +1,43 @@
-/**
- * @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/contextplugin
- */
-import { ObservableMixin } from '@ckeditor/ckeditor5-utils';
-/**
- * The base class for {@link module:core/context~Context} plugin classes.
- *
- * A context plugin can either be initialized for an {@link module:core/editor/editor~Editor editor} or for
- * a {@link module:core/context~Context context}. In other words, it can either
- * work within one editor instance or with one or more editor instances that use a single context.
- * It is the context plugin's role to implement handling for both modes.
- *
- * There are a few rules for interaction between the editor plugins and context plugins:
- *
- * * A context plugin can require another context plugin.
- * * An {@link module:core/plugin~Plugin editor plugin} can require a context plugin.
- * * A context plugin MUST NOT require an {@link module:core/plugin~Plugin editor plugin}.
- */
-export default class ContextPlugin extends ObservableMixin() {
-    /**
-     * Creates a new plugin instance.
-     */
-    constructor(context) {
-        super();
-        this.context = context;
-    }
-    /**
-     * @inheritDoc
-     */
-    destroy() {
-        this.stopListening();
-    }
-    /**
-     * @inheritDoc
-     */
-    static get isContextPlugin() {
-        return true;
-    }
-}
+/**
+ * @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/contextplugin
+ */
+import { ObservableMixin } from '@ckeditor/ckeditor5-utils';
+/**
+ * The base class for {@link module:core/context~Context} plugin classes.
+ *
+ * A context plugin can either be initialized for an {@link module:core/editor/editor~Editor editor} or for
+ * a {@link module:core/context~Context context}. In other words, it can either
+ * work within one editor instance or with one or more editor instances that use a single context.
+ * It is the context plugin's role to implement handling for both modes.
+ *
+ * There are a few rules for interaction between the editor plugins and context plugins:
+ *
+ * * A context plugin can require another context plugin.
+ * * An {@link module:core/plugin~Plugin editor plugin} can require a context plugin.
+ * * A context plugin MUST NOT require an {@link module:core/plugin~Plugin editor plugin}.
+ */
+export default class ContextPlugin extends ObservableMixin() {
+    /**
+     * Creates a new plugin instance.
+     */
+    constructor(context) {
+        super();
+        this.context = context;
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        this.stopListening();
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isContextPlugin() {
+        return true;
+    }
+}