@ckeditor/ckeditor5-engine 27.1.0 → 29.2.0

package/src/conversion/upcasthelpers.js

@@ -7,7 +7,6 @@ import Matcher from '../view/matcher';
 import ConversionHelpers from './conversionhelpers';
 
 import { cloneDeep } from 'lodash-es';
-import { logWarning } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 
 import priorities from '@ckeditor/ckeditor5-utils/src/priorities';
 import { isParagraphable, wrapInParagraph } from '../model/utils/autoparagraphing';
@@ -173,7 +172,7 @@ export default class UpcastHelpers extends ConversionHelpers {
 	 * View attribute to model attribute conversion helper.
 	 *
 	 * This conversion results in setting an attribute on a model node. For example, view `<img src="foo.jpg"></img>` becomes
-	 * `<image source="foo.jpg"></image>` in the model.
+	 * `<imageBlock source="foo.jpg"></imageBlock>` in the model.
 	 *
 	 * This helper is meant to convert view attributes from view elements which got converted to the model, so the view attribute
 	 * is set only on the corresponding model node:
@@ -294,13 +293,17 @@ export default class UpcastHelpers extends ConversionHelpers {
 	/**
 	 * View element to model marker conversion helper.
 	 *
-	 * **Note**: This method was deprecated. Please use {@link #dataToMarker} instead.
-	 *
 	 * This conversion results in creating a model marker. For example, if the marker was stored in a view as an element:
 	 * `<p>Fo<span data-marker="comment" data-comment-id="7"></span>o</p><p>B<span data-marker="comment" data-comment-id="7"></span>ar</p>`,
 	 * after the conversion is done, the marker will be available in
 	 * {@link module:engine/model/model~Model#markers model document markers}.
 	 *
+	 * **Note**: When this helper is used in the data upcast in combination with
+	 * {@link module:engine/conversion/downcasthelpers~DowncastHelpers#markerToData `#markerToData()`} in the data downcast,
+	 * then invalid HTML code (e.g. a span between table cells) may be produced by the latter converter.
+	 *
+	 * In most of the cases, the {@link #dataToMarker} should be used instead.
+	 *
 	 *		editor.conversion.for( 'upcast' ).elementToMarker( {
 	 *			view: 'marker-search',
 	 *			model: 'search'
@@ -330,7 +333,6 @@ export default class UpcastHelpers extends ConversionHelpers {
 	 * See {@link module:engine/conversion/conversion~Conversion#for `conversion.for()`} to learn how to add a converter
 	 * to the conversion process.
 	 *
-	 * @deprecated
 	 * @method #elementToMarker
 	 * @param {Object} config Conversion configuration.
 	 * @param {module:engine/view/matcher~MatcherPattern} config.view Pattern matching all view elements which should be converted.
@@ -340,15 +342,6 @@ export default class UpcastHelpers extends ConversionHelpers {
 	 * @returns {module:engine/conversion/upcasthelpers~UpcastHelpers}
 	 */
 	elementToMarker( config ) {
-		/**
-		 * The {@link module:engine/conversion/upcasthelpers~UpcastHelpers#elementToMarker `UpcastHelpers#elementToMarker()`}
-		 * method was deprecated and will be removed in the near future.
-		 * Please use {@link module:engine/conversion/upcasthelpers~UpcastHelpers#dataToMarker `UpcastHelpers#dataToMarker()`} instead.
-		 *
-		 * @error upcast-helpers-element-to-marker-deprecated
-		 */
-		logWarning( 'upcast-helpers-element-to-marker-deprecated' );
-
 		return this.add( upcastElementToMarker( config ) );
 	}
 
@@ -389,7 +382,7 @@ export default class UpcastHelpers extends ConversionHelpers {
 	 *
 	 *		// Model:
 	 *		<paragraph>Foo[bar</paragraph>
-	 *		<image src="abc.jpg"></image>]
+	 *		<imageBlock src="abc.jpg"></imageBlock>]
 	 *
 	 * Where `[]` are boundaries of a marker that will receive the `comment:commentId:uid` name.
 	 *
@@ -651,11 +644,11 @@ function upcastDataToMarker( config ) {
 		// Below is a hack that is needed to properly handle `converterPriority` for both elements and attributes.
 		// Attribute conversion needs to be performed *after* element conversion.
 		// This converter handles both element conversion and attribute conversion, which means that if a single
-		// `config.converterPriority` is used, it will lead to problems. For example, if `'high'` priority is used,
-		// then attribute conversion will be performed before a lot of element upcast converters.
-		// On the other hand we want to support `config.converterPriority` and overwriting conveters.
+		// `config.converterPriority` is used, it will lead to problems. For example, if the `'high'` priority is used,
+		// the attribute conversion will be performed before a lot of element upcast converters.
+		// On the other hand, we want to support `config.converterPriority` and converter overwriting.
 		//
-		// To have it work, we need to do some extra processing for priority for attribute converter.
+		// To make it work, we need to do some extra processing for priority for attribute converter.
 		// Priority `'low'` value should be the base value and then we will change it depending on `config.converterPriority` value.
 		//
 		// This hack probably would not be needed if attributes are upcasted separately.
@@ -682,12 +675,23 @@ function upcastAttributeToMarker( config ) {
 	return ( evt, data, conversionApi ) => {
 		const attrName = `data-${ config.view }`;
 
+		// Check if any attribute for the given view item can be consumed before changing the conversion data
+		// and consuming view items with these attributes.
+		if (
+			!conversionApi.consumable.test( data.viewItem, { attributes: attrName + '-end-after' } ) &&
+			!conversionApi.consumable.test( data.viewItem, { attributes: attrName + '-start-after' } ) &&
+			!conversionApi.consumable.test( data.viewItem, { attributes: attrName + '-end-before' } ) &&
+			!conversionApi.consumable.test( data.viewItem, { attributes: attrName + '-start-before' } )
+		) {
+			return;
+		}
+
 		// This converter wants to add a model element, marking a marker, before/after an element (or maybe even group of elements).
 		// To do that, we can use `data.modelRange` which is set on an element (or a group of elements) that has been upcasted.
 		// But, if the processed view element has not been upcasted yet (it does not have been converted), we need to
 		// fire conversion for its children first, then we will have `data.modelRange` available.
 		if ( !data.modelRange ) {
-			data = Object.assign( data, conversionApi.convertChildren( data.viewItem, data.modelCursor ) );
+			Object.assign( data, conversionApi.convertChildren( data.viewItem, data.modelCursor ) );
 		}
 
 		if ( conversionApi.consumable.consume( data.viewItem, { attributes: attrName + '-end-after' } ) ) {
@@ -868,15 +872,6 @@ function prepareToAttributeConverter( config, shallow ) {
 			return;
 		}
 
-		const modelKey = config.model.key;
-		const modelValue = typeof config.model.value == 'function' ?
-			config.model.value( data.viewItem, conversionApi ) : config.model.value;
-
-		// Do not convert if attribute building function returned falsy value.
-		if ( modelValue === null ) {
-			return;
-		}
-
 		if ( onlyViewNameIsDefined( config.view, data.viewItem ) ) {
 			match.match.name = true;
 		} else {
@@ -889,11 +884,20 @@ function prepareToAttributeConverter( config, shallow ) {
 			return;
 		}
 
+		const modelKey = config.model.key;
+		const modelValue = typeof config.model.value == 'function' ?
+			config.model.value( data.viewItem, conversionApi ) : config.model.value;
+
+		// Do not convert if attribute building function returned falsy value.
+		if ( modelValue === null ) {
+			return;
+		}
+
 		// Since we are converting to attribute we need a range on which we will set the attribute.
 		// If the range is not created yet, let's create it by converting children of the current node first.
 		if ( !data.modelRange ) {
 			// Convert children and set conversion result as a current data.
-			data = Object.assign( data, conversionApi.convertChildren( data.viewItem, data.modelCursor ) );
+			Object.assign( data, conversionApi.convertChildren( data.viewItem, data.modelCursor ) );
 		}
 
 		// Set attribute on current `output`. `Schema` is checked inside this helper function.

package/src/dataprocessor/dataprocessor.jsdoc

@@ -51,14 +51,14 @@
  */
 
 /**
- * If the processor is set to use marked fillers, it will insert nbsp fillers wrapped in spans
- * (`<span data-cke-filler="true">&nbsp;</span>`), instead of regular nbsp characters (`&nbsp;`).
+ * If the processor is set to use marked fillers, it will insert `&nbsp;` fillers wrapped in `<span>` elements
+ * (`<span data-cke-filler="true">&nbsp;</span>`) instead of regular `&nbsp;` characters.
  *
- * This mode allows for more precise handling of block fillers (so they don't leak into editor content) but bloats the editor
- * data with additional markup.
+ * This mode allows for more precise handling of block fillers (so they do not leak into the editor content) but bloats the
+ * editor data with additional markup.
  *
  * This mode may be required by some features and will be turned on by them automatically.
  *
  * @method #useFillerType
- * @param {'default'|'marked'} type Whether to use default or marked nbsp block fillers.
+ * @param {'default'|'marked'} type Whether to use the default or marked `&nbsp;` block fillers.
  */

package/src/dataprocessor/htmldataprocessor.js

@@ -7,7 +7,7 @@
  * @module engine/dataprocessor/htmldataprocessor
  */
 
-/* globals document, DOMParser */
+/* globals document, DOMParser, Node */
 
 import BasicHtmlWriter from './basichtmlwriter';
 import DomConverter from '../view/domconverter';
@@ -94,15 +94,15 @@ export default class HtmlDataProcessor {
 	}
 
 	/**
-	 * If the processor is set to use marked fillers, it will insert nbsp fillers wrapped in spans
-	 * (`<span data-cke-filler="true">&nbsp;</span>`), instead of regular nbsp characters (`&nbsp;`).
+	 * If the processor is set to use marked fillers, it will insert `&nbsp;` fillers wrapped in `<span>` elements
+	 * (`<span data-cke-filler="true">&nbsp;</span>`) instead of regular `&nbsp;` characters.
 	 *
-	 * This mode allows for more precise handling of block fillers (so they don't leak into editor content) but bloats the editor
-	 * data with additional markup.
+	 * This mode allows for a more precise handling of the block fillers (so they do not leak into the editor content) but
+	 * bloats the editor data with additional markup.
 	 *
 	 * This mode may be required by some features and will be turned on by them automatically.
 	 *
-	 * @param {'default'|'marked'} type Whether to use default or marked nbsp block fillers.
+	 * @param {'default'|'marked'} type Whether to use the default or the marked `&nbsp;` block fillers.
 	 */
 	useFillerType( type ) {
 		this._domConverter.blockFillerMode = type == 'marked' ? 'markedNbsp' : 'nbsp';
@@ -119,10 +119,39 @@ export default class HtmlDataProcessor {
 	_toDom( data ) {
 		const document = this._domParser.parseFromString( data, 'text/html' );
 		const fragment = document.createDocumentFragment();
-		const nodes = document.body.childNodes;
 
-		while ( nodes.length > 0 ) {
-			fragment.appendChild( nodes[ 0 ] );
+		// 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 );
+			}
+		}
+
+		const bodyChildNodes = document.body.childNodes;
+
+		while ( bodyChildNodes.length > 0 ) {
+			fragment.appendChild( bodyChildNodes[ 0 ] );
 		}
 
 		return fragment;

package/src/dataprocessor/xmldataprocessor.js

@@ -111,15 +111,15 @@ export default class XmlDataProcessor {
 	}
 
 	/**
-	 * If the processor is set to use marked fillers, it will insert nbsp fillers wrapped in spans
-	 * (`<span data-cke-filler="true">&nbsp;</span>`), instead of regular nbsp characters (`&nbsp;`).
+	 * If the processor is set to use marked fillers, it will insert `&nbsp;` fillers wrapped in `<span>` elements
+	 * (`<span data-cke-filler="true">&nbsp;</span>`) instead of regular `&nbsp;` characters.
 	 *
-	 * This mode allows for more precise handling of block fillers (so they don't leak into editor content) but bloats the editor
-	 * data with additional markup.
+	 * This mode allows for a more precise handling of block fillers (so they do not leak into editor content) but
+	 * bloats the editor data with additional markup.
 	 *
 	 * This mode may be required by some features and will be turned on by them automatically.
 	 *
-	 * @param {'default'|'marked'} type Whether to use default or marked nbsp block fillers.
+	 * @param {'default'|'marked'} type Whether to use the default or the marked `&nbsp;` block fillers.
 	 */
 	useFillerType( type ) {
 		this._domConverter.blockFillerMode = type == 'marked' ? 'markedNbsp' : 'nbsp';

package/src/index.js

@@ -30,6 +30,7 @@ export { default as TreeWalker } from './model/treewalker';
 export { default as Element } from './model/element';
 
 export { default as DomConverter } from './view/domconverter';
+export { default as Renderer } from './view/renderer';
 export { default as ViewDocument } from './view/document';
 
 export { getFillerOffset } from './view/containerelement';

package/src/model/element.js

@@ -104,9 +104,9 @@ export default class Element extends Node {
 	 * Assuming that the object being checked is an element, you can also check its
 	 * {@link module:engine/model/element~Element#name name}:
 	 *
-	 *		element.is( 'element', 'image' ); // -> true if this is an <image> element
-	 *		element.is( 'element', 'image' ); // -> same as above
-	 *		text.is( 'element', 'image' ); -> false
+	 *		element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
+	 *		element.is( 'element', 'imageBlock' ); // -> same as above
+	 *		text.is( 'element', 'imageBlock' ); -> false
 	 *
 	 * {@link module:engine/model/node~Node#is Check the entire list of model objects} which implement the `is()` method.
 	 *

package/src/model/liveposition.js

@@ -96,7 +96,7 @@ export default class LivePosition extends Position {
 	 *
 	 * @param {module:engine/model/position~Position} position
 	 * @param {module:engine/model/position~PositionStickiness} [stickiness]
-	 * @returns {module:engine/model/position~Position}
+	 * @returns {module:engine/model/liveposition~LivePosition}
 	 */
 	static fromPosition( position, stickiness ) {
 		return new this( position.root, position.path.slice(), stickiness ? stickiness : position.stickiness );

package/src/model/model.js

@@ -109,15 +109,15 @@ export default class Model {
 
 		this.schema.register( '$clipboardHolder', {
 			allowContentOf: '$root',
+			allowChildren: '$text',
 			isLimit: true
 		} );
-		this.schema.extend( '$text', { allowIn: '$clipboardHolder' } );
 
 		this.schema.register( '$documentFragment', {
 			allowContentOf: '$root',
+			allowChildren: '$text',
 			isLimit: true
 		} );
-		this.schema.extend( '$text', { allowIn: '$documentFragment' } );
 
 		// An element needed by the `upcastElementToMarker` converter.
 		// This element temporarily represents a marker boundary during the conversion process and is removed
@@ -463,14 +463,14 @@ export default class Model {
 	 * @param {Boolean} [options.doNotAutoparagraph=false] Whether to create a paragraph if after content deletion selection is moved
 	 * to a place where text cannot be inserted.
 	 *
-	 * For example `<paragraph>x</paragraph>[<image src="foo.jpg"></image>]` will become:
+	 * For example `<paragraph>x</paragraph>[<imageBlock src="foo.jpg"></imageBlock>]` will become:
 	 *
 	 * * `<paragraph>x</paragraph><paragraph>[]</paragraph>` with the option disabled (`doNotAutoparagraph == false`)
 	 * * `<paragraph>x[]</paragraph>` with the option enabled (`doNotAutoparagraph == true`).
 	 *
 	 * **Note:** if there is no valid position for the selection, the paragraph will always be created:
 	 *
-	 * `[<image src="foo.jpg"></image>]` -> `<paragraph>[]</paragraph>`.
+	 * `[<imageBlock src="foo.jpg"></imageBlock>]` -> `<paragraph>[]</paragraph>`.
 	 *
 	 * @param {'forward'|'backward'} [options.direction='backward'] The direction in which the content is being consumed.
 	 * Deleting backward corresponds to using the <kbd>Backspace</kbd> key, while deleting content forward corresponds to
@@ -559,7 +559,7 @@ export default class Model {
 	 * {@link module:engine/model/markercollection~Marker#_affectsData affects data}.
 	 *
 	 * This means that a range containing an empty `<paragraph></paragraph>` is not considered to have a meaningful content.
-	 * However, a range containing an `<image></image>` (which would normally be marked in the schema as an object element)
+	 * However, a range containing an `<imageBlock></imageBlock>` (which would normally be marked in the schema as an object element)
 	 * is considered non-empty.
 	 *
 	 * @param {module:engine/model/range~Range|module:engine/model/element~Element} rangeOrElement Range or element to check.

package/src/model/node.js

@@ -406,9 +406,9 @@ export default class Node {
 	 *
 	 * By using this method it is also possible to check a name of an element:
 	 *
-	 *		imageElement.is( 'element', 'image' ); // -> true
-	 *		imageElement.is( 'element', 'image' ); // -> same as above
-	 *		imageElement.is( 'model:element', 'image' ); // -> same as above, but more precise
+	 *		imageElement.is( 'element', 'imageBlock' ); // -> true
+	 *		imageElement.is( 'element', 'imageBlock' ); // -> same as above
+	 *		imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more precise
 	 *
 	 * The list of model objects which implement the `is()` method:
 	 *

package/src/model/range.js

@@ -25,8 +25,9 @@ export default class Range {
 	/**
 	 * Creates a range spanning from `start` position to `end` position.
 	 *
-	 * @param {module:engine/model/position~Position} start Start position.
-	 * @param {module:engine/model/position~Position} [end] End position. If not set, range will be collapsed at `start` position.
+	 * @param {module:engine/model/position~Position} start The start position.
+	 * @param {module:engine/model/position~Position} [end] The end position. If not set,
+	 * the range will be collapsed at the `start` position.
 	 */
 	constructor( start, end = null ) {
 		/**
@@ -426,6 +427,7 @@ export default class Range {
 	 * @param {Boolean} [options.singleCharacters=false]
 	 * @param {Boolean} [options.shallow=false]
 	 * @param {Boolean} [options.ignoreElementEnd=false]
+	 * @returns {module:engine/model/treewalker~TreeWalker}
 	 */
 	getWalker( options = {} ) {
 		options.boundaries = this;
@@ -1031,7 +1033,7 @@ export default class Range {
 	 *
 	 * @param {Object} json Plain object to be converted to `Range`.
 	 * @param {module:engine/model/document~Document} doc Document object that will be range owner.
-	 * @returns {module:engine/model/element~Element} `Range` instance created using given plain object.
+	 * @returns {module:engine/model/range~Range} `Range` instance created using given plain object.
 	 */
 	static fromJSON( json, doc ) {
 		return new this( Position.fromJSON( json.start, doc ), Position.fromJSON( json.end, doc ) );