@ckeditor/ckeditor5-special-characters 0.0.0-internal-20241017.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@ckeditor/ckeditor5-special-characters",
+  "version": "0.0.0-internal-20241017.0",
+  "description": "Special characters feature for CKEditor 5.",
+  "keywords": [
+    "ckeditor",
+    "ckeditor5",
+    "ckeditor 5",
+    "ckeditor5-feature",
+    "ckeditor5-plugin",
+    "ckeditor5-dll"
+  ],
+  "type": "module",
+  "main": "src/index.js",
+  "dependencies": {
+    "ckeditor5": "0.0.0-internal-20241017.0",
+    "@ckeditor/ckeditor5-core": "0.0.0-internal-20241017.0",
+    "@ckeditor/ckeditor5-typing": "0.0.0-internal-20241017.0",
+    "@ckeditor/ckeditor5-ui": "0.0.0-internal-20241017.0",
+    "@ckeditor/ckeditor5-utils": "0.0.0-internal-20241017.0"
+  },
+  "author": "CKSource (http://cksource.com/)",
+  "license": "GPL-2.0-or-later",
+  "homepage": "https://ckeditor.com",
+  "bugs": "https://github.com/ckeditor/ckeditor5/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ckeditor/ckeditor5.git",
+    "directory": "packages/ckeditor5-special-characters"
+  },
+  "files": [
+    "dist",
+    "lang",
+    "src/**/*.js",
+    "src/**/*.d.ts",
+    "theme",
+    "build",
+    "ckeditor5-metadata.json",
+    "CHANGELOG.md"
+  ],
+  "types": "src/index.d.ts"
+}

package/src/augmentation.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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
+ */
+import type { SpecialCharacters, SpecialCharactersArrows, SpecialCharactersCurrency, SpecialCharactersEssentials, SpecialCharactersLatin, SpecialCharactersMathematical, SpecialCharactersText, SpecialCharactersConfig } from './index.js';
+declare module '@ckeditor/ckeditor5-core' {
+    interface PluginsMap {
+        [SpecialCharacters.pluginName]: SpecialCharacters;
+        [SpecialCharactersText.pluginName]: SpecialCharactersText;
+        [SpecialCharactersArrows.pluginName]: SpecialCharactersArrows;
+        [SpecialCharactersEssentials.pluginName]: SpecialCharactersEssentials;
+        [SpecialCharactersLatin.pluginName]: SpecialCharactersLatin;
+        [SpecialCharactersCurrency.pluginName]: SpecialCharactersCurrency;
+        [SpecialCharactersMathematical.pluginName]: SpecialCharactersMathematical;
+    }
+    interface EditorConfig {
+        /**
+         * The configuration of the {@link module:special-characters/specialcharacters~SpecialCharacters} feature.
+         *
+         * Read more in {@link module:special-characters/specialcharactersconfig~SpecialCharactersConfig}.
+         */
+        specialCharacters?: SpecialCharactersConfig;
+    }
+}

package/src/augmentation.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @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
+ */
+export { default as SpecialCharacters } from './specialcharacters.js';
+export { default as SpecialCharactersArrows } from './specialcharactersarrows.js';
+export { default as SpecialCharactersText } from './specialcharacterstext.js';
+export { default as SpecialCharactersMathematical } from './specialcharactersmathematical.js';
+export { default as SpecialCharactersLatin } from './specialcharacterslatin.js';
+export { default as SpecialCharactersEssentials } from './specialcharactersessentials.js';
+export { default as SpecialCharactersCurrency } from './specialcharacterscurrency.js';
+export type { SpecialCharactersConfig } from './specialcharactersconfig.js';
+import './augmentation.js';

package/src/index.js

@@ -0,0 +1,15 @@
+/**
+ * @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
+ */
+export { default as SpecialCharacters } from './specialcharacters.js';
+export { default as SpecialCharactersArrows } from './specialcharactersarrows.js';
+export { default as SpecialCharactersText } from './specialcharacterstext.js';
+export { default as SpecialCharactersMathematical } from './specialcharactersmathematical.js';
+export { default as SpecialCharactersLatin } from './specialcharacterslatin.js';
+export { default as SpecialCharactersEssentials } from './specialcharactersessentials.js';
+export { default as SpecialCharactersCurrency } from './specialcharacterscurrency.js';
+import './augmentation.js';

package/src/specialcharacters.d.ts

@@ -0,0 +1,106 @@
+/**
+ * @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 { Dialog } from 'ckeditor5/src/ui.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, typeof Dialog];
+    /**
+     * @inheritDoc
+     */
+    static get pluginName(): "SpecialCharacters";
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @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 `categoriesView`, `gridView` and `infoView` properties, containing UI parts.
+     */
+    private _createDropdownPanelContent;
+    /**
+     * Creates a button for toolbar and menu bar that will show special characters dialog.
+     */
+    private _createDialogButton;
+    private _showDialog;
+}
+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/src/specialcharacters.js

@@ -0,0 +1,235 @@
+/**
+ * @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 } from 'ckeditor5/src/core.js';
+import { Typing } from 'ckeditor5/src/typing.js';
+import { ButtonView, MenuBarMenuListItemButtonView, DialogViewPosition, Dialog } from 'ckeditor5/src/ui.js';
+import { CKEditorError } from 'ckeditor5/src/utils.js';
+import CharacterGridView from './ui/charactergridview.js';
+import CharacterInfoView from './ui/characterinfoview.js';
+import SpecialCharactersView from './ui/specialcharactersview.js';
+import specialCharactersIcon from '../theme/icons/specialcharacters.svg';
+import '../theme/specialcharacters.css';
+import SpecialCharactersCategoriesView from './ui/specialcharacterscategoriesview.js';
+const ALL_SPECIAL_CHARACTERS_GROUP = 'All';
+/**
+ * The special characters feature.
+ *
+ * Introduces the `'specialCharacters'` dropdown.
+ */
+export default class SpecialCharacters extends Plugin {
+    /**
+     * @inheritDoc
+     */
+    static get requires() {
+        return [Typing, Dialog];
+    }
+    /**
+     * @inheritDoc
+     */
+    static get pluginName() {
+        return 'SpecialCharacters';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    constructor(editor) {
+        super(editor);
+        const t = editor.t;
+        this._characters = new Map();
+        this._groups = new Map();
+        this._allSpecialCharactersGroupLabel = t('All');
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        editor.ui.componentFactory.add('specialCharacters', () => {
+            const button = this._createDialogButton(ButtonView);
+            button.set({
+                tooltip: true
+            });
+            return button;
+        });
+        editor.ui.componentFactory.add('menuBar:specialCharacters', () => {
+            return this._createDialogButton(MenuBarMenuListItemButtonView);
+        });
+    }
+    /**
+     * 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, items, options = { label: groupName }) {
+        if (groupName === ALL_SPECIAL_CHARACTERS_GROUP) {
+            /**
+             * The name "All" for a special category group cannot be used because it is a special category that displays all
+             * available special characters.
+             *
+             * @error special-character-invalid-group-name
+             */
+            throw new CKEditorError('special-character-invalid-group-name', null);
+        }
+        const group = this._getGroup(groupName, options.label);
+        for (const item of items) {
+            group.items.add(item.title);
+            this._characters.set(item.title, item.character);
+        }
+    }
+    /**
+     * Returns special character groups in an order determined based on configuration and registration sequence.
+     */
+    getGroups() {
+        const groups = Array.from(this._groups.keys());
+        const order = this.editor.config.get('specialCharacters.order') || [];
+        const invalidGroup = order.find(item => !groups.includes(item));
+        if (invalidGroup) {
+            /**
+             * One of the special character groups in the "specialCharacters.order" configuration doesn't exist.
+             *
+             * @error special-character-invalid-order-group-name
+             */
+            throw new CKEditorError('special-character-invalid-order-group-name', null, { invalidGroup });
+        }
+        return new Set([
+            ...order,
+            ...groups
+        ]);
+    }
+    /**
+     * Returns a collection of special characters symbol names (titles).
+     */
+    getCharactersForGroup(groupName) {
+        if (groupName === ALL_SPECIAL_CHARACTERS_GROUP) {
+            return new Set(this._characters.keys());
+        }
+        const group = this._groups.get(groupName);
+        if (group) {
+            return group.items;
+        }
+    }
+    /**
+     * 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) {
+        return this._characters.get(title);
+    }
+    /**
+     * 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.
+     */
+    _getGroup(groupName, label) {
+        if (!this._groups.has(groupName)) {
+            this._groups.set(groupName, {
+                items: new Set(),
+                label
+            });
+        }
+        return this._groups.get(groupName);
+    }
+    /**
+     * Updates the symbol grid depending on the currently selected character group.
+     */
+    _updateGrid(currentGroupName, gridView) {
+        // Updating the grid starts with removing all tiles belonging to the old group.
+        gridView.tiles.clear();
+        const characterTitles = this.getCharactersForGroup(currentGroupName);
+        for (const title of characterTitles) {
+            const character = this.getCharacter(title);
+            gridView.tiles.add(gridView.createTile(character, title));
+        }
+    }
+    /**
+     * Initializes the dropdown, used for lazy loading.
+     *
+     * @returns An object with `categoriesView`, `gridView` and `infoView` properties, containing UI parts.
+     */
+    _createDropdownPanelContent(locale) {
+        const groupEntries = Array
+            .from(this.getGroups())
+            .map(name => ([name, this._groups.get(name).label]));
+        // The map contains a name of category (an identifier) and its label (a translational string).
+        const specialCharsGroups = new Map([
+            // Add a special group that shows all available special characters.
+            [ALL_SPECIAL_CHARACTERS_GROUP, this._allSpecialCharactersGroupLabel],
+            ...groupEntries
+        ]);
+        const categoriesView = new SpecialCharactersCategoriesView(locale, specialCharsGroups);
+        const gridView = new CharacterGridView(locale);
+        const infoView = new CharacterInfoView(locale);
+        gridView.on('tileHover', (evt, data) => {
+            infoView.set(data);
+        });
+        gridView.on('tileFocus', (evt, data) => {
+            infoView.set(data);
+        });
+        // Update the grid of special characters when a user changed the character group.
+        categoriesView.on('change:currentGroupName', (evt, propertyName, newValue) => {
+            this._updateGrid(newValue, gridView);
+        });
+        // Set the initial content of the special characters grid.
+        this._updateGrid(categoriesView.currentGroupName, gridView);
+        return { categoriesView, gridView, infoView };
+    }
+    /**
+     * Creates a button for toolbar and menu bar that will show special characters dialog.
+     */
+    _createDialogButton(ButtonClass) {
+        const editor = this.editor;
+        const locale = editor.locale;
+        const buttonView = new ButtonClass(editor.locale);
+        const command = editor.commands.get('insertText');
+        const t = locale.t;
+        const dialogPlugin = this.editor.plugins.get('Dialog');
+        buttonView.set({
+            label: t('Special characters'),
+            icon: specialCharactersIcon,
+            isToggleable: true
+        });
+        buttonView.bind('isOn').to(dialogPlugin, 'id', id => id === 'specialCharacters');
+        buttonView.bind('isEnabled').to(command, 'isEnabled');
+        buttonView.on('execute', () => {
+            if (dialogPlugin.id === 'specialCharacters') {
+                dialogPlugin.hide();
+                return;
+            }
+            this._showDialog();
+        });
+        return buttonView;
+    }
+    _showDialog() {
+        const editor = this.editor;
+        const dialog = editor.plugins.get('Dialog');
+        const locale = editor.locale;
+        const t = locale.t;
+        const { categoriesView, gridView, infoView } = this._createDropdownPanelContent(locale);
+        const content = new SpecialCharactersView(locale, categoriesView, gridView, infoView);
+        gridView.on('execute', (evt, data) => {
+            editor.execute('insertText', { text: data.character });
+        });
+        dialog.show({
+            id: 'specialCharacters',
+            title: t('Special characters'),
+            className: 'ck-special-characters',
+            content,
+            position: DialogViewPosition.EDITOR_TOP_SIDE
+        });
+    }
+}

package/src/specialcharactersarrows.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}

package/src/specialcharactersarrows.js

@@ -0,0 +1,66 @@
+/**
+ * @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() {
+        return 'SpecialCharactersArrows';
+    }
+    /**
+     * @inheritDoc
+     */
+    static get isOfficialPlugin() {
+        return true;
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        const editor = this.editor;
+        const t = editor.t;
+        const plugin = editor.plugins.get('SpecialCharacters');
+        plugin.addItems('Arrows', [
+            { title: t('leftwards simple arrow'), character: '←' },
+            { title: t('rightwards simple arrow'), character: '→' },
+            { title: t('upwards simple arrow'), character: '↑' },
+            { title: t('downwards simple arrow'), character: '↓' },
+            { title: t('leftwards double arrow'), character: '⇐' },
+            { title: t('rightwards double arrow'), character: '⇒' },
+            { title: t('upwards double arrow'), character: '⇑' },
+            { title: t('downwards double arrow'), character: '⇓' },
+            { title: t('leftwards dashed arrow'), character: '⇠' },
+            { title: t('rightwards dashed arrow'), character: '⇢' },
+            { title: t('upwards dashed arrow'), character: '⇡' },
+            { title: t('downwards dashed arrow'), character: '⇣' },
+            { title: t('leftwards arrow to bar'), character: '⇤' },
+            { title: t('rightwards arrow to bar'), character: '⇥' },
+            { title: t('upwards arrow to bar'), character: '⤒' },
+            { title: t('downwards arrow to bar'), character: '⤓' },
+            { title: t('up down arrow with base'), character: '↨' },
+            { title: t('back with leftwards arrow above'), character: '🔙' },
+            { title: t('end with leftwards arrow above'), character: '🔚' },
+            { title: t('on with exclamation mark with left right arrow above'), character: '🔛' },
+            { title: t('soon with rightwards arrow above'), character: '🔜' },
+            { title: t('top with upwards arrow above'), character: '🔝' }
+        ], { label: t('Arrows') });
+    }
+}

package/src/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/src/specialcharactersconfig.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/specialcharacterscurrency.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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
+     */
+    static get isOfficialPlugin(): true;
+    /**
+     * @inheritDoc
+     */
+    init(): void;
+}