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

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

@@ -0,0 +1,129 @@
+/**
+ * @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, addKeyboardHandlingForGrid } from 'ckeditor5/src/ui.js';
+import { KeystrokeHandler, FocusTracker, global } 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 {
+    /**
+     * Creates an instance of a character grid containing tiles representing special characters.
+     *
+     * @param locale The localization services instance.
+     */
+    constructor(locale) {
+        super(locale);
+        this.tiles = this.createCollection();
+        this.setTemplate({
+            tag: 'div',
+            children: [
+                {
+                    tag: 'div',
+                    attributes: {
+                        class: [
+                            'ck',
+                            'ck-character-grid__tiles'
+                        ]
+                    },
+                    children: this.tiles
+                }
+            ],
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-character-grid'
+                ]
+            }
+        });
+        this.focusTracker = new FocusTracker();
+        this.keystrokes = new KeystrokeHandler();
+        addKeyboardHandlingForGrid({
+            keystrokeHandler: this.keystrokes,
+            focusTracker: this.focusTracker,
+            gridItems: this.tiles,
+            numberOfColumns: () => global.window
+                .getComputedStyle(this.element.firstChild) // Responsive .ck-character-grid__tiles
+                .getPropertyValue('grid-template-columns')
+                .split(' ')
+                .length,
+            uiLanguageDirection: this.locale && this.locale.uiLanguageDirection
+        });
+    }
+    /**
+     * 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, name) {
+        const tile = new ButtonView(this.locale);
+        tile.set({
+            label: character,
+            withText: true,
+            class: 'ck-character-grid__tile'
+        });
+        // Labels are vital for the users to understand what character they're looking at.
+        // For now we're using native title attribute for that, see #5817.
+        tile.extendTemplate({
+            attributes: {
+                title: name
+            },
+            on: {
+                mouseover: tile.bindTemplate.to('mouseover'),
+                focus: tile.bindTemplate.to('focus')
+            }
+        });
+        tile.on('mouseover', () => {
+            this.fire('tileHover', { name, character });
+        });
+        tile.on('focus', () => {
+            this.fire('tileFocus', { name, character });
+        });
+        tile.on('execute', () => {
+            this.fire('execute', { name, character });
+        });
+        return tile;
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        for (const item of this.tiles) {
+            this.focusTracker.add(item.element);
+        }
+        this.tiles.on('change', (eventInfo, { added, removed }) => {
+            if (added.length > 0) {
+                for (const item of added) {
+                    this.focusTracker.add(item.element);
+                }
+            }
+            if (removed.length > 0) {
+                for (const item of removed) {
+                    this.focusTracker.remove(item.element);
+                }
+            }
+        });
+        this.keystrokes.listenTo(this.element);
+    }
+    /**
+     * @inheritDoc
+     */
+    destroy() {
+        super.destroy();
+        this.keystrokes.destroy();
+    }
+    /**
+     * Focuses the first focusable in {@link ~CharacterGridView#tiles}.
+     */
+    focus() {
+        this.tiles.first.focus();
+    }
+}

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

@@ -0,0 +1,71 @@
+/**
+ * @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 { 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 {
+    constructor(locale) {
+        super(locale);
+        const bind = this.bindTemplate;
+        this.set('character', null);
+        this.set('name', null);
+        this.bind('code').to(this, 'character', characterToUnicodeString);
+        this.setTemplate({
+            tag: 'div',
+            children: [
+                {
+                    tag: 'span',
+                    attributes: {
+                        class: [
+                            'ck-character-info__name'
+                        ]
+                    },
+                    children: [
+                        {
+                            // Note: ZWSP to prevent vertical collapsing.
+                            text: bind.to('name', name => name ? name : '\u200B')
+                        }
+                    ]
+                },
+                {
+                    tag: 'span',
+                    attributes: {
+                        class: [
+                            'ck-character-info__code'
+                        ]
+                    },
+                    children: [
+                        {
+                            text: bind.to('code')
+                        }
+                    ]
+                }
+            ],
+            attributes: {
+                class: [
+                    'ck',
+                    'ck-character-info'
+                ]
+            }
+        });
+    }
+}
+/**
+ * Converts a character into a "Unicode string", for instance:
+ *
+ * "$" -> "U+0024"
+ *
+ * Returns an empty string when the character is `null`.
+ */
+function characterToUnicodeString(character) {
+    if (character === null) {
+        return '';
+    }
+    const hexCode = character.codePointAt(0).toString(16);
+    return 'U+' + ('0000' + hexCode).slice(-4);
+}

package/src/ui/specialcharacterscategoriesview.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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/specialcharacterscategoriesview
+ */
+import { type Locale } from 'ckeditor5/src/utils.js';
+import { View } 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 SpecialCharactersCategoriesView extends View {
+    /**
+     * Currently selected special characters group's name.
+     */
+    currentGroupName: string;
+    private _groupNames;
+    private _dropdownView;
+    /**
+     * Creates an instance of the {@link module:special-characters/ui/specialcharacterscategoriesview~SpecialCharactersCategoriesView}
+     * class.
+     *
+     * @param locale The localization services instance.
+     * @param groupNames The names of the character groups.
+     */
+    constructor(locale: Locale, groupNames: Map<string, string>);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    focus(): void;
+    /**
+     * Creates dropdown item list, sets up bindings and fills properties.
+     */
+    private _setupDropdown;
+}

package/src/ui/specialcharacterscategoriesview.js

@@ -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/specialcharacterscategoriesview
+ */
+import { Collection } from 'ckeditor5/src/utils.js';
+import { addListToDropdown, createLabeledDropdown, LabeledFieldView, View, ViewModel } 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 SpecialCharactersCategoriesView extends View {
+    /**
+     * Creates an instance of the {@link module:special-characters/ui/specialcharacterscategoriesview~SpecialCharactersCategoriesView}
+     * class.
+     *
+     * @param locale The localization services instance.
+     * @param groupNames The names of the character groups.
+     */
+    constructor(locale, groupNames) {
+        super(locale);
+        this.set('currentGroupName', Array.from(groupNames.entries())[0][0]);
+        this._groupNames = groupNames;
+        this._dropdownView = new LabeledFieldView(locale, createLabeledDropdown);
+        this.setTemplate({
+            tag: 'div',
+            attributes: {
+                class: ['ck', 'ck-character-categories']
+            },
+            children: [
+                this._dropdownView
+            ]
+        });
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this._setupDropdown();
+    }
+    /**
+     * @inheritDoc
+     */
+    focus() {
+        this._dropdownView.focus();
+    }
+    /**
+     * Creates dropdown item list, sets up bindings and fills properties.
+     */
+    _setupDropdown() {
+        const items = new Collection();
+        for (const [name, label] of this._groupNames) {
+            const item = {
+                type: 'button',
+                model: new ViewModel({
+                    name,
+                    label,
+                    role: 'menuitemradio',
+                    withText: true
+                })
+            };
+            item.model.bind('isOn').to(this, 'currentGroupName', value => {
+                return value === name;
+            });
+            items.add(item);
+        }
+        const t = this.locale.t;
+        const accessibleLabel = t('Category');
+        this._dropdownView.set({
+            label: accessibleLabel,
+            isEmpty: false
+        });
+        this._dropdownView.fieldView.panelPosition = this.locale.uiLanguageDirection === 'rtl' ? 'se' : 'sw';
+        this._dropdownView.fieldView.buttonView.set({
+            withText: true,
+            tooltip: accessibleLabel,
+            ariaLabel: accessibleLabel,
+            ariaLabelledBy: undefined,
+            isOn: false
+        });
+        this._dropdownView.fieldView.buttonView.bind('label')
+            .to(this, 'currentGroupName', value => this._groupNames.get(value));
+        this._dropdownView.fieldView.on('execute', ({ source }) => {
+            this.currentGroupName = source.name;
+        });
+        addListToDropdown(this._dropdownView.fieldView, items, {
+            ariaLabel: accessibleLabel,
+            role: 'menu'
+        });
+    }
+}

package/src/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 SpecialCharactersCategoriesView from './specialcharacterscategoriesview.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 `SpecialCharactersCategoriesView`.
+     */
+    categoriesView: SpecialCharactersCategoriesView;
+    /**
+     * An instance of the `CharacterGridView`.
+     */
+    gridView: CharacterGridView;
+    /**
+     * An instance of the `CharacterInfoView`.
+     */
+    infoView: CharacterInfoView;
+    /**
+     * Creates an instance of the `SpecialCharactersView`.
+     */
+    constructor(locale: Locale, categoriesView: SpecialCharactersCategoriesView, gridView: CharacterGridView, infoView: CharacterInfoView);
+    /**
+     * @inheritDoc
+     */
+    render(): void;
+    /**
+     * @inheritDoc
+     */
+    destroy(): void;
+    /**
+     * Focuses the first focusable in {@link #items}.
+     */
+    focus(): void;
+}

package/src/ui/specialcharactersview.js

@@ -0,0 +1,78 @@
+/**
+ * @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 } from 'ckeditor5/src/ui.js';
+import { FocusTracker, KeystrokeHandler } from 'ckeditor5/src/utils.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 {
+    /**
+     * Creates an instance of the `SpecialCharactersView`.
+     */
+    constructor(locale, categoriesView, gridView, infoView) {
+        super(locale);
+        this.categoriesView = categoriesView;
+        this.gridView = gridView;
+        this.infoView = infoView;
+        this.items = this.createCollection();
+        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: [
+                this.categoriesView,
+                this.gridView,
+                this.infoView
+            ],
+            attributes: {
+                // Avoid focus loss when the user clicks the area of the grid that is not a button.
+                // https://github.com/ckeditor/ckeditor5/pull/12319#issuecomment-1231779819
+                tabindex: '-1'
+            }
+        });
+        this.items.add(this.categoriesView);
+        this.items.add(this.gridView);
+    }
+    /**
+     * @inheritDoc
+     */
+    render() {
+        super.render();
+        this.focusTracker.add(this.categoriesView.element);
+        this.focusTracker.add(this.gridView.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 first focusable in {@link #items}.
+     */
+    focus() {
+        this._focusCycler.focusFirst();
+    }
+}

package/theme/charactergrid.css

@@ -0,0 +1,12 @@
+/*
+ * 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
+ */
+
+.ck.ck-character-grid {
+	max-width: 100%;
+
+	& .ck-character-grid__tiles {
+		display: grid;
+	}
+}

package/theme/characterinfo.css

@@ -0,0 +1,9 @@
+/*
+ * 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
+ */
+
+.ck.ck-character-info {
+	display: flex;
+	justify-content: space-between;
+}

package/theme/icons/specialcharacters.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg"><path d="M10 2.5a7.47 7.47 0 0 1 4.231 1.31 7.268 7.268 0 0 1 2.703 3.454 7.128 7.128 0 0 1 .199 4.353c-.39 1.436-1.475 2.72-2.633 3.677h2.013c0-.226.092-.443.254-.603a.876.876 0 0 1 1.229 0c.163.16.254.377.254.603v.853c0 .209-.078.41-.22.567a.873.873 0 0 1-.547.28l-.101.006h-4.695a.517.517 0 0 1-.516-.518v-1.265c0-.21.128-.398.317-.489a5.601 5.601 0 0 0 2.492-2.371 5.459 5.459 0 0 0 .552-3.693 5.53 5.53 0 0 0-1.955-3.2A5.71 5.71 0 0 0 10 4.206 5.708 5.708 0 0 0 6.419 5.46 5.527 5.527 0 0 0 4.46 8.663a5.457 5.457 0 0 0 .554 3.695 5.6 5.6 0 0 0 2.497 2.37.55.55 0 0 1 .317.49v1.264c0 .286-.23.518-.516.518H2.618a.877.877 0 0 1-.614-.25.845.845 0 0 1-.254-.603v-.853c0-.226.091-.443.254-.603a.876.876 0 0 1 1.228 0c.163.16.255.377.255.603h1.925c-1.158-.958-2.155-2.241-2.545-3.678a7.128 7.128 0 0 1 .199-4.352 7.268 7.268 0 0 1 2.703-3.455A7.475 7.475 0 0 1 10 2.5z"/></svg>