@ckeditor/ckeditor5-utils 34.2.0 → 35.1.0

package/src/keyboard.js

@@ -2,29 +2,19 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
-/**
- * A set of utilities related to keyboard support.
- *
- * @module utils/keyboard
- */
-
 import CKEditorError from './ckeditorerror';
 import env from './env';
-
 const modifiersToGlyphsMac = {
-	ctrl: '⌃',
-	cmd: '⌘',
-	alt: '⌥',
-	shift: '⇧'
+    ctrl: '⌃',
+    cmd: '⌘',
+    alt: '⌥',
+    shift: '⇧'
 };
-
 const modifiersToGlyphsNonMac = {
-	ctrl: 'Ctrl+',
-	alt: 'Alt+',
-	shift: 'Shift+'
+    ctrl: 'Ctrl+',
+    alt: 'Alt+',
+    shift: 'Shift+'
 };
-
 /**
  * An object with `keyName => keyCode` pairs for a set of known keys.
  *
@@ -39,11 +29,7 @@ const modifiersToGlyphsNonMac = {
  * * `ctrl`, `cmd`, `shift`, `alt`.
  */
 export const keyCodes = generateKnownKeyCodes();
-
-const keyCodeNames = Object.fromEntries(
-	Object.entries( keyCodes ).map( ( [ name, code ] ) => [ code, name.charAt( 0 ).toUpperCase() + name.slice( 1 ) ] )
-);
-
+const keyCodeNames = Object.fromEntries(Object.entries(keyCodes).map(([name, code]) => [code, name.charAt(0).toUpperCase() + name.slice(1)]));
 /**
  * Converts a key name or {@link module:utils/keyboard~KeystrokeInfo keystroke info} into a key code.
  *
@@ -53,32 +39,29 @@ const keyCodeNames = Object.fromEntries(
  * or a keystroke data object.
  * @returns {Number} Key or keystroke code.
  */
-export function getCode( key ) {
-	let keyCode;
-
-	if ( typeof key == 'string' ) {
-		keyCode = keyCodes[ key.toLowerCase() ];
-
-		if ( !keyCode ) {
-			/**
-			 * Unknown key name. Only key names included in the {@link module:utils/keyboard~keyCodes} can be used.
-			 *
-			 * @error keyboard-unknown-key
-			 * @param {String} key
-			 */
-			throw new CKEditorError( 'keyboard-unknown-key', null, { key } );
-		}
-	} else {
-		keyCode = key.keyCode +
-			( key.altKey ? keyCodes.alt : 0 ) +
-			( key.ctrlKey ? keyCodes.ctrl : 0 ) +
-			( key.shiftKey ? keyCodes.shift : 0 ) +
-			( key.metaKey ? keyCodes.cmd : 0 );
-	}
-
-	return keyCode;
+export function getCode(key) {
+    let keyCode;
+    if (typeof key == 'string') {
+        keyCode = keyCodes[key.toLowerCase()];
+        if (!keyCode) {
+            /**
+             * Unknown key name. Only key names included in the {@link module:utils/keyboard~keyCodes} can be used.
+             *
+             * @error keyboard-unknown-key
+             * @param {String} key
+             */
+            throw new CKEditorError('keyboard-unknown-key', null, { key });
+        }
+    }
+    else {
+        keyCode = key.keyCode +
+            (key.altKey ? keyCodes.alt : 0) +
+            (key.ctrlKey ? keyCodes.ctrl : 0) +
+            (key.shiftKey ? keyCodes.shift : 0) +
+            (key.metaKey ? keyCodes.cmd : 0);
+    }
+    return keyCode;
 }
-
 /**
  * Parses the keystroke and returns a keystroke code that will match the code returned by
  * {@link module:utils/keyboard~getCode} for the corresponding {@link module:utils/keyboard~KeystrokeInfo keystroke info}.
@@ -101,16 +84,14 @@ export function getCode( key ) {
  * @param {String|Array.<Number|String>} keystroke The keystroke definition.
  * @returns {Number} Keystroke code.
  */
-export function parseKeystroke( keystroke ) {
-	if ( typeof keystroke == 'string' ) {
-		keystroke = splitKeystrokeText( keystroke );
-	}
-
-	return keystroke
-		.map( key => ( typeof key == 'string' ) ? getEnvKeyCode( key ) : key )
-		.reduce( ( key, sum ) => sum + key, 0 );
+export function parseKeystroke(keystroke) {
+    if (typeof keystroke == 'string') {
+        keystroke = splitKeystrokeText(keystroke);
+    }
+    return keystroke
+        .map(key => (typeof key == 'string') ? getEnvKeyCode(key) : key)
+        .reduce((key, sum) => sum + key, 0);
 }
-
 /**
  * Translates any keystroke string text like `"Ctrl+A"` to an
  * environment–specific keystroke, i.e. `"⌘A"` on macOS.
@@ -118,37 +99,31 @@ export function parseKeystroke( keystroke ) {
  * @param {String} keystroke The keystroke text.
  * @returns {String} The keystroke text specific for the environment.
  */
-export function getEnvKeystrokeText( keystroke ) {
-	let keystrokeCode = parseKeystroke( keystroke );
-
-	const modifiersToGlyphs = Object.entries( env.isMac ? modifiersToGlyphsMac : modifiersToGlyphsNonMac );
-
-	const modifiers = modifiersToGlyphs.reduce( ( modifiers, [ name, glyph ] ) => {
-		// Modifier keys are stored as a bit mask so extract those from the keystroke code.
-		if ( ( keystrokeCode & keyCodes[ name ] ) != 0 ) {
-			keystrokeCode &= ~keyCodes[ name ];
-			modifiers += glyph;
-		}
-
-		return modifiers;
-	}, '' );
-
-	return modifiers + ( keystrokeCode ? keyCodeNames[ keystrokeCode ] : '' );
+export function getEnvKeystrokeText(keystroke) {
+    let keystrokeCode = parseKeystroke(keystroke);
+    const modifiersToGlyphs = Object.entries(env.isMac ? modifiersToGlyphsMac : modifiersToGlyphsNonMac);
+    const modifiers = modifiersToGlyphs.reduce((modifiers, [name, glyph]) => {
+        // Modifier keys are stored as a bit mask so extract those from the keystroke code.
+        if ((keystrokeCode & keyCodes[name]) != 0) {
+            keystrokeCode &= ~keyCodes[name];
+            modifiers += glyph;
+        }
+        return modifiers;
+    }, '');
+    return modifiers + (keystrokeCode ? keyCodeNames[keystrokeCode] : '');
 }
-
 /**
  * Returns `true` if the provided key code represents one of the arrow keys.
  *
  * @param {Number} keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
  * @returns {Boolean}
  */
-export function isArrowKeyCode( keyCode ) {
-	return keyCode == keyCodes.arrowright ||
-		keyCode == keyCodes.arrowleft ||
-		keyCode == keyCodes.arrowup ||
-		keyCode == keyCodes.arrowdown;
+export function isArrowKeyCode(keyCode) {
+    return keyCode == keyCodes.arrowright ||
+        keyCode == keyCodes.arrowleft ||
+        keyCode == keyCodes.arrowup ||
+        keyCode == keyCodes.arrowdown;
 }
-
 /**
  * Returns the direction in which the {@link module:engine/model/documentselection~DocumentSelection selection}
  * will move when the provided arrow key code is pressed considering the language direction of the editor content.
@@ -157,45 +132,37 @@ export function isArrowKeyCode( keyCode ) {
  * in the model structure. Similarly, pressing the right arrow moves the selection left (backward).
  *
  * @param {Number} keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
- * @param {'ltr'|'rtl'} contentLanguageDirection The content language direction, corresponding to
+ * @param {module:utils/language~LanguageDirection} contentLanguageDirection The content language direction, corresponding to
  * {@link module:utils/locale~Locale#contentLanguageDirection}.
- * @returns {'left'|'up'|'right'|'down'} Localized arrow direction.
+ * @returns {module:utils/keyboard~ArrowKeyCodeDirection|undefined} Localized arrow direction or `undefined` for non-arrow key codes.
  */
-export function getLocalizedArrowKeyCodeDirection( keyCode, contentLanguageDirection ) {
-	const isLtrContent = contentLanguageDirection === 'ltr';
-
-	switch ( keyCode ) {
-		case keyCodes.arrowleft:
-			return isLtrContent ? 'left' : 'right';
-
-		case keyCodes.arrowright:
-			return isLtrContent ? 'right' : 'left';
-
-		case keyCodes.arrowup:
-			return 'up';
-
-		case keyCodes.arrowdown:
-			return 'down';
-	}
+export function getLocalizedArrowKeyCodeDirection(keyCode, contentLanguageDirection) {
+    const isLtrContent = contentLanguageDirection === 'ltr';
+    switch (keyCode) {
+        case keyCodes.arrowleft:
+            return isLtrContent ? 'left' : 'right';
+        case keyCodes.arrowright:
+            return isLtrContent ? 'right' : 'left';
+        case keyCodes.arrowup:
+            return 'up';
+        case keyCodes.arrowdown:
+            return 'down';
+    }
 }
-
 // Converts a key name to the key code with mapping based on the env.
 //
 // See: {@link module:utils/keyboard~getCode}.
 //
 // @param {String} key The key name (see {@link module:utils/keyboard~keyCodes}).
 // @returns {Number} Key code.
-function getEnvKeyCode( key ) {
-	// Don't remap modifier key for forced modifiers.
-	if ( key.endsWith( '!' ) ) {
-		return getCode( key.slice( 0, -1 ) );
-	}
-
-	const code = getCode( key );
-
-	return env.isMac && code == keyCodes.ctrl ? keyCodes.cmd : code;
+function getEnvKeyCode(key) {
+    // Don't remap modifier key for forced modifiers.
+    if (key.endsWith('!')) {
+        return getCode(key.slice(0, -1));
+    }
+    const code = getCode(key);
+    return env.isMac && code == keyCodes.ctrl ? keyCodes.cmd : code;
 }
-
 /**
  * Determines if the provided key code moves the {@link module:engine/model/documentselection~DocumentSelection selection}
  * forward or backward considering the language direction of the editor content.
@@ -204,98 +171,52 @@ function getEnvKeyCode( key ) {
  * in the model structure. Similarly, pressing the right arrow moves the selection backward.
  *
  * @param {Number} keyCode A key code as in {@link module:utils/keyboard~KeystrokeInfo#keyCode}.
- * @param {'ltr'|'rtl'} contentLanguageDirection The content language direction, corresponding to
+ * @param {module:utils/language~LanguageDirection} contentLanguageDirection The content language direction, corresponding to
  * {@link module:utils/locale~Locale#contentLanguageDirection}.
  * @returns {Boolean}
  */
-export function isForwardArrowKeyCode( keyCode, contentLanguageDirection ) {
-	const localizedKeyCodeDirection = getLocalizedArrowKeyCodeDirection( keyCode, contentLanguageDirection );
-
-	return localizedKeyCodeDirection === 'down' || localizedKeyCodeDirection === 'right';
+export function isForwardArrowKeyCode(keyCode, contentLanguageDirection) {
+    const localizedKeyCodeDirection = getLocalizedArrowKeyCodeDirection(keyCode, contentLanguageDirection);
+    return localizedKeyCodeDirection === 'down' || localizedKeyCodeDirection === 'right';
 }
-
 function generateKnownKeyCodes() {
-	const keyCodes = {
-		arrowleft: 37,
-		arrowup: 38,
-		arrowright: 39,
-		arrowdown: 40,
-		backspace: 8,
-		delete: 46,
-		enter: 13,
-		space: 32,
-		esc: 27,
-		tab: 9,
-
-		// The idea about these numbers is that they do not collide with any real key codes, so we can use them
-		// like bit masks.
-		ctrl: 0x110000,
-		shift: 0x220000,
-		alt: 0x440000,
-		cmd: 0x880000
-	};
-
-	// a-z
-	for ( let code = 65; code <= 90; code++ ) {
-		const letter = String.fromCharCode( code );
-
-		keyCodes[ letter.toLowerCase() ] = code;
-	}
-
-	// 0-9
-	for ( let code = 48; code <= 57; code++ ) {
-		keyCodes[ code - 48 ] = code;
-	}
-
-	// F1-F12
-	for ( let code = 112; code <= 123; code++ ) {
-		keyCodes[ 'f' + ( code - 111 ) ] = code;
-	}
-
-	// other characters
-	for ( const char of '`-=[];\',./\\' ) {
-		keyCodes[ char ] = char.charCodeAt( 0 );
-	}
-
-	return keyCodes;
+    const keyCodes = {
+        arrowleft: 37,
+        arrowup: 38,
+        arrowright: 39,
+        arrowdown: 40,
+        backspace: 8,
+        delete: 46,
+        enter: 13,
+        space: 32,
+        esc: 27,
+        tab: 9,
+        // The idea about these numbers is that they do not collide with any real key codes, so we can use them
+        // like bit masks.
+        ctrl: 0x110000,
+        shift: 0x220000,
+        alt: 0x440000,
+        cmd: 0x880000
+    };
+    // a-z
+    for (let code = 65; code <= 90; code++) {
+        const letter = String.fromCharCode(code);
+        keyCodes[letter.toLowerCase()] = code;
+    }
+    // 0-9
+    for (let code = 48; code <= 57; code++) {
+        keyCodes[code - 48] = code;
+    }
+    // F1-F12
+    for (let code = 112; code <= 123; code++) {
+        keyCodes['f' + (code - 111)] = code;
+    }
+    // other characters
+    for (const char of '`-=[];\',./\\') {
+        keyCodes[char] = char.charCodeAt(0);
+    }
+    return keyCodes;
 }
-
-function splitKeystrokeText( keystroke ) {
-	return keystroke.split( '+' ).map( key => key.trim() );
+function splitKeystrokeText(keystroke) {
+    return keystroke.split('+').map(key => key.trim());
 }
-
-/**
- * Information about the keystroke.
- *
- * @interface module:utils/keyboard~KeystrokeInfo
- */
-
-/**
- * The [key code](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/keyCode).
- *
- * @member {Number} module:utils/keyboard~KeystrokeInfo#keyCode
- */
-
-/**
- * Whether the <kbd>Alt</kbd> modifier was pressed.
- *
- * @member {Boolean} module:utils/keyboard~KeystrokeInfo#altKey
- */
-
-/**
- * Whether the <kbd>Ctrl</kbd> modifier was pressed.
- *
- * @member {Boolean} module:utils/keyboard~KeystrokeInfo#ctrlKey
- */
-
-/**
- * Whether the <kbd>Shift</kbd> modifier was pressed.
- *
- * @member {Boolean} module:utils/keyboard~KeystrokeInfo#shiftKey
- */
-
-/**
- * Whether the <kbd>Cmd</kbd> modifier was pressed.
- *
- * @member {Boolean} module:utils/keyboard~KeystrokeInfo#metaKey
- */

package/src/keystrokehandler.js

@@ -2,14 +2,11 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
 /**
  * @module utils/keystrokehandler
  */
-
 import DomEmitterMixin from './dom/emittermixin';
 import { getCode, parseKeystroke } from './keyboard';
-
 /**
  * Keystroke handler allows registering callbacks for given keystrokes.
  *
@@ -42,89 +39,76 @@ import { getCode, parseKeystroke } from './keyboard';
  *
  */
 export default class KeystrokeHandler {
-	/**
-	 * Creates an instance of the keystroke handler.
-	 */
-	constructor() {
-		/**
-		 * Listener used to listen to events for easier keystroke handler destruction.
-		 *
-		 * @protected
-		 * @member {module:utils/dom/emittermixin~Emitter}
-		 */
-		this._listener = Object.create( DomEmitterMixin );
-	}
-
-	/**
-	 * Starts listening for `keydown` events from a given emitter.
-	 *
-	 * @param {module:utils/emittermixin~Emitter} emitter
-	 */
-	listenTo( emitter ) {
-		// The #_listener works here as a kind of dispatcher. It groups the events coming from the same
-		// keystroke so the listeners can be attached to them with different priorities.
-		//
-		// E.g. all the keystrokes with the `keyCode` of 42 coming from the `emitter` are propagated
-		// as a `_keydown:42` event by the `_listener`. If there's a callback created by the `set`
-		// method for this 42 keystroke, it listens to the `_listener#_keydown:42` event only and interacts
-		// only with other listeners of this particular event, thus making it possible to prioritize
-		// the listeners and safely cancel execution, when needed. Instead of duplicating the Emitter logic,
-		// the KeystrokeHandler re–uses it to do its job.
-		this._listener.listenTo( emitter, 'keydown', ( evt, keyEvtData ) => {
-			this._listener.fire( '_keydown:' + getCode( keyEvtData ), keyEvtData );
-		} );
-	}
-
-	/**
-	 * Registers a handler for the specified keystroke.
-	 *
-	 * @param {String|Array.<String|Number>} keystroke Keystroke defined in a format accepted by
-	 * the {@link module:utils/keyboard~parseKeystroke} function.
-	 * @param {Function} callback A function called with the
-	 * {@link module:engine/view/observer/keyobserver~KeyEventData key event data} object and
-	 * a helper funcion to call both `preventDefault()` and `stopPropagation()` on the underlying event.
-	 * @param {Object} [options={}] Additional options.
-	 * @param {module:utils/priorities~PriorityString|Number} [options.priority='normal'] The priority of the keystroke
-	 * callback. The higher the priority value the sooner the callback will be executed. Keystrokes having the same priority
-	 * are called in the order they were added.
-	 */
-	set( keystroke, callback, options = {} ) {
-		const keyCode = parseKeystroke( keystroke );
-		const priority = options.priority;
-
-		// Execute the passed callback on KeystrokeHandler#_keydown.
-		// TODO: https://github.com/ckeditor/ckeditor5-utils/issues/144
-		this._listener.listenTo( this._listener, '_keydown:' + keyCode, ( evt, keyEvtData ) => {
-			callback( keyEvtData, () => {
-				// Stop the event in the DOM: no listener in the web page
-				// will be triggered by this event.
-				keyEvtData.preventDefault();
-				keyEvtData.stopPropagation();
-
-				// Stop the event in the KeystrokeHandler: no more callbacks
-				// will be executed for this keystroke.
-				evt.stop();
-			} );
-
-			// Mark this keystroke as handled by the callback. See: #press.
-			evt.return = true;
-		}, { priority } );
-	}
-
-	/**
-	 * Triggers a keystroke handler for a specified key combination, if such a keystroke was {@link #set defined}.
-	 *
-	 * @param {module:engine/view/observer/keyobserver~KeyEventData} keyEvtData Key event data.
-	 * @returns {Boolean} Whether the keystroke was handled.
-	 */
-	press( keyEvtData ) {
-		return !!this._listener.fire( '_keydown:' + getCode( keyEvtData ), keyEvtData );
-	}
-
-	/**
-	 * Destroys the keystroke handler.
-	 */
-	destroy() {
-		this._listener.stopListening();
-	}
+    /**
+     * Creates an instance of the keystroke handler.
+     */
+    constructor() {
+        this._listener = Object.create(DomEmitterMixin);
+    }
+    /**
+     * Starts listening for `keydown` events from a given emitter.
+     *
+     * @param {module:utils/emittermixin~Emitter|HTMLElement|Window} emitter
+     */
+    listenTo(emitter) {
+        // The #_listener works here as a kind of dispatcher. It groups the events coming from the same
+        // keystroke so the listeners can be attached to them with different priorities.
+        //
+        // E.g. all the keystrokes with the `keyCode` of 42 coming from the `emitter` are propagated
+        // as a `_keydown:42` event by the `_listener`. If there's a callback created by the `set`
+        // method for this 42 keystroke, it listens to the `_listener#_keydown:42` event only and interacts
+        // only with other listeners of this particular event, thus making it possible to prioritize
+        // the listeners and safely cancel execution, when needed. Instead of duplicating the Emitter logic,
+        // the KeystrokeHandler re–uses it to do its job.
+        this._listener.listenTo(emitter, 'keydown', (evt, keyEvtData) => {
+            this._listener.fire('_keydown:' + getCode(keyEvtData), keyEvtData);
+        });
+    }
+    /**
+     * Registers a handler for the specified keystroke.
+     *
+     * @param {String|Array.<String|Number>} keystroke Keystroke defined in a format accepted by
+     * the {@link module:utils/keyboard~parseKeystroke} function.
+     * @param {Function} callback A function called with the
+     * {@link module:engine/view/observer/keyobserver~KeyEventData key event data} object and
+     * a helper funcion to call both `preventDefault()` and `stopPropagation()` on the underlying event.
+     * @param {Object} [options={}] Additional options.
+     * @param {module:utils/priorities~PriorityString|Number} [options.priority='normal'] The priority of the keystroke
+     * callback. The higher the priority value the sooner the callback will be executed. Keystrokes having the same priority
+     * are called in the order they were added.
+     */
+    set(keystroke, callback, options = {}) {
+        const keyCode = parseKeystroke(keystroke);
+        const priority = options.priority;
+        // Execute the passed callback on KeystrokeHandler#_keydown.
+        // TODO: https://github.com/ckeditor/ckeditor5-utils/issues/144
+        this._listener.listenTo(this._listener, '_keydown:' + keyCode, (evt, keyEvtData) => {
+            callback(keyEvtData, () => {
+                // Stop the event in the DOM: no listener in the web page
+                // will be triggered by this event.
+                keyEvtData.preventDefault();
+                keyEvtData.stopPropagation();
+                // Stop the event in the KeystrokeHandler: no more callbacks
+                // will be executed for this keystroke.
+                evt.stop();
+            });
+            // Mark this keystroke as handled by the callback. See: #press.
+            evt.return = true;
+        }, { priority });
+    }
+    /**
+     * Triggers a keystroke handler for a specified key combination, if such a keystroke was {@link #set defined}.
+     *
+     * @param {module:engine/view/observer/keyobserver~KeyEventData} keyEvtData Key event data.
+     * @returns {Boolean} Whether the keystroke was handled.
+     */
+    press(keyEvtData) {
+        return !!this._listener.fire('_keydown:' + getCode(keyEvtData), keyEvtData);
+    }
+    /**
+     * Destroys the keystroke handler.
+     */
+    destroy() {
+        this._listener.stopListening();
+    }
 }

package/src/language.js

@@ -2,25 +2,19 @@
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  */
-
-/**
- * @module utils/language
- */
-
 const RTL_LANGUAGE_CODES = [
-	'ar', 'ara', // Arabic
-	'fa', 'per', 'fas', // Persian
-	'he', 'heb', // Hebrew
-	'ku', 'kur', // Kurdish
-	'ug', 'uig' // Uighur, Uyghur
+    'ar', 'ara',
+    'fa', 'per', 'fas',
+    'he', 'heb',
+    'ku', 'kur',
+    'ug', 'uig' // Uighur, Uyghur
 ];
-
 /**
  * Helps determine whether a language text direction is LTR or RTL.
  *
- * @param {String} language The ISO 639-1 or ISO 639-2 language code.
- * @returns {'ltr'|'rtl'}
+ * @param {String} languageCode The ISO 639-1 or ISO 639-2 language code.
+ * @returns {module:utils/language~LanguageDirection}
  */
-export function getLanguageDirection( languageCode ) {
-	return RTL_LANGUAGE_CODES.includes( languageCode ) ? 'rtl' : 'ltr';
+export function getLanguageDirection(languageCode) {
+    return RTL_LANGUAGE_CODES.includes(languageCode) ? 'rtl' : 'ltr';
 }