@ckeditor/ckeditor5-engine 36.0.0 → 37.0.0-alpha.0

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;

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

@@ -0,0 +1,65 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import Range from '../range';
+import type Model from '../model';
+/**
+ * Injects selection post-fixer to the model.
+ *
+ * The role of the selection post-fixer is to ensure that the selection is in a correct place
+ * after a {@link module:engine/model/model~Model#change `change()`} block was executed.
+ *
+ * The correct position means that:
+ *
+ * * All collapsed selection ranges are in a place where the {@link module:engine/model/schema~Schema}
+ * allows a `$text`.
+ * * None of the selection's non-collapsed ranges crosses a {@link module:engine/model/schema~Schema#isLimit limit element}
+ * boundary (a range must be rooted within one limit element).
+ * * Only {@link module:engine/model/schema~Schema#isSelectable selectable elements} can be selected from the outside
+ * (e.g. `[<paragraph>foo</paragraph>]` is invalid). This rule applies independently to both selection ends, so this
+ * selection is correct: `<paragraph>f[oo</paragraph><imageBlock></imageBlock>]`.
+ *
+ * If the position is not correct, the post-fixer will automatically correct it.
+ *
+ * ## Fixing a non-collapsed selection
+ *
+ * See as an example a selection that starts in a P1 element and ends inside the text of a TD element
+ * (`[` and `]` are range boundaries and `(l)` denotes an element defined as `isLimit=true`):
+ *
+ * ```
+ * root
+ *  |- element P1
+ *  |   |- "foo"                                      root
+ *  |- element TABLE (l)                   P1         TABLE             P2
+ *  |   |- element TR (l)                 f o[o     TR      TR         b a r
+ *  |   |   |- element TD (l)                       TD      TD
+ *  |   |       |- "aaa"                          a]a a    b b b
+ *  |   |- element TR (l)
+ *  |   |   |- element TD (l)                           ||
+ *  |   |       |- "bbb"                                ||
+ *  |- element P2                                       VV
+ *  |   |- "bar"
+ *                                                    root
+ *                                         P1         TABLE]            P2
+ *                                        f o[o     TR      TR         b a r
+ *                                                  TD      TD
+ *                                                a a a    b b b
+ * ```
+ *
+ * In the example above, the TABLE, TR and TD are defined as `isLimit=true` in the schema. The range which is not contained within
+ * a single limit element must be expanded to select the outermost limit element. The range end is inside the text node of the TD element.
+ * As the TD element is a child of the TR and TABLE elements, where both are defined as `isLimit=true` in the schema, the range must be
+ * expanded to select the whole TABLE element.
+ *
+ * **Note** If the selection contains multiple ranges, the method returns a minimal set of ranges that are not intersecting after expanding
+ * them to select `isLimit=true` elements.
+ */
+export declare function injectSelectionPostFixer(model: Model): void;
+/**
+ * Returns a minimal non-intersecting array of ranges without duplicates.
+ *
+ * @param ranges Ranges to merge.
+ * @returns Array of unique and non-intersecting ranges.
+ */
+export declare function mergeIntersectingRanges(ranges: Array<Range>): Array<Range>;