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

package/src/augmentation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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 type { Emoji, EmojiConfig, EmojiMention, EmojiPicker, EmojiRepository, EmojiCommand } from './index.js';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The configuration of the {@link module:emoji/emoji~Emoji} feature.
+         *
+         * Read more in {@link module:emoji/emojiconfig~EmojiConfig}.
+         */
+        emoji?: EmojiConfig;
+    }
+    interface PluginsMap {
+        [Emoji.pluginName]: Emoji;
+        [EmojiMention.pluginName]: EmojiMention;
+        [EmojiPicker.pluginName]: EmojiPicker;
+        [EmojiRepository.pluginName]: EmojiRepository;
+    }
+    interface CommandsMap {
+        emoji: EmojiCommand;
+    }
+}

package/src/augmentation.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/emoji.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @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/emoji
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import EmojiMention from './emojimention.js';
+import EmojiPicker from './emojipicker.js';
+/**
+ * The emoji plugin.
+ *
+ * This is a "glue" plugin which loads the following plugins:
+ *
+ * * {@link module:emoji/emojimention~EmojiMention},
+ * * {@link module:emoji/emojipicker~EmojiPicker},
+ */
+export default class Emoji extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof EmojiMention, typeof EmojiPicker];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "Emoji";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+}

package/src/emoji.js

@@ -0,0 +1,38 @@
+/**
+ * @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/emoji
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import EmojiMention from './emojimention.js';
+import EmojiPicker from './emojipicker.js';
+/**
+ * The emoji plugin.
+ *
+ * This is a "glue" plugin which loads the following plugins:
+ *
+ * * {@link module:emoji/emojimention~EmojiMention},
+ * * {@link module:emoji/emojipicker~EmojiPicker},
+ */
+export default class Emoji extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [EmojiMention, EmojiPicker];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'Emoji';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+}

package/src/emojicommand.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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/emojicommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * Command that shows the emoji user interface.
+ */
+export default class EmojiCommand extends Command {
+    /**
+     * Updates the command's {@link #isEnabled} based on the current selection.
+     */
+    refresh(): void;
+    /**
+     * Opens emoji user interface for the current document selection.
+     *
+     * @fires execute
+     * @param [searchValue=''] A default query used to filer the grid when opening the UI.
+     */
+    execute(searchValue?: string): void;
+}

package/src/emojicommand.js

@@ -0,0 +1,33 @@
+/**
+ * @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/emojicommand
+ */
+import { Command } from 'ckeditor5/src/core.js';
+/**
+ * Command that shows the emoji user interface.
+ */
+export default class EmojiCommand extends Command {
+    /**
+     * Updates the command's {@link #isEnabled} based on the current selection.
+     */
+    refresh() {
+        const editor = this.editor;
+        const model = editor.model;
+        const schema = model.schema;
+        const selection = model.document.selection;
+        this.isEnabled = schema.checkChild(selection.getFirstPosition(), '$text');
+    }
+    /**
+     * Opens emoji user interface for the current document selection.
+     *
+     * @fires execute
+     * @param [searchValue=''] A default query used to filer the grid when opening the UI.
+     */
+    execute(searchValue = '') {
+        const emojiPickerPlugin = this.editor.plugins.get('EmojiPicker');
+        emojiPickerPlugin.showUI(searchValue);
+    }
+}

package/src/emojiconfig.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @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/emojiconfig
+ */
+/**
+ * The configuration of the emoji feature.
+ *
+ * Read more about {@glink features/emoji#configuration configuring the emoji feature}.
+ *
+ * ```ts
+ *	ClassicEditor
+ *		.create( editorElement, {
+ *			emoji: ... // Emoji feature options.
+ *		} )
+ *		.then( ... )
+ *		.catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor configuration options}.
+ */
+export interface EmojiConfig {
+    /**
+     * The maximum number of emojis displayed in the dropdown list.
+     *
+     * ```ts
+     *	ClassicEditor
+     *		.create( editorElement, {
+     *			plugins: [ Emoji, ... ],
+     *			emoji: {
+     *				dropdownLimit: 4
+     *			}
+     *		} )
+     *		.then( ... )
+     *		.catch( ... );
+     * ```
+     *
+     * @default 6
+     */
+    dropdownLimit?: number;
+    /**
+     * Initial skin tone for the emojis that support skin tones.
+     *
+     * ```ts
+     *	ClassicEditor
+     *		.create( editorElement, {
+     *			plugins: [ Emoji, ... ],
+     *			emoji: {
+     *				skinTone: 'medium'
+     *			}
+     *		} )
+     *		.then( ... )
+     *		.catch( ... );
+     * ```
+     *
+     * @default 'default'
+     */
+    skinTone?: SkinToneId;
+    /**
+     * The emoji database version.
+     *
+     * ```ts
+     *	ClassicEditor
+     *		.create( editorElement, {
+     *			plugins: [ Emoji, ... ],
+     *			emoji: {
+     *				version: 15
+     *			}
+     *		} )
+     *		.then( ... )
+     *		.catch( ... );
+     * ```
+     *
+     * @default 16
+     */
+    version?: 15 | 16;
+}
+export type SkinToneId = 'default' | 'light' | 'medium-light' | 'medium' | 'medium-dark' | 'dark';

package/src/emojiconfig.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/emojimention.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @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 { Typing } from 'ckeditor5/src/typing.js';
+import EmojiRepository from './emojirepository.js';
+/**
+ * The emoji mention plugin.
+ *
+ * Introduces the autocomplete of emojis while typing.
+ */
+export default class EmojiMention extends Plugin {
+    /**
+     * An instance of the {@link module:emoji/emojipicker~EmojiPicker} plugin if it is loaded in the editor.
+     */
+    private _emojiPickerPlugin;
+    /**
+     * An instance of the {@link module:emoji/emojirepository~EmojiRepository} plugin.
+     */
+    private _emojiRepositoryPlugin;
+    /**
+     * Defines a number of displayed items in the auto complete dropdown.
+     *
+     * It includes the "Show all emoji..." option if the `EmojiPicker` plugin is loaded.
+     */
+    private readonly _emojiDropdownLimit;
+    /**
+     * Defines a skin tone that is set in the emoji config.
+     */
+    private readonly _skinTone;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof EmojiRepository, typeof Typing, "Mention"];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "EmojiMention";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): Promise<void>;
+    /**
+     * Initializes the configuration for emojis in the mention feature.
+     */
+    private _setupMentionConfiguration;
+    /**
+     * Returns the `itemRenderer()` callback for mention config.
+     */
+    private _customItemRendererFactory;
+    /**
+     * Overrides the default mention execute listener to insert an emoji as plain text instead.
+     */
+    private _overrideMentionExecuteListener;
+    /**
+     * Returns the `feed()` callback for mention config.
+     */
+    private _queryEmojiCallbackFactory;
+}

package/src/emojimention.js

@@ -0,0 +1,193 @@
+/**
+ * @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/emojimention
+ */
+import { logWarning } from 'ckeditor5/src/utils.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+import { Typing } from 'ckeditor5/src/typing.js';
+import EmojiRepository from './emojirepository.js';
+const EMOJI_MENTION_MARKER = ':';
+const EMOJI_SHOW_ALL_OPTION_ID = ':__EMOJI_SHOW_ALL:';
+const EMOJI_HINT_OPTION_ID = ':__EMOJI_HINT:';
+/**
+ * The emoji mention plugin.
+ *
+ * Introduces the autocomplete of emojis while typing.
+ */
+export default class EmojiMention extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [EmojiRepository, Typing, 'Mention'];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'EmojiMention';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    constructor(editor) {
+        super(editor);
+        this.editor.config.define('emoji', {
+            dropdownLimit: 6
+        });
+        this._emojiDropdownLimit = editor.config.get('emoji.dropdownLimit');
+        this._skinTone = editor.config.get('emoji.skinTone');
+        const mentionFeedsConfigs = editor.config.get('mention.feeds');
+        const mergeFieldsPrefix = editor.config.get('mergeFields.prefix');
+        const markerAlreadyUsed = mentionFeedsConfigs.some(config => config.marker === EMOJI_MENTION_MARKER);
+        const isMarkerUsedByMergeFields = mergeFieldsPrefix ? mergeFieldsPrefix[0] === EMOJI_MENTION_MARKER : false;
+        if (markerAlreadyUsed || isMarkerUsedByMergeFields) {
+            /**
+             * The `marker` in the `emoji` config is already used by other plugin configuration.
+             *
+             * @error emoji-config-marker-already-used
+             * @param {string} marker Used marker.
+             */
+            logWarning('emoji-config-marker-already-used', { marker: EMOJI_MENTION_MARKER });
+            return;
+        }
+        this._setupMentionConfiguration(mentionFeedsConfigs);
+    }
+    /**
+     * @inheritDoc
+     */
+    async init() {
+        const editor = this.editor;
+        this._emojiPickerPlugin = editor.plugins.has('EmojiPicker') ? editor.plugins.get('EmojiPicker') : null;
+        this._emojiRepositoryPlugin = editor.plugins.get('EmojiRepository');
+        // Skip overriding the `mention` command listener if the emoji repository is not ready.
+        if (!await this._emojiRepositoryPlugin.isReady()) {
+            return;
+        }
+        editor.once('ready', this._overrideMentionExecuteListener.bind(this));
+    }
+    /**
+     * Initializes the configuration for emojis in the mention feature.
+     */
+    _setupMentionConfiguration(mentionFeedsConfigs) {
+        const emojiMentionFeedConfig = {
+            marker: EMOJI_MENTION_MARKER,
+            dropdownLimit: this._emojiDropdownLimit,
+            itemRenderer: this._customItemRendererFactory(this.editor.t),
+            feed: this._queryEmojiCallbackFactory()
+        };
+        this.editor.config.set('mention.feeds', [...mentionFeedsConfigs, emojiMentionFeedConfig]);
+    }
+    /**
+     * Returns the `itemRenderer()` callback for mention config.
+     */
+    _customItemRendererFactory(t) {
+        return (item) => {
+            const itemElement = document.createElement('button');
+            itemElement.classList.add('ck');
+            itemElement.classList.add('ck-button');
+            itemElement.classList.add('ck-button_with-text');
+            itemElement.id = `mention-list-item-id${item.id.slice(0, -1)}`;
+            itemElement.type = 'button';
+            itemElement.tabIndex = -1;
+            const labelElement = document.createElement('span');
+            labelElement.classList.add('ck');
+            labelElement.classList.add('ck-button__label');
+            itemElement.appendChild(labelElement);
+            if (item.id === EMOJI_HINT_OPTION_ID) {
+                itemElement.classList.add('ck-list-item-button');
+                itemElement.classList.add('ck-disabled');
+                labelElement.textContent = t('Keep on typing to see the emoji.');
+            }
+            else if (item.id === EMOJI_SHOW_ALL_OPTION_ID) {
+                labelElement.textContent = t('Show all emoji...');
+            }
+            else {
+                labelElement.textContent = `${item.text} ${item.id}`;
+            }
+            return itemElement;
+        };
+    }
+    /**
+     * Overrides the default mention execute listener to insert an emoji as plain text instead.
+     */
+    _overrideMentionExecuteListener() {
+        const editor = this.editor;
+        editor.commands.get('mention').on('execute', (event, data) => {
+            const eventData = data[0];
+            // Ignore non-emoji auto-complete actions.
+            if (eventData.marker !== EMOJI_MENTION_MARKER) {
+                return;
+            }
+            // Do not propagate the event.
+            event.stop();
+            // Do nothing when executing after selecting a hint message.
+            if (eventData.mention.id === EMOJI_HINT_OPTION_ID) {
+                return;
+            }
+            // Trigger the picker UI.
+            if (eventData.mention.id === EMOJI_SHOW_ALL_OPTION_ID) {
+                const text = [...eventData.range.getItems()]
+                    .filter(item => item.is('$textProxy'))
+                    .map(item => item.data)
+                    .reduce((result, text) => result + text, '');
+                editor.model.change(writer => {
+                    editor.model.deleteContent(writer.createSelection(eventData.range));
+                });
+                const emojiPickerPlugin = this._emojiPickerPlugin;
+                emojiPickerPlugin.showUI(text.slice(1));
+                setTimeout(() => {
+                    emojiPickerPlugin.emojiPickerView.focus();
+                });
+            }
+            // Or insert the emoji to editor.
+            else {
+                editor.execute('insertText', {
+                    text: eventData.mention.text,
+                    range: eventData.range
+                });
+            }
+        }, { priority: 'high' });
+    }
+    /**
+     * Returns the `feed()` callback for mention config.
+     */
+    _queryEmojiCallbackFactory() {
+        return (searchQuery) => {
+            // Do not show anything when a query starts with a space.
+            if (searchQuery.startsWith(' ')) {
+                return [];
+            }
+            const emojis = this._emojiRepositoryPlugin.getEmojiByQuery(searchQuery)
+                .map(emoji => {
+                let text = emoji.skins[this._skinTone] || emoji.skins.default;
+                if (this._emojiPickerPlugin) {
+                    text = emoji.skins[this._emojiPickerPlugin.skinTone] || emoji.skins.default;
+                }
+                return {
+                    id: `:${emoji.annotation}:`,
+                    text
+                };
+            });
+            if (!this._emojiPickerPlugin) {
+                return emojis.slice(0, this._emojiDropdownLimit);
+            }
+            const actionItem = {
+                id: searchQuery.length > 1 ? EMOJI_SHOW_ALL_OPTION_ID : EMOJI_HINT_OPTION_ID
+            };
+            return [
+                ...emojis.slice(0, this._emojiDropdownLimit - 1),
+                actionItem
+            ];
+        };
+    }
+}

package/src/emojipicker.d.ts

@@ -0,0 +1,97 @@
+/**
+ * @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 { ContextualBalloon, Dialog } from 'ckeditor5/src/ui.js';
+import { Plugin } from 'ckeditor5/src/core.js';
+import { Typing } from 'ckeditor5/src/typing.js';
+import EmojiRepository from './emojirepository.js';
+import EmojiPickerView from './ui/emojipickerview.js';
+import type { SkinToneId } from './emojiconfig.js';
+import '../theme/emojipicker.css';
+/**
+ * The emoji picker plugin.
+ *
+ * Introduces the `'emoji'` dropdown.
+ */
+export default class EmojiPicker extends Plugin {
+    /**
+     * The actions view displayed inside the balloon.
+     */
+    emojiPickerView: EmojiPickerView | undefined;
+    /**
+     * The contextual balloon plugin instance.
+     */
+    _balloonPlugin: ContextualBalloon;
+    /**
+     * An instance of the {@link module:emoji/emojirepository~EmojiRepository} plugin.
+     */
+    private _emojiRepositoryPlugin;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof EmojiRepository, typeof ContextualBalloon, typeof Dialog, typeof Typing];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "EmojiPicker";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): Promise<void>;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * 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(): SkinToneId;
+    /**
+     * Displays the balloon with the emoji picker.
+     *
+     * @param [searchValue=''] A default query used to filer the grid when opening the UI.
+     */
+    showUI(searchValue?: string): void;
+    /**
+     * Creates a button for toolbar and menu bar that will show the emoji dialog.
+     */
+    private _createButton;
+    /**
+     * Creates an instance of the `EmojiPickerView` class that represents an emoji balloon.
+     */
+    private _createEmojiPickerView;
+    /**
+     * Hides the balloon with the emoji picker.
+     */
+    private _hideUI;
+    /**
+     * Registers converters.
+     */
+    private _setupConversion;
+    /**
+     * Returns positioning options for the {@link #_balloonPlugin}. They control the way the balloon is attached
+     * to the target element or selection.
+     */
+    private _getBalloonPositionData;
+    /**
+     * 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.
+     */
+    private _showFakeVisualSelection;
+    /**
+     * Hides the fake visual selection.
+     */
+    private _hideFakeVisualSelection;
+}