@ckeditor/ckeditor5-engine 45.0.0-alpha.9 → 45.1.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-engine",
-  "version": "45.0.0-alpha.9",
+  "version": "45.1.0-alpha.0",
   "description": "The editing engine of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "wysiwyg",
@@ -24,7 +24,7 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-utils": "45.0.0-alpha.9",
+    "@ckeditor/ckeditor5-utils": "45.1.0-alpha.0",
     "es-toolkit": "1.32.0"
   },
   "author": "CKSource (http://cksource.com/)",

package/src/controller/editingcontroller.js

@@ -158,7 +158,7 @@ export default class EditingController extends /* #__PURE__ */ ObservableMixin()
              * The marker with the provided name does not exist and cannot be reconverted.
              *
              * @error editingcontroller-reconvertmarker-marker-not-exist
-             * @param {String} markerName The name of the reconverted marker.
+             * @param {string} markerName The name of the reconverted marker.
              */
             throw new CKEditorError('editingcontroller-reconvertmarker-marker-not-exist', this, { markerName });
         }

package/src/conversion/conversion.d.ts

@@ -470,7 +470,10 @@ export default class Conversion {
     /**
      * Creates and caches conversion helpers for given dispatchers group.
      *
+     * @param options Group name.
      * @param options.name Group name.
+     * @param options.dispatchers Dispatchers to register.
+     * @param options.isDowncast Whether downcast group.
      */
     private _createConversionHelpers;
 }

package/src/conversion/conversion.js

@@ -559,7 +559,10 @@ export default class Conversion {
     /**
      * Creates and caches conversion helpers for given dispatchers group.
      *
+     * @param options Group name.
      * @param options.name Group name.
+     * @param options.dispatchers Dispatchers to register.
+     * @param options.isDowncast Whether downcast group.
      */
     _createConversionHelpers({ name, dispatchers, isDowncast }) {
         if (this._helpers.has(name)) {

package/src/conversion/downcasthelpers.d.ts

@@ -169,13 +169,10 @@ export default class DowncastHelpers extends ConversionHelpers<DowncastDispatche
      *
      * @param config Conversion configuration.
      * @param config.model The description or a name of the model element to convert.
-     * @param config.model.attributes The list of attribute names that should be consumed while creating
-     * the view element. Note that the view will be reconverted if any of the listed attributes changes.
-     * @param config.model.children Specifies whether the view element requires reconversion if the list
-     * of the model child nodes changed.
      * @param config.view A view element definition or a function that takes the model element and
      * {@link module:engine/conversion/downcastdispatcher~DowncastConversionApi downcast conversion API}
      * as parameters and returns a view container element.
+     * @param config.converterPriority Converter priority.
      */
     elementToElement(config: {
         model: string | {
@@ -290,12 +287,10 @@ export default class DowncastHelpers extends ConversionHelpers<DowncastDispatche
      *
      * @param config Conversion configuration.
      * @param config.model The description or a name of the model element to convert.
-     * @param config.model.name The name of the model element to convert.
-     * @param config.model.attributes The list of attribute names that should be consumed while creating
-     * the view structure. Note that the view will be reconverted if any of the listed attributes will change.
      * @param config.view A function that takes the model element and
      * {@link module:engine/conversion/downcastdispatcher~DowncastConversionApi downcast conversion API} as parameters
      * and returns a view container element with slots for model child nodes to be converted into.
+     * @param config.converterPriority Converter priority.
      */
     elementToStructure(config: {
         model: string | {

package/src/conversion/downcasthelpers.js

@@ -161,13 +161,10 @@ export default class DowncastHelpers extends ConversionHelpers {
      *
      * @param config Conversion configuration.
      * @param config.model The description or a name of the model element to convert.
-     * @param config.model.attributes The list of attribute names that should be consumed while creating
-     * the view element. Note that the view will be reconverted if any of the listed attributes changes.
-     * @param config.model.children Specifies whether the view element requires reconversion if the list
-     * of the model child nodes changed.
      * @param config.view A view element definition or a function that takes the model element and
      * {@link module:engine/conversion/downcastdispatcher~DowncastConversionApi downcast conversion API}
      * as parameters and returns a view container element.
+     * @param config.converterPriority Converter priority.
      */
     elementToElement(config) {
         return this.add(downcastElementToElement(config));
@@ -276,12 +273,10 @@ export default class DowncastHelpers extends ConversionHelpers {
      *
      * @param config Conversion configuration.
      * @param config.model The description or a name of the model element to convert.
-     * @param config.model.name The name of the model element to convert.
-     * @param config.model.attributes The list of attribute names that should be consumed while creating
-     * the view structure. Note that the view will be reconverted if any of the listed attributes will change.
      * @param config.view A function that takes the model element and
      * {@link module:engine/conversion/downcastdispatcher~DowncastConversionApi downcast conversion API} as parameters
      * and returns a view container element with slots for model child nodes to be converted into.
+     * @param config.converterPriority Converter priority.
      */
     elementToStructure(config) {
         return this.add(downcastElementToStructure(config));
@@ -1348,6 +1343,7 @@ function changeAttribute(attributeCreator) {
              * ```
              *
              * @error conversion-attribute-to-attribute-on-text
+             * @param {object} data The conversion data.
              */
             throw new CKEditorError('conversion-attribute-to-attribute-on-text', conversionApi.dispatcher, data);
         }
@@ -1610,7 +1606,7 @@ function downcastElementToStructure(config) {
              * ```
              *
              * @error conversion-element-to-structure-disallowed-text
-             * @param {String} elementName The name of the element the structure is to be created for.
+             * @param {string} elementName The name of the element the structure is to be created for.
              */
             throw new CKEditorError('conversion-element-to-structure-disallowed-text', dispatcher, { elementName: model.name });
         }
@@ -1999,9 +1995,9 @@ function createConsumer(model) {
     };
 }
 /**
- * Creates a function that create view slots.
+ * Creates a function that creates view slots.
  *
- * @returns Function exposed by writer as createSlot().
+ * @returns Function exposed by the writer as `createSlot()`.
  */
 function createSlotFactory(element, slotsMap, conversionApi) {
     return (writer, modeOrFilter) => {
@@ -2015,9 +2011,10 @@ function createSlotFactory(element, slotsMap, conversionApi) {
         }
         else {
             /**
-             * Unknown slot mode was provided to `writer.createSlot()` in downcast converter.
+             * Unknown slot mode was provided to `writer.createSlot()` in the downcast converter.
              *
              * @error conversion-slot-mode-unknown
+             * @param {never} modeOrFilter The specified mode or filter.
              */
             throw new CKEditorError('conversion-slot-mode-unknown', conversionApi.dispatcher, { modeOrFilter });
         }

package/src/dev-utils/utils.js

@@ -107,6 +107,7 @@ export function logDocument(document, version) {
 // @if CK_DEBUG_TYPING // 		editor.editing.view.domConverter,
 // @if CK_DEBUG_TYPING // 		...editor.editing.view._observers.values(),
 // @if CK_DEBUG_TYPING // 		editor.plugins.get( 'Input' ),
+// @if CK_DEBUG_TYPING // 		editor.plugins.get( 'Input' )._typingQueue,
 // @if CK_DEBUG_TYPING // 		editor.plugins.get( 'WidgetTypeAround' ),
 // @if CK_DEBUG_TYPING // 		editor.commands.get( 'delete' ),
 // @if CK_DEBUG_TYPING // 		editor.commands.get( 'deleteForward' )

package/src/dev-utils/view.d.ts

@@ -19,6 +19,7 @@ import type DomConverter from '../view/domconverter.js';
 /**
  * Writes the content of the {@link module:engine/view/document~Document document} to an HTML-like string.
  *
+ * @param view The view to stringify.
  * @param options.withoutSelection Whether to write the selection. When set to `true`, the selection will
  * not be included in the returned string.
  * @param options.rootName The name of the root from which the data should be stringified. If not provided,
@@ -27,8 +28,6 @@ import type DomConverter from '../view/domconverter.js';
  * instead of `<p>`, `<attribute:b>` instead of `<b>` and `<empty:img>` instead of `<img>`).
  * @param options.showPriority When set to `true`, the attribute element's priority will be printed
  * (`<span view-priority="12">`, `<b view-priority="10">`).
- * @param options.showAttributeElementId When set to `true`, the attribute element's ID will be printed
- * (`<span id="marker:foo">`).
  * @param options.renderUIElements When set to `true`, the inner content of each
  * {@link module:engine/view/uielement~UIElement} will be printed.
  * @param options.renderRawElements When set to `true`, the inner content of each
@@ -304,7 +303,6 @@ export declare function stringify(node: ViewNode | ViewDocumentFragment, selecti
  * this node will be used as the root for all parsed nodes.
  * @param options.sameSelectionCharacters When set to `false`, the selection inside the text should be marked using
  * `{` and `}` and the selection outside the ext using `[` and `]`. When set to `true`, both should be marked with `[` and `]` only.
- * @param options.stylesProcessor Styles processor.
  * @returns Returns the parsed view node or an object with two fields: `view` and `selection` when selection ranges were included in the
  * data to parse.
  */

package/src/dev-utils/view.js

@@ -44,6 +44,7 @@ const domConverterStub = {
 /**
  * Writes the content of the {@link module:engine/view/document~Document document} to an HTML-like string.
  *
+ * @param view The view to stringify.
  * @param options.withoutSelection Whether to write the selection. When set to `true`, the selection will
  * not be included in the returned string.
  * @param options.rootName The name of the root from which the data should be stringified. If not provided,
@@ -52,8 +53,6 @@ const domConverterStub = {
  * instead of `<p>`, `<attribute:b>` instead of `<b>` and `<empty:img>` instead of `<img>`).
  * @param options.showPriority When set to `true`, the attribute element's priority will be printed
  * (`<span view-priority="12">`, `<b view-priority="10">`).
- * @param options.showAttributeElementId When set to `true`, the attribute element's ID will be printed
- * (`<span id="marker:foo">`).
  * @param options.renderUIElements When set to `true`, the inner content of each
  * {@link module:engine/view/uielement~UIElement} will be printed.
  * @param options.renderRawElements When set to `true`, the inner content of each
@@ -351,7 +350,6 @@ export function stringify(node, selectionOrPositionOrRange = null, options = {})
  * this node will be used as the root for all parsed nodes.
  * @param options.sameSelectionCharacters When set to `false`, the selection inside the text should be marked using
  * `{` and `}` and the selection outside the ext using `[` and `]`. When set to `true`, both should be marked with `[` and `]` only.
- * @param options.stylesProcessor Styles processor.
  * @returns Returns the parsed view node or an object with two fields: `view` and `selection` when selection ranges were included in the
  * data to parse.
  */

package/src/model/documentselection.js

@@ -612,7 +612,7 @@ class LiveSelection extends Selection {
              * UID obtained from the {@link module:engine/model/writer~Writer#overrideSelectionGravity} to restore.
              *
              * @error document-selection-gravity-wrong-restore
-             * @param uid The unique identifier returned by
+             * @param {string} uid The unique identifier returned by
              * {@link module:engine/model/documentselection~DocumentSelection#_overrideGravity}.
              */
             throw new CKEditorError('document-selection-gravity-wrong-restore', this, { uid });
@@ -649,7 +649,7 @@ class LiveSelection extends Selection {
                  * starts or ends at incorrect position.
                  *
                  * @error document-selection-wrong-position
-                 * @param range
+                 * @param {module:engine/model/range~Range} range The invalid range.
                  */
                 throw new CKEditorError('document-selection-wrong-position', this, { range });
             }

package/src/model/history.js

@@ -77,7 +77,8 @@ export default class History {
              * Only operations with matching versions can be added to the history.
              *
              * @error model-document-history-addoperation-incorrect-version
-             * @param errorData The operation and the current document history version.
+             * @param {module:engine/model/operation/operation~Operation} operation The current operation.
+             * @param {number} historyVersion The current document history version.
              */
             throw new CKEditorError('model-document-history-addoperation-incorrect-version', this, {
                 operation,

package/src/model/nodelist.js

@@ -121,8 +121,8 @@ export default class NodeList {
              * Given offset cannot be found in the node list.
              *
              * @error model-nodelist-offset-out-of-bounds
-             * @param offset
-             * @param nodeList Stringified node list.
+             * @param {number} offset The offset value.
+             * @param {module:engine/model/nodelist~NodeList} nodeList Stringified node list.
              */
             throw new CKEditorError('model-nodelist-offset-out-of-bounds', this, {
                 offset,

package/src/model/operation/attributeoperation.js

@@ -125,9 +125,9 @@ export default class AttributeOperation extends Operation {
                  * Changed node has different attribute value than operation's old attribute value.
                  *
                  * @error attribute-operation-wrong-old-value
-                 * @param item
-                 * @param key
-                 * @param value
+                 * @param {module:engine/model/item~Item} root The item element.
+                 * @param {string} key The key of the attribute.
+                 * @param {never} value The value.
                  */
                 throw new CKEditorError('attribute-operation-wrong-old-value', this, { item, key: this.key, value: this.oldValue });
             }
@@ -136,8 +136,8 @@ export default class AttributeOperation extends Operation {
                  * The attribute with given key already exists for the given node.
                  *
                  * @error attribute-operation-attribute-exists
-                 * @param node
-                 * @param key
+                 * @param {module:engine/model/item~Item} root The item element.
+                 * @param {string} key The key of the attribute.
                  */
                 throw new CKEditorError('attribute-operation-attribute-exists', this, { node: item, key: this.key });
             }

package/src/model/operation/operation.d.ts

@@ -93,7 +93,7 @@ export default abstract class Operation {
      * Creates `Operation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
-     * @param doc Document on which this operation will be applied.
+     * @param document Document on which this operation will be applied.
      */
     static fromJSON(json: any, document: Document): Operation;
 }

package/src/model/operation/operation.js

@@ -70,7 +70,7 @@ export default class Operation {
      * Creates `Operation` object from deserialized object, i.e. from parsed JSON string.
      *
      * @param json Deserialized JSON object.
-     * @param doc Document on which this operation will be applied.
+     * @param document Document on which this operation will be applied.
      */
     static fromJSON(json, document) {
         return new this(json.baseVersion);

package/src/model/operation/rootattributeoperation.js

@@ -100,9 +100,8 @@ export default class RootAttributeOperation extends Operation {
              * The element to change is not a root element.
              *
              * @error rootattribute-operation-not-a-root
-             * @param root
-             * @param key
-             * @param value
+             * @param {module:engine/model/rootelement~RootElement} root The root element.
+             * @param {string} key The key of the attribute.
              */
             throw new CKEditorError('rootattribute-operation-not-a-root', this, { root: this.root, key: this.key });
         }
@@ -111,9 +110,8 @@ export default class RootAttributeOperation extends Operation {
              * The attribute which should be removed does not exist for the given node.
              *
              * @error rootattribute-operation-wrong-old-value
-             * @param root
-             * @param key
-             * @param value
+             * @param {module:engine/model/rootelement~RootElement} root The root element.
+             * @param {string} key The key of the attribute.
              */
             throw new CKEditorError('rootattribute-operation-wrong-old-value', this, { root: this.root, key: this.key });
         }
@@ -122,8 +120,8 @@ export default class RootAttributeOperation extends Operation {
              * The attribute with given key already exists for the given node.
              *
              * @error rootattribute-operation-attribute-exists
-             * @param root
-             * @param key
+             * @param {module:engine/model/rootelement~RootElement} root The root element.
+             * @param {string} key The key of the attribute.
              */
             throw new CKEditorError('rootattribute-operation-attribute-exists', this, { root: this.root, key: this.key });
         }
@@ -163,10 +161,10 @@ export default class RootAttributeOperation extends Operation {
     static fromJSON(json, document) {
         if (!document.getRoot(json.root)) {
             /**
-             * Cannot create RootAttributeOperation for document. Root with specified name does not exist.
+             * Cannot create RootAttributeOperation for document. Root with the specified name does not exist.
              *
              * @error rootattribute-operation-fromjson-no-root
-             * @param rootName
+             * @param {string} rootName The root name.
              */
             throw new CKEditorError('rootattribute-operation-fromjson-no-root', this, { rootName: json.root });
         }

package/src/model/operation/transform.js

@@ -1037,23 +1037,80 @@ setTransformation(MarkerOperation, SplitOperation, (a, b, context) => {
     }
     if (a.newRange) {
         if (context.abRelation) {
+            // If we have context, it means that there was previously a merge operation which transformed this marker operation, and that
+            // merge operation was then undone, and this split operation should reverse the marker to state before the merge operation.
             const aNewRange = a.newRange._getTransformedBySplitOperation(b);
-            if (a.newRange.start.isEqual(b.splitPosition) && context.abRelation.wasStartBeforeMergedElement) {
-                a.newRange.start = Position._createAt(b.insertionPosition);
-            }
-            else if (a.newRange.start.isEqual(b.splitPosition) && !context.abRelation.wasInLeftElement) {
-                a.newRange.start = Position._createAt(b.moveTargetPosition);
+            if (a.newRange.start.isEqual(b.splitPosition)) {
+                // If marker range start is same as split position, we need to decide where marker start should be placed, as there
+                // are three possible options.
+                //
+                if (context.abRelation.wasStartBeforeMergedElement) {
+                    // If the marker start was initially before the merged element, move it back to that place.
+                    //
+                    // <p>Foo</p>[<p>Bar]</p>  -- merge ->  <p>Foo[Bar]</p>  -- default split ->  <p>Foo</p><p>[Bar]</p>
+                    // <p>Foo</p>[<p>Bar]</p>  -- merge ->  <p>Foo[Bar]</p>  --- fixed split -->  <p>Foo</p>[<p>Bar]</p>
+                    //
+                    a.newRange.start = Position._createAt(b.insertionPosition);
+                }
+                else if (context.abRelation.wasInLeftElement) {
+                    // If the marker start was initially in the "left" element, keep the start position there.
+                    //
+                    // <p>Foo[</p><p>Bar]</p>  -- merge ->  <p>Foo[Bar]</p>  -- default split ->  <p>Foo</p><p>[Bar]</p>
+                    // <p>Foo[</p><p>Bar]</p>  -- merge ->  <p>Foo[Bar]</p>  --- fixed split -->  <p>Foo[</p><p>Bar]</p>
+                    //
+                    a.newRange.start = Position._createAt(a.newRange.start);
+                }
+                else {
+                    // Finally, the start position must have been at the beginning of the "right" (merged) element.
+                    // In this case, move it back to the "right" element.
+                    //
+                    // Note, that this what the default transformation (`_getTransformedBySplitOperation()`) does, BUT ONLY for
+                    // a non-collapsed marker. For a collapsed marker, by default, the whole marker is kept at the split position,
+                    // which would be incorrect. This is why this case is needed, and why we don't use `aNewRange.start` here.
+                    //
+                    // <p>Foo</p><p>[]Bar</p>  -- merge ->  <p>Foo[]Bar</p>  -- default split ->  <p>Foo[]</p><p>Bar</p>
+                    // <p>Foo</p><p>[]Bar</p>  -- merge ->  <p>Foo[]Bar</p>  --- fixed split -->  <p>Foo</p><p>[]Bar</p>
+                    //
+                    a.newRange.start = Position._createAt(b.moveTargetPosition);
+                }
             }
             else {
+                // If marker range start is not the same as split position, simply use the default transformation, as there is no
+                // ambiguity in this case.
                 a.newRange.start = aNewRange.start;
             }
-            if (a.newRange.end.isEqual(b.splitPosition) && context.abRelation.wasInRightElement) {
-                a.newRange.end = Position._createAt(b.moveTargetPosition);
-            }
-            else if (a.newRange.end.isEqual(b.splitPosition) && context.abRelation.wasEndBeforeMergedElement) {
-                a.newRange.end = Position._createAt(b.insertionPosition);
+            if (a.newRange.end.isEqual(b.splitPosition)) {
+                // If marker range end is same as split position, we need to decide where marker end should be placed, as there
+                // are three possible options.
+                //
+                if (a.newRange.end.isEqual(b.splitPosition) && context.abRelation.wasEndBeforeMergedElement) {
+                    // If the marker end was initially before the merged element, move it back to that place.
+                    //
+                    // <p>[Foo</p>]<p>Bar</p>  -- merge ->  <p>[Foo]Bar</p>  -- default split ->  <p>[Foo]</p><p>Bar</p>
+                    // <p>[Foo</p>]<p>Bar</p>  -- merge ->  <p>[Foo]Bar</p>  --- fixed split -->  <p>[Foo</p>]<p>Bar</p>
+                    //
+                    a.newRange.end = Position._createAt(b.insertionPosition);
+                }
+                else if (context.abRelation.wasInRightElement) {
+                    // If the marker was initially in the "right" element, keep the end position there.
+                    //
+                    // <p>[Foo</p><p>]Bar</p>  -- merge ->  <p>[Foo]Bar</p>  -- default split ->  <p>[Foo]</p><p>Bar</p>
+                    // <p>[Foo</p><p>]Bar</p>  -- merge ->  <p>[Foo]Bar</p>  --- fixed split -->  <p>[Foo</p><p>]Bar</p>
+                    //
+                    a.newRange.end = Position._createAt(b.moveTargetPosition);
+                }
+                else {
+                    // Finally, the end position must have been at the end of the "left" (merged) element.
+                    // In this case, keep it where it is.
+                    //
+                    // Note, that this is what the default transformation does, so we could use `aNewRange.end`, but this is more clear.
+                    //
+                    a.newRange.end = Position._createAt(a.newRange.end);
+                }
             }
             else {
+                // If marker range end is not the same as split position, simply use the default transformation, as there is no
+                // ambiguity in this case.
                 a.newRange.end = aNewRange.end;
             }
             return [a];

package/src/model/operation/utils.d.ts

@@ -16,7 +16,7 @@ import type Position from '../position.js';
  *
  * @internal
  * @param position Position at which nodes should be inserted.
- * @param normalizedNodes Nodes to insert.
+ * @param nodes Nodes to insert.
  * @returns Range spanning over inserted elements.
  */
 export declare function _insert(position: Position, nodes: NodeSet): Range;

package/src/model/operation/utils.js

@@ -15,7 +15,7 @@ import { CKEditorError, isIterable } from '@ckeditor/ckeditor5-utils';
  *
  * @internal
  * @param position Position at which nodes should be inserted.
- * @param normalizedNodes Nodes to insert.
+ * @param nodes Nodes to insert.
  * @returns Range spanning over inserted elements.
  */
 export function _insert(position, nodes) {

package/src/model/position.js

@@ -100,7 +100,7 @@ export default class Position extends TypeCheckable {
              * Position path must be an array with at least one item.
              *
              * @error model-position-path-incorrect-format
-             * @param path
+             * @param {Array.<number>} path A path to the position.
              */
             throw new CKEditorError('model-position-path-incorrect-format', root, { path });
         }
@@ -155,7 +155,7 @@ export default class Position extends TypeCheckable {
                  * the {@glink framework/architecture/editing-engine#indexes-and-offsets Editing engine architecture} guide.
                  *
                  * @error model-position-path-incorrect
-                 * @param position The incorrect position.
+                 * @param {module:engine/model/position~Position} position The incorrect position.
                  */
                 throw new CKEditorError('model-position-path-incorrect', this, { position: this });
             }
@@ -823,10 +823,10 @@ export default class Position extends TypeCheckable {
     static _createAfter(item, stickiness) {
         if (!item.parent) {
             /**
-             * You can not make a position after a root element.
+             * You cannot make a position after a root element.
              *
              * @error model-position-after-root
-             * @param root
+             * @param {module:engine/model/rootelement~RootElement} root The root element..
              */
             throw new CKEditorError('model-position-after-root', [this, item], { root: item });
         }
@@ -842,10 +842,10 @@ export default class Position extends TypeCheckable {
     static _createBefore(item, stickiness) {
         if (!item.parent) {
             /**
-             * You can not make a position before a root element.
+             * You cannot make a position before a root element.
              *
              * @error model-position-before-root
-             * @param root
+             * @param {module:engine/model/rootelement~RootElement} root The root element..
              */
             throw new CKEditorError('model-position-before-root', item, { root: item });
         }
@@ -869,7 +869,7 @@ export default class Position extends TypeCheckable {
              * Cannot create position for document. Root with specified name does not exist.
              *
              * @error model-position-fromjson-no-root
-             * @param rootName
+             * @param {string} rootName The root name.
              */
             throw new CKEditorError('model-position-fromjson-no-root', doc, { rootName: json.root });
         }

package/src/model/range.d.ts

@@ -400,7 +400,7 @@ export default class Range extends TypeCheckable implements Iterable<TreeWalkerV
      * If the deleted range contains transformed range, `null` will be returned.
      *
      * @internal
-     * @param deletionPosition Position from which nodes are removed.
+     * @param deletePosition Position from which nodes are removed.
      * @param howMany How many nodes are removed.
      * @returns Result of the transformation.
      */

package/src/model/range.js

@@ -744,7 +744,7 @@ export default class Range extends TypeCheckable {
      * If the deleted range contains transformed range, `null` will be returned.
      *
      * @internal
-     * @param deletionPosition Position from which nodes are removed.
+     * @param deletePosition Position from which nodes are removed.
      * @param howMany How many nodes are removed.
      * @returns Result of the transformation.
      */

package/src/model/selection.js

@@ -635,8 +635,8 @@ export default class Selection extends /* #__PURE__ */ EmitterMixin(TypeCheckabl
                  * Trying to add a range that intersects with another range in the selection.
                  *
                  * @error model-selection-range-intersects
-                 * @param addedRange Range that was added to the selection.
-                 * @param intersectingRange Range in the selection that intersects with `addedRange`.
+                 * @param {module:engine/model/range~Range} addedRange Range that was added to the selection.
+                 * @param {module:engine/model/range~Range} intersectingRange Range in the selection that intersects with `addedRange`.
                  */
                 throw new CKEditorError('model-selection-range-intersects', [this, range], { addedRange: range, intersectingRange: this._ranges[i] });
             }

package/src/model/utils/deletecontent.d.ts

@@ -50,9 +50,22 @@ import type Selection from '../selection.js';
  * **Note:** If there is no valid position for the selection, the paragraph will always be created:
  *
  * `[<imageBlock src="foo.jpg"></imageBlock>]` -> `<paragraph>[]</paragraph>`.
+ *
+ * @param options.doNotFixSelection Whether given selection-to-remove should be fixed if it ends at the beginning of an element.
+ *
+ * By default, `deleteContent()` will fix selection before performing a deletion, so that the selection does not end at the beginning of
+ * an element. For example, selection `<heading>[Heading</heading><paragraph>]Some text.</paragraph>` will be treated as it was
+ * `<heading>[Heading]</heading><paragraph>Some text.</paragraph>`. As a result, the elements will not get merged.
+ *
+ * If selection is as in example, visually, the next element (paragraph) is not selected and it may be confusing for the user that
+ * the elements got merged. Selection is set up like this by browsers when a user triple-clicks on some text.
+ *
+ * However, in some cases, it is expected to remove content exactly as selected in the selection, without any fixing. In these cases,
+ * this flag can be set to `true`, which will prevent fixing the selection.
  */
 export default function deleteContent(model: Model, selection: Selection | DocumentSelection, options?: {
     leaveUnmerged?: boolean;
     doNotResetEntireContent?: boolean;
     doNotAutoparagraph?: boolean;
+    doNotFixSelection?: boolean;
 }): void;

package/src/model/utils/deletecontent.js

@@ -50,6 +50,18 @@ import Range from '../range.js';
  * **Note:** If there is no valid position for the selection, the paragraph will always be created:
  *
  * `[<imageBlock src="foo.jpg"></imageBlock>]` -> `<paragraph>[]</paragraph>`.
+ *
+ * @param options.doNotFixSelection Whether given selection-to-remove should be fixed if it ends at the beginning of an element.
+ *
+ * By default, `deleteContent()` will fix selection before performing a deletion, so that the selection does not end at the beginning of
+ * an element. For example, selection `<heading>[Heading</heading><paragraph>]Some text.</paragraph>` will be treated as it was
+ * `<heading>[Heading]</heading><paragraph>Some text.</paragraph>`. As a result, the elements will not get merged.
+ *
+ * If selection is as in example, visually, the next element (paragraph) is not selected and it may be confusing for the user that
+ * the elements got merged. Selection is set up like this by browsers when a user triple-clicks on some text.
+ *
+ * However, in some cases, it is expected to remove content exactly as selected in the selection, without any fixing. In these cases,
+ * this flag can be set to `true`, which will prevent fixing the selection.
  */
 export default function deleteContent(model, selection, options = {}) {
     if (selection.isCollapsed) {
@@ -77,7 +89,14 @@ export default function deleteContent(model, selection, options = {}) {
             }
         }
         // Get the live positions for the range adjusted to span only blocks selected from the user perspective.
-        const [startPosition, endPosition] = getLivePositionsForSelectedBlocks(selRange);
+        let startPosition, endPosition;
+        if (!options.doNotFixSelection) {
+            [startPosition, endPosition] = getLivePositionsForSelectedBlocks(selRange);
+        }
+        else {
+            startPosition = LivePosition.fromPosition(selRange.start, 'toPrevious');
+            endPosition = LivePosition.fromPosition(selRange.end, 'toNext');
+        }
         // 2. Remove the content if there is any.
         if (!startPosition.isTouching(endPosition)) {
             writer.remove(writer.createRange(startPosition, endPosition));

package/src/model/utils/insertcontent.d.ts

@@ -38,7 +38,6 @@ import type Selection from '../selection.js';
  * @param model The model in context of which the insertion should be performed.
  * @param content The content to insert.
  * @param selectable Selection into which the content should be inserted.
- * @param placeOrOffset Sets place or offset of the selection.
  * @returns 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 `insertContent`, returns a range collapsed
  * at the insertion position.