@ckeditor/ckeditor5-emoji 44.2.0-alpha.14 → 44.2.0-alpha.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-emoji",
-  "version": "44.2.0-alpha.14",
+  "version": "44.2.0-alpha.16",
   "description": "Emoji feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -13,12 +13,12 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-core": "44.2.0-alpha.14",
-    "@ckeditor/ckeditor5-mention": "44.2.0-alpha.14",
-    "@ckeditor/ckeditor5-typing": "44.2.0-alpha.14",
-    "@ckeditor/ckeditor5-ui": "44.2.0-alpha.14",
-    "@ckeditor/ckeditor5-utils": "44.2.0-alpha.14",
-    "ckeditor5": "44.2.0-alpha.14",
+    "@ckeditor/ckeditor5-core": "44.2.0-alpha.16",
+    "@ckeditor/ckeditor5-mention": "44.2.0-alpha.16",
+    "@ckeditor/ckeditor5-typing": "44.2.0-alpha.16",
+    "@ckeditor/ckeditor5-ui": "44.2.0-alpha.16",
+    "@ckeditor/ckeditor5-utils": "44.2.0-alpha.16",
+    "ckeditor5": "44.2.0-alpha.16",
     "fuse.js": "7.0.0",
     "lodash-es": "4.17.21"
   },

package/src/emojiconfig.d.ts

@@ -58,6 +58,22 @@ export interface EmojiConfig {
      * @default 'default'
      */
     skinTone?: SkinToneId;
+    /**
+     * The URL from which the emoji definitions should be loaded.
+     *
+     * ```ts
+     *	ClassicEditor
+     *		.create( editorElement, {
+     *			plugins: [ Emoji, ... ],
+     *			emoji: {
+     *				definitionsUrl: ''
+     *			}
+     *		} )
+     *		.then( ... )
+     *		.catch( ... );
+     * ```
+     */
+    definitionsUrl?: string;
     /**
      * The emoji database version.
      *
@@ -73,7 +89,8 @@ export interface EmojiConfig {
      *		.catch( ... );
      * ```
      *
-     * @default 16
+     * If the {@link module:emoji/emojiconfig~EmojiConfig#definitionsUrl `emoji.definitionsUrl`}
+     * option is provided, `version` is ignored as the defined URL takes precedence over the `version`.
      */
     version?: EmojiVersion;
 }

package/src/emojirepository.d.ts

@@ -20,9 +20,9 @@ export default class EmojiRepository extends Plugin {
      */
     private _fuseSearch;
     /**
-     * The emoji version that is used to prepare the emoji repository.
+     * The resolved URL from which the emoji repository is downloaded.
      */
-    private readonly _version;
+    private readonly _url;
     /**
      * A promise resolved after downloading the emoji collection.
      * The promise resolves with `true` when the repository is successfully downloaded or `false` otherwise.
@@ -72,14 +72,26 @@ export default class EmojiRepository extends Plugin {
      * Indicates whether the emoji repository has been successfully downloaded and the plugin is operational.
      */
     isReady(): Promise<boolean>;
+    /**
+     * Returns the URL from which the emoji repository is downloaded. If the URL is not provided
+     * in the configuration, the default URL is used with the version from the configuration.
+     *
+     * If both the URL and version are provided, a warning is logged.
+     */
+    private _getUrl;
+    /**
+     * Warn users on self-hosted installations that this plugin uses a CDN to fetch the emoji repository.
+     */
+    private _warnAboutCdnUse;
     /**
      * Returns the emoji repository in a configured version if it is a non-empty array. Returns `null` otherwise.
      */
     private _getItems;
     /**
-     * Makes the HTTP request to download the emoji repository in a configured version.
+     * Loads the emoji repository. If the repository is already loaded, it returns the cached result.
+     * Otherwise, it fetches the repository from the URL and adds it to the cache.
      */
-    private _loadItemsFromCdn;
+    private _loadAndCacheEmoji;
     /**
      * Normalizes the raw data fetched from CDN. By normalization, we meant:
      *

package/src/emojirepository.js

@@ -8,11 +8,12 @@
 import Fuse from 'fuse.js';
 import { groupBy } from 'lodash-es';
 import { Plugin } from 'ckeditor5/src/core.js';
-import { logWarning, version } from 'ckeditor5/src/utils.js';
+import { logWarning, version as editorVersion } from 'ckeditor5/src/utils.js';
 import EmojiUtils from './emojiutils.js';
 // An endpoint from which the emoji data will be downloaded during plugin initialization.
 // The `{version}` placeholder is replaced with the value from editor config.
-const EMOJI_DATABASE_URL = 'https://cdn.ckeditor.com/ckeditor5/data/emoji/{version}/en.json';
+const DEFAULT_EMOJI_DATABASE_URL = 'https://cdn.ckeditor.com/ckeditor5/data/emoji/{version}/en.json';
+const DEFAULT_EMOJI_VERSION = 16;
 /**
  * The emoji repository plugin.
  *
@@ -43,10 +44,11 @@ class EmojiRepository extends Plugin {
     constructor(editor) {
         super(editor);
         editor.config.define('emoji', {
-            version: 16,
-            skinTone: 'default'
+            version: undefined,
+            skinTone: 'default',
+            definitionsUrl: undefined
         });
-        this._version = editor.config.get('emoji.version');
+        this._url = this._getUrl();
         this._repositoryPromise = new Promise(resolve => {
             this._repositoryPromiseResolveCallback = resolve;
         });
@@ -56,10 +58,8 @@ class EmojiRepository extends Plugin {
      * @inheritDoc
      */
     async init() {
-        if (!(this._version in EmojiRepository._results)) {
-            const cdnResult = await this._loadItemsFromCdn();
-            EmojiRepository._results[this._version] = this._normalizeEmoji(cdnResult);
-        }
+        this._warnAboutCdnUse();
+        await this._loadAndCacheEmoji();
         const items = this._getItems();
         // Skip plugin initialization if the emoji repository is not available.
         // The initialization of other dependent plugins, such as `EmojiMention` and `EmojiPicker`, is prevented as well.
@@ -164,20 +164,83 @@ class EmojiRepository extends Plugin {
     isReady() {
         return this._repositoryPromise;
     }
+    /**
+     * Returns the URL from which the emoji repository is downloaded. If the URL is not provided
+     * in the configuration, the default URL is used with the version from the configuration.
+     *
+     * If both the URL and version are provided, a warning is logged.
+     */
+    _getUrl() {
+        const { definitionsUrl, version } = this.editor.config.get('emoji');
+        if (!definitionsUrl || definitionsUrl === 'cdn') {
+            // URL was not provided or is set to 'cdn', so we use the default CDN URL.
+            const urlVersion = version || DEFAULT_EMOJI_VERSION;
+            const url = new URL(DEFAULT_EMOJI_DATABASE_URL.replace('{version}', urlVersion.toString()));
+            url.searchParams.set('editorVersion', editorVersion);
+            return url;
+        }
+        if (version) {
+            /**
+             * Both {@link module:emoji/emojiconfig~EmojiConfig#definitionsUrl `emoji.definitionsUrl`} and
+             * {@link module:emoji/emojiconfig~EmojiConfig#version `emoji.version`} configuration options
+             * are set. Only the `emoji.definitionsUrl` option will be used.
+             *
+             * The `emoji.version` option will be ignored and should be removed from the configuration.
+             *
+             * @error emoji-repository-redundant-version
+             */
+            logWarning('emoji-repository-redundant-version');
+        }
+        return new URL(definitionsUrl);
+    }
+    /**
+     * Warn users on self-hosted installations that this plugin uses a CDN to fetch the emoji repository.
+     */
+    _warnAboutCdnUse() {
+        const editor = this.editor;
+        const config = editor.config.get('emoji');
+        const licenseKey = editor.config.get('licenseKey');
+        const distributionChannel = window[Symbol.for('cke distribution')];
+        if (licenseKey === 'GPL') {
+            // Don't warn GPL users.
+            return;
+        }
+        if (distributionChannel === 'cloud') {
+            // Don't warn cloud users, because they already use our CDN.
+            return;
+        }
+        if (config && config.definitionsUrl) {
+            // Don't warn users who have configured their own definitions URL.
+            return;
+        }
+        /**
+         * By default, the Emoji plugin fetches the emoji repository from CKEditor 5 CDN. To avoid this,
+         * you can use the {@link module:emoji/emojiconfig~EmojiConfig#definitionsUrl `emoji.definitionsUrl`}
+         * configuration option to provide a URL to your own emoji repository.
+         *
+         * If you only want to suppress this warning, set this configuration option to `cdn`.
+         *
+         * @error emoji-repository-cdn-use
+         */
+        logWarning('emoji-repository-cdn-use');
+    }
     /**
      * Returns the emoji repository in a configured version if it is a non-empty array. Returns `null` otherwise.
      */
     _getItems() {
-        const repository = EmojiRepository._results[this._version];
+        const repository = EmojiRepository._results[this._url.href];
         return repository && repository.length ? repository : null;
     }
     /**
-     * Makes the HTTP request to download the emoji repository in a configured version.
+     * Loads the emoji repository. If the repository is already loaded, it returns the cached result.
+     * Otherwise, it fetches the repository from the URL and adds it to the cache.
      */
-    async _loadItemsFromCdn() {
-        const repositoryUrl = new URL(EMOJI_DATABASE_URL.replace('{version}', `${this._version}`));
-        repositoryUrl.searchParams.set('editorVersion', version);
-        const result = await fetch(repositoryUrl, { cache: 'force-cache' })
+    async _loadAndCacheEmoji() {
+        if (EmojiRepository._results[this._url.href]) {
+            // The repository has already been downloaded.
+            return;
+        }
+        const result = await fetch(this._url, { cache: 'force-cache' })
             .then(response => {
             if (!response.ok) {
                 return [];
@@ -189,17 +252,17 @@ class EmojiRepository extends Plugin {
         });
         if (!result.length) {
             /**
-             * Unable to load the emoji repository from CDN.
+             * Unable to load the emoji repository from the URL.
              *
-             * If the CDN works properly and there is no disruption of communication, please check your
+             * If the URL works properly and there is no disruption of communication, please check your
              * {@glink getting-started/setup/csp Content Security Policy (CSP)} setting and make sure
-             * the CDN connection is allowed by the editor.
+             * the URL connection is allowed by the editor.
              *
              * @error emoji-repository-load-failed
              */
             logWarning('emoji-repository-load-failed');
         }
-        return result;
+        EmojiRepository._results[this._url.href] = this._normalizeEmoji(result);
     }
     /**
      * Normalizes the raw data fetched from CDN. By normalization, we meant: