@ckeditor/ckeditor5-engine 34.2.0 → 35.1.0

package/src/view/typecheckable.js

@@ -0,0 +1,19 @@
+/**
+ * @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 engine/view/typecheckable
+ */
+export default class TypeCheckable {
+    /* istanbul ignore next */
+    is() {
+        // There are a lot of overloads above.
+        // Overriding method in derived classes remove them and only `is( type: string ): boolean` is visible which we don't want.
+        // One option would be to copy them all to all classes, but that's ugly.
+        // It's best when TypeScript compiler doesn't see those overloads, except the one in the top base class.
+        // To overload a method, but not let the compiler see it, do after class definition:
+        // `MyClass.prototype.is = function( type: string ) {...}`
+        throw new Error('is() method is abstract');
+    }
+}

package/src/view/uielement.js

@@ -2,16 +2,13 @@
  * @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 engine/view/uielement
  */
-
 import Element from './element';
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 import Node from './node';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 import { keyCodes } from '@ckeditor/ckeditor5-utils/src/keyboard';
-
 /**
  * UI element class. It should be used to represent editing UI which needs to be injected into the editing view
  * If possible, you should keep your UI outside the editing view. However, if that is not possible,
@@ -33,135 +30,127 @@ import { keyCodes } from '@ckeditor/ckeditor5-utils/src/keyboard';
  * @extends module:engine/view/element~Element
  */
 export default class UIElement extends Element {
-	/**
-	 * Creates new instance of UIElement.
-	 *
-	 * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-uielement-cannot-add` when third parameter is passed,
-	 * to inform that usage of UIElement is incorrect (adding child nodes to UIElement is forbidden).
-	 *
-	 * @see module:engine/view/downcastwriter~DowncastWriter#createUIElement
-	 * @protected
-	 * @param {module:engine/view/document~Document} document The document instance to which this element belongs.
-	 * @param {String} name Node name.
-	 * @param {Object|Iterable} [attributes] Collection of attributes.
-	 * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
-	 * A list of nodes to be inserted into created element.
-	 */
-	constructor( document, name, attributes, children ) {
-		super( document, name, attributes, children );
-
-		/**
-		 * Returns `null` because filler is not needed for UIElements.
-		 *
-		 * @method #getFillerOffset
-		 * @returns {null} Always returns null.
-		 */
-		this.getFillerOffset = getFillerOffset;
-	}
-
-	/**
-	 * Checks whether this object is of the given.
-	 *
-	 *		uiElement.is( 'uiElement' ); // -> true
-	 *		uiElement.is( 'element' ); // -> true
-	 *		uiElement.is( 'node' ); // -> true
-	 *		uiElement.is( 'view:uiElement' ); // -> true
-	 *		uiElement.is( 'view:element' ); // -> true
-	 *		uiElement.is( 'view:node' ); // -> true
-	 *
-	 *		uiElement.is( 'model:element' ); // -> false
-	 *		uiElement.is( 'documentFragment' ); // -> false
-	 *
-	 * Assuming that the object being checked is an ui element, you can also check its
-	 * {@link module:engine/view/uielement~UIElement#name name}:
-	 *
-	 *		uiElement.is( 'element', 'span' ); // -> true if this is a span ui element
-	 *		uiElement.is( 'uiElement', 'span' ); // -> same as above
-	 *		text.is( 'element', 'span' ); -> false
-	 *
-	 * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
-	 *
-	 * @param {String} type Type to check.
-	 * @param {String} [name] Element name.
-	 * @returns {Boolean}
-	 */
-	is( type, name = null ) {
-		if ( !name ) {
-			return type === 'uiElement' || type === 'view:uiElement' ||
-				// From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
-				type === 'element' || type === 'view:element' ||
-				type === 'node' || type === 'view:node';
-		} else {
-			return name === this.name && (
-				type === 'uiElement' || type === 'view:uiElement' ||
-				type === 'element' || type === 'view:element'
-			);
-		}
-	}
-
-	/**
-	 * Overrides {@link module:engine/view/element~Element#_insertChild} method.
-	 * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-uielement-cannot-add` to prevent adding any child nodes
-	 * to UIElement.
-	 *
-	 * @protected
-	 */
-	_insertChild( index, nodes ) {
-		if ( nodes && ( nodes instanceof Node || Array.from( nodes ).length > 0 ) ) {
-			/**
-			 * Cannot add children to {@link module:engine/view/uielement~UIElement}.
-			 *
-			 * @error view-uielement-cannot-add
-			 */
-			throw new CKEditorError( 'view-uielement-cannot-add', this );
-		}
-	}
-
-	/**
-	 * Renders this {@link module:engine/view/uielement~UIElement} to DOM. This method is called by
-	 * {@link module:engine/view/domconverter~DomConverter}.
-	 * Do not use inheritance to create custom rendering method, replace `render()` method instead:
-	 *
-	 *		const myUIElement = downcastWriter.createUIElement( 'span' );
-	 *		myUIElement.render = function( domDocument, domConverter ) {
-	 *			const domElement = this.toDomElement( domDocument );
-	 *
-	 *			domConverter.setContentOf( domElement, '<b>this is ui element</b>' );
-	 *
-	 *			return domElement;
-	 *		};
-	 *
-	 * If changes in your UI element should trigger some editor UI update you should call
-	 * the {@link module:core/editor/editorui~EditorUI#update `editor.ui.update()`} method
-	 * after rendering your UI element.
-	 *
-	 * @param {Document} domDocument
-	 * @param {module:engine/view/domconverter~DomConverter} domConverter Instance of the DomConverter used to optimize the output.
-	 * @returns {HTMLElement}
-	 */
-	render( domDocument ) {
-		// Provide basic, default output.
-		return this.toDomElement( domDocument );
-	}
-
-	/**
-	 * Creates DOM element based on this view UIElement.
-	 * Note that each time this method is called new DOM element is created.
-	 *
-	 * @param {Document} domDocument
-	 * @returns {HTMLElement}
-	 */
-	toDomElement( domDocument ) {
-		const domElement = domDocument.createElement( this.name );
-
-		for ( const key of this.getAttributeKeys() ) {
-			domElement.setAttribute( key, this.getAttribute( key ) );
-		}
-
-		return domElement;
-	}
+    /**
+     * Creates new instance of UIElement.
+     *
+     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-uielement-cannot-add` when third parameter is passed,
+     * to inform that usage of UIElement is incorrect (adding child nodes to UIElement is forbidden).
+     *
+     * @see module:engine/view/downcastwriter~DowncastWriter#createUIElement
+     * @protected
+     * @param {module:engine/view/document~Document} document The document instance to which this element belongs.
+     * @param {String} name Node name.
+     * @param {Object|Iterable} [attributes] Collection of attributes.
+     * @param {module:engine/view/node~Node|Iterable.<module:engine/view/node~Node>} [children]
+     * A list of nodes to be inserted into created element.
+     */
+    constructor(...args) {
+        super(...args);
+        /**
+         * Returns `null` because filler is not needed for UIElements.
+         *
+         * @method #getFillerOffset
+         * @returns {null} Always returns null.
+         */
+        this.getFillerOffset = getFillerOffset;
+    }
+    /**
+     * Overrides {@link module:engine/view/element~Element#_insertChild} method.
+     * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-uielement-cannot-add` to prevent adding any child nodes
+     * to UIElement.
+     *
+     * @protected
+     */
+    _insertChild(index, items) {
+        if (items && (items instanceof Node || Array.from(items).length > 0)) {
+            /**
+             * Cannot add children to {@link module:engine/view/uielement~UIElement}.
+             *
+             * @error view-uielement-cannot-add
+             */
+            throw new CKEditorError('view-uielement-cannot-add', [this, items]);
+        }
+        return 0;
+    }
+    /**
+     * Renders this {@link module:engine/view/uielement~UIElement} to DOM. This method is called by
+     * {@link module:engine/view/domconverter~DomConverter}.
+     * Do not use inheritance to create custom rendering method, replace `render()` method instead:
+     *
+     *		const myUIElement = downcastWriter.createUIElement( 'span' );
+     *		myUIElement.render = function( domDocument, domConverter ) {
+     *			const domElement = this.toDomElement( domDocument );
+     *
+     *			domConverter.setContentOf( domElement, '<b>this is ui element</b>' );
+     *
+     *			return domElement;
+     *		};
+     *
+     * If changes in your UI element should trigger some editor UI update you should call
+     * the {@link module:core/editor/editorui~EditorUI#update `editor.ui.update()`} method
+     * after rendering your UI element.
+     *
+     * @param {Document} domDocument
+     * @param {module:engine/view/domconverter~DomConverter} domConverter Instance of the DomConverter used to optimize the output.
+     * @returns {HTMLElement}
+     */
+    render(domDocument, domConverter) {
+        // Provide basic, default output.
+        return this.toDomElement(domDocument);
+    }
+    /**
+     * Creates DOM element based on this view UIElement.
+     * Note that each time this method is called new DOM element is created.
+     *
+     * @param {Document} domDocument
+     * @returns {HTMLElement}
+     */
+    toDomElement(domDocument) {
+        const domElement = domDocument.createElement(this.name);
+        for (const key of this.getAttributeKeys()) {
+            domElement.setAttribute(key, this.getAttribute(key));
+        }
+        return domElement;
+    }
 }
-
+/**
+ * Checks whether this object is of the given.
+ *
+ *		uiElement.is( 'uiElement' ); // -> true
+ *		uiElement.is( 'element' ); // -> true
+ *		uiElement.is( 'node' ); // -> true
+ *		uiElement.is( 'view:uiElement' ); // -> true
+ *		uiElement.is( 'view:element' ); // -> true
+ *		uiElement.is( 'view:node' ); // -> true
+ *
+ *		uiElement.is( 'model:element' ); // -> false
+ *		uiElement.is( 'documentFragment' ); // -> false
+ *
+ * Assuming that the object being checked is an ui element, you can also check its
+ * {@link module:engine/view/uielement~UIElement#name name}:
+ *
+ *		uiElement.is( 'element', 'span' ); // -> true if this is a span ui element
+ *		uiElement.is( 'uiElement', 'span' ); // -> same as above
+ *		text.is( 'element', 'span' ); -> false
+ *
+ * {@link module:engine/view/node~Node#is Check the entire list of view objects} which implement the `is()` method.
+ *
+ * @param {String} type Type to check.
+ * @param {String} [name] Element name.
+ * @returns {Boolean}
+ */
+UIElement.prototype.is = function (type, name) {
+    if (!name) {
+        return type === 'uiElement' || type === 'view:uiElement' ||
+            // From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+            type === 'element' || type === 'view:element' ||
+            type === 'node' || type === 'view:node';
+    }
+    else {
+        return name === this.name && (type === 'uiElement' || type === 'view:uiElement' ||
+            type === 'element' || type === 'view:element');
+    }
+};
 /**
  * This function injects UI element handling to the given {@link module:engine/view/document~Document document}.
  *
@@ -171,68 +160,58 @@ export default class UIElement extends Element {
  *
  * @param {module:engine/view/view~View} view View controller to which the quirks handling will be injected.
  */
-export function injectUiElementHandling( view ) {
-	view.document.on( 'arrowKey', ( evt, data ) => jumpOverUiElement( evt, data, view.domConverter ), { priority: 'low' } );
+export function injectUiElementHandling(view) {
+    view.document.on('arrowKey', (evt, data) => jumpOverUiElement(evt, data, view.domConverter), { priority: 'low' });
 }
-
 // Returns `null` because block filler is not needed for UIElements.
 //
 // @returns {null}
 function getFillerOffset() {
-	return null;
+    return null;
 }
-
 // Selection cannot be placed in a `UIElement`. Whenever it is placed there, it is moved before it. This
 // causes a situation when it is impossible to jump over `UIElement` using right arrow key, because the selection
 // ends up in ui element (in DOM) and is moved back to the left. This handler fixes this situation.
-function jumpOverUiElement( evt, data, domConverter ) {
-	if ( data.keyCode == keyCodes.arrowright ) {
-		const domSelection = data.domTarget.ownerDocument.defaultView.getSelection();
-		const domSelectionCollapsed = domSelection.rangeCount == 1 && domSelection.getRangeAt( 0 ).collapsed;
-
-		// Jump over UI element if selection is collapsed or shift key is pressed. These are the cases when selection would extend.
-		if ( domSelectionCollapsed || data.shiftKey ) {
-			const domParent = domSelection.focusNode;
-			const domOffset = domSelection.focusOffset;
-
-			const viewPosition = domConverter.domPositionToView( domParent, domOffset );
-
-			// In case if dom element is not converted to view or is not mapped or something. Happens for example in some tests.
-			if ( viewPosition === null ) {
-				return;
-			}
-
-			// Skip all following ui elements.
-			let jumpedOverAnyUiElement = false;
-
-			const nextViewPosition = viewPosition.getLastMatchingPosition( value => {
-				if ( value.item.is( 'uiElement' ) ) {
-					// Remember that there was at least one ui element.
-					jumpedOverAnyUiElement = true;
-				}
-
-				// Jump over ui elements, jump over empty attribute elements, move up from inside of attribute element.
-				if ( value.item.is( 'uiElement' ) || value.item.is( 'attributeElement' ) ) {
-					return true;
-				}
-
-				// Don't jump over text or don't get out of container element.
-				return false;
-			} );
-
-			// If anything has been skipped, fix position.
-			// This `if` could be possibly omitted but maybe it is better not to mess with DOM selection if not needed.
-			if ( jumpedOverAnyUiElement ) {
-				const newDomPosition = domConverter.viewPositionToDom( nextViewPosition );
-
-				if ( domSelectionCollapsed ) {
-					// Selection was collapsed, so collapse it at further position.
-					domSelection.collapse( newDomPosition.parent, newDomPosition.offset );
-				} else {
-					// Selection was not collapse, so extend it instead of collapsing.
-					domSelection.extend( newDomPosition.parent, newDomPosition.offset );
-				}
-			}
-		}
-	}
+function jumpOverUiElement(evt, data, domConverter) {
+    if (data.keyCode == keyCodes.arrowright) {
+        const domSelection = data.domTarget.ownerDocument.defaultView.getSelection();
+        const domSelectionCollapsed = domSelection.rangeCount == 1 && domSelection.getRangeAt(0).collapsed;
+        // Jump over UI element if selection is collapsed or shift key is pressed. These are the cases when selection would extend.
+        if (domSelectionCollapsed || data.shiftKey) {
+            const domParent = domSelection.focusNode;
+            const domOffset = domSelection.focusOffset;
+            const viewPosition = domConverter.domPositionToView(domParent, domOffset);
+            // In case if dom element is not converted to view or is not mapped or something. Happens for example in some tests.
+            if (viewPosition === null) {
+                return;
+            }
+            // Skip all following ui elements.
+            let jumpedOverAnyUiElement = false;
+            const nextViewPosition = viewPosition.getLastMatchingPosition(value => {
+                if (value.item.is('uiElement')) {
+                    // Remember that there was at least one ui element.
+                    jumpedOverAnyUiElement = true;
+                }
+                // Jump over ui elements, jump over empty attribute elements, move up from inside of attribute element.
+                if (value.item.is('uiElement') || value.item.is('attributeElement')) {
+                    return true;
+                }
+                // Don't jump over text or don't get out of container element.
+                return false;
+            });
+            // If anything has been skipped, fix position.
+            // This `if` could be possibly omitted but maybe it is better not to mess with DOM selection if not needed.
+            if (jumpedOverAnyUiElement) {
+                const newDomPosition = domConverter.viewPositionToDom(nextViewPosition);
+                if (domSelectionCollapsed) {
+                    // Selection was collapsed, so collapse it at further position.
+                    domSelection.collapse(newDomPosition.parent, newDomPosition.offset);
+                }
+                else {
+                    // Selection was not collapse, so extend it instead of collapsing.
+                    domSelection.extend(newDomPosition.parent, newDomPosition.offset);
+                }
+            }
+        }
+    }
 }