@ckeditor/ckeditor5-engine 30.0.0

package/src/view/observer/fakeselectionobserver.js

@@ -0,0 +1,118 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/view/observer/fakeselectionobserver
+ */
+
+import Observer from './observer';
+import ViewSelection from '../selection';
+import { keyCodes } from '@ckeditor/ckeditor5-utils/src/keyboard';
+import { debounce } from 'lodash-es';
+
+/**
+ * Fake selection observer class. If view selection is fake it is placed in dummy DOM container. This observer listens
+ * on {@link module:engine/view/document~Document#event:keydown keydown} events and handles moving fake view selection to the correct place
+ * if arrow keys are pressed.
+ * Fires {@link module:engine/view/document~Document#event:selectionChange selectionChange event} simulating natural behaviour of
+ * {@link module:engine/view/observer/selectionobserver~SelectionObserver SelectionObserver}.
+ *
+ * @extends module:engine/view/observer/observer~Observer
+ */
+export default class FakeSelectionObserver extends Observer {
+	/**
+	 * Creates new FakeSelectionObserver instance.
+	 *
+	 * @param {module:engine/view/view~View} view
+	 */
+	constructor( view ) {
+		super( view );
+
+		/**
+		 * Fires debounced event `selectionChangeDone`. It uses `lodash#debounce` method to delay function call.
+		 *
+		 * @private
+		 * @param {Object} data Selection change data.
+		 * @method #_fireSelectionChangeDoneDebounced
+		 */
+		this._fireSelectionChangeDoneDebounced = debounce( data => this.document.fire( 'selectionChangeDone', data ), 200 );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	observe() {
+		const document = this.document;
+
+		document.on( 'arrowKey', ( eventInfo, data ) => {
+			const selection = document.selection;
+
+			if ( selection.isFake && this.isEnabled ) {
+				// Prevents default key down handling - no selection change will occur.
+				data.preventDefault();
+			}
+		}, { context: '$capture' } );
+
+		document.on( 'arrowKey', ( eventInfo, data ) => {
+			const selection = document.selection;
+
+			if ( selection.isFake && this.isEnabled ) {
+				this._handleSelectionMove( data.keyCode );
+			}
+		}, { priority: 'lowest' } );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	destroy() {
+		super.destroy();
+
+		this._fireSelectionChangeDoneDebounced.cancel();
+	}
+
+	/**
+	 * Handles collapsing view selection according to given key code. If left or up key is provided - new selection will be
+	 * collapsed to left. If right or down key is pressed - new selection will be collapsed to right.
+	 *
+	 * This method fires {@link module:engine/view/document~Document#event:selectionChange} and
+	 * {@link module:engine/view/document~Document#event:selectionChangeDone} events imitating behaviour of
+	 * {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
+	 *
+	 * @private
+	 * @param {Number} keyCode
+	 * @fires module:engine/view/document~Document#event:selectionChange
+	 * @fires module:engine/view/document~Document#event:selectionChangeDone
+	 */
+	_handleSelectionMove( keyCode ) {
+		const selection = this.document.selection;
+		const newSelection = new ViewSelection( selection.getRanges(), { backward: selection.isBackward, fake: false } );
+
+		// Left or up arrow pressed - move selection to start.
+		if ( keyCode == keyCodes.arrowleft || keyCode == keyCodes.arrowup ) {
+			newSelection.setTo( newSelection.getFirstPosition() );
+		}
+
+		// Right or down arrow pressed - move selection to end.
+		if ( keyCode == keyCodes.arrowright || keyCode == keyCodes.arrowdown ) {
+			newSelection.setTo( newSelection.getLastPosition() );
+		}
+
+		const data = {
+			oldSelection: selection,
+			newSelection,
+			domSelection: null
+		};
+
+		// Fire dummy selection change event.
+		this.document.fire( 'selectionChange', data );
+
+		// Call` #_fireSelectionChangeDoneDebounced` every time when `selectionChange` event is fired.
+		// This function is debounced what means that `selectionChangeDone` event will be fired only when
+		// defined int the function time will elapse since the last time the function was called.
+		// So `selectionChangeDone` will be fired when selection will stop changing.
+		this._fireSelectionChangeDoneDebounced( data );
+	}
+}

package/src/view/observer/focusobserver.js

@@ -0,0 +1,106 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/view/observer/focusobserver
+ */
+
+/* globals setTimeout, clearTimeout */
+
+import DomEventObserver from './domeventobserver';
+
+/**
+ * {@link module:engine/view/document~Document#event:focus Focus}
+ * and {@link module:engine/view/document~Document#event:blur blur} events observer.
+ * Focus observer handle also {@link module:engine/view/rooteditableelement~RootEditableElement#isFocused isFocused} property of the
+ * {@link module:engine/view/rooteditableelement~RootEditableElement root elements}.
+ *
+ * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
+ *
+ * @extends module:engine/view/observer/domeventobserver~DomEventObserver
+ */
+export default class FocusObserver extends DomEventObserver {
+	constructor( view ) {
+		super( view );
+
+		this.domEventType = [ 'focus', 'blur' ];
+		this.useCapture = true;
+		const document = this.document;
+
+		document.on( 'focus', () => {
+			document.isFocused = true;
+
+			// Unfortunately native `selectionchange` event is fired asynchronously.
+			// We need to wait until `SelectionObserver` handle the event and then render. Otherwise rendering will
+			// overwrite new DOM selection with selection from the view.
+			// See https://github.com/ckeditor/ckeditor5-engine/issues/795 for more details.
+			// Long timeout is needed to solve #676 and https://github.com/ckeditor/ckeditor5-engine/issues/1157 issues.
+			//
+			// Using `view.change()` instead of `view.forceRender()` to prevent double rendering
+			// in a situation where `selectionchange` already caused selection change.
+			this._renderTimeoutId = setTimeout( () => view.change( () => {} ), 50 );
+		} );
+
+		document.on( 'blur', ( evt, data ) => {
+			const selectedEditable = document.selection.editableElement;
+
+			if ( selectedEditable === null || selectedEditable === data.target ) {
+				document.isFocused = false;
+
+				// Re-render the document to update view elements
+				// (changing document.isFocused already marked view as changed since last rendering).
+				view.change( () => {} );
+			}
+		} );
+
+		/**
+		 * Identifier of the timeout currently used by focus listener to delay rendering execution.
+		 *
+		 * @private
+		 * @member {Number} #_renderTimeoutId
+		 */
+	}
+
+	onDomEvent( domEvent ) {
+		this.fire( domEvent.type, domEvent );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	destroy() {
+		if ( this._renderTimeoutId ) {
+			clearTimeout( this._renderTimeoutId );
+		}
+
+		super.destroy();
+	}
+}
+
+/**
+ * Fired when one of the editables gets focus.
+ *
+ * Introduced by {@link module:engine/view/observer/focusobserver~FocusObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/focusobserver~FocusObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/focusobserver~FocusObserver
+ * @event module:engine/view/document~Document#event:focus
+ * @param {module:engine/view/observer/domeventdata~DomEventData} data Event data.
+ */
+
+/**
+ * Fired when one of the editables loses focus.
+ *
+ * Introduced by {@link module:engine/view/observer/focusobserver~FocusObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/focusobserver~FocusObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/focusobserver~FocusObserver
+ * @event module:engine/view/document~Document#event:blur
+ * @param {module:engine/view/observer/domeventdata~DomEventData} data Event data.
+ */

package/src/view/observer/inputobserver.js

@@ -0,0 +1,44 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md.
+ */
+
+/**
+ * @module engine/view/observer/inputobserver
+ */
+
+import DomEventObserver from './domeventobserver';
+
+/**
+ * Observer for events connected with data input.
+ *
+ * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
+ *
+ * @extends module:engine/view/observer/domeventobserver~DomEventObserver
+ */
+export default class InputObserver extends DomEventObserver {
+	constructor( view ) {
+		super( view );
+
+		this.domEventType = [ 'beforeinput' ];
+	}
+
+	onDomEvent( domEvent ) {
+		this.fire( domEvent.type, domEvent );
+	}
+}
+
+/**
+ * Fired before browser inputs (or deletes) some data.
+ *
+ * This event is available only on browsers which support DOM `beforeinput` event.
+ *
+ * Introduced by {@link module:engine/view/observer/inputobserver~InputObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/inputobserver~InputObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/inputobserver~InputObserver
+ * @event module:engine/view/document~Document#event:beforeinput
+ * @param {module:engine/view/observer/domeventdata~DomEventData} data Event data.
+ */

package/src/view/observer/keyobserver.js

@@ -0,0 +1,83 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/view/observer/keyobserver
+ */
+
+import DomEventObserver from './domeventobserver';
+import { getCode } from '@ckeditor/ckeditor5-utils/src/keyboard';
+
+/**
+ * Observer for events connected with pressing keyboard keys.
+ *
+ * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
+ *
+ * @extends module:engine/view/observer/domeventobserver~DomEventObserver
+ */
+export default class KeyObserver extends DomEventObserver {
+	constructor( view ) {
+		super( view );
+
+		this.domEventType = [ 'keydown', 'keyup' ];
+	}
+
+	onDomEvent( domEvt ) {
+		this.fire( domEvt.type, domEvt, {
+			keyCode: domEvt.keyCode,
+
+			altKey: domEvt.altKey,
+			ctrlKey: domEvt.ctrlKey,
+			shiftKey: domEvt.shiftKey,
+			metaKey: domEvt.metaKey,
+
+			get keystroke() {
+				return getCode( this );
+			}
+		} );
+	}
+}
+
+/**
+ * Fired when a key has been pressed.
+ *
+ * Introduced by {@link module:engine/view/observer/keyobserver~KeyObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/keyobserver~KeyObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/keyobserver~KeyObserver
+ * @event module:engine/view/document~Document#event:keydown
+ * @param {module:engine/view/observer/keyobserver~KeyEventData} keyEventData
+ */
+
+/**
+ * Fired when a key has been released.
+ *
+ * Introduced by {@link module:engine/view/observer/keyobserver~KeyObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/keyobserver~KeyObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/keyobserver~KeyObserver
+ * @event module:engine/view/document~Document#event:keyup
+ * @param {module:engine/view/observer/keyobserver~KeyEventData} keyEventData
+ */
+
+/**
+ * The value of both events - {@link module:engine/view/document~Document#event:keydown} and
+ * {@link module:engine/view/document~Document#event:keyup}.
+ *
+ * @class module:engine/view/observer/keyobserver~KeyEventData
+ * @extends module:engine/view/observer/domeventdata~DomEventData
+ * @implements module:utils/keyboard~KeystrokeInfo
+ */
+
+/**
+ * Code of the whole keystroke. See {@link module:utils/keyboard~getCode}.
+ *
+ * @readonly
+ * @member {Number} module:engine/view/observer/keyobserver~KeyEventData#keystroke
+ */

package/src/view/observer/mouseobserver.js

@@ -0,0 +1,56 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/view/observer/mouseobserver
+ */
+
+import DomEventObserver from './domeventobserver';
+
+/**
+ * Mouse events observer.
+ *
+ * Note that this observer is not available by default. To make it available it needs to be added to
+ * {@link module:engine/view/view~View} by {@link module:engine/view/view~View#addObserver} method.
+ *
+ * @extends module:engine/view/observer/domeventobserver~DomEventObserver
+ */
+export default class MouseObserver extends DomEventObserver {
+	constructor( view ) {
+		super( view );
+
+		this.domEventType = [ 'mousedown', 'mouseup', 'mouseover', 'mouseout' ];
+	}
+
+	onDomEvent( domEvent ) {
+		this.fire( domEvent.type, domEvent );
+	}
+}
+
+/**
+ * Fired when the mouse button is pressed down on one of the editing roots of the editor.
+ *
+ * Introduced by {@link module:engine/view/observer/mouseobserver~MouseObserver}.
+ *
+ * Note that this event is not available by default. To make it available, {@link module:engine/view/observer/mouseobserver~MouseObserver}
+ * needs to be added to {@link module:engine/view/view~View} by the {@link module:engine/view/view~View#addObserver} method.
+ *
+ * @see module:engine/view/observer/mouseobserver~MouseObserver
+ * @event module:engine/view/document~Document#event:mousedown
+ * @param {module:engine/view/observer/domeventdata~DomEventData} data The event data.
+ */
+
+/**
+ * Fired when the mouse button is released over one of the editing roots of the editor.
+ *
+ * Introduced by {@link module:engine/view/observer/mouseobserver~MouseObserver}.
+ *
+ * Note that this event is not available by default. To make it available, {@link module:engine/view/observer/mouseobserver~MouseObserver}
+ * needs to be added to {@link module:engine/view/view~View} by the {@link module:engine/view/view~View#addObserver} method.
+ *
+ * @see module:engine/view/observer/mouseobserver~MouseObserver
+ * @event module:engine/view/document~Document#event:mouseup
+ * @param {module:engine/view/observer/domeventdata~DomEventData} data The event data.
+ */