@ckeditor/ckeditor5-engine 38.1.1 → 38.2.0-alpha.1

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

@@ -1,32 +1,32 @@
-/**
- * @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 type DocumentSelection from '../documentselection';
-import type Model from '../model';
-import type Range from '../range';
-import type Selection from '../selection';
-/**
- * Returns a model range which is optimal (in terms of UX) for inserting a widget block.
- *
- * For instance, if a selection is in the middle of a paragraph, the collapsed range before this paragraph
- * will be returned so that it is not split. If the selection is at the end of a paragraph,
- * the collapsed range after this paragraph will be returned.
- *
- * Note: If the selection is placed in an empty block, the range in that block will be returned. If that range
- * is then passed to {@link module:engine/model/model~Model#insertContent}, the block will be fully replaced
- * by the inserted widget block.
- *
- * **Note:** Use {@link module:widget/utils#findOptimalInsertionRange} instead of this function outside engine.
- * This function is only exposed to be used by {@link module:widget/utils#findOptimalInsertionRange findOptimalInsertionRange()}
- * in the `widget` package and inside the `engine` package.
- *
- * @param selection The selection based on which the insertion position should be calculated.
- * @param model Model instance.
- * @param place The place where to look for optimal insertion range.
- * The default `auto` value will determine itself the best position for insertion.
- * The `before` value will try to find a position before selection.
- * The `after` value will try to find a position after selection.
- * @returns The optimal range.
- */
-export declare function findOptimalInsertionRange(selection: Selection | DocumentSelection, model: Model, place?: 'auto' | 'before' | 'after'): 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 type DocumentSelection from '../documentselection.js';
+import type Model from '../model.js';
+import type Range from '../range.js';
+import type Selection from '../selection.js';
+/**
+ * Returns a model range which is optimal (in terms of UX) for inserting a widget block.
+ *
+ * For instance, if a selection is in the middle of a paragraph, the collapsed range before this paragraph
+ * will be returned so that it is not split. If the selection is at the end of a paragraph,
+ * the collapsed range after this paragraph will be returned.
+ *
+ * Note: If the selection is placed in an empty block, the range in that block will be returned. If that range
+ * is then passed to {@link module:engine/model/model~Model#insertContent}, the block will be fully replaced
+ * by the inserted widget block.
+ *
+ * **Note:** Use {@link module:widget/utils#findOptimalInsertionRange} instead of this function outside engine.
+ * This function is only exposed to be used by {@link module:widget/utils#findOptimalInsertionRange findOptimalInsertionRange()}
+ * in the `widget` package and inside the `engine` package.
+ *
+ * @param selection The selection based on which the insertion position should be calculated.
+ * @param model Model instance.
+ * @param place The place where to look for optimal insertion range.
+ * The default `auto` value will determine itself the best position for insertion.
+ * The `before` value will try to find a position before selection.
+ * The `after` value will try to find a position after selection.
+ * @returns The optimal range.
+ */
+export declare function findOptimalInsertionRange(selection: Selection | DocumentSelection, model: Model, place?: 'auto' | 'before' | 'after'): Range;

package/src/model/utils/findoptimalinsertionrange.js

@@ -1,57 +1,57 @@
-/**
- * @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/findoptimalinsertionrange
- */
-import { first } from '@ckeditor/ckeditor5-utils';
-/**
- * Returns a model range which is optimal (in terms of UX) for inserting a widget block.
- *
- * For instance, if a selection is in the middle of a paragraph, the collapsed range before this paragraph
- * will be returned so that it is not split. If the selection is at the end of a paragraph,
- * the collapsed range after this paragraph will be returned.
- *
- * Note: If the selection is placed in an empty block, the range in that block will be returned. If that range
- * is then passed to {@link module:engine/model/model~Model#insertContent}, the block will be fully replaced
- * by the inserted widget block.
- *
- * **Note:** Use {@link module:widget/utils#findOptimalInsertionRange} instead of this function outside engine.
- * This function is only exposed to be used by {@link module:widget/utils#findOptimalInsertionRange findOptimalInsertionRange()}
- * in the `widget` package and inside the `engine` package.
- *
- * @param selection The selection based on which the insertion position should be calculated.
- * @param model Model instance.
- * @param place The place where to look for optimal insertion range.
- * The default `auto` value will determine itself the best position for insertion.
- * The `before` value will try to find a position before selection.
- * The `after` value will try to find a position after selection.
- * @returns The optimal range.
- */
-export function findOptimalInsertionRange(selection, model, place = 'auto') {
-    const selectedElement = selection.getSelectedElement();
-    if (selectedElement && model.schema.isObject(selectedElement) && !model.schema.isInline(selectedElement)) {
-        if (place == 'before' || place == 'after') {
-            return model.createRange(model.createPositionAt(selectedElement, place));
-        }
-        return model.createRangeOn(selectedElement);
-    }
-    const firstBlock = first(selection.getSelectedBlocks());
-    // There are no block elements within ancestors (in the current limit element).
-    if (!firstBlock) {
-        return model.createRange(selection.focus);
-    }
-    // If inserting into an empty block – return position in that block. It will get
-    // replaced with the image by insertContent(). #42.
-    if (firstBlock.isEmpty) {
-        return model.createRange(model.createPositionAt(firstBlock, 0));
-    }
-    const positionAfter = model.createPositionAfter(firstBlock);
-    // If selection is at the end of the block - return position after the block.
-    if (selection.focus.isTouching(positionAfter)) {
-        return model.createRange(positionAfter);
-    }
-    // Otherwise, return position before the block.
-    return model.createRange(model.createPositionBefore(firstBlock));
-}
+/**
+ * @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/findoptimalinsertionrange
+ */
+import { first } from '@ckeditor/ckeditor5-utils';
+/**
+ * Returns a model range which is optimal (in terms of UX) for inserting a widget block.
+ *
+ * For instance, if a selection is in the middle of a paragraph, the collapsed range before this paragraph
+ * will be returned so that it is not split. If the selection is at the end of a paragraph,
+ * the collapsed range after this paragraph will be returned.
+ *
+ * Note: If the selection is placed in an empty block, the range in that block will be returned. If that range
+ * is then passed to {@link module:engine/model/model~Model#insertContent}, the block will be fully replaced
+ * by the inserted widget block.
+ *
+ * **Note:** Use {@link module:widget/utils#findOptimalInsertionRange} instead of this function outside engine.
+ * This function is only exposed to be used by {@link module:widget/utils#findOptimalInsertionRange findOptimalInsertionRange()}
+ * in the `widget` package and inside the `engine` package.
+ *
+ * @param selection The selection based on which the insertion position should be calculated.
+ * @param model Model instance.
+ * @param place The place where to look for optimal insertion range.
+ * The default `auto` value will determine itself the best position for insertion.
+ * The `before` value will try to find a position before selection.
+ * The `after` value will try to find a position after selection.
+ * @returns The optimal range.
+ */
+export function findOptimalInsertionRange(selection, model, place = 'auto') {
+    const selectedElement = selection.getSelectedElement();
+    if (selectedElement && model.schema.isObject(selectedElement) && !model.schema.isInline(selectedElement)) {
+        if (place == 'before' || place == 'after') {
+            return model.createRange(model.createPositionAt(selectedElement, place));
+        }
+        return model.createRangeOn(selectedElement);
+    }
+    const firstBlock = first(selection.getSelectedBlocks());
+    // There are no block elements within ancestors (in the current limit element).
+    if (!firstBlock) {
+        return model.createRange(selection.focus);
+    }
+    // If inserting into an empty block – return position in that block. It will get
+    // replaced with the image by insertContent(). #42.
+    if (firstBlock.isEmpty) {
+        return model.createRange(model.createPositionAt(firstBlock, 0));
+    }
+    const positionAfter = model.createPositionAfter(firstBlock);
+    // If selection is at the end of the block - return position after the block.
+    if (selection.focus.isTouching(positionAfter)) {
+        return model.createRange(positionAfter);
+    }
+    // Otherwise, return position before the block.
+    return model.createRange(model.createPositionBefore(firstBlock));
+}

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

@@ -1,30 +1,30 @@
-/**
- * @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 type DocumentFragment from '../documentfragment';
-import type DocumentSelection from '../documentselection';
-import type Model from '../model';
-import type Selection from '../selection';
-/**
- * @module engine/model/utils/getselectedcontent
- */
-/**
- * Gets a clone of the selected content.
- *
- * For example, for the following selection:
- *
- * ```html
- * <p>x</p><quote><p>y</p><h>fir[st</h></quote><p>se]cond</p><p>z</p>
- * ```
- *
- * It will return a document fragment with such a content:
- *
- * ```html
- * <quote><h>st</h></quote><p>se</p>
- * ```
- *
- * @param model The model in context of which the selection modification should be performed.
- * @param selection The selection of which content will be returned.
- */
-export default function getSelectedContent(model: Model, selection: Selection | DocumentSelection): DocumentFragment;
+/**
+ * @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 type DocumentFragment from '../documentfragment.js';
+import type DocumentSelection from '../documentselection.js';
+import type Model from '../model.js';
+import type Selection from '../selection.js';
+/**
+ * @module engine/model/utils/getselectedcontent
+ */
+/**
+ * Gets a clone of the selected content.
+ *
+ * For example, for the following selection:
+ *
+ * ```html
+ * <p>x</p><quote><p>y</p><h>fir[st</h></quote><p>se]cond</p><p>z</p>
+ * ```
+ *
+ * It will return a document fragment with such a content:
+ *
+ * ```html
+ * <quote><h>st</h></quote><p>se</p>
+ * ```
+ *
+ * @param model The model in context of which the selection modification should be performed.
+ * @param selection The selection of which content will be returned.
+ */
+export default function getSelectedContent(model: Model, selection: Selection | DocumentSelection): DocumentFragment;

package/src/model/utils/getselectedcontent.js

@@ -1,125 +1,125 @@
-/**
- * @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/getselectedcontent
- */
-/**
- * Gets a clone of the selected content.
- *
- * For example, for the following selection:
- *
- * ```html
- * <p>x</p><quote><p>y</p><h>fir[st</h></quote><p>se]cond</p><p>z</p>
- * ```
- *
- * It will return a document fragment with such a content:
- *
- * ```html
- * <quote><h>st</h></quote><p>se</p>
- * ```
- *
- * @param model The model in context of which the selection modification should be performed.
- * @param selection The selection of which content will be returned.
- */
-export default function getSelectedContent(model, selection) {
-    return model.change(writer => {
-        const frag = writer.createDocumentFragment();
-        const range = selection.getFirstRange();
-        if (!range || range.isCollapsed) {
-            return frag;
-        }
-        const root = range.start.root;
-        const commonPath = range.start.getCommonPath(range.end);
-        const commonParent = root.getNodeByPath(commonPath);
-        // ## 1st step
-        //
-        // First, we'll clone a fragment represented by a minimal flat range
-        // containing the original range to be cloned.
-        // E.g. let's consider such a range:
-        //
-        // <p>x</p><quote><p>y</p><h>fir[st</h></quote><p>se]cond</p><p>z</p>
-        //
-        // A minimal flat range containing this one is:
-        //
-        // <p>x</p>[<quote><p>y</p><h>first</h></quote><p>second</p>]<p>z</p>
-        //
-        // We can easily clone this structure, preserving e.g. the <quote> element.
-        let flatSubtreeRange;
-        if (range.start.parent == range.end.parent) {
-            // The original range is flat, so take it.
-            flatSubtreeRange = range;
-        }
-        else {
-            flatSubtreeRange = writer.createRange(writer.createPositionAt(commonParent, range.start.path[commonPath.length]), writer.createPositionAt(commonParent, range.end.path[commonPath.length] + 1));
-        }
-        const howMany = flatSubtreeRange.end.offset - flatSubtreeRange.start.offset;
-        // Clone the whole contents.
-        for (const item of flatSubtreeRange.getItems({ shallow: true })) {
-            if (item.is('$textProxy')) {
-                writer.appendText(item.data, item.getAttributes(), frag);
-            }
-            else {
-                writer.append(writer.cloneElement(item, true), frag);
-            }
-        }
-        // ## 2nd step
-        //
-        // If the original range wasn't flat, then we need to remove the excess nodes from the both ends of the cloned fragment.
-        //
-        // For example, for the range shown in the 1st step comment, we need to remove these pieces:
-        //
-        // <quote>[<p>y</p>]<h>[fir]st</h></quote><p>se[cond]</p>
-        //
-        // So this will be the final copied content:
-        //
-        // <quote><h>st</h></quote><p>se</p>
-        //
-        // In order to do that, we remove content from these two ranges:
-        //
-        // [<quote><p>y</p><h>fir]st</h></quote><p>se[cond</p>]
-        if (flatSubtreeRange != range) {
-            // Find the position of the original range in the cloned fragment.
-            const newRange = range._getTransformedByMove(flatSubtreeRange.start, writer.createPositionAt(frag, 0), howMany)[0];
-            const leftExcessRange = writer.createRange(writer.createPositionAt(frag, 0), newRange.start);
-            const rightExcessRange = writer.createRange(newRange.end, writer.createPositionAt(frag, 'end'));
-            removeRangeContent(rightExcessRange, writer);
-            removeRangeContent(leftExcessRange, writer);
-        }
-        return frag;
-    });
-}
-// After https://github.com/ckeditor/ckeditor5-engine/issues/690 is fixed,
-// this function will, most likely, be able to rewritten using getMinimalFlatRanges().
-function removeRangeContent(range, writer) {
-    const parentsToCheck = [];
-    Array.from(range.getItems({ direction: 'backward' }))
-        // We should better store ranges because text proxies will lose integrity
-        // with the text nodes when we'll start removing content.
-        .map(item => writer.createRangeOn(item))
-        // Filter only these items which are fully contained in the passed range.
-        //
-        // E.g. for the following range: [<quote><p>y</p><h>fir]st</h>
-        // the walker will return the entire <h> element, when only the "fir" item inside it is fully contained.
-        .filter(itemRange => {
-        // We should be able to use Range.containsRange, but https://github.com/ckeditor/ckeditor5-engine/issues/691.
-        const contained = (itemRange.start.isAfter(range.start) || itemRange.start.isEqual(range.start)) &&
-            (itemRange.end.isBefore(range.end) || itemRange.end.isEqual(range.end));
-        return contained;
-    })
-        .forEach(itemRange => {
-        parentsToCheck.push(itemRange.start.parent);
-        writer.remove(itemRange);
-    });
-    // Remove ancestors of the removed items if they turned to be empty now
-    // (their whole content was contained in the range).
-    parentsToCheck.forEach(parentToCheck => {
-        let parent = parentToCheck;
-        while (parent.parent && parent.isEmpty) {
-            const removeRange = writer.createRangeOn(parent);
-            parent = parent.parent;
-            writer.remove(removeRange);
-        }
-    });
-}
+/**
+ * @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/getselectedcontent
+ */
+/**
+ * Gets a clone of the selected content.
+ *
+ * For example, for the following selection:
+ *
+ * ```html
+ * <p>x</p><quote><p>y</p><h>fir[st</h></quote><p>se]cond</p><p>z</p>
+ * ```
+ *
+ * It will return a document fragment with such a content:
+ *
+ * ```html
+ * <quote><h>st</h></quote><p>se</p>
+ * ```
+ *
+ * @param model The model in context of which the selection modification should be performed.
+ * @param selection The selection of which content will be returned.
+ */
+export default function getSelectedContent(model, selection) {
+    return model.change(writer => {
+        const frag = writer.createDocumentFragment();
+        const range = selection.getFirstRange();
+        if (!range || range.isCollapsed) {
+            return frag;
+        }
+        const root = range.start.root;
+        const commonPath = range.start.getCommonPath(range.end);
+        const commonParent = root.getNodeByPath(commonPath);
+        // ## 1st step
+        //
+        // First, we'll clone a fragment represented by a minimal flat range
+        // containing the original range to be cloned.
+        // E.g. let's consider such a range:
+        //
+        // <p>x</p><quote><p>y</p><h>fir[st</h></quote><p>se]cond</p><p>z</p>
+        //
+        // A minimal flat range containing this one is:
+        //
+        // <p>x</p>[<quote><p>y</p><h>first</h></quote><p>second</p>]<p>z</p>
+        //
+        // We can easily clone this structure, preserving e.g. the <quote> element.
+        let flatSubtreeRange;
+        if (range.start.parent == range.end.parent) {
+            // The original range is flat, so take it.
+            flatSubtreeRange = range;
+        }
+        else {
+            flatSubtreeRange = writer.createRange(writer.createPositionAt(commonParent, range.start.path[commonPath.length]), writer.createPositionAt(commonParent, range.end.path[commonPath.length] + 1));
+        }
+        const howMany = flatSubtreeRange.end.offset - flatSubtreeRange.start.offset;
+        // Clone the whole contents.
+        for (const item of flatSubtreeRange.getItems({ shallow: true })) {
+            if (item.is('$textProxy')) {
+                writer.appendText(item.data, item.getAttributes(), frag);
+            }
+            else {
+                writer.append(writer.cloneElement(item, true), frag);
+            }
+        }
+        // ## 2nd step
+        //
+        // If the original range wasn't flat, then we need to remove the excess nodes from the both ends of the cloned fragment.
+        //
+        // For example, for the range shown in the 1st step comment, we need to remove these pieces:
+        //
+        // <quote>[<p>y</p>]<h>[fir]st</h></quote><p>se[cond]</p>
+        //
+        // So this will be the final copied content:
+        //
+        // <quote><h>st</h></quote><p>se</p>
+        //
+        // In order to do that, we remove content from these two ranges:
+        //
+        // [<quote><p>y</p><h>fir]st</h></quote><p>se[cond</p>]
+        if (flatSubtreeRange != range) {
+            // Find the position of the original range in the cloned fragment.
+            const newRange = range._getTransformedByMove(flatSubtreeRange.start, writer.createPositionAt(frag, 0), howMany)[0];
+            const leftExcessRange = writer.createRange(writer.createPositionAt(frag, 0), newRange.start);
+            const rightExcessRange = writer.createRange(newRange.end, writer.createPositionAt(frag, 'end'));
+            removeRangeContent(rightExcessRange, writer);
+            removeRangeContent(leftExcessRange, writer);
+        }
+        return frag;
+    });
+}
+// After https://github.com/ckeditor/ckeditor5-engine/issues/690 is fixed,
+// this function will, most likely, be able to rewritten using getMinimalFlatRanges().
+function removeRangeContent(range, writer) {
+    const parentsToCheck = [];
+    Array.from(range.getItems({ direction: 'backward' }))
+        // We should better store ranges because text proxies will lose integrity
+        // with the text nodes when we'll start removing content.
+        .map(item => writer.createRangeOn(item))
+        // Filter only these items which are fully contained in the passed range.
+        //
+        // E.g. for the following range: [<quote><p>y</p><h>fir]st</h>
+        // the walker will return the entire <h> element, when only the "fir" item inside it is fully contained.
+        .filter(itemRange => {
+        // We should be able to use Range.containsRange, but https://github.com/ckeditor/ckeditor5-engine/issues/691.
+        const contained = (itemRange.start.isAfter(range.start) || itemRange.start.isEqual(range.start)) &&
+            (itemRange.end.isBefore(range.end) || itemRange.end.isEqual(range.end));
+        return contained;
+    })
+        .forEach(itemRange => {
+        parentsToCheck.push(itemRange.start.parent);
+        writer.remove(itemRange);
+    });
+    // Remove ancestors of the removed items if they turned to be empty now
+    // (their whole content was contained in the range).
+    parentsToCheck.forEach(parentToCheck => {
+        let parent = parentToCheck;
+        while (parent.parent && parent.isEmpty) {
+            const removeRange = writer.createRangeOn(parent);
+            parent = parent.parent;
+            writer.remove(removeRange);
+        }
+    });
+}

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

@@ -1,46 +1,46 @@
-/**
- * @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/insertcontent
- */
-import DocumentSelection from '../documentselection';
-import Range from '../range';
-import type DocumentFragment from '../documentfragment';
-import type Item from '../item';
-import type Model from '../model';
-import type Selection from '../selection';
-/**
- * Inserts content into the editor (specified selection) as one would expect the paste functionality to work.
- *
- * It takes care of removing the selected content, splitting elements (if needed), inserting elements and merging elements appropriately.
- *
- * Some examples:
- *
- * ```html
- * <p>x^</p> + <p>y</p> => <p>x</p><p>y</p> => <p>xy[]</p>
- * <p>x^y</p> + <p>z</p> => <p>x</p>^<p>y</p> + <p>z</p> => <p>x</p><p>z</p><p>y</p> => <p>xz[]y</p>
- * <p>x^y</p> + <img /> => <p>x</p>^<p>y</p> + <img /> => <p>x</p><img /><p>y</p>
- * <p>x</p><p>^</p><p>z</p> + <p>y</p> => <p>x</p><p>y[]</p><p>z</p> (no merging)
- * <p>x</p>[<img />]<p>z</p> + <p>y</p> => <p>x</p>^<p>z</p> + <p>y</p> => <p>x</p><p>y[]</p><p>z</p>
- * ```
- *
- * If an instance of {@link module:engine/model/selection~Selection} is passed as `selectable` it will be modified
- * to the insertion selection (equal to a range to be selected after insertion).
- *
- * If `selectable` is not passed, the content will be inserted using the current selection of the model document.
- *
- * **Note:** Use {@link module:engine/model/model~Model#insertContent} instead of this function.
- * This function is only exposed to be reusable in algorithms which change the {@link module:engine/model/model~Model#insertContent}
- * method's behavior.
- *
- * @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.
- */
-export default function insertContent(model: Model, content: Item | DocumentFragment, selectable?: Selection | DocumentSelection): 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
+ */
+/**
+ * @module engine/model/utils/insertcontent
+ */
+import DocumentSelection from '../documentselection.js';
+import Range from '../range.js';
+import type DocumentFragment from '../documentfragment.js';
+import type Item from '../item.js';
+import type Model from '../model.js';
+import type Selection from '../selection.js';
+/**
+ * Inserts content into the editor (specified selection) as one would expect the paste functionality to work.
+ *
+ * It takes care of removing the selected content, splitting elements (if needed), inserting elements and merging elements appropriately.
+ *
+ * Some examples:
+ *
+ * ```html
+ * <p>x^</p> + <p>y</p> => <p>x</p><p>y</p> => <p>xy[]</p>
+ * <p>x^y</p> + <p>z</p> => <p>x</p>^<p>y</p> + <p>z</p> => <p>x</p><p>z</p><p>y</p> => <p>xz[]y</p>
+ * <p>x^y</p> + <img /> => <p>x</p>^<p>y</p> + <img /> => <p>x</p><img /><p>y</p>
+ * <p>x</p><p>^</p><p>z</p> + <p>y</p> => <p>x</p><p>y[]</p><p>z</p> (no merging)
+ * <p>x</p>[<img />]<p>z</p> + <p>y</p> => <p>x</p>^<p>z</p> + <p>y</p> => <p>x</p><p>y[]</p><p>z</p>
+ * ```
+ *
+ * If an instance of {@link module:engine/model/selection~Selection} is passed as `selectable` it will be modified
+ * to the insertion selection (equal to a range to be selected after insertion).
+ *
+ * If `selectable` is not passed, the content will be inserted using the current selection of the model document.
+ *
+ * **Note:** Use {@link module:engine/model/model~Model#insertContent} instead of this function.
+ * This function is only exposed to be reusable in algorithms which change the {@link module:engine/model/model~Model#insertContent}
+ * method's behavior.
+ *
+ * @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.
+ */
+export default function insertContent(model: Model, content: Item | DocumentFragment, selectable?: Selection | DocumentSelection): Range;