@ckeditor/ckeditor5-engine 41.2.0 → 41.3.0-alpha.1

package/dist/types/model/treewalker.d.ts

@@ -0,0 +1,186 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import { default as Position } from './position.js';
+import type Item from './item.js';
+import type Range from './range.js';
+/**
+ * Position iterator class. It allows to iterate forward and backward over the document.
+ */
+export default class TreeWalker implements Iterable<TreeWalkerValue> {
+    /**
+     * Walking direction. Defaults `'forward'`.
+     */
+    readonly direction: TreeWalkerDirection;
+    /**
+     * Iterator boundaries.
+     *
+     * When the iterator is walking `'forward'` on the end of boundary or is walking `'backward'`
+     * on the start of boundary, then `{ done: true }` is returned.
+     *
+     * If boundaries are not defined they are set before first and after last child of the root node.
+     */
+    readonly boundaries: Range | null;
+    /**
+     * Flag indicating whether all consecutive characters with the same attributes should be
+     * returned as one {@link module:engine/model/textproxy~TextProxy} (`true`) or one by one (`false`).
+     */
+    readonly singleCharacters: boolean;
+    /**
+     * Flag indicating whether iterator should enter elements or not. If the iterator is shallow child nodes of any
+     * iterated node will not be returned along with `elementEnd` tag.
+     */
+    readonly shallow: boolean;
+    /**
+     * Flag indicating whether iterator should ignore `elementEnd` tags. If the option is true walker will not
+     * return a parent node of the start position. If this option is `true` each {@link module:engine/model/element~Element} will
+     * be returned once, while if the option is `false` they might be returned twice:
+     * for `'elementStart'` and `'elementEnd'`.
+     */
+    readonly ignoreElementEnd: boolean;
+    /**
+     * Iterator position. This is always static position, even if the initial position was a
+     * {@link module:engine/model/liveposition~LivePosition live position}. If start position is not defined then position depends
+     * on {@link #direction}. If direction is `'forward'` position starts form the beginning, when direction
+     * is `'backward'` position starts from the end.
+     */
+    private _position;
+    /**
+     * Start boundary cached for optimization purposes.
+     */
+    private _boundaryStartParent;
+    /**
+     * End boundary cached for optimization purposes.
+     */
+    private _boundaryEndParent;
+    /**
+     * Parent of the most recently visited node. Cached for optimization purposes.
+     */
+    private _visitedParent;
+    /**
+     * Creates a range iterator. All parameters are optional, but you have to specify either `boundaries` or `startPosition`.
+     *
+     * @param options Object with configuration.
+     */
+    constructor(options: TreeWalkerOptions);
+    /**
+     * Iterable interface.
+     *
+     * @returns {Iterable.<module:engine/model/treewalker~TreeWalkerValue>}
+     */
+    [Symbol.iterator](): IterableIterator<TreeWalkerValue>;
+    /**
+     * Iterator position. This is always static position, even if the initial position was a
+     * {@link module:engine/model/liveposition~LivePosition live position}. If start position is not defined then position depends
+     * on {@link #direction}. If direction is `'forward'` position starts form the beginning, when direction
+     * is `'backward'` position starts from the end.
+     */
+    get position(): Position;
+    /**
+     * Moves {@link #position} in the {@link #direction} skipping values as long as the callback function returns `true`.
+     *
+     * For example:
+     *
+     * ```ts
+     * walker.skip( value => value.type == 'text' ); // <paragraph>[]foo</paragraph> -> <paragraph>foo[]</paragraph>
+     * walker.skip( () => true ); // Move the position to the end: <paragraph>[]foo</paragraph> -> <paragraph>foo</paragraph>[]
+     * walker.skip( () => false ); // Do not move the position.
+     * ```
+     *
+     * @param skip Callback function. Gets {@link module:engine/model/treewalker~TreeWalkerValue} and should
+     * return `true` if the value should be skipped or `false` if not.
+     */
+    skip(skip: (value: TreeWalkerValue) => boolean): void;
+    /**
+     * Gets the next tree walker's value.
+     */
+    next(): IteratorResult<TreeWalkerValue>;
+    /**
+     * Makes a step forward in model. Moves the {@link #position} to the next position and returns the encountered value.
+     */
+    private _next;
+    /**
+     * Makes a step backward in model. Moves the {@link #position} to the previous position and returns the encountered value.
+     */
+    private _previous;
+}
+/**
+ * Type of the step made by {@link module:engine/model/treewalker~TreeWalker}.
+ * Possible values: `'elementStart'` if walker is at the beginning of a node, `'elementEnd'` if walker is at the end of node,
+ * or `'text'` if walker traversed over text.
+ */
+export type TreeWalkerValueType = 'elementStart' | 'elementEnd' | 'text';
+/**
+ * Object returned by {@link module:engine/model/treewalker~TreeWalker} when traversing tree model.
+ */
+export interface TreeWalkerValue {
+    type: TreeWalkerValueType;
+    /**
+     * Item between old and new positions of {@link module:engine/model/treewalker~TreeWalker}.
+     */
+    item: Item;
+    /**
+     * Previous position of the iterator.
+     * * Forward iteration: For `'elementEnd'` it is the last position inside the element. For all other types it is the
+     * position before the item.
+     * * Backward iteration: For `'elementStart'` it is the first position inside the element. For all other types it is
+     * the position after item.
+     */
+    previousPosition: Position;
+    /**
+     * Next position of the iterator.
+     * * Forward iteration: For `'elementStart'` it is the first position inside the element. For all other types it is
+     * the position after the item.
+     * * Backward iteration: For `'elementEnd'` it is last position inside element. For all other types it is the position
+     * before the item.
+     */
+    nextPosition: Position;
+    /**
+     * Length of the item. For `'elementStart'` it is 1. For `'text'` it is the length of the text. For `'elementEnd'` it is `undefined`.
+     */
+    length?: number;
+}
+/**
+ * Tree walking direction.
+ */
+export type TreeWalkerDirection = 'forward' | 'backward';
+/**
+ * The configuration of TreeWalker.
+ *
+ * All parameters are optional, but you have to specify either `boundaries` or `startPosition`.
+ */
+export interface TreeWalkerOptions {
+    /**
+     * Walking direction.
+     *
+     * @default 'forward'
+     */
+    direction?: TreeWalkerDirection;
+    /**
+     * Range to define boundaries of the iterator.
+     */
+    boundaries?: Range | null;
+    /**
+     * Starting position.
+     */
+    startPosition?: Position;
+    /**
+     * Flag indicating whether all consecutive characters with the same attributes
+     * should be returned one by one as multiple {@link module:engine/model/textproxy~TextProxy} (`true`) objects or as one
+     * {@link module:engine/model/textproxy~TextProxy} (`false`).
+     */
+    singleCharacters?: boolean;
+    /**
+     * Flag indicating whether iterator should enter elements or not. If the
+     * iterator is shallow child nodes of any iterated node will not be returned along with `elementEnd` tag.
+     */
+    shallow?: boolean;
+    /**
+     * Flag indicating whether iterator should ignore `elementEnd` tags.
+     * If the option is true walker will not return a parent node of start position. If this option is `true`
+     * each {@link module:engine/model/element~Element} will be returned once, while if the option is `false` they might be returned
+     * twice: for `'elementStart'` and `'elementEnd'`.
+     */
+    ignoreElementEnd?: boolean;
+}

package/dist/types/model/typecheckable.d.ts

@@ -0,0 +1,285 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/typecheckable
+ */
+import type { Marker } from './markercollection.js';
+import type DocumentFragment from './documentfragment.js';
+import type DocumentSelection from './documentselection.js';
+import type Element from './element.js';
+import type LivePosition from './liveposition.js';
+import type LiveRange from './liverange.js';
+import type Node from './node.js';
+import type Position from './position.js';
+import type Range from './range.js';
+import type RootElement from './rootelement.js';
+import type Selection from './selection.js';
+import type Text from './text.js';
+import type TextProxy from './textproxy.js';
+export default abstract class TypeCheckable {
+    /**
+     * Checks whether the object is of type {@link module:engine/model/node~Node} or its subclass.
+     *
+     * This method is useful when processing model objects that are of unknown type. For example, a function
+     * may return a {@link module:engine/model/documentfragment~DocumentFragment} or a {@link module:engine/model/node~Node}
+     * that can be either a text node or an element. This method can be used to check what kind of object is returned.
+     *
+     * ```ts
+     * someObject.is( 'element' ); // -> true if this is an element
+     * someObject.is( 'node' ); // -> true if this is a node (a text node or an element)
+     * someObject.is( 'documentFragment' ); // -> true if this is a document fragment
+     * ```
+     *
+     * Since this method is also available on a range of view objects, you can prefix the type of the object with
+     * `model:` or `view:` to check, for example, if this is the model's or view's element:
+     *
+     * ```ts
+     * modelElement.is( 'model:element' ); // -> true
+     * modelElement.is( 'view:element' ); // -> false
+     * ```
+     *
+     * By using this method it is also possible to check a name of an element:
+     *
+     * ```ts
+     * imageElement.is( 'element', 'imageBlock' ); // -> true
+     * imageElement.is( 'element', 'imageBlock' ); // -> same as above
+     * imageElement.is( 'model:element', 'imageBlock' ); // -> same as above, but more precise
+     * ```
+     *
+     * @label NODE
+     */
+    is(type: 'node' | 'model:node'): this is Node | Element | Text | RootElement;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/element~Element} or its subclass.
+     *
+     * ```ts
+     * element.is( 'element' ); // -> true
+     * element.is( 'node' ); // -> true
+     * element.is( 'model:element' ); // -> true
+     * element.is( 'model:node' ); // -> true
+     *
+     * element.is( 'view:element' ); // -> false
+     * element.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * Assuming that the object being checked is an element, you can also check its
+     * {@link module:engine/model/element~Element#name name}:
+     *
+     * ```ts
+     * element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
+     * text.is( 'element', 'imageBlock' ); -> false
+     * ```
+     *
+     * @label ELEMENT
+     */
+    is(type: 'element' | 'model:element'): this is Element | RootElement;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/rootelement~RootElement}.
+     *
+     * ```ts
+     * rootElement.is( 'rootElement' ); // -> true
+     * rootElement.is( 'element' ); // -> true
+     * rootElement.is( 'node' ); // -> true
+     * rootElement.is( 'model:rootElement' ); // -> true
+     * rootElement.is( 'model:element' ); // -> true
+     * rootElement.is( 'model:node' ); // -> true
+     *
+     * rootElement.is( 'view:element' ); // -> false
+     * rootElement.is( 'documentFragment' ); // -> false
+     * ```
+     *
+     * Assuming that the object being checked is an element, you can also check its
+     * {@link module:engine/model/element~Element#name name}:
+     *
+     * ```ts
+     * rootElement.is( 'rootElement', '$root' ); // -> same as above
+     * ```
+     *
+     * @label ROOT_ELEMENT
+     */
+    is(type: 'rootElement' | 'model:rootElement'): this is RootElement;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/text~Text}.
+     *
+     * ```ts
+     * text.is( '$text' ); // -> true
+     * text.is( 'node' ); // -> true
+     * text.is( 'model:$text' ); // -> true
+     * text.is( 'model:node' ); // -> true
+     *
+     * text.is( 'view:$text' ); // -> false
+     * text.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * **Note:** Until version 20.0.0 this method wasn't accepting `'$text'` type. The legacy `'text'` type is still
+     * accepted for backward compatibility.
+     *
+     * @label TEXT
+     */
+    is(type: '$text' | 'model:$text'): this is Text;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/position~Position} or its subclass.
+     *
+     * ```ts
+     * position.is( 'position' ); // -> true
+     * position.is( 'model:position' ); // -> true
+     *
+     * position.is( 'view:position' ); // -> false
+     * position.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * @label POSITION
+     */
+    is(type: 'position' | 'model:position'): this is Position | LivePosition;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/liveposition~LivePosition}.
+     *
+     * ```ts
+     * livePosition.is( 'position' ); // -> true
+     * livePosition.is( 'model:position' ); // -> true
+     * livePosition.is( 'liveposition' ); // -> true
+     * livePosition.is( 'model:livePosition' ); // -> true
+     *
+     * livePosition.is( 'view:position' ); // -> false
+     * livePosition.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * @label LIVE_POSITION
+     */
+    is(type: 'livePosition' | 'model:livePosition'): this is LivePosition;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/range~Range} or its subclass.
+     *
+     * ```ts
+     * range.is( 'range' ); // -> true
+     * range.is( 'model:range' ); // -> true
+     *
+     * range.is( 'view:range' ); // -> false
+     * range.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * @label RANGE
+     */
+    is(type: 'range' | 'model:range'): this is Range | LiveRange;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/liverange~LiveRange}.
+     *
+     * ```ts
+     * liveRange.is( 'range' ); // -> true
+     * liveRange.is( 'model:range' ); // -> true
+     * liveRange.is( 'liveRange' ); // -> true
+     * liveRange.is( 'model:liveRange' ); // -> true
+     *
+     * liveRange.is( 'view:range' ); // -> false
+     * liveRange.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * @label LIVE_RANGE
+     */
+    is(type: 'liveRange' | 'model:liveRange'): this is LiveRange;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/documentfragment~DocumentFragment}.
+     *
+     * ```ts
+     * docFrag.is( 'documentFragment' ); // -> true
+     * docFrag.is( 'model:documentFragment' ); // -> true
+     *
+     * docFrag.is( 'view:documentFragment' ); // -> false
+     * docFrag.is( 'element' ); // -> false
+     * docFrag.is( 'node' ); // -> false
+     * ```
+     *
+     * @label DOCUMENT_FRAGMENT
+     */
+    is(type: 'documentFragment' | 'model:documentFragment'): this is DocumentFragment;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/selection~Selection}
+     * or {@link module:engine/model/documentselection~DocumentSelection}.
+     *
+     * ```ts
+     * selection.is( 'selection' ); // -> true
+     * selection.is( 'model:selection' ); // -> true
+     *
+     * selection.is( 'view:selection' ); // -> false
+     * selection.is( 'range' ); // -> false
+     * ```
+     *
+     * @label SELECTION
+     */
+    is(type: 'selection' | 'model:selection'): this is Selection | DocumentSelection;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/documentselection~DocumentSelection}.
+     *
+     * ```ts
+     * selection.is( 'selection' ); // -> true
+     * selection.is( 'documentSelection' ); // -> true
+     * selection.is( 'model:selection' ); // -> true
+     * selection.is( 'model:documentSelection' ); // -> true
+     *
+     * selection.is( 'view:selection' ); // -> false
+     * selection.is( 'element' ); // -> false
+     * selection.is( 'node' ); // -> false
+     * ```
+     *
+     * @label DOCUMENT_SELECTION
+     */
+    is(type: 'documentSelection' | 'model:documentSelection'): this is DocumentSelection;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/markercollection~Marker}.
+     *
+     * ```ts
+     * marker.is( 'marker' ); // -> true
+     * marker.is( 'model:marker' ); // -> true
+     *
+     * marker.is( 'view:element' ); // -> false
+     * marker.is( 'documentSelection' ); // -> false
+     * ```
+     *
+     * @label MARKER
+     */
+    is(type: 'marker' | 'model:marker'): this is Marker;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/textproxy~TextProxy}.
+     *
+     * ```ts
+     * textProxy.is( '$textProxy' ); // -> true
+     * textProxy.is( 'model:$textProxy' ); // -> true
+     *
+     * textProxy.is( 'view:$textProxy' ); // -> false
+     * textProxy.is( 'range' ); // -> false
+     * ```
+     *
+     * **Note:** Until version 20.0.0 this method wasn't accepting `'$textProxy'` type. The legacy `'textProxt'` type is still
+     * accepted for backward compatibility.
+     *
+     * @label TEXT_PROXY
+     */
+    is(type: '$textProxy' | 'model:$textProxy'): this is TextProxy;
+    /**
+     * Checks whether the object is of type {@link module:engine/model/element~Element} or its subclass and has the specified `name`.
+     *
+     * ```ts
+     * element.is( 'element', 'imageBlock' ); // -> true if this is an <imageBlock> element
+     * text.is( 'element', 'imageBlock' ); -> false
+     * ```
+     *
+     * @label ELEMENT_NAME
+     */
+    is<N extends string>(type: 'element' | 'model:element', name: N): this is (Element | RootElement) & {
+        name: N;
+    };
+    /**
+     * Checks whether the object is of type {@link module:engine/model/rootelement~RootElement} and has the specified `name`.
+     *
+     * ```ts
+     * rootElement.is( 'rootElement', '$root' );
+     * ```
+     *
+     * @label ROOT_ELEMENT_NAME
+     */
+    is<N extends string>(type: 'rootElement' | 'model:rootElement', name: N): this is RootElement & {
+        name: N;
+    };
+}

package/dist/types/model/utils/autoparagraphing.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type Node from '../node.js';
+import type Position from '../position.js';
+import type Schema from '../schema.js';
+import type Writer from '../writer.js';
+/**
+ * @module engine/model/utils/autoparagraphing
+ */
+/**
+ * Fixes all empty roots.
+ *
+ * @internal
+ * @param writer The model writer.
+ * @returns `true` if any change has been applied, `false` otherwise.
+ */
+export declare function autoParagraphEmptyRoots(writer: Writer): boolean;
+/**
+ * Checks if the given node wrapped with a paragraph would be accepted by the schema in the given position.
+ *
+ * @internal
+ * @param position The position at which to check.
+ * @param nodeOrType The child node or child type to check.
+ * @param schema A schema instance used for element validation.
+ */
+export declare function isParagraphable(position: Position, nodeOrType: Node | string, schema: Schema): boolean;
+/**
+ * Inserts a new paragraph at the given position and returns a position inside that paragraph.
+ *
+ * @internal
+ * @param position The position where a paragraph should be inserted.
+ * @param writer The model writer.
+ * @returns  Position inside the created paragraph.
+ */
+export declare function wrapInParagraph(position: Position, writer: Writer): Position;

package/dist/types/model/utils/deletecontent.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/deletecontent
+ */
+import DocumentSelection from '../documentselection.js';
+import type Model from '../model.js';
+import type Selection from '../selection.js';
+/**
+ * Deletes content of the selection and merge siblings. The resulting selection is always collapsed.
+ *
+ * **Note:** Use {@link module:engine/model/model~Model#deleteContent} instead of this function.
+ * This function is only exposed to be reusable in algorithms
+ * which change the {@link module:engine/model/model~Model#deleteContent}
+ * method's behavior.
+ *
+ * @param model The model in context of which the insertion should be performed.
+ * @param selection Selection of which the content should be deleted.
+ * @param options.leaveUnmerged Whether to merge elements after removing the content of the selection.
+ *
+ * For example `<heading>x[x</heading><paragraph>y]y</paragraph>` will become:
+ *
+ * * `<heading>x^y</heading>` with the option disabled (`leaveUnmerged == false`)
+ * * `<heading>x^</heading><paragraph>y</paragraph>` with enabled (`leaveUnmerged == true`).
+ *
+ * Note: {@link module:engine/model/schema~Schema#isObject object} and {@link module:engine/model/schema~Schema#isLimit limit}
+ * elements will not be merged.
+ *
+ * @param options.doNotResetEntireContent Whether to skip replacing the entire content with a
+ * paragraph when the entire content was selected.
+ *
+ * For example `<heading>[x</heading><paragraph>y]</paragraph>` will become:
+ *
+ * * `<paragraph>^</paragraph>` with the option disabled (`doNotResetEntireContent == false`)
+ * * `<heading>^</heading>` with enabled (`doNotResetEntireContent == true`).
+ *
+ * @param options.doNotAutoparagraph Whether to create a paragraph if after content deletion selection is moved
+ * to a place where text cannot be inserted.
+ *
+ * For example `<paragraph>x</paragraph>[<imageBlock src="foo.jpg"></imageBlock>]` will become:
+ *
+ * * `<paragraph>x</paragraph><paragraph>[]</paragraph>` with the option disabled (`doNotAutoparagraph == false`)
+ * * `<paragraph>x</paragraph>[]` with the option enabled (`doNotAutoparagraph == true`).
+ *
+ * If you use this option you need to make sure to handle invalid selections yourself or leave
+ * them to the selection post-fixer (may not always work).
+ *
+ * **Note:** If there is no valid position for the selection, the paragraph will always be created:
+ *
+ * `[<imageBlock src="foo.jpg"></imageBlock>]` -> `<paragraph>[]</paragraph>`.
+ */
+export default function deleteContent(model: Model, selection: Selection | DocumentSelection, options?: {
+    leaveUnmerged?: boolean;
+    doNotResetEntireContent?: boolean;
+    doNotAutoparagraph?: boolean;
+}): void;

package/dist/types/model/utils/getselectedcontent.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @license Copyright (c) 2003-2024, 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/dist/types/model/utils/insertcontent.d.ts

@@ -0,0 +1,46 @@
+/**
+ * @license Copyright (c) 2003-2024, 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;