@ckeditor/ckeditor5-core 47.6.1 → 48.0.0-alpha.1

package/dist/index.js

@@ -2,8 +2,8 @@
  * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
-import { ObservableMixin, insertToPriorityArray, CKEditorError, EmitterMixin, Config, Locale, Collection, KeystrokeHandler, env, global, uid, decodeLicenseKey, toArray, crc32, releaseDate, logError, isFeatureBlockedByLicenseKey, setDataInElement } from '@ckeditor/ckeditor5-utils/dist/index.js';
-import { get, set, isFunction } from 'es-toolkit/compat';
+import { ObservableMixin, insertToPriorityArray, CKEditorError, EmitterMixin, Config, Locale, Collection, KeystrokeHandler, env, global, uid, decodeLicenseKey, toArray, crc32, releaseDate, logError, isFeatureBlockedByLicenseKey, setDataInElement, getDataFromElement } from '@ckeditor/ckeditor5-utils/dist/index.js';
+import { get, set, isFunction, isElement as isElement$1 } from 'es-toolkit/compat';
 import { Model, StylesProcessor, DataController, EditingController, Conversion } from '@ckeditor/ckeditor5-engine/dist/index.js';
 import { EditorWatchdog, ContextWatchdog } from '@ckeditor/ckeditor5-watchdog/dist/index.js';
 
@@ -726,8 +726,8 @@ import { EditorWatchdog, ContextWatchdog } from '@ckeditor/ckeditor5-watchdog/di
 				 * current list of plugins (`Editor.builtinPlugins` or `config.plugins`/`config.extraPlugins`).
 				 *
 				 * Soft requirements were introduced in version 26.0.0. If you happen to stumble upon this error
-				 * when upgrading to version 26.0.0, read also the
-				 * {@glink updating/guides/update-to-26 Migration to 26.0.0} guide.
+				 * when upgrading to version 26.0.0, read also the `Update to v26.x` section in the
+				 * {@glink updating/guides/updating-from-older-versions updating from older versions} guide.
 				 *
 				 * @error plugincollection-soft-required
 				 * @param {string} missingPlugin The name of the required plugin.
@@ -2111,7 +2111,8 @@ function getPageSessionID() {
 				 *   use the 'GPL' license key instead.
 				 *
 				 * ```js
-				 * ClassicEditor.create( document.querySelector( '#editor' ), {
+				 * ClassicEditor.create( {
+				 * 	attachTo: document.querySelector( '#editor' ),
 				 * 	licenseKey: '<YOUR_LICENSE_KEY>', // Or 'GPL'.
 				 * 	// ... Other configuration options ...
 				 * } ) ;
@@ -2880,6 +2881,160 @@ function isTextArea(sourceElement) {
     });
 }
 
+/**
+ * Normalizes the editor roots configuration. It ensures that all root configurations are defined in `config.roots`
+ * and that they have `initialData` defined.
+ *
+ * It normalizes a single-root configuration (where `config.root` is used) to a multi-root configuration
+ * (where all roots are defined in `config.roots`). This is considered a standard configuration format,
+ * so the editor features can always expect roots to be defined in `config.roots`.
+ *
+ * It also handles legacy configuration options, such as `config.initialData`, `config.placeholder`, and `config.label`.
+ *
+ * @internal
+ */ function normalizeRootsConfig(sourceElementsOrData, config, defaultRootName = 'main', separateAttachTo = false) {
+    const mainRootConfig = config.get('root');
+    const rootsConfig = config.get('roots') || Object.create(null);
+    // Avoid mixing `config.root` and `config.roots.main`.
+    if (mainRootConfig && (!defaultRootName || defaultRootName in rootsConfig)) {
+        // Documented in core/editor/editorconfig.ts.
+        // eslint-disable-next-line ckeditor5-rules/ckeditor-error-message
+        throw new CKEditorError('editor-create-roots-initial-data');
+    }
+    // Move `config.root` to `config.roots.main`.
+    // This makes access to root configuration more consistent as all roots will be defined in `config.roots`.
+    if (defaultRootName && !rootsConfig[defaultRootName]) {
+        rootsConfig[defaultRootName] = mainRootConfig || Object.create(null);
+    }
+    const sourceElementIsPlainObject = isPlainObject(sourceElementsOrData);
+    // Collect legacy configuration values for `initialData`, `placeholder`, and `label` from the config.
+    const legacyInitialData = getLegacyInitialData(config, sourceElementIsPlainObject, defaultRootName);
+    // Collect root names. This includes root names from the source element (if it's an object),
+    // from `config.roots`, and from legacy config. This ensures that all roots are processed in the next step.
+    const rootNames = Array.from(new Set([
+        ...sourceElementIsPlainObject ? Object.keys(sourceElementsOrData) : [],
+        ...Object.keys(rootsConfig),
+        ...Object.keys(legacyInitialData)
+    ]));
+    // Ensure that all roots have `initialData` defined. If not, try to get it from the source element or data.
+    for (const rootName of rootNames){
+        const rootConfig = rootsConfig[rootName] || Object.create(null);
+        const sourceElementOrDataForRoot = sourceElementIsPlainObject ? sourceElementsOrData[rootName] : sourceElementsOrData;
+        // No dedicated initial data for the root.
+        if (rootConfig.initialData === undefined) {
+            // No legacy initial data for the root, either.
+            if (legacyInitialData[rootName] === undefined) {
+                // Use source element data or data itself as a string.
+                // Fall back to `rootConfig.element` or `config.attachTo` (for ClassicEditor) for data extraction.
+                rootConfig.initialData = getInitialData(sourceElementOrDataForRoot || rootConfig.element || separateAttachTo && config.get('attachTo') || '');
+            } else if (sourceElementOrDataForRoot && !isElement(sourceElementOrDataForRoot)) {
+                // Documented in core/editor/editorconfig.ts.
+                // eslint-disable-next-line ckeditor5-rules/ckeditor-error-message
+                throw new CKEditorError('editor-create-initial-data', null);
+            } else {
+                rootConfig.initialData = legacyInitialData[rootName];
+            }
+        } else if (sourceElementOrDataForRoot && !isElement(sourceElementOrDataForRoot)) {
+            // Documented in core/editor/editorconfig.ts.
+            // eslint-disable-next-line ckeditor5-rules/ckeditor-error-message
+            throw new CKEditorError('editor-create-initial-data', null);
+        } else if (legacyInitialData[rootName] !== undefined) {
+            // Documented in core/editor/editorconfig.ts.
+            // eslint-disable-next-line ckeditor5-rules/ckeditor-error-message
+            throw new CKEditorError('editor-create-roots-initial-data');
+        }
+        // Assign `sourceElement` to root config if it's an element.
+        if (!separateAttachTo && isElement(sourceElementOrDataForRoot)) {
+            rootConfig.element = sourceElementOrDataForRoot;
+        }
+        // Handle legacy `config.placeholder` and `config.label` for the root.
+        rootConfig.placeholder ??= getLegacyPlainConfigValue(config, 'placeholder', rootName);
+        rootConfig.label ??= getLegacyPlainConfigValue(config, 'label', rootName);
+        rootsConfig[rootName] = rootConfig;
+    }
+    // The ClassicEditor has a special separate config option `attachTo`.
+    // It is used as a source of editor data and attachment element, but not the root element.
+    if (separateAttachTo && config.get('attachTo') === undefined && isElement(sourceElementsOrData)) {
+        config.set('attachTo', sourceElementsOrData);
+    }
+    config.set('roots', rootsConfig);
+}
+/**
+ * Normalizes the parameters passed to the editor constructor when a single root is used. It supports both of the following signatures:
+ *
+ * ```ts
+ * new Editor( editorConfig: EditorConfig );
+ * new Editor( sourceElementOrData: HTMLElement | string, editorConfig: EditorConfig );
+ * ```
+ *
+ * @internal
+ */ function normalizeSingleRootEditorConstructorParams(sourceElementOrDataOrConfig, editorConfig) {
+    if (typeof sourceElementOrDataOrConfig === 'string' || isElement(sourceElementOrDataOrConfig) || editorConfig && Object.keys(editorConfig).length) {
+        return {
+            sourceElementOrData: sourceElementOrDataOrConfig,
+            editorConfig
+        };
+    } else {
+        return {
+            sourceElementOrData: '',
+            editorConfig: sourceElementOrDataOrConfig
+        };
+    }
+}
+/**
+ * Normalizes the parameters passed to the editor constructor when a multi root is used. It supports both of the following signatures:
+ *
+ * ```ts
+ * new Editor( editorConfig: EditorConfig );
+ * new Editor( sourceElementsOrData: Record<string, string> | Record<string, HTMLElement>, editorConfig: EditorConfig );
+ * ```
+ *
+ * @internal
+ */ function normalizeMultiRootEditorConstructorParams(sourceElementOrDataOrConfig, editorConfig) {
+    if (editorConfig && Object.keys(editorConfig).length || Object.keys(sourceElementOrDataOrConfig).length == 0 || Object.values(sourceElementOrDataOrConfig).every((value)=>typeof value === 'string' || isElement(value))) {
+        return {
+            sourceElementsOrData: sourceElementOrDataOrConfig,
+            editorConfig
+        };
+    } else {
+        return {
+            sourceElementsOrData: {},
+            editorConfig: sourceElementOrDataOrConfig
+        };
+    }
+}
+/**
+ * Type guard to check if the provided value is a plain object.
+ */ function isPlainObject(sourceElementsOrData) {
+    return !!sourceElementsOrData && typeof sourceElementsOrData == 'object' && !Array.isArray(sourceElementsOrData) && !isElement(sourceElementsOrData);
+}
+/**
+ * Retrieve data from source element or return the string data as is.
+ */ function getInitialData(sourceElementOrData) {
+    return isElement(sourceElementOrData) ? getDataFromElement(sourceElementOrData) : sourceElementOrData;
+}
+/**
+ * Retrieve legacy configuration value for `initialData` from the config.
+ * Normalize single-root config so returned value is always an object with root names as keys.
+ */ function getLegacyInitialData(config, sourceElementIsObject, defaultRootName) {
+    return sourceElementIsObject || !defaultRootName ? config.get('initialData') || Object.create(null) : {
+        [defaultRootName]: config.get('initialData')
+    };
+}
+/**
+ * Retrieve legacy configuration value for `placeholder` or `label` from the config for a specific root.
+ */ function getLegacyPlainConfigValue(config, key, rootName) {
+    const legacyValue = config.get(key);
+    if (legacyValue) {
+        return typeof legacyValue == 'string' ? legacyValue : legacyValue[rootName];
+    }
+}
+/**
+ * An alias for `isElement` from `es-toolkit/compat` with additional type guard.
+ */ function isElement(value) {
+    return isElement$1(value);
+}
+
 /**
  * The list of pending editor actions.
  *
@@ -2991,5 +3146,5 @@ function isTextArea(sourceElement) {
     }
 }
 
-export { Accessibility, Command, CommandCollection, Context, ContextPlugin, EditingKeystrokeHandler, Editor, ElementApiMixin, MultiCommand, PendingActions, Plugin, DEFAULT_GROUP_ID as _DEFAULT_ACCESSIBILITY_GROUP_ID, getEditorUsageData as _getEditorUsageData, attachToForm, secureSourceElement };
+export { Accessibility, Command, CommandCollection, Context, ContextPlugin, EditingKeystrokeHandler, Editor, ElementApiMixin, MultiCommand, PendingActions, Plugin, DEFAULT_GROUP_ID as _DEFAULT_ACCESSIBILITY_GROUP_ID, getEditorUsageData as _getEditorUsageData, attachToForm, normalizeMultiRootEditorConstructorParams, normalizeRootsConfig, normalizeSingleRootEditorConstructorParams, secureSourceElement };
 //# sourceMappingURL=index.js.map