@ckeditor/ckeditor5-special-characters 36.0.1 → 37.0.0-alpha.0

package/src/ui/characterinfoview.js

@@ -2,110 +2,70 @@
  * @license Copyright (c) 2003-2023, 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 { View } from 'ckeditor5/src/ui';
-
 import '../../theme/characterinfo.css';
-
 /**
  * The view displaying detailed information about a special character glyph, e.g. upon
  * hovering it with a mouse.
- *
- * @extends module:ui/view~View
  */
 export default class CharacterInfoView extends View {
-	constructor( locale ) {
-		super( locale );
-
-		const bind = this.bindTemplate;
-
-		/**
-		 * The character whose information is displayed by the view. For instance,
-		 * "∑" or "¿".
-		 *
-		 * @observable
-		 * @member {String|null} #character
-		 */
-		this.set( 'character', null );
-
-		/**
-		 * The name of the {@link #character}. For instance,
-		 * "N-ary summation" or "Inverted question mark".
-		 *
-		 * @observable
-		 * @member {String|null} #name
-		 */
-		this.set( 'name', null );
-
-		/**
-		 * The "Unicode string" of the {@link #character}. For instance,
-		 * "U+0061".
-		 *
-		 * @observable
-		 * @readonly
-		 * @member {String} #code
-		 */
-		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'
-				]
-			}
-		} );
-	}
+    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`.
-//
-// @param {String} character
-// @returns {String}
-function characterToUnicodeString( character ) {
-	if ( character === null ) {
-		return '';
-	}
-
-	const hexCode = character.codePointAt( 0 ).toString( 16 );
-
-	return 'U+' + ( '0000' + hexCode ).slice( -4 );
+/**
+ * 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/specialcharactersnavigationview.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @license Copyright (c) 2003-2023, 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';
+import { FormHeaderView, type DropdownView } from 'ckeditor5/src/ui';
+/**
+ * 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/src/ui/specialcharactersnavigationview.js

@@ -2,134 +2,87 @@
  * @license Copyright (c) 2003-2023, 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 { Collection } from 'ckeditor5/src/utils';
-import { Model, FormHeaderView, createDropdown, addListToDropdown } from 'ckeditor5/src/ui';
-
+import { addListToDropdown, createDropdown, Model, FormHeaderView } from 'ckeditor5/src/ui';
 /**
  * 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.
- *
- * @extends module:ui/formheader/formheaderview~FormHeaderView
  */
 export default class SpecialCharactersNavigationView extends FormHeaderView {
-	/**
-	 * Creates an instance of the {@link module:special-characters/ui/specialcharactersnavigationview~SpecialCharactersNavigationView}
-	 * class.
-	 *
-	 * @param {module:utils/locale~Locale} locale The localization services instance.
-	 * @param {Map.<String, String>} groupNames The names of the character groups and their displayed labels.
-	 */
-	constructor( locale, groupNames ) {
-		super( locale );
-
-		const t = locale.t;
-
-		this.set( 'class', 'ck-special-characters-navigation' );
-
-		/**
-		 * A dropdown that allows selecting a group of special characters to be displayed.
-		 *
-		 * @member {module:ui/dropdown/dropdownview~DropdownView}
-		 */
-		this.groupDropdownView = this._createGroupDropdown( groupNames );
-		this.groupDropdownView.panelPosition = locale.uiLanguageDirection === 'rtl' ? 'se' : 'sw';
-
-		/**
-		 * @inheritDoc
-		 */
-		this.label = t( 'Special characters' );
-
-		/**
-		 * @inheritDoc
-		 */
-		this.children.add( this.groupDropdownView );
-	}
-
-	/**
-	 * Returns the name of the character group currently selected in the {@link #groupDropdownView}.
-	 *
-	 * @type {String}
-	 */
-	get currentGroupName() {
-		return this.groupDropdownView.value;
-	}
-
-	/**
-	 * Focuses the character categories dropdown.
-	 */
-	focus() {
-		this.groupDropdownView.focus();
-	}
-
-	/**
-	 * Returns a dropdown that allows selecting character groups.
-	 *
-	 * @private
-	 * @param {Map.<String, String>} groupNames The names of the character groups and their displayed labels.
-	 * @returns {module:ui/dropdown/dropdownview~DropdownView}
-	 */
-	_createGroupDropdown( groupNames ) {
-		const locale = this.locale;
-		const t = locale.t;
-		const dropdown = createDropdown( locale );
-		const groupDefinitions = this._getCharacterGroupListItemDefinitions( dropdown, groupNames );
-
-		dropdown.set( 'value', groupDefinitions.first.model.name );
-
-		dropdown.buttonView.bind( 'label' ).to( dropdown, 'value', value => groupNames.get( value ) );
-
-		dropdown.buttonView.set( {
-			isOn: false,
-			withText: true,
-			tooltip: t( 'Character categories' ),
-			class: [ 'ck-dropdown__button_label-width_auto' ]
-		} );
-
-		dropdown.on( 'execute', evt => {
-			dropdown.value = evt.source.name;
-		} );
-
-		dropdown.delegate( 'execute' ).to( this );
-
-		addListToDropdown( dropdown, groupDefinitions );
-
-		return dropdown;
-	}
-
-	/**
-	 * Returns list item definitions to be used in the character group dropdown
-	 * representing specific character groups.
-	 *
-	 * @private
-	 * @param {module:ui/dropdown/dropdownview~DropdownView} dropdown
-	 * @param {Map.<String, String>} groupNames The names of the character groups and their displayed labels.
-	 * @returns {Iterable.<module:ui/dropdown/utils~ListDropdownItemDefinition>}
-	 */
-	_getCharacterGroupListItemDefinitions( dropdown, groupNames ) {
-		const groupDefs = new Collection();
-
-		for ( const [ name, label ] of groupNames ) {
-			const definition = {
-				type: 'button',
-				model: new Model( {
-					name,
-					label,
-					withText: true
-				} )
-			};
-
-			definition.model.bind( 'isOn' ).to( dropdown, 'value', value => {
-				return value === definition.model.name;
-			} );
-
-			groupDefs.add( definition );
-		}
-
-		return groupDefs;
-	}
+    /**
+     * 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, groupNames) {
+        super(locale);
+        const t = locale.t;
+        this.set('class', 'ck-special-characters-navigation');
+        this.groupDropdownView = this._createGroupDropdown(groupNames);
+        this.groupDropdownView.panelPosition = locale.uiLanguageDirection === 'rtl' ? 'se' : 'sw';
+        this.label = t('Special characters');
+        this.children.add(this.groupDropdownView);
+    }
+    /**
+     * Returns the name of the character group currently selected in the {@link #groupDropdownView}.
+     */
+    get currentGroupName() {
+        return this.groupDropdownView.value;
+    }
+    /**
+     * Focuses the character categories dropdown.
+     */
+    focus() {
+        this.groupDropdownView.focus();
+    }
+    /**
+     * Returns a dropdown that allows selecting character groups.
+     *
+     * @param groupNames The names of the character groups and their displayed labels.
+     */
+    _createGroupDropdown(groupNames) {
+        const locale = this.locale;
+        const t = locale.t;
+        const dropdown = createDropdown(locale);
+        const groupDefinitions = this._getCharacterGroupListItemDefinitions(dropdown, groupNames);
+        dropdown.set('value', groupDefinitions.first.model.name);
+        dropdown.buttonView.bind('label').to(dropdown, 'value', value => groupNames.get(value));
+        dropdown.buttonView.set({
+            isOn: false,
+            withText: true,
+            tooltip: t('Character categories'),
+            class: ['ck-dropdown__button_label-width_auto']
+        });
+        dropdown.on('execute', evt => {
+            dropdown.value = evt.source.name;
+        });
+        dropdown.delegate('execute').to(this);
+        addListToDropdown(dropdown, groupDefinitions);
+        return dropdown;
+    }
+    /**
+     * 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.
+     */
+    _getCharacterGroupListItemDefinitions(dropdown, groupNames) {
+        const groupDefs = new Collection();
+        for (const [name, label] of groupNames) {
+            const model = new Model({
+                name,
+                label,
+                withText: true
+            });
+            model.bind('isOn').to(dropdown, 'value', value => value === model.name);
+            groupDefs.add({ type: 'button', model });
+        }
+        return groupDefs;
+    }
 }

package/src/ui/specialcharactersview.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @license Copyright (c) 2003-2023, 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 } from 'ckeditor5/src/ui';
+import { FocusTracker, KeystrokeHandler, type Locale } from 'ckeditor5/src/utils';
+import type CharacterGridView from './charactergridview';
+import type CharacterInfoView from './characterinfoview';
+import type SpecialCharactersNavigationView from './specialcharactersnavigationview';
+/**
+ * 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;
+    /**
+     * 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;
+}