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

package/src/model/model.js

@@ -12,8 +12,10 @@ import ModelPosition from './position';
 import ModelRange from './range';
 import ModelSelection from './selection';
 import OperationFactory from './operation/operationfactory';
+import DocumentSelection from './documentselection';
 import Schema from './schema';
 import Writer from './writer';
+import Node from './node';
 import { autoParagraphEmptyRoots } from './utils/autoparagraphing';
 import { injectSelectionPostFixer } from './utils/selection-post-fixer';
 import deleteContent from './utils/deletecontent';
@@ -22,13 +24,15 @@ import insertContent from './utils/insertcontent';
 import insertObject from './utils/insertobject';
 import modifySelection from './utils/modifyselection';
 import { CKEditorError, ObservableMixin } from '@ckeditor/ckeditor5-utils';
-// @if CK_DEBUG_ENGINE // const { dumpTrees } = require( '../dev-utils/utils' );
+// @if CK_DEBUG_ENGINE // const { dumpTrees, initDocumentDumping } = require( '../dev-utils/utils' );
 // @if CK_DEBUG_ENGINE // const { OperationReplayer } = require( '../dev-utils/operationreplayer' ).default;
 /**
  * Editor's data model. Read about the model in the
- * {@glink framework/guides/architecture/editing-engine engine architecture guide}.
+ * {@glink framework/architecture/editing-engine engine architecture} guide.
  */
 export default class Model extends ObservableMixin() {
+    // @if CK_DEBUG_ENGINE // private _operationLogs: Array<string>;
+    // @if CK_DEBUG_ENGINE // private _appliedOperations: Array<Operation>;
     constructor() {
         super();
         this.markers = new MarkerCollection();
@@ -36,7 +40,7 @@ export default class Model extends ObservableMixin() {
         this.schema = new Schema();
         this._pendingChanges = [];
         this._currentWriter = null;
-        ['insertContent', 'insertObject', 'deleteContent', 'modifySelection', 'getSelectedContent', 'applyOperation']
+        ['deleteContent', 'modifySelection', 'getSelectedContent', 'applyOperation']
             .forEach(methodName => this.decorate(methodName));
         // Adding operation validation with `highest` priority, so it is called before any other feature would like
         // to do anything with the operation. If the operation has incorrect parameters it should throw on the earliest occasion.
@@ -94,9 +98,20 @@ export default class Model extends ObservableMixin() {
         injectSelectionPostFixer(this);
         // Post-fixer which takes care of adding empty paragraph elements to the empty roots.
         this.document.registerPostFixer(autoParagraphEmptyRoots);
+        // The base implementation for "decorated" method with remapped arguments.
+        this.on('insertContent', (evt, [content, selectable]) => {
+            evt.return = insertContent(this, content, selectable);
+        });
+        // The base implementation for "decorated" method with remapped arguments.
+        this.on('insertObject', (evt, [element, selection, options]) => {
+            evt.return = insertObject(this, element, selection, options);
+        });
+        // @if CK_DEBUG_ENGINE // initDocumentDumping( this.document );
         // @if CK_DEBUG_ENGINE // this.on( 'applyOperation', () => {
         // @if CK_DEBUG_ENGINE // 	dumpTrees( this.document, this.document.version );
         // @if CK_DEBUG_ENGINE // }, { priority: 'lowest' } );
+        // @if CK_DEBUG_ENGINE // this._operationLogs = [];
+        // @if CK_DEBUG_ENGINE // this._appliedOperations = [];
     }
     /**
      * The `change()` method is the primary way of changing the model. You should use it to modify all document nodes
@@ -186,37 +201,31 @@ export default class Model extends ObservableMixin() {
      *
      * This is a low-level way of changing the model. It is exposed for very specific use cases (like the undo feature).
      * Normally, to modify the model, you will want to use {@link module:engine/model/writer~Writer `Writer`}.
-     * See also {@glink framework/guides/architecture/editing-engine#changing-the-model Changing the model} section
-     * of the {@glink framework/guides/architecture/editing-engine Editing architecture} guide.
+     * See also {@glink framework/architecture/editing-engine#changing-the-model Changing the model} section
+     * of the {@glink framework/architecture/editing-engine Editing architecture} guide.
      *
      * @param operation The operation to apply.
      */
     applyOperation(operation) {
         // @if CK_DEBUG_ENGINE // console.log( 'Applying ' + operation );
-        // @if CK_DEBUG_ENGINE // if ( !this._operationLogs ) {
-        // @if CK_DEBUG_ENGINE //	this._operationLogs = [];
-        // @if CK_DEBUG_ENGINE // }
         // @if CK_DEBUG_ENGINE // this._operationLogs.push( JSON.stringify( operation ) );
-        // @if CK_DEBUG_ENGINE //if ( !this._appliedOperations ) {
-        // @if CK_DEBUG_ENGINE //	this._appliedOperations = [];
-        // @if CK_DEBUG_ENGINE //}
-        // @if CK_DEBUG_ENGINE //this._appliedOperations.push( operation );
+        // @if CK_DEBUG_ENGINE // this._appliedOperations.push( operation );
         operation._execute();
     }
-    // @if CK_DEBUG_ENGINE // getAppliedOperation() {
-    // @if CK_DEBUG_ENGINE //	if ( !this._appliedOperations ) {
-    // @if CK_DEBUG_ENGINE //		return '';
-    // @if CK_DEBUG_ENGINE //	}
-    // @if CK_DEBUG_ENGINE //	return this._appliedOperations.map( JSON.stringify ).join( '-------' );
+    // @if CK_DEBUG_ENGINE // public getAppliedOperation(): string {
+    // @if CK_DEBUG_ENGINE // 	if ( !this._appliedOperations ) {
+    // @if CK_DEBUG_ENGINE // 		return '';
+    // @if CK_DEBUG_ENGINE // 	}
+    // @if CK_DEBUG_ENGINE // 	return this._appliedOperations.map( operation => JSON.stringify( operation ) ).join( '-------' );
     // @if CK_DEBUG_ENGINE // }
-    // @if CK_DEBUG_ENGINE // createReplayer( stringifiedOperations ) {
-    // @if CK_DEBUG_ENGINE //	return new OperationReplayer( this, '-------', stringifiedOperations );
+    // @if CK_DEBUG_ENGINE // public createReplayer( stringifiedOperations: string ): typeof OperationReplayer {
+    // @if CK_DEBUG_ENGINE // 	return new OperationReplayer( this, '-------', stringifiedOperations );
     // @if CK_DEBUG_ENGINE // }
     /**
      * Inserts content at the position in the editor specified by the selection, as one would expect the paste
      * functionality to work.
      *
-     * **Note**: If you want to insert an {@glink framework/guides/deep-dive/schema#object-elements object element}
+     * **Note**: If you want to insert an {@glink framework/deep-dive/schema#object-elements object element}
      * (e.g. a {@link module:widget/utils~toWidget widget}), see {@link #insertObject} instead.
      *
      * This is a high-level method. It takes the {@link #schema schema} into consideration when inserting
@@ -235,8 +244,8 @@ export default class Model extends ObservableMixin() {
      * Inserting elements and text nodes into the model is not enough to make CKEditor 5 render that content
      * to the user. CKEditor 5 implements a model-view-controller architecture and what `model.insertContent()` does
      * is only adding nodes to the model. Additionally, you need to define
-     * {@glink framework/guides/architecture/editing-engine#conversion converters} between the model and view
-     * and define those nodes in the {@glink framework/guides/architecture/editing-engine#schema schema}.
+     * {@glink framework/architecture/editing-engine#conversion converters} between the model and view
+     * and define those nodes in the {@glink framework/architecture/editing-engine#schema schema}.
      *
      * So, while this method may seem similar to CKEditor 4 `editor.insertHtml()` (in fact, both methods
      * are used for paste-like content insertion), the CKEditor 5 method cannot be use to insert arbitrary HTML
@@ -354,11 +363,13 @@ export default class Model extends ObservableMixin() {
      * This param defines a position in relation to that item.
      * at the insertion position.
      */
-    insertContent(content, selectable, placeOrOffset) {
-        return insertContent(this, content, selectable, placeOrOffset);
+    insertContent(content, selectable, placeOrOffset, ...rest) {
+        const selection = normalizeSelectable(selectable, placeOrOffset);
+        // Passing all call arguments so it acts like decorated method.
+        return this.fire('insertContent', [content, selection, placeOrOffset, ...rest]);
     }
     /**
-     * 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.
      *
      * This is a high-level API:
      * * It takes the {@link #schema schema} into consideration,
@@ -377,8 +388,8 @@ export default class Model extends ObservableMixin() {
      * * Inserting object into the model is not enough to make CKEditor 5 render that content to the user.
      * CKEditor 5 implements a model-view-controller architecture and what `model.insertObject()` does
      * is only adding nodes to the model. Additionally, you need to define
-     * {@glink framework/guides/architecture/editing-engine#conversion converters} between the model and view
-     * and define those nodes in the {@glink framework/guides/architecture/editing-engine#schema schema}.
+     * {@glink framework/architecture/editing-engine#conversion converters} between the model and view
+     * and define those nodes in the {@glink framework/architecture/editing-engine#schema schema}.
      *
      * # Examples
      *
@@ -421,7 +432,7 @@ export default class Model extends ObservableMixin() {
      * model.insertObject( tableElement, range );
      * ```
      *
-     * @param object An object to be inserted into the model document.
+     * @param element 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`.
@@ -440,8 +451,11 @@ export default class Model extends ObservableMixin() {
      * such text node, a paragraph will be created and the document selection will be moved inside it.
      * at the insertion position.
      */
-    insertObject(object, selectable, placeOrOffset, options) {
-        return insertObject(this, object, selectable, placeOrOffset, options);
+    insertObject(element, selectable, placeOrOffset, options, ...rest) {
+        const selection = normalizeSelectable(selectable, placeOrOffset);
+        // Note that options are fired as 2 arguments for backward compatibility with the decorated method.
+        // Passing all call arguments so it acts like decorated method.
+        return this.fire('insertObject', [element, selection, options, options, ...rest]);
     }
     /**
      * Deletes content of the selection and merge siblings. The resulting selection is always collapsed.
@@ -829,3 +843,18 @@ export default class Model extends ObservableMixin() {
         return ret;
     }
 }
+/**
+ * Normalizes a selectable to a Selection or DocumentSelection.
+ */
+function normalizeSelectable(selectable, placeOrOffset) {
+    if (!selectable) {
+        return;
+    }
+    if (selectable instanceof ModelSelection || selectable instanceof DocumentSelection) {
+        return selectable;
+    }
+    if (selectable instanceof Node) {
+        return new ModelSelection(selectable, placeOrOffset);
+    }
+    return new ModelSelection(selectable);
+}

package/src/model/node.d.ts

@@ -0,0 +1,256 @@
+/**
+ * @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/node
+ */
+import TypeCheckable from './typecheckable';
+import type Document from './document';
+import type DocumentFragment from './documentfragment';
+import type Element from './element';
+import '@ckeditor/ckeditor5-utils/src/version';
+/**
+ * Model node. Most basic structure of model tree.
+ *
+ * This is an abstract class that is a base for other classes representing different nodes in model.
+ *
+ * **Note:** If a node is detached from the model tree, you can manipulate it using it's API.
+ * However, it is **very important** that nodes already attached to model tree should be only changed through
+ * {@link module:engine/model/writer~Writer Writer API}.
+ *
+ * Changes done by `Node` methods, like {@link module:engine/model/element~Element#_insertChild _insertChild} or
+ * {@link module:engine/model/node~Node#_setAttribute _setAttribute}
+ * do not generate {@link module:engine/model/operation/operation~Operation operations}
+ * which are essential for correct editor work if you modify nodes in {@link module:engine/model/document~Document document} root.
+ *
+ * The flow of working on `Node` (and classes that inherits from it) is as such:
+ * 1. You can create a `Node` instance, modify it using it's API.
+ * 2. Add `Node` to the model using `Batch` API.
+ * 3. Change `Node` that was already added to the model using `Batch` API.
+ *
+ * Similarly, you cannot use `Batch` API on a node that has not been added to the model tree, with the exception
+ * of {@link module:engine/model/writer~Writer#insert inserting} that node to the model tree.
+ *
+ * Be aware that using {@link module:engine/model/writer~Writer#remove remove from Batch API} does not allow to use `Node` API because
+ * the information about `Node` is still kept in model document.
+ *
+ * In case of {@link module:engine/model/element~Element element node}, adding and removing children also counts as changing a node and
+ * follows same rules.
+ */
+export default abstract class Node extends TypeCheckable {
+    /**
+     * Parent of this node. It could be {@link module:engine/model/element~Element}
+     * or {@link module:engine/model/documentfragment~DocumentFragment}.
+     * Equals to `null` if the node has no parent.
+     */
+    readonly parent: Element | DocumentFragment | null;
+    /**
+     * Unique root name used to identify this root element by {@link module:engine/model/document~Document}.
+     */
+    readonly rootName: string | undefined;
+    /**
+     * Attributes set on this node.
+     */
+    private _attrs;
+    /**
+     * Creates a model node.
+     *
+     * This is an abstract class, so this constructor should not be used directly.
+     *
+     * @param attrs Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
+     */
+    constructor(attrs?: NodeAttributes);
+    /**
+     * {@link module:engine/model/document~Document Document} that owns this root element.
+     */
+    get document(): Document | null;
+    /**
+     * Index of this node in it's parent or `null` if the node has no parent.
+     *
+     * Accessing this property throws an error if this node's parent element does not contain it.
+     * This means that model tree got broken.
+     */
+    get index(): number | null;
+    /**
+     * Offset at which this node starts in it's parent. It is equal to the sum of {@link #offsetSize offsetSize}
+     * of all it's previous siblings. Equals to `null` if node has no parent.
+     *
+     * Accessing this property throws an error if this node's parent element does not contain it.
+     * This means that model tree got broken.
+     */
+    get startOffset(): number | null;
+    /**
+     * Offset size of this node. Represents how much "offset space" is occupied by the node in it's parent.
+     * It is important for {@link module:engine/model/position~Position position}. When node has `offsetSize` greater than `1`, position
+     * can be placed between that node start and end. `offsetSize` greater than `1` is for nodes that represents more
+     * than one entity, i.e. {@link module:engine/model/text~Text text node}.
+     */
+    get offsetSize(): number;
+    /**
+     * Offset at which this node ends in it's parent. It is equal to the sum of this node's
+     * {@link module:engine/model/node~Node#startOffset start offset} and {@link #offsetSize offset size}.
+     * Equals to `null` if the node has no parent.
+     */
+    get endOffset(): number | null;
+    /**
+     * Node's next sibling or `null` if the node is a last child of it's parent or if the node has no parent.
+     */
+    get nextSibling(): Node | null;
+    /**
+     * Node's previous sibling or `null` if the node is a first child of it's parent or if the node has no parent.
+     */
+    get previousSibling(): Node | null;
+    /**
+     * The top-most ancestor of the node. If node has no parent it is the root itself. If the node is a part
+     * of {@link module:engine/model/documentfragment~DocumentFragment}, it's `root` is equal to that `DocumentFragment`.
+     */
+    get root(): Node | DocumentFragment;
+    /**
+     * Returns true if the node is in a tree rooted in the document (is a descendant of one of its roots).
+     */
+    isAttached(): boolean;
+    /**
+     * Gets path to the node. The path is an array containing starting offsets of consecutive ancestors of this node,
+     * beginning from {@link module:engine/model/node~Node#root root}, down to this node's starting offset. The path can be used to
+     * create {@link module:engine/model/position~Position Position} instance.
+     *
+     * ```ts
+     * const abc = new Text( 'abc' );
+     * const foo = new Text( 'foo' );
+     * const h1 = new Element( 'h1', null, new Text( 'header' ) );
+     * const p = new Element( 'p', null, [ abc, foo ] );
+     * const div = new Element( 'div', null, [ h1, p ] );
+     * foo.getPath(); // Returns [ 1, 3 ]. `foo` is in `p` which is in `div`. `p` starts at offset 1, while `foo` at 3.
+     * h1.getPath(); // Returns [ 0 ].
+     * div.getPath(); // Returns [].
+     * ```
+     */
+    getPath(): Array<number>;
+    /**
+     * Returns ancestors array of this node.
+     *
+     * @param options Options object.
+     * @param options.includeSelf When set to `true` this node will be also included in parent's array.
+     * @param options.parentFirst When set to `true`, array will be sorted from node's parent to root element,
+     * otherwise root element will be the first item in the array.
+     * @returns Array with ancestors.
+     */
+    getAncestors(options?: {
+        includeSelf?: boolean;
+        parentFirst?: boolean;
+    }): Array<Node | DocumentFragment>;
+    /**
+     * Returns a {@link module:engine/model/element~Element} or {@link module:engine/model/documentfragment~DocumentFragment}
+     * which is a common ancestor of both nodes.
+     *
+     * @param node The second node.
+     * @param options Options object.
+     * @param options.includeSelf When set to `true` both nodes will be considered "ancestors" too.
+     * Which means that if e.g. node A is inside B, then their common ancestor will be B.
+     */
+    getCommonAncestor(node: Node, options?: {
+        includeSelf?: boolean;
+    }): Element | DocumentFragment | null;
+    /**
+     * Returns whether this node is before given node. `false` is returned if nodes are in different trees (for example,
+     * in different {@link module:engine/model/documentfragment~DocumentFragment}s).
+     *
+     * @param node Node to compare with.
+     */
+    isBefore(node: Node): boolean;
+    /**
+     * Returns whether this node is after given node. `false` is returned if nodes are in different trees (for example,
+     * in different {@link module:engine/model/documentfragment~DocumentFragment}s).
+     *
+     * @param node Node to compare with.
+     */
+    isAfter(node: Node): boolean;
+    /**
+     * Checks if the node has an attribute with given key.
+     *
+     * @param key Key of attribute to check.
+     * @returns `true` if attribute with given key is set on node, `false` otherwise.
+     */
+    hasAttribute(key: string): boolean;
+    /**
+     * Gets an attribute value for given key or `undefined` if that attribute is not set on node.
+     *
+     * @param key Key of attribute to look for.
+     * @returns Attribute value or `undefined`.
+     */
+    getAttribute(key: string): unknown;
+    /**
+     * Returns iterator that iterates over this node's attributes.
+     *
+     * Attributes are returned as arrays containing two items. First one is attribute key and second is attribute value.
+     * This format is accepted by native `Map` object and also can be passed in `Node` constructor.
+     */
+    getAttributes(): IterableIterator<[string, unknown]>;
+    /**
+     * Returns iterator that iterates over this node's attribute keys.
+     */
+    getAttributeKeys(): IterableIterator<string>;
+    /**
+     * Converts `Node` to plain object and returns it.
+     *
+     * @returns `Node` converted to plain object.
+     */
+    toJSON(): unknown;
+    /**
+     * Creates a copy of this node, that is a node with exactly same attributes, and returns it.
+     *
+     * @internal
+     * @returns Node with same attributes as this node.
+     */
+    _clone(_deep?: boolean): Node;
+    /**
+     * Removes this node from it's parent.
+     *
+     * @internal
+     * @see module:engine/model/writer~Writer#remove
+     */
+    _remove(): void;
+    /**
+     * Sets attribute on the node. If attribute with the same key already is set, it's value is overwritten.
+     *
+     * @see module:engine/model/writer~Writer#setAttribute
+     * @internal
+     * @param key Key of attribute to set.
+     * @param value Attribute value.
+     */
+    _setAttribute(key: string, value: unknown): void;
+    /**
+     * Removes all attributes from the node and sets given attributes.
+     *
+     * @see module:engine/model/writer~Writer#setAttributes
+     * @internal
+     * @param attrs Attributes to set. See {@link module:utils/tomap~toMap} for a list of accepted values.
+     */
+    _setAttributesTo(attrs: NodeAttributes): void;
+    /**
+     * Removes an attribute with given key from the node.
+     *
+     * @see module:engine/model/writer~Writer#removeAttribute
+     * @internal
+     * @param key Key of attribute to remove.
+     * @returns `true` if the attribute was set on the element, `false` otherwise.
+     */
+    _removeAttribute(key: string): boolean;
+    /**
+     * Removes all attributes from the node.
+     *
+     * @see module:engine/model/writer~Writer#clearAttributes
+     * @internal
+     */
+    _clearAttributes(): void;
+}
+/**
+ * The node's parent does not contain this node.
+ *
+ * @error model-node-not-found-in-parent
+ */
+/**
+ * Node's attributes. See {@link module:utils/tomap~toMap} for a list of accepted values.
+ */
+export type NodeAttributes = Record<string, unknown> | Iterable<[string, unknown]>;

package/src/model/nodelist.d.ts

@@ -0,0 +1,91 @@
+/**
+ * @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/nodelist
+ */
+import Node from './node';
+/**
+ * Provides an interface to operate on a list of {@link module:engine/model/node~Node nodes}. `NodeList` is used internally
+ * in classes like {@link module:engine/model/element~Element Element}
+ * or {@link module:engine/model/documentfragment~DocumentFragment DocumentFragment}.
+ */
+export default class NodeList implements Iterable<Node> {
+    /**
+     * Nodes contained in this node list.
+     */
+    private _nodes;
+    /**
+     * Creates an empty node list.
+     *
+     * @internal
+     * @param nodes Nodes contained in this node list.
+     */
+    constructor(nodes?: Iterable<Node>);
+    /**
+     * Iterable interface.
+     *
+     * Iterates over all nodes contained inside this node list.
+     */
+    [Symbol.iterator](): IterableIterator<Node>;
+    /**
+     * Number of nodes contained inside this node list.
+     */
+    get length(): number;
+    /**
+     * Sum of {@link module:engine/model/node~Node#offsetSize offset sizes} of all nodes contained inside this node list.
+     */
+    get maxOffset(): number;
+    /**
+     * Gets the node at the given index. Returns `null` if incorrect index was passed.
+     */
+    getNode(index: number): Node | null;
+    /**
+     * Returns an index of the given node. Returns `null` if given node is not inside this node list.
+     */
+    getNodeIndex(node: Node): number | null;
+    /**
+     * Returns the starting offset of given node. Starting offset is equal to the sum of
+     * {@link module:engine/model/node~Node#offsetSize offset sizes} of all nodes that are before this node in this node list.
+     */
+    getNodeStartOffset(node: Node): number | null;
+    /**
+     * Converts index to offset in node list.
+     *
+     * Returns starting offset of a node that is at given index. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
+     * `model-nodelist-index-out-of-bounds` if given index is less than `0` or more than {@link #length}.
+     */
+    indexToOffset(index: number): number;
+    /**
+     * Converts offset in node list to index.
+     *
+     * Returns index of a node that occupies given offset. Throws {@link module:utils/ckeditorerror~CKEditorError CKEditorError}
+     * `model-nodelist-offset-out-of-bounds` if given offset is less than `0` or more than {@link #maxOffset}.
+     */
+    offsetToIndex(offset: number): number;
+    /**
+     * Inserts given nodes at given index.
+     *
+     * @internal
+     * @param index Index at which nodes should be inserted.
+     * @param nodes Nodes to be inserted.
+     */
+    _insertNodes(index: number, nodes: Iterable<Node>): void;
+    /**
+     * Removes one or more nodes starting at the given index.
+     *
+     * @internal
+     * @param indexStart Index of the first node to remove.
+     * @param howMany Number of nodes to remove.
+     * @returns Array containing removed nodes.
+     */
+    _removeNodes(indexStart: number, howMany?: number): Array<Node>;
+    /**
+     * Converts `NodeList` instance to an array containing nodes that were inserted in the node list. Nodes
+     * are also converted to their plain object representation.
+     *
+     * @returns `NodeList` instance converted to `Array`.
+     */
+    toJSON(): unknown;
+}

package/src/model/operation/attributeoperation.d.ts

@@ -0,0 +1,98 @@
+/**
+ * @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/operation/attributeoperation
+ */
+import Operation from './operation';
+import Range from '../range';
+import type Document from '../document';
+/**
+ * Operation to change nodes' attribute.
+ *
+ * Using this class you can add, remove or change value of the attribute.
+ */
+export default class AttributeOperation extends Operation {
+    /**
+     * Range on which operation should be applied.
+     *
+     * @readonly
+     */
+    range: Range;
+    /**
+     * Key of an attribute to change or remove.
+     *
+     * @readonly
+     */
+    key: string;
+    /**
+     * Old value of the attribute with given key or `null`, if attribute was not set before.
+     *
+     * @readonly
+     */
+    oldValue: unknown;
+    /**
+     * New value of the attribute with given key or `null`, if operation should remove attribute.
+     *
+     * @readonly
+     */
+    newValue: unknown;
+    /**
+     * Creates an operation that changes, removes or adds attributes.
+     *
+     * If only `newValue` is set, attribute will be added on a node. Note that all nodes in operation's range must not
+     * have an attribute with the same key as the added attribute.
+     *
+     * If only `oldValue` is set, then attribute with given key will be removed. Note that all nodes in operation's range
+     * must have an attribute with that key added.
+     *
+     * If both `newValue` and `oldValue` are set, then the operation will change the attribute value. Note that all nodes in
+     * operation's ranges must already have an attribute with given key and `oldValue` as value
+     *
+     * @param range Range on which the operation should be applied. Must be a flat range.
+     * @param key Key of an attribute to change or remove.
+     * @param oldValue Old value of the attribute with given key or `null`, if attribute was not set before.
+     * @param newValue New value of the attribute with given key or `null`, if operation should remove attribute.
+     * @param baseVersion Document {@link module:engine/model/document~Document#version} on which operation
+     * can be applied or `null` if the operation operates on detached (non-document) tree.
+     */
+    constructor(range: Range, key: string, oldValue: unknown, newValue: unknown, baseVersion: number | null);
+    /**
+     * @inheritDoc
+     */
+    get type(): 'addAttribute' | 'removeAttribute' | 'changeAttribute';
+    /**
+     * Creates and returns an operation that has the same parameters as this operation.
+     */
+    clone(): AttributeOperation;
+    /**
+     * See {@link module:engine/model/operation/operation~Operation#getReversed `Operation#getReversed()`}.
+     */
+    getReversed(): Operation;
+    /**
+     * @inheritDoc
+     */
+    toJSON(): unknown;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _validate(): void;
+    /**
+     * @inheritDoc
+     * @internal
+     */
+    _execute(): void;
+    /**
+     * @inheritDoc
+     */
+    static get className(): string;
+    /**
+     * Creates `AttributeOperation` object from deserilized object, i.e. from parsed JSON string.
+     *
+     * @param json Deserialized JSON object.
+     * @param document Document on which this operation will be applied.
+     */
+    static fromJSON(json: any, document: Document): AttributeOperation;
+}