@ckeditor/ckeditor5-engine 30.0.0

package/src/model/utils/modifyselection.js

@@ -0,0 +1,229 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/model/utils/modifyselection
+ */
+
+import Position from '../position';
+import TreeWalker from '../treewalker';
+import Range from '../range';
+import { isInsideSurrogatePair, isInsideCombinedSymbol } from '@ckeditor/ckeditor5-utils/src/unicode';
+import DocumentSelection from '../documentselection';
+
+const wordBoundaryCharacters = ' ,.?!:;"-()';
+
+/**
+ * Modifies the selection. Currently, the supported modifications are:
+ *
+ * * Extending. The selection focus is moved in the specified `options.direction` with a step specified in `options.unit`.
+ * Possible values for `unit` are:
+ *  * `'character'` (default) - moves selection by one user-perceived character. In most cases this means moving by one
+ *  character in `String` sense. However, unicode also defines "combing marks". These are special symbols, that combines
+ *  with a symbol before it ("base character") to create one user-perceived character. For example, `q̣̇` is a normal
+ *  letter `q` with two "combining marks": upper dot (`Ux0307`) and lower dot (`Ux0323`). For most actions, i.e. extending
+ *  selection by one position, it is correct to include both "base character" and all of it's "combining marks". That is
+ *  why `'character'` value is most natural and common method of modifying selection.
+ *  * `'codePoint'` - moves selection by one unicode code point. In contrary to, `'character'` unit, this will insert
+ *  selection between "base character" and "combining mark", because "combining marks" have their own unicode code points.
+ *  However, for technical reasons, unicode code points with values above `UxFFFF` are represented in native `String` by
+ *  two characters, called "surrogate pairs". Halves of "surrogate pairs" have a meaning only when placed next to each other.
+ *  For example `𨭎` is represented in `String` by `\uD862\uDF4E`. Both `\uD862` and `\uDF4E` do not have any meaning
+ *  outside the pair (are rendered as ? when alone). Position between them would be incorrect. In this case, selection
+ *  extension will include whole "surrogate pair".
+ *  * `'word'` - moves selection by a whole word.
+ *
+ * **Note:** if you extend a forward selection in a backward direction you will in fact shrink it.
+ *
+ * **Note:** Use {@link module:engine/model/model~Model#modifySelection} instead of this function.
+ * This function is only exposed to be reusable in algorithms
+ * which change the {@link module:engine/model/model~Model#modifySelection}
+ * method's behavior.
+ *
+ * @param {module:engine/model/model~Model} model The model in context of which
+ * the selection modification should be performed.
+ * @param {module:engine/model/selection~Selection|module:engine/model/documentselection~DocumentSelection} selection
+ * The selection to modify.
+ * @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.
+ */
+export default function modifySelection( model, selection, options = {} ) {
+	const schema = model.schema;
+	const isForward = options.direction != 'backward';
+	const unit = options.unit ? options.unit : 'character';
+
+	const focus = selection.focus;
+
+	const walker = new TreeWalker( {
+		boundaries: getSearchRange( focus, isForward ),
+		singleCharacters: true,
+		direction: isForward ? 'forward' : 'backward'
+	} );
+
+	const data = { walker, schema, isForward, unit };
+
+	let next;
+
+	while ( ( next = walker.next() ) ) {
+		if ( next.done ) {
+			return;
+		}
+
+		const position = tryExtendingTo( data, next.value );
+
+		if ( position ) {
+			if ( selection instanceof DocumentSelection ) {
+				model.change( writer => {
+					writer.setSelectionFocus( position );
+				} );
+			} else {
+				selection.setFocus( position );
+			}
+
+			return;
+		}
+	}
+}
+
+// Checks whether the selection can be extended to the the walker's next value (next position).
+// @param {{ walker, unit, isForward, schema }} data
+// @param {module:engine/view/treewalker~TreeWalkerValue} value
+function tryExtendingTo( data, value ) {
+	const { isForward, walker, unit, schema } = data;
+	const { type, item, nextPosition } = value;
+
+	// If found text, we can certainly put the focus in it. Let's just find a correct position
+	// based on the unit.
+	if ( type == 'text' ) {
+		if ( data.unit === 'word' ) {
+			return getCorrectWordBreakPosition( walker, isForward );
+		}
+
+		return getCorrectPosition( walker, unit, isForward );
+	}
+
+	// Entering an element.
+	if ( type == ( isForward ? 'elementStart' : 'elementEnd' ) ) {
+		// If it's a selectable, we can select it now.
+		if ( schema.isSelectable( item ) ) {
+			return Position._createAt( item, isForward ? 'after' : 'before' );
+		}
+
+		// If text allowed on this position, extend to this place.
+		if ( schema.checkChild( nextPosition, '$text' ) ) {
+			return nextPosition;
+		}
+	}
+	// Leaving an element.
+	else {
+		// If leaving a limit element, stop.
+		if ( schema.isLimit( item ) ) {
+			// NOTE: Fast-forward the walker until the end.
+			walker.skip( () => true );
+
+			return;
+		}
+
+		// If text allowed on this position, extend to this place.
+		if ( schema.checkChild( nextPosition, '$text' ) ) {
+			return nextPosition;
+		}
+	}
+}
+
+// Finds a correct position by walking in a text node and checking whether selection can be extended to given position
+// or should be extended further.
+//
+// @param {module:engine/model/treewalker~TreeWalker} walker
+// @param {String} unit The unit by which selection should be modified.
+function getCorrectPosition( walker, unit ) {
+	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 ) ) ) {
+			walker.next();
+
+			offset = walker.position.offset - textNode.startOffset;
+		}
+	}
+
+	return walker.position;
+}
+
+// Finds a correct position of a word break by walking in a text node and checking whether selection can be extended to given position
+// or should be extended further.
+//
+// @param {module:engine/model/treewalker~TreeWalker} walker
+// @param {Boolean} isForward Is the direction in which the selection should be modified is forward.
+function getCorrectWordBreakPosition( walker, isForward ) {
+	let textNode = walker.position.textNode;
+
+	if ( textNode ) {
+		let offset = walker.position.offset - textNode.startOffset;
+
+		while ( !isAtWordBoundary( textNode.data, offset, isForward ) && !isAtNodeBoundary( textNode, offset, isForward ) ) {
+			walker.next();
+
+			// Check of adjacent text nodes with different attributes (like BOLD).
+			// Example          : 'foofoo []bar<$text bold="true">bar</$text> bazbaz'
+			// should expand to : 'foofoo [bar<$text bold="true">bar</$text>] bazbaz'.
+			const nextNode = isForward ? walker.position.nodeAfter : walker.position.nodeBefore;
+
+			// Scan only text nodes. Ignore inline elements (like `<softBreak>`).
+			if ( nextNode && nextNode.is( '$text' ) ) {
+				// Check boundary char of an adjacent text node.
+				const boundaryChar = nextNode.data.charAt( isForward ? 0 : nextNode.data.length - 1 );
+
+				// Go to the next node if the character at the boundary of that node belongs to the same word.
+				if ( !wordBoundaryCharacters.includes( boundaryChar ) ) {
+					// If adjacent text node belongs to the same word go to it & reset values.
+					walker.next();
+
+					textNode = walker.position.textNode;
+				}
+			}
+
+			offset = walker.position.offset - textNode.startOffset;
+		}
+	}
+
+	return walker.position;
+}
+
+function getSearchRange( start, isForward ) {
+	const root = start.root;
+	const searchEnd = Position._createAt( root, isForward ? 'end' : 0 );
+
+	if ( isForward ) {
+		return new Range( start, searchEnd );
+	} else {
+		return new Range( searchEnd, start );
+	}
+}
+
+// Checks if selection is on word boundary.
+//
+// @param {String} data The text node value to investigate.
+// @param {Number} offset Position offset.
+// @param {Boolean} isForward Is the direction in which the selection should be modified is forward.
+function isAtWordBoundary( data, offset, isForward ) {
+	// The offset to check depends on direction.
+	const offsetToCheck = offset + ( isForward ? 0 : -1 );
+
+	return wordBoundaryCharacters.includes( data.charAt( offsetToCheck ) );
+}
+
+// Checks if selection is on node boundary.
+//
+// @param {module:engine/model/text~Text} textNode The text node to investigate.
+// @param {Number} offset Position offset.
+// @param {Boolean} isForward Is the direction in which the selection should be modified is forward.
+function isAtNodeBoundary( textNode, offset, isForward ) {
+	return offset === ( isForward ? textNode.endOffset : 0 );
+}

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

@@ -0,0 +1,297 @@
+/**
+ * @license Copyright (c) 2003-2021, CKSource - Frederico Knabben. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+
+/**
+ * @module engine/model/utils/selection-post-fixer
+ */
+
+import Range from '../range';
+import Position from '../position';
+
+/**
+ * Injects selection post-fixer to the model.
+ *
+ * The role of the selection post-fixer is to ensure that the selection is in a correct place
+ * after a {@link module:engine/model/model~Model#change `change()`} block was executed.
+ *
+ * The correct position means that:
+ *
+ * * All collapsed selection ranges are in a place where the {@link module:engine/model/schema~Schema}
+ * allows a `$text`.
+ * * None of the selection's non-collapsed ranges crosses a {@link module:engine/model/schema~Schema#isLimit limit element}
+ * boundary (a range must be rooted within one limit element).
+ * * Only {@link module:engine/model/schema~Schema#isSelectable selectable elements} can be selected from the outside
+ * (e.g. `[<paragraph>foo</paragraph>]` is invalid). This rule applies independently to both selection ends, so this
+ * selection is correct: `<paragraph>f[oo</paragraph><imageBlock></imageBlock>]`.
+ *
+ * If the position is not correct, the post-fixer will automatically correct it.
+ *
+ * ## Fixing a non-collapsed selection
+ *
+ * See as an example a selection that starts in a P1 element and ends inside the text of a TD element
+ * (`[` and `]` are range boundaries and `(l)` denotes an element defined as `isLimit=true`):
+ *
+ *		root
+ *		 |- element P1
+ *		 |   |- "foo"                                      root
+ *		 |- element TABLE (l)                   P1         TABLE             P2
+ *		 |   |- element TR (l)                 f o[o     TR      TR         b a r
+ *		 |   |   |- element TD (l)                       TD      TD
+ *		 |   |       |- "aaa"                          a]a a    b b b
+ *		 |   |- element TR (l)
+ *		 |   |   |- element TD (l)                           ||
+ *		 |   |       |- "bbb"                                ||
+ *		 |- element P2                                       VV
+ *		 |   |- "bar"
+ *		                                                   root
+ *		                                        P1         TABLE]            P2
+ *		                                       f o[o     TR      TR         b a r
+ *		                                                 TD      TD
+ *		                                               a a a    b b b
+ *
+ * In the example above, the TABLE, TR and TD are defined as `isLimit=true` in the schema. The range which is not contained within
+ * a single limit element must be expanded to select the outermost limit element. The range end is inside the text node of the TD element.
+ * As the TD element is a child of the TR and TABLE elements, where both are defined as `isLimit=true` in the schema, the range must be
+ * expanded to select the whole TABLE element.
+ *
+ * **Note** If the selection contains multiple ranges, the method returns a minimal set of ranges that are not intersecting after expanding
+ * them to select `isLimit=true` elements.
+ *
+ * @param {module:engine/model/model~Model} model
+ */
+export function injectSelectionPostFixer( model ) {
+	model.document.registerPostFixer( writer => selectionPostFixer( writer, model ) );
+}
+
+// The selection post-fixer.
+//
+// @param {module:engine/model/writer~Writer} writer
+// @param {module:engine/model/model~Model} model
+function selectionPostFixer( writer, model ) {
+	const selection = model.document.selection;
+	const schema = model.schema;
+
+	const ranges = [];
+
+	let wasFixed = false;
+
+	for ( const modelRange of selection.getRanges() ) {
+		// Go through all ranges in selection and try fixing each of them.
+		// Those ranges might overlap but will be corrected later.
+		const correctedRange = tryFixingRange( modelRange, schema );
+
+		// "Selection fixing" algorithms sometimes get lost. In consequence, it may happen
+		// that a new range is returned but, in fact, it has the same positions as the original
+		// range anyway. If this range is not discarded, a new selection will be set and that,
+		// for instance, would destroy the selection attributes. Let's make sure that the post-fixer
+		// actually worked first before setting a new selection.
+		//
+		// https://github.com/ckeditor/ckeditor5/issues/6693
+		if ( correctedRange && !correctedRange.isEqual( modelRange ) ) {
+			ranges.push( correctedRange );
+			wasFixed = true;
+		} else {
+			ranges.push( modelRange );
+		}
+	}
+
+	// If any of ranges were corrected update the selection.
+	if ( wasFixed ) {
+		writer.setSelection( mergeIntersectingRanges( ranges ), { backward: selection.isBackward } );
+	}
+}
+
+// Tries fixing a range if it's incorrect.
+//
+// @param {module:engine/model/range~Range} range
+// @param {module:engine/model/schema~Schema} schema
+// @returns {module:engine/model/range~Range|null} Returns fixed range or null if range is valid.
+function tryFixingRange( range, schema ) {
+	if ( range.isCollapsed ) {
+		return tryFixingCollapsedRange( range, schema );
+	}
+
+	return tryFixingNonCollapsedRage( range, schema );
+}
+
+// Tries to fix collapsed ranges.
+//
+// * Fixes situation when a range is in a place where $text is not allowed
+//
+// @param {module:engine/model/range~Range} range Collapsed range to fix.
+// @param {module:engine/model/schema~Schema} schema
+// @returns {module:engine/model/range~Range|null} Returns fixed range or null if range is valid.
+function tryFixingCollapsedRange( range, schema ) {
+	const originalPosition = range.start;
+
+	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.
+	if ( !nearestSelectionRange ) {
+		return null;
+	}
+
+	if ( !nearestSelectionRange.isCollapsed ) {
+		return nearestSelectionRange;
+	}
+
+	const fixedPosition = nearestSelectionRange.start;
+
+	// Fixed position is the same as original - no need to return corrected range.
+	if ( originalPosition.isEqual( fixedPosition ) ) {
+		return null;
+	}
+
+	return new Range( fixedPosition );
+}
+
+// Tries to fix an expanded range.
+//
+// @param {module:engine/model/range~Range} range Expanded range to fix.
+// @param {module:engine/model/schema~Schema} schema
+// @returns {module:engine/model/range~Range|null} Returns fixed range or null if range is valid.
+function tryFixingNonCollapsedRage( range, schema ) {
+	const { start, end } = range;
+
+	const isTextAllowedOnStart = schema.checkChild( start, '$text' );
+	const isTextAllowedOnEnd = schema.checkChild( end, '$text' );
+
+	const startLimitElement = schema.getLimitElement( start );
+	const endLimitElement = schema.getLimitElement( end );
+
+	// Ranges which both end are inside the same limit element (or root) might needs only minor fix.
+	if ( startLimitElement === endLimitElement ) {
+		// Range is valid when both position allows to place a text:
+		// - <block>f[oobarba]z</block>
+		// This would be "fixed" by a next check but as it will be the same it's better to return null so the selection stays the same.
+		if ( isTextAllowedOnStart && isTextAllowedOnEnd ) {
+			return null;
+		}
+
+		// Range that is on non-limit element (or is partially) must be fixed so it is placed inside the block around $text:
+		// - [<block>foo</block>]    ->    <block>[foo]</block>
+		// - [<block>foo]</block>    ->    <block>[foo]</block>
+		// - <block>f[oo</block>]    ->    <block>f[oo]</block>
+		// - [<block>foo</block><selectable></selectable>]    ->    <block>[foo</block><selectable></selectable>]
+		if ( checkSelectionOnNonLimitElements( start, end, schema ) ) {
+			const isStartBeforeSelectable = start.nodeAfter && schema.isSelectable( start.nodeAfter );
+			const fixedStart = isStartBeforeSelectable ? null : schema.getNearestSelectionRange( start, 'forward' );
+
+			const isEndAfterSelectable = end.nodeBefore && schema.isSelectable( end.nodeBefore );
+			const fixedEnd = isEndAfterSelectable ? null : schema.getNearestSelectionRange( end, 'backward' );
+
+			// The schema.getNearestSelectionRange might return null - if that happens use original position.
+			const rangeStart = fixedStart ? fixedStart.start : start;
+			const rangeEnd = fixedEnd ? fixedEnd.end : end;
+
+			return new Range( rangeStart, rangeEnd );
+		}
+	}
+
+	const isStartInLimit = startLimitElement && !startLimitElement.is( 'rootElement' );
+	const isEndInLimit = endLimitElement && !endLimitElement.is( 'rootElement' );
+
+	// At this point we eliminated valid positions on text nodes so if one of range positions is placed inside a limit element
+	// then the range crossed limit element boundaries and needs to be fixed.
+	if ( isStartInLimit || isEndInLimit ) {
+		const bothInSameParent = ( start.nodeAfter && end.nodeBefore ) && start.nodeAfter.parent === end.nodeBefore.parent;
+
+		const expandStart = isStartInLimit && ( !bothInSameParent || !isSelectable( start.nodeAfter, schema ) );
+		const expandEnd = isEndInLimit && ( !bothInSameParent || !isSelectable( end.nodeBefore, schema ) );
+
+		// Although we've already found limit element on start/end positions we must find the outer-most limit element.
+		// as limit elements might be nested directly inside (ie table > tableRow > tableCell).
+		let fixedStart = start;
+		let fixedEnd = end;
+
+		if ( expandStart ) {
+			fixedStart = Position._createBefore( findOutermostLimitAncestor( startLimitElement, schema ) );
+		}
+
+		if ( expandEnd ) {
+			fixedEnd = Position._createAfter( findOutermostLimitAncestor( endLimitElement, schema ) );
+		}
+
+		return new Range( fixedStart, fixedEnd );
+	}
+
+	// Range was not fixed at this point so it is valid - ie it was placed around limit element already.
+	return null;
+}
+
+// Finds the outer-most ancestor.
+//
+// @param {module:engine/model/node~Node} startingNode
+// @param {module:engine/model/schema~Schema} schema
+// @param {String} expandToDirection Direction of expansion - either 'start' or 'end' of the range.
+// @returns {module:engine/model/node~Node}
+function findOutermostLimitAncestor( startingNode, schema ) {
+	let isLimitNode = startingNode;
+	let parent = isLimitNode;
+
+	// Find outer most isLimit block as such blocks might be nested (ie. in tables).
+	while ( schema.isLimit( parent ) && parent.parent ) {
+		isLimitNode = parent;
+		parent = parent.parent;
+	}
+
+	return isLimitNode;
+}
+
+// Checks whether any of range boundaries is placed around non-limit elements.
+//
+// @param {module:engine/model/position~Position} start
+// @param {module:engine/model/position~Position} end
+// @param {module:engine/model/schema~Schema} schema
+// @returns {Boolean}
+function checkSelectionOnNonLimitElements( start, end, schema ) {
+	const startIsOnBlock = ( start.nodeAfter && !schema.isLimit( start.nodeAfter ) ) || schema.checkChild( start, '$text' );
+	const endIsOnBlock = ( end.nodeBefore && !schema.isLimit( end.nodeBefore ) ) || schema.checkChild( end, '$text' );
+
+	// We should fix such selection when one of those nodes needs fixing.
+	return startIsOnBlock || endIsOnBlock;
+}
+
+// Returns a minimal non-intersecting array of ranges.
+//
+// @param {Array.<module:engine/model/range~Range>} ranges
+// @returns {Array.<module:engine/model/range~Range>}
+function mergeIntersectingRanges( ranges ) {
+	const nonIntersectingRanges = [];
+
+	// First range will always be fine.
+	nonIntersectingRanges.push( ranges.shift() );
+
+	for ( const range of ranges ) {
+		const previousRange = nonIntersectingRanges.pop();
+
+		if ( range.isEqual( previousRange ) ) {
+			// Use only one of two identical ranges.
+			nonIntersectingRanges.push( previousRange );
+		} else if ( range.isIntersecting( previousRange ) ) {
+			// Get the sum of two ranges.
+			const start = previousRange.start.isAfter( range.start ) ? range.start : previousRange.start;
+			const end = previousRange.end.isAfter( range.end ) ? previousRange.end : range.end;
+
+			const merged = new Range( start, end );
+			nonIntersectingRanges.push( merged );
+		} else {
+			nonIntersectingRanges.push( previousRange );
+			nonIntersectingRanges.push( range );
+		}
+	}
+
+	return nonIntersectingRanges;
+}
+
+// Checks if node exists and if it's a selectable.
+//
+// @param {module:engine/model/node~Node} node
+// @param {module:engine/model/schema~Schema} schema
+// @returns {Boolean}
+function isSelectable( node, schema ) {
+	return node && schema.isSelectable( node );
+}