@ckeditor/ckeditor5-engine 37.0.0-alpha.3 → 37.0.0

package/src/model/writer.js

@@ -13,6 +13,7 @@ import MergeOperation from './operation/mergeoperation';
 import MoveOperation from './operation/moveoperation';
 import RenameOperation from './operation/renameoperation';
 import RootAttributeOperation from './operation/rootattributeoperation';
+import RootOperation from './operation/rootoperation';
 import SplitOperation from './operation/splitoperation';
 import DocumentFragment from './documentfragment';
 import DocumentSelection from './documentselection';
@@ -361,7 +362,7 @@ export default class Writer {
      * writer.move( sourceRange, image, 'after' );
      * ```
      *
-     * These parameters works the same way as {@link #createPositionAt `writer.createPositionAt()`}.
+     * These parameters work the same way as {@link #createPositionAt `writer.createPositionAt()`}.
      *
      * Note that items can be moved only within the same tree. It means that you can move items within the same root
      * (element or document fragment) or between {@link module:engine/model/document~Document#roots documents roots},
@@ -917,6 +918,78 @@ export default class Writer {
         const oldRange = marker.getRange();
         applyMarkerOperation(this, name, oldRange, null, marker.affectsData);
     }
+    /**
+     * Adds a new root to the document (or re-attaches a {@link #detachRoot detached root}).
+     *
+     * Throws an error, if trying to add a root that is already added and attached.
+     *
+     * @param rootName Name of the added root.
+     * @param elementName The element name. Defaults to `'$root'` which also has some basic schema defined
+     * (e.g. `$block` elements are allowed inside the `$root`). Make sure to define a proper schema if you use a different name.
+     * @returns The added root element.
+     */
+    addRoot(rootName, elementName = '$root') {
+        this._assertWriterUsedCorrectly();
+        const root = this.model.document.getRoot(rootName);
+        if (root && root.isAttached()) {
+            /**
+             * Root with provided name already exists and is attached.
+             *
+             * @error writer-addroot-root-exists
+             */
+            throw new CKEditorError('writer-addroot-root-exists', this);
+        }
+        const document = this.model.document;
+        const operation = new RootOperation(rootName, elementName, true, document, document.version);
+        this.batch.addOperation(operation);
+        this.model.applyOperation(operation);
+        return this.model.document.getRoot(rootName);
+    }
+    /**
+     * Detaches the root from the document.
+     *
+     * All content and markers are removed from the root upon detaching. New content and new markers cannot be added to the root, as long
+     * as it is detached.
+     *
+     * A root cannot be fully removed from the document, it can be only detached. A root is permanently removed only after you
+     * re-initialize the editor and do not specify the root in the initial data.
+     *
+     * A detached root can be re-attached using {@link #addRoot}.
+     *
+     * Throws an error if the root does not exist or the root is already detached.
+     *
+     * @param rootOrName Name of the detached root.
+     */
+    detachRoot(rootOrName) {
+        this._assertWriterUsedCorrectly();
+        const root = typeof rootOrName == 'string' ? this.model.document.getRoot(rootOrName) : rootOrName;
+        if (!root || !root.isAttached()) {
+            /**
+             * Root with provided name does not exist or is already detached.
+             *
+             * @error writer-detachroot-no-root
+             */
+            throw new CKEditorError('writer-detachroot-no-root', this);
+        }
+        // First, remove all markers from the root. It is better to do it before removing stuff for undo purposes.
+        // However, looking through all the markers may not be the best performance wise. But there's no better solution for now.
+        for (const marker of this.model.markers) {
+            if (marker.getRange().root === root) {
+                this.removeMarker(marker);
+            }
+        }
+        // Remove all attributes from the root.
+        for (const key of root.getAttributeKeys()) {
+            this.removeAttribute(key, root);
+        }
+        // Remove all contents of the root.
+        this.remove(this.createRangeIn(root));
+        // Finally, detach the root.
+        const document = this.model.document;
+        const operation = new RootOperation(root.rootName, root.name, false, document, document.version);
+        this.batch.addOperation(operation);
+        this.model.applyOperation(operation);
+    }
     setSelection(...args) {
         this._assertWriterUsedCorrectly();
         this.model.document.selection._setTo(...args);

package/src/view/matcher.d.ts

@@ -447,7 +447,7 @@ export type ClassPatterns = PropertyPatterns<never>;
  * }
  * ```
  *
- * Refer to the {@glink updating/migration-to-29##migration-to-ckeditor-5-v2910 Migration to v29.1.0} guide
+ * Refer to the {@glink updating/guides/update-to-29##update-to-ckeditor-5-v2910 Migration to v29.1.0} guide
  * and {@link module:engine/view/matcher~MatcherPattern} documentation.
  *
  * @param pattern Pattern with missing properties.
@@ -478,7 +478,7 @@ export type ClassPatterns = PropertyPatterns<never>;
  * }
  * ```
  *
- * Refer to the {@glink updating/migration-to-29##migration-to-ckeditor-5-v2910 Migration to v29.1.0} guide
+ * Refer to the {@glink updating/guides/update-to-29##update-to-ckeditor-5-v2910 Migration to v29.1.0} guide
  * and the {@link module:engine/view/matcher~MatcherPattern} documentation.
  *
  * @param pattern Pattern with missing properties.

package/src/view/matcher.js

@@ -468,7 +468,7 @@ function matchStyles(patterns, element) {
  * }
  * ```
  *
- * Refer to the {@glink updating/migration-to-29##migration-to-ckeditor-5-v2910 Migration to v29.1.0} guide
+ * Refer to the {@glink updating/guides/update-to-29##update-to-ckeditor-5-v2910 Migration to v29.1.0} guide
  * and {@link module:engine/view/matcher~MatcherPattern} documentation.
  *
  * @param pattern Pattern with missing properties.
@@ -499,7 +499,7 @@ function matchStyles(patterns, element) {
  * }
  * ```
  *
- * Refer to the {@glink updating/migration-to-29##migration-to-ckeditor-5-v2910 Migration to v29.1.0} guide
+ * Refer to the {@glink updating/guides/update-to-29##update-to-ckeditor-5-v2910 Migration to v29.1.0} guide
  * and the {@link module:engine/view/matcher~MatcherPattern} documentation.
  *
  * @param pattern Pattern with missing properties.

package/src/view/observer/arrowkeysobserver.d.ts

@@ -23,6 +23,10 @@ export default class ArrowKeysObserver extends Observer {
      * @inheritDoc
      */
     observe(): void;
+    /**
+     * @inheritDoc
+     */
+    stopObserving(): void;
 }
 /**
  * Event fired when the user presses an arrow keys.

package/src/view/observer/arrowkeysobserver.js

@@ -33,4 +33,8 @@ export default class ArrowKeysObserver extends Observer {
      * @inheritDoc
      */
     observe() { }
+    /**
+     * @inheritDoc
+     */
+    stopObserving() { }
 }

package/src/view/observer/domeventobserver.d.ts

@@ -56,6 +56,10 @@ export default abstract class DomEventObserver<EventType extends keyof HTMLEleme
      * @inheritDoc
      */
     observe(domElement: HTMLElement): void;
+    /**
+     * @inheritDoc
+     */
+    stopObserving(domElement: HTMLElement): void;
     /**
      * Calls `Document#fire()` if observer {@link #isEnabled is enabled}.
      *

package/src/view/observer/domeventobserver.js

@@ -56,6 +56,12 @@ export default class DomEventObserver extends Observer {
             }, { useCapture: this.useCapture });
         });
     }
+    /**
+     * @inheritDoc
+     */
+    stopObserving(domElement) {
+        this.stopListening(domElement);
+    }
     /**
      * Calls `Document#fire()` if observer {@link #isEnabled is enabled}.
      *

package/src/view/observer/fakeselectionobserver.d.ts

@@ -27,6 +27,10 @@ export default class FakeSelectionObserver extends Observer {
      * @inheritDoc
      */
     observe(): void;
+    /**
+     * @inheritDoc
+     */
+    stopObserving(): void;
     /**
      * @inheritDoc
      */

package/src/view/observer/fakeselectionobserver.js

@@ -45,6 +45,10 @@ export default class FakeSelectionObserver extends Observer {
             }
         }, { priority: 'lowest' });
     }
+    /**
+     * @inheritDoc
+     */
+    stopObserving() { }
     /**
      * @inheritDoc
      */

package/src/view/observer/mutationobserver.d.ts

@@ -53,6 +53,10 @@ export default class MutationObserver extends Observer {
      * @inheritDoc
      */
     observe(domElement: HTMLElement): void;
+    /**
+     * @inheritDoc
+     */
+    stopObserving(domElement: HTMLElement): void;
     /**
      * @inheritDoc
      */

package/src/view/observer/mutationobserver.js

@@ -33,7 +33,7 @@ export default class MutationObserver extends Observer {
         };
         this.domConverter = view.domConverter;
         this.renderer = view._renderer;
-        this._domElements = [];
+        this._domElements = new Set();
         this._mutationObserver = new window.MutationObserver(this._onMutations.bind(this));
     }
     /**
@@ -46,11 +46,25 @@ export default class MutationObserver extends Observer {
      * @inheritDoc
      */
     observe(domElement) {
-        this._domElements.push(domElement);
+        this._domElements.add(domElement);
         if (this.isEnabled) {
             this._mutationObserver.observe(domElement, this._config);
         }
     }
+    /**
+     * @inheritDoc
+     */
+    stopObserving(domElement) {
+        this._domElements.delete(domElement);
+        if (this.isEnabled) {
+            // Unfortunately, it is not possible to stop observing particular DOM element.
+            // In order to stop observing one of multiple DOM elements, we need to re-connect the mutation observer.
+            this._mutationObserver.disconnect();
+            for (const domElement of this._domElements) {
+                this._mutationObserver.observe(domElement, this._config);
+            }
+        }
+    }
     /**
      * @inheritDoc
      */

package/src/view/observer/observer.d.ts

@@ -71,11 +71,16 @@ export default abstract class Observer extends Observer_base {
      */
     checkShouldIgnoreEventFromTarget(domTarget: Node | null): boolean;
     /**
-     * Starts observing the given root element.
+     * Starts observing given DOM element.
      *
-     * @param name The name of the root element.
+     * @param domElement DOM element to observe.
+     * @param name The name of the related root element.
      */
     abstract observe(domElement: HTMLElement, name: string): void;
+    /**
+     * Stops observing given DOM element.
+     */
+    abstract stopObserving(domElement: HTMLElement): void;
 }
 /**
  * The constructor of {@link ~Observer} subclass.

package/src/view/observer/selectionobserver.d.ts

@@ -74,6 +74,10 @@ export default class SelectionObserver extends Observer {
      * @inheritDoc
      */
     observe(domElement: HTMLElement): void;
+    /**
+     * @inheritDoc
+     */
+    stopObserving(domElement: HTMLElement): void;
     /**
      * @inheritDoc
      */

package/src/view/observer/selectionobserver.js

@@ -101,6 +101,12 @@ export default class SelectionObserver extends Observer {
         });
         this._documents.add(domDocument);
     }
+    /**
+     * @inheritDoc
+     */
+    stopObserving(domElement) {
+        this.stopListening(domElement);
+    }
     /**
      * @inheritDoc
      */

package/src/view/observer/tabobserver.d.ts

@@ -24,6 +24,10 @@ export default class TabObserver extends Observer {
      * @inheritDoc
      */
     observe(): void;
+    /**
+     * @inheritDoc
+     */
+    stopObserving(): void;
 }
 /**
  * Event fired when the user presses a tab key.

package/src/view/observer/tabobserver.js

@@ -35,4 +35,8 @@ export default class TabObserver extends Observer {
      * @inheritDoc
      */
     observe() { }
+    /**
+     * @inheritDoc
+     */
+    stopObserving() { }
 }

package/src/view/placeholder.js

@@ -56,10 +56,10 @@ export function enablePlaceholder({ view, element, text, isDirectHost = true, ke
  */
 export function disablePlaceholder(view, element) {
     const doc = element.document;
+    if (!documentPlaceholders.has(doc)) {
+        return;
+    }
     view.change(writer => {
-        if (!documentPlaceholders.has(doc)) {
-            return;
-        }
         const placeholders = documentPlaceholders.get(doc);
         const config = placeholders.get(element);
         writer.removeAttribute('data-placeholder', config.hostElement);

package/src/view/renderer.d.ts

@@ -208,11 +208,11 @@ export default class Renderer extends Renderer_base {
      * @param actions Actions array which is a result of the {@link module:utils/diff~diff} function.
      * @param actualDom Actual DOM children
      * @param expectedDom Expected DOM children.
-     * @param options Options
-     * @param options.replaceText Mark text nodes replacement.
-     * @returns Actions array modified with the `replace` actions.
+     * @param comparator A comparator function that should return `true` if the given node should be reused
+     * (either by the update of a text node data or an element children list for similar elements).
+     * @returns Actions array modified with the `update` actions.
      */
-    private _findReplaceActions;
+    private _findUpdateActions;
     /**
      * Marks text nodes to be synchronized.
      *

package/src/view/renderer.js

@@ -261,11 +261,11 @@ export default class Renderer extends ObservableMixin() {
         const actualDomChildren = Array.from(this.domConverter.mapViewToDom(viewElement).childNodes);
         const expectedDomChildren = Array.from(this.domConverter.viewChildrenToDom(viewElement, { withChildren: false }));
         const diff = this._diffNodeLists(actualDomChildren, expectedDomChildren);
-        const actions = this._findReplaceActions(diff, actualDomChildren, expectedDomChildren);
-        if (actions.indexOf('replace') !== -1) {
+        const actions = this._findUpdateActions(diff, actualDomChildren, expectedDomChildren, areSimilarElements);
+        if (actions.indexOf('update') !== -1) {
             const counter = { equal: 0, insert: 0, delete: 0 };
             for (const action of actions) {
-                if (action === 'replace') {
+                if (action === 'update') {
                     const insertIndex = counter.equal + counter.insert;
                     const deleteIndex = counter.equal + counter.delete;
                     const viewChild = viewElement.getChild(insertIndex);
@@ -512,17 +512,9 @@ export default class Renderer extends ObservableMixin() {
             addInlineFiller(domElement.ownerDocument, expectedDomChildren, inlineFillerPosition.offset);
         }
         const diff = this._diffNodeLists(actualDomChildren, expectedDomChildren);
-        // The rendering is not disabled on Android in the composition mode.
-        // Composition events are not cancellable and browser will modify the DOM tree.
-        // On Android composition events are immediately applied to the model, so we don't need to skip rendering,
-        // and we should not do it because the difference between view and DOM could lead to position mapping problems.
-        // Since the composition is fragile and often breaks if the composed text node is replaced while composing
-        // we need to make sure that we update the existing text node and not replace it with another one.
-        // We don't want to change the behavior on other browsers for safety, but maybe one day cause it seems to make sense.
-        // https://github.com/ckeditor/ckeditor5/issues/12455.
-        const actions = env.isAndroid ?
-            this._findReplaceActions(diff, actualDomChildren, expectedDomChildren, { replaceText: true }) :
-            diff;
+        // We need to make sure that we update the existing text node and not replace it with another one.
+        // The composition and different "language" browser extensions are fragile to text node being completely replaced.
+        const actions = this._findUpdateActions(diff, actualDomChildren, expectedDomChildren, areTextNodes);
         let i = 0;
         const nodesToUnbind = new Set();
         // Handle deletions first.
@@ -541,7 +533,7 @@ export default class Renderer extends ObservableMixin() {
                 nodesToUnbind.add(actualDomChildren[i]);
                 remove(actualDomChildren[i]);
             }
-            else if (action === 'equal' || action === 'replace') {
+            else if (action === 'equal' || action === 'update') {
                 i++;
             }
         }
@@ -557,7 +549,7 @@ export default class Renderer extends ObservableMixin() {
                 i++;
             }
             // Update the existing text node data. Note that replace action is generated only for Android for now.
-            else if (action === 'replace') {
+            else if (action === 'update') {
                 // @if CK_DEBUG_TYPING // if ( ( window as any ).logCKETyping ) {
                 // @if CK_DEBUG_TYPING // 	console.group( '%c[Renderer]%c Update text node',
                 // @if CK_DEBUG_TYPING // 		'color: green;font-weight: bold', ''
@@ -613,11 +605,11 @@ export default class Renderer extends ObservableMixin() {
      * @param actions Actions array which is a result of the {@link module:utils/diff~diff} function.
      * @param actualDom Actual DOM children
      * @param expectedDom Expected DOM children.
-     * @param options Options
-     * @param options.replaceText Mark text nodes replacement.
-     * @returns Actions array modified with the `replace` actions.
+     * @param comparator A comparator function that should return `true` if the given node should be reused
+     * (either by the update of a text node data or an element children list for similar elements).
+     * @returns Actions array modified with the `update` actions.
      */
-    _findReplaceActions(actions, actualDom, expectedDom, options = {}) {
+    _findUpdateActions(actions, actualDom, expectedDom, comparator) {
         // If there is no both 'insert' and 'delete' actions, no need to check for replaced elements.
         if (actions.indexOf('insert') === -1 || actions.indexOf('delete') === -1) {
             return actions;
@@ -634,8 +626,8 @@ export default class Renderer extends ObservableMixin() {
                 actualSlice.push(actualDom[counter.equal + counter.delete]);
             }
             else { // equal
-                newActions = newActions.concat(diff(actualSlice, expectedSlice, options.replaceText ? areTextNodes : areSimilar)
-                    .map(x => x === 'equal' ? 'replace' : x));
+                newActions = newActions.concat(diff(actualSlice, expectedSlice, comparator)
+                    .map(action => action === 'equal' ? 'update' : action));
                 newActions.push('equal');
                 // Reset stored elements on 'equal'.
                 actualSlice = [];
@@ -643,8 +635,8 @@ export default class Renderer extends ObservableMixin() {
             }
             counter[action]++;
         }
-        return newActions.concat(diff(actualSlice, expectedSlice, options.replaceText ? areTextNodes : areSimilar)
-            .map(x => x === 'equal' ? 'replace' : x));
+        return newActions.concat(diff(actualSlice, expectedSlice, comparator)
+            .map(action => action === 'equal' ? 'update' : action));
     }
     /**
      * Marks text nodes to be synchronized.
@@ -879,7 +871,7 @@ function addInlineFiller(domDocument, domParentOrArray, offset) {
  * Whether two DOM nodes should be considered as similar.
  * Nodes are considered similar if they have the same tag name.
  */
-function areSimilar(node1, node2) {
+function areSimilarElements(node1, node2) {
     return isNode(node1) && isNode(node2) &&
         !isText(node1) && !isText(node2) &&
         !isComment(node1) && !isComment(node2) &&

package/src/view/view.js

@@ -215,6 +215,9 @@ export default class View extends ObservableMixin() {
         }
         this.domRoots.delete(name);
         this.domConverter.unbindDomElement(domRoot);
+        for (const observer of this._observers.values()) {
+            observer.stopObserving(domRoot);
+        }
     }
     /**
      * Gets DOM root element.