@ckeditor/ckeditor5-engine 30.0.0

package/src/view/observer/bubblingemittermixin.js

@@ -0,0 +1,307 @@
+/**
+ * @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/bubblingemittermixin
+ */
+
+import EventInfo from '@ckeditor/ckeditor5-utils/src/eventinfo';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
+import EmitterMixin from '@ckeditor/ckeditor5-utils/src/emittermixin';
+import toArray from '@ckeditor/ckeditor5-utils/src/toarray';
+
+import BubblingEventInfo from './bubblingeventinfo';
+
+const contextsSymbol = Symbol( 'bubbling contexts' );
+
+/**
+ * Bubbling emitter mixin for the view document as described in the
+ * {@link ~BubblingEmitter} interface.
+ *
+ * @mixin BubblingEmitterMixin
+ * @implements module:engine/view/observer/bubblingemittermixin~BubblingEmitter
+ */
+const BubblingEmitterMixin = {
+	/**
+	 * @inheritDoc
+	 */
+	fire( eventOrInfo, ...eventArgs ) {
+		try {
+			const eventInfo = eventOrInfo instanceof EventInfo ? eventOrInfo : new EventInfo( this, eventOrInfo );
+			const eventContexts = getBubblingContexts( this );
+
+			if ( !eventContexts.size ) {
+				return;
+			}
+
+			updateEventInfo( eventInfo, 'capturing', this );
+
+			// The capture phase of the event.
+			if ( fireListenerFor( eventContexts, '$capture', eventInfo, ...eventArgs ) ) {
+				return eventInfo.return;
+			}
+
+			const startRange = eventInfo.startRange || this.selection.getFirstRange();
+			const selectedElement = startRange ? startRange.getContainedElement() : null;
+			const isCustomContext = selectedElement ? Boolean( getCustomContext( eventContexts, selectedElement ) ) : false;
+
+			let node = selectedElement || getDeeperRangeParent( startRange );
+
+			updateEventInfo( eventInfo, 'atTarget', node );
+
+			// For the not yet bubbling event trigger for $text node if selection can be there and it's not a custom context selected.
+			if ( !isCustomContext ) {
+				if ( fireListenerFor( eventContexts, '$text', eventInfo, ...eventArgs ) ) {
+					return eventInfo.return;
+				}
+
+				updateEventInfo( eventInfo, 'bubbling', node );
+			}
+
+			while ( node ) {
+				// Root node handling.
+				if ( node.is( 'rootElement' ) ) {
+					if ( fireListenerFor( eventContexts, '$root', eventInfo, ...eventArgs ) ) {
+						return eventInfo.return;
+					}
+				}
+
+				// Element node handling.
+				else if ( node.is( 'element' ) ) {
+					if ( fireListenerFor( eventContexts, node.name, eventInfo, ...eventArgs ) ) {
+						return eventInfo.return;
+					}
+				}
+
+				// Check custom contexts (i.e., a widget).
+				if ( fireListenerFor( eventContexts, node, eventInfo, ...eventArgs ) ) {
+					return eventInfo.return;
+				}
+
+				node = node.parent;
+
+				updateEventInfo( eventInfo, 'bubbling', node );
+			}
+
+			updateEventInfo( eventInfo, 'bubbling', this );
+
+			// Document context.
+			fireListenerFor( eventContexts, '$document', eventInfo, ...eventArgs );
+
+			return eventInfo.return;
+		} catch ( err ) {
+			// @if CK_DEBUG // throw err;
+			/* istanbul ignore next */
+			CKEditorError.rethrowUnexpectedError( err, this );
+		}
+	},
+
+	/**
+	 * @inheritDoc
+	 */
+	_addEventListener( event, callback, options ) {
+		const contexts = toArray( options.context || '$document' );
+		const eventContexts = getBubblingContexts( this );
+
+		for ( const context of contexts ) {
+			let emitter = eventContexts.get( context );
+
+			if ( !emitter ) {
+				emitter = Object.create( EmitterMixin );
+				eventContexts.set( context, emitter );
+			}
+
+			this.listenTo( emitter, event, callback, options );
+		}
+	},
+
+	/**
+	 * @inheritDoc
+	 */
+	_removeEventListener( event, callback ) {
+		const eventContexts = getBubblingContexts( this );
+
+		for ( const emitter of eventContexts.values() ) {
+			this.stopListening( emitter, event, callback );
+		}
+	}
+};
+
+export default BubblingEmitterMixin;
+
+// Update the event info bubbling fields.
+//
+// @param {module:utils/eventinfo~EventInfo} eventInfo The event info object to update.
+// @param {'none'|'capturing'|'atTarget'|'bubbling'} eventPhase The current event phase.
+// @param {module:engine/view/document~Document|module:engine/view/node~Node} currentTarget The current bubbling target.
+function updateEventInfo( eventInfo, eventPhase, currentTarget ) {
+	if ( eventInfo instanceof BubblingEventInfo ) {
+		eventInfo._eventPhase = eventPhase;
+		eventInfo._currentTarget = currentTarget;
+	}
+}
+
+// Fires the listener for the specified context. Returns `true` if event was stopped.
+//
+// @private
+// @param {Map.<String|Function, module:utils/emittermixin~Emitter>} eventContexts
+// @param {String|module:engine/view/node~Node} context
+// @param {module:utils/eventinfo~EventInfo} eventInfo The `EventInfo` object.
+// @param {...*} [eventArgs] Additional arguments to be passed to the callbacks.
+// @returns {Boolean} True if event stop was called.
+function fireListenerFor( eventContexts, context, eventInfo, ...eventArgs ) {
+	const emitter = typeof context == 'string' ? eventContexts.get( context ) : getCustomContext( eventContexts, context );
+
+	if ( !emitter ) {
+		return false;
+	}
+
+	emitter.fire( eventInfo, ...eventArgs );
+
+	return eventInfo.stop.called;
+}
+
+// Returns an emitter for a specified view node.
+//
+// @private
+// @param {Map.<String|Function, module:utils/emittermixin~Emitter>} eventContexts
+// @param {module:engine/view/node~Node} node
+// @returns {module:utils/emittermixin~Emitter|null}
+function getCustomContext( eventContexts, node ) {
+	for ( const [ context, emitter ] of eventContexts ) {
+		if ( typeof context == 'function' && context( node ) ) {
+			return emitter;
+		}
+	}
+
+	return null;
+}
+
+// Returns bubbling contexts map for the source (emitter).
+function getBubblingContexts( source ) {
+	if ( !source[ contextsSymbol ] ) {
+		source[ contextsSymbol ] = new Map();
+	}
+
+	return source[ contextsSymbol ];
+}
+
+// Returns the deeper parent element for the range.
+function getDeeperRangeParent( range ) {
+	if ( !range ) {
+		return null;
+	}
+
+	const startParent = range.start.parent;
+	const endParent = range.end.parent;
+
+	const startPath = startParent.getPath();
+	const endPath = endParent.getPath();
+
+	return startPath.length > endPath.length ? startParent : endParent;
+}
+
+/**
+ * Bubbling emitter for the view document.
+ *
+ * Bubbling emitter is triggering events in the context of specified {@link module:engine/view/element~Element view element} name,
+ * predefined `'$text'`, `'$root'`, `'$document'` and `'$capture'` contexts, and context matchers provided as a function.
+ *
+ * Before bubbling starts, listeners for `'$capture'` context are triggered. Then the bubbling starts from the deeper selection
+ * position (by firing event on the `'$text'` context) and propagates the view document tree up to the `'$root'` and finally
+ * the listeners at `'$document'` context are fired (this is the default context).
+ *
+ * Examples:
+ *
+ *		// Listeners registered in the context of the view element names:
+ *		this.listenTo( viewDocument, 'enter', ( evt, data ) => {
+ *			// ...
+ *		}, { context: 'blockquote' } );
+ *
+ *		this.listenTo( viewDocument, 'enter', ( evt, data ) => {
+ *			// ...
+ *		}, { context: 'li' } );
+ *
+ *		// Listeners registered in the context of the '$text' and '$root' nodes.
+ *		this.listenTo( view.document, 'arrowKey', ( evt, data ) => {
+ *			// ...
+ *		}, { context: '$text', priority: 'high' } );
+ *
+ *		this.listenTo( view.document, 'arrowKey', ( evt, data ) => {
+ *			// ...
+ *		}, { context: '$root' } );
+ *
+ *		// Listeners registered in the context of custom callback function.
+ *		this.listenTo( view.document, 'arrowKey', ( evt, data ) => {
+ *			// ...
+ *		}, { context: isWidget } );
+ *
+ *		this.listenTo( view.document, 'arrowKey', ( evt, data ) => {
+ *			// ...
+ *		}, { context: isWidget, priority: 'high' } );
+ *
+ * Example flow for selection in text:
+ *
+ *		<blockquote><p>Foo[]bar</p></blockquote>
+ *
+ * Fired events on contexts:
+ * 1. `'$capture'`
+ * 2. `'$text'`
+ * 3. `'p'`
+ * 4. `'blockquote'`
+ * 5. `'$root'`
+ * 6. `'$document'`
+ *
+ * Example flow for selection on element (i.e., Widget):
+ *
+ *		<blockquote><p>Foo[<widget/>]bar</p></blockquote>
+ *
+ * Fired events on contexts:
+ * 1. `'$capture'`
+ * 2. *widget* (custom matcher)
+ * 3. `'p'`
+ * 4. `'blockquote'`
+ * 5. `'$root'`
+ * 6. `'$document'`
+ *
+ * There could be multiple listeners registered for the same context and at different priority levels:
+ *
+ *		<p>Foo[]bar</p>
+ *
+ * 1. `'$capture'` at priorities:
+ *    1. `'highest'`
+ *    2. `'high'`
+ *    3. `'normal'`
+ *    4. `'low'`
+ *    5. `'lowest'`
+ * 2. `'$text'` at priorities:
+ *    1. `'highest'`
+ *    2. `'high'`
+ *    3. `'normal'`
+ *    4. `'low'`
+ *    5. `'lowest'`
+ * 3. `'p'` at priorities:
+ *    1. `'highest'`
+ *    2. `'high'`
+ *    3. `'normal'`
+ *    4. `'low'`
+ *    5. `'lowest'`
+ * 4. `'$root'` at priorities:
+ *    1. `'highest'`
+ *    2. `'high'`
+ *    3. `'normal'`
+ *    4. `'low'`
+ *    5. `'lowest'`
+ * 5. `'$document'` at priorities:
+ *    1. `'highest'`
+ *    2. `'high'`
+ *    3. `'normal'`
+ *    4. `'low'`
+ *    5. `'lowest'`
+ *
+ * @interface BubblingEmitter
+ * @extends module:utils/emittermixin~Emitter
+ */

package/src/view/observer/bubblingeventinfo.js

@@ -0,0 +1,71 @@
+/**
+ * @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/bubblingeventinfo
+ */
+
+import EventInfo from '@ckeditor/ckeditor5-utils/src/eventinfo';
+
+/**
+ * The event object passed to bubbling event callbacks. It is used to provide information about the event as well as a tool to
+ * manipulate it.
+ *
+ * @extends module:utils/eventinfo~EventInfo
+ */
+export default class BubblingEventInfo extends EventInfo {
+	/**
+	 * @param {Object} source The emitter.
+	 * @param {String} name The event name.
+	 * @param {module:engine/view/range~Range} startRange The view range that the bubbling should start from.
+	 */
+	constructor( source, name, startRange ) {
+		super( source, name );
+
+		/**
+		 * The view range that the bubbling should start from.
+		 *
+		 * @readonly
+		 * @member {module:engine/view/range~Range}
+		 */
+		this.startRange = startRange;
+
+		/**
+		 * The current event phase.
+		 *
+		 * @protected
+		 * @member {'none'|'capturing'|'atTarget'|'bubbling'}
+		 */
+		this._eventPhase = 'none';
+
+		/**
+		 * The current bubbling target.
+		 *
+		 * @protected
+		 * @member {module:engine/view/document~Document|module:engine/view/node~Node|null}
+		 */
+		this._currentTarget = null;
+	}
+
+	/**
+	 * The current event phase.
+	 *
+	 * @readonly
+	 * @member {'none'|'capturing'|'atTarget'|'bubbling'}
+	 */
+	get eventPhase() {
+		return this._eventPhase;
+	}
+
+	/**
+	 * The current bubbling target.
+	 *
+	 * @readonly
+	 * @member {module:engine/view/document~Document|module:engine/view/node~Node|null}
+	 */
+	get currentTarget() {
+		return this._currentTarget;
+	}
+}

package/src/view/observer/clickobserver.js

@@ -0,0 +1,46 @@
+
+/**
+ * @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/clickobserver
+ */
+
+import DomEventObserver from './domeventobserver';
+
+/**
+ * {@link module:engine/view/document~Document#event:click Click} event 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 view controller}
+ * by a {@link module:engine/view/view~View#addObserver} method.
+ *
+ * @extends module:engine/view/observer/domeventobserver~DomEventObserver
+ */
+export default class ClickObserver extends DomEventObserver {
+	constructor( view ) {
+		super( view );
+
+		this.domEventType = 'click';
+	}
+
+	onDomEvent( domEvent ) {
+		this.fire( domEvent.type, domEvent );
+	}
+}
+
+/**
+ * Fired when one of the editables has been clicked.
+ *
+ * Introduced by {@link module:engine/view/observer/clickobserver~ClickObserver}.
+ *
+ * Note that this event is not available by default. To make it available
+ * {@link module:engine/view/observer/clickobserver~ClickObserver} needs to be added
+ * to {@link module:engine/view/view~View} by a {@link module:engine/view/view~View#addObserver} method.
+ *
+ * @see module:engine/view/observer/clickobserver~ClickObserver
+ * @event module:engine/view/document~Document#event:click
+ * @param {module:engine/view/observer/domeventdata~DomEventData} data Event data.
+ */

package/src/view/observer/compositionobserver.js

@@ -0,0 +1,79 @@
+/**
+ * @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/compositionobserver
+ */
+
+import DomEventObserver from './domeventobserver';
+
+/**
+ * {@link module:engine/view/document~Document#event:compositionstart Compositionstart},
+ * {@link module:engine/view/document~Document#event:compositionupdate compositionupdate} and
+ * {@link module:engine/view/document~Document#event:compositionend compositionend} events observer.
+ *
+ * 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 CompositionObserver extends DomEventObserver {
+	constructor( view ) {
+		super( view );
+
+		this.domEventType = [ 'compositionstart', 'compositionupdate', 'compositionend' ];
+		const document = this.document;
+
+		document.on( 'compositionstart', () => {
+			document.isComposing = true;
+		} );
+
+		document.on( 'compositionend', () => {
+			document.isComposing = false;
+		} );
+	}
+
+	onDomEvent( domEvent ) {
+		this.fire( domEvent.type, domEvent );
+	}
+}
+
+/**
+ * Fired when composition starts inside one of the editables.
+ *
+ * Introduced by {@link module:engine/view/observer/compositionobserver~CompositionObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/compositionobserver~CompositionObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/compositionobserver~CompositionObserver
+ * @event module:engine/view/document~Document#event:compositionstart
+ * @param {module:engine/view/observer/domeventdata~DomEventData} data Event data.
+ */
+
+/**
+ * Fired when composition is updated inside one of the editables.
+ *
+ * Introduced by {@link module:engine/view/observer/compositionobserver~CompositionObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/compositionobserver~CompositionObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/compositionobserver~CompositionObserver
+ * @event module:engine/view/document~Document#event:compositionupdate
+ * @param {module:engine/view/observer/domeventdata~DomEventData} data Event data.
+ */
+
+/**
+ * Fired when composition ends inside one of the editables.
+ *
+ * Introduced by {@link module:engine/view/observer/compositionobserver~CompositionObserver}.
+ *
+ * Note that because {@link module:engine/view/observer/compositionobserver~CompositionObserver} is attached by the
+ * {@link module:engine/view/view~View} this event is available by default.
+ *
+ * @see module:engine/view/observer/compositionobserver~CompositionObserver
+ * @event module:engine/view/document~Document#event:compositionend
+ * @param {module:engine/view/observer/domeventdata~DomEventData} data Event data.
+ */

package/src/view/observer/domeventdata.js

@@ -0,0 +1,82 @@
+/**
+ * @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/domeventdata
+ */
+
+import { extend } from 'lodash-es';
+
+/**
+ * Information about a DOM event in context of the {@link module:engine/view/document~Document}.
+ * It wraps the native event, which usually should not be used as the wrapper contains
+ * additional data (like key code for keyboard events).
+ */
+export default class DomEventData {
+	/**
+	 * @param {module:engine/view/view~View} view The instance of the view controller.
+	 * @param {Event} domEvent The DOM event.
+	 * @param {Object} [additionalData] Additional properties that the instance should contain.
+	 */
+	constructor( view, domEvent, additionalData ) {
+		/**
+		 * Instance of the view controller.
+		 *
+		 * @readonly
+		 * @member {module:engine/view/view~View} module:engine/view/observer/observer~Observer.DomEvent#view
+		 */
+		this.view = view;
+
+		/**
+		 * The instance of the document.
+		 *
+		 * @readonly
+		 * @member {module:engine/view/document~Document} module:engine/view/observer/observer~Observer.DomEvent#document
+		 */
+		this.document = view.document;
+
+		/**
+		 * The DOM event.
+		 *
+		 * @readonly
+		 * @member {Event} module:engine/view/observer/observer~Observer.DomEvent#domEvent
+		 */
+		this.domEvent = domEvent;
+
+		/**
+		 * The DOM target.
+		 *
+		 * @readonly
+		 * @member {HTMLElement} module:engine/view/observer/observer~Observer.DomEvent#target
+		 */
+		this.domTarget = domEvent.target;
+
+		extend( this, additionalData );
+	}
+
+	/**
+	 * The tree view element representing the target.
+	 *
+	 * @readonly
+	 * @type module:engine/view/element~Element
+	 */
+	get target() {
+		return this.view.domConverter.mapDomToView( this.domTarget );
+	}
+
+	/**
+	 * Prevents the native's event default action.
+	 */
+	preventDefault() {
+		this.domEvent.preventDefault();
+	}
+
+	/**
+	 * Stops native event propagation.
+	 */
+	stopPropagation() {
+		this.domEvent.stopPropagation();
+	}
+}

package/src/view/observer/domeventobserver.js

@@ -0,0 +1,99 @@
+/**
+ * @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/domeventobserver
+ */
+
+import Observer from './observer';
+import DomEventData from './domeventdata';
+
+/**
+ * Base class for DOM event observers. This class handles
+ * {@link module:engine/view/observer/observer~Observer#observe adding} listeners to DOM elements,
+ * {@link module:engine/view/observer/observer~Observer#disable disabling} and
+ * {@link module:engine/view/observer/observer~Observer#enable re-enabling} events.
+ * Child class needs to define
+ * {@link module:engine/view/observer/domeventobserver~DomEventObserver#domEventType DOM event type} and
+ * {@link module:engine/view/observer/domeventobserver~DomEventObserver#onDomEvent callback}.
+ *
+ * For instance:
+ *
+ *		class ClickObserver extends DomEventObserver {
+ *			// It can also be defined as a normal property in the constructor.
+ *			get domEventType() {
+ *				return 'click';
+ *			}
+ *
+ *			onDomEvent( domEvent ) {
+ *				this.fire( 'click', domEvent );
+ *			}
+ *		}
+ *
+ * @extends module:engine/view/observer/observer~Observer
+ */
+export default class DomEventObserver extends Observer {
+	/**
+	 * Type of the DOM event the observer should listen to. Array of types can be defined
+	 * if the observer should listen to multiple DOM events.
+	 *
+	 * @readonly
+	 * @member {String|Array.<String>} #domEventType
+	 */
+
+	/**
+	 * Callback which should be called when the DOM event occurred. Note that the callback will not be called if
+	 * observer {@link #isEnabled is not enabled}.
+	 *
+	 * @see #domEventType
+	 * @abstract
+	 * @method #onDomEvent
+	 */
+
+	/**
+	 * @inheritDoc
+	 */
+	constructor( view ) {
+		super( view );
+
+		/**
+		 * If set to `true` DOM events will be listened on the capturing phase.
+		 * Default value is `false`.
+		 *
+		 * @member {Boolean}
+		 */
+		this.useCapture = false;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	observe( domElement ) {
+		const types = typeof this.domEventType == 'string' ? [ this.domEventType ] : this.domEventType;
+
+		types.forEach( type => {
+			this.listenTo( domElement, type, ( eventInfo, domEvent ) => {
+				if ( this.isEnabled && !this.checkShouldIgnoreEventFromTarget( domEvent.target ) ) {
+					this.onDomEvent( domEvent );
+				}
+			}, { useCapture: this.useCapture } );
+		} );
+	}
+
+	/**
+	 * Calls `Document#fire()` if observer {@link #isEnabled is enabled}.
+	 *
+	 * @see module:utils/emittermixin~EmitterMixin#fire
+	 * @param {String} eventType The event type (name).
+	 * @param {Event} domEvent The DOM event.
+	 * @param {Object} [additionalData] The additional data which should extend the
+	 * {@link module:engine/view/observer/domeventdata~DomEventData event data} object.
+	 */
+	fire( eventType, domEvent, additionalData ) {
+		if ( this.isEnabled ) {
+			this.document.fire( eventType, new DomEventData( this.view, domEvent, additionalData ) );
+		}
+	}
+}