@ckeditor/ckeditor5-engine 30.0.0

package/src/view/attributeelement.js

@@ -0,0 +1,274 @@
+/**
+ * @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/attributeelement
+ */
+
+import Element from './element';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
+// Default attribute priority.
+const DEFAULT_PRIORITY = 10;
+
+/**
+ * Attribute elements are used to represent formatting elements in the view (think – `<b>`, `<span style="font-size: 2em">`, etc.).
+ * Most often they are created when downcasting model text attributes.
+ *
+ * Editing engine does not define a fixed HTML DTD. This is why a feature developer needs to choose between various
+ * types (container element, {@link module:engine/view/attributeelement~AttributeElement attribute element},
+ * {@link module:engine/view/emptyelement~EmptyElement empty element}, etc) when developing a feature.
+ *
+ * To create a new attribute element instance use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement `DowncastWriter#createAttributeElement()`} method.
+ *
+ * **Note:** Attribute elements by default can wrap {@link module:engine/view/text~Text},
+ * {@link module:engine/view/emptyelement~EmptyElement}, {@link module:engine/view/uielement~UIElement},
+ * {@link module:engine/view/rawelement~RawElement} and other attribute elements with higher priority. Other elements while placed inside
+ * an attribute element will split it (or nest in case of an `AttributeElement`). This behavior can be modified by changing
+ * the `isAllowedInsideAttributeElement` option while creating
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createContainerElement},
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createEmptyElement},
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createUIElement} or
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createRawElement}.
+ *
+ * @extends module:engine/view/element~Element
+ */
+export default class AttributeElement extends Element {
+	/**
+	 * Creates an attribute element.
+	 *
+	 * @see module:engine/view/downcastwriter~DowncastWriter#createAttributeElement
+	 * @see module:engine/view/element~Element
+	 * @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 );
+
+		/**
+		 * Returns block {@link module:engine/view/filler filler} offset or `null` if block filler is not needed.
+		 *
+		 * @method #getFillerOffset
+		 * @returns {Number|null} Block filler offset or `null` if block filler is not needed.
+		 */
+		this.getFillerOffset = getFillerOffset;
+
+		/**
+		 * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
+		 *
+		 * @protected
+		 * @member {Number}
+		 */
+		this._priority = DEFAULT_PRIORITY;
+
+		/**
+		 * Element identifier. If set, it is used by {@link module:engine/view/element~Element#isSimilar},
+		 * and then two elements are considered similar if, and only if they have the same `_id`.
+		 *
+		 * @protected
+		 * @member {String|Number}
+		 */
+		this._id = null;
+
+		/**
+		 * Keeps all the attribute elements that have the same {@link module:engine/view/attributeelement~AttributeElement#id ids}
+		 * and still exist in the view tree.
+		 *
+		 * This property is managed by {@link module:engine/view/downcastwriter~DowncastWriter}.
+		 *
+		 * @protected
+		 * @member {Set.<module:engine/view/attributeelement~AttributeElement>|null}
+		 */
+		this._clonesGroup = null;
+	}
+
+	/**
+	 * Element priority. Decides in what order elements are wrapped by {@link module:engine/view/downcastwriter~DowncastWriter}.
+	 *
+	 * @readonly
+	 * @type {Number}
+	 */
+	get priority() {
+		return this._priority;
+	}
+
+	/**
+	 * Element identifier. If set, it is used by {@link module:engine/view/element~Element#isSimilar},
+	 * and then two elements are considered similar if, and only if they have the same `id`.
+	 *
+	 * @readonly
+	 * @type {String|Number}
+	 */
+	get id() {
+		return this._id;
+	}
+
+	/**
+	 * Returns all {@link module:engine/view/attributeelement~AttributeElement attribute elements} that has the
+	 * same {@link module:engine/view/attributeelement~AttributeElement#id id} and are in the view tree (were not removed).
+	 *
+	 * Note: If this element has been removed from the tree, returned set will not include it.
+	 *
+	 * Throws {@link module:utils/ckeditorerror~CKEditorError attribute-element-get-elements-with-same-id-no-id}
+	 * if this element has no `id`.
+	 *
+	 * @returns {Set.<module:engine/view/attributeelement~AttributeElement>} Set containing all the attribute elements
+	 * with the same `id` that were added and not removed from the view tree.
+	 */
+	getElementsWithSameId() {
+		if ( this.id === null ) {
+			/**
+			 * Cannot get elements with the same id for an attribute element without id.
+			 *
+			 * @error attribute-element-get-elements-with-same-id-no-id
+			 */
+			throw new CKEditorError(
+				'attribute-element-get-elements-with-same-id-no-id',
+				this
+			);
+		}
+
+		return new Set( this._clonesGroup );
+	}
+
+	/**
+	 * Checks whether this object is of the given.
+	 *
+	 *		attributeElement.is( 'attributeElement' ); // -> true
+	 *		attributeElement.is( 'element' ); // -> true
+	 *		attributeElement.is( 'node' ); // -> true
+	 *		attributeElement.is( 'view:attributeElement' ); // -> true
+	 *		attributeElement.is( 'view:element' ); // -> true
+	 *		attributeElement.is( 'view:node' ); // -> true
+	 *
+	 *		attributeElement.is( 'model:element' ); // -> false
+	 *		attributeElement.is( 'documentFragment' ); // -> false
+	 *
+	 * Assuming that the object being checked is an attribute element, you can also check its
+	 * {@link module:engine/view/attributeelement~AttributeElement#name name}:
+	 *
+	 *		attributeElement.is( 'element', 'b' ); // -> true if this is a bold element
+	 *		attributeElement.is( 'attributeElement', 'b' ); // -> same as above
+	 *		text.is( 'element', 'b' ); -> 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 === 'attributeElement' || type === 'view:attributeElement' ||
+				// 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 === 'attributeElement' || type === 'view:attributeElement' ||
+				// From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+				type === 'element' || type === 'view:element'
+			);
+		}
+	}
+
+	/**
+	 * Checks if this element is similar to other element.
+	 *
+	 * If none of elements has set {@link module:engine/view/attributeelement~AttributeElement#id}, then both elements
+	 * should have the same name, attributes and priority to be considered as similar. Two similar elements can contain
+	 * different set of children nodes.
+	 *
+	 * If at least one element has {@link module:engine/view/attributeelement~AttributeElement#id} set, then both
+	 * elements have to have the same {@link module:engine/view/attributeelement~AttributeElement#id} value to be
+	 * considered similar.
+	 *
+	 * Similarity is important for {@link module:engine/view/downcastwriter~DowncastWriter}. For example:
+	 *
+	 * * two following similar elements can be merged together into one, longer element,
+	 * * {@link module:engine/view/downcastwriter~DowncastWriter#unwrap} checks similarity of passed element and processed element to
+	 * decide whether processed element should be unwrapped,
+	 * * etc.
+	 *
+	 * @param {module:engine/view/element~Element} otherElement
+	 * @returns {Boolean}
+	 */
+	isSimilar( otherElement ) {
+		// If any element has an `id` set, just compare the ids.
+		if ( this.id !== null || otherElement.id !== null ) {
+			return this.id === otherElement.id;
+		}
+
+		return super.isSimilar( otherElement ) && this.priority == otherElement.priority;
+	}
+
+	/**
+	 * Clones provided element with priority.
+	 *
+	 * @protected
+	 * @param {Boolean} deep If set to `true` clones element and all its children recursively. When set to `false`,
+	 * element will be cloned without any children.
+	 * @returns {module:engine/view/attributeelement~AttributeElement} Clone of this element.
+	 */
+	_clone( deep ) {
+		const cloned = super._clone( deep );
+
+		// Clone priority too.
+		cloned._priority = this._priority;
+
+		// And id too.
+		cloned._id = this._id;
+
+		return cloned;
+	}
+}
+
+/**
+ * Default attribute priority.
+ *
+ * @member {Number} module:engine/view/attributeelement~AttributeElement.DEFAULT_PRIORITY
+ */
+AttributeElement.DEFAULT_PRIORITY = DEFAULT_PRIORITY;
+
+// Returns block {@link module:engine/view/filler~Filler filler} offset or `null` if block filler is not needed.
+//
+// @returns {Number|null} Block filler offset or `null` if block filler is not needed.
+function getFillerOffset() {
+	// <b>foo</b> does not need filler.
+	if ( nonUiChildrenCount( this ) ) {
+		return null;
+	}
+
+	let element = this.parent;
+
+	// <p><b></b></p> needs filler -> <p><b><br></b></p>
+	while ( element && element.is( 'attributeElement' ) ) {
+		if ( nonUiChildrenCount( element ) > 1 ) {
+			return null;
+		}
+
+		element = element.parent;
+	}
+
+	if ( !element || nonUiChildrenCount( element ) > 1 ) {
+		return null;
+	}
+
+	// Render block filler at the end of element (after all ui elements).
+	return this.childCount;
+}
+
+// Returns total count of children that are not {@link module:engine/view/uielement~UIElement UIElements}.
+//
+// @param {module:engine/view/element~Element} element
+// @returns {Number}
+function nonUiChildrenCount( element ) {
+	return Array.from( element.getChildren() ).filter( element => !element.is( 'uiElement' ) ).length;
+}

package/src/view/containerelement.js

@@ -0,0 +1,123 @@
+/**
+ * @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/containerelement
+ */
+
+import Element from './element';
+
+/**
+ * Containers are elements which define document structure. They define boundaries for
+ * {@link module:engine/view/attributeelement~AttributeElement attributes}. They are mostly used for block elements like `<p>` or `<div>`.
+ *
+ * Editing engine does not define a fixed HTML DTD. This is why a feature developer needs to choose between various
+ * types (container element, {@link module:engine/view/attributeelement~AttributeElement attribute element},
+ * {@link module:engine/view/emptyelement~EmptyElement empty element}, etc) when developing a feature.
+ *
+ * The container element should be your default choice when writing a converter, unless:
+ *
+ * * this element represents a model text attribute (then use {@link module:engine/view/attributeelement~AttributeElement}),
+ * * this is an empty element like `<img>` (then use {@link module:engine/view/emptyelement~EmptyElement}),
+ * * this is a root element,
+ * * this is a nested editable element (then use  {@link module:engine/view/editableelement~EditableElement}).
+ *
+ * To create a new container element instance use the
+ * {@link module:engine/view/downcastwriter~DowncastWriter#createContainerElement `DowncastWriter#createContainerElement()`}
+ * method.
+ *
+ * @extends module:engine/view/element~Element
+ */
+export default class ContainerElement extends Element {
+	/**
+	 * Creates a container element.
+	 *
+	 * @see module:engine/view/downcastwriter~DowncastWriter#createContainerElement
+	 * @see module:engine/view/element~Element
+	 * @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 );
+
+		/**
+		 * Returns block {@link module:engine/view/filler filler} offset or `null` if block filler is not needed.
+		 *
+		 * @method #getFillerOffset
+		 * @returns {Number|null} Block filler offset or `null` if block filler is not needed.
+		 */
+		this.getFillerOffset = getFillerOffset;
+	}
+
+	/**
+	 * Checks whether this object is of the given.
+	 *
+	 *		containerElement.is( 'containerElement' ); // -> true
+	 *		containerElement.is( 'element' ); // -> true
+	 *		containerElement.is( 'node' ); // -> true
+	 *		containerElement.is( 'view:containerElement' ); // -> true
+	 *		containerElement.is( 'view:element' ); // -> true
+	 *		containerElement.is( 'view:node' ); // -> true
+	 *
+	 *		containerElement.is( 'model:element' ); // -> false
+	 *		containerElement.is( 'documentFragment' ); // -> false
+	 *
+	 * Assuming that the object being checked is a container element, you can also check its
+	 * {@link module:engine/view/containerelement~ContainerElement#name name}:
+	 *
+	 *		containerElement.is( 'element', 'div' ); // -> true if this is a div container element
+	 *		containerElement.is( 'contaienrElement', 'div' ); // -> same as above
+	 *		text.is( 'element', 'div' ); -> 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 === 'containerElement' || type === 'view:containerElement' ||
+				// 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 === 'containerElement' || type === 'view:containerElement' ||
+				// From super.is(). This is highly utilised method and cannot call super. See ckeditor/ckeditor5#6529.
+				type === 'element' || type === 'view:element'
+			);
+		}
+	}
+}
+
+/**
+ * Returns block {@link module:engine/view/filler filler} offset or `null` if block filler is not needed.
+ *
+ * @returns {Number|null} Block filler offset or `null` if block filler is not needed.
+ */
+export function getFillerOffset() {
+	const children = [ ...this.getChildren() ];
+	const lastChild = children[ this.childCount - 1 ];
+
+	// Block filler is required after a `<br>` if it's the last element in its container. See #1422.
+	if ( lastChild && lastChild.is( 'element', 'br' ) ) {
+		return this.childCount;
+	}
+
+	for ( const child of children ) {
+		// If there's any non-UI element – don't render the bogus.
+		if ( !child.is( 'uiElement' ) ) {
+			return null;
+		}
+	}
+
+	// If there are only UI elements – render the bogus at the end of the element.
+	return this.childCount;
+}

package/src/view/document.js

@@ -0,0 +1,221 @@
+/**
+ * @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/document
+ */
+
+import DocumentSelection from './documentselection';
+import Collection from '@ckeditor/ckeditor5-utils/src/collection';
+import mix from '@ckeditor/ckeditor5-utils/src/mix';
+import BubblingEmitterMixin from './observer/bubblingemittermixin';
+import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
+
+// @if CK_DEBUG_ENGINE // const { logDocument } = require( '../dev-utils/utils' );
+
+/**
+ * Document class creates an abstract layer over the content editable area, contains a tree of view elements and
+ * {@link module:engine/view/documentselection~DocumentSelection view selection} associated with this document.
+ *
+ * @mixes module:engine/view/observer/bubblingemittermixin~BubblingEmitterMixin
+ * @mixes module:utils/observablemixin~ObservableMixin
+ */
+export default class Document {
+	/**
+	 * Creates a Document instance.
+	 *
+	 * @param {module:engine/view/stylesmap~StylesProcessor} stylesProcessor The styles processor instance.
+	 */
+	constructor( stylesProcessor ) {
+		/**
+		 * Selection done on this document.
+		 *
+		 * @readonly
+		 * @member {module:engine/view/documentselection~DocumentSelection} module:engine/view/document~Document#selection
+		 */
+		this.selection = new DocumentSelection();
+
+		/**
+		 * Roots of the view tree. Collection of the {@link module:engine/view/element~Element view elements}.
+		 *
+		 * View roots are created as a result of binding between {@link module:engine/view/document~Document#roots} and
+		 * {@link module:engine/model/document~Document#roots} and this is handled by
+		 * {@link module:engine/controller/editingcontroller~EditingController}, so to create view root we need to create
+		 * model root using {@link module:engine/model/document~Document#createRoot}.
+		 *
+		 * @readonly
+		 * @member {module:utils/collection~Collection} module:engine/view/document~Document#roots
+		 */
+		this.roots = new Collection( { idProperty: 'rootName' } );
+
+		/**
+		 * The styles processor instance used by this document when normalizing styles.
+		 *
+		 * @readonly
+		 * @member {module:engine/view/stylesmap~StylesProcessor}
+		 */
+		this.stylesProcessor = stylesProcessor;
+
+		/**
+		 * Defines whether document is in read-only mode.
+		 *
+		 * When document is read-ony then all roots are read-only as well and caret placed inside this root is hidden.
+		 *
+		 * @observable
+		 * @member {Boolean} #isReadOnly
+		 */
+		this.set( 'isReadOnly', false );
+
+		/**
+		 * True if document is focused.
+		 *
+		 * This property is updated by the {@link module:engine/view/observer/focusobserver~FocusObserver}.
+		 * If the {@link module:engine/view/observer/focusobserver~FocusObserver} is disabled this property will not change.
+		 *
+		 * @readonly
+		 * @observable
+		 * @member {Boolean} module:engine/view/document~Document#isFocused
+		 */
+		this.set( 'isFocused', false );
+
+		/**
+		 * True if composition is in progress inside the document.
+		 *
+		 * This property is updated by the {@link module:engine/view/observer/compositionobserver~CompositionObserver}.
+		 * If the {@link module:engine/view/observer/compositionobserver~CompositionObserver} is disabled this property will not change.
+		 *
+		 * @readonly
+		 * @observable
+		 * @member {Boolean} module:engine/view/document~Document#isComposing
+		 */
+		this.set( 'isComposing', false );
+
+		/**
+		 * Post-fixer callbacks registered to the view document.
+		 *
+		 * @private
+		 * @member {Set}
+		 */
+		this._postFixers = new Set();
+	}
+
+	/**
+	 * Gets a {@link module:engine/view/document~Document#roots view root element} with the specified name. If the name is not
+	 * specific "main" root is returned.
+	 *
+	 * @param {String} [name='main'] Name of the root.
+	 * @returns {module:engine/view/rooteditableelement~RootEditableElement|null} The view root element with the specified name
+	 * or null when there is no root of given name.
+	 */
+	getRoot( name = 'main' ) {
+		return this.roots.get( name );
+	}
+
+	/**
+	 * Allows registering post-fixer callbacks. A post-fixers mechanism allows to update the view tree just before it is rendered
+	 * to the DOM.
+	 *
+	 * Post-fixers are executed right after all changes from the outermost change block were applied but
+	 * before the {@link module:engine/view/view~View#event:render render event} is fired. If a post-fixer callback made
+	 * a change, it should return `true`. When this happens, all post-fixers are fired again to check if something else should
+	 * not be fixed in the new document tree state.
+	 *
+	 * View post-fixers are useful when you want to apply some fixes whenever the view structure changes. Keep in mind that
+	 * changes executed in a view post-fixer should not break model-view mapping.
+	 *
+	 * The types of changes which should be safe:
+	 *
+	 * * adding or removing attribute from elements,
+	 * * changes inside of {@link module:engine/view/uielement~UIElement UI elements},
+	 * * {@link module:engine/model/differ~Differ#refreshItem marking some of the model elements to be re-converted}.
+	 *
+	 * Try to avoid changes which touch view structure:
+	 *
+	 * * you should not add or remove nor wrap or unwrap any view elements,
+	 * * you should not change the editor data model in a view post-fixer.
+	 *
+	 * As a parameter, a post-fixer callback receives a {@link module:engine/view/downcastwriter~DowncastWriter downcast writer}.
+	 *
+	 * Typically, a post-fixer will look like this:
+	 *
+	 *		editor.editing.view.document.registerPostFixer( writer => {
+	 *			if ( checkSomeCondition() ) {
+	 *				writer.doSomething();
+	 *
+	 *				// Let other post-fixers know that something changed.
+	 *				return true;
+	 *			}
+	 *		} );
+	 *
+	 * Note that nothing happens right after you register a post-fixer (e.g. execute such a code in the console).
+	 * That is because adding a post-fixer does not execute it.
+	 * The post-fixer will be executed as soon as any change in the document needs to cause its rendering.
+	 * If you want to re-render the editor's view after registering the post-fixer then you should do it manually by calling
+	 * {@link module:engine/view/view~View#forceRender `view.forceRender()`}.
+	 *
+	 * If you need to register a callback which is executed when DOM elements are already updated,
+	 * use {@link module:engine/view/view~View#event:render render event}.
+	 *
+	 * @param {Function} postFixer
+	 */
+	registerPostFixer( postFixer ) {
+		this._postFixers.add( postFixer );
+	}
+
+	/**
+	 * Destroys this instance. Makes sure that all observers are destroyed and listeners removed.
+	 */
+	destroy() {
+		this.roots.map( root => root.destroy() );
+		this.stopListening();
+	}
+
+	/**
+	 * Performs post-fixer loops. Executes post-fixer callbacks as long as none of them has done any changes to the model.
+	 *
+	 * @protected
+	 * @param {module:engine/view/downcastwriter~DowncastWriter} writer
+	 */
+	_callPostFixers( writer ) {
+		let wasFixed = false;
+
+		do {
+			for ( const callback of this._postFixers ) {
+				wasFixed = callback( writer );
+
+				if ( wasFixed ) {
+					break;
+				}
+			}
+		} while ( wasFixed );
+	}
+
+	/**
+	 * Event fired whenever document content layout changes. It is fired whenever content is
+	 * {@link module:engine/view/view~View#event:render rendered}, but should be also fired by observers in case of
+	 * other actions which may change layout, for instance when image loads.
+	 *
+	 * @event layoutChanged
+	 */
+
+	// @if CK_DEBUG_ENGINE // log( version ) {
+	// @if CK_DEBUG_ENGINE //	logDocument( this, version );
+	// @if CK_DEBUG_ENGINE // }
+}
+
+mix( Document, BubblingEmitterMixin );
+mix( Document, ObservableMixin );
+
+/**
+ * Enum representing type of the change.
+ *
+ * Possible values:
+ *
+ * * `children` - for child list changes,
+ * * `attributes` - for element attributes changes,
+ * * `text` - for text nodes changes.
+ *
+ * @typedef {String} module:engine/view/document~ChangeType
+ */