@ckeditor/ckeditor5-engine 39.0.1 → 40.0.0

package/src/model/utils/modifyselection.js

@@ -1,186 +1,186 @@
-/**
- * @license Copyright (c) 2003-2023, 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/modifyselection
- */
-import DocumentSelection from '../documentselection';
-import Position from '../position';
-import Range from '../range';
-import TreeWalker from '../treewalker';
-import { isInsideSurrogatePair, isInsideCombinedSymbol, isInsideEmojiSequence } from '@ckeditor/ckeditor5-utils';
-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 model The model in context of which the selection modification should be performed.
- * @param selection The selection to modify.
- * @param options.direction The direction in which the selection should be modified. Default 'forward'.
- * @param options.unit The unit by which selection should be modified. Default 'character'.
- * @param options.treatEmojiAsSingleUnit 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;
-    const walker = new TreeWalker({
-        boundaries: getSearchRange(focus, isForward),
-        singleCharacters: true,
-        direction: isForward ? 'forward' : 'backward'
-    });
-    const data = { walker, schema, isForward, unit, treatEmojiAsSingleUnit };
-    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).
- */
-function tryExtendingTo(data, value) {
-    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
-    // based on the unit.
-    if (type == 'text') {
-        if (data.unit === 'word') {
-            return getCorrectWordBreakPosition(walker, isForward);
-        }
-        return getCorrectPosition(walker, unit, treatEmojiAsSingleUnit);
-    }
-    // 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.
- */
-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)) ||
-            (treatEmojiAsSingleUnit && isInsideEmojiSequence(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.
- */
-function getCorrectWordBreakPosition(walker, isForward) {
-    let textNode = walker.position.textNode;
-    if (!textNode) {
-        textNode = isForward ? walker.position.nodeAfter : walker.position.nodeBefore;
-    }
-    while (textNode && textNode.is('$text')) {
-        const offset = walker.position.offset - textNode.startOffset;
-        // 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'.
-        if (isAtNodeBoundary(textNode, offset, isForward)) {
-            textNode = isForward ? walker.position.nodeAfter : walker.position.nodeBefore;
-        }
-        // Check if this is a word boundary.
-        else if (isAtWordBoundary(textNode.data, offset, isForward)) {
-            break;
-        }
-        // Maybe one more character.
-        else {
-            walker.next();
-        }
-    }
-    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.
- */
-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.
- */
-function isAtNodeBoundary(textNode, offset, isForward) {
-    return offset === (isForward ? textNode.offsetSize : 0);
-}
+/**
+ * @license Copyright (c) 2003-2023, 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/modifyselection
+ */
+import DocumentSelection from '../documentselection';
+import Position from '../position';
+import Range from '../range';
+import TreeWalker from '../treewalker';
+import { isInsideSurrogatePair, isInsideCombinedSymbol, isInsideEmojiSequence } from '@ckeditor/ckeditor5-utils';
+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 model The model in context of which the selection modification should be performed.
+ * @param selection The selection to modify.
+ * @param options.direction The direction in which the selection should be modified. Default 'forward'.
+ * @param options.unit The unit by which selection should be modified. Default 'character'.
+ * @param options.treatEmojiAsSingleUnit 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;
+    const walker = new TreeWalker({
+        boundaries: getSearchRange(focus, isForward),
+        singleCharacters: true,
+        direction: isForward ? 'forward' : 'backward'
+    });
+    const data = { walker, schema, isForward, unit, treatEmojiAsSingleUnit };
+    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).
+ */
+function tryExtendingTo(data, value) {
+    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
+    // based on the unit.
+    if (type == 'text') {
+        if (data.unit === 'word') {
+            return getCorrectWordBreakPosition(walker, isForward);
+        }
+        return getCorrectPosition(walker, unit, treatEmojiAsSingleUnit);
+    }
+    // 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.
+ */
+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)) ||
+            (treatEmojiAsSingleUnit && isInsideEmojiSequence(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.
+ */
+function getCorrectWordBreakPosition(walker, isForward) {
+    let textNode = walker.position.textNode;
+    if (!textNode) {
+        textNode = isForward ? walker.position.nodeAfter : walker.position.nodeBefore;
+    }
+    while (textNode && textNode.is('$text')) {
+        const offset = walker.position.offset - textNode.startOffset;
+        // 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'.
+        if (isAtNodeBoundary(textNode, offset, isForward)) {
+            textNode = isForward ? walker.position.nodeAfter : walker.position.nodeBefore;
+        }
+        // Check if this is a word boundary.
+        else if (isAtWordBoundary(textNode.data, offset, isForward)) {
+            break;
+        }
+        // Maybe one more character.
+        else {
+            walker.next();
+        }
+    }
+    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.
+ */
+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.
+ */
+function isAtNodeBoundary(textNode, offset, isForward) {
+    return offset === (isForward ? textNode.offsetSize : 0);
+}

package/src/model/utils/selection-post-fixer.d.ts

@@ -1,74 +1,74 @@
-/**
- * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
- * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
- */
-import Range from '../range';
-import type Model from '../model';
-import type Schema from '../schema';
-/**
- * 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.
- */
-export declare function injectSelectionPostFixer(model: Model): void;
-/**
- * Tries fixing a range if it's incorrect.
- *
- * **Note:** This helper is used by the selection post-fixer and to fix the `beforeinput` target ranges.
- *
- * @returns Returns fixed range or null if range is valid.
- */
-export declare function tryFixingRange(range: Range, schema: Schema): Range | null;
-/**
- * Returns a minimal non-intersecting array of ranges without duplicates.
- *
- * @param ranges Ranges to merge.
- * @returns Array of unique and non-intersecting ranges.
- */
-export declare function mergeIntersectingRanges(ranges: Array<Range>): Array<Range>;
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import Range from '../range';
+import type Model from '../model';
+import type Schema from '../schema';
+/**
+ * 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.
+ */
+export declare function injectSelectionPostFixer(model: Model): void;
+/**
+ * Tries fixing a range if it's incorrect.
+ *
+ * **Note:** This helper is used by the selection post-fixer and to fix the `beforeinput` target ranges.
+ *
+ * @returns Returns fixed range or null if range is valid.
+ */
+export declare function tryFixingRange(range: Range, schema: Schema): Range | null;
+/**
+ * Returns a minimal non-intersecting array of ranges without duplicates.
+ *
+ * @param ranges Ranges to merge.
+ * @returns Array of unique and non-intersecting ranges.
+ */
+export declare function mergeIntersectingRanges(ranges: Array<Range>): Array<Range>;