@ckeditor/ckeditor5-emoji 0.0.0-nightly-20250129.0

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;
+}

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;
+};