@ckeditor/ckeditor5-utils 34.2.0 → 35.0.0

package/src/focustracker.js

@@ -1,157 +0,0 @@
-/**
- * @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 `HTMLElement`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 `HTMLElement`
- * 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
- */
-export default class FocusTracker {
-	constructor() {
-		/**
-		 * True when one of the registered elements is focused.
-		 *
-		 * @readonly
-		 * @observable
-		 * @member {Boolean} #isFocused
-		 */
-		this.set( 'isFocused', false );
-
-		/**
-		 * The currently focused element.
-		 *
-		 * While {@link #isFocused `isFocused`} remains `true`, the focus can
-		 * move between different UI elements. This property tracks those
-		 * elements and tells which one is currently focused.
-		 *
-		 * @readonly
-		 * @observable
-		 * @member {HTMLElement|null} #focusedElement
-		 */
-		this.set( 'focusedElement', null );
-
-		/**
-		 * List of registered elements.
-		 *
-		 * @private
-		 * @member {Set.<HTMLElement>}
-		 */
-		this._elements = new Set();
-
-		/**
-		 * Event loop timeout.
-		 *
-		 * @private
-		 * @member {Number}
-		 */
-		this._nextEventLoopTimeout = null;
-	}
-
-	/**
-	 * Starts tracking the specified element.
-	 *
-	 * @param {HTMLElement} 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 {HTMLElement} element
-	 */
-	remove( element ) {
-		if ( element === this.focusedElement ) {
-			this._blur( element );
-		}
-
-		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 {HTMLElement} 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 );
-	}
-
-	/**
-	 * @event focus
-	 */
-
-	/**
-	 * @event blur
-	 */
-}
-
-mix( FocusTracker, DomEmitterMixin );
-mix( FocusTracker, ObservableMixin );

package/src/index.js

@@ -1,45 +0,0 @@
-/**
- * @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

@@ -1,42 +0,0 @@
-/**
- * @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';
-
-/**
- * @module utils/inserttopriorityarray
- */
-
-/**
- * The priority object descriptor.
- *
- *		const objectWithPriority = {
- *			priority: 'high'
- *		}
- *
- * @typedef {Object} module:utils/inserttopriorityarray~ObjectWithPriority
- *
- * @property {module:utils/priorities~PriorityString|Number} priority Priority of the object.
- */
-
-/**
- * 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

@@ -1,18 +0,0 @@
-/**
- * @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

@@ -1,301 +0,0 @@
-/**
- * @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: '⇧'
-};
-
-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 {'ltr'|'rtl'} contentLanguageDirection The content language direction, corresponding to
- * {@link module:utils/locale~Locale#contentLanguageDirection}.
- * @returns {'left'|'up'|'right'|'down'} Localized arrow direction.
- */
-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 {'ltr'|'rtl'} 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() );
-}
-
-/**
- * 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

@@ -1,130 +0,0 @@
-/**
- * @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.
- *
- * The most frequent use of this class is through the {@link module:core/editor/editor~Editor#keystrokes `editor.keystrokes`}
- * property. It allows listening to keystrokes executed in the editing view:
- *
- *		editor.keystrokes.set( 'Ctrl+A', ( keyEvtData, cancel ) => {
- *			console.log( 'Ctrl+A has been pressed' );
- *			cancel();
- *		} );
- *
- * However, this utility class can be used in various part of the UI. For instance, a certain {@link module:ui/view~View}
- * can use it like this:
- *
- *		class MyView extends View {
- *			constructor() {
- *				this.keystrokes = new KeystrokeHandler();
- *
- * 				this.keystrokes.set( 'tab', handleTabKey );
- *			}
- *
- *			render() {
- *				super.render();
- *
- *				this.keystrokes.listenTo( this.element );
- *			}
- *		}
- *
- * That keystroke handler will listen to `keydown` events fired in this view's main element.
- *
- */
-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();
-	}
-}