Merge pull request #32 from ckeditor/ck/improve-errors

Feature: Improved error readability in `loadCKEditorCloud`. It should now detect existing editor instances and provide migration info from NPM to CDN.

src/cdn/ck/createCKCdnBaseBundlePack.ts

@@ -3,12 +3,16 @@
  * For licensing, see LICENSE.md.
  */
 
-import type { CKCdnResourcesAdvancedPack } from '../utils/loadCKCdnResourcesPack';
+import type { CKCdnResourcesAdvancedPack } from '@/cdn/utils/loadCKCdnResourcesPack';
+
+import { waitForWindowEntry } from '@/utils/waitForWindowEntry';
+import { injectScriptsInParallel } from '@/utils/injectScript';
+import { without } from '@/utils/without';
+
+import { getCKBaseBundleInstallationInfo } from '@/installation-info/getCKBaseBundleInstallationInfo';
+import { createCKDocsUrl } from '@/docs/createCKDocsUrl';
 
 import { createCKCdnUrl, type CKCdnVersion } from './createCKCdnUrl';
-import { waitForWindowEntry } from '../../utils/waitForWindowEntry';
-import { injectScriptsInParallel } from '../../utils/injectScript';
-import { without } from '../../utils/without';
 
 import './globals.d';
 
@@ -68,7 +72,30 @@ export function createCKCdnBaseBundlePack(
 
 		// Pick the exported global variables from the window object.
 		checkPluginLoaded: async () =>
-			waitForWindowEntry( [ 'CKEDITOR' ] )
+			waitForWindowEntry( [ 'CKEDITOR' ] ),
+
+		// Check if the CKEditor base bundle is already loaded and throw an error if it is.
+		beforeInject: () => {
+			const installationInfo = getCKBaseBundleInstallationInfo();
+
+			switch ( installationInfo?.source ) {
+				case 'npm':
+					throw new Error(
+						'CKEditor 5 is already loaded from npm. Check the migration guide for more details: ' +
+						createCKDocsUrl( 'updating/migration-to-cdn/vanilla-js.html' )
+					);
+
+				case 'cdn':
+					if ( installationInfo.version !== version ) {
+						throw new Error(
+							`CKEditor 5 is already loaded from CDN in version ${ installationInfo.version }. ` +
+							`Remove the old <script> and <link> tags loading CKEditor 5 to allow loading the ${ version } version.`
+						);
+					}
+
+					break;
+			}
+		}
 	};
 }
 

src/cdn/ck/createCKCdnPremiumBundlePack.ts

@@ -3,13 +3,14 @@
  * For licensing, see LICENSE.md.
  */
 
-import type { CKCdnResourcesAdvancedPack } from '../utils/loadCKCdnResourcesPack';
+import type { CKCdnResourcesAdvancedPack } from '@/cdn/utils/loadCKCdnResourcesPack';
 import type { CKCdnBaseBundlePackConfig } from './createCKCdnBaseBundlePack';
 
+import { waitForWindowEntry } from '@/utils/waitForWindowEntry';
+import { injectScriptsInParallel } from '@/utils/injectScript';
+import { without } from '@/utils/without';
+
 import { createCKCdnUrl } from './createCKCdnUrl';
-import { waitForWindowEntry } from '../../utils/waitForWindowEntry';
-import { injectScriptsInParallel } from '../../utils/injectScript';
-import { without } from '../../utils/without';
 
 import './globals.d';
 

src/cdn/ck/createCKCdnUrl.ts

@@ -3,6 +3,8 @@
  * For licensing, see LICENSE.md.
  */
 
+import type { SemanticVersion } from '@/utils/isSemanticVersion';
+
 /**
  * The URL of the CKEditor CDN.
  */
@@ -11,7 +13,7 @@ export const CK_CDN_URL = 'https://cdn.ckeditor.com';
 /**
  * A version of a file on the CKEditor CDN.
  */
-export type CKCdnVersion = `${ number }.${ number }.${ number }`;
+export type CKCdnVersion = SemanticVersion;
 
 /**
  * Creates a URL to a file on the CKEditor CDN.

src/cdn/ckbox/createCKBoxCdnBundlePack.ts

@@ -3,9 +3,10 @@
  * For licensing, see LICENSE.md.
  */
 
-import type { CKCdnResourcesAdvancedPack } from '../utils/loadCKCdnResourcesPack';
+import { waitForWindowEntry } from '@/utils/waitForWindowEntry';
+import { getCKBoxInstallationInfo } from '@/installation-info/getCKBoxInstallationInfo';
 
-import { waitForWindowEntry } from '../../utils/waitForWindowEntry';
+import type { CKCdnResourcesAdvancedPack } from '@/cdn/utils/loadCKCdnResourcesPack';
 import { createCKBoxCdnUrl, type CKBoxCdnVersion } from './createCKBoxCdnUrl';
 
 import './globals.d';
@@ -39,14 +40,24 @@ export function createCKBoxBundlePack(
 
 		// Load optional theme, if provided. It's not required but recommended because it improves the look and feel.
 		...theme && {
-			stylesheets: [
-				createCKBoxCdnUrl( 'ckbox', `styles/themes/${ theme }.css`, version )
-			]
+			stylesheets: [ createCKBoxCdnUrl( 'ckbox', `styles/themes/${ theme }.css`, version ) ]
 		},
 
 		// Pick the exported global variables from the window object.
 		checkPluginLoaded: async () =>
-			waitForWindowEntry( [ 'CKBox' ] )
+			waitForWindowEntry( [ 'CKBox' ] ),
+
+		// Check if the CKBox bundle is already loaded and throw an error if it is.
+		beforeInject: () => {
+			const installationInfo = getCKBoxInstallationInfo();
+
+			if ( installationInfo && installationInfo.version !== version ) {
+				throw new Error(
+					`CKBox is already loaded from CDN in version ${ installationInfo.version }. ` +
+					`Remove the old <script> and <link> tags loading CKBox to allow loading the ${ version } version.`
+				);
+			}
+		}
 	};
 }
 

src/cdn/ckbox/createCKBoxCdnUrl.ts

@@ -3,6 +3,8 @@
  * For licensing, see LICENSE.md.
  */
 
+import type { SemanticVersion } from '@/utils/isSemanticVersion';
+
 /**
  * The URL of the CKBox CDN.
  */
@@ -11,7 +13,7 @@ export const CKBOX_CDN_URL = 'https://cdn.ckbox.io';
 /**
  * A version of a file on the CKBox CDN.
  */
-export type CKBoxCdnVersion = `${ number }.${ number }.${ number }`;
+export type CKBoxCdnVersion = SemanticVersion;
 
 /**
  * Creates a URL to a file on the CKBox CDN.

src/cdn/plugins/combineCdnPluginsPacks.ts

@@ -3,8 +3,8 @@
  * For licensing, see LICENSE.md.
  */
 
-import { mapObjectValues } from '../../utils/mapObjectValues';
-import { waitForWindowEntry } from '../../utils/waitForWindowEntry';
+import { mapObjectValues } from '@/utils/mapObjectValues';
+import { waitForWindowEntry } from '@/utils/waitForWindowEntry';
 
 import {
 	normalizeCKCdnResourcesPack,

src/cdn/utils/combineCKCdnBundlesPacks.ts

@@ -3,8 +3,9 @@
  * For licensing, see LICENSE.md.
  */
 
-import { filterBlankObjectValues } from '../../utils/filterBlankObjectValues';
-import { mapObjectValues } from '../../utils/mapObjectValues';
+import { filterBlankObjectValues } from '@/utils/filterBlankObjectValues';
+import { mapObjectValues } from '@/utils/mapObjectValues';
+
 import {
 	normalizeCKCdnResourcesPack,
 	type CKCdnResourcesPack,
@@ -71,8 +72,16 @@ export function combineCKCdnBundlesPacks<P extends CKCdnBundlesPacks>( packs: P
 		return exportedGlobalVariables as any;
 	};
 
+	// Call beforeInject method of all packs.
+	const beforeInject = () => {
+		for ( const pack of Object.values( normalizedPacks ) ) {
+			pack.beforeInject?.();
+		}
+	};
+
 	return {
 		...mergedPacks,
+		beforeInject,
 		checkPluginLoaded
 	};
 }

src/cdn/utils/loadCKCdnResourcesPack.ts

@@ -3,12 +3,12 @@
  * For licensing, see LICENSE.md.
  */
 
-import type { Awaitable } from '../../types/Awaitable';
+import type { Awaitable } from '@/types/Awaitable';
 
-import { injectScript, type InjectScriptProps } from '../../utils/injectScript';
-import { injectStylesheet } from '../../utils/injectStylesheet';
-import { preloadResource } from '../../utils/preloadResource';
-import { uniq } from '../../utils/uniq';
+import { injectScript, type InjectScriptProps } from '@/utils/injectScript';
+import { injectStylesheet } from '@/utils/injectStylesheet';
+import { preloadResource } from '@/utils/preloadResource';
+import { uniq } from '@/utils/uniq';
 
 /**
  * Loads pack of resources (scripts and stylesheets) and returns the exported global variables (if any).
@@ -32,9 +32,13 @@ export async function loadCKCdnResourcesPack<P extends CKCdnResourcesPack<any>>(
 		scripts = [],
 		stylesheets = [],
 		preload,
+		beforeInject,
 		checkPluginLoaded
 	} = normalizeCKCdnResourcesPack( pack );
 
+	// Execute the `beforeInject` callback if defined. It checks if the resources are already loaded.
+	beforeInject?.();
+
 	// If preload is not defined, use all stylesheets and scripts as preload resources.
 	if ( !preload ) {
 		preload = uniq( [
@@ -174,6 +178,11 @@ export type CKCdnResourcesAdvancedPack<R> = {
 	 */
 	htmlAttributes?: Record<string, any>;
 
+	/**
+	 * Callback that is executed before injecting the resources. It can be used to verify if the resources are already loaded.
+	 */
+	beforeInject?: () => void;
+
 	/**
 	 * Get JS object with global variables exported by scripts.
 	 */

src/docs/createCKDocsUrl.ts

@@ -0,0 +1,15 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import type { SemanticVersion } from '@/utils/isSemanticVersion';
+
+export const CK_DOCS_URL = 'https://ckeditor.com/docs/ckeditor5';
+
+/**
+ * Creates a URL to a file on the CKEditor documentation.
+ */
+export function createCKDocsUrl( path: string, version: SemanticVersion | 'latest' = 'latest' ): string {
+	return `${ CK_DOCS_URL }/${ version }/${ path }`;
+}

src/installation-info/getCKBaseBundleInstallationInfo.ts

@@ -0,0 +1,25 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import type { BundleInstallationInfo } from './types';
+
+import { isSemanticVersion } from '@/utils/isSemanticVersion';
+
+/**
+ * Returns information about the base CKEditor bundle installation.
+ */
+export function getCKBaseBundleInstallationInfo(): BundleInstallationInfo | null {
+	const { CKEDITOR_VERSION, CKEDITOR } = window;
+
+	if ( !isSemanticVersion( CKEDITOR_VERSION ) ) {
+		return null;
+	}
+
+	// Global `CKEDITOR` is set only in CDN builds.
+	return {
+		source: CKEDITOR ? 'cdn' : 'npm',
+		version: CKEDITOR_VERSION
+	};
+}

src/installation-info/getCKBoxInstallationInfo.ts

@@ -0,0 +1,24 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import type { BundleInstallationInfo } from './types';
+
+import { isSemanticVersion } from '@/utils/isSemanticVersion';
+
+/**
+ * Returns information about the CKBox installation.
+ */
+export function getCKBoxInstallationInfo(): BundleInstallationInfo | null {
+	const version = window.CKBox?.version;
+
+	if ( !isSemanticVersion( version ) ) {
+		return null;
+	}
+
+	return {
+		source: 'cdn',
+		version
+	};
+}

src/installation-info/types.ts

@@ -0,0 +1,27 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+import type { SemanticVersion } from '@/utils/isSemanticVersion';
+
+/**
+ * The source from which CKEditor was installed.
+ */
+type BundleInstallationSource = 'npm' | 'cdn';
+
+/**
+ * Information about the currently installed CKEditor.
+ */
+export type BundleInstallationInfo = {
+
+	/**
+	 * The source from which CKEditor was installed.
+	 */
+	source: BundleInstallationSource;
+
+	/**
+	 * The version of CKEditor.
+	 */
+	version: SemanticVersion;
+};

src/utils/isSemanticVersion.ts

@@ -0,0 +1,16 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+export type SemanticVersion = `${ number }.${ number }.${ number }`;
+
+/**
+ * Checks if the given string is a semantic version number.
+ *
+ * @param version - The string to check.
+ * @returns `true` if the string is a semantic version, `false` otherwise.
+ */
+export function isSemanticVersion( version: string | undefined | null ): version is SemanticVersion {
+	return !!version && /^\d+\.\d+\.\d+/.test( version );
+}