@ckeditor/ckeditor5-engine 31.1.0 → 34.0.0

package/src/conversion/upcastdispatcher.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 
@@ -40,10 +40,7 @@ import mix from '@ckeditor/ckeditor5-utils/src/mix';
  * The third parameter of the callback is an instance of {@link module:engine/conversion/upcastdispatcher~UpcastConversionApi}
  * which provides additional tools for converters.
  *
- * You can read more about conversion in the following guides:
- *
- * * {@glink framework/guides/deep-dive/conversion/conversion-introduction Advanced conversion concepts — attributes}
- * * {@glink framework/guides/deep-dive/conversion/custom-element-conversion Custom element conversion}
+ * You can read more about conversion in the {@glink framework/guides/deep-dive/conversion/upcast Upcast conversion} guide.
  *
  * Examples of event-based converters:
  *
@@ -127,7 +124,7 @@ export default class UpcastDispatcher {
 		/**
 		 * The list of elements that were created during splitting.
 		 *
-		 * After the conversion process the list is cleared.
+		 * After the conversion process, the list is cleared.
 		 *
 		 * @private
 		 * @type {Map.<module:engine/model/element~Element,Array.<module:engine/model/element~Element>>}
@@ -154,6 +151,16 @@ export default class UpcastDispatcher {
 		 */
 		this._modelCursor = null;
 
+		/**
+		 * The list of elements that were created during splitting but should not get removed on conversion end even if they are empty.
+		 *
+		 * After the conversion process the list is cleared.
+		 *
+		 * @private
+		 * @type {Set.<module:engine/model/element~Element>}
+		 */
+		this._emptyElementsToKeep = new Set();
+
 		/**
 		 * An interface passed by the dispatcher to the event callbacks.
 		 *
@@ -170,6 +177,7 @@ export default class UpcastDispatcher {
 		// Advanced API - use only if custom position handling is needed.
 		this.conversionApi.splitToAllowedParent = this._splitToAllowedParent.bind( this );
 		this.conversionApi.getSplitParts = this._getSplitParts.bind( this );
+		this.conversionApi.keepEmptyElement = this._keepEmptyElement.bind( this );
 	}
 
 	/**
@@ -229,6 +237,7 @@ export default class UpcastDispatcher {
 		// Clear split elements & parents lists.
 		this._splitParts.clear();
 		this._cursorParents.clear();
+		this._emptyElementsToKeep.clear();
 
 		// Clear conversion API.
 		this.conversionApi.writer = null;
@@ -454,6 +463,15 @@ export default class UpcastDispatcher {
 		return parts;
 	}
 
+	/**
+	 * Mark an element that were created during splitting that it should not get removed on conversion end even if it's empty.
+	 *
+	 * @private
+	 */
+	_keepEmptyElement( element ) {
+		this._emptyElementsToKeep.add( element );
+	}
+
 	/**
 	 * Checks if there are any empty elements created while splitting and removes them.
 	 *
@@ -466,7 +484,7 @@ export default class UpcastDispatcher {
 		let anyRemoved = false;
 
 		for ( const element of this._splitParts.keys() ) {
-			if ( element.isEmpty ) {
+			if ( element.isEmpty && !this._emptyElementsToKeep.has( element ) ) {
 				this.conversionApi.writer.remove( element );
 				this._splitParts.delete( element );
 
@@ -760,6 +778,15 @@ function createContextTree( contextDefinition, writer ) {
  * @returns {Array.<module:engine/model/element~Element>}
  */
 
+/**
+ * Mark an element that was created during splitting that it should not get removed on conversion end even if it's empty.
+ *
+ * **Note:** This is an advanced method. For most cases you will not need to keep the split empty element.
+ *
+ * @method #keepEmptyElement
+ * @param {module:engine/model/element~Element} element
+ */
+
 /**
  * Stores information about what parts of the processed view item are still waiting to be handled. After a piece of view item
  * was converted, an appropriate consumable value should be

package/src/conversion/upcasthelpers.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 
@@ -12,7 +12,7 @@ import priorities from '@ckeditor/ckeditor5-utils/src/priorities';
 import { isParagraphable, wrapInParagraph } from '../model/utils/autoparagraphing';
 
 /**
- * Contains {@link module:engine/view/view view} to {@link module:engine/model/model model} converters for
+ * Contains the {@link module:engine/view/view view} to {@link module:engine/model/model model} converters for
  * {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher}.
  *
  * @module engine/conversion/upcasthelpers
@@ -21,6 +21,8 @@ import { isParagraphable, wrapInParagraph } from '../model/utils/autoparagraphin
 /**
  * Upcast conversion helper functions.
  *
+ * Learn more about {@glink framework/guides/deep-dive/conversion/upcast upcast helpers}.
+ *
  * @extends module:engine/conversion/conversionhelpers~ConversionHelpers
  */
 export default class UpcastHelpers extends ConversionHelpers {

package/src/conversion/viewconsumable.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dataprocessor/basichtmlwriter.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dataprocessor/dataprocessor.jsdoc

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dataprocessor/htmldataprocessor.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 
@@ -7,7 +7,7 @@
  * @module engine/dataprocessor/htmldataprocessor
  */
 
-/* globals document, DOMParser, Node */
+/* globals document, DOMParser */
 
 import BasicHtmlWriter from './basichtmlwriter';
 import DomConverter from '../view/domconverter';
@@ -114,37 +114,15 @@ export default class HtmlDataProcessor {
 	 * @returns {DocumentFragment}
 	 */
 	_toDom( data ) {
-		const document = this.domParser.parseFromString( data, 'text/html' );
-		const fragment = document.createDocumentFragment();
-
-		// The rules for parsing an HTML string can be read on https://html.spec.whatwg.org/multipage/parsing.html#parsing-main-inhtml.
-		//
-		// In short, parsing tokens in an HTML string starts with the so-called "initial" insertion mode. When a DOM parser is in this
-		// state and encounters a comment node, it inserts this comment node as the last child of the newly-created `HTMLDocument` object.
-		// The parser then proceeds to successive insertion modes during parsing subsequent tokens and appends in the `HTMLDocument` object
-		// other nodes (like <html>, <head>, <body>). This causes that the first leading comments from HTML string become the first nodes
-		// in the `HTMLDocument` object, but not in the <body> collection, because they are ultimately located before the <html> element.
-		//
-		// Therefore, so that such leading comments do not disappear, they all are moved from the `HTMLDocument` object to the document
-		// fragment, until the <html> element is encountered.
-		//
-		// See: https://github.com/ckeditor/ckeditor5/issues/9861.
-		let documentChildNode = document.firstChild;
-
-		while ( !documentChildNode.isSameNode( document.documentElement ) ) {
-			const node = documentChildNode;
-
-			documentChildNode = documentChildNode.nextSibling;
-
-			// It seems that `DOMParser#parseFromString()` adds only comment nodes directly to the `HTMLDocument` object, before the <html>
-			// node. The condition below is just to be sure we are moving only comment nodes.
-
-			/* istanbul ignore else */
-			if ( node.nodeType == Node.COMMENT_NODE ) {
-				fragment.appendChild( node );
-			}
+		// Wrap data with a <body> tag so leading non-layout nodes (like <script>, <style>, HTML comment)
+		// will be preserved in the body collection.
+		// Do it only for data that is not a full HTML document.
+		if ( !data.match( /<(?:html|body|head|meta)(?:\s[^>]*)?>/i ) ) {
+			data = `<body>${ data }</body>`;
 		}
 
+		const document = this.domParser.parseFromString( data, 'text/html' );
+		const fragment = document.createDocumentFragment();
 		const bodyChildNodes = document.body.childNodes;
 
 		while ( bodyChildNodes.length > 0 ) {

package/src/dataprocessor/htmlwriter.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dataprocessor/xmldataprocessor.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dev-utils/model.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 
@@ -31,6 +31,7 @@ import Mapper from '../conversion/mapper';
 import {
 	convertCollapsedSelection,
 	convertRangeSelection,
+	insertAttributesAndChildren,
 	insertElement,
 	insertText,
 	insertUIElement,
@@ -102,7 +103,7 @@ getData._stringify = stringify;
  * name will be used.
  * @param {Array<Object>} [options.selectionAttributes] A list of attributes which will be passed to the selection.
  * @param {Boolean} [options.lastRangeBackward=false] If set to `true`, the last range will be added as backward.
- * @param {String} [options.batchType='default'] Batch type used for inserting elements.
+ * @param {Object} [options.batchType] Batch type used for inserting elements. See {@link module:engine/model/batch~Batch#constructor}.
  * See {@link module:engine/model/batch~Batch#type}.
  */
 export function setData( model, data, options = {} ) {
@@ -128,7 +129,7 @@ export function setData( model, data, options = {} ) {
 		modelDocumentFragment = parsedResult;
 	}
 
-	if ( typeof options.batchType === 'string' ) {
+	if ( options.batchType !== undefined ) {
 		model.enqueueChange( options.batchType, writeToModel );
 	} else {
 		model.change( writeToModel );
@@ -233,6 +234,7 @@ export function stringify( node, selectionOrPositionOrRange = null, markers = nu
 	mapper.bindElements( node.root, viewRoot );
 
 	downcastDispatcher.on( 'insert:$text', insertText() );
+	downcastDispatcher.on( 'insert', insertAttributesAndChildren(), { priority: 'lowest' } );
 	downcastDispatcher.on( 'attribute', ( evt, data, conversionApi ) => {
 		if ( data.item instanceof ModelSelection || data.item instanceof DocumentSelection || data.item.is( '$textProxy' ) ) {
 			const converter = wrap( ( modelAttributeValue, { writer } ) => {
@@ -260,28 +262,28 @@ export function stringify( node, selectionOrPositionOrRange = null, markers = nu
 		return writer.createUIElement( name );
 	} ) );
 
+	const markersMap = new Map();
+
+	if ( markers ) {
+		// To provide stable results, sort markers by name.
+		for ( const marker of Array.from( markers ).sort( ( a, b ) => a.name < b.name ? 1 : -1 ) ) {
+			markersMap.set( marker.name, marker.getRange() );
+		}
+	}
+
 	// Convert model to view.
 	const writer = view._writer;
-	downcastDispatcher.convertInsert( range, writer );
+	downcastDispatcher.convert( range, markersMap, writer );
 
 	// Convert model selection to view selection.
 	if ( selection ) {
 		downcastDispatcher.convertSelection( selection, markers || model.markers, writer );
 	}
 
-	if ( markers ) {
-		// To provide stable results, sort markers by name.
-		markers = Array.from( markers ).sort( ( a, b ) => a.name < b.name ? 1 : -1 );
-
-		for ( const marker of markers ) {
-			downcastDispatcher.convertMarkerAdd( marker.name, marker.getRange(), writer );
-		}
-	}
-
 	// Parse view to data string.
 	let data = viewStringify( viewRoot, viewDocument.selection, { sameSelectionCharacters: true } );
 
-	// Removing unneccessary <div> and </div> added because `viewRoot` was also stringified alongside input data.
+	// Removing unnecessary <div> and </div> added because `viewRoot` was also stringified alongside input data.
 	data = data.substr( 5, data.length - 11 );
 
 	view.destroy();

package/src/dev-utils/operationreplayer.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dev-utils/utils.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/dev-utils/view.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 

package/src/index.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 
@@ -28,10 +28,17 @@ export { default as LivePosition } from './model/liveposition';
 export { default as Model } from './model/model';
 export { default as TreeWalker } from './model/treewalker';
 export { default as Element } from './model/element';
+export { default as Position } from './model/position';
+export { default as DocumentFragment } from './model/documentfragment';
+export { default as History } from './model/history';
+export { default as Text } from './model/text';
 
 export { default as DomConverter } from './view/domconverter';
 export { default as Renderer } from './view/renderer';
 export { default as ViewDocument } from './view/document';
+export { default as ViewText } from './view/text';
+export { default as ViewElement } from './view/element';
+export { default as ViewDocumentFragment } from './view/documentfragment';
 
 export { getFillerOffset } from './view/containerelement';
 export { default as Observer } from './view/observer/observer';

package/src/model/batch.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * @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
  */
 
@@ -7,6 +7,8 @@
  * @module engine/model/batch
  */
 
+import { logWarning } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
 /**
  * A batch instance groups model changes ({@link module:engine/model/operation/operation~Operation operations}). All operations
  * grouped in a single batch can be reverted together, so you can also think about a batch as of a single undo step. If you want
@@ -25,9 +27,30 @@ export default class Batch {
 	 *
 	 * @see module:engine/model/model~Model#enqueueChange
 	 * @see module:engine/model/model~Model#change
-	 * @param {'transparent'|'default'} [type='default'] The type of the batch.
+	 * @param {Object} [type] A set of flags that specify the type of the batch. Batch type can alter how some of the features work
+	 * when encountering a given `Batch` instance (for example, when a feature listens to applied operations).
+	 * @param {Boolean} [type.isUndoable=true] Whether a batch can be undone through undo feature.
+	 * @param {Boolean} [type.isLocal=true] Whether a batch includes operations created locally (`true`) or operations created on
+	 * other, remote editors (`false`).
+	 * @param {Boolean} [type.isUndo=false] Whether a batch was created by the undo feature and undoes other operations.
+	 * @param {Boolean} [type.isTyping=false] Whether a batch includes operations connected with a typing action.
 	 */
-	constructor( type = 'default' ) {
+	constructor( type = {} ) {
+		if ( typeof type === 'string' ) {
+			type = type === 'transparent' ? { isUndoable: false } : {};
+
+			/**
+			 * The string value for a `type` property of the `Batch` constructor has been deprecated and will be removed in the near future.
+			 * Please refer to the {@link module:engine/model/batch~Batch#constructor `Batch` constructor API documentation} for more
+			 * information.
+			 *
+			 * @error batch-constructor-deprecated-string-type
+			 */
+			logWarning( 'batch-constructor-deprecated-string-type' );
+		}
+
+		const { isUndoable = true, isLocal = true, isUndo = false, isTyping = false } = type;
+
 		/**
 		 * An array of operations that compose this batch.
 		 *
@@ -37,17 +60,61 @@ export default class Batch {
 		this.operations = [];
 
 		/**
-		 * The type of the batch.
+		 * Whether the batch can be undone through the undo feature.
+		 *
+		 * @readonly
+		 * @type {Boolean}
+		 */
+		this.isUndoable = isUndoable;
+
+		/**
+		 * Whether the batch includes operations created locally (`true`) or operations created on other, remote editors (`false`).
+		 *
+		 * @readonly
+		 * @type {Boolean}
+		 */
+		this.isLocal = isLocal;
+
+		/**
+		 * Whether the batch was created by the undo feature and undoes other operations.
 		 *
-		 * It can be one of the following values:
-		 * * `'default'` – All "normal" batches. This is the most commonly used type.
-		 * * `'transparent'` – A batch that should be ignored by other features, i.e. an initial batch or collaborative editing
-		 * changes.
+		 * @readonly
+		 * @type {Boolean}
+		 */
+		this.isUndo = isUndo;
+
+		/**
+		 * Whether the batch includes operations connected with typing.
 		 *
 		 * @readonly
-		 * @type {'transparent'|'default'}
+		 * @type {Boolean}
 		 */
-		this.type = type;
+		this.isTyping = isTyping;
+	}
+
+	/**
+	 * The type of the batch.
+	 *
+	 * **This property has been deprecated and is always set to the `'default'` value.**
+	 *
+	 * It can be one of the following values:
+	 * * `'default'` – All "normal" batches. This is the most commonly used type.
+	 * * `'transparent'` – A batch that should be ignored by other features, i.e. an initial batch or collaborative editing
+	 * changes.
+	 *
+	 * @deprecated
+	 * @type {'default'}
+	 */
+	get type() {
+		/**
+		 * The {@link module:engine/model/batch~Batch#type `Batch#type` } property has been deprecated and will be removed in the near
+		 * future. Use `Batch#isLocal`, `Batch#isUndoable`, `Batch#isUndo` and `Batch#isTyping` instead.
+		 *
+		 * @error batch-type-deprecated
+		 */
+		logWarning( 'batch-type-deprecated' );
+
+		return 'default';
 	}
 
 	/**