@ckeditor/ckeditor5-engine 30.0.0

package/src/view/elementdefinition.jsdoc

@@ -0,0 +1,59 @@
+/**
+ * @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/elementdefinition
+ */
+
+/**
+ * A plain object that describes a view element in a way that a concrete, exact view element could be created from that description.
+ *
+ *		const viewDefinition = {
+ *			name: 'h1',
+ *			classes: [ 'foo', 'bar' ]
+ *		};
+ *
+ * Above describes a view element:
+ *
+ *		<h1 class="foo bar"></h1>
+ *
+ * An example with styles and attributes:
+ *
+ *      const viewDefinition = {
+ *          name: 'span',
+ *          styles: {
+ *              'font-size': '12px',
+ *              'font-weight': 'bold'
+ *          },
+ *          attributes: {
+ *              'data-id': '123'
+ *          }
+ *      };
+ *
+ * Describes:
+ *
+ *      <span style="font-size:12px;font-weight:bold" data-id="123"></span>
+ *
+ * Elements without attributes can be given simply as a string:
+ *
+ *		const viewDefinition = 'p';
+ *
+ * Which will be treated as:
+ *
+ *		const viewDefinition = {
+ *			name: 'p'
+ *		};
+ *
+ * @typedef {String|Object} module:engine/view/elementdefinition~ElementDefinition
+ *
+ * @property {String} name View element name.
+ * @property {String|Array.<String>} [classes] Class name or array of class names to match. Each name can be
+ * provided in a form of string.
+ * @property {Object} [styles] Object with key-value pairs representing styles. Each object key represents style name.
+ * Value under that key must be a string.
+ * @property {Object} [attributes] Object with key-value pairs representing attributes. Each object key represents
+ * attribute name. Value under that key must be a string.
+ * @property {Number} [priority] Element's {@link module:engine/view/attributeelement~AttributeElement#priority priority}.
+ */

package/src/view/emptyelement.js

@@ -0,0 +1,119 @@
+/**
+ * @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/emptyelement
+ */
+
+import Element from './element';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import Node from './node';
+
+/**
+ * Empty element class. It is used to represent elements that cannot contain any child nodes (for example `<img>` elements).
+ *
+ * To create a new empty element use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createEmptyElement `downcastWriter#createEmptyElement()`} method.
+ *
+ * @extends module:engine/view/element~Element
+ */
+export default class EmptyElement extends Element {
+	/**
+	 * Creates new instance of EmptyElement.
+	 *
+	 * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-emptyelement-cannot-add` when third parameter is passed,
+	 * to inform that usage of EmptyElement is incorrect (adding child nodes to EmptyElement is forbidden).
+	 *
+	 * @see module:engine/view/downcastwriter~DowncastWriter#createEmptyElement
+	 * @protected
+	 * @param {module:engine/view/document~Document} document The document instance to which this element belongs.
+	 * @param {String} name Node name.
+	 * @param {Object|Iterable} [attrs] 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, attrs, children ) {
+		super( document, name, attrs, children );
+
+		// Override the default of the base class.
+		this._isAllowedInsideAttributeElement = true;
+
+		/**
+		 * Returns `null` because filler is not needed for EmptyElements.
+		 *
+		 * @method #getFillerOffset
+		 * @returns {null} Always returns null.
+		 */
+		this.getFillerOffset = getFillerOffset;
+	}
+
+	/**
+	 * Checks whether this object is of the given.
+	 *
+	 *		emptyElement.is( 'emptyElement' ); // -> true
+	 *		emptyElement.is( 'element' ); // -> true
+	 *		emptyElement.is( 'node' ); // -> true
+	 *		emptyElement.is( 'view:emptyElement' ); // -> true
+	 *		emptyElement.is( 'view:element' ); // -> true
+	 *		emptyElement.is( 'view:node' ); // -> true
+	 *
+	 *		emptyElement.is( 'model:element' ); // -> false
+	 *		emptyElement.is( 'documentFragment' ); // -> false
+	 *
+	 * Assuming that the object being checked is an empty element, you can also check its
+	 * {@link module:engine/view/emptyelement~EmptyElement#name name}:
+	 *
+	 *		emptyElement.is( 'element', 'img' ); // -> true if this is a img element
+	 *		emptyElement.is( 'emptyElement', 'img' ); // -> same as above
+	 *		text.is( 'element', 'img' ); -> 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 === 'emptyElement' || type === 'view:emptyElement' ||
+				// 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 === 'emptyElement' || type === 'view:emptyElement' ||
+				type === 'element' || type === 'view:element'
+			);
+		}
+	}
+
+	/**
+	 * Overrides {@link module:engine/view/element~Element#_insertChild} method.
+	 * Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError} `view-emptyelement-cannot-add` to prevent
+	 * adding any child nodes to EmptyElement.
+	 *
+	 * @protected
+	 */
+	_insertChild( index, nodes ) {
+		if ( nodes && ( nodes instanceof Node || Array.from( nodes ).length > 0 ) ) {
+			/**
+			 * Cannot add children to {@link module:engine/view/emptyelement~EmptyElement}.
+			 *
+			 * @error view-emptyelement-cannot-add
+			 */
+			throw new CKEditorError(
+				'view-emptyelement-cannot-add',
+				[ this, nodes ]
+			);
+		}
+	}
+}
+
+// Returns `null` because block filler is not needed for EmptyElements.
+//
+// @returns {null}
+function getFillerOffset() {
+	return null;
+}

package/src/view/filler.js

@@ -0,0 +1,161 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+import { keyCodes } from '@ckeditor/ckeditor5-utils/src/keyboard';
+import isText from '@ckeditor/ckeditor5-utils/src/dom/istext';
+
+/**
+ * Set of utilities related to handling block and inline fillers.
+ *
+ * Browsers do not allow to put caret in elements which does not have height. Because of it, we need to fill all
+ * empty elements which should be selectable with elements or characters called "fillers". Unfortunately there is no one
+ * universal filler, this is why two types are uses:
+ *
+ * * Block filler is an element which fill block elements, like `<p>`. CKEditor uses `<br>` as a block filler during the editing,
+ * as browsers do natively. So instead of an empty `<p>` there will be `<p><br></p>`. The advantage of block filler is that
+ * it is transparent for the selection, so when the caret is before the `<br>` and user presses right arrow he will be
+ * moved to the next paragraph, not after the `<br>`. The disadvantage is that it breaks a block, so it can not be used
+ * in the middle of a line of text. The {@link module:engine/view/filler~BR_FILLER `<br>` filler} can be replaced with any other
+ * character in the data output, for instance {@link module:engine/view/filler~NBSP_FILLER non-breaking space} or
+ * {@link module:engine/view/filler~MARKED_NBSP_FILLER marked non-breaking space}.
+ *
+ * * Inline filler is a filler which does not break a line of text, so it can be used inside the text, for instance in the empty
+ * `<b>` surrendered by text: `foo<b></b>bar`, if we want to put the caret there. CKEditor uses a sequence of the zero-width
+ * spaces as an {@link module:engine/view/filler~INLINE_FILLER inline filler} having the predetermined
+ * {@link module:engine/view/filler~INLINE_FILLER_LENGTH length}. A sequence is used, instead of a single character to
+ * avoid treating random zero-width spaces as the inline filler. Disadvantage of the inline filler is that it is not
+ * transparent for the selection. The arrow key moves the caret between zero-width spaces characters, so the additional
+ * code is needed to handle the caret.
+ *
+ * Both inline and block fillers are handled by the {@link module:engine/view/renderer~Renderer renderer} and are not present in the
+ * view.
+ *
+ * @module engine/view/filler
+ */
+
+/**
+ * Non-breaking space filler creator. This function creates the `&nbsp;` text node.
+ * It defines how the filler is created.
+ *
+ * @see module:engine/view/filler~MARKED_NBSP_FILLER
+ * @see module:engine/view/filler~BR_FILLER
+ * @function
+ */
+export const NBSP_FILLER = domDocument => domDocument.createTextNode( '\u00A0' );
+
+/**
+ * Marked non-breaking space filler creator. This function creates the `<span data-cke-filler="true">&nbsp;</span>` element.
+ * It defines how the filler is created.
+ *
+ * @see module:engine/view/filler~NBSP_FILLER
+ * @see module:engine/view/filler~BR_FILLER
+ * @function
+ */
+export const MARKED_NBSP_FILLER = domDocument => {
+	const span = domDocument.createElement( 'span' );
+	span.dataset.ckeFiller = true;
+	span.innerHTML = '\u00A0';
+
+	return span;
+};
+
+/**
+ * `<br>` filler creator. This function creates the `<br data-cke-filler="true">` element.
+ * It defines how the filler is created.
+ *
+ * @see module:engine/view/filler~NBSP_FILLER
+ * @see module:engine/view/filler~MARKED_NBSP_FILLER
+ * @function
+ */
+export const BR_FILLER = domDocument => {
+	const fillerBr = domDocument.createElement( 'br' );
+	fillerBr.dataset.ckeFiller = true;
+
+	return fillerBr;
+};
+
+/**
+ * Length of the {@link module:engine/view/filler~INLINE_FILLER INLINE_FILLER}.
+ */
+export const INLINE_FILLER_LENGTH = 7;
+
+/**
+ * Inline filler which is a sequence of the word joiners.
+ *
+ * @type {String}
+ */
+export const INLINE_FILLER = '\u2060'.repeat( INLINE_FILLER_LENGTH );
+
+/**
+ * Checks if the node is a text node which starts with the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
+ *
+ *		startsWithFiller( document.createTextNode( INLINE_FILLER ) ); // true
+ *		startsWithFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ); // true
+ *		startsWithFiller( document.createTextNode( 'foo' ) ); // false
+ *		startsWithFiller( document.createElement( 'p' ) ); // false
+ *
+ * @param {Node} domNode DOM node.
+ * @returns {Boolean} True if the text node starts with the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
+ */
+export function startsWithFiller( domNode ) {
+	return isText( domNode ) && ( domNode.data.substr( 0, INLINE_FILLER_LENGTH ) === INLINE_FILLER );
+}
+
+/**
+ * Checks if the text node contains only the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
+ *
+ *		isInlineFiller( document.createTextNode( INLINE_FILLER ) ); // true
+ *		isInlineFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ); // false
+ *
+ * @param {Text} domText DOM text node.
+ * @returns {Boolean} True if the text node contains only the {@link module:engine/view/filler~INLINE_FILLER inline filler}.
+ */
+export function isInlineFiller( domText ) {
+	return domText.data.length == INLINE_FILLER_LENGTH && startsWithFiller( domText );
+}
+
+/**
+ * Get string data from the text node, removing an {@link module:engine/view/filler~INLINE_FILLER inline filler} from it,
+ * if text node contains it.
+ *
+ *		getDataWithoutFiller( document.createTextNode( INLINE_FILLER + 'foo' ) ) == 'foo' // true
+ *		getDataWithoutFiller( document.createTextNode( 'foo' ) ) == 'foo' // true
+ *
+ * @param {Text} domText DOM text node, possible with inline filler.
+ * @returns {String} Data without filler.
+ */
+export function getDataWithoutFiller( domText ) {
+	if ( startsWithFiller( domText ) ) {
+		return domText.data.slice( INLINE_FILLER_LENGTH );
+	} else {
+		return domText.data;
+	}
+}
+
+/**
+ * Assign key observer which move cursor from the end of the inline filler to the beginning of it when
+ * the left arrow is pressed, so the filler does not break navigation.
+ *
+ * @param {module:engine/view/view~View} view View controller instance we should inject quirks handling on.
+ */
+export function injectQuirksHandling( view ) {
+	view.document.on( 'arrowKey', jumpOverInlineFiller, { priority: 'low' } );
+}
+
+// Move cursor from the end of the inline filler to the beginning of it when, so the filler does not break navigation.
+function jumpOverInlineFiller( evt, data ) {
+	if ( data.keyCode == keyCodes.arrowleft ) {
+		const domSelection = data.domTarget.ownerDocument.defaultView.getSelection();
+
+		if ( domSelection.rangeCount == 1 && domSelection.getRangeAt( 0 ).collapsed ) {
+			const domParent = domSelection.getRangeAt( 0 ).startContainer;
+			const domOffset = domSelection.getRangeAt( 0 ).startOffset;
+
+			if ( startsWithFiller( domParent ) && domOffset <= INLINE_FILLER_LENGTH ) {
+				domSelection.collapse( domParent, 0 );
+			}
+		}
+	}
+}

package/src/view/item.jsdoc

@@ -0,0 +1,14 @@
+/**
+ * @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/item
+ */
+
+/**
+ * Item is a {@link module:engine/view/node~Node Node} or {@link module:engine/view/textproxy~TextProxy TextProxy}.
+ *
+ * @typedef {module:engine/view/node~Node|module:engine/view/textproxy~TextProxy} module:engine/view/item~Item
+ */