@ckeditor/ckeditor5-engine 36.0.1 → 37.0.0-alpha.1

package/src/model/typecheckable.d.ts

@@ -0,0 +1,285 @@
+/**
+ * @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/typecheckable
+ */
+import type { Marker } from './markercollection';
+import type DocumentFragment from './documentfragment';
+import type DocumentSelection from './documentselection';
+import type Element from './element';
+import type LivePosition from './liveposition';
+import type LiveRange from './liverange';
+import type Node from './node';
+import type Position from './position';
+import type Range from './range';
+import type RootElement from './rootelement';
+import type Selection from './selection';
+import type Text from './text';
+import type TextProxy from './textproxy';
+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/src/model/utils/autoparagraphing.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @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 Node from '../node';
+import type Position from '../position';
+import type Schema from '../schema';
+import type Writer from '../writer';
+/**
+ * @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/src/model/utils/deletecontent.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @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/deletecontent
+ */
+import DocumentSelection from '../documentselection';
+import type Model from '../model';
+import type Selection from '../selection';
+/**
+ * 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/src/model/utils/findoptimalinsertionrange.d.ts

@@ -0,0 +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;

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

@@ -0,0 +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;

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

@@ -0,0 +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;

package/src/model/utils/insertcontent.js

@@ -11,7 +11,6 @@ import LivePosition from '../liveposition';
 import LiveRange from '../liverange';
 import Position from '../position';
 import Range from '../range';
-import Selection from '../selection';
 import { CKEditorError } from '@ckeditor/ckeditor5-utils';
 /**
  * Inserts content into the editor (specified selection) as one would expect the paste functionality to work.
@@ -45,18 +44,9 @@ import { CKEditorError } from '@ckeditor/ckeditor5-utils';
  * 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, content, selectable, placeOrOffset) {
+export default function insertContent(model, content, selectable) {
     return model.change(writer => {
-        let selection;
-        if (!selectable) {
-            selection = model.document.selection;
-        }
-        else if (selectable instanceof Selection || selectable instanceof DocumentSelection) {
-            selection = selectable;
-        }
-        else {
-            selection = writer.createSelection(selectable, placeOrOffset);
-        }
+        const selection = selectable ? selectable : model.document.selection;
         if (!selection.isCollapsed) {
             model.deleteContent(selection, { doNotAutoparagraph: true });
         }

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

@@ -0,0 +1,44 @@
+/**
+ * @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 Selection from '../selection';
+import type Element from '../element';
+import type Model from '../model';
+import type Range from '../range';
+/**
+ * Inserts an {@glink framework/deep-dive/schema#object-elements object element} at a specific position in the editor content.
+ *
+ * **Note:** Use {@link module:engine/model/model~Model#insertObject} instead of this function.
+ * This function is only exposed to be reusable in algorithms which change the {@link module:engine/model/model~Model#insertObject}
+ * method's behavior.
+ *
+ * **Note**: For more documentation and examples, see {@link module:engine/model/model~Model#insertObject}.
+ *
+ * @param model The model in context of which the insertion should be performed.
+ * @param object An object to be inserted into the model document.
+ * @param selectable A selectable where the content should be inserted. If not specified, the current
+ * {@link module:engine/model/document~Document#selection document selection} will be used instead.
+ * @param placeOrOffset Specifies the exact place or offset for the insertion to take place, relative to `selectable`.
+ * @param options Additional options.
+ * @param options.findOptimalPosition An option that, when set, adjusts the insertion position (relative to
+ * `selectable` and `placeOrOffset`) so that the content of `selectable` is not split upon insertion (a.k.a. non-destructive insertion).
+ * * When `'auto'`, the algorithm will decide whether to insert the object before or after `selectable` to avoid content splitting.
+ * * When `'before'`, the closest position before `selectable` will be used that will not result in content splitting.
+ * * When `'after'`, the closest position after `selectable` will be used that will not result in content splitting.
+ *
+ * Note that this option works only for block objects. Inline objects are inserted into text and do not split blocks.
+ * @param options.setSelection An option that, when set, moves the
+ * {@link module:engine/model/document~Document#selection document selection} after inserting the object.
+ * * When `'on'`, the document selection will be set on the inserted object.
+ * * When `'after'`, the document selection will move to the closest text node after the inserted object. If there is no
+ * such text node, a paragraph will be created and the document selection will be moved inside it.
+ * @returns A 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 `insertObject()`, returns a range collapsed
+ * at the insertion position.
+ */
+export default function insertObject(model: Model, object: Element, selectable?: Selection | DocumentSelection | null, options?: {
+    findOptimalPosition?: 'auto' | 'before' | 'after';
+    setSelection?: 'on' | 'after';
+}): Range;

package/src/model/utils/insertobject.js

@@ -6,11 +6,9 @@
  * @module engine/model/utils/insertobject
  */
 import { findOptimalInsertionRange } from './findoptimalinsertionrange';
-import DocumentSelection from '../documentselection';
-import Selection from '../selection';
 import { CKEditorError, first } from '@ckeditor/ckeditor5-utils';
 /**
- * Inserts an {@glink framework/guides/deep-dive/schema#object-elements object element} at a specific position in the editor content.
+ * Inserts an {@glink framework/deep-dive/schema#object-elements object element} at a specific position in the editor content.
  *
  * **Note:** Use {@link module:engine/model/model~Model#insertObject} instead of this function.
  * This function is only exposed to be reusable in algorithms which change the {@link module:engine/model/model~Model#insertObject}
@@ -40,7 +38,7 @@ import { CKEditorError, first } from '@ckeditor/ckeditor5-utils';
  * would return the model to the state before the insertion. If no changes were preformed by `insertObject()`, returns a range collapsed
  * at the insertion position.
  */
-export default function insertObject(model, object, selectable, placeOrOffset, options = {}) {
+export default function insertObject(model, object, selectable, options = {}) {
     if (!model.schema.isObject(object)) {
         /**
          * Tried to insert an element with {@link module:engine/model/utils/insertobject insertObject()} function
@@ -53,16 +51,7 @@ export default function insertObject(model, object, selectable, placeOrOffset, o
         throw new CKEditorError('insertobject-element-not-an-object', model, { object });
     }
     // Normalize selectable to a selection instance.
-    let originalSelection;
-    if (!selectable) {
-        originalSelection = model.document.selection;
-    }
-    else if (selectable instanceof Selection || selectable instanceof DocumentSelection) {
-        originalSelection = selectable;
-    }
-    else {
-        originalSelection = model.createSelection(selectable, placeOrOffset);
-    }
+    const originalSelection = selectable ? selectable : model.document.selection;
     // Adjust the insertion selection.
     let insertionSelection = originalSelection;
     if (options.findOptimalPosition && model.schema.isBlock(object)) {

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

@@ -0,0 +1,48 @@
+/**
+ * @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 type Model from '../model';
+import type Selection from '../selection';
+/**
+ * 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: Model, selection: Selection | DocumentSelection, options?: {
+    direction?: 'forward' | 'backward';
+    unit?: 'character' | 'codePoint' | 'word';
+    treatEmojiAsSingleUnit?: boolean;
+}): void;