@ckeditor/ckeditor5-watchdog 38.2.0-alpha.0 → 39.0.0

package/README.md

@@ -4,7 +4,6 @@ CKEditor 5 watchdog feature
 [![npm version](https://badge.fury.io/js/%40ckeditor%2Fckeditor5-watchdog.svg)](https://www.npmjs.com/package/@ckeditor/ckeditor5-watchdog)
 [![Coverage Status](https://coveralls.io/repos/github/ckeditor/ckeditor5/badge.svg?branch=master)](https://coveralls.io/github/ckeditor/ckeditor5?branch=master)
 [![Build Status](https://travis-ci.com/ckeditor/ckeditor5.svg?branch=master)](https://app.travis-ci.com/github/ckeditor/ckeditor5)
-![Dependency Status](https://img.shields.io/librariesio/release/npm/@ckeditor/ckeditor5-watchdog)
 
 This package implements the watchdog feature for CKEditor 5. It keeps a CKEditor 5 rich-text editor instance running.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor5-watchdog",
-  "version": "38.2.0-alpha.0",
+  "version": "39.0.0",
   "description": "A watchdog feature for CKEditor 5 editors. It keeps a CKEditor 5 editor instance running.",
   "keywords": [
     "ckeditor",
@@ -10,9 +10,8 @@
     "ckeditor5-dll"
   ],
   "main": "src/index.js",
-  "type": "module",
   "dependencies": {
-    "lodash-es": "^4.17.15"
+    "lodash-es": "4.17.21"
   },
   "engines": {
     "node": ">=16.0.0",

package/src/augmentation.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @license Copyright (c) 2003-2023, CKSource Holding sp. z o.o. All rights reserved.
+ * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
+ */
+import type { EditorData } from './editorwatchdog';
+declare module '@ckeditor/ckeditor5-core' {
+    interface EditorConfig {
+        /**
+         * The temporary property that is used for passing data to the plugin which restores the editor state.
+         *
+         * @internal
+         */
+        _watchdogInitialData?: EditorData;
+    }
+}

package/src/augmentation.js

@@ -0,0 +1,5 @@
+/**
+ * @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
+ */
+export {};

package/src/editorwatchdog.d.ts

@@ -36,6 +36,14 @@ export default class EditorWatchdog<TEditor extends Editor = Editor> extends Wat
      * The editor source element or data.
      */
     private _elementOrData?;
+    /**
+     * Specifies whether the editor was initialized using document data (`true`) or HTML elements (`false`).
+     */
+    private _initUsingData;
+    /**
+     * The latest record of the editor editable elements. Used to restart the editor.
+     */
+    private _editables;
     /**
      * The editor configuration.
      */
@@ -109,7 +117,7 @@ export default class EditorWatchdog<TEditor extends Editor = Editor> extends Wat
      * @param config The editor configuration.
      * @param context A context for the editor.
      */
-    create(elementOrData?: HTMLElement | string | Record<string, string>, config?: EditorConfig, context?: Context): Promise<unknown>;
+    create(elementOrData?: HTMLElement | string | Record<string, string> | Record<string, HTMLElement>, config?: EditorConfig, context?: Context): Promise<unknown>;
     /**
      * Destroys the watchdog and the current editor instance. It fires the callback
      * registered in {@link #setDestructor `setDestructor()`} and uses it to destroy the editor instance.
@@ -127,9 +135,13 @@ export default class EditorWatchdog<TEditor extends Editor = Editor> extends Wat
      */
     _setExcludedProperties(props: Set<unknown>): void;
     /**
-     * Returns the editor data.
+     * Gets all data that is required to reinitialize editor instance.
      */
     private _getData;
+    /**
+     * For each attached model root, returns its HTML editable element (if available).
+     */
+    private _getEditables;
     /**
      * Traverses the error context and the current editor to find out whether these structures are connected
      * to each other via properties.
@@ -142,6 +154,23 @@ export default class EditorWatchdog<TEditor extends Editor = Editor> extends Wat
      */
     private _cloneEditorConfiguration;
 }
+export type EditorData = {
+    roots: Record<string, {
+        content: string;
+        attributes: string;
+        isLoaded: boolean;
+    }>;
+    markers: Record<string, {
+        rangeJSON: {
+            start: any;
+            end: any;
+        };
+        usingOperation: boolean;
+        affectsData: boolean;
+    }>;
+    commentThreads: string;
+    suggestions: string;
+};
 /**
  * Fired after the watchdog restarts the error in case of a crash.
  *
@@ -152,4 +181,4 @@ export type EditorWatchdogRestartEvent = {
     args: [];
     return: undefined;
 };
-export type EditorCreatorFunction<TEditor = Editor> = (elementOrData: HTMLElement | string | Record<string, string>, config: EditorConfig) => Promise<TEditor>;
+export type EditorCreatorFunction<TEditor = Editor> = (elementOrData: HTMLElement | string | Record<string, string> | Record<string, HTMLElement>, config: EditorConfig) => Promise<TEditor>;

package/src/editorwatchdog.js

@@ -22,6 +22,14 @@ export default class EditorWatchdog extends Watchdog {
          * The current editor instance.
          */
         this._editor = null;
+        /**
+         * Specifies whether the editor was initialized using document data (`true`) or HTML elements (`false`).
+         */
+        this._initUsingData = true;
+        /**
+         * The latest record of the editor editable elements. Used to restart the editor.
+         */
+        this._editables = {};
         // this._editorClass = Editor;
         this._throttledSave = throttle(this._save.bind(this), typeof watchdogConfig.saveInterval === 'number' ? watchdogConfig.saveInterval : 5000);
         // Set default creator and destructor functions:
@@ -90,14 +98,56 @@ export default class EditorWatchdog extends Watchdog {
             console.error('An error happened during the editor destroying.', err);
         })
             .then(() => {
-            if (typeof this._elementOrData === 'string') {
-                return this.create(this._data, this._config, this._config.context);
+            // Pre-process some data from the original editor config.
+            // Our goal here is to make sure that the restarted editor will be reinitialized with correct set of roots.
+            // We are not interested in any data set in config or in `.create()` first parameter. It will be replaced anyway.
+            // But we need to set them correctly to make sure that proper roots are created.
+            //
+            // Since a different set of roots will be created, `lazyRoots` and `rootsAttributes` properties must be managed too.
+            // Keys are root names, values are ''. Used when the editor was initialized by setting the first parameter to document data.
+            const existingRoots = {};
+            // Keeps lazy roots. They may be different when compared to initial config if some of the roots were loaded.
+            const lazyRoots = [];
+            // Roots attributes from the old config. Will be referred when setting new attributes.
+            const oldRootsAttributes = this._config.rootsAttributes || {};
+            // New attributes to be set. Is filled only for roots that still exist in the document.
+            const rootsAttributes = {};
+            // Traverse through the roots saved when the editor crashed and set up the discussed values.
+            for (const [rootName, rootData] of Object.entries(this._data.roots)) {
+                if (rootData.isLoaded) {
+                    existingRoots[rootName] = '';
+                    rootsAttributes[rootName] = oldRootsAttributes[rootName] || {};
+                }
+                else {
+                    lazyRoots.push(rootName);
+                }
+            }
+            const updatedConfig = {
+                ...this._config,
+                extraPlugins: this._config.extraPlugins || [],
+                lazyRoots,
+                rootsAttributes,
+                _watchdogInitialData: this._data
+            };
+            // Delete `initialData` as it is not needed. Data will be set by the watchdog based on `_watchdogInitialData`.
+            // First parameter of the editor `.create()` will be used to set up initial roots.
+            delete updatedConfig.initialData;
+            updatedConfig.extraPlugins.push(EditorWatchdogInitPlugin);
+            if (this._initUsingData) {
+                return this.create(existingRoots, updatedConfig, updatedConfig.context);
             }
             else {
-                const updatedConfig = Object.assign({}, this._config, {
-                    initialData: this._data
-                });
-                return this.create(this._elementOrData, updatedConfig, updatedConfig.context);
+                // Set correct editables to make sure that proper roots are created and linked with DOM elements.
+                // No need to set initial data, as it would be discarded anyway.
+                //
+                // If one element was initially set in `elementOrData`, then use that original element to restart the editor.
+                // This is for compatibility purposes with single-root editor types.
+                if (isElement(this._elementOrData)) {
+                    return this.create(this._elementOrData, updatedConfig, updatedConfig.context);
+                }
+                else {
+                    return this.create(this._editables, updatedConfig, updatedConfig.context);
+                }
             }
         })
             .then(() => {
@@ -116,6 +166,10 @@ export default class EditorWatchdog extends Watchdog {
             .then(() => {
             super._startErrorHandling();
             this._elementOrData = elementOrData;
+            // Use document data in the first parameter of the editor `.create()` call only if it was used like this originally.
+            // Use document data if a string or object with strings was passed.
+            this._initUsingData = typeof elementOrData == 'string' ||
+                (Object.keys(elementOrData).length > 0 && typeof Object.values(elementOrData)[0] == 'string');
             // Clone configuration because it might be shared within multiple watchdog instances. Otherwise,
             // when an error occurs in one of these editors, the watchdog will restart all of them.
             this._config = this._cloneEditorConfiguration(config) || {};
@@ -127,6 +181,9 @@ export default class EditorWatchdog extends Watchdog {
             editor.model.document.on('change:data', this._throttledSave);
             this._lastDocumentVersion = editor.model.document.version;
             this._data = this._getData();
+            if (!this._initUsingData) {
+                this._editables = this._getEditables();
+            }
             this.state = 'ready';
             this._fire('stateChange');
         });
@@ -149,8 +206,7 @@ export default class EditorWatchdog extends Watchdog {
         return Promise.resolve()
             .then(() => {
             this._stopErrorHandling();
-            // Save data if there is a remaining editor data change.
-            this._throttledSave.flush();
+            this._throttledSave.cancel();
             const editor = this._editor;
             this._editor = null;
             // Remove the `change:data` listener before destroying the editor.
@@ -168,6 +224,9 @@ export default class EditorWatchdog extends Watchdog {
         const version = this._editor.model.document.version;
         try {
             this._data = this._getData();
+            if (!this._initUsingData) {
+                this._editables = this._getEditables();
+            }
             this._lastDocumentVersion = version;
         }
         catch (err) {
@@ -182,15 +241,59 @@ export default class EditorWatchdog extends Watchdog {
         this._excludedProps = props;
     }
     /**
-     * Returns the editor data.
+     * Gets all data that is required to reinitialize editor instance.
      */
     _getData() {
-        const data = {};
-        for (const rootName of this._editor.model.document.getRootNames()) {
-            data[rootName] = this._editor.data.get({ rootName });
+        const editor = this._editor;
+        const roots = editor.model.document.roots.filter(root => root.isAttached() && root.rootName != '$graveyard');
+        const { plugins } = editor;
+        // `as any` to avoid linking from external private repo.
+        const commentsRepository = plugins.has('CommentsRepository') && plugins.get('CommentsRepository');
+        const trackChanges = plugins.has('TrackChanges') && plugins.get('TrackChanges');
+        const data = {
+            roots: {},
+            markers: {},
+            commentThreads: JSON.stringify([]),
+            suggestions: JSON.stringify([])
+        };
+        roots.forEach(root => {
+            data.roots[root.rootName] = {
+                content: JSON.stringify(Array.from(root.getChildren())),
+                attributes: JSON.stringify(Array.from(root.getAttributes())),
+                isLoaded: root._isLoaded
+            };
+        });
+        for (const marker of editor.model.markers) {
+            if (!marker._affectsData) {
+                continue;
+            }
+            data.markers[marker.name] = {
+                rangeJSON: marker.getRange().toJSON(),
+                usingOperation: marker._managedUsingOperations,
+                affectsData: marker._affectsData
+            };
+        }
+        if (commentsRepository) {
+            data.commentThreads = JSON.stringify(commentsRepository.getCommentThreads({ toJSON: true, skipNotAttached: true }));
+        }
+        if (trackChanges) {
+            data.suggestions = JSON.stringify(trackChanges.getSuggestions({ toJSON: true, skipNotAttached: true }));
         }
         return data;
     }
+    /**
+     * For each attached model root, returns its HTML editable element (if available).
+     */
+    _getEditables() {
+        const editables = {};
+        for (const rootName of this.editor.model.document.getRootNames()) {
+            const editable = this.editor.ui.getEditableElement(rootName);
+            if (editable) {
+                editables[rootName] = editable;
+            }
+        }
+        return editables;
+    }
     /**
      * Traverses the error context and the current editor to find out whether these structures are connected
      * to each other via properties.
@@ -215,3 +318,106 @@ export default class EditorWatchdog extends Watchdog {
         });
     }
 }
+/**
+ * Internal plugin that is used to stop the default editor initialization and restoring the editor state
+ * based on the `editor.config._watchdogInitialData` data.
+ */
+class EditorWatchdogInitPlugin {
+    constructor(editor) {
+        this.editor = editor;
+        this._data = editor.config.get('_watchdogInitialData');
+    }
+    /**
+     * @inheritDoc
+     */
+    init() {
+        // Stops the default editor initialization and use the saved data to restore the editor state.
+        // Some of data could not be initialize as a config properties. It is important to keep the data
+        // in the same form as it was before the restarting.
+        this.editor.data.on('init', evt => {
+            evt.stop();
+            this.editor.model.enqueueChange({ isUndoable: false }, writer => {
+                this._restoreCollaborationData();
+                this._restoreEditorData(writer);
+            });
+            this.editor.data.fire('ready');
+            // Keep priority `'high' - 1` to be sure that RTC initialization will be first.
+        }, { priority: 1000 - 1 });
+    }
+    /**
+     * Creates a model node (element or text) based on provided JSON.
+     */
+    _createNode(writer, jsonNode) {
+        if ('name' in jsonNode) {
+            // If child has name property, it is an Element.
+            const element = writer.createElement(jsonNode.name, jsonNode.attributes);
+            if (jsonNode.children) {
+                for (const child of jsonNode.children) {
+                    element._appendChild(this._createNode(writer, child));
+                }
+            }
+            return element;
+        }
+        else {
+            // Otherwise, it is a Text node.
+            return writer.createText(jsonNode.data, jsonNode.attributes);
+        }
+    }
+    /**
+     * Restores the editor by setting the document data, roots attributes and markers.
+     */
+    _restoreEditorData(writer) {
+        const editor = this.editor;
+        Object.entries(this._data.roots).forEach(([rootName, { content, attributes }]) => {
+            const parsedNodes = JSON.parse(content);
+            const parsedAttributes = JSON.parse(attributes);
+            const rootElement = editor.model.document.getRoot(rootName);
+            for (const [key, value] of parsedAttributes) {
+                writer.setAttribute(key, value, rootElement);
+            }
+            for (const child of parsedNodes) {
+                const node = this._createNode(writer, child);
+                writer.insert(node, rootElement, 'end');
+            }
+        });
+        Object.entries(this._data.markers).forEach(([markerName, markerOptions]) => {
+            const { document } = editor.model;
+            const { rangeJSON: { start, end }, ...options } = markerOptions;
+            const root = document.getRoot(start.root);
+            const startPosition = writer.createPositionFromPath(root, start.path, start.stickiness);
+            const endPosition = writer.createPositionFromPath(root, end.path, end.stickiness);
+            const range = writer.createRange(startPosition, endPosition);
+            writer.addMarker(markerName, {
+                range,
+                ...options
+            });
+        });
+    }
+    /**
+     * Restores the editor collaboration data - comment threads and suggestions.
+     */
+    _restoreCollaborationData() {
+        // `as any` to avoid linking from external private repo.
+        const parsedCommentThreads = JSON.parse(this._data.commentThreads);
+        const parsedSuggestions = JSON.parse(this._data.suggestions);
+        parsedCommentThreads.forEach(commentThreadData => {
+            const channelId = this.editor.config.get('collaboration.channelId');
+            const commentsRepository = this.editor.plugins.get('CommentsRepository');
+            if (commentsRepository.hasCommentThread(commentThreadData.threadId)) {
+                const commentThread = commentsRepository.getCommentThread(commentThreadData.threadId);
+                commentThread.remove();
+            }
+            commentsRepository.addCommentThread({ channelId, ...commentThreadData });
+        });
+        parsedSuggestions.forEach(suggestionData => {
+            const trackChangesEditing = this.editor.plugins.get('TrackChangesEditing');
+            if (trackChangesEditing.hasSuggestion(suggestionData.id)) {
+                const suggestion = trackChangesEditing.getSuggestion(suggestionData.id);
+                suggestion.attributes = suggestionData.attributes;
+            }
+            else {
+                trackChangesEditing.addSuggestionData(suggestionData);
+            }
+        });
+    }
+}

package/src/index.d.ts

@@ -8,3 +8,4 @@
 export { default as ContextWatchdog } from './contextwatchdog';
 export { default as EditorWatchdog } from './editorwatchdog';
 export { default as Watchdog } from './watchdog';
+import './augmentation';

package/src/index.js

@@ -8,3 +8,4 @@
 export { default as ContextWatchdog } from './contextwatchdog';
 export { default as EditorWatchdog } from './editorwatchdog';
 export { default as Watchdog } from './watchdog';
+import './augmentation';