@ckeditor/ckeditor5-special-characters 41.1.0 → 41.3.0-alpha.0

package/dist/types/specialcharacters.d.ts

@@ -0,0 +1,96 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/specialcharacters
+ */
+import { Plugin, type Editor } from 'ckeditor5/src/core.js';
+import { Typing } from 'ckeditor5/src/typing.js';
+import '../theme/specialcharacters.css';
+/**
+ * The special characters feature.
+ *
+ * Introduces the `'specialCharacters'` dropdown.
+ */
+export default class SpecialCharacters extends Plugin {
+    /**
+     * Registered characters. A pair of a character name and its symbol.
+     */
+    private _characters;
+    /**
+     * Registered groups. Each group contains a displayed label and a collection with symbol names.
+     */
+    private _groups;
+    /**
+     * A label describing the "All" special characters category.
+     */
+    private _allSpecialCharactersGroupLabel;
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof Typing];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "SpecialCharacters";
+    /**
+     * @inheritDoc
+     */
+    constructor(editor: Editor);
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+    /**
+     * Adds a collection of special characters to the specified group. The title of a special character must be unique.
+     *
+     * **Note:** The "All" category name is reserved by the plugin and cannot be used as a new name for a special
+     * characters category.
+     */
+    addItems(groupName: string, items: Array<SpecialCharacterDefinition>, options?: {
+        label: string;
+    }): void;
+    /**
+     * Returns special character groups in an order determined based on configuration and registration sequence.
+     */
+    getGroups(): Set<string>;
+    /**
+     * Returns a collection of special characters symbol names (titles).
+     */
+    getCharactersForGroup(groupName: string): Set<string> | undefined;
+    /**
+     * Returns the symbol of a special character for the specified name. If the special character could not be found, `undefined`
+     * is returned.
+     *
+     * @param title The title of a special character.
+     */
+    getCharacter(title: string): string | undefined;
+    /**
+     * Returns a group of special characters. If the group with the specified name does not exist, it will be created.
+     *
+     * @param groupName The name of the group to create.
+     * @param label The label describing the new group.
+     */
+    private _getGroup;
+    /**
+     * Updates the symbol grid depending on the currently selected character group.
+     */
+    private _updateGrid;
+    /**
+     * Initializes the dropdown, used for lazy loading.
+     *
+     * @returns An object with `navigationView`, `gridView` and `infoView` properties, containing UI parts.
+     */
+    private _createDropdownPanelContent;
+}
+export interface SpecialCharacterDefinition {
+    /**
+     * A unique name of the character (e.g. "greek small letter epsilon").
+     */
+    title: string;
+    /**
+     * A human-readable character displayed as the label (e.g. "ε").
+     */
+    character: string;
+}

package/dist/types/specialcharactersarrows.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/specialcharactersarrows
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * A plugin that provides special characters for the "Arrows" category.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     plugins: [ ..., SpecialCharacters, SpecialCharactersArrows ],
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ */
+export default class SpecialCharactersArrows extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "SpecialCharactersArrows";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/specialcharactersconfig.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/specialcharactersconfig
+ */
+/**
+ * The configuration of the special characters feature.
+ *
+ * Read more about {@glink features/special-characters#configuration configuring the special characters feature}.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( editorElement, {
+ *     specialCharacters: ... // Special characters feature options.
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ *
+ * See {@link module:core/editor/editorconfig~EditorConfig all editor configuration options}.
+ */
+export interface SpecialCharactersConfig {
+    /**
+     * The configuration of the special characters category order.
+     *
+     * Special characters categories are displayed in the UI in the order in which they were registered. Using the `order` property
+     * allows to override this behaviour and enforce specific order. Categories not listed in the `order` property will be displayed
+     * in the default order below categories listed in the configuration.
+     *
+     * ```ts
+     * ClassicEditor
+     *   .create( editorElement, {
+     *     plugins: [ SpecialCharacters, SpecialCharactersEssentials, ... ],
+     *     specialCharacters: {
+     *       order: [
+     *         'Text',
+     *         'Latin',
+     *         'Mathematical',
+     *         'Currency',
+     *         'Arrows'
+     *       ]
+     *     }
+     *   } )
+     *   .then( ... )
+     *   .catch( ... );
+     * ```
+     */
+    order?: Array<string>;
+}

package/dist/types/specialcharacterscurrency.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/specialcharacterscurrency
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * A plugin that provides special characters for the "Currency" category.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     plugins: [ ..., SpecialCharacters, SpecialCharactersCurrency ],
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ */
+export default class SpecialCharactersCurrency extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "SpecialCharactersCurrency";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/specialcharactersessentials.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/specialcharactersessentials
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+import SpecialCharactersCurrency from './specialcharacterscurrency.js';
+import SpecialCharactersMathematical from './specialcharactersmathematical.js';
+import SpecialCharactersArrows from './specialcharactersarrows.js';
+import SpecialCharactersLatin from './specialcharacterslatin.js';
+import SpecialCharactersText from './specialcharacterstext.js';
+/**
+ * A plugin combining a basic set of characters for the special characters plugin.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     plugins: [ ..., SpecialCharacters, SpecialCharactersEssentials ],
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ */
+export default class SpecialCharactersEssentials extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "SpecialCharactersEssentials";
+    /**
+     * @inheritDoc
+     */
+    static get requires(): readonly [typeof SpecialCharactersCurrency, typeof SpecialCharactersText, typeof SpecialCharactersMathematical, typeof SpecialCharactersArrows, typeof SpecialCharactersLatin];
+}

package/dist/types/specialcharacterslatin.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/specialcharacterslatin
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * A plugin that provides special characters for the "Latin" category.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     plugins: [ ..., SpecialCharacters, SpecialCharactersLatin ],
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ */
+export default class SpecialCharactersLatin extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "SpecialCharactersLatin";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/specialcharactersmathematical.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/specialcharactersmathematical
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * A plugin that provides special characters for the "Mathematical" category.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     plugins: [ ..., SpecialCharacters, SpecialCharactersMathematical ],
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ */
+export default class SpecialCharactersMathematical extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "SpecialCharactersMathematical";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/specialcharacterstext.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/specialcharacterstext
+ */
+import { Plugin } from 'ckeditor5/src/core.js';
+/**
+ * A plugin that provides special characters for the "Text" category.
+ *
+ * ```ts
+ * ClassicEditor
+ *   .create( {
+ *     plugins: [ ..., SpecialCharacters, SpecialCharactersText ],
+ *   } )
+ *   .then( ... )
+ *   .catch( ... );
+ * ```
+ */
+export default class SpecialCharactersText extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "SpecialCharactersText";
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/dist/types/ui/charactergridview.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/ui/charactergridview
+ */
+import { View, ButtonView, type ViewCollection } from 'ckeditor5/src/ui.js';
+import { KeystrokeHandler, FocusTracker, type Locale } from 'ckeditor5/src/utils.js';
+import '../../theme/charactergrid.css';
+/**
+ * A grid of character tiles. It allows browsing special characters and selecting the character to
+ * be inserted into the content.
+ */
+export default class CharacterGridView extends View<HTMLDivElement> {
+    /**
+     * A collection of the child tile views. Each tile represents a particular character.
+     */
+    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;
+    /**
+     * Creates an instance of a character grid containing tiles representing special characters.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale: Locale);
+    /**
+     * Creates a new tile for the grid.
+     *
+     * @param character A human-readable character displayed as the label (e.g. "ε").
+     * @param name The name of the character (e.g. "greek small letter epsilon").
+     */
+    createTile(character: string, name: string): ButtonView;
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the first focusable in {@link ~CharacterGridView#tiles}.
+     */
+    focus(): void;
+}
+/**
+ * Fired when any of {@link ~CharacterGridView#tiles grid tiles} is clicked.
+ *
+ * @eventName ~CharacterGridView#execute
+ * @param data Additional information about the event.
+ */
+export type CharacterGridViewExecuteEvent = {
+    name: 'execute';
+    args: [data: CharacterGridViewEventData];
+};
+/**
+ * Fired when a mouse or another pointing device caused the cursor to move onto any {@link ~CharacterGridView#tiles grid tile}
+ * (similar to the native `mouseover` DOM event).
+ *
+ * @eventName ~CharacterGridView#tileHover
+ * @param data Additional information about the event.
+ */
+export type CharacterGridViewTileHoverEvent = {
+    name: 'tileHover';
+    args: [data: CharacterGridViewEventData];
+};
+/**
+ * Fired when {@link ~CharacterGridView#tiles grid tile} is focused (e.g. by navigating with arrow keys).
+ *
+ * @eventName ~CharacterGridView#tileFocus
+ * @param data Additional information about the event.
+ */
+export type CharacterGridViewTileFocusEvent = {
+    name: 'tileFocus';
+    args: [data: CharacterGridViewEventData];
+};
+export interface CharacterGridViewEventData {
+    /**
+     * The name of the tile that caused the event (e.g. "greek small letter epsilon").
+     */
+    name: string;
+    /**
+     * A human-readable character displayed as the label (e.g. "ε").
+     */
+    character: string;
+}

package/dist/types/ui/characterinfoview.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/ui/characterinfoview
+ */
+import type { Locale } from 'ckeditor5/src/utils.js';
+import { View } from 'ckeditor5/src/ui.js';
+import '../../theme/characterinfo.css';
+/**
+ * The view displaying detailed information about a special character glyph, e.g. upon
+ * hovering it with a mouse.
+ */
+export default class CharacterInfoView extends View<HTMLDivElement> {
+    /**
+     * The character whose information is displayed by the view. For instance, "∑" or "¿".
+     *
+     * @observable
+     */
+    character: string | null;
+    /**
+     * The name of the {@link #character}. For instance, "N-ary summation" or "Inverted question mark".
+     *
+     * @observable
+     */
+    name: string | null;
+    /**
+     * The "Unicode string" of the {@link #character}. For instance "U+0061".
+     *
+     * @observable
+     */
+    readonly code: string;
+    constructor(locale: Locale);
+}

package/dist/types/ui/specialcharactersnavigationview.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/ui/specialcharactersnavigationview
+ */
+import { type Locale } from 'ckeditor5/src/utils.js';
+import { FormHeaderView, type DropdownView } from 'ckeditor5/src/ui.js';
+/**
+ * A class representing the navigation part of the special characters UI. It is responsible
+ * for describing the feature and allowing the user to select a particular character group.
+ */
+export default class SpecialCharactersNavigationView extends FormHeaderView {
+    /**
+     * A dropdown that allows selecting a group of special characters to be displayed.
+     */
+    groupDropdownView: GroupDropdownView;
+    /**
+     * Creates an instance of the {@link module:special-characters/ui/specialcharactersnavigationview~SpecialCharactersNavigationView}
+     * class.
+     *
+     * @param locale The localization services instance.
+     * @param groupNames The names of the character groups and their displayed labels.
+     */
+    constructor(locale: Locale, groupNames: GroupNames);
+    /**
+     * Returns the name of the character group currently selected in the {@link #groupDropdownView}.
+     */
+    get currentGroupName(): string;
+    /**
+     * Focuses the character categories dropdown.
+     */
+    focus(): void;
+    /**
+     * Returns a dropdown that allows selecting character groups.
+     *
+     * @param groupNames The names of the character groups and their displayed labels.
+     */
+    private _createGroupDropdown;
+    /**
+     * Returns list item definitions to be used in the character group dropdown
+     * representing specific character groups.
+     *
+     * @param dropdown Dropdown view element
+     * @param groupNames The names of the character groups and their displayed labels.
+     */
+    private _getCharacterGroupListItemDefinitions;
+}
+/**
+ * The names of the character groups and their displayed labels.
+ */
+export type GroupNames = Map<string, string>;
+/**
+ * `DropdownView` with additional field for the name of the currectly selected character group.
+ */
+export type GroupDropdownView = DropdownView & {
+    value: string;
+};

package/dist/types/ui/specialcharactersview.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+/**
+ * @module special-characters/ui/specialcharactersview
+ */
+import { View, FocusCycler, type ViewCollection, type FocusableView } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils.js';
+import type CharacterGridView from './charactergridview.js';
+import type CharacterInfoView from './characterinfoview.js';
+import type SpecialCharactersNavigationView from './specialcharactersnavigationview.js';
+/**
+ * A view that glues pieces of the special characters dropdown panel together:
+ *
+ * * the navigation view (allows selecting the category),
+ * * the grid view (displays characters as a grid),
+ * * and the info view (displays detailed info about a specific character).
+ */
+export default class SpecialCharactersView 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.
+     */
+    protected readonly _focusCycler: FocusCycler;
+    /**
+     * An instance of the `SpecialCharactersNavigationView`.
+     */
+    navigationView: SpecialCharactersNavigationView;
+    /**
+     * An instance of the `CharacterGridView`.
+     */
+    gridView: CharacterGridView;
+    /**
+     * An instance of the `CharacterInfoView`.
+     */
+    infoView: CharacterInfoView;
+    /**
+     * Creates an instance of the `SpecialCharactersView`.
+     */
+    constructor(locale: Locale, navigationView: SpecialCharactersNavigationView, gridView: CharacterGridView, infoView: CharacterInfoView);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focus(): void;
+}

package/lang/translations/he.po

@@ -14,7 +14,7 @@ msgid ""
 msgstr ""
 "Language-Team: Hebrew (https://app.transifex.com/ckeditor/teams/11143/he/)\n"
 "Language: he\n"
-"Plural-Forms: nplurals=4; plural=(n == 1 && n % 1 == 0) ? 0 : (n == 2 && n % 1 == 0) ? 1: (n % 10 == 0 && n % 1 == 0 && n > 10) ? 2 : 3;\n"
+"Plural-Forms: nplurals=3; plural=(n == 1 && n % 1 == 0) ? 0 : (n == 2 && n % 1 == 0) ? 1: 2;\n"
 "Content-Type: text/plain; charset=UTF-8\n"
 
 msgctxt "Name of the special characters plugins, visible in a dropdown and as a button tooltip."

package/lang/translations/pt.po

@@ -135,11 +135,11 @@ msgstr "\"Top\" com seta para cima em cima"
 
 msgctxt "A label for the \"dollar sign\" symbol."
 msgid "Dollar sign"
-msgstr "Cifrão"
+msgstr "Sinal de Dólar"
 
 msgctxt "A label for the \"euro sign\" symbol."
 msgid "Euro sign"
-msgstr "Sinal de euro"
+msgstr "Sinal de Euro"
 
 msgctxt "A label for the \"yen sign\" symbol."
 msgid "Yen sign"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-special-characters",
-  "version": "41.1.0",
+  "version": "41.3.0-alpha.0",
   "description": "Special characters feature for CKEditor 5.",
   "keywords": [
     "ckeditor",
@@ -13,7 +13,7 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "ckeditor5": "41.1.0"
+    "ckeditor5": "41.3.0-alpha.0"
   },
   "author": "CKSource (http://cksource.com/)",
   "license": "GPL-2.0-or-later",
@@ -25,6 +25,7 @@
     "directory": "packages/ckeditor5-special-characters"
   },
   "files": [
+    "dist",
     "lang",
     "src/**/*.js",
     "src/**/*.d.ts",