@ckeditor/ckeditor5-engine 44.1.0-alpha.5 → 44.2.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-engine",
-  "version": "44.1.0-alpha.5",
+  "version": "44.2.0-alpha.0",
   "description": "The editing engine of CKEditor 5 – the best browser-based rich text editor.",
   "keywords": [
     "wysiwyg",
@@ -24,7 +24,7 @@
   "type": "module",
   "main": "src/index.js",
   "dependencies": {
-    "@ckeditor/ckeditor5-utils": "44.1.0-alpha.5",
+    "@ckeditor/ckeditor5-utils": "44.2.0-alpha.0",
     "lodash-es": "4.17.21"
   },
   "author": "CKSource (http://cksource.com/)",
@@ -45,5 +45,25 @@
     "ckeditor5-metadata.json",
     "CHANGELOG.md"
   ],
-  "types": "src/index.d.ts"
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./dist/*": {
+      "types": "./src/index.d.ts",
+      "import": "./dist/*",
+      "default": "./dist/*"
+    },
+    "./src/*": {
+      "types": "./src/*.d.ts",
+      "import": "./src/*",
+      "default": "./src/*"
+    },
+    "./theme/*": "./theme/*",
+    "./ckeditor5-metadata.json": "./ckeditor5-metadata.json",
+    "./package.json": "./package.json"
+  }
 }

package/src/controller/datacontroller.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 import Mapper from '../conversion/mapper.js';

package/src/controller/datacontroller.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 /**

package/src/controller/editingcontroller.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 import View from '../view/view.js';

package/src/controller/editingcontroller.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 /**

package/src/conversion/conversion.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 /**

package/src/conversion/conversion.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 /**

package/src/conversion/conversionhelpers.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 /**

package/src/conversion/conversionhelpers.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 /**

package/src/conversion/downcastdispatcher.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 /**

package/src/conversion/downcastdispatcher.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 /**

package/src/conversion/downcasthelpers.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 /**

package/src/conversion/downcasthelpers.js

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 /**

package/src/conversion/mapper.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
+ * @license Copyright (c) 2003-2025, CKSource Holding sp. z o.o. All rights reserved.
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-licensing-options
  */
 /**
@@ -13,7 +13,7 @@ import type ViewDocumentFragment from '../view/documentfragment.js';
 import type ViewElement from '../view/element.js';
 import type ModelElement from '../model/element.js';
 import type ModelDocumentFragment from '../model/documentfragment.js';
-import type ViewNode from '../view/node.js';
+import type { default as ViewNode } from '../view/node.js';
 declare const Mapper_base: {
     new (): import("@ckeditor/ckeditor5-utils").Emitter;
     prototype: import("@ckeditor/ckeditor5-utils").Emitter;
@@ -73,6 +73,10 @@ export default class Mapper extends /* #__PURE__ */ Mapper_base {
      * has been removed, moved or renamed).
      */
     private _unboundMarkerNames;
+    /**
+     * Manages dynamic cache for the `Mapper` to improve the performance.
+     */
+    private _cache;
     /**
      * Creates an instance of the mapper.
      */
@@ -224,6 +228,10 @@ export default class Mapper extends /* #__PURE__ */ Mapper_base {
      */
     markerNameToElements(name: string): Set<ViewElement> | null;
     /**
+     * **This method is deprecated and will be removed in one of the future CKEditor 5 releases.**
+     *
+     * **Using this method will turn off `Mapper` caching system and may degrade performance when operating on bigger documents.**
+     *
      * Registers a callback that evaluates the length in the model of a view element with the given name.
      *
      * The callback is fired with one argument, which is a view element instance. The callback is expected to return
@@ -253,6 +261,7 @@ export default class Mapper extends /* #__PURE__ */ Mapper_base {
      *
      * @param viewElementName Name of view element for which callback is registered.
      * @param lengthCallback Function return a length of view element instance in model.
+     * @deprecated
      */
     registerViewToModelLength(viewElementName: string, lengthCallback: (element: ViewElement) => number): void;
     /**
@@ -310,32 +319,44 @@ export default class Mapper extends /* #__PURE__ */ Mapper_base {
      */
     getModelLength(viewNode: ViewNode | ViewDocumentFragment): number;
     /**
-     * Finds the position in the view node (or in its children) with the expected model offset.
+     * Finds the position in a view element or view document fragment node (or in its children) with the expected model offset.
      *
-     * Example:
+     * If the passed `viewContainer` is bound to model, `Mapper` will use caching mechanism to improve performance.
      *
-     * ```
-     * <p>fo<b>bar</b>bom</p> -> expected offset: 4
+     * @param viewContainer Tree view element in which we are looking for the position.
+     * @param modelOffset Expected offset.
+     * @returns Found position.
+     */
+    findPositionIn(viewContainer: ViewElement | ViewDocumentFragment, modelOffset: number): ViewPosition;
+    /**
+     * Performs most of the logic for `Mapper#findPositionIn()`.
      *
-     * findPositionIn( p, 4 ):
-     * <p>|fo<b>bar</b>bom</p> -> expected offset: 4, actual offset: 0
-     * <p>fo|<b>bar</b>bom</p> -> expected offset: 4, actual offset: 2
-     * <p>fo<b>bar</b>|bom</p> -> expected offset: 4, actual offset: 5 -> we are too far
+     * It allows to start looking for the requested model offset from a given starting position, to enable caching. Using the cache,
+     * you can set the starting point and skip all the calculations that were already previously done.
      *
-     * findPositionIn( b, 4 - ( 5 - 3 ) ):
-     * <p>fo<b>|bar</b>bom</p> -> expected offset: 2, actual offset: 0
-     * <p>fo<b>bar|</b>bom</p> -> expected offset: 2, actual offset: 3 -> we are too far
+     * This method uses recursion to find positions inside deep structures. Example:
      *
-     * findPositionIn( bar, 2 - ( 3 - 3 ) ):
-     * We are in the text node so we can simple find the offset.
-     * <p>fo<b>ba|r</b>bom</p> -> expected offset: 2, actual offset: 2 -> position found
      * ```
+     * <p>fo<b>bar</b>bom</p>  -> target offset: 4
+     * <p>|fo<b>bar</b>bom</p> -> target offset: 4, traversed offset: 0
+     * <p>fo|<b>bar</b>bom</p> -> target offset: 4, traversed offset: 2
+     * <p>fo<b>bar</b>|bom</p> -> target offset: 4, traversed offset: 5 -> we are too far, look recursively in <b>.
      *
-     * @param viewParent Tree view element in which we are looking for the position.
-     * @param expectedOffset Expected offset.
-     * @returns Found position.
+     * <p>fo<b>|bar</b>bom</p> -> target offset: 4, traversed offset: 2
+     * <p>fo<b>bar|</b>bom</p> -> target offset: 4, traversed offset: 5 -> we are too far, look inside "bar".
+     *
+     * <p>fo<b>ba|r</b>bom</p> -> target offset: 4, traversed offset: 2 -> position is inside text node at offset 4-2 = 2.
+     * ```
+     *
+     * @param startViewPosition View position to start looking from.
+     * @param startModelOffset Model offset related to `startViewPosition`.
+     * @param targetModelOffset Target model offset to find.
+     * @param viewContainer Mapped ancestor of `startViewPosition`. `startModelOffset` is the offset inside a model element or model
+     * document fragment mapped to `viewContainer`.
+     * @param useCache Whether `Mapper` should cache positions while traversing the view tree looking for `expectedModelOffset`.
+     * @returns View position mapped to `targetModelOffset`.
      */
-    findPositionIn(viewParent: ViewNode | ViewDocumentFragment, expectedOffset: number): ViewPosition;
+    private _findPositionStartingFrom;
     /**
      * Because we prefer positions in the text nodes over positions next to text nodes, if the view position was next to a text node,
      * it moves it into the text node instead.
@@ -351,6 +372,197 @@ export default class Mapper extends /* #__PURE__ */ Mapper_base {
      */
     private _moveViewPositionToTextNode;
 }
+declare const MapperCache_base: {
+    new (): import("@ckeditor/ckeditor5-utils").Emitter;
+    prototype: import("@ckeditor/ckeditor5-utils").Emitter;
+};
+/**
+ * Cache mechanism for {@link module:engine/conversion/mapper~Mapper Mapper}.
+ *
+ * `MapperCache` improves performance for model-to-view position mapping, which is the main `Mapper` task. Asking for a mapping is much
+ * more frequent than actually performing changes, and even if the change happens, we can still partially keep the cache. This makes
+ * caching a useful strategy for `Mapper`.
+ *
+ * `MapperCache` will store some data for view elements or view document fragments that are mapped by the `Mapper`. These view items
+ * are "tracked" by the `MapperCache`. For such view items, we will keep entries of model offsets inside their mapped counterpart. For
+ * the cached model offsets, we will keep a view position that is inside the tracked item. This allows us to either get the mapping
+ * instantly, or at least in less steps than when calculating it from the beginning.
+ *
+ * Important problem related to caching is invalidating the cache. The cache must be invalidated each time the tracked view item changes.
+ * Additionally, we should invalidate as small part of the cache as possible. Since all the logic is encapsulated inside `MapperCache`,
+ * the `MapperCache` listens to view items {@link module:engine/view/node~ViewNodeChangeEvent `change` event} and reacts to it.
+ * Then, it invalidates just the part of the cache that is "after" the changed part of the view.
+ *
+ * As mentioned, `MapperCache` currently is used only for model-to-view position mapping as it was much bigger problem than view-to-model
+ * mapping. However, it should be possible to use it also for view-to-model.
+ *
+ * The main assumptions regarding `MapperCache` are:
+ *
+ * * it is an internal tool, used by `Mapper`, transparent to the outside (no additional effort when developing a plugin or a converter),
+ * * it stores all the necessary data internally, which makes it easier to disable or debug,
+ * * it is optimized for initial downcast process (long insertions), which is crucial for editor init and data save,
+ * * it does not save all possible positions for memory considerations, although it is a possible improvement, which may have increase
+ *   performance, as well as simplify some parts of the `MapperCache` logic.
+ *
+ * @internal
+ */
+export declare class MapperCache extends /* #__PURE__ */ MapperCache_base {
+    /**
+     * For every view element or document fragment tracked by `MapperCache`, it holds currently cached data, or more precisely,
+     * model offset to view position mappings. See also `MappingCache` and `CacheItem`.
+     *
+     * If an item is tracked by `MapperCache` it has an entry in this structure, so this structure can be used to check which items
+     * are tracked by `MapperCache`. When an item is no longer tracked, it is removed from this structure.
+     *
+     * Although `MappingCache` and `CacheItem` structures allows for caching any model offsets and view positions, we only cache
+     * values for model offsets that are after a view node. So, in essence, positions inside text nodes are not cached. However, it takes
+     * from one to at most a few steps, to get from a cached position to a position that is inside a view text node.
+     *
+     * Additionally, only one item per `modelOffset` is cached. There can be several view nodes that "end" at the same `modelOffset`.
+     * In this case, we favour positions that are closer to the mapped item. For example
+     *
+     * * for model: `<paragraph>Some <$text bold=true italic=true>formatted</$text> text.</paragraph>`,
+     * * and view: `<p>Some <em><strong>formatted</strong></em> text.</p>`,
+     *
+     * for model offset `14` (after "d"), we store view position after `<em>` element (i.e. view position: at `<p>`, offset `2`).
+     */
+    private _cachedMapping;
+    /**
+     * When `MapperCache` {@link ~MapperCache#save saves} view position -> model offset mapping, a `CacheItem` is inserted into certain
+     * `MappingCache#cacheList` at some index. Additionally, we store that index with the view node that is before the cached view position.
+     *
+     * This allows to quickly get a cache list item related to certain view node, and hence, for fast cache invalidation.
+     *
+     * For example, consider view: `<p>Some <strong>bold</strong> text.</p>`, where `<p>` is a view element tracked by `MapperCache`.
+     * If all `<p>` children were visited by `MapperCache`, then `<p>` cache list would have four items, related to following model offsets:
+     * `0`, `5`, `9`, `15`. Then, view node `"Some "` would have index `1`, `<strong>` index `2`, and `" text." index `3`.
+     *
+     * Note that the index related with a node is always greater than `0`. The first item in cache list is always for model offset `0`
+     * (and view offset `0`), and it is not related to any node.
+     */
+    private _nodeToCacheListIndex;
+    /**
+     * Callback fired whenever there is a direct or indirect children change in tracked view element or tracked view document fragment.
+     *
+     * This is specified as a property to make it easier to set as an event callback and to later turn off that event.
+     */
+    private _invalidateOnChildrenChangeCallback;
+    /**
+     * Callback fired whenever a view text node directly or indirectly inside a tracked view element or tracked view document fragment
+     * changes its text data.
+     *
+     * This is specified as a property to make it easier to set as an event callback and to later turn off that event.
+     */
+    private _invalidateOnTextChangeCallback;
+    /**
+     * Saves cache for given view position mapping <-> model offset mapping. The view position should be after a node (i.e. it cannot
+     * be the first position inside its parent, or in other words, `viewOffset` must be greater than `0`).
+     *
+     * @param viewParent View position parent.
+     * @param viewOffset View position offset. Must be greater than `0`.
+     * @param viewContainer Tracked view position ascendant (it may be the direct parent of the view position).
+     * @param modelOffset Model offset in the model element or document fragment which is mapped to `viewContainer`.
+     */
+    save(viewParent: ViewElement | ViewDocumentFragment, viewOffset: number, viewContainer: ViewElement | ViewDocumentFragment, modelOffset: number): void;
+    /**
+     * For given `modelOffset` inside a model element mapped to given `viewContainer`, it returns the closest saved cache item
+     * (view position and related model offset) to the requested one.
+     *
+     * It can be exactly the requested mapping, or it can be mapping that is the closest starting point to look for the requested mapping.
+     *
+     * `viewContainer` must be a view element or document fragment that is mapped by the {@link ~Mapper Mapper}.
+     *
+     * If `viewContainer` is not yet tracked by the `MapperCache`, it will be automatically tracked after calling this method.
+     *
+     * Note: this method will automatically "hoist" cached positions, i.e. it will return a position that is closest to the tracked element.
+     *
+     * For example, if `<p>` is tracked element, and `^` is cached position:
+     *
+     * ```
+     * <p>This is <strong>some <em>heavily <u>formatted</u>^</em></strong> text.</p>
+     * ```
+     *
+     * If this position would be returned, instead, a position directly in `<p>` would be returned:
+     *
+     * ```
+     * <p>This is <strong>some <em>heavily <u>formatted</u></em></strong>^ text.</p>
+     * ```
+     *
+     * Note, that `modelOffset` for both positions is the same.
+     *
+     * @param viewContainer Tracked view element or document fragment, which cache will be used.
+     * @param modelOffset Model offset in a model element or document fragment, which is mapped to `viewContainer`.
+     */
+    getClosest(viewContainer: ViewElement | ViewDocumentFragment, modelOffset: number): CacheItem;
+    /**
+     * Moves a view position to a preferred location.
+     *
+     * The view position is moved up from a non-tracked view element as long as it remains at the end of its current parent.
+     *
+     * See example below to understand when it is important:
+     *
+     * Starting state:
+     *
+     * ```
+     * <p>This is <strong>some <em>heavily <u>formatted</u>^ piece of</em></strong> text.</p>
+     * ```
+     *
+     * Then we remove " piece of " and invalidate some cache:
+     *
+     * ```
+     * <p>This is <strong>some <em>heavily <u>formatted</u>^</em></strong> text.</p>
+     * ```
+     *
+     * Now, if we ask for model offset after letter "d" in "formatted", we should get a position in " text", but we will get in `<em>`.
+     * For this scenario, we need to hoist the position.
+     *
+     * ```
+     * <p>This is <strong>some <em>heavily <u>formatted</u></em></strong>^ text.</p>
+     * ```
+     */
+    private _hoistViewPosition;
+    /**
+     * Starts tracking given `viewContainer`, which must be mapped to a model element or model document fragment.
+     *
+     * Note, that this method is automatically called by
+     * {@link module:engine/conversion/mapper~MapperCache#getClosest `MapperCache#getClosest()`} and there is no need to call it manually.
+     *
+     * This method initializes the cache for `viewContainer` and adds callbacks for
+     * {@link module:engine/view/node~ViewNodeChangeEvent `change` event} fired by `viewContainer`. `MapperCache` listens to `change` event
+     * on the tracked elements to invalidate the stored cache.
+     */
+    startTracking(viewContainer: ViewElement | ViewDocumentFragment): CacheItem;
+    /**
+     * Stops tracking given `viewContainer`.
+     *
+     * It removes the cached data and stops listening to {@link module:engine/view/node~ViewNodeChangeEvent `change` event} on the
+     * `viewContainer`.
+     */
+    stopTracking(viewContainer: ViewElement | ViewDocumentFragment): void;
+    /**
+     * Invalidates cache inside `viewParent`, starting from given `index` in that parent.
+     */
+    private _clearCacheInsideParent;
+    /**
+     * Clears all the cache for given tracked `viewContainer`.
+     */
+    private _clearCacheAll;
+    /**
+     * Clears all the stored cache starting before given `viewNode`. The `viewNode` can be any node that is inside a tracked view element
+     * or view document fragment.
+     */
+    private _clearCacheStartingBefore;
+    /**
+     * Clears all the cache in the cache list related to given `viewContainer`, starting from `index` (inclusive).
+     */
+    private _clearCacheFromIndex;
+    /**
+     * Finds a cache item in the given cache list, which `modelOffset` is closest (but smaller or equal) to given `offset`.
+     *
+     * Since `cacheList` is a sorted array, this uses binary search to retrieve the item quickly.
+     */
+    private _findInCacheList;
+}
 /**
  * Fired for each model-to-view position mapping request. The purpose of this event is to enable custom model-to-view position
  * mapping. Callbacks added to this event take {@link module:engine/model/position~Position model position} and are expected to
@@ -500,4 +712,21 @@ export type MapperViewToModelPositionEventData = {
      */
     viewPosition: ViewPosition;
 };
+/**
+ * Informs that given `viewPosition` corresponds to given `modelOffset` (with the assumption that the model offset is in a model element
+ * mapped to the `viewPosition` parent or its ancestor).
+ *
+ * For example, for model `<paragraph>Some <$text bold=true>bold</$text> text</paragraph>` and view `<p>Some <strong>bold</strong> text</p>`
+ * and assuming `<paragraph>` and `<p>` are mapped, following example `CacheItem`s are possible:
+ *
+ * * `viewPosition` = `<p>`, 1; `modelOffset` = 5
+ * * `viewPosition` = `"bold"`, 2; `modelOffset` = 7
+ * * `viewPosition` = `<strong>, 1; `modelOffset` = 9
+ * * `viewPosition` = `" text"`, 0; `modelOffset` = 9
+ * * `viewPosition` = `<p>`, 2; `modelOffset` = 9
+ */
+type CacheItem = {
+    viewPosition: ViewPosition;
+    modelOffset: number;
+};
 export {};