@ckeditor/ckeditor5-emoji 0.0.0-nightly-20250129.0

package/src/ui/emojigridview.js

@@ -0,0 +1,183 @@
+/**
+ * @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 { addKeyboardHandlingForGrid, ButtonView, View } from 'ckeditor5/src/ui.js';
+import { FocusTracker, global, KeystrokeHandler } from 'ckeditor5/src/utils.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 {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale, { categoryName, emojiCategories, getEmojiByQuery, skinTone }) {
+        super(locale);
+        this.set('isEmpty', true);
+        this.set('categoryName', categoryName);
+        this.set('skinTone', skinTone);
+        this.tiles = this.createCollection();
+        this.cachedTiles = this.createCollection();
+        this.focusTracker = new FocusTracker();
+        this.keystrokes = new KeystrokeHandler();
+        this._getEmojiByQuery = getEmojiByQuery;
+        this.emojiCategories = emojiCategories;
+        const bind = this.bindTemplate;
+        this.setTemplate({
+            tag: 'div',
+            children: [
+                {
+                    tag: 'div',
+                    attributes: {
+                        role: 'grid',
+                        class: [
+                            'ck',
+                            'ck-emoji__grid'
+                        ]
+                    },
+                    children: this.tiles
+                }
+            ],
+            attributes: {
+                role: 'tabpanel',
+                class: [
+                    'ck',
+                    'ck-emoji__tiles',
+                    // To avoid issues with focus cycling, ignore a grid when it's empty.
+                    bind.if('isEmpty', 'ck-hidden', value => value)
+                ]
+            }
+        });
+        addKeyboardHandlingForGrid({
+            keystrokeHandler: this.keystrokes,
+            focusTracker: this.focusTracker,
+            gridItems: this.tiles,
+            numberOfColumns: () => global.window
+                .getComputedStyle(this.element.firstChild) // Responsive `.ck-emoji-grid__tiles`.
+                .getPropertyValue('grid-template-columns')
+                .split(' ')
+                .length,
+            uiLanguageDirection: this.locale && this.locale.uiLanguageDirection
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.keystrokes.destroy();
+        this.focusTracker.destroy();
+    }
+    /**
+     * Focuses the first focusable in {@link ~EmojiGridView#tiles} if available.
+     */
+    focus() {
+        const firstTile = this.tiles.first;
+        if (firstTile) {
+            firstTile.focus();
+        }
+    }
+    /**
+     * 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) {
+        const { matchingItems, allItems } = pattern ? this._getItemsByQuery(pattern.source) : this._getItemsByCategory();
+        this._updateGrid(matchingItems);
+        this.set('isEmpty', matchingItems.length === 0);
+        return {
+            resultsCount: matchingItems.length,
+            totalItemsCount: allItems.length
+        };
+    }
+    /**
+     * Filters emojis to show based on the specified query phrase.
+     *
+     * @param query A query used to filter the grid.
+     */
+    _getItemsByQuery(query) {
+        return {
+            matchingItems: this._getEmojiByQuery(query),
+            allItems: this.emojiCategories.flatMap(group => group.items)
+        };
+    }
+    /**
+     * Returns emojis that belong to the specified category.
+     */
+    _getItemsByCategory() {
+        const emojiCategory = this.emojiCategories.find(item => item.title === this.categoryName);
+        const { items } = emojiCategory;
+        return {
+            matchingItems: items,
+            allItems: items
+        };
+    }
+    /**
+     * Updates the grid by removing the existing items and insert the new ones.
+     *
+     * @param items An array of items to insert.
+     */
+    _updateGrid(items) {
+        // Clean-up.
+        [...this.tiles].forEach(item => {
+            this.focusTracker.remove(item);
+            this.tiles.remove(item);
+        });
+        items
+            // Create tiles from matching results.
+            .map(item => {
+            const emoji = item.skins[this.skinTone] || item.skins.default;
+            return this.cachedTiles.get(emoji) || this._createTile(emoji, item.annotation);
+        })
+            // Insert new elements.
+            .forEach(item => {
+            this.tiles.add(item);
+            this.focusTracker.add(item);
+        });
+    }
+    /**
+     * 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").
+     */
+    _createTile(emoji, name) {
+        const tile = new ButtonView(this.locale);
+        tile.viewUid = emoji;
+        tile.extendTemplate({
+            attributes: {
+                class: [
+                    'ck-emoji__tile'
+                ]
+            }
+        });
+        tile.set({
+            label: emoji,
+            tooltip: name,
+            withText: true,
+            ariaLabel: name,
+            // 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
+        });
+        tile.on('execute', () => {
+            this.fire('execute', { name, emoji });
+        });
+        this.cachedTiles.add(tile);
+        return tile;
+    }
+}

package/src/ui/emojipickerview.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @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/emojipickerview
+ */
+import { FocusCycler, SearchInfoView, View, type FocusableView, type ViewCollection } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import EmojiGridView, { type EmojiSearchQueryCallback } from './emojigridview.js';
+import EmojiCategoriesView from './emojicategoriesview.js';
+import EmojiSearchView from './emojisearchview.js';
+import EmojiToneView from './emojitoneview.js';
+import type { SkinToneId } from '../emojiconfig.js';
+import type { EmojiCategory, SkinTone } from '../emojirepository.js';
+/**
+ * A view that glues pieces of the emoji panel together.
+ */
+export default class EmojiPickerView extends View<HTMLDivElement> {
+    /**
+     * A collection of the focusable children of the view.
+     */
+    readonly items: ViewCollection<FocusableView>;
+    /**
+     * Tracks information about the DOM focus in the view.
+     */
+    readonly focusTracker: FocusTracker;
+    /**
+     * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}.
+     */
+    readonly keystrokes: KeystrokeHandler;
+    /**
+     * Helps cycling over focusable {@link #items} in the view.
+     */
+    readonly focusCycler: FocusCycler;
+    /**
+     * An instance of the `EmojiSearchView`.
+     */
+    readonly searchView: EmojiSearchView;
+    /**
+     * An instance of the `EmojiToneView`.
+     */
+    readonly toneView: EmojiToneView;
+    /**
+     * An instance of the `EmojiCategoriesView`.
+     */
+    readonly categoriesView: EmojiCategoriesView;
+    /**
+     * An instance of the `EmojiGridView`.
+     */
+    readonly gridView: EmojiGridView;
+    /**
+     * An instance of the `EmojiGridView`.
+     */
+    readonly infoView: SearchInfoView;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, { emojiCategories, getEmojiByQuery, skinTone, skinTones }: {
+        emojiCategories: Array<EmojiCategory>;
+        getEmojiByQuery: EmojiSearchQueryCallback;
+        skinTone: SkinToneId;
+        skinTones: Array<SkinTone>;
+    });
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the search input.
+     */
+    focus(): void;
+    /**
+     * Initializes interactions between sub-views.
+     */
+    private _setupEventListeners;
+}
+/**
+ * Fired when the  {@link module:emoji/ui/emojipickerview~EmojiPickerView} layout is changed, either by filtering emoji tiles or
+ * showing a hint to a user regarding the provided query.
+ *
+ * @eventName ~EmojiPickerView#update
+ */
+export type EmojiPickerViewUpdateEvent = {
+    name: 'update';
+    args: [];
+};

package/src/ui/emojipickerview.js

@@ -0,0 +1,172 @@
+/**
+ * @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/emojipickerview
+ */
+import { FocusCycler, SearchInfoView, View } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler } from 'ckeditor5/src/utils.js';
+import EmojiGridView from './emojigridview.js';
+import EmojiCategoriesView from './emojicategoriesview.js';
+import EmojiSearchView from './emojisearchview.js';
+import EmojiToneView from './emojitoneview.js';
+/**
+ * A view that glues pieces of the emoji panel together.
+ */
+export default class EmojiPickerView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale, { emojiCategories, getEmojiByQuery, skinTone, skinTones }) {
+        super(locale);
+        const categoryName = emojiCategories[0].title;
+        this.gridView = new EmojiGridView(locale, {
+            categoryName,
+            emojiCategories,
+            getEmojiByQuery,
+            skinTone
+        });
+        this.infoView = new SearchInfoView();
+        this.searchView = new EmojiSearchView(locale, {
+            gridView: this.gridView,
+            resultsView: this.infoView
+        });
+        this.categoriesView = new EmojiCategoriesView(locale, {
+            emojiCategories,
+            categoryName
+        });
+        this.toneView = new EmojiToneView(locale, {
+            skinTone,
+            skinTones
+        });
+        this.items = this.createCollection([
+            this.searchView,
+            this.toneView,
+            this.categoriesView,
+            this.gridView,
+            this.infoView
+        ]);
+        this.focusTracker = new FocusTracker();
+        this.keystrokes = new KeystrokeHandler();
+        this.focusCycler = new FocusCycler({
+            focusables: this.items,
+            focusTracker: this.focusTracker,
+            keystrokeHandler: this.keystrokes,
+            actions: {
+                focusPrevious: 'shift + tab',
+                focusNext: 'tab'
+            }
+        });
+        this.setTemplate({
+            tag: 'div',
+            children: [
+                {
+                    tag: 'div',
+                    children: [
+                        this.searchView,
+                        this.toneView
+                    ],
+                    attributes: {
+                        class: ['ck', 'ck-emoji__search']
+                    }
+                },
+                this.categoriesView,
+                this.gridView,
+                {
+                    tag: 'div',
+                    children: [
+                        this.infoView
+                    ],
+                    attributes: {
+                        class: ['ck', 'ck-search__results']
+                    }
+                }
+            ],
+            attributes: {
+                tabindex: '-1',
+                class: ['ck', 'ck-emoji', 'ck-search']
+            }
+        });
+        this._setupEventListeners();
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.focusTracker.add(this.searchView.element);
+        this.focusTracker.add(this.toneView.element);
+        this.focusTracker.add(this.categoriesView.element);
+        this.focusTracker.add(this.gridView.element);
+        this.focusTracker.add(this.infoView.element);
+        // Start listening for the keystrokes coming from #element.
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.focusTracker.destroy();
+        this.keystrokes.destroy();
+    }
+    /**
+     * Focuses the search input.
+     */
+    focus() {
+        this.searchView.focus();
+    }
+    /**
+     * Initializes interactions between sub-views.
+     */
+    _setupEventListeners() {
+        const t = this.locale.t;
+        // Disable the category switcher when filtering by a query.
+        this.searchView.on('search', (evt, data) => {
+            if (data.query) {
+                this.categoriesView.disableCategories();
+            }
+            else {
+                this.categoriesView.enableCategories();
+            }
+        });
+        // Show a user-friendly message depending on the search query.
+        this.searchView.on('search', (evt, data) => {
+            if (data.query.length === 1) {
+                this.infoView.set({
+                    primaryText: t('Keep on typing to see the emoji.'),
+                    secondaryText: t('The query must contain at least two characters.'),
+                    isVisible: true
+                });
+            }
+            else if (!data.resultsCount) {
+                this.infoView.set({
+                    primaryText: t('No emojis were found matching "%0".', data.query),
+                    secondaryText: t('Please try a different phrase or check the spelling.'),
+                    isVisible: true
+                });
+            }
+            else {
+                this.infoView.set({
+                    isVisible: false
+                });
+            }
+        });
+        // Emit an update event to react to balloon dimensions changes.
+        this.searchView.on('search', () => {
+            this.fire('update');
+        });
+        // Update the grid of emojis when the selected category is changed.
+        this.categoriesView.on('change:categoryName', (ev, args, categoryName) => {
+            this.gridView.categoryName = categoryName;
+            this.searchView.search('');
+        });
+        // Update the grid of emojis when the selected skin tone is changed.
+        // In such a case, the displayed emoji should use an updated skin tone value.
+        this.toneView.on('change:skinTone', (evt, propertyName, newValue) => {
+            this.gridView.skinTone = newValue;
+            this.searchView.search(this.searchView.getInputValue());
+        });
+    }
+}

package/src/ui/emojisearchview.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @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 { SearchTextView, View, type SearchInfoView } from 'ckeditor5/src/ui.js';
+import type { Locale } from 'ckeditor5/src/utils.js';
+import type EmojiGridView from './emojigridview.js';
+/**
+ * A view responsible for providing an input element that allows filtering emoji by the provided query.
+ */
+export default class EmojiSearchView extends View {
+    /**
+     * The find in text input view that stores the searched string.
+     */
+    readonly inputView: SearchTextView;
+    /**
+     * An instance of the `EmojiGridView`.
+     */
+    readonly gridView: EmojiGridView;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, { gridView, resultsView }: {
+        gridView: EmojiGridView;
+        resultsView: SearchInfoView;
+    });
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Searches the {@link #gridView} for the given query.
+     *
+     * @param query The search query string.
+     */
+    search(query: string): void;
+    /**
+     * Allows defining the default value in the search text field.
+     *
+     * @param value The new value.
+     */
+    setInputValue(value: string): void;
+    /**
+     * Returns an input provided by a user in the search text field.
+     */
+    getInputValue(): string;
+    /**
+     * @inheritDoc
+     */
+    focus(): void;
+}

package/src/ui/emojisearchview.js

@@ -0,0 +1,89 @@
+/**
+ * @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/emojisearchview
+ */
+import { escapeRegExp } from 'lodash-es';
+import { createLabeledInputText, SearchTextView, View } from 'ckeditor5/src/ui.js';
+/**
+ * A view responsible for providing an input element that allows filtering emoji by the provided query.
+ */
+export default class EmojiSearchView extends View {
+    /**
+     * @inheritDoc
+     */
+    constructor(locale, { gridView, resultsView }) {
+        super(locale);
+        this.gridView = gridView;
+        const t = locale.t;
+        this.inputView = new SearchTextView(this.locale, {
+            queryView: {
+                label: t('Find an emoji (min. 2 characters)'),
+                creator: createLabeledInputText
+            },
+            filteredView: this.gridView,
+            infoView: {
+                instance: resultsView
+            }
+        });
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-search'
+                ],
+                tabindex: '-1'
+            },
+            children: [
+                this.inputView.queryView
+            ]
+        });
+        // Pass through the `search` event to handle it by a parent view.
+        this.inputView.delegate('search').to(this);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.inputView.destroy();
+    }
+    /**
+     * Searches the {@link #gridView} for the given query.
+     *
+     * @param query The search query string.
+     */
+    search(query) {
+        const regExp = query ? new RegExp(escapeRegExp(query), 'ig') : null;
+        const filteringResults = this.gridView.filter(regExp);
+        this.inputView.fire('search', { query, ...filteringResults });
+    }
+    /**
+     * Allows defining the default value in the search text field.
+     *
+     * @param value The new value.
+     */
+    setInputValue(value) {
+        if (!value) {
+            this.inputView.queryView.fieldView.reset();
+        }
+        else {
+            this.inputView.queryView.fieldView.value = value;
+        }
+    }
+    /**
+     * Returns an input provided by a user in the search text field.
+     */
+    getInputValue() {
+        return this.inputView.queryView.fieldView.element.value;
+    }
+    /**
+     * @inheritDoc
+     */
+    focus() {
+        this.inputView.focus();
+    }
+}

package/src/ui/emojitoneview.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @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/emojitoneview
+ */
+import { View, type DropdownView } from 'ckeditor5/src/ui.js';
+import { type Locale } from 'ckeditor5/src/utils.js';
+import type { SkinToneId } from '../emojiconfig.js';
+import type { SkinTone } from '../emojirepository.js';
+import '../../theme/emojitone.css';
+/**
+ * A view responsible for selecting a skin tone for an emoji.
+ */
+export default class EmojiToneView extends View {
+    /**
+     * Active skin tone.
+     *
+     * @observable
+     */
+    skinTone: SkinToneId;
+    /**
+     * A dropdown element for selecting an active skin tone.
+     */
+    readonly dropdownView: DropdownView;
+    /**
+     * An array of available skin tones.
+     */
+    private readonly _skinTones;
+    /**
+     * @inheritDoc
+     */
+    constructor(locale: Locale, { skinTone, skinTones }: {
+        skinTone: SkinToneId;
+        skinTones: Array<SkinTone>;
+    });
+    /**
+     * @inheritDoc
+     */
+    focus(): void;
+    /**
+     * Helper method for receiving an object describing the active skin tone.
+     */
+    private _getSkinTone;
+}