Merge pull request #1357 from ckeditor/t/1304

Other: View selection is now split onto Selection and DocumentSelection. Closes #1304 .

BREAKING CHANGE: Introduced view.DocumentSelection. It has protected API and can be modified only by view writer. Observers creating instance of selection (like SelectionObserver, MutationObserver) use view.Selection class now.

Author: Piotr Jasiun

src/conversion/downcast-selection-converters.js

@@ -5,16 +5,16 @@
 
 /**
  * Contains {@link module:engine/model/selection~Selection model selection} to
- * {@link module:engine/view/selection~Selection view selection} converters for
+ * {@link module:engine/view/documentselection~DocumentSelection view selection} converters for
  * {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher}.
  *
  * @module engine/conversion/downcast-selection-converters
  */
 
 /**
  * Function factory, creates a converter that converts non-collapsed {@link module:engine/model/selection~Selection model selection} to
- * {@link module:engine/view/selection~Selection view selection}. The converter consumes appropriate value from `consumable` object
- * and maps model positions from selection to view positions.
+ * {@link module:engine/view/documentselection~DocumentSelection view selection}. The converter consumes appropriate
+ * value from `consumable` object and maps model positions from selection to view positions.
  *
  *		modelDispatcher.on( 'selection', convertRangeSelection() );
  *
@@ -45,9 +45,9 @@ export function convertRangeSelection() {
 
 /**
  * Function factory, creates a converter that converts collapsed {@link module:engine/model/selection~Selection model selection} to
- * {@link module:engine/view/selection~Selection view selection}. The converter consumes appropriate value from `consumable` object,
- * maps model selection position to view position and breaks {@link module:engine/view/attributeelement~AttributeElement attribute elements}
- * at the selection position.
+ * {@link module:engine/view/documentselection~DocumentSelection view selection}. The converter consumes appropriate
+ * value from `consumable` object, maps model selection position to view position and breaks
+ * {@link module:engine/view/attributeelement~AttributeElement attribute elements} at the selection position.
  *
  *		modelDispatcher.on( 'selection', convertCollapsedSelection() );
  *

src/conversion/upcast-selection-converters.js

@@ -4,7 +4,7 @@
  */
 
 /**
- * Contains {@link module:engine/view/selection~Selection view selection}
+ * Contains {@link module:engine/view/documentselection~DocumentSelection view selection}
  * to {@link module:engine/model/selection~Selection model selection} conversion helpers.
  *
  * @module engine/conversion/upcast-selection-converters
@@ -13,8 +13,8 @@
 import ModelSelection from '../model/selection';
 
 /**
- * Function factory, creates a callback function which converts a {@link module:engine/view/selection~Selection view selection} taken
- * from the {@link module:engine/view/document~Document#event:selectionChange} event
+ * Function factory, creates a callback function which converts a {@link module:engine/view/selection~Selection
+ * view selection} taken from the {@link module:engine/view/document~Document#event:selectionChange} event
  * and sets in on the {@link module:engine/model/document~Document#selection model}.
  *
  * **Note**: because there is no view selection change dispatcher nor any other advanced view selection to model

src/dev-utils/view.js

@@ -15,7 +15,7 @@ import View from '../view/view';
 import ViewDocumentFragment from '../view/documentfragment';
 import XmlDataProcessor from '../dataprocessor/xmldataprocessor';
 import ViewElement from '../view/element';
-import Selection from '../view/selection';
+import DocumentSelection from '../view/documentselection';
 import Range from '../view/range';
 import Position from '../view/position';
 import AttributeElement from '../view/attributeelement';
@@ -125,8 +125,8 @@ setData._parse = parse;
  *
  *		stringify( fragment ); // '<p style="color:red;"></p><b name="test">foobar</b>'
  *
- * Additionally, a {@link module:engine/view/selection~Selection selection} instance can be provided. Ranges from the selection
- * will then be included in output data.
+ * Additionally, a {@link module:engine/view/documentselection~DocumentSelection selection} instance can be provided.
+ * Ranges from the selection will then be included in output data.
  * If a range position is placed inside the element node, it will be represented with `[` and `]`:
  *
  *		const text = new Text( 'foobar' );
@@ -163,9 +163,9 @@ setData._parse = parse;
  *		stringify( text, selection ); // '{f}oo{ba}r'
  *
  * A {@link module:engine/view/range~Range range} or {@link module:engine/view/position~Position position} instance can be provided
- * instead of the {@link module:engine/view/selection~Selection selection} instance. If a range instance is provided, it will be
- * converted to a selection containing this range. If a position instance is provided, it will be converted to a selection
- * containing one range collapsed at this position.
+ * instead of the {@link module:engine/view/documentselection~DocumentSelection selection} instance. If a range instance
+ * is provided, it will be converted to a selection containing this range. If a position instance is provided, it will
+ * be converted to a selection containing one range collapsed at this position.
  *
  *		const text = new Text( 'foobar' );
  *		const range = Range.createFromParentsAndOffsets( text, 0, text, 1 );
@@ -206,7 +206,7 @@ setData._parse = parse;
  *
  * @param {module:engine/view/text~Text|module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment}
  * node The node to stringify.
- * @param {module:engine/view/selection~Selection|module:engine/view/position~Position|module:engine/view/range~Range}
+ * @param {module:engine/view/documentselection~DocumentSelection|module:engine/view/position~Position|module:engine/view/range~Range}
  * [selectionOrPositionOrRange = null ]
  * A selection instance whose ranges will be included in the returned string data. If a range instance is provided, it will be
  * converted to a selection containing this range. If a position instance is provided, it will be converted to a selection
@@ -231,7 +231,7 @@ export function stringify( node, selectionOrPositionOrRange = null, options = {}
 		selectionOrPositionOrRange instanceof Position ||
 		selectionOrPositionOrRange instanceof Range
 	) {
-		selection = new Selection( selectionOrPositionOrRange );
+		selection = new DocumentSelection( selectionOrPositionOrRange );
 	} else {
 		selection = selectionOrPositionOrRange;
 	}
@@ -257,7 +257,7 @@ export function stringify( node, selectionOrPositionOrRange = null, options = {}
  *		parse( '<b>foo</b><i>bar</i>' ); // Returns a document fragment with two child elements.
  *
  * The method can parse multiple {@link module:engine/view/range~Range ranges} provided in string data and return a
- * {@link module:engine/view/selection~Selection selection} instance containing these ranges. Ranges placed inside
+ * {@link module:engine/view/documentselection~DocumentSelection selection} instance containing these ranges. Ranges placed inside
  * {@link module:engine/view/text~Text text} nodes should be marked using `{` and `}` brackets:
  *
  *		const { text, selection } = parse( 'f{ooba}r' );
@@ -278,8 +278,9 @@ export function stringify( node, selectionOrPositionOrRange = null, options = {}
  * In the example above, the first range (`{fo}`) will be added to the selection as the second one, the second range (`{ar}`) will be
  * added as the third and the third range (`{ba}`) will be added as the first one.
  *
- * If the selection's last range should be added as a backward one (so the {@link module:engine/view/selection~Selection#anchor selection
- * anchor} is represented by the `end` position and {@link module:engine/view/selection~Selection#focus selection focus} is
+ * If the selection's last range should be added as a backward one
+ * (so the {@link module:engine/view/documentselection~DocumentSelection#anchor selection anchor} is represented
+ * by the `end` position and {@link module:engine/view/documentselection~DocumentSelection#focus selection focus} is
  * represented by the `start` position), use the `lastRangeBackward` flag:
  *
  *		const { root, selection } = parse( `{foo}bar{baz}`, { lastRangeBackward: true } );
@@ -298,11 +299,11 @@ export function stringify( node, selectionOrPositionOrRange = null, options = {}
  * @param {String} data An HTML-like string to be parsed.
  * @param {Object} options
  * @param {Array.<Number>} [options.order] An array with the order of parsed ranges added to the returned
- * {@link module:engine/view/selection~Selection Selection} instance. Each element should represent the desired position of each range in
- * the selection instance. For example: `[2, 3, 1]` means that the first range will be placed as the second, the second as the third and
- * the third as the first.
+ * {@link module:engine/view/documentselection~DocumentSelection Selection} instance. Each element should represent the
+ * desired position of each range in the selection instance. For example: `[2, 3, 1]` means that the first range will be
+ * placed as the second, the second as the third and the third as the first.
  * @param {Boolean} [options.lastRangeBackward=false] If set to `true`, the last range will be added as backward to the returned
- * {@link module:engine/view/selection~Selection selection} instance.
+ * {@link module:engine/view/documentselection~DocumentSelection selection} instance.
  * @param {module:engine/view/element~Element|module:engine/view/documentfragment~DocumentFragment}
  * [options.rootElement=null] The default root to use when parsing elements.
  * When set to `null`, the root element will be created automatically. If set to
@@ -351,7 +352,7 @@ export function parse( data, options = {} ) {
 
 	// When ranges are present - return object containing view, and selection.
 	if ( ranges.length ) {
-		const selection = new Selection( ranges, { backward: !!options.lastRangeBackward } );
+		const selection = new DocumentSelection( ranges, { backward: !!options.lastRangeBackward } );
 
 		return {
 			view,
@@ -594,7 +595,8 @@ class ViewStringify {
 	 * Creates a view stringify instance.
 	 *
 	 * @param root
-	 * @param {module:engine/view/selection~Selection} selection A selection whose ranges should also be converted to a string.
+	 * @param {module:engine/view/documentselection~DocumentSelection} selection A selection whose ranges
+	 * should also be converted to a string.
 	 * @param {Object} options An options object.
 	 * @param {Boolean} [options.showType=false] When set to `true`, the type of elements will be printed (`<container:p>`
 	 * instead of `<p>`, `<attribute:b>` instead of `<b>` and `<empty:img>` instead of `<img>`).

src/view/document.js

@@ -7,14 +7,14 @@
  * @module engine/view/document
  */
 
-import Selection from './selection';
+import DocumentSelection from './documentselection';
 import Collection from '@ckeditor/ckeditor5-utils/src/collection';
 import mix from '@ckeditor/ckeditor5-utils/src/mix';
 import ObservableMixin from '@ckeditor/ckeditor5-utils/src/observablemixin';
 
 /**
  * Document class creates an abstract layer over the content editable area, contains a tree of view elements and
- * {@link module:engine/view/selection~Selection view selection} associated with this document.
+ * {@link module:engine/view/documentselection~DocumentSelection view selection} associated with this document.
  *
  * @mixes module:utils/observablemixin~ObservableMixin
  */
@@ -27,9 +27,9 @@ export default class Document {
 		 * Selection done on this document.
 		 *
 		 * @readonly
-		 * @member {module:engine/view/selection~Selection} module:engine/view/document~Document#selection
+		 * @member {module:engine/view/documentselection~DocumentSelection} module:engine/view/document~Document#selection
 		 */
-		this.selection = new Selection();
+		this.selection = new DocumentSelection();
 
 		/**
 		 * Roots of the view tree. Collection of the {module:engine/view/element~Element view elements}.