@ckeditor/ckeditor5-emoji 0.0.1 → 44.2.0-alpha.0

package/src/emojipicker.js

@@ -0,0 +1,255 @@
+/**
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+ */
+/**
+ * @module emoji/emojipicker
+ */
+import { ButtonView, clickOutsideHandler, ContextualBalloon, Dialog, MenuBarMenuListItemButtonView } from 'ckeditor5/src/ui.js';
+import { icons, Plugin } from 'ckeditor5/src/core.js';
+import { Typing } from 'ckeditor5/src/typing.js';
+import EmojiCommand from './emojicommand.js';
+import EmojiRepository from './emojirepository.js';
+import EmojiPickerView from './ui/emojipickerview.js';
+import '../theme/emojipicker.css';
+const VISUAL_SELECTION_MARKER_NAME = 'emoji-picker';
+/**
+ * The emoji picker plugin.
+ *
+ * Introduces the `'emoji'` dropdown.
+ */
+export default class EmojiPicker extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [EmojiRepository, ContextualBalloon, Dialog, Typing];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'EmojiPicker';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    async init() {
+        const editor = this.editor;
+        this._balloonPlugin = editor.plugins.get('ContextualBalloon');
+        this._emojiRepositoryPlugin = editor.plugins.get('EmojiRepository');
+        // Skip registering a button in the toolbar and list item in the menu bar if the emoji repository is not ready.
+        if (!await this._emojiRepositoryPlugin.isReady()) {
+            return;
+        }
+        const command = new EmojiCommand(editor);
+        editor.commands.add('emoji', command);
+        editor.ui.componentFactory.add('emoji', () => {
+            const button = this._createButton(ButtonView, command);
+            button.set({
+                tooltip: true
+            });
+            return button;
+        });
+        editor.ui.componentFactory.add('menuBar:emoji', () => {
+            return this._createButton(MenuBarMenuListItemButtonView, command);
+        });
+        this._setupConversion();
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        if (this.emojiPickerView) {
+            this.emojiPickerView.destroy();
+        }
+    }
+    /**
+     * Represents an active skin tone. Its value depends on the emoji UI plugin.
+     *
+     * Before opening the UI for the first time, the returned value is read from the editor configuration.
+     * Otherwise, it reflects the user's intention.
+     */
+    get skinTone() {
+        if (!this.emojiPickerView) {
+            return this.editor.config.get('emoji.skinTone');
+        }
+        return this.emojiPickerView.gridView.skinTone;
+    }
+    /**
+     * Displays the balloon with the emoji picker.
+     *
+     * @param [searchValue=''] A default query used to filer the grid when opening the UI.
+     */
+    showUI(searchValue = '') {
+        // Show visual selection on a text when the contextual balloon is displayed.
+        // See #17654.
+        this._showFakeVisualSelection();
+        if (!this.emojiPickerView) {
+            this.emojiPickerView = this._createEmojiPickerView();
+        }
+        if (searchValue) {
+            this.emojiPickerView.searchView.setInputValue(searchValue);
+        }
+        this.emojiPickerView.searchView.search(searchValue);
+        if (!this._balloonPlugin.hasView(this.emojiPickerView)) {
+            this._balloonPlugin.add({
+                view: this.emojiPickerView,
+                position: this._getBalloonPositionData()
+            });
+        }
+        this.emojiPickerView.focus();
+    }
+    /**
+     * Creates a button for toolbar and menu bar that will show the emoji dialog.
+     */
+    _createButton(ViewClass, command) {
+        const buttonView = new ViewClass(this.editor.locale);
+        const t = this.editor.locale.t;
+        buttonView.bind('isEnabled').to(command, 'isEnabled');
+        buttonView.set({
+            label: t('Emoji'),
+            icon: icons.emoji,
+            isToggleable: true
+        });
+        buttonView.on('execute', () => {
+            this.showUI();
+        });
+        return buttonView;
+    }
+    /**
+     * Creates an instance of the `EmojiPickerView` class that represents an emoji balloon.
+     */
+    _createEmojiPickerView() {
+        const emojiPickerView = new EmojiPickerView(this.editor.locale, {
+            emojiCategories: this._emojiRepositoryPlugin.getEmojiCategories(),
+            skinTone: this.editor.config.get('emoji.skinTone'),
+            skinTones: this._emojiRepositoryPlugin.getSkinTones(),
+            getEmojiByQuery: (query) => {
+                return this._emojiRepositoryPlugin.getEmojiByQuery(query);
+            }
+        });
+        // Insert an emoji on a tile click.
+        this.listenTo(emojiPickerView.gridView, 'execute', (evt, data) => {
+            const editor = this.editor;
+            const textToInsert = data.emoji;
+            this._hideUI();
+            editor.execute('insertText', { text: textToInsert });
+        });
+        // Update the balloon position when layout is changed.
+        this.listenTo(emojiPickerView, 'update', () => {
+            if (this._balloonPlugin.visibleView === emojiPickerView) {
+                this._balloonPlugin.updatePosition();
+            }
+        });
+        // Close the panel on `Esc` key press when the **actions have focus**.
+        emojiPickerView.keystrokes.set('Esc', (data, cancel) => {
+            this._hideUI();
+            cancel();
+        });
+        // Close the dialog when clicking outside of it.
+        clickOutsideHandler({
+            emitter: emojiPickerView,
+            contextElements: [this._balloonPlugin.view.element],
+            callback: () => this._hideUI(),
+            activator: () => this._balloonPlugin.visibleView === emojiPickerView
+        });
+        return emojiPickerView;
+    }
+    /**
+     * Hides the balloon with the emoji picker.
+     */
+    _hideUI() {
+        this._balloonPlugin.remove(this.emojiPickerView);
+        this.emojiPickerView.searchView.setInputValue('');
+        this.editor.editing.view.focus();
+        this._hideFakeVisualSelection();
+    }
+    /**
+     * Registers converters.
+     */
+    _setupConversion() {
+        const editor = this.editor;
+        // Renders a fake visual selection marker on an expanded selection.
+        editor.conversion.for('editingDowncast').markerToHighlight({
+            model: VISUAL_SELECTION_MARKER_NAME,
+            view: {
+                classes: ['ck-fake-emoji-selection']
+            }
+        });
+        // Renders a fake visual selection marker on a collapsed selection.
+        editor.conversion.for('editingDowncast').markerToElement({
+            model: VISUAL_SELECTION_MARKER_NAME,
+            view: (data, { writer }) => {
+                if (!data.markerRange.isCollapsed) {
+                    return null;
+                }
+                const markerElement = writer.createUIElement('span');
+                writer.addClass(['ck-fake-emoji-selection', 'ck-fake-emoji-selection_collapsed'], markerElement);
+                return markerElement;
+            }
+        });
+    }
+    /**
+     * Returns positioning options for the {@link #_balloonPlugin}. They control the way the balloon is attached
+     * to the target element or selection.
+     */
+    _getBalloonPositionData() {
+        const view = this.editor.editing.view;
+        const viewDocument = view.document;
+        // Set a target position by converting view selection range to DOM.
+        const target = () => view.domConverter.viewRangeToDom(viewDocument.selection.getFirstRange());
+        return {
+            target
+        };
+    }
+    /**
+     * Displays a fake visual selection when the contextual balloon is displayed.
+     *
+     * This adds an 'emoji-picker' marker into the document that is rendered as a highlight on selected text fragment.
+     */
+    _showFakeVisualSelection() {
+        const model = this.editor.model;
+        model.change(writer => {
+            const range = model.document.selection.getFirstRange();
+            if (model.markers.has(VISUAL_SELECTION_MARKER_NAME)) {
+                writer.updateMarker(VISUAL_SELECTION_MARKER_NAME, { range });
+            }
+            else {
+                if (range.start.isAtEnd) {
+                    const startPosition = range.start.getLastMatchingPosition(({ item }) => !model.schema.isContent(item), { boundaries: range });
+                    writer.addMarker(VISUAL_SELECTION_MARKER_NAME, {
+                        usingOperation: false,
+                        affectsData: false,
+                        range: writer.createRange(startPosition, range.end)
+                    });
+                }
+                else {
+                    writer.addMarker(VISUAL_SELECTION_MARKER_NAME, {
+                        usingOperation: false,
+                        affectsData: false,
+                        range
+                    });
+                }
+            }
+        });
+    }
+    /**
+     * Hides the fake visual selection.
+     */
+    _hideFakeVisualSelection() {
+        const model = this.editor.model;
+        if (model.markers.has(VISUAL_SELECTION_MARKER_NAME)) {
+            model.change(writer => {
+                writer.removeMarker(VISUAL_SELECTION_MARKER_NAME);
+            });
+        }
+    }
+}

package/src/emojirepository.d.ts

@@ -0,0 +1,139 @@
+/**
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+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.
+ */
+export default class EmojiRepository extends Plugin {
+    /**
+     * Emoji database.
+     */
+    private _database;
+    /**
+     * A promise resolved after downloading the emoji database.
+     * The promise resolves with `true` when the database is successfully downloaded or `false` otherwise.
+     */
+    private _databasePromise;
+    /**
+     * A callback to resolve the {@link #_databasePromise} to control the return value of this promise.
+     */
+    private _databasePromiseResolveCallback;
+    /**
+     * An instance of the [Fuse.js](https://www.fusejs.io/) library.
+     */
+    private _fuseSearch;
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "EmojiRepository";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    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,
+     * hence this method returns an empty array.
+     *
+     * @param searchQuery A search query to match emoji.
+     * @returns An array of emoji entries that match the search query.
+     */
+    getEmojiByQuery(searchQuery: string): Array<EmojiEntry>;
+    /**
+     * Groups all emojis by categories.
+     * If the emoji database is not loaded, it returns an empty array.
+     *
+     * @returns An array of emoji entries grouped by categories.
+     */
+    getEmojiCategories(): Array<EmojiCategory>;
+    /**
+     * Returns an array of available skin tones.
+     */
+    getSkinTones(): Array<SkinTone>;
+    /**
+     * Indicates whether the emoji database has been successfully downloaded and the plugin is operational.
+     */
+    isReady(): Promise<boolean>;
+    /**
+     * A function used to check if the given emoji is supported in the operating system.
+     *
+     * Referenced for unit testing purposes.
+     */
+    private static _isEmojiSupported;
+}
+/**
+ * Represents a single group of the emoji category, e.g., "Smileys & Expressions".
+ */
+export type EmojiCategory = {
+    /**
+     * A name of the category.
+     */
+    title: string;
+    /**
+     * An example emoji representing items belonging to the category.
+     */
+    icon: string;
+    /**
+     * Group id used to assign {@link #items}.
+     */
+    groupId: number;
+    /**
+     * An array of emojis.
+     */
+    items: Array<EmojiEntry>;
+};
+/**
+ * Represents a single item fetched from the CDN.
+ */
+export type EmojiCdnResource = {
+    annotation: string;
+    emoji: string;
+    group: number;
+    order: number;
+    version: number;
+    emoticon?: string;
+    shortcodes?: Array<string>;
+    skins?: Array<{
+        emoji: string;
+        tone: number;
+        version: number;
+    }>;
+    tags?: Array<string>;
+};
+/**
+ * Represents a single emoji item used by the emoji feature.
+ */
+export type EmojiEntry = Omit<EmojiCdnResource, 'skins'> & {
+    skins: EmojiMap;
+};
+/**
+ * Represents mapping between a skin tone and its corresponding emoji.
+ *
+ * The `default` key is always present. Additional values are assigned only if an emoji supports skin tones.
+ */
+export type EmojiMap = {
+    [K in Exclude<SkinToneId, 'default'>]?: string;
+} & {
+    default: string;
+};
+/**
+ * Represents an emoji skin tone variant.
+ */
+export type SkinTone = {
+    id: SkinToneId;
+    icon: string;
+    tooltip: string;
+};

package/src/emojirepository.js

@@ -0,0 +1,267 @@
+/**
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+ */
+/**
+ * @module emoji/emojirepository
+ */
+import Fuse from 'fuse.js';
+import { groupBy } from 'lodash-es';
+import { Plugin } from 'ckeditor5/src/core.js';
+import { logWarning } from 'ckeditor5/src/utils.js';
+// An endpoint from which the emoji database 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 SKIN_TONE_MAP = {
+    0: 'default',
+    1: 'light',
+    2: 'medium-light',
+    3: 'medium',
+    4: 'medium-dark',
+    5: 'dark'
+};
+const BASELINE_EMOJI_WIDTH = 24;
+/**
+ * The emoji repository plugin.
+ *
+ * Loads the emoji database from URL during plugin initialization and provides utility methods to search it.
+ */
+class EmojiRepository extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'EmojiRepository';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    constructor(editor) {
+        super(editor);
+        this.editor.config.define('emoji', {
+            version: 16,
+            skinTone: 'default'
+        });
+        this._database = [];
+        this._databasePromise = new Promise(resolve => {
+            this._databasePromiseResolveCallback = resolve;
+        });
+        this._fuseSearch = null;
+    }
+    /**
+     * @inheritDoc
+     */
+    async init() {
+        const emojiVersion = this.editor.config.get('emoji.version');
+        const emojiDatabaseUrl = EMOJI_DATABASE_URL.replace('{version}', `${emojiVersion}`);
+        const emojiDatabase = await loadEmojiDatabase(emojiDatabaseUrl);
+        // 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);
+        }
+        const container = createEmojiWidthTestingContainer();
+        // Store the emoji database after normalizing the raw data.
+        this._database = emojiDatabase
+            .filter(item => isEmojiCategoryAllowed(item))
+            .filter(item => EmojiRepository._isEmojiSupported(item, container))
+            .map(item => 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, {
+            keys: [
+                { name: 'emoticon', weight: 5 },
+                { name: 'annotation', weight: 3 },
+                { name: 'tags', weight: 1 }
+            ],
+            minMatchCharLength: 2,
+            threshold: 0,
+            ignoreLocation: true
+        });
+        return this._databasePromiseResolveCallback(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,
+     * hence this method returns an empty array.
+     *
+     * @param searchQuery A search query to match emoji.
+     * @returns An array of emoji entries that match the search query.
+     */
+    getEmojiByQuery(searchQuery) {
+        if (!this._fuseSearch) {
+            return [];
+        }
+        const searchQueryTokens = searchQuery.split(/\s/).filter(Boolean);
+        // Perform the search only if there is at least two non-white characters next to each other.
+        const shouldSearch = searchQueryTokens.some(token => token.length >= 2);
+        if (!shouldSearch) {
+            return [];
+        }
+        return this._fuseSearch
+            .search({
+            '$or': [
+                {
+                    emoticon: searchQuery
+                },
+                {
+                    '$and': searchQueryTokens.map(token => ({ annotation: token }))
+                },
+                {
+                    '$and': searchQueryTokens.map(token => ({ tags: token }))
+                }
+            ]
+        })
+            .map(result => result.item);
+    }
+    /**
+     * Groups all emojis by categories.
+     * If the emoji database is not loaded, it returns an empty array.
+     *
+     * @returns An array of emoji entries grouped by categories.
+     */
+    getEmojiCategories() {
+        if (!this._database.length) {
+            return [];
+        }
+        const { t } = this.editor.locale;
+        const categories = [
+            { title: t('Smileys & Expressions'), icon: '😀', groupId: 0 },
+            { title: t('Gestures & People'), icon: '👋', groupId: 1 },
+            { title: t('Animals & Nature'), icon: '🐻', groupId: 3 },
+            { title: t('Food & Drinks'), icon: '🍎', groupId: 4 },
+            { title: t('Travel & Places'), icon: '🚘', groupId: 5 },
+            { title: t('Activities'), icon: '🏀', groupId: 6 },
+            { title: t('Objects'), icon: '💡', groupId: 7 },
+            { title: t('Symbols'), icon: '🟢', groupId: 8 },
+            { title: t('Flags'), icon: '🏁', groupId: 9 }
+        ];
+        const groups = groupBy(this._database, 'group');
+        return categories.map(category => {
+            return {
+                ...category,
+                items: groups[category.groupId]
+            };
+        });
+    }
+    /**
+     * Returns an array of available skin tones.
+     */
+    getSkinTones() {
+        const { t } = this.editor.locale;
+        return [
+            { id: 'default', icon: '👋', tooltip: t('Default skin tone') },
+            { id: 'light', icon: '👋🏻', tooltip: t('Light skin tone') },
+            { id: 'medium-light', icon: '👋🏼', tooltip: t('Medium Light skin tone') },
+            { id: 'medium', icon: '👋🏽', tooltip: t('Medium skin tone') },
+            { id: 'medium-dark', icon: '👋🏾', tooltip: t('Medium Dark skin tone') },
+            { id: 'dark', icon: '👋🏿', tooltip: t('Dark skin tone') }
+        ];
+    }
+    /**
+     * Indicates whether the emoji database has been successfully downloaded and the plugin is operational.
+     */
+    isReady() {
+        return this._databasePromise;
+    }
+}
+/**
+ * A function used to check if the given emoji is supported in the operating system.
+ *
+ * Referenced for unit testing purposes.
+ */
+EmojiRepository._isEmojiSupported = isEmojiSupported;
+export default EmojiRepository;
+/**
+ * Makes the HTTP request to download the emoji database.
+ */
+async function loadEmojiDatabase(emojiDatabaseUrl) {
+    const result = await fetch(emojiDatabaseUrl)
+        .then(response => {
+        if (!response.ok) {
+            return [];
+        }
+        return response.json();
+    })
+        .catch(() => {
+        return [];
+    });
+    if (!result.length) {
+        /**
+         * Unable to load the emoji database from CDN.
+         *
+         * TODO: It could be a problem of CKEditor 5 CDN, but also, Content Security Policy that disallow the request.
+         * It would be good to explain what to do in such a case.
+         *
+         * @error emoji-database-load-failed
+         */
+        logWarning('emoji-database-load-failed');
+    }
+    return result;
+}
+/**
+ * Creates a div for emoji width testing purposes.
+ */
+function createEmojiWidthTestingContainer() {
+    const container = document.createElement('div');
+    container.setAttribute('aria-hidden', 'true');
+    container.style.position = 'absolute';
+    container.style.left = '-9999px';
+    container.style.whiteSpace = 'nowrap';
+    container.style.fontSize = BASELINE_EMOJI_WIDTH + 'px';
+    document.body.appendChild(container);
+    return container;
+}
+/**
+ * Returns the width of the provided node.
+ */
+function getNodeWidth(container, node) {
+    const span = document.createElement('span');
+    span.textContent = node;
+    container.appendChild(span);
+    const nodeWidth = span.offsetWidth;
+    container.removeChild(span);
+    return nodeWidth;
+}
+/**
+ * Checks whether the emoji is supported in the operating system.
+ */
+function isEmojiSupported(item, container) {
+    const emojiWidth = getNodeWidth(container, item.emoji);
+    // On Windows, some supported emoji are ~50% bigger than the baseline emoji, but what we really want to guard
+    // against are the ones that are 2x the size, because those are truly broken (person with red hair = person with
+    // floating red wig, black cat = cat with black square, polar bear = bear with snowflake, etc.)
+    // So here we set the threshold at 1.8 times the size of the baseline emoji.
+    return (emojiWidth / 1.8 < BASELINE_EMOJI_WIDTH) && (emojiWidth >= BASELINE_EMOJI_WIDTH);
+}
+/**
+ * Adds default skin tone property to each emoji. If emoji defines other skin tones, they are added as well.
+ */
+function normalizeEmojiSkinTone(item) {
+    const entry = {
+        ...item,
+        skins: {
+            default: item.emoji
+        }
+    };
+    if (item.skins) {
+        item.skins.forEach(skin => {
+            const skinTone = SKIN_TONE_MAP[skin.tone];
+            entry.skins[skinTone] = skin.emoji;
+        });
+    }
+    return entry;
+}
+/**
+ * Checks whether the emoji belongs to a group that is allowed.
+ */
+function isEmojiCategoryAllowed(item) {
+    // Category group=2 contains skin tones only, which we do not want to render.
+    return item.group !== 2;
+}

package/src/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+ */
+/**
+ * @module emoji
+ */
+export { default as Emoji } from './emoji.js';
+export { default as EmojiMention } from './emojimention.js';
+export { default as EmojiPicker } from './emojipicker.js';
+export { default as EmojiRepository } from './emojirepository.js';
+export { default as EmojiCommand } from './emojicommand.js';
+export type { EmojiConfig } from './emojiconfig.js';
+import './augmentation.js';

package/src/index.js

@@ -0,0 +1,13 @@
+/**
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+ */
+/**
+ * @module emoji
+ */
+export { default as Emoji } from './emoji.js';
+export { default as EmojiMention } from './emojimention.js';
+export { default as EmojiPicker } from './emojipicker.js';
+export { default as EmojiRepository } from './emojirepository.js';
+export { default as EmojiCommand } from './emojicommand.js';
+import './augmentation.js';