@ckeditor/ckeditor5-core 41.0.0 → 41.2.0

package/src/editor/editor.d.ts

@@ -12,6 +12,7 @@ import Context from '../context.js';
 import PluginCollection from '../plugincollection.js';
 import CommandCollection, { type CommandsMap } from '../commandcollection.js';
 import EditingKeystrokeHandler from '../editingkeystrokehandler.js';
+import Accessibility from '../accessibility.js';
 import type { LoadedPlugins, PluginConstructor } from '../plugin.js';
 import type { EditorConfig } from './editorconfig.js';
 declare const Editor_base: {
@@ -37,6 +38,10 @@ declare const Editor_base: {
  * (as most editor implementations do).
  */
 export default abstract class Editor extends Editor_base {
+    /**
+     * A namespace for the accessibility features of the editor.
+     */
+    readonly accessibility: Accessibility;
     /**
      * Commands registered to the editor.
      *
@@ -314,6 +319,62 @@ export default abstract class Editor extends Editor_base {
      * @param lockId The lock ID for setting the editor to the read-only state.
      */
     disableReadOnlyMode(lockId: string | symbol): void;
+    /**
+     * Sets the data in the editor.
+     *
+     * ```ts
+     * editor.setData( '<p>This is editor!</p>' );
+     * ```
+     *
+     * If your editor implementation uses multiple roots, you should pass an object with keys corresponding
+     * to the editor root names and values equal to the data that should be set in each root:
+     *
+     * ```ts
+     * editor.setData( {
+     *     header: '<p>Content for header part.</p>',
+     *     content: '<p>Content for main part.</p>',
+     *     footer: '<p>Content for footer part.</p>'
+     * } );
+     * ```
+     *
+     * By default the editor accepts HTML. This can be controlled by injecting a different data processor.
+     * See the {@glink features/markdown Markdown output} guide for more details.
+     *
+     * @param data Input data.
+     */
+    setData(data: string | Record<string, string>): void;
+    /**
+     * Gets the data from the editor.
+     *
+     * ```ts
+     * editor.getData(); // -> '<p>This is editor!</p>'
+     * ```
+     *
+     * If your editor implementation uses multiple roots, you should pass root name as one of the options:
+     *
+     * ```ts
+     * editor.getData( { rootName: 'header' } ); // -> '<p>Content for header part.</p>'
+     * ```
+     *
+     * By default, the editor outputs HTML. This can be controlled by injecting a different data processor.
+     * See the {@glink features/markdown Markdown output} guide for more details.
+     *
+     * A warning is logged when you try to retrieve data for a detached root, as most probably this is a mistake. A detached root should
+     * be treated like it is removed, and you should not save its data. Note, that the detached root data is always an empty string.
+     *
+     * @param options Additional configuration for the retrieved data.
+     * Editor features may introduce more configuration options that can be set through this parameter.
+     * @param options.rootName Root name. Defaults to `'main'`.
+     * @param options.trim Whether returned data should be trimmed. This option is set to `'empty'` by default,
+     * which means that whenever editor content is considered empty, an empty string is returned. To turn off trimming
+     * use `'none'`. In such cases exact content will be returned (for example `'<p>&nbsp;</p>'` for an empty editor).
+     * @returns Output data.
+     */
+    getData(options?: {
+        rootName?: string;
+        trim?: 'empty' | 'none';
+        [key: string]: unknown;
+    }): string;
     /**
      * Loads and initializes plugins specified in the configuration.
      *

package/src/editor/editor.js

@@ -11,6 +11,7 @@ import Context from '../context.js';
 import PluginCollection from '../plugincollection.js';
 import CommandCollection from '../commandcollection.js';
 import EditingKeystrokeHandler from '../editingkeystrokehandler.js';
+import Accessibility from '../accessibility.js';
 /**
  * The class representing a basic, generic editor.
  *
@@ -40,14 +41,18 @@ export default class Editor extends ObservableMixin() {
     constructor(config = {}) {
         super();
         const constructor = this.constructor;
+        // We don't pass translations to the config, because its behavior of splitting keys
+        // with dots (e.g. `resize.width` => `resize: { width }`) breaks the translations.
+        const { translations: defaultTranslations, ...defaultConfig } = constructor.defaultConfig || {};
+        const { translations = defaultTranslations, ...rest } = config;
         // Prefer the language passed as the argument to the constructor instead of the constructor's `defaultConfig`, if both are set.
-        const language = config.language || (constructor.defaultConfig && constructor.defaultConfig.language);
-        this._context = config.context || new Context({ language });
+        const language = config.language || defaultConfig.language;
+        this._context = config.context || new Context({ language, translations });
         this._context._addEditor(this, !config.context);
         // Clone the plugins to make sure that the plugin array will not be shared
         // between editors and make the watchdog feature work correctly.
         const availablePlugins = Array.from(constructor.builtinPlugins || []);
-        this.config = new Config(config, constructor.defaultConfig);
+        this.config = new Config(rest, defaultConfig);
         this.config.define('plugins', availablePlugins);
         this.config.define(this._context._getEditorConfig());
         this.plugins = new PluginCollection(this, availablePlugins, this._context.plugins);
@@ -71,6 +76,7 @@ export default class Editor extends ObservableMixin() {
         this.conversion.addAlias('editingDowncast', this.editing.downcastDispatcher);
         this.keystrokes = new EditingKeystrokeHandler(this);
         this.keystrokes.listenTo(this.editing.view.document);
+        this.accessibility = new Accessibility(this);
     }
     /**
      * Defines whether the editor is in the read-only mode.
@@ -202,6 +208,62 @@ export default class Editor extends ObservableMixin() {
             this.fire('change:isReadOnly', 'isReadOnly', false, true);
         }
     }
+    /**
+     * Sets the data in the editor.
+     *
+     * ```ts
+     * editor.setData( '<p>This is editor!</p>' );
+     * ```
+     *
+     * If your editor implementation uses multiple roots, you should pass an object with keys corresponding
+     * to the editor root names and values equal to the data that should be set in each root:
+     *
+     * ```ts
+     * editor.setData( {
+     *     header: '<p>Content for header part.</p>',
+     *     content: '<p>Content for main part.</p>',
+     *     footer: '<p>Content for footer part.</p>'
+     * } );
+     * ```
+     *
+     * By default the editor accepts HTML. This can be controlled by injecting a different data processor.
+     * See the {@glink features/markdown Markdown output} guide for more details.
+     *
+     * @param data Input data.
+     */
+    setData(data) {
+        this.data.set(data);
+    }
+    /**
+     * Gets the data from the editor.
+     *
+     * ```ts
+     * editor.getData(); // -> '<p>This is editor!</p>'
+     * ```
+     *
+     * If your editor implementation uses multiple roots, you should pass root name as one of the options:
+     *
+     * ```ts
+     * editor.getData( { rootName: 'header' } ); // -> '<p>Content for header part.</p>'
+     * ```
+     *
+     * By default, the editor outputs HTML. This can be controlled by injecting a different data processor.
+     * See the {@glink features/markdown Markdown output} guide for more details.
+     *
+     * A warning is logged when you try to retrieve data for a detached root, as most probably this is a mistake. A detached root should
+     * be treated like it is removed, and you should not save its data. Note, that the detached root data is always an empty string.
+     *
+     * @param options Additional configuration for the retrieved data.
+     * Editor features may introduce more configuration options that can be set through this parameter.
+     * @param options.rootName Root name. Defaults to `'main'`.
+     * @param options.trim Whether returned data should be trimmed. This option is set to `'empty'` by default,
+     * which means that whenever editor content is considered empty, an empty string is returned. To turn off trimming
+     * use `'none'`. In such cases exact content will be returned (for example `'<p>&nbsp;</p>'` for an empty editor).
+     * @returns Output data.
+     */
+    getData(options) {
+        return this.data.get(options);
+    }
     /**
      * Loads and initializes plugins specified in the configuration.
      *

package/src/editor/editorconfig.d.ts

@@ -5,6 +5,7 @@
 /**
  * @module core/editor/editorconfig
  */
+import type { ArrayOrItem, Translations } from '@ckeditor/ckeditor5-utils';
 import type Context from '../context.js';
 import type { PluginConstructor } from '../plugin.js';
 import type Editor from './editor.js';
@@ -519,6 +520,10 @@ export interface EditorConfig {
      * [order a trial](https://orders.ckeditor.com/trial/premium-features).
      */
     licenseKey?: string;
+    /**
+     * Translations to be used in the editor.
+     */
+    translations?: ArrayOrItem<Translations>;
 }
 /**
  * The `config.initialData` option cannot be used together with the initial data passed as the first parameter of

package/src/editor/utils/dataapimixin.d.ts

@@ -6,11 +6,13 @@
  * @module core/editor/utils/dataapimixin
  */
 import type Editor from '../editor.js';
-import type { Constructor, Mixed } from '@ckeditor/ckeditor5-utils';
+import type { Constructor } from '@ckeditor/ckeditor5-utils';
 /**
  * Implementation of the {@link module:core/editor/utils/dataapimixin~DataApi}.
+ *
+ * @deprecated This functionality is already implemented by the `Editor` class.
  */
-export default function DataApiMixin<Base extends Constructor<Editor>>(base: Base): Mixed<Base, DataApi>;
+export default function DataApiMixin<Base extends Constructor<Editor>>(base: Base): Base;
 /**
  * Interface defining editor methods for setting and getting data to and from the editor's main root element
  * using the {@link module:core/editor/editor~Editor#data data pipeline}.
@@ -18,6 +20,8 @@ export default function DataApiMixin<Base extends Constructor<Editor>>(base: Bas
  * This interface is not a part of the {@link module:core/editor/editor~Editor} class because one may want to implement
  * an editor with multiple root elements, in which case the methods for setting and getting data will need to be implemented
  * differently.
+ *
+ * @deprecated This interface is implemented by all `Editor` instances by default.
  */
 export interface DataApi {
     /**

package/src/editor/utils/dataapimixin.js

@@ -4,21 +4,9 @@
  */
 /**
  * Implementation of the {@link module:core/editor/utils/dataapimixin~DataApi}.
+ *
+ * @deprecated This functionality is already implemented by the `Editor` class.
  */
 export default function DataApiMixin(base) {
-    class Mixin extends base {
-        setData(data) {
-            this.data.set(data);
-        }
-        getData(options) {
-            return this.data.get(options);
-        }
-    }
-    return Mixin;
-}
-// Backward compatibility with `mix`.
-{
-    const mixin = DataApiMixin(Object);
-    DataApiMixin.setData = mixin.prototype.setData;
-    DataApiMixin.getData = mixin.prototype.getData;
+    return base;
 }

package/src/index.d.ts

@@ -13,6 +13,7 @@ export type { PluginsMap, default as PluginCollection } from './plugincollection
 export { default as Context, type ContextConfig } from './context.js';
 export { default as ContextPlugin, type ContextPluginDependencies } from './contextplugin.js';
 export { type EditingKeystrokeCallback } from './editingkeystrokehandler.js';
+export type { PartialBy } from './typings.js';
 export { default as Editor, type EditorReadyEvent, type EditorDestroyEvent } from './editor/editor.js';
 export type { EditorConfig, LanguageConfig, ToolbarConfig, ToolbarConfigItem, UiConfig } from './editor/editorconfig.js';
 export { default as attachToForm } from './editor/utils/attachtoform.js';
@@ -20,6 +21,7 @@ export { default as DataApiMixin, type DataApi } from './editor/utils/dataapimix
 export { default as ElementApiMixin, type ElementApi } from './editor/utils/elementapimixin.js';
 export { default as secureSourceElement } from './editor/utils/securesourceelement.js';
 export { default as PendingActions, type PendingAction } from './pendingactions.js';
+export type { KeystrokeInfos as KeystrokeInfoDefinitions, KeystrokeInfoGroup as KeystrokeInfoGroupDefinition, KeystrokeInfoCategory as KeystrokeInfoCategoryDefinition, KeystrokeInfoDefinition as KeystrokeInfoDefinition } from './accessibility.js';
 export declare const icons: {
     bold: string;
     cancel: string;

package/src/typings.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @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/typings
+ */
+export type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

package/src/typings.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};