@ckeditor/ckeditor5-engine 30.0.0

package/src/view/observer/mutationobserver.js

@@ -0,0 +1,345 @@
+/**
+ * @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/mutationobserver
+ */
+
+/* globals window */
+
+import Observer from './observer';
+import ViewSelection from '../selection';
+import { startsWithFiller, getDataWithoutFiller } from '../filler';
+import { isEqualWith } from 'lodash-es';
+
+/**
+ * Mutation observer class observes changes in the DOM, fires {@link module:engine/view/document~Document#event:mutations} event, mark view
+ * elements as changed and call {@link module:engine/view/renderer~Renderer#render}.
+ * Because all mutated nodes are marked as "to be rendered" and the
+ * {@link module:engine/view/renderer~Renderer#render} is called, all changes will be reverted, unless the mutation will be handled by the
+ * {@link module:engine/view/document~Document#event:mutations} event listener. It means user will see only handled changes, and the editor
+ * will block all changes which are not handled.
+ *
+ * Mutation Observer also take care of reducing number of mutations which are fired. It removes duplicates and
+ * mutations on elements which do not have corresponding view elements. Also
+ * {@link module:engine/view/observer/mutationobserver~MutatedText text mutation} is fired only if parent element do not change child list.
+ *
+ * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
+ *
+ * @extends module:engine/view/observer/observer~Observer
+ */
+export default class MutationObserver extends Observer {
+	constructor( view ) {
+		super( view );
+
+		/**
+		 * Native mutation observer config.
+		 *
+		 * @private
+		 * @member {Object}
+		 */
+		this._config = {
+			childList: true,
+			characterData: true,
+			characterDataOldValue: true,
+			subtree: true
+		};
+
+		/**
+		 * Reference to the {@link module:engine/view/view~View#domConverter}.
+		 *
+		 * @member {module:engine/view/domconverter~DomConverter}
+		 */
+		this.domConverter = view.domConverter;
+
+		/**
+		 * Reference to the {@link module:engine/view/view~View#_renderer}.
+		 *
+		 * @member {module:engine/view/renderer~Renderer}
+		 */
+		this.renderer = view._renderer;
+
+		/**
+		 * Observed DOM elements.
+		 *
+		 * @private
+		 * @member {Array.<HTMLElement>}
+		 */
+		this._domElements = [];
+
+		/**
+		 * Native mutation observer.
+		 *
+		 * @private
+		 * @member {MutationObserver}
+		 */
+		this._mutationObserver = new window.MutationObserver( this._onMutations.bind( this ) );
+	}
+
+	/**
+	 * Synchronously fires {@link module:engine/view/document~Document#event:mutations} event with all mutations in record queue.
+	 * At the same time empties the queue so mutations will not be fired twice.
+	 */
+	flush() {
+		this._onMutations( this._mutationObserver.takeRecords() );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	observe( domElement ) {
+		this._domElements.push( domElement );
+
+		if ( this.isEnabled ) {
+			this._mutationObserver.observe( domElement, this._config );
+		}
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	enable() {
+		super.enable();
+
+		for ( const domElement of this._domElements ) {
+			this._mutationObserver.observe( domElement, this._config );
+		}
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	disable() {
+		super.disable();
+
+		this._mutationObserver.disconnect();
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	destroy() {
+		super.destroy();
+
+		this._mutationObserver.disconnect();
+	}
+
+	/**
+	 * Handles mutations. Deduplicates, mark view elements to sync, fire event and call render.
+	 *
+	 * @private
+	 * @param {Array.<Object>} domMutations Array of native mutations.
+	 */
+	_onMutations( domMutations ) {
+		// As a result of this.flush() we can have an empty collection.
+		if ( domMutations.length === 0 ) {
+			return;
+		}
+
+		const domConverter = this.domConverter;
+
+		// Use map and set for deduplication.
+		const mutatedTexts = new Map();
+		const mutatedElements = new Set();
+
+		// Handle `childList` mutations first, so we will be able to check if the `characterData` mutation is in the
+		// element with changed structure anyway.
+		for ( const mutation of domMutations ) {
+			if ( mutation.type === 'childList' ) {
+				const element = domConverter.mapDomToView( mutation.target );
+
+				// Do not collect mutations from UIElements and RawElements.
+				if ( element && ( element.is( 'uiElement' ) || element.is( 'rawElement' ) ) ) {
+					continue;
+				}
+
+				if ( element && !this._isBogusBrMutation( mutation ) ) {
+					mutatedElements.add( element );
+				}
+			}
+		}
+
+		// Handle `characterData` mutations later, when we have the full list of nodes which changed structure.
+		for ( const mutation of domMutations ) {
+			const element = domConverter.mapDomToView( mutation.target );
+
+			// Do not collect mutations from UIElements and RawElements.
+			if ( element && ( element.is( 'uiElement' ) || element.is( 'rawElement' ) ) ) {
+				continue;
+			}
+
+			if ( mutation.type === 'characterData' ) {
+				const text = domConverter.findCorrespondingViewText( mutation.target );
+
+				if ( text && !mutatedElements.has( text.parent ) ) {
+					// Use text as a key, for deduplication. If there will be another mutation on the same text element
+					// we will have only one in the map.
+					mutatedTexts.set( text, {
+						type: 'text',
+						oldText: text.data,
+						newText: getDataWithoutFiller( mutation.target ),
+						node: text
+					} );
+				}
+				// When we added first letter to the text node which had only inline filler, for the DOM it is mutation
+				// on text, but for the view, where filler text node did not existed, new text node was created, so we
+				// need to fire 'children' mutation instead of 'text'.
+				else if ( !text && startsWithFiller( mutation.target ) ) {
+					mutatedElements.add( domConverter.mapDomToView( mutation.target.parentNode ) );
+				}
+			}
+		}
+
+		// Now we build the list of mutations to fire and mark elements. We did not do it earlier to avoid marking the
+		// same node multiple times in case of duplication.
+
+		// List of mutations we will fire.
+		const viewMutations = [];
+
+		for ( const mutatedText of mutatedTexts.values() ) {
+			this.renderer.markToSync( 'text', mutatedText.node );
+			viewMutations.push( mutatedText );
+		}
+
+		for ( const viewElement of mutatedElements ) {
+			const domElement = domConverter.mapViewToDom( viewElement );
+			const viewChildren = Array.from( viewElement.getChildren() );
+			const newViewChildren = Array.from( domConverter.domChildrenToView( domElement, { withChildren: false } ) );
+
+			// It may happen that as a result of many changes (sth was inserted and then removed),
+			// both elements haven't really changed. #1031
+			if ( !isEqualWith( viewChildren, newViewChildren, sameNodes ) ) {
+				this.renderer.markToSync( 'children', viewElement );
+
+				viewMutations.push( {
+					type: 'children',
+					oldChildren: viewChildren,
+					newChildren: newViewChildren,
+					node: viewElement
+				} );
+			}
+		}
+
+		// Retrieve `domSelection` using `ownerDocument` of one of mutated nodes.
+		// There should not be simultaneous mutation in multiple documents, so it's fine.
+		const domSelection = domMutations[ 0 ].target.ownerDocument.getSelection();
+
+		let viewSelection = null;
+
+		if ( domSelection && domSelection.anchorNode ) {
+			// If `domSelection` is inside a dom node that is already bound to a view node from view tree, get
+			// corresponding selection in the view and pass it together with `viewMutations`. The `viewSelection` may
+			// be used by features handling mutations.
+			// Only one range is supported.
+
+			const viewSelectionAnchor = domConverter.domPositionToView( domSelection.anchorNode, domSelection.anchorOffset );
+			const viewSelectionFocus = domConverter.domPositionToView( domSelection.focusNode, domSelection.focusOffset );
+
+			// Anchor and focus has to be properly mapped to view.
+			if ( viewSelectionAnchor && viewSelectionFocus ) {
+				viewSelection = new ViewSelection( viewSelectionAnchor );
+				viewSelection.setFocus( viewSelectionFocus );
+			}
+		}
+
+		// In case only non-relevant mutations were recorded it skips the event and force render (#5600).
+		if ( viewMutations.length ) {
+			this.document.fire( 'mutations', viewMutations, viewSelection );
+
+			// If nothing changes on `mutations` event, at this point we have "dirty DOM" (changed) and de-synched
+			// view (which has not been changed). In order to "reset DOM" we render the view again.
+			this.view.forceRender();
+		}
+
+		function sameNodes( child1, child2 ) {
+			// First level of comparison (array of children vs array of children) – use the Lodash's default behavior.
+			if ( Array.isArray( child1 ) ) {
+				return;
+			}
+
+			// Elements.
+			if ( child1 === child2 ) {
+				return true;
+			}
+			// Texts.
+			else if ( child1.is( '$text' ) && child2.is( '$text' ) ) {
+				return child1.data === child2.data;
+			}
+
+			// Not matching types.
+			return false;
+		}
+	}
+
+	/**
+	 * Checks if mutation was generated by the browser inserting bogus br on the end of the block element.
+	 * Such mutations are generated while pressing space or performing native spellchecker correction
+	 * on the end of the block element in Firefox browser.
+	 *
+	 * @private
+	 * @param {Object} mutation Native mutation object.
+	 * @returns {Boolean}
+	 */
+	_isBogusBrMutation( mutation ) {
+		let addedNode = null;
+
+		// Check if mutation added only one node on the end of its parent.
+		if ( mutation.nextSibling === null && mutation.removedNodes.length === 0 && mutation.addedNodes.length == 1 ) {
+			addedNode = this.domConverter.domToView( mutation.addedNodes[ 0 ], {
+				withChildren: false
+			} );
+		}
+
+		return addedNode && addedNode.is( 'element', 'br' );
+	}
+}
+
+/**
+ * Fired when mutation occurred. If tree view is not changed on this event, DOM will be reverted to the state before
+ * mutation, so all changes which should be applied, should be handled on this event.
+ *
+ * Introduced by {@link module:engine/view/observer/mutationobserver~MutationObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/mutationobserver~MutationObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/mutationobserver~MutationObserver
+ * @event module:engine/view/document~Document#event:mutations
+ * @param {Array.<module:engine/view/observer/mutationobserver~MutatedText|module:engine/view/observer/mutationobserver~MutatedChildren>}
+ * viewMutations Array of mutations.
+ * For mutated texts it will be {@link module:engine/view/observer/mutationobserver~MutatedText} and for mutated elements it will be
+ * {@link module:engine/view/observer/mutationobserver~MutatedChildren}. You can recognize the type based on the `type` property.
+ * @param {module:engine/view/selection~Selection|null} viewSelection View selection that is a result of converting DOM selection to view.
+ * Keep in
+ * mind that the DOM selection is already "updated", meaning that it already acknowledges changes done in mutation.
+ */
+
+/**
+ * Mutation item for text.
+ *
+ * @see module:engine/view/document~Document#event:mutations
+ * @see module:engine/view/observer/mutationobserver~MutatedChildren
+ *
+ * @typedef {Object} module:engine/view/observer/mutationobserver~MutatedText
+ *
+ * @property {String} type For text mutations it is always 'text'.
+ * @property {module:engine/view/text~Text} node Mutated text node.
+ * @property {String} oldText Old text.
+ * @property {String} newText New text.
+ */
+
+/**
+ * Mutation item for child nodes.
+ *
+ * @see module:engine/view/document~Document#event:mutations
+ * @see module:engine/view/observer/mutationobserver~MutatedText
+ *
+ * @typedef {Object} module:engine/view/observer/mutationobserver~MutatedChildren
+ *
+ * @property {String} type For child nodes mutations it is always 'children'.
+ * @property {module:engine/view/element~Element} node Parent of the mutated children.
+ * @property {Array.<module:engine/view/node~Node>} oldChildren Old child nodes.
+ * @property {Array.<module:engine/view/node~Node>} newChildren New child nodes.
+ */

package/src/view/observer/observer.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/observer
+ */
+
+import DomEmitterMixin from '@ckeditor/ckeditor5-utils/src/dom/emittermixin';
+import mix from '@ckeditor/ckeditor5-utils/src/mix';
+
+/**
+ * Abstract base observer class. Observers are classes which listen to DOM events, do the preliminary
+ * processing and fire events on the {@link module:engine/view/document~Document} objects.
+ * Observers can also add features to the view, for instance by updating its status or marking elements
+ * which need a refresh on DOM events.
+ *
+ * @abstract
+ */
+export default class Observer {
+	/**
+	 * Creates an instance of the observer.
+	 *
+	 * @param {module:engine/view/view~View} view
+	 */
+	constructor( view ) {
+		/**
+		 * An instance of the view controller.
+		 *
+		 * @readonly
+		 * @member {module:engine/view/view~View}
+		 */
+		this.view = view;
+
+		/**
+		 * A reference to the {@link module:engine/view/document~Document} object.
+		 *
+		 * @readonly
+		 * @member {module:engine/view/document~Document}
+		 */
+		this.document = view.document;
+
+		/**
+		 * The state of the observer. If it is disabled, no events will be fired.
+		 *
+		 * @readonly
+		 * @member {Boolean}
+		 */
+		this.isEnabled = false;
+	}
+
+	/**
+	 * Enables the observer. This method is called when the observer is registered to the
+	 * {@link module:engine/view/view~View} and after {@link module:engine/view/view~View#forceRender rendering}
+	 * (all observers are {@link #disable disabled} before rendering).
+	 *
+	 * A typical use case for disabling observers is that mutation observers need to be disabled for the rendering.
+	 * However, a child class may not need to be disabled, so it can implement an empty method.
+	 *
+	 * @see module:engine/view/observer/observer~Observer#disable
+	 */
+	enable() {
+		this.isEnabled = true;
+	}
+
+	/**
+	 * Disables the observer. This method is called before
+	 * {@link module:engine/view/view~View#forceRender rendering} to prevent firing events during rendering.
+	 *
+	 * @see module:engine/view/observer/observer~Observer#enable
+	 */
+	disable() {
+		this.isEnabled = false;
+	}
+
+	/**
+	 * Disables and destroys the observer, among others removes event listeners created by the observer.
+	 */
+	destroy() {
+		this.disable();
+		this.stopListening();
+	}
+
+	/**
+	 * Checks whether a given DOM event should be ignored (should not be turned into a synthetic view document event).
+	 *
+	 * Currently, an event will be ignored only if its target or any of its ancestors has the `data-cke-ignore-events` attribute.
+	 * This attribute can be used inside the structures generated by
+	 * {@link module:engine/view/downcastwriter~DowncastWriter#createUIElement `DowncastWriter#createUIElement()`} to ignore events
+	 * fired within a UI that should be excluded from CKEditor 5's realms.
+	 *
+	 * @param {Node} domTarget The DOM event target to check (usually an element, sometimes a text node and
+	 * potentially sometimes a document, too).
+	 * @returns {Boolean} Whether this event should be ignored by the observer.
+	 */
+	checkShouldIgnoreEventFromTarget( domTarget ) {
+		if ( domTarget && domTarget.nodeType === 3 ) {
+			domTarget = domTarget.parentNode;
+		}
+
+		if ( !domTarget || domTarget.nodeType !== 1 ) {
+			return false;
+		}
+
+		return domTarget.matches( '[data-cke-ignore-events], [data-cke-ignore-events] *' );
+	}
+
+	/**
+	 * Starts observing the given root element.
+	 *
+	 * @method #observe
+	 * @param {HTMLElement} domElement
+	 * @param {String} name The name of the root element.
+	 */
+}
+
+mix( Observer, DomEmitterMixin );

package/src/view/observer/selectionobserver.js

@@ -0,0 +1,242 @@
+/**
+ * @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/selectionobserver
+ */
+
+/* global setInterval, clearInterval */
+
+import Observer from './observer';
+import MutationObserver from './mutationobserver';
+import { debounce } from 'lodash-es';
+
+/**
+ * Selection observer class observes selection changes in the document. If a selection changes on the document this
+ * observer checks if there are any mutations and if the DOM selection is different from the
+ * {@link module:engine/view/document~Document#selection view selection}. The selection observer fires
+ * {@link module:engine/view/document~Document#event:selectionChange} event only if a selection change was the only change in the document
+ * and the DOM selection is different then the view selection.
+ *
+ * Note that this observer is attached by the {@link module:engine/view/view~View} and is available by default.
+ *
+ * @see module:engine/view/observer/mutationobserver~MutationObserver
+ * @extends module:engine/view/observer/observer~Observer
+ */
+export default class SelectionObserver extends Observer {
+	constructor( view ) {
+		super( view );
+
+		/**
+		 * Instance of the mutation observer. Selection observer calls
+		 * {@link module:engine/view/observer/mutationobserver~MutationObserver#flush} to ensure that the mutations will be handled
+		 * before the {@link module:engine/view/document~Document#event:selectionChange} event is fired.
+		 *
+		 * @readonly
+		 * @member {module:engine/view/observer/mutationobserver~MutationObserver}
+		 * module:engine/view/observer/selectionobserver~SelectionObserver#mutationObserver
+		 */
+		this.mutationObserver = view.getObserver( MutationObserver );
+
+		/**
+		 * Reference to the view {@link module:engine/view/documentselection~DocumentSelection} object used to compare
+		 * new selection with it.
+		 *
+		 * @readonly
+		 * @member {module:engine/view/documentselection~DocumentSelection}
+		 * module:engine/view/observer/selectionobserver~SelectionObserver#selection
+		 */
+		this.selection = this.document.selection;
+
+		/* eslint-disable max-len */
+		/**
+		 * Reference to the {@link module:engine/view/view~View#domConverter}.
+		 *
+		 * @readonly
+		 * @member {module:engine/view/domconverter~DomConverter} module:engine/view/observer/selectionobserver~SelectionObserver#domConverter
+		 */
+		/* eslint-enable max-len */
+		this.domConverter = view.domConverter;
+
+		/**
+		 * A set of documents which have added `selectionchange` listener to avoid adding a listener twice to the same
+		 * document.
+		 *
+		 * @private
+		 * @member {WeakSet.<Document>} module:engine/view/observer/selectionobserver~SelectionObserver#_documents
+		 */
+		this._documents = new WeakSet();
+
+		/**
+		 * 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 );
+
+		this._clearInfiniteLoopInterval = setInterval( () => this._clearInfiniteLoop(), 1000 );
+
+		/**
+		 * Private property to check if the code does not enter infinite loop.
+		 *
+		 * @private
+		 * @member {Number} module:engine/view/observer/selectionobserver~SelectionObserver#_loopbackCounter
+		 */
+		this._loopbackCounter = 0;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	observe( domElement ) {
+		const domDocument = domElement.ownerDocument;
+
+		// Add listener once per each document.
+		if ( this._documents.has( domDocument ) ) {
+			return;
+		}
+
+		this.listenTo( domDocument, 'selectionchange', ( evt, domEvent ) => {
+			this._handleSelectionChange( domEvent, domDocument );
+		} );
+
+		this._documents.add( domDocument );
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	destroy() {
+		super.destroy();
+
+		clearInterval( this._clearInfiniteLoopInterval );
+		this._fireSelectionChangeDoneDebounced.cancel();
+	}
+
+	/**
+	 * Selection change listener. {@link module:engine/view/observer/mutationobserver~MutationObserver#flush Flush} mutations, check if
+	 * a selection changes and fires {@link module:engine/view/document~Document#event:selectionChange} event on every change
+	 * and {@link module:engine/view/document~Document#event:selectionChangeDone} when a selection stop changing.
+	 *
+	 * @private
+	 * @param {Event} domEvent DOM event.
+	 * @param {Document} domDocument DOM document.
+	 */
+	_handleSelectionChange( domEvent, domDocument ) {
+		if ( !this.isEnabled ) {
+			return;
+		}
+
+		const domSelection = domDocument.defaultView.getSelection();
+
+		if ( this.checkShouldIgnoreEventFromTarget( domSelection.anchorNode ) ) {
+			return;
+		}
+
+		// Ensure the mutation event will be before selection event on all browsers.
+		this.mutationObserver.flush();
+
+		// If there were mutations then the view will be re-rendered by the mutation observer and the selection
+		// will be updated, so the selections will equal and the event will not be fired, as expected.
+		const newViewSelection = this.domConverter.domSelectionToView( domSelection );
+
+		// Do not convert selection change if the new view selection has no ranges in it.
+		//
+		// It means that the DOM selection is in some way incorrect. Ranges that were in the DOM selection could not be
+		// converted to the view. This happens when the DOM selection was moved outside of the editable element.
+		if ( newViewSelection.rangeCount == 0 ) {
+			this.view.hasDomSelection = false;
+
+			return;
+		}
+
+		this.view.hasDomSelection = true;
+
+		if ( this.selection.isEqual( newViewSelection ) && this.domConverter.isDomSelectionCorrect( domSelection ) ) {
+			return;
+		}
+
+		// Ensure we are not in the infinite loop (#400).
+		// This counter is reset each second. 60 selection changes in 1 second is enough high number
+		// to be very difficult (impossible) to achieve using just keyboard keys (during normal editor use).
+		if ( ++this._loopbackCounter > 60 ) {
+			// Selection change observer detected an infinite rendering loop.
+			// Most probably you try to put the selection in the position which is not allowed
+			// by the browser and browser fixes it automatically what causes `selectionchange` event on
+			// which a loopback through a model tries to re-render the wrong selection and again.
+			//
+			// @if CK_DEBUG // console.warn( 'Selection change observer detected an infinite rendering loop.' );
+
+			return;
+		}
+
+		if ( this.selection.isSimilar( newViewSelection ) ) {
+			// If selection was equal and we are at this point of algorithm, it means that it was incorrect.
+			// Just re-render it, no need to fire any events, etc.
+			this.view.forceRender();
+		} else {
+			const data = {
+				oldSelection: this.selection,
+				newSelection: newViewSelection,
+				domSelection
+			};
+
+			// Prepare data for new selection and fire appropriate events.
+			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 );
+		}
+	}
+
+	/**
+	 * Clears `SelectionObserver` internal properties connected with preventing infinite loop.
+	 *
+	 * @protected
+	 */
+	_clearInfiniteLoop() {
+		this._loopbackCounter = 0;
+	}
+}
+
+/**
+ * Fired when a selection has changed. This event is fired only when the selection change was the only change that happened
+ * in the document, and the old selection is different then the new selection.
+ *
+ * Introduced by {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/selectionobserver~SelectionObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/selectionobserver~SelectionObserver
+ * @event module:engine/view/document~Document#event:selectionChange
+ * @param {Object} data
+ * @param {module:engine/view/documentselection~DocumentSelection} data.oldSelection Old View selection which is
+ * {@link module:engine/view/document~Document#selection}.
+ * @param {module:engine/view/selection~Selection} data.newSelection New View selection which is converted DOM selection.
+ * @param {Selection} data.domSelection Native DOM selection.
+ */
+
+/**
+ * Fired when selection stops changing.
+ *
+ * Introduced by {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/selectionobserver~SelectionObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/selectionobserver~SelectionObserver
+ * @event module:engine/view/document~Document#event:selectionChangeDone
+ * @param {Object} data
+ * @param {module:engine/view/documentselection~DocumentSelection} data.oldSelection Old View selection which is
+ * {@link module:engine/view/document~Document#selection}.
+ * @param {module:engine/view/selection~Selection} data.newSelection New View selection which is converted DOM selection.
+ * @param {Selection} data.domSelection Native DOM selection.
+ */