@ckeditor/ckeditor5-engine 31.1.0 → 34.0.0

package/src/model/utils/findoptimalinsertionrange.js

@@ -0,0 +1,68 @@
+/**
+ * @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/model/utils/findoptimalinsertionrange
+ */
+
+import first from '@ckeditor/ckeditor5-utils/src/first';
+
+// Returns a model range which is optimal (in terms of UX) for inserting a widget block.
+//
+// For instance, if a selection is in the middle of a paragraph, the collapsed range before this paragraph
+// will be returned so that it is not split. If the selection is at the end of a paragraph,
+// the collapsed range after this paragraph will be returned.
+//
+// Note: If the selection is placed in an empty block, the range in that block will be returned. If that range
+// is then passed to {@link module:engine/model/model~Model#insertContent}, the block will be fully replaced
+// by the inserted widget block.
+//
+// **Note:** Use {@link module:widget/utils#findOptimalInsertionRange} instead of this function outside engine.
+// This function is only exposed to be used by {@link module:widget/utils#findOptimalInsertionRange findOptimalInsertionRange()}
+// in `widget` package and inside `engine` package.
+//
+// @private
+// @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+// The selection based on which the insertion position should be calculated.
+// @param {module:engine/model/model~Model} model Model instance.
+// @param {'auto'|'before'|'after'} [place='auto'] Place where to look for optimal insertion range.
+// Default value `auto` will determine itself the best position for insertion.
+// Value `before` will try to find a position before selection.
+// Value `after` will try to find a position after selection.
+// @returns {module:engine/model/range~Range} The optimal range.
+export function findOptimalInsertionRange( selection, model, place = 'auto' ) {
+	const selectedElement = selection.getSelectedElement();
+
+	if ( selectedElement && model.schema.isObject( selectedElement ) && !model.schema.isInline( selectedElement ) ) {
+		if ( [ 'before', 'after' ].includes( place ) ) {
+			return model.createRange( model.createPositionAt( selectedElement, place ) );
+		}
+
+		return model.createRangeOn( selectedElement );
+	}
+
+	const firstBlock = first( selection.getSelectedBlocks() );
+
+	// There are no block elements within ancestors (in the current limit element).
+	if ( !firstBlock ) {
+		return model.createRange( selection.focus );
+	}
+
+	// If inserting into an empty block – return position in that block. It will get
+	// replaced with the image by insertContent(). #42.
+	if ( firstBlock.isEmpty ) {
+		return model.createRange( model.createPositionAt( firstBlock, 0 ) );
+	}
+
+	const positionAfter = model.createPositionAfter( firstBlock );
+
+	// If selection is at the end of the block - return position after the block.
+	if ( selection.focus.isTouching( positionAfter ) ) {
+		return model.createRange( positionAfter );
+	}
+
+	// Otherwise, return position before the block.
+	return model.createRange( model.createPositionBefore( firstBlock ) );
+}

package/src/model/utils/getselectedcontent.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/model/utils/insertcontent.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/model/utils/insertobject.js

@@ -0,0 +1,173 @@
+/**
+ * @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/model/utils/insertobject
+ */
+
+import first from '@ckeditor/ckeditor5-utils/src/first';
+import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+
+import { findOptimalInsertionRange } from './findoptimalinsertionrange';
+
+/**
+ * Inserts an {@glink framework/guides/deep-dive/schema#object-elements object element} at a specific position in the editor content.
+ *
+ * **Note:** Use {@link module:engine/model/model~Model#insertObject} instead of this function.
+ * This function is only exposed to be reusable in algorithms which change the {@link module:engine/model/model~Model#insertObject}
+ * method's behavior.
+ *
+ * **Note**: For more documentation and examples, see {@link module:engine/model/model~Model#insertObject}.
+ *
+ * @param {module:engine/model/model~Model} model The model in context of which the insertion
+ * should be performed.
+ * @param {module:engine/model/element~Element} object An object to be inserted into the model document.
+ * @param {module:engine/model/selection~Selectable} [selectable=model.document.selection]
+ * A selectable where the content should be inserted. If not specified, the current
+ * {@link module:engine/model/document~Document#selection document selection} will be used instead.
+ * @param {Number|'before'|'end'|'after'|'on'|'in'} placeOrOffset Specifies the exact place or offset for the insertion to take place,
+ * relative to `selectable`.
+ * @param {Object} [options] Additional options.
+ * @param {'auto'|'before'|'after'} [options.findOptimalPosition] An option that, when set, adjusts the insertion position (relative to
+ * `selectable` and `placeOrOffset`) so that the content of `selectable` is not split upon insertion (a.k.a. non-destructive insertion).
+ * * When `'auto'`, the algorithm will decide whether to insert the object before or after `selectable` to avoid content splitting.
+ * * When `'before'`, the closest position before `selectable` will be used that will not result in content splitting.
+ * * When `'after'`, the closest position after `selectable` will be used that will not result in content splitting.
+ *
+ * Note that this option works only for block objects. Inline objects are inserted into text and do not split blocks.
+ * @param {'on'|'after'} [options.setSelection] An option that, when set, moves the
+ * {@link module:engine/model/document~Document#selection document selection} after inserting the object.
+ * * When `'on'`, the document selection will be set on the inserted object.
+ * * When `'after'`, the document selection will move to the closest text node after the inserted object. If there is no
+ * such text node, a paragraph will be created and the document selection will be moved inside it.
+ * @returns {module:engine/model/range~Range} A range which contains all the performed changes. This is a range that, if removed,
+ * would return the model to the state before the insertion. If no changes were preformed by `insertObject()`, returns a range collapsed
+ * at the insertion position.
+ */
+export default function insertObject( model, object, selectable, placeOrOffset, options = {} ) {
+	if ( !model.schema.isObject( object ) ) {
+		/**
+		 * Tried to insert an element with {@link module:engine/model/utils/insertobject insertObject()} function
+		 * that is not defined as an object in schema.
+		 * See {@link module:engine/model/schema~SchemaItemDefinition#isObject `SchemaItemDefinition`}.
+		 * If you want to insert content that is not an object you might want to use
+		 * {@link module:engine/model/utils/insertcontent insertContent()} function.
+		 * @error insertobject-element-not-an-object
+		 */
+		throw new CKEditorError( 'insertobject-element-not-an-object', model, { object } );
+	}
+
+	// Normalize selectable to a selection instance.
+	let originalSelection;
+
+	if ( !selectable ) {
+		originalSelection = model.document.selection;
+	} else if ( selectable.is( 'selection' ) ) {
+		originalSelection = selectable;
+	} else {
+		originalSelection = model.createSelection( selectable, placeOrOffset );
+	}
+
+	// Adjust the insertion selection.
+	let insertionSelection = originalSelection;
+
+	if ( options.findOptimalPosition && model.schema.isBlock( object ) ) {
+		insertionSelection = model.createSelection( findOptimalInsertionRange( originalSelection, model, options.findOptimalPosition ) );
+	}
+
+	// Collect attributes to be copied on the inserted object.
+	const firstSelectedBlock = first( originalSelection.getSelectedBlocks() );
+	const attributesToCopy = {};
+
+	if ( firstSelectedBlock ) {
+		Object.assign( attributesToCopy, model.schema.getAttributesWithProperty( firstSelectedBlock, 'copyOnReplace', true ) );
+	}
+
+	return model.change( writer => {
+		// Remove the selected content to find out what the parent of the inserted object would be.
+		// It would be removed inside model.insertContent() anyway.
+		if ( !insertionSelection.isCollapsed ) {
+			model.deleteContent( insertionSelection, { doNotAutoparagraph: true } );
+		}
+
+		let elementToInsert = object;
+		const insertionPositionParent = insertionSelection.anchor.parent;
+
+		// Autoparagraphing of an inline objects.
+		if (
+			!model.schema.checkChild( insertionPositionParent, object ) &&
+			model.schema.checkChild( insertionPositionParent, 'paragraph' ) &&
+			model.schema.checkChild( 'paragraph', object )
+		) {
+			elementToInsert = writer.createElement( 'paragraph' );
+
+			writer.insert( object, elementToInsert );
+		}
+
+		// Apply attributes that are allowed on the inserted object (or paragraph if autoparagraphed).
+		model.schema.setAllowedAttributes( elementToInsert, attributesToCopy, writer );
+
+		// Insert the prepared content at the optionally adjusted selection.
+		const affectedRange = model.insertContent( elementToInsert, insertionSelection );
+
+		// Nothing got inserted.
+		if ( affectedRange.isCollapsed ) {
+			return affectedRange;
+		}
+
+		if ( options.setSelection ) {
+			updateSelection( writer, object, options.setSelection, attributesToCopy );
+		}
+
+		return affectedRange;
+	} );
+}
+
+// Updates document selection based on given `place` parameter in relation to `contextElement` element.
+//
+// @private
+// @param {module:engine/model/writer~Writer} writer An instance of the model writer.
+// @param {module:engine/model/element~Element} contextElement An element to set attributes on.
+// @param {'on'|'after'} place Place where selection should be set in relation to `contextElement` element.
+// Value `on` will set selection on passed `contextElement`. Value `after` will set selection after `contextElement`.
+// @param {Object} attributes Attributes keys and values to set on a paragraph that this function can create when
+// `place` parameter is equal to `after` but there is no element with `$text` node to set selection in.
+function updateSelection( writer, contextElement, place, paragraphAttributes ) {
+	const model = writer.model;
+
+	if ( place == 'after' ) {
+		let nextElement = contextElement.nextSibling;
+
+		// Check whether an element next to the inserted element is defined and can contain a text.
+		const canSetSelection = nextElement && model.schema.checkChild( nextElement, '$text' );
+
+		// If the element is missing, but a paragraph could be inserted next to the element, let's add it.
+		if ( !canSetSelection && model.schema.checkChild( contextElement.parent, 'paragraph' ) ) {
+			nextElement = writer.createElement( 'paragraph' );
+
+			model.schema.setAllowedAttributes( nextElement, paragraphAttributes, writer );
+			model.insertContent( nextElement, writer.createPositionAfter( contextElement ) );
+		}
+
+		// Put the selection inside the element, at the beginning.
+		if ( nextElement ) {
+			writer.setSelection( nextElement, 0 );
+		}
+	}
+	else if ( place == 'on' ) {
+		writer.setSelection( contextElement, 'on' );
+	}
+	else {
+		/**
+		 * Unsupported `options.setSelection` parameter was passed
+		 * to the {@link module:engine/model/utils/insertobject insertObject()} function.
+		 * Check {@link module:engine/model/utils/insertobject insertObject()} API documentation for allowed
+		 * `options.setSelection` parameter values.
+		 *
+		 * @error insertobject-invalid-place-parameter-value
+		 */
+		throw new CKEditorError( 'insertobject-invalid-place-parameter-value', model );
+	}
+}

package/src/model/utils/modifyselection.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
  */
 
@@ -10,7 +10,7 @@
 import Position from '../position';
 import TreeWalker from '../treewalker';
 import Range from '../range';
-import { isInsideSurrogatePair, isInsideCombinedSymbol } from '@ckeditor/ckeditor5-utils/src/unicode';
+import { isInsideSurrogatePair, isInsideCombinedSymbol, isInsideEmojiSequence } from '@ckeditor/ckeditor5-utils/src/unicode';
 import DocumentSelection from '../documentselection';
 
 const wordBoundaryCharacters = ' ,.?!:;"-()';
@@ -49,11 +49,13 @@ const wordBoundaryCharacters = ' ,.?!:;"-()';
  * @param {Object} [options]
  * @param {'forward'|'backward'} [options.direction='forward'] The direction in which the selection should be modified.
  * @param {'character'|'codePoint'|'word'} [options.unit='character'] The unit by which selection should be modified.
+ * @param {Boolean} [options.treatEmojiAsSingleUnit=false] Whether multi-characer emoji sequences should be handled as single unit.
  */
 export default function modifySelection( model, selection, options = {} ) {
 	const schema = model.schema;
 	const isForward = options.direction != 'backward';
 	const unit = options.unit ? options.unit : 'character';
+	const treatEmojiAsSingleUnit = !!options.treatEmojiAsSingleUnit;
 
 	const focus = selection.focus;
 
@@ -63,7 +65,7 @@ export default function modifySelection( model, selection, options = {} ) {
 		direction: isForward ? 'forward' : 'backward'
 	} );
 
-	const data = { walker, schema, isForward, unit };
+	const data = { walker, schema, isForward, unit, treatEmojiAsSingleUnit };
 
 	let next;
 
@@ -89,10 +91,10 @@ export default function modifySelection( model, selection, options = {} ) {
 }
 
 // Checks whether the selection can be extended to the the walker's next value (next position).
-// @param {{ walker, unit, isForward, schema }} data
+// @param {{ walker, unit, isForward, schema, treatEmojiAsSingleUnit }} data
 // @param {module:engine/view/treewalker~TreeWalkerValue} value
 function tryExtendingTo( data, value ) {
-	const { isForward, walker, unit, schema } = data;
+	const { isForward, walker, unit, schema, treatEmojiAsSingleUnit } = data;
 	const { type, item, nextPosition } = value;
 
 	// If found text, we can certainly put the focus in it. Let's just find a correct position
@@ -102,7 +104,7 @@ function tryExtendingTo( data, value ) {
 			return getCorrectWordBreakPosition( walker, isForward );
 		}
 
-		return getCorrectPosition( walker, unit, isForward );
+		return getCorrectPosition( walker, unit, treatEmojiAsSingleUnit );
 	}
 
 	// Entering an element.
@@ -139,14 +141,19 @@ function tryExtendingTo( data, value ) {
 //
 // @param {module:engine/model/treewalker~TreeWalker} walker
 // @param {String} unit The unit by which selection should be modified.
-function getCorrectPosition( walker, unit ) {
+// @param {Boolean} treatEmojiAsSingleUnit
+function getCorrectPosition( walker, unit, treatEmojiAsSingleUnit ) {
 	const textNode = walker.position.textNode;
 
 	if ( textNode ) {
 		const data = textNode.data;
 		let offset = walker.position.offset - textNode.startOffset;
 
-		while ( isInsideSurrogatePair( data, offset ) || ( unit == 'character' && isInsideCombinedSymbol( data, offset ) ) ) {
+		while (
+			isInsideSurrogatePair( data, offset ) ||
+			( unit == 'character' && isInsideCombinedSymbol( data, offset ) ) ||
+			( treatEmojiAsSingleUnit && isInsideEmojiSequence( data, offset ) )
+		) {
 			walker.next();
 
 			offset = walker.position.offset - textNode.startOffset;

package/src/model/utils/selection-post-fixer.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/model/writer.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
  */
 
@@ -27,7 +27,7 @@ import DocumentSelection from './documentselection';
 
 import toMap from '@ckeditor/ckeditor5-utils/src/tomap';
 
-import CKEditorError from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
+import CKEditorError, { logWarning } from '@ckeditor/ckeditor5-utils/src/ckeditorerror';
 
 /**
  * The model can only be modified by using the writer. It should be used whenever you want to create a node, modify
@@ -968,30 +968,8 @@ export default class Writer {
 	 * As the first parameter you can set marker name or instance. If none of them is provided, new marker, with a unique
 	 * name is created and returned.
 	 *
-	 * As the second parameter you can set the new marker data or leave this parameter as empty which will just refresh
-	 * the marker by triggering downcast conversion for it. Refreshing the marker is useful when you want to change
-	 * the marker {@link module:engine/view/element~Element view element} without changing any marker data.
-	 *
-	 * 		let isCommentActive = false;
-	 *
-	 * 		model.conversion.markerToHighlight( {
-	 * 			model: 'comment',
-	 *			view: data => {
-	 *				const classes = [ 'comment-marker' ];
-	 *
-	 *				if ( isCommentActive ) {
-	 *					classes.push( 'comment-marker--active' );
-	 *				}
-	 *
-	 *				return { classes };
-	 *			}
-	 * 		} );
-	 *
-	 * 		// Change the property that indicates if marker is displayed as active or not.
-	 * 		isCommentActive = true;
-	 *
-	 * 		// And refresh the marker to convert it with additional class.
-	 * 		model.change( writer => writer.updateMarker( 'comment' ) );
+	 * **Note**: If you want to change the {@link module:engine/view/element~Element view element} of the marker while its data in the model
+	 * remains the same, use the dedicated {@link module:engine/controller/editingcontroller~EditingController#reconvertMarker} method.
 	 *
 	 * The `options.usingOperation` parameter lets you change if the marker should be managed by operations or not. See
 	 * {@link module:engine/model/markercollection~Marker marker class description} to learn about the difference between
@@ -1037,7 +1015,7 @@ export default class Writer {
 
 		if ( !currentMarker ) {
 			/**
-			 * Marker with provided name does not exists.
+			 * Marker with provided name does not exist and will not be updated.
 			 *
 			 * @error writer-updatemarker-marker-not-exists
 			 */
@@ -1045,6 +1023,18 @@ export default class Writer {
 		}
 
 		if ( !options ) {
+			/**
+			 * The usage of `writer.updateMarker()` only to reconvert (refresh) a
+			 * {@link module:engine/model/markercollection~Marker model marker} was deprecated and may not work in the future.
+			 * Please update your code to use
+			 * {@link module:engine/controller/editingcontroller~EditingController#reconvertMarker `editor.editing.reconvertMarker()`}
+			 * instead.
+			 *
+			 * @error writer-updatemarker-reconvert-using-editingcontroller
+			 * @param {String} markerName The name of the updated marker.
+			 */
+			logWarning( 'writer-updatemarker-reconvert-using-editingcontroller', { markerName } );
+
 			this.model.markers._refresh( currentMarker );
 
 			return;

package/src/view/attributeelement.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
  */
 
@@ -24,16 +24,6 @@ const DEFAULT_PRIORITY = 10;
  * 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 {

package/src/view/containerelement.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/view/document.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
  */
 
@@ -141,7 +141,8 @@ export default class Document {
 	 *
 	 * * 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}.
+	 * * {@link module:engine/controller/editingcontroller~EditingController#reconvertItem marking some of the model elements to be
+	 * re-converted}.
 	 *
 	 * Try to avoid changes which touch view structure:
 	 *

package/src/view/documentfragment.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/view/documentselection.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
  */