@ckeditor/ckeditor5-engine 29.0.0 → 31.0.0

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 ) {
 		/**
@@ -445,7 +446,7 @@ export default class Range {
 	 * You may specify additional options for the tree walker. See {@link module:engine/model/treewalker~TreeWalker} for
 	 * a full list of available options.
 	 *
-	 * @param {Object} options Object with configuration options. See {@link module:engine/model/treewalker~TreeWalker}.
+	 * @param {Object} [options] Object with configuration options. See {@link module:engine/model/treewalker~TreeWalker}.
 	 * @returns {Iterable.<module:engine/model/item~Item>}
 	 */
 	* getItems( options = {} ) {

package/src/model/schema.js

@@ -18,23 +18,23 @@ import Text from './text';
 import TreeWalker from './treewalker';
 
 /**
- * The model's schema. It defines allowed and disallowed structures of nodes as well as nodes' attributes.
- * The schema is usually defined by features and based on them the editing framework and features
- * make decisions how to change and process the model.
+ * The model's schema. It defines the allowed and disallowed structures of nodes as well as nodes' attributes.
+ * The schema is usually defined by the features and based on them, the editing framework and features
+ * make decisions on how to change and process the model.
  *
  * The instance of schema is available in {@link module:engine/model/model~Model#schema `editor.model.schema`}.
  *
  * Read more about the schema in:
  *
- * * {@glink framework/guides/architecture/editing-engine#schema Schema} section of the
- * {@glink framework/guides/architecture/editing-engine Introduction to the Editing engine architecture}.
- * * {@glink framework/guides/deep-dive/schema Schema deep dive} guide.
+ * * The {@glink framework/guides/architecture/editing-engine#schema schema section} of the
+ * {@glink framework/guides/architecture/editing-engine Introduction to the Editing engine architecture} guide.
+ * * The {@glink framework/guides/deep-dive/schema Schema deep dive} guide.
  *
  * @mixes module:utils/observablemixin~ObservableMixin
  */
 export default class Schema {
 	/**
-	 * Creates schema instance.
+	 * Creates a schema instance.
 	 */
 	constructor() {
 		this._sourceDefinitions = {};
@@ -61,7 +61,7 @@ export default class Schema {
 	}
 
 	/**
-	 * Registers schema item. Can only be called once for every item name.
+	 * Registers a schema item. Can only be called once for every item name.
 	 *
 	 *		schema.register( 'paragraph', {
 	 *			inheritAllFrom: '$block'
@@ -221,8 +221,8 @@ export default class Schema {
 	 *		const paragraphElement = writer.createElement( 'paragraph' );
 	 *		schema.isBlock( paragraphElement ); // -> true
 	 *
-	 * See the {@glink framework/guides/deep-dive/schema#block-elements Block elements} section of the Schema deep dive
-	 * guide for more details.
+	 * See the {@glink framework/guides/deep-dive/schema#block-elements Block elements} section of
+	 * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
 	 *
 	 * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
   	 * @returns {Boolean}
@@ -247,8 +247,8 @@ export default class Schema {
 	 *		schema.isLimit( editor.model.document.getRoot() ); // -> true
 	 *		schema.isLimit( 'imageBlock' ); // -> true
 	 *
-	 * See the {@glink framework/guides/deep-dive/schema#limit-elements Limit elements} section of the Schema deep dive
-	 * guide for more details.
+	 * See the {@glink framework/guides/deep-dive/schema#limit-elements Limit elements} section of
+	 * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
 	 *
 	 * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
   	 * @returns {Boolean}
@@ -277,8 +277,8 @@ export default class Schema {
 	 *		const imageElement = writer.createElement( 'imageBlock' );
 	 *		schema.isObject( imageElement ); // -> true
 	 *
-	 * See the {@glink framework/guides/deep-dive/schema#object-elements Object elements} section of the Schema deep dive
-	 * guide for more details.
+	 * See the {@glink framework/guides/deep-dive/schema#object-elements Object elements} section of
+	 * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
 	 *
 	 * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
   	 * @returns {Boolean}
@@ -305,8 +305,8 @@ export default class Schema {
 	 *		const text = writer.createText( 'foo' );
 	 *		schema.isInline( text ); // -> true
 	 *
-	 * See the {@glink framework/guides/deep-dive/schema#inline-elements Inline elements} section of the Schema deep dive
-	 * guide for more details.
+	 * See the {@glink framework/guides/deep-dive/schema#inline-elements Inline elements} section of
+	 * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
 	 *
 	 * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
 	 * @returns {Boolean}
@@ -329,8 +329,8 @@ export default class Schema {
 	 *		const text = writer.createText( 'foo' );
 	 *		schema.isSelectable( text ); // -> false
 	 *
-	 * See the {@glink framework/guides/deep-dive/schema#selectable-elements Selectable elements section} of the Schema deep dive
-	 * guide for more details.
+	 * See the {@glink framework/guides/deep-dive/schema#selectable-elements Selectable elements section} of
+	 * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
 	 *
 	 * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
 	 * @returns {Boolean}
@@ -357,8 +357,8 @@ export default class Schema {
 	 *		const text = writer.createText( 'foo' );
 	 *		schema.isContent( text ); // -> true
 	 *
-	 * See the {@glink framework/guides/deep-dive/schema#content-elements Content elements section} of the Schema deep dive
-	 * guide for more details.
+	 * See the {@glink framework/guides/deep-dive/schema#content-elements Content elements section} of
+	 * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide for more details.
 	 *
 	 * @param {module:engine/model/item~Item|module:engine/model/schema~SchemaContextItem|String} item
 	 * @returns {Boolean}
@@ -1243,7 +1243,8 @@ mix( Schema, ObservableMixin );
  * Most block type items will inherit from `$block` (through `inheritAllFrom`).
  *
  * Read more about the block elements in the
- * {@glink framework/guides/deep-dive/schema#block-elements Block elements section} of the Schema deep dive guide.
+ * {@glink framework/guides/deep-dive/schema#block-elements Block elements section} of
+ * the {@glink framework/guides/deep-dive/schema Schema deep dive}.
  *
  * @property {Boolean} isInline
  * Whether an item is "text-like" and should be treated as an inline node. Examples of inline elements:
@@ -1258,7 +1259,8 @@ mix( Schema, ObservableMixin );
  * a limit element are limited to its content.
  *
  * Read more about the limit elements in the
- * {@glink framework/guides/deep-dive/schema#limit-elements Limit elements section} of the Schema deep dive guide.
+ * {@glink framework/guides/deep-dive/schema#limit-elements Limit elements section} of
+ * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide.
  *
  * @property {Boolean} isObject
  * Whether an item is "self-contained" and should be treated as a whole. Examples of object elements:
@@ -1278,7 +1280,8 @@ mix( Schema, ObservableMixin );
  * {@link module:engine/model/schema~Schema#isSelectable `isSelectable()`} returns `true` for object elements automatically.
  *
  * Read more about selectable elements in the
- * {@glink framework/guides/deep-dive/schema#selectable-elements Selectable elements section} of the Schema deep dive guide.
+ * {@glink framework/guides/deep-dive/schema#selectable-elements Selectable elements section} of
+ * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide.
  *
  * @property {Boolean} isContent
  * An item is a content when it always finds its way to the editor data output regardless of the number and type of its descendants.
@@ -1288,7 +1291,8 @@ mix( Schema, ObservableMixin );
  * {@link module:engine/model/schema~Schema#isContent `isContent()`} returns `true` for object elements automatically.
  *
  * Read more about content elements in the
- * {@glink framework/guides/deep-dive/schema#content-elements Content elements section} of the Schema deep dive guide.
+ * {@glink framework/guides/deep-dive/schema#content-elements Content elements section} of
+ * the {@glink framework/guides/deep-dive/schema Schema deep dive} guide.
  */
 
 /**

package/src/model/selection.js

@@ -71,7 +71,7 @@ export default class Selection {
 	 *		// Creates backward selection.
 	 *		const selection = writer.createSelection( range, { backward: true } );
 	 *
-	 * @param {module:engine/model/selection~Selectable} selectable
+	 * @param {module:engine/model/selection~Selectable} [selectable]
 	 * @param {Number|'before'|'end'|'after'|'on'|'in'} [placeOrOffset] Sets place or offset of the selection.
 	 * @param {Object} [options]
 	 * @param {Boolean} [options.backward] Sets this selection instance to be backward.

package/src/model/utils/deletecontent.js

@@ -53,7 +53,7 @@ import DocumentSelection from '../documentselection';
  * If you use this option you need to make sure to handle invalid selections yourself or leave
  * them to the selection post-fixer (may not always work).
  *
- * **Note:** if there is no valid position for the selection, the paragraph will always be created:
+ * **Note:** If there is no valid position for the selection, the paragraph will always be created:
  *
  * `[<imageBlock src="foo.jpg"></imageBlock>]` -> `<paragraph>[]</paragraph>`.
  */
@@ -150,10 +150,10 @@ function getLivePositionsForSelectedBlocks( range ) {
 
 			const newEndPosition = selection.getLastPosition();
 
-			// For such model and selection:
+			// For such a model and selection:
 			//     <paragraph>A[</paragraph><imageBlock></imageBlock><paragraph>]B</paragraph>
 			//
-			// After modifySelection() we would end up with this:
+			// After modifySelection(), we would end up with this:
 			//     <paragraph>A[</paragraph>]<imageBlock></imageBlock><paragraph>B</paragraph>
 			//
 			// So we need to check if there is no content in the skipped range (because we want to include the <imageBlock>).

package/src/model/utils/selection-post-fixer.js

@@ -128,9 +128,17 @@ function tryFixingCollapsedRange( range, schema ) {
 
 	const nearestSelectionRange = schema.getNearestSelectionRange( originalPosition );
 
-	// This might be null ie when editor data is empty.
-	// In such cases there is no need to fix the selection range.
+	// This might be null ie when editor data is empty or the selection is inside limit element
+	// that doesn't allow text inside.
+	// In the first case there is no need to fix the selection range.
+	// In the second let's go up to the outer selectable element
 	if ( !nearestSelectionRange ) {
+		const ancestorObject = originalPosition.getAncestors().reverse().find( item => schema.isObject( item ) );
+
+		if ( ancestorObject ) {
+			return Range._createOn( ancestorObject );
+		}
+
 		return null;
 	}
 

package/src/view/document.js

@@ -80,6 +80,18 @@ export default class Document {
 		 */
 		this.set( 'isFocused', false );
 
+		/**
+		 * `true` while the user is making a selection in the document (e.g. holding the mouse button and moving the cursor).
+		 * When they stop selecting, the property goes back to `false`.
+		 *
+		 * This property is updated by the {@link module:engine/view/observer/selectionobserver~SelectionObserver}.
+		 *
+		 * @readonly
+		 * @observable
+		 * @member {Boolean} module:engine/view/document~Document#isSelecting
+		 */
+		this.set( 'isSelecting', false );
+
 		/**
 		 * True if composition is in progress inside the document.
 		 *