@ckeditor/ckeditor5-core 41.3.1 → 41.4.0

package/dist/types/context.d.ts

@@ -0,0 +1,241 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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, Locale, type LocaleTranslate } from '@ckeditor/ckeditor5-utils';
+import PluginCollection from './plugincollection.js';
+import type Editor from './editor/editor.js';
+import type { LoadedPlugins, PluginConstructor } from './plugin.js';
+import type { EditorConfig } from './editor/editorconfig.js';
+/**
+ * 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 {
+    /**
+     * Stores all the configurations specific to this context instance.
+     */
+    readonly config: Config<ContextConfig>;
+    /**
+     * The plugins loaded and in use by this context instance.
+     */
+    readonly plugins: PluginCollection<Context | Editor>;
+    readonly locale: Locale;
+    /**
+     * Shorthand for {@link module:utils/locale~Locale#t}.
+     */
+    readonly t: LocaleTranslate;
+    /**
+     * A list of editors that this context instance is injected to.
+     */
+    readonly editors: Collection<Editor>;
+    /**
+     * The default configuration which is built into the `Context` class.
+     *
+     * It is used in CKEditor 5 builds featuring `Context` to provide the default configuration options which are later used during the
+     * context initialization.
+     *
+     * ```ts
+     * Context.defaultConfig = {
+     * 	foo: 1,
+     * 	bar: 2
+     * };
+     *
+     * Context
+     * 	.create()
+     * 	.then( context => {
+     * 		context.config.get( 'foo' ); // -> 1
+     * 		context.config.get( 'bar' ); // -> 2
+     * 	} );
+     *
+     * // The default options can be overridden by the configuration passed to create().
+     * Context
+     * 	.create( { bar: 3 } )
+     * 	.then( context => {
+     * 		context.config.get( 'foo' ); // -> 1
+     * 		context.config.get( 'bar' ); // -> 3
+     * 	} );
+     * ```
+     *
+     * See also {@link module:core/context~Context.builtinPlugins `Context.builtinPlugins`}
+     * and {@link module:core/editor/editor~Editor.defaultConfig `Editor.defaultConfig`}.
+     */
+    static defaultConfig: ContextConfig;
+    /**
+     * An array of plugins built into the `Context` class.
+     *
+     * It is used in CKEditor 5 builds featuring `Context` to provide a list of context plugins which are later automatically initialized
+     * during the context initialization.
+     *
+     * They will be automatically initialized by `Context` unless `config.plugins` is passed.
+     *
+     * ```ts
+     * // Build some context plugins into the Context class first.
+     * Context.builtinPlugins = [ FooPlugin, BarPlugin ];
+     *
+     * // Normally, you need to define config.plugins, but since Context.builtinPlugins was
+     * // defined, now you can call create() without any configuration.
+     * Context
+     * 	.create()
+     * 	.then( context => {
+     * 		context.plugins.get( FooPlugin ); // -> An instance of the Foo plugin.
+     * 		context.plugins.get( BarPlugin ); // -> An instance of the Bar plugin.
+     * 	} );
+     * ```
+     *
+     * See also {@link module:core/context~Context.defaultConfig `Context.defaultConfig`}
+     * and {@link module:core/editor/editor~Editor.builtinPlugins `Editor.builtinPlugins`}.
+     */
+    static builtinPlugins: Array<PluginConstructor<Context | Editor>>;
+    /**
+     * 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.
+     */
+    private _contextOwner;
+    /**
+     * 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?: ContextConfig);
+    /**
+     * 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(): Promise<LoadedPlugins>;
+    /**
+     * 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(): Promise<unknown>;
+    /**
+     * 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: Editor, isContextOwner: boolean): void;
+    /**
+     * 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: Editor): Promise<unknown>;
+    /**
+     * 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 &ndash; 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(): Partial<EditorConfig>;
+    /**
+     * 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?: ContextConfig): Promise<Context>;
+}
+/**
+ * The context configuration.
+ */
+export type ContextConfig = {
+    plugins?: Array<PluginConstructor<Context | Editor>>;
+    substitutePlugins?: Array<PluginConstructor<Context | Editor>>;
+} & Omit<EditorConfig, 'plugins' | 'substitutePlugins' | 'removePlugins' | 'extraPlugins'>;

package/dist/types/contextplugin.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, 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.js';
+import type { EditorConfig } from './editor/editorconfig.js';
+import type Context from './context.js';
+import type { PluginDependencies, PluginInterface } from './plugin.js';
+import type PluginCollection from './plugincollection.js';
+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/dist/types/editingkeystrokehandler.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module core/editingkeystrokehandler
+ */
+import { KeystrokeHandler, type PriorityString } from '@ckeditor/ckeditor5-utils';
+import type Editor from './editor/editor.js';
+/**
+ * A keystroke handler for editor editing. Its instance is available
+ * in {@link module:core/editor/editor~Editor#keystrokes} so plugins
+ * can register their keystrokes.
+ *
+ * E.g. an undo plugin would do this:
+ *
+ * ```ts
+ * editor.keystrokes.set( 'Ctrl+Z', 'undo' );
+ * editor.keystrokes.set( 'Ctrl+Shift+Z', 'redo' );
+ * editor.keystrokes.set( 'Ctrl+Y', 'redo' );
+ * ```
+ */
+export default class EditingKeystrokeHandler extends KeystrokeHandler {
+    /**
+     * The editor instance.
+     */
+    readonly editor: Editor;
+    /**
+     * Creates an instance of the keystroke handler.
+     */
+    constructor(editor: Editor);
+    /**
+     * Registers a handler for the specified keystroke.
+     *
+     * The handler can be specified as a command name or a callback.
+     *
+     * @param keystroke Keystroke defined in a format accepted by
+     * the {@link module:utils/keyboard~parseKeystroke} function.
+     * @param callback If a string is passed, then the keystroke will
+     * {@link module:core/editor/editor~Editor#execute execute a command}.
+     * If a function, then it will be called with the
+     * {@link module:engine/view/observer/keyobserver~KeyEventData key event data} object and
+     * a `cancel()` helper to both `preventDefault()` and `stopPropagation()` of the event.
+     * @param options Additional options.
+     * @param options.priority The priority of the keystroke callback. The higher the priority value
+     * the sooner the callback will be executed. Keystrokes having the same priority
+     * are called in the order they were added.
+     */
+    set(keystroke: string | Array<string | number>, callback: EditingKeystrokeCallback, options?: {
+        readonly priority?: PriorityString;
+    }): void;
+}
+/**
+ * Command name or a callback to be executed when a given keystroke is pressed.
+ */
+export type EditingKeystrokeCallback = string | ((ev: KeyboardEvent, cancel: () => void) => void);