@ckeditor/ckeditor5-utils 35.0.0 → 35.0.1

package/src/fastdiff.js

@@ -0,0 +1,229 @@
+/**
+ * @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
+ */
+/**
+ * Finds positions of the first and last change in the given string/array and generates a set of changes:
+ *
+ *		fastDiff( '12a', '12xyza' );
+ *		// [ { index: 2, type: 'insert', values: [ 'x', 'y', 'z' ] } ]
+ *
+ *		fastDiff( '12a', '12aa' );
+ *		// [ { index: 3, type: 'insert', values: [ 'a' ] } ]
+ *
+ *		fastDiff( '12xyza', '12a' );
+ *		// [ { index: 2, type: 'delete', howMany: 3 } ]
+ *
+ *		fastDiff( [ '1', '2', 'a', 'a' ], [ '1', '2', 'a' ] );
+ *		// [ { index: 3, type: 'delete', howMany: 1 } ]
+ *
+ *		fastDiff( [ '1', '2', 'a', 'b', 'c', '3' ], [ '2', 'a', 'b' ] );
+ *		// [ { index: 0, type: 'insert', values: [ '2', 'a', 'b' ] }, { index: 3, type: 'delete', howMany: 6 } ]
+ *
+ * Passed arrays can contain any type of data, however to compare them correctly custom comparator function
+ * should be passed as a third parameter:
+ *
+ *		fastDiff( [ { value: 1 }, { value: 2 } ], [ { value: 1 }, { value: 3 } ], ( a, b ) => {
+ *			return a.value === b.value;
+ *		} );
+ *		// [ { index: 1, type: 'insert', values: [ { value: 3 } ] }, { index: 2, type: 'delete', howMany: 1 } ]
+ *
+ * The resulted set of changes can be applied to the input in order to transform it into the output, for example:
+ *
+ *		let input = '12abc3';
+ *		const output = '2ab';
+ *		const changes = fastDiff( input, output );
+ *
+ *		changes.forEach( change => {
+ *			if ( change.type == 'insert' ) {
+ *				input = input.substring( 0, change.index ) + change.values.join( '' ) + input.substring( change.index );
+ *			} else if ( change.type == 'delete' ) {
+ *				input = input.substring( 0, change.index ) + input.substring( change.index + change.howMany );
+ *			}
+ *		} );
+ *
+ *		// input equals output now
+ *
+ * or in case of arrays:
+ *
+ *		let input = [ '1', '2', 'a', 'b', 'c', '3' ];
+ *		const output = [ '2', 'a', 'b' ];
+ *		const changes = fastDiff( input, output );
+ *
+ *		changes.forEach( change => {
+ *			if ( change.type == 'insert' ) {
+ *				input = input.slice( 0, change.index ).concat( change.values, input.slice( change.index ) );
+ *			} else if ( change.type == 'delete' ) {
+ *				input = input.slice( 0, change.index ).concat( input.slice( change.index + change.howMany ) );
+ *			}
+ *		} );
+ *
+ *		// input equals output now
+ *
+ * By passing `true` as the fourth parameter (`atomicChanges`) the output of this function will become compatible with
+ * the {@link module:utils/diff~diff `diff()`} function:
+ *
+ *		fastDiff( '12a', '12xyza' );
+ *		// [ 'equal', 'equal', 'insert', 'insert', 'insert', 'equal' ]
+ *
+ * The default output format of this function is compatible with the output format of
+ * {@link module:utils/difftochanges~diffToChanges `diffToChanges()`}. The `diffToChanges()` input format is, in turn,
+ * compatible with the output of {@link module:utils/diff~diff `diff()`}:
+ *
+ *		const a = '1234';
+ *		const b = '12xyz34';
+ *
+ *		// Both calls will return the same results (grouped changes format).
+ *		fastDiff( a, b );
+ *		diffToChanges( diff( a, b ) );
+ *
+ *		// Again, both calls will return the same results (atomic changes format).
+ *		fastDiff( a, b, null, true );
+ *		diff( a, b );
+ *
+ *
+ * @param {Array|String} a Input array or string.
+ * @param {Array|String} b Input array or string.
+ * @param {Function} [cmp] Optional function used to compare array values, by default `===` (strict equal operator) is used.
+ * @param {Boolean} [atomicChanges=false] Whether an array of `inset|delete|equal` operations should
+ * be returned instead of changes set. This makes this function compatible with {@link module:utils/diff~diff `diff()`}.
+ * @returns {Array} Array of changes.
+ */
+export default function fastDiff(a, b, cmp, atomicChanges = false) {
+    // Set the comparator function.
+    cmp = cmp || function (a, b) {
+        return a === b;
+    };
+    // Convert the string (or any array-like object - eg. NodeList) to an array by using the slice() method because,
+    // unlike Array.from(), it returns array of UTF-16 code units instead of the code points of a string.
+    // One code point might be a surrogate pair of two code units. All text offsets are expected to be in code units.
+    // See ckeditor/ckeditor5#3147.
+    //
+    // We need to make sure here that fastDiff() works identical to diff().
+    const arrayA = Array.isArray(a) ? a : Array.prototype.slice.call(a);
+    const arrayB = Array.isArray(b) ? b : Array.prototype.slice.call(b);
+    // Find first and last change.
+    const changeIndexes = findChangeBoundaryIndexes(arrayA, arrayB, cmp);
+    // Transform into changes array.
+    return atomicChanges ? changeIndexesToAtomicChanges(changeIndexes, arrayB.length) : changeIndexesToChanges(arrayB, changeIndexes);
+}
+// Finds position of the first and last change in the given arrays. For example:
+//
+//		const indexes = findChangeBoundaryIndexes( [ '1', '2', '3', '4' ], [ '1', '3', '4', '2', '4' ] );
+//		console.log( indexes ); // { firstIndex: 1, lastIndexOld: 3, lastIndexNew: 4 }
+//
+// The above indexes means that in the first array the modified part is `1[23]4` and in the second array it is `1[342]4`.
+// Based on such indexes, array with `insert`/`delete` operations which allows transforming first value into the second one
+// can be generated.
+//
+// @param {Array} arr1
+// @param {Array} arr2
+// @param {Function} cmp Comparator function.
+// @returns {Object}
+// @returns {Number} return.firstIndex Index of the first change in both values (always the same for both).
+// @returns {Number} result.lastIndexOld Index of the last common value in `arr1`.
+// @returns {Number} result.lastIndexNew Index of the last common value in `arr2`.
+function findChangeBoundaryIndexes(arr1, arr2, cmp) {
+    // Find the first difference between passed values.
+    const firstIndex = findFirstDifferenceIndex(arr1, arr2, cmp);
+    // If arrays are equal return -1 indexes object.
+    if (firstIndex === -1) {
+        return { firstIndex: -1, lastIndexOld: -1, lastIndexNew: -1 };
+    }
+    // Remove the common part of each value and reverse them to make it simpler to find the last difference between them.
+    const oldArrayReversed = cutAndReverse(arr1, firstIndex);
+    const newArrayReversed = cutAndReverse(arr2, firstIndex);
+    // Find the first difference between reversed values.
+    // It should be treated as "how many elements from the end the last difference occurred".
+    //
+    // For example:
+    //
+    // 				initial	->	after cut	-> reversed:
+    // oldValue:	'321ba'	->	'21ba'		-> 'ab12'
+    // newValue:	'31xba'	->	'1xba'		-> 'abx1'
+    // lastIndex:							-> 2
+    //
+    // So the last change occurred two characters from the end of the arrays.
+    const lastIndex = findFirstDifferenceIndex(oldArrayReversed, newArrayReversed, cmp);
+    // Use `lastIndex` to calculate proper offset, starting from the beginning (`lastIndex` kind of starts from the end).
+    const lastIndexOld = arr1.length - lastIndex;
+    const lastIndexNew = arr2.length - lastIndex;
+    return { firstIndex, lastIndexOld, lastIndexNew };
+}
+// Returns a first index on which given arrays differ. If both arrays are the same, -1 is returned.
+//
+// @param {Array} arr1
+// @param {Array} arr2
+// @param {Function} cmp Comparator function.
+// @returns {Number}
+function findFirstDifferenceIndex(arr1, arr2, cmp) {
+    for (let i = 0; i < Math.max(arr1.length, arr2.length); i++) {
+        if (arr1[i] === undefined || arr2[i] === undefined || !cmp(arr1[i], arr2[i])) {
+            return i;
+        }
+    }
+    return -1; // Return -1 if arrays are equal.
+}
+// Returns a copy of the given array with `howMany` elements removed starting from the beginning and in reversed order.
+//
+// @param {Array} arr Array to be processed.
+// @param {Number} howMany How many elements from array beginning to remove.
+// @returns {Array} Shortened and reversed array.
+function cutAndReverse(arr, howMany) {
+    return arr.slice(howMany).reverse();
+}
+// Generates changes array based on change indexes from `findChangeBoundaryIndexes` function. This function will
+// generate array with 0 (no changes), 1 (deletion or insertion) or 2 records (insertion and deletion).
+//
+// @param {Array} newArray New array for which change indexes were calculated.
+// @param {Object} changeIndexes Change indexes object from `findChangeBoundaryIndexes` function.
+// @returns {Array.<module:utils/difftochanges~Change>} Array of changes compatible with
+// {@link module:utils/difftochanges~diffToChanges} format.
+function changeIndexesToChanges(newArray, changeIndexes) {
+    const result = [];
+    const { firstIndex, lastIndexOld, lastIndexNew } = changeIndexes;
+    // Order operations as 'insert', 'delete' array to keep compatibility with {@link module:utils/difftochanges~diffToChanges}
+    // in most cases. However, 'diffToChanges' does not stick to any order so in some cases
+    // (for example replacing '12345' with 'abcd') it will generate 'delete', 'insert' order.
+    if (lastIndexNew - firstIndex > 0) {
+        result.push({
+            index: firstIndex,
+            type: 'insert',
+            values: newArray.slice(firstIndex, lastIndexNew)
+        });
+    }
+    if (lastIndexOld - firstIndex > 0) {
+        result.push({
+            index: firstIndex + (lastIndexNew - firstIndex),
+            type: 'delete',
+            howMany: lastIndexOld - firstIndex
+        });
+    }
+    return result;
+}
+// Generates array with set `equal|insert|delete` operations based on change indexes from `findChangeBoundaryIndexes` function.
+//
+// @param {Object} changeIndexes Change indexes object from `findChangeBoundaryIndexes` function.
+// @param {Number} newLength Length of the new array on which `findChangeBoundaryIndexes` calculated change indexes.
+// @returns {Array.<module:utils/diff~DiffResult>} Array of changes compatible with {@link module:utils/diff~diff} format.
+function changeIndexesToAtomicChanges(changeIndexes, newLength) {
+    const { firstIndex, lastIndexOld, lastIndexNew } = changeIndexes;
+    // No changes.
+    if (firstIndex === -1) {
+        return Array(newLength).fill('equal');
+    }
+    let result = [];
+    if (firstIndex > 0) {
+        result = result.concat(Array(firstIndex).fill('equal'));
+    }
+    if (lastIndexNew - firstIndex > 0) {
+        result = result.concat(Array(lastIndexNew - firstIndex).fill('insert'));
+    }
+    if (lastIndexOld - firstIndex > 0) {
+        result = result.concat(Array(lastIndexOld - firstIndex).fill('delete'));
+    }
+    if (lastIndexNew < newLength) {
+        result = result.concat(Array(newLength - lastIndexNew).fill('equal'));
+    }
+    return result;
+}

package/src/first.js

@@ -0,0 +1,20 @@
+/**
+ * @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/first
+ */
+/**
+ * Returns first item of the given `iterator`.
+ *
+ * @param {Iterator.<*>} iterator
+ * @returns {*}
+ */
+export default function first(iterator) {
+    const iteratorItem = iterator.next();
+    if (iteratorItem.done) {
+        return null;
+    }
+    return iteratorItem.value;
+}

package/src/focustracker.js

@@ -0,0 +1,103 @@
+/**
+ * @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
+ */
+/* global setTimeout, clearTimeout */
+/**
+ * @module utils/focustracker
+ */
+import DomEmitterMixin from './dom/emittermixin';
+import ObservableMixin from './observablemixin';
+import CKEditorError from './ckeditorerror';
+import mix from './mix';
+/**
+ * Allows observing a group of `Element`s whether at least one of them is focused.
+ *
+ * Used by the {@link module:core/editor/editor~Editor} in order to track whether the focus is still within the application,
+ * or were used outside of its UI.
+ *
+ * **Note** `focus` and `blur` listeners use event capturing, so it is only needed to register wrapper `Element`
+ * which contain other `focusable` elements. But note that this wrapper element has to be focusable too
+ * (have e.g. `tabindex="-1"`).
+ *
+ * Check out the {@glink framework/guides/deep-dive/ui/focus-tracking "Deep dive into focus tracking" guide} to learn more.
+ *
+ * @mixes module:utils/dom/emittermixin~EmitterMixin
+ * @mixes module:utils/observablemixin~ObservableMixin
+ */
+class FocusTracker {
+    constructor() {
+        this.set('isFocused', false);
+        this.set('focusedElement', null);
+        this._elements = new Set();
+        this._nextEventLoopTimeout = null;
+    }
+    /**
+     * Starts tracking the specified element.
+     *
+     * @param {Element} element
+     */
+    add(element) {
+        if (this._elements.has(element)) {
+            /**
+             * This element is already tracked by {@link module:utils/focustracker~FocusTracker}.
+             *
+             * @error focustracker-add-element-already-exist
+             */
+            throw new CKEditorError('focustracker-add-element-already-exist', this);
+        }
+        this.listenTo(element, 'focus', () => this._focus(element), { useCapture: true });
+        this.listenTo(element, 'blur', () => this._blur(), { useCapture: true });
+        this._elements.add(element);
+    }
+    /**
+     * Stops tracking the specified element and stops listening on this element.
+     *
+     * @param {Element} element
+     */
+    remove(element) {
+        if (element === this.focusedElement) {
+            this._blur();
+        }
+        if (this._elements.has(element)) {
+            this.stopListening(element);
+            this._elements.delete(element);
+        }
+    }
+    /**
+     * Destroys the focus tracker by:
+     * - Disabling all event listeners attached to tracked elements.
+     * - Removing all tracked elements that were previously added.
+     */
+    destroy() {
+        this.stopListening();
+    }
+    /**
+     * Stores currently focused element and set {#isFocused} as `true`.
+     *
+     * @private
+     * @param {Element} element Element which has been focused.
+     */
+    _focus(element) {
+        clearTimeout(this._nextEventLoopTimeout);
+        this.focusedElement = element;
+        this.isFocused = true;
+    }
+    /**
+     * Clears currently focused element and set {@link #isFocused} as `false`.
+     * This method uses `setTimeout` to change order of fires `blur` and `focus` events.
+     *
+     * @private
+     * @fires blur
+     */
+    _blur() {
+        clearTimeout(this._nextEventLoopTimeout);
+        this._nextEventLoopTimeout = setTimeout(() => {
+            this.focusedElement = null;
+            this.isFocused = false;
+        }, 0);
+    }
+}
+mix(FocusTracker, DomEmitterMixin);
+mix(FocusTracker, ObservableMixin);
+export default FocusTracker;

package/src/index.js

@@ -0,0 +1,36 @@
+/**
+ * @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
+ */
+export { default as env } from './env';
+export { default as diff } from './diff';
+export { default as mix } from './mix';
+export { default as EmitterMixin } from './emittermixin';
+export { default as ObservableMixin } from './observablemixin';
+export { default as CKEditorError, logError, logWarning } from './ckeditorerror';
+export { default as ElementReplacer } from './elementreplacer';
+export { default as createElement } from './dom/createelement';
+export { default as DomEmitterMixin } from './dom/emittermixin';
+export { default as global } from './dom/global';
+export { default as getDataFromElement } from './dom/getdatafromelement';
+export { default as Rect } from './dom/rect';
+export { default as ResizeObserver } from './dom/resizeobserver';
+export { default as setDataInElement } from './dom/setdatainelement';
+export { default as toUnit } from './dom/tounit';
+export { default as isVisible } from './dom/isvisible';
+export * from './dom/scroll';
+export * from './keyboard';
+export * from './language';
+export { default as Locale } from './locale';
+export { default as Collection } from './collection';
+export { default as first } from './first';
+export { default as FocusTracker } from './focustracker';
+export { default as KeystrokeHandler } from './keystrokehandler';
+export { default as toArray } from './toarray';
+export { default as toMap } from './tomap';
+export { default as priorities } from './priorities';
+export { default as uid } from './uid';
+export { default as version } from './version';

package/src/inserttopriorityarray.js

@@ -0,0 +1,21 @@
+/**
+ * @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
+ */
+import priorities from './priorities';
+/**
+ * Inserts any object with priority at correct index by priority so registered objects are always sorted from highest to lowest priority.
+ *
+ * @param {Array.<module:utils/inserttopriorityarray~ObjectWithPriority>} objects Array of objects with priority to insert object to.
+ * @param {module:utils/inserttopriorityarray~ObjectWithPriority} objectToInsert Object with `priority` property.
+ */
+export default function insertToPriorityArray(objects, objectToInsert) {
+    const priority = priorities.get(objectToInsert.priority);
+    for (let i = 0; i < objects.length; i++) {
+        if (priorities.get(objects[i].priority) < priority) {
+            objects.splice(i, 0, objectToInsert);
+            return;
+        }
+    }
+    objects.push(objectToInsert);
+}

package/src/isiterable.js

@@ -0,0 +1,16 @@
+/**
+ * @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/isiterable
+ */
+/**
+ * Checks if value implements iterator interface.
+ *
+ * @param {*} value The value to check.
+ * @returns {Boolean} True if value implements iterator interface.
+ */
+export default function isIterable(value) {
+    return !!(value && value[Symbol.iterator]);
+}

package/src/keyboard.js

@@ -0,0 +1,222 @@
+/**
+ * @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
+ */
+import CKEditorError from './ckeditorerror';
+import env from './env';
+const modifiersToGlyphsMac = {
+    ctrl: '⌃',
+    cmd: '⌘',
+    alt: '⌥',
+    shift: '⇧'
+};
+const modifiersToGlyphsNonMac = {
+    ctrl: 'Ctrl+',
+    alt: 'Alt+',
+    shift: 'Shift+'
+};
+/**
+ * An object with `keyName => keyCode` pairs for a set of known keys.
+ *
+ * Contains:
+ *
+ * * `a-z`,
+ * * `0-9`,
+ * * `f1-f12`,
+ * * `` ` ``, `-`, `=`, `[`, `]`, `;`, `'`, `,`, `.`, `/`, `\`,
+ * * `arrow(left|up|right|bottom)`,
+ * * `backspace`, `delete`, `enter`, `esc`, `tab`,
+ * * `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)]));
+/**
+ * Converts a key name or {@link module:utils/keyboard~KeystrokeInfo keystroke info} into a key code.
+ *
+ * Note: Key names are matched with {@link module:utils/keyboard~keyCodes} in a case-insensitive way.
+ *
+ * @param {String|module:utils/keyboard~KeystrokeInfo} A key name (see {@link module:utils/keyboard~keyCodes})
+ * 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;
+}
+/**
+ * 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}.
+ *
+ * The keystroke can be passed in two formats:
+ *
+ * * as a single string – e.g. `ctrl + A`,
+ * * as an array of {@link module:utils/keyboard~keyCodes known key names} and key codes – e.g.:
+ *   * `[ 'ctrl', 32 ]` (ctrl + space),
+ *   * `[ 'ctrl', 'a' ]` (ctrl + A).
+ *
+ * Note: Key names are matched with {@link module:utils/keyboard~keyCodes} in a case-insensitive way.
+ *
+ * Note: Only keystrokes with a single non-modifier key are supported (e.g. `ctrl+A` is OK, but `ctrl+A+B` is not).
+ *
+ * Note: On macOS, keystroke handling is translating the `Ctrl` key to the `Cmd` key and handling only that keystroke.
+ * For example, a registered keystroke `Ctrl+A` will be translated to `Cmd+A` on macOS. To disable the translation of some keystroke,
+ * use the forced modifier: `Ctrl!+A` (note the exclamation mark).
+ *
+ * @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);
+}
+/**
+ * Translates any keystroke string text like `"Ctrl+A"` to an
+ * environment–specific keystroke, i.e. `"⌘A"` on macOS.
+ *
+ * @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] : '');
+}
+/**
+ * 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;
+}
+/**
+ * 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.
+ *
+ * For instance, in right–to–left (RTL) content languages, pressing the left arrow means moving the selection right (forward)
+ * 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 {module:utils/language~LanguageDirection} contentLanguageDirection The content language direction, corresponding to
+ * {@link module:utils/locale~Locale#contentLanguageDirection}.
+ * @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';
+    }
+}
+// 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;
+}
+/**
+ * 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.
+ *
+ * For instance, in right–to–left (RTL) languages, pressing the left arrow means moving forward
+ * 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 {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';
+}
+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;
+}
+function splitKeystrokeText(keystroke) {
+    return keystroke.split('+').map(key => key.trim());
+}