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

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

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: [];
+};