@ckeditor/ckeditor5-emoji 44.2.0-alpha.8 → 44.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-emoji",
-  "version": "44.2.0-alpha.8",
+  "version": "44.2.0",
   "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.8",
-    "@ckeditor/ckeditor5-mention": "44.2.0-alpha.8",
-    "@ckeditor/ckeditor5-typing": "44.2.0-alpha.8",
-    "@ckeditor/ckeditor5-ui": "44.2.0-alpha.8",
-    "@ckeditor/ckeditor5-utils": "44.2.0-alpha.8",
-    "ckeditor5": "44.2.0-alpha.8",
+    "@ckeditor/ckeditor5-core": "44.2.0",
+    "@ckeditor/ckeditor5-mention": "44.2.0",
+    "@ckeditor/ckeditor5-typing": "44.2.0",
+    "@ckeditor/ckeditor5-ui": "44.2.0",
+    "@ckeditor/ckeditor5-utils": "44.2.0",
+    "ckeditor5": "44.2.0",
     "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,8 +89,10 @@ 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?: 15 | 16;
+    version?: EmojiVersion;
 }
 export type SkinToneId = 'default' | 'light' | 'medium-light' | 'medium' | 'medium-dark' | 'dark';
+export type EmojiVersion = 15 | 16;

package/src/emojimention.js

@@ -176,6 +176,10 @@ export default class EmojiMention extends Plugin {
             if (searchQuery.startsWith(' ')) {
                 return [];
             }
+            // Do not show anything when a query starts with a marker character.
+            if (searchQuery.startsWith(EMOJI_MENTION_MARKER)) {
+                return [];
+            }
             // If the repository plugin is not available, return an empty feed to avoid confusion. See: #17842.
             if (!this._isEmojiRepositoryAvailable) {
                 return [];

package/src/emojirepository.d.ts

@@ -8,26 +8,26 @@ import type { SkinToneId } from './emojiconfig.js';
 /**
  * The emoji repository plugin.
  *
- * Loads the emoji database from URL during plugin initialization and provides utility methods to search it.
+ * Loads the emoji repository from URL during plugin initialization and provides utility methods to search it.
  */
 export default class EmojiRepository extends Plugin {
     /**
-     * A callback to resolve the {@link #_databasePromise} to control the return value of this promise.
+     * A callback to resolve the {@link #_repositoryPromise} to control the return value of this promise.
      */
-    private _databasePromiseResolveCallback;
+    private _repositoryPromiseResolveCallback;
     /**
      * An instance of the [Fuse.js](https://www.fusejs.io/) library.
      */
     private _fuseSearch;
     /**
-     * Emoji database.
+     * The resolved URL from which the emoji repository is downloaded.
      */
-    private _database;
+    private readonly _url;
     /**
-     * A promise resolved after downloading the emoji database.
-     * The promise resolves with `true` when the database is successfully downloaded or `false` otherwise.
+     * A promise resolved after downloading the emoji collection.
+     * The promise resolves with `true` when the repository is successfully downloaded or `false` otherwise.
      */
-    private readonly _databasePromise;
+    private readonly _repositoryPromise;
     /**
      * @inheritDoc
      */
@@ -50,7 +50,7 @@ export default class EmojiRepository extends Plugin {
     init(): Promise<void>;
     /**
      * Returns an array of emoji entries that match the search query.
-     * If the emoji database is not loaded, the [Fuse.js](https://www.fusejs.io/) instance is not created,
+     * If the emoji repository is not loaded, the [Fuse.js](https://www.fusejs.io/) instance is not created,
      * hence this method returns an empty array.
      *
      * @param searchQuery A search query to match emoji.
@@ -59,7 +59,7 @@ export default class EmojiRepository extends Plugin {
     getEmojiByQuery(searchQuery: string): Array<EmojiEntry>;
     /**
      * Groups all emojis by categories.
-     * If the emoji database is not loaded, it returns an empty array.
+     * If the emoji repository is not loaded, it returns an empty array.
      *
      * @returns An array of emoji entries grouped by categories.
      */
@@ -69,9 +69,40 @@ export default class EmojiRepository extends Plugin {
      */
     getSkinTones(): Array<SkinTone>;
     /**
-     * Indicates whether the emoji database has been successfully downloaded and the plugin is operational.
+     * 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;
+    /**
+     * 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 _loadAndCacheEmoji;
+    /**
+     * Normalizes the raw data fetched from CDN. By normalization, we meant:
+     *
+     *  * Filter out unsupported emoji (these that will not render correctly),
+     *  * Prepare skin tone variants if an emoji defines them.
+     */
+    private _normalizeEmoji;
+    /**
+     * Versioned emoji repository.
+     */
+    private static _results;
 }
 /**
  * Represents a single group of the emoji category, e.g., "Smileys & Expressions".

package/src/emojirepository.js

@@ -8,17 +8,18 @@
 import Fuse from 'fuse.js';
 import { groupBy } from 'lodash-es';
 import { Plugin } from 'ckeditor5/src/core.js';
-import { logWarning } 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 database will be downloaded during plugin initialization.
+// 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.
  *
- * Loads the emoji database from URL during plugin initialization and provides utility methods to search it.
+ * Loads the emoji repository from URL during plugin initialization and provides utility methods to search it.
  */
-export default class EmojiRepository extends Plugin {
+class EmojiRepository extends Plugin {
     /**
      * @inheritDoc
      */
@@ -42,13 +43,14 @@ export default class EmojiRepository extends Plugin {
      */
     constructor(editor) {
         super(editor);
-        this.editor.config.define('emoji', {
-            version: 16,
-            skinTone: 'default'
+        editor.config.define('emoji', {
+            version: undefined,
+            skinTone: 'default',
+            definitionsUrl: undefined
         });
-        this._database = [];
-        this._databasePromise = new Promise(resolve => {
-            this._databasePromiseResolveCallback = resolve;
+        this._url = this._getUrl();
+        this._repositoryPromise = new Promise(resolve => {
+            this._repositoryPromiseResolveCallback = resolve;
         });
         this._fuseSearch = null;
     }
@@ -56,26 +58,16 @@ export default class EmojiRepository extends Plugin {
      * @inheritDoc
      */
     async init() {
-        const emojiUtils = this.editor.plugins.get('EmojiUtils');
-        const emojiVersion = this.editor.config.get('emoji.version');
-        const emojiDatabaseUrl = EMOJI_DATABASE_URL.replace('{version}', `${emojiVersion}`);
-        const emojiDatabase = await loadEmojiDatabase(emojiDatabaseUrl);
-        const emojiSupportedVersionByOs = emojiUtils.getEmojiSupportedVersionByOs();
-        // Skip the initialization if the emoji database download has failed.
-        // An empty database prevents the initialization of other dependent plugins, such as `EmojiMention` and `EmojiPicker`.
-        if (!emojiDatabase.length) {
-            return this._databasePromiseResolveCallback(false);
+        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.
+        if (!items) {
+            return this._repositoryPromiseResolveCallback(false);
         }
-        const container = emojiUtils.createEmojiWidthTestingContainer();
-        document.body.appendChild(container);
-        // Store the emoji database after normalizing the raw data.
-        this._database = emojiDatabase
-            .filter(item => emojiUtils.isEmojiCategoryAllowed(item))
-            .filter(item => emojiUtils.isEmojiSupported(item, emojiSupportedVersionByOs, container))
-            .map(item => emojiUtils.normalizeEmojiSkinTone(item));
-        container.remove();
         // Create instance of the Fuse.js library with configured weighted search keys and disabled fuzzy search.
-        this._fuseSearch = new Fuse(this._database, {
+        this._fuseSearch = new Fuse(items, {
             keys: [
                 { name: 'emoticon', weight: 5 },
                 { name: 'annotation', weight: 3 },
@@ -85,11 +77,11 @@ export default class EmojiRepository extends Plugin {
             threshold: 0,
             ignoreLocation: true
         });
-        return this._databasePromiseResolveCallback(true);
+        return this._repositoryPromiseResolveCallback(true);
     }
     /**
      * Returns an array of emoji entries that match the search query.
-     * If the emoji database is not loaded, the [Fuse.js](https://www.fusejs.io/) instance is not created,
+     * If the emoji repository is not loaded, the [Fuse.js](https://www.fusejs.io/) instance is not created,
      * hence this method returns an empty array.
      *
      * @param searchQuery A search query to match emoji.
@@ -123,12 +115,13 @@ export default class EmojiRepository extends Plugin {
     }
     /**
      * Groups all emojis by categories.
-     * If the emoji database is not loaded, it returns an empty array.
+     * If the emoji repository is not loaded, it returns an empty array.
      *
      * @returns An array of emoji entries grouped by categories.
      */
     getEmojiCategories() {
-        if (!this._database.length) {
+        const repository = this._getItems();
+        if (!repository) {
             return [];
         }
         const { t } = this.editor.locale;
@@ -143,7 +136,7 @@ export default class EmojiRepository extends Plugin {
             { title: t('Symbols'), icon: '🟢', groupId: 8 },
             { title: t('Flags'), icon: '🏁', groupId: 9 }
         ];
-        const groups = groupBy(this._database, 'group');
+        const groups = groupBy(repository, 'group');
         return categories.map(category => {
             return {
                 ...category,
@@ -166,37 +159,132 @@ export default class EmojiRepository extends Plugin {
         ];
     }
     /**
-     * Indicates whether the emoji database has been successfully downloaded and the plugin is operational.
+     * Indicates whether the emoji repository has been successfully downloaded and the plugin is operational.
      */
     isReady() {
-        return this._databasePromise;
+        return this._repositoryPromise;
     }
-}
-/**
- * Makes the HTTP request to download the emoji database.
- */
-async function loadEmojiDatabase(emojiDatabaseUrl) {
-    const result = await fetch(emojiDatabaseUrl)
-        .then(response => {
-        if (!response.ok) {
-            return [];
+    /**
+     * 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;
         }
-        return response.json();
-    })
-        .catch(() => {
-        return [];
-    });
-    if (!result.length) {
         /**
-         * Unable to load the emoji database from CDN.
+         * 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 the CDN 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.
+         * If you only want to suppress this warning, set this configuration option to `cdn`.
          *
-         * @error emoji-database-load-failed
+         * @error emoji-repository-cdn-use
          */
-        logWarning('emoji-database-load-failed');
+        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._url.href];
+        return repository && repository.length ? repository : null;
+    }
+    /**
+     * 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 _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 [];
+            }
+            return response.json();
+        })
+            .catch(() => {
+            return [];
+        });
+        if (!result.length) {
+            /**
+             * Unable to load the emoji repository from the URL.
+             *
+             * 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 URL connection is allowed by the editor.
+             *
+             * @error emoji-repository-load-failed
+             */
+            logWarning('emoji-repository-load-failed');
+        }
+        EmojiRepository._results[this._url.href] = this._normalizeEmoji(result);
+    }
+    /**
+     * Normalizes the raw data fetched from CDN. By normalization, we meant:
+     *
+     *  * Filter out unsupported emoji (these that will not render correctly),
+     *  * Prepare skin tone variants if an emoji defines them.
+     */
+    _normalizeEmoji(data) {
+        const emojiUtils = this.editor.plugins.get('EmojiUtils');
+        const emojiSupportedVersionByOs = emojiUtils.getEmojiSupportedVersionByOs();
+        const container = emojiUtils.createEmojiWidthTestingContainer();
+        document.body.appendChild(container);
+        const results = data
+            .filter(item => emojiUtils.isEmojiCategoryAllowed(item))
+            .filter(item => emojiUtils.isEmojiSupported(item, emojiSupportedVersionByOs, container))
+            .map(item => emojiUtils.normalizeEmojiSkinTone(item));
+        container.remove();
+        return results;
     }
-    return result;
 }
+/**
+ * Versioned emoji repository.
+ */
+EmojiRepository._results = {};
+export default EmojiRepository;

package/src/utils/isemojisupported.js

@@ -59,7 +59,7 @@ export default function isEmojiSupported(unicode) {
 ;
 function getCanvas() {
     try {
-        return document.createElement('canvas').getContext('2d');
+        return document.createElement('canvas').getContext('2d', { willReadFrequently: true });
     }
     catch {
         /* istanbul ignore next -- @preserve */