@ckeditor/ckeditor5-engine 41.4.2 → 42.0.0-alpha.0

package/src/controller/datacontroller.d.ts

@@ -38,7 +38,7 @@ declare const DataController_base: {
  * editor.data.get( { rootName: 'customRoot' } ); // -> '<p>Hello!</p>'
  * ```
  */
-export default class DataController extends DataController_base {
+export default class DataController extends /* #__PURE__ */ DataController_base {
     /**
      * Data model.
      */

package/src/controller/datacontroller.js

@@ -34,7 +34,7 @@ import HtmlDataProcessor from '../dataprocessor/htmldataprocessor.js';
  * editor.data.get( { rootName: 'customRoot' } ); // -> '<p>Hello!</p>'
  * ```
  */
-export default class DataController extends EmitterMixin() {
+export default class DataController extends /* #__PURE__ */ EmitterMixin() {
     /**
      * Creates a data controller instance.
      *

package/src/controller/editingcontroller.d.ts

@@ -18,7 +18,7 @@ declare const EditingController_base: {
  * including selection handling. It also creates the {@link ~EditingController#view view} which builds a
  * browser-independent virtualization over the DOM elements. The editing controller also attaches default converters.
  */
-export default class EditingController extends EditingController_base {
+export default class EditingController extends /* #__PURE__ */ EditingController_base {
     /**
      * Editor model.
      */

package/src/controller/editingcontroller.js

@@ -19,7 +19,7 @@ import { tryFixingRange } from '../model/utils/selection-post-fixer.js';
  * including selection handling. It also creates the {@link ~EditingController#view view} which builds a
  * browser-independent virtualization over the DOM elements. The editing controller also attaches default converters.
  */
-export default class EditingController extends ObservableMixin() {
+export default class EditingController extends /* #__PURE__ */ ObservableMixin() {
     /**
      * Creates an editing controller instance.
      *

package/src/conversion/downcastdispatcher.d.ts

@@ -113,7 +113,7 @@ declare const DowncastDispatcher_base: {
  * } );
  * ```
  */
-export default class DowncastDispatcher extends DowncastDispatcher_base {
+export default class DowncastDispatcher extends /* #__PURE__ */ DowncastDispatcher_base {
     /**
      * A template for an interface passed by the dispatcher to the event callbacks.
      *

package/src/conversion/downcastdispatcher.js

@@ -99,7 +99,7 @@ import { EmitterMixin } from '@ckeditor/ckeditor5-utils';
  * } );
  * ```
  */
-export default class DowncastDispatcher extends EmitterMixin() {
+export default class DowncastDispatcher extends /* #__PURE__ */ EmitterMixin() {
     /**
      * Creates a downcast dispatcher instance.
      *

package/src/conversion/mapper.d.ts

@@ -37,7 +37,7 @@ declare const Mapper_base: {
  * with `'lowest'` priority. To override default `Mapper` mapping, add custom callback with higher priority and
  * stop the event.
  */
-export default class Mapper extends Mapper_base {
+export default class Mapper extends /* #__PURE__ */ Mapper_base {
     /**
      * Model element to view element mapping.
      */

package/src/conversion/mapper.js

@@ -30,7 +30,7 @@ import { CKEditorError, EmitterMixin } from '@ckeditor/ckeditor5-utils';
  * with `'lowest'` priority. To override default `Mapper` mapping, add custom callback with higher priority and
  * stop the event.
  */
-export default class Mapper extends EmitterMixin() {
+export default class Mapper extends /* #__PURE__ */ EmitterMixin() {
     /**
      * Creates an instance of the mapper.
      */

package/src/conversion/upcastdispatcher.d.ts

@@ -117,7 +117,7 @@ declare const UpcastDispatcher_base: {
  * @fires text
  * @fires documentFragment
  */
-export default class UpcastDispatcher extends UpcastDispatcher_base {
+export default class UpcastDispatcher extends /* #__PURE__ */ UpcastDispatcher_base {
     /**
      * An interface passed by the dispatcher to the event callbacks.
      */

package/src/conversion/upcastdispatcher.js

@@ -107,7 +107,7 @@ import { CKEditorError, EmitterMixin } from '@ckeditor/ckeditor5-utils';
  * @fires text
  * @fires documentFragment
  */
-export default class UpcastDispatcher extends EmitterMixin() {
+export default class UpcastDispatcher extends /* #__PURE__ */ EmitterMixin() {
     /**
      * Creates an upcast dispatcher that operates using the passed API.
      *

package/src/index.d.ts

@@ -17,6 +17,7 @@ export type { default as ModelConsumable } from './conversion/modelconsumable.js
 export type { Consumables, default as ViewConsumable } from './conversion/viewconsumable.js';
 export type { default as DataProcessor } from './dataprocessor/dataprocessor.js';
 export { default as HtmlDataProcessor } from './dataprocessor/htmldataprocessor.js';
+export { default as XmlDataProcessor } from './dataprocessor/xmldataprocessor.js';
 export type { default as Operation } from './model/operation/operation.js';
 export { default as InsertOperation } from './model/operation/insertoperation.js';
 export { default as MoveOperation } from './model/operation/moveoperation.js';
@@ -88,7 +89,7 @@ export { default as ClickObserver } from './view/observer/clickobserver.js';
 export { default as DomEventObserver } from './view/observer/domeventobserver.js';
 export { default as MouseObserver } from './view/observer/mouseobserver.js';
 export { default as TabObserver } from './view/observer/tabobserver.js';
-export { default as FocusObserver } from './view/observer/focusobserver.js';
+export { default as FocusObserver, type ViewDocumentBlurEvent, type ViewDocumentFocusEvent } from './view/observer/focusobserver.js';
 export { default as DowncastWriter } from './view/downcastwriter.js';
 export { default as UpcastWriter } from './view/upcastwriter.js';
 export { default as Matcher, type MatcherPattern, type MatcherObjectPattern, type Match, type MatchResult } from './view/matcher.js';

package/src/index.js

@@ -12,6 +12,7 @@ export { default as DataController } from './controller/datacontroller.js';
 // Conversion.
 export { default as Conversion } from './conversion/conversion.js';
 export { default as HtmlDataProcessor } from './dataprocessor/htmldataprocessor.js';
+export { default as XmlDataProcessor } from './dataprocessor/xmldataprocessor.js';
 export { default as InsertOperation } from './model/operation/insertoperation.js';
 export { default as MoveOperation } from './model/operation/moveoperation.js';
 export { default as MergeOperation } from './model/operation/mergeoperation.js';

package/src/model/differ.d.ts

@@ -8,8 +8,8 @@
 import Position from './position.js';
 import Range from './range.js';
 import type { default as MarkerCollection, MarkerData } from './markercollection.js';
-import type Element from './element.js';
 import type Item from './item.js';
+import type Node from './node.js';
 import type RootElement from './rootelement.js';
 import type Operation from './operation/operation.js';
 /**
@@ -21,6 +21,11 @@ import type Operation from './operation/operation.js';
  * elements and new ones and returns a change set.
  */
 export default class Differ {
+    /**
+     * Priority of the {@link ~Differ#_elementState element states}. States on higher indexes of the array can overwrite states on the lower
+     * indexes.
+     */
+    private static readonly _statesPriority;
     /**
      * Reference to the model's marker collection.
      */
@@ -33,18 +38,48 @@ export default class Differ {
      */
     private readonly _changesInElement;
     /**
-     * A map that stores "element's children snapshots". A snapshot is representing children of a given element before
-     * the first change was applied on that element. Snapshot items are objects with two properties: `name`,
-     * containing the element name (or `'$text'` for a text node) and `attributes` which is a map of the node's attributes.
+     * Stores a snapshot for these model nodes that might have changed.
+     *
+     * This complements {@link ~Differ#_elementChildrenSnapshots `_elementChildrenSnapshots`}.
+     *
+     * See also {@link ~DifferSnapshot}.
      */
-    private readonly _elementSnapshots;
+    private readonly _elementsSnapshots;
+    /**
+     * For each element or document fragment inside which there was a change, it stores a snapshot of the child nodes list (an array
+     * of children snapshots that represent the state in the element / fragment before any change has happened).
+     *
+     * This complements {@link ~Differ#_elementsSnapshots `_elementsSnapshots`}.
+     *
+     * See also {@link ~DifferSnapshot}.
+     */
+    private readonly _elementChildrenSnapshots;
+    /**
+     * Keeps the state for a given element, describing how the element was changed so far. It is used to evaluate the `action` property
+     * of diff items returned by {@link ~Differ#getChanges}.
+     *
+     * Possible values, in the order from the lowest priority to the highest priority:
+     *
+     * * `'refresh'` - element was refreshed,
+     * * `'rename'` - element was renamed,
+     * * `'move'` - element was moved (or, usually, removed, that is moved to the graveyard).
+     *
+     * Element that was refreshed, may change its state to `'rename'` if it was later renamed, or to `'move'` if it was removed.
+     * But the element cannot change its state from `'move'` to `'rename'`, or from `'rename'` to `'refresh'`.
+     *
+     * Only already existing elements are registered in `_elementState`. If a new element was inserted as a result of a buffered operation,
+     * it is not be registered in `_elementState`.
+     */
+    private readonly _elementState;
     /**
      * A map that stores all changed markers.
      *
      * The keys of the map are marker names.
+     *
      * The values of the map are objects with the following properties:
-     * - `oldMarkerData`,
-     * - `newMarkerData`.
+     *
+     * * `oldMarkerData`,
+     * * `newMarkerData`.
      */
     private readonly _changedMarkers;
     /**
@@ -89,7 +124,7 @@ export default class Differ {
      */
     get isEmpty(): boolean;
     /**
-     * Buffers the given operation. An operation has to be buffered before it is executed.
+     * Buffers the given operation. **An operation has to be buffered before it is executed.**
      *
      * @param operationToBuffer An operation to buffer.
      */
@@ -177,14 +212,6 @@ export default class Differ {
      * Resets `Differ`. Removes all buffered changes.
      */
     reset(): void;
-    /**
-     * Buffers the root state change after the root was attached or detached
-     */
-    private _bufferRootStateChange;
-    /**
-     * Buffers a root attribute change.
-     */
-    private _bufferRootAttributeChange;
     /**
      * Marks the given `item` in differ to be "refreshed". It means that the item will be marked as removed and inserted
      * in the differ changes set, so it will be effectively re-converted when the differ changes are handled by a dispatcher.
@@ -206,6 +233,14 @@ export default class Differ {
      * @internal
      */
     _bufferRootLoad(root: RootElement): void;
+    /**
+     * Buffers the root state change after the root was attached or detached
+     */
+    private _bufferRootStateChange;
+    /**
+     * Buffers a root attribute change.
+     */
+    private _bufferRootAttributeChange;
     /**
      * Saves and handles an insert change.
      */
@@ -222,14 +257,34 @@ export default class Differ {
      * Saves and handles a model change.
      */
     private _markChange;
+    /**
+     * Tries to set given state for given item.
+     *
+     * This method does simple validation (it sets the state only for model elements, not for text proxy nodes). It also follows state
+     * setting rules, that is, `'refresh'` cannot overwrite `'rename'`, and `'rename'` cannot overwrite `'move'`.
+     */
+    private _setElementState;
+    /**
+     * Returns a value for {@link ~DifferItemAction `action`} property for diff items returned by {@link ~Differ#getChanges}.
+     * This method aims to return `'rename'` or `'refresh'` when it should, and `diffItemType` ("default action") in all other cases.
+     *
+     * It bases on a few factors:
+     *
+     * * for text nodes, the method always returns `diffItemType`,
+     * * for newly inserted element, the method returns `diffItemType`,
+     * * if {@link ~Differ#_elementState element state} was not recorded, the method returns `diffItemType`,
+     * * if state was recorded, and it was `'move'` (default action), the method returns `diffItemType`,
+     * * finally, if state was `'refresh'` or `'rename'`, the method returns the state value.
+     */
+    private _getDiffActionForNode;
     /**
      * Gets an array of changes that have already been saved for a given element.
      */
     private _getChangesForElement;
     /**
-     * Saves a children snapshot for a given element.
+     * Creates and saves a snapshot for all children of the given element.
      */
-    private _makeSnapshot;
+    private _makeSnapshots;
     /**
      * For a given newly saved change, compares it with a change already done on the element and modifies the incoming
      * change and/or the old change.
@@ -243,7 +298,9 @@ export default class Differ {
      *
      * @param parent The element in which the change happened.
      * @param offset The offset at which change happened.
-     * @param elementSnapshot The snapshot of the removed element a character.
+     * @param action Further specifies what kind of action led to generating this change.
+     * @param elementSnapshot Snapshot of the inserted node after changes.
+     * @param elementSnapshotBefore Snapshot of the inserted node before changes.
      * @returns The diff item.
      */
     private _getInsertDiff;
@@ -252,7 +309,8 @@ export default class Differ {
      *
      * @param parent The element in which change happened.
      * @param offset The offset at which change happened.
-     * @param elementSnapshot The snapshot of the removed element a character.
+     * @param action Further specifies what kind of action led to generating this change.
+     * @param elementSnapshot The snapshot of the removed node before changes.
      * @returns The diff item.
      */
     private _getRemoveDiff;
@@ -275,6 +333,32 @@ export default class Differ {
      */
     private _removeAllNestedChanges;
 }
+/**
+ * Further specifies what kind of action led to generating a change:
+ *
+ * * `'insert'` if element was inserted,
+ * * `'remove'` if element was removed,
+ * * `'rename'` if element got renamed (e.g. `writer.rename()`),
+ * * `'refresh'` if element got refreshed (e.g. `model.editing.reconvertItem()`).
+ */
+export type DifferItemAction = 'insert' | 'remove' | 'rename' | 'refresh';
+/**
+ * A snapshot is representing state of a given element before the first change was applied on that element.
+ */
+export interface DifferSnapshot {
+    /**
+     * Node for which was snapshot was made.
+     */
+    node: Node;
+    /**
+     * Name of the element at the time when the snapshot was made. For text node snapshots, it is set to `'$text'`.
+     */
+    name: string;
+    /**
+     * Attributes of the node at the time when the snapshot was made.
+     */
+    attributes: Map<string, unknown>;
+}
 /**
  * The single diff item.
  *
@@ -294,19 +378,19 @@ export interface DiffItemInsert {
      */
     type: 'insert';
     /**
-     * Reference to the model element that was inserted.
+     * Further specifies what kind of action led to generating this change.
      *
-     * Undefined if the diff item is related to text node insertion.
-     *
-     * @internal
+     * The action is set in relation to the document state before any change. It means that, for example, if an element was added and
+     * then renamed (during the same {@link module:engine/model/batch~Batch batch}), the action will be set to `'insert'`, because when
+     * compared to the document state before changes, a new element was inserted, and the renaming does not matter from this point of view.
      */
-    _element?: Element;
+    action: DifferItemAction;
     /**
      * The name of the inserted elements or `'$text'` for a text node.
      */
     name: string;
     /**
-     * Map of attributes that were set on the item while it was inserted.
+     * Map of attributes of the inserted element.
      */
     attributes: Map<string, unknown>;
     /**
@@ -317,6 +401,25 @@ export interface DiffItemInsert {
      * The length of an inserted text node. For elements, it is always 1 as each inserted element is counted as a one.
      */
     length: number;
+    /**
+     * Holds information about the element state before all changes happened.
+     *
+     * For example, when `<paragraph textAlign="right">` was changed to `<codeBlock language="plaintext">`,
+     * `before.name` will be equal to `'paragraph'` and `before.attributes` map will have one entry: `'textAlign' -> 'right'`.
+     *
+     * The property is available only if the insertion change was due to element rename or refresh (when `action` property is `'rename'`
+     * or `'refresh'`). As such, `before` property is never available for text node changes.
+     */
+    before?: {
+        /**
+         * The name of the inserted element before all changes.
+         */
+        name: string;
+        /**
+         * Map of the attributes of the inserted element before all changes.
+         */
+        attributes: Map<string, unknown>;
+    };
 }
 /**
  * A single diff item for removed nodes.
@@ -327,24 +430,13 @@ export interface DiffItemRemove {
      */
     type: 'remove';
     /**
-     * Reference to the model element that was removed.
-     *
-     * Undefined if the diff item is related to text node deletion.
+     * Further specifies what kind of action led to generating this change.
      *
-     * Note that this element will have the state after all changes has been performed on the model, not before. For example, if a paragraph
-     * was first renamed to `heading1`, and then removed, `element.name` will be `heading1`. Similarly, with attributes. Also, you should
-     * not read the element's position, as it will no longer point to the original element position.
-     *
-     * Instead, you should use {@link ~DiffItemRemove#name `DiffItemRemove#name`},
-     * {@link ~DiffItemRemove#attributes `DiffItemRemove#attributes`}, and {@link ~DiffItemRemove#position `DiffItemRemove#position`}.
-     *
-     * This property should be only used to check instance reference equality. For example, if you want to detect that some particular
-     * element was removed, you can check `_element` property. You can use it together with {@link ~DiffItemInsert#_element `#_element`} on
-     * insert diff items to detect move, refresh, or rename changes.
-     *
-     * @internal
+     * The action is set in relation to the document state before any change. It means that, for example, if an element was renamed and
+     * then removed (during the same {@link module:engine/model/batch~Batch batch}), the action will be set to `'remove'`, because when
+     * compared to the document state before changes, the element was removed, and it does not matter that it was also renamed at one point.
      */
-    _element?: Element;
+    action: DifferItemAction;
     /**
      * The name of the removed element or `'$text'` for a text node.
      */