@ckeditor/ckeditor5-emoji 48.2.0 → 48.3.0-alpha.1

package/dist/emojipicker.d.ts

@@ -1,108 +1,108 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
+* @license Copyright (c) 2003-2026, 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 '@ckeditor/ckeditor5-ui';
-import { Plugin } from '@ckeditor/ckeditor5-core';
-import { Typing } from '@ckeditor/ckeditor5-typing';
-import { EmojiRepository } from './emojirepository.js';
-import { EmojiPickerView } from './ui/emojipickerview.js';
-import { EmojiPickerFormView } from './ui/emojipickerformview.js';
-import type { EmojiSkinToneId } from './emojiconfig.js';
-import '../theme/emojipicker.css';
+* @module emoji/emojipicker
+*/
+import { ContextualBalloon, Dialog } from "@ckeditor/ckeditor5-ui";
+import { Plugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { Typing } from "@ckeditor/ckeditor5-typing";
+import { EmojiRepository } from "./emojirepository.js";
+import { EmojiPickerView } from "./ui/emojipickerview.js";
+import { EmojiPickerFormView } from "./ui/emojipickerformview.js";
+import type { EmojiSkinToneId } from "./emojiconfig.js";
+import "../theme/emojipicker.css";
 /**
- * The emoji picker plugin.
- *
- * Introduces the `'emoji'` dropdown.
- */
+* The emoji picker plugin.
+*
+* Introduces the `'emoji'` dropdown.
+*/
 export declare class EmojiPicker extends Plugin {
-    /**
-     * The actions view displayed inside the balloon.
-     */
-    emojiPickerView: EmojiPickerView | undefined;
-    /**
-     * The form view displayed inside the balloon.
-     */
-    emojiPickerFormView: EmojiPickerFormView | undefined;
-    /**
-     * The contextual balloon plugin instance.
-     */
-    balloonPlugin: ContextualBalloon;
-    /**
-     * An instance of the {@link module:emoji/emojirepository~EmojiRepository} plugin.
-     */
-    emojiRepositoryPlugin: EmojiRepository;
-    /**
-     * @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(): EmojiSkinToneId;
-    /**
-     * 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;
-    /**
-     * Creates an instance of the `EmojiPickerFormView` class that represents a balloon with the emoji picker.
-     */
-    private _createEmojiPickerFormView;
-    /**
-     * Hides the balloon with the emoji picker.
-     *
-     * @param updateFocus Whether to focus the editor after closing 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;
+	/**
+	* The actions view displayed inside the balloon.
+	*/
+	emojiPickerView: EmojiPickerView | undefined;
+	/**
+	* The form view displayed inside the balloon.
+	*/
+	emojiPickerFormView: EmojiPickerFormView | undefined;
+	/**
+	* The contextual balloon plugin instance.
+	*/
+	balloonPlugin: ContextualBalloon;
+	/**
+	* An instance of the {@link module:emoji/emojirepository~EmojiRepository} plugin.
+	*/
+	emojiRepositoryPlugin: EmojiRepository;
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[EmojiRepository, ContextualBalloon, Dialog, Typing]>;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "EmojiPicker";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	init(): void;
+	/**
+	* @inheritDoc
+	*/
+	override 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(): EmojiSkinToneId;
+	/**
+	* 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;
+	/**
+	* Creates an instance of the `EmojiPickerFormView` class that represents a balloon with the emoji picker.
+	*/
+	private _createEmojiPickerFormView;
+	/**
+	* Hides the balloon with the emoji picker.
+	*
+	* @param updateFocus Whether to focus the editor after closing the emoji picker.
+	*/
+	private _hideUI;
+	/**
+	* Registers converters.
+	*/
+	private _setupConversion;
+	/**
+	* Returns positioning options for the balloon plugin. 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/dist/emojirepository.d.ts

@@ -1,177 +1,172 @@
 /**
- * @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
- */
-import { type Editor, Plugin } from '@ckeditor/ckeditor5-core';
-import { EmojiUtils } from './emojiutils.js';
-import type { EmojiSkinToneId } from './emojiconfig.js';
+* @license Copyright (c) 2003-2026, CKSource Holding sp. z o.o. All rights reserved.
+* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
+*/
+import { type Editor, Plugin, type PluginDependenciesOf } from "@ckeditor/ckeditor5-core";
+import { EmojiUtils } from "./emojiutils.js";
+import type { EmojiSkinToneId } from "./emojiconfig.js";
 /**
- * The emoji repository plugin.
- *
- * Loads the emoji repository from URL during plugin initialization and provides utility methods to search it.
- */
+* The emoji repository plugin.
+*
+* Loads the emoji repository from URL during plugin initialization and provides utility methods to search it.
+*/
 export declare class EmojiRepository extends Plugin {
-    /**
-     * A callback to resolve the {@link #_repositoryPromise} to control the return value of this promise.
-     */
-    private _repositoryPromiseResolveCallback;
-    /**
-     * Emoji repository in a configured version.
-     */
-    private _items;
-    /**
-     * The resolved URL from which the emoji repository is downloaded.
-     */
-    private readonly _url;
-    /**
-     * A promise resolved after downloading the emoji collection.
-     * The promise resolves with `true` when the repository is successfully downloaded or `false` otherwise.
-     */
-    private readonly _repositoryPromise;
-    /**
-     * @inheritDoc
-     */
-    static get requires(): readonly [typeof EmojiUtils];
-    /**
-     * @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 repository is not loaded 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 repository 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<EmojiSkinTone>;
-    /**
-     * Indicates whether the emoji repository has been successfully downloaded and the plugin is operational.
-     */
-    isReady(): Promise<boolean>;
-    /**
-     * Returns the URL from which the emoji repository is downloaded. If the URL is not provided
-     * in the configuration, the default URL is used with the version from the configuration.
-     *
-     * If both the URL and version are provided, a warning is logged.
-     */
-    private _getUrl;
-    /**
-     * Warn users on self-hosted installations that this plugin uses a CDN to fetch the emoji repository.
-     */
-    private _warnAboutCdnUse;
-    /**
-     * Returns the emoji repository in a configured version if it is a non-empty array. Returns `null` otherwise.
-     */
-    private _getItems;
-    /**
-     * Loads the emoji repository. If the repository is already loaded, it returns the cached result.
-     * Otherwise, it fetches the repository from the URL and adds it to the cache.
-     */
-    private _loadAndCacheEmoji;
-    /**
-     * Normalizes the raw data fetched from CDN. By normalization, we meant:
-     *
-     *  * Filter out unsupported emoji (these that will not render correctly),
-     *  * Prepare skin tone variants if an emoji defines them.
-     */
-    private _normalizeEmoji;
-    /**
-     * Versioned emoji repository.
-     */
-    private static _results;
+	/**
+	* Whether the emoji repository has been successfully loaded.
+	*
+	* - `null` – the repository is still being loaded (initial state).
+	* - `true` – the repository has been loaded successfully.
+	* - `false` – the repository failed to load (e.g. network error or empty response).
+	*/
+	isRepositoryReady: boolean | null;
+	/**
+	* The resolved URL from which the emoji repository is downloaded.
+	*/
+	private readonly _url;
+	/**
+	* @inheritDoc
+	*/
+	static get requires(): PluginDependenciesOf<[EmojiUtils]>;
+	/**
+	* @inheritDoc
+	*/
+	static get pluginName(): "EmojiRepository";
+	/**
+	* @inheritDoc
+	*/
+	static override get isOfficialPlugin(): true;
+	/**
+	* @inheritDoc
+	*/
+	constructor(editor: Editor);
+	/**
+	* @inheritDoc
+	*/
+	init(): void;
+	/**
+	* Calls `callback` once the repository finishes loading, passing the result as the argument.
+	*
+	* @param callback Receives `true` when the repository loaded successfully, `false` on failure.
+	* Note: if the editor is destroyed before loading completes, the callback may never be called.
+	* Use {@link #isReady} instead if you need a guaranteed resolution in all cases.
+	*/
+	onReady(callback: (isReady: boolean) => void): void;
+	/**
+	* Returns an array of emoji entries that match the search query.
+	* If the emoji repository is not loaded 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 repository 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<EmojiSkinTone>;
+	/**
+	* Returns a promise that resolves once the repository finishes loading.
+	*
+	* Resolves with `true` if the repository loaded successfully, or `false` if loading failed.
+	* Rejects if the editor was destroyed before loading completed.
+	*/
+	isReady(): Promise<boolean>;
+	/**
+	* Returns the URL from which the emoji repository is downloaded. If the URL is not provided
+	* in the configuration, the default URL is used with the version from the configuration.
+	*
+	* If both the URL and version are provided, a warning is logged.
+	*/
+	private _getUrl;
+	/**
+	* Warn users on self-hosted installations that this plugin uses a CDN to fetch the emoji repository.
+	*/
+	private _warnAboutCdnUse;
+	/**
+	* Returns the normalised emoji repository for this editor instance if it is
+	* a non-empty array, or `null` otherwise.
+	*/
+	private _getItems;
+	/**
+	* Normalizes the raw data fetched from CDN. By normalization, we meant:
+	*
+	*  * Filter out unsupported emoji (these that will not render correctly),
+	*  * Prepare skin tone variants if an emoji defines them.
+	*/
+	private _normalizeEmoji;
+	/**
+	* Cache key segments that distinguish the transformation result for this editor instance.
+	*/
+	private get _cacheKeys();
+	/**
+	* Process-global cache that stores fetched emojis.
+	*/
+	private static _cache;
 }
 /**
- * Represents a single group of the emoji category, e.g., "Smileys & Expressions".
- */
+* 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>;
+	/**
+	* 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.
- */
+* 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>;
+	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 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<EmojiSkinToneId, 'default'>]?: string;
-} & {
-    default: string;
+* 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<EmojiSkinToneId, "default">]?: string } & {
+	default: string;
 };
 /**
- * Represents an emoji skin tone variant.
- */
+* Represents an emoji skin tone variant.
+*/
 export type EmojiSkinTone = {
-    id: EmojiSkinToneId;
-    icon: string;
-    tooltip: string;
+	id: EmojiSkinToneId;
+	icon: string;
+	tooltip: string;
 };
-/**
- * Unable to load the emoji repository from the URL.
- *
- * If the URL works properly and there is no disruption of communication, please check your
- * {@glink getting-started/setup/csp Content Security Policy (CSP)} setting and make sure
- * the URL connection is allowed by the editor.
- *
- * @error emoji-repository-load-failed
- */