@ckeditor/ckeditor5-emoji 0.0.0-nightly-20250129.0

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';

package/src/ui/emojicategoriesview.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
+ */
+/**
+ * @module emoji/ui/emojicategoriesview
+ */
+import { ButtonView, View, FocusCycler, type ViewCollection } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import type { EmojiCategory } from '../emojirepository.js';
+import '../../theme/emojicategories.css';
+/**
+ * A class representing the navigation part of the emoji UI.
+ * It is responsible allowing the user to select a particular emoji category.
+ */
+export default class EmojiCategoriesView extends View {
+    /**
+     * Currently selected emoji category name.
+     */
+    categoryName: string;
+    /**
+     * Tracks information about the DOM focus in the grid.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * Helps cycling over focusable children in the input view.
+     */
+    readonly focusCycler: FocusCycler;
+    /**
+     * A collection of the categories buttons.
+     */
+    readonly buttonViews: ViewCollection<ButtonView>;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, { emojiCategories, categoryName }: {
+        emojiCategories: Array<EmojiCategory>;
+        categoryName: string;
+    });
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * @inheritDoc
+     */
+    focus(): void;
+    /**
+     * Marks all categories buttons as enabled (clickable).
+     */
+    enableCategories(): void;
+    /**
+     * Marks all categories buttons as disabled (non-clickable).
+     */
+    disableCategories(): void;
+    /**
+     * Creates a button representing a category item.
+     */
+    private _createCategoryButton;
+}

package/src/ui/emojicategoriesview.js

@@ -0,0 +1,131 @@
+/**
+ * @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/ui/emojicategoriesview
+ */
+import { ButtonView, View, FocusCycler } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler } from 'ckeditor5/src/utils.js';
+import '../../theme/emojicategories.css';
+/**
+ * A class representing the navigation part of the emoji UI.
+ * It is responsible allowing the user to select a particular emoji category.
+ */
+export default class EmojiCategoriesView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale, { emojiCategories, categoryName }) {
+        super(locale);
+        this.buttonViews = this.createCollection(emojiCategories.map(emojiCategory => this._createCategoryButton(emojiCategory)));
+        this.focusTracker = new FocusTracker();
+        this.keystrokes = new KeystrokeHandler();
+        this.focusCycler = new FocusCycler({
+            focusables: this.buttonViews,
+            focusTracker: this.focusTracker,
+            keystrokeHandler: this.keystrokes,
+            actions: {
+                focusPrevious: 'arrowleft',
+                focusNext: 'arrowright'
+            }
+        });
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: ['ck', 'ck-emoji__categories-list'],
+                role: 'tablist'
+            },
+            children: this.buttonViews
+        });
+        this.on('change:categoryName', (event, name, newValue, oldValue) => {
+            const oldCategoryButton = this.buttonViews.find(button => button.tooltip === oldValue);
+            if (oldCategoryButton) {
+                oldCategoryButton.isOn = false;
+            }
+            const newCategoryButton = this.buttonViews.find(button => button.tooltip === newValue);
+            newCategoryButton.isOn = true;
+        });
+        this.set('categoryName', categoryName);
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.buttonViews.forEach(buttonView => {
+            this.focusTracker.add(buttonView);
+        });
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+        this.buttonViews.destroy();
+    }
+    /**
+     * @inheritDoc
+     */
+    focus() {
+        this.buttonViews.first.focus();
+    }
+    /**
+     * Marks all categories buttons as enabled (clickable).
+     */
+    enableCategories() {
+        this.buttonViews.forEach(buttonView => {
+            buttonView.isEnabled = true;
+        });
+    }
+    /**
+     * Marks all categories buttons as disabled (non-clickable).
+     */
+    disableCategories() {
+        this.buttonViews.forEach(buttonView => {
+            buttonView.set({
+                class: '',
+                isEnabled: false,
+                isOn: false
+            });
+        });
+    }
+    /**
+     * Creates a button representing a category item.
+     */
+    _createCategoryButton(emojiCategory) {
+        const buttonView = new ButtonView();
+        const bind = buttonView.bindTemplate;
+        // A `[role="tab"]` element requires also the `[aria-selected]` attribute with its state.
+        buttonView.extendTemplate({
+            attributes: {
+                'aria-selected': bind.to('isOn', value => value.toString()),
+                class: [
+                    'ck-emoji__category-item'
+                ]
+            }
+        });
+        buttonView.set({
+            ariaLabel: emojiCategory.title,
+            label: emojiCategory.icon,
+            role: 'tab',
+            tooltip: emojiCategory.title,
+            withText: true,
+            // To improve accessibility, disconnect a button and its label connection so that screen
+            // readers can read the `[aria-label]` attribute directly from the more descriptive button.
+            ariaLabelledBy: undefined
+        });
+        buttonView.on('execute', () => {
+            this.categoryName = emojiCategory.title;
+        });
+        buttonView.on('change:isEnabled', () => {
+            if (buttonView.isEnabled && buttonView.tooltip === this.categoryName) {
+                buttonView.isOn = true;
+            }
+        });
+        return buttonView;
+    }
+}

package/src/ui/emojigridview.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @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/ui/emojigridview
+ */
+import { ButtonView, type FilteredView, View, type ViewCollection } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import type { EmojiCategory, EmojiEntry } from '../emojirepository.js';
+import type { SkinToneId } from '../emojiconfig.js';
+import '../../theme/emojigrid.css';
+/**
+ * A grid of emoji tiles. It allows browsing emojis and selecting them to be inserted into the content.
+ */
+export default class EmojiGridView extends View<HTMLDivElement> implements FilteredView {
+    /**
+     * Defines the active category name.
+     *
+     * @observable
+     */
+    categoryName: string;
+    /**
+     * Active skin tone.
+     *
+     * @observable
+     */
+    skinTone: SkinToneId;
+    /**
+     * Set to `true` when the {@link #tiles} collection does not contain items to display.
+     *
+     * @observable
+     */
+    isEmpty: boolean;
+    /**
+     * A collection of the child tile views. Each tile represents a particular emoji.
+     */
+    readonly tiles: ViewCollection<ButtonView>;
+    /**
+     * Tracks information about the DOM focus in the grid.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * An array containing all emojis grouped by their categories.
+     */
+    readonly emojiCategories: Array<EmojiCategory>;
+    /**
+     * A collection of all already created tile views. Each tile represents a particular emoji.
+     * The cached tiles collection is used for efficiency purposes to avoid re-creating a particular
+     * tile again when the grid view has changed.
+     */
+    readonly cachedTiles: ViewCollection<ButtonView>;
+    /**
+     * A callback used to filter grid items by a specified query.
+     */
+    private readonly _getEmojiByQuery;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, { categoryName, emojiCategories, getEmojiByQuery, skinTone }: {
+        categoryName: string;
+        emojiCategories: Array<EmojiCategory>;
+        getEmojiByQuery: EmojiSearchQueryCallback;
+        skinTone: SkinToneId;
+    });
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the first focusable in {@link ~EmojiGridView#tiles} if available.
+     */
+    focus(): void;
+    /**
+     * Filters the grid view by the given regular expression.
+     *
+     * It filters either by the pattern or an emoji category, but never both.
+     *
+     * @param pattern Expression to search or `null` when filter by category name.
+     */
+    filter(pattern: RegExp | null): {
+        resultsCount: number;
+        totalItemsCount: number;
+    };
+    /**
+     * Filters emojis to show based on the specified query phrase.
+     *
+     * @param query A query used to filter the grid.
+     */
+    private _getItemsByQuery;
+    /**
+     * Returns emojis that belong to the specified category.
+     */
+    private _getItemsByCategory;
+    /**
+     * Updates the grid by removing the existing items and insert the new ones.
+     *
+     * @param items An array of items to insert.
+     */
+    private _updateGrid;
+    /**
+     * Creates a new tile for the grid. Created tile is added to the {@link #cachedTiles} collection for further usage, if needed.
+     *
+     * @param emoji The emoji itself.
+     * @param name The name of the emoji (e.g. "Smiling Face with Smiling Eyes").
+     */
+    private _createTile;
+}
+/**
+ * A callback used to filter grid items by a specified query.
+ */
+export type EmojiSearchQueryCallback = (query: string) => Array<EmojiEntry>;
+/**
+ * Fired when any of {@link ~EmojiGridView#tiles grid tiles} is clicked.
+ *
+ * @eventName ~EmojiGridView#execute
+ * @param data Additional information about the event.
+ */
+export type EmojiGridViewExecuteEvent = {
+    name: 'execute';
+    args: [data: EmojiGridViewEventData];
+};
+export type EmojiGridViewEventData = {
+    /**
+     * The name of the emoji (e.g. "Smiling Face with Smiling Eyes").
+     */
+    name: string;
+    /**
+     * The emoji itself.
+     */
+    emoji: string;
+};