@manuscripts/track-changes-plugin 1.10.1 → 1.10.2-LEAN-4382.0

package/README.md

@@ -1,6 +1,58 @@
 # [@manuscripts/track-changes-plugin](https://github.com/Atypon-OpenSource/manuscripts-quarterback/tree/main/quarterback-packages/track-changes-plugin)
 
-ProseMirror plugin to track inserts/deletes to nodes and text.
+ProseMirror plugin designed to track changes within a document, similar to the track changes functionality found in Google Docs or Microsoft Word. It allows for the tracking of insertions and deletions of nodes, text and node attributes, preserving information about past changes using dataTracked attributes on nodes.
+
+## Features
+
+1. **Tracking of Changes:** Monitors and records insertions and deletions of block nodes, inline nodes, attributes on nodes and text within the ProseMirror editor.
+2. **Changes management:** Allows to reject/accept a single change or a list of changes.
+3. **Command Set:** Provides commands to enable, disable, skip, accept, reject changes. Commands are issues as transactions meta. This is the way to communicate with the plugin.
+4. **Interpretation:** Plugin provides a ChangeSet class that helps to interpret changes in a user-friendly way.
+
+## Core Architecture Overview
+
+### Main design points
+
+- Intercept transactions (insert/delete).
+  Transactions are intercepted and reverted using default plugins lifecycle, unless transaction has meta commanding to skip tracking.
+
+- Annotate changes with metadata using node attributes and marks.
+  Before transaction is reverted the changes in each step of transaction are processed and created metadata that described the changes are stored in the dataTracked attributes. For text changes, dataTracked attributes are added to marks,
+  with which the inline change is marked on the document. For node changes the dataTracked metadata are assigned to nodes.
+
+- ChangeSet class handles changes interpretation to create a more meaningful representation:
+  - Creates a list of top level changes out of a list of nested changed.
+  - Groups adjacent inline change of to create a single change
+  - Provides utilities to process changes, such as checking the type of a change, checking validity, flattening, etc.
+- Changes acceptance/rejection in the document is executed via commands. Accepting a change means integrating the change into the document and discarding metadata about it.
+  Rejecting the change means reverting to the state of nodes or text or attributes before the change and discarding metadata about it.
+- History of edits (who, what, when) is supported only in the boundaries of dataTracked attributes metadata. The plugin doesn't provide Undo/Redo capabilities but perfectly compatible with default prosemirror-history plugin.
+
+### How it works under the hood
+
+1. Transaction intercepted and decided upon if needs to be tracked or not. Done in appendTransaction method of the plugin. Besides explicit disabling there is a number of internal cases that disables tracking
+2. Each type of prosemirror change step type is processed by differently. **trackTransaction** function invokes a function for each of those, such as trackReplaceStep or trackReplaceAroundStep.
+   While all of these step processing functions are a bit different, all of them result in returning an array of **ChangeStep**
+3. **ChangeSteps** have high descriptive value and represent a specific change. This process is required because prosemirror steps are designed to efficiently capture a change in the document structure but are hard to reason about because they don't really correspond to meaningful user actions directly. There also cases when something, what we consider to be a single step of change, is represented by multiple changes. See ChangeStep type for details.
+4. ChangeSteps are then processed by diffChangeSteps function. The function attempts to match inserted content with previously deleted content, so it can detect and consolidate edits rather than treat all changes as new inserts.
+5. Finally, changes produced from ChangeSteps are recreated on the prosemirror document along with appropriate metadata (see **processChangeSteps** function) and a new transaction is issued to apply them. Note that some metadata are created in steps processing function.
+6. Due to the fact that we revert changes from original transaction and then apply new changes with both old state and new state of affected node/text, the current selection on the document may be misplaced. Because of that, in some cases, we repair the selection to match its position as expected by the user.
+
+### Basic DataTracked Attributes Model
+
+Nodes that change are extended with dataTracked attributes:
+
+```ts
+{ "dataTracked": [ { "id": "uuid", "user": "anonymous", "timestamp": 123456789, "operation": "insert" | "delete" | "set_attrs" | "wrap_with_node" ... } ] }
+```
+
+## Requirements
+
+Node schema needs to have { dataTracked: null } attribute declared. Otherwise the node will not be tracked.
+
+## Best practices and caveats
+
+Storing metadata about changes directly in the document as an attributes provides a lot of advantages (simple data model is one of them) but also has a caveat of treating metadata as data. Unless treated with care, complex changes may result in a loss of metadata during processing. Prosemirror doesn't do deepCloning of attributes between states so it would be a good practice to treat attributes with care and avoiding mutation of attributes to avoid weird behaviour.
 
 ## How to use
 

package/dist/cjs/plugin.js

@@ -21,6 +21,7 @@ const ChangeSet_1 = require("./ChangeSet");
 const trackTransaction_1 = require("./steps/trackTransaction");
 const track_1 = require("./types/track");
 const logger_1 = require("./utils/logger");
+const track_utils_1 = require("./utils/track-utils");
 exports.trackChangesPluginKey = new prosemirror_state_1.PluginKey('track-changes');
 const trackChangesPlugin = (opts = { userID: 'anonymous:Anonymous', initialStatus: track_1.TrackChangesStatus.enabled }) => {
     const { userID, debug, skipTrsWithMetas = [] } = opts;
@@ -60,9 +61,7 @@ const trackChangesPlugin = (opts = { userID: 'anonymous:Anonymous', initialStatu
                     return Object.assign(Object.assign({}, pluginState), { changeSet: new ChangeSet_1.ChangeSet() });
                 }
                 let { changeSet } = pluginState, rest = __rest(pluginState, ["changeSet"]);
-                if ((0, actions_1.getAction)(tr, actions_1.TrackChangesAction.refreshChanges) ||
-                    tr.getMeta('history$') ||
-                    tr.getMeta('history$1')) {
+                if ((0, actions_1.getAction)(tr, actions_1.TrackChangesAction.refreshChanges) || (0, track_utils_1.trFromHistory)(tr)) {
                     changeSet = (0, findChanges_1.findChanges)(newState);
                 }
                 return Object.assign({ changeSet }, rest);
@@ -99,7 +98,7 @@ const trackChangesPlugin = (opts = { userID: 'anonymous:Anonymous', initialStatu
                     tr.docChanged &&
                     !skipMetaUsed &&
                     !skipTrackUsed &&
-                    !(tr.getMeta('history$') || tr.getMeta('history$1')) &&
+                    !(0, track_utils_1.trFromHistory)(tr) &&
                     !(wasAppended && tr.getMeta('origin') === 'paragraphs')) {
                     createdTr = (0, trackTransaction_1.trackTransaction)(tr, oldState, createdTr, userID);
                 }

package/dist/cjs/steps/trackReplaceStep.js

@@ -58,7 +58,8 @@ function trackReplaceStep(step, oldState, newTr, attrs, stepResult, currentStepD
         if (backSpacedText) {
             changeSteps.splice(changeSteps.indexOf(backSpacedText));
         }
-        const textWasDeleted = !!changeSteps.length;
+        const textWasDeleted = !!changeSteps.length && !(fromA === fromB);
+        console.log(textWasDeleted);
         if (!backSpacedText && newSliceContent.size > 0) {
             logger_1.log.info('newSliceContent', newSliceContent);
             let fragment = (0, setFragmentAsInserted_1.setFragmentAsInserted)(newSliceContent, trackUtils.createNewInsertAttrs(attrs), oldState.schema);

package/dist/cjs/utils/track-utils.js

@@ -11,7 +11,7 @@ var __rest = (this && this.__rest) || function (s, e) {
     return t;
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stepIsLift = exports.isLiftStep = exports.isWrapStep = exports.isSplitStep = exports.createNewUpdateAttrs = exports.createNewDeleteAttrs = exports.createNewReferenceAttrs = exports.createNewSplitAttrs = exports.createNewWrapAttrs = exports.createNewInsertAttrs = void 0;
+exports.trFromHistory = exports.stepIsLift = exports.isLiftStep = exports.isWrapStep = exports.isSplitStep = exports.createNewUpdateAttrs = exports.createNewDeleteAttrs = exports.createNewReferenceAttrs = exports.createNewSplitAttrs = exports.createNewWrapAttrs = exports.createNewInsertAttrs = void 0;
 const change_1 = require("../types/change");
 function createNewInsertAttrs(attrs) {
     return Object.assign(Object.assign({}, attrs), { operation: change_1.CHANGE_OPERATION.insert });
@@ -82,3 +82,5 @@ function stepIsLift(gap, node, to) {
     return gap.start < gap.end && gap.insert === 0 && gap.end === to && !node.isText;
 }
 exports.stepIsLift = stepIsLift;
+const trFromHistory = (tr) => Object.keys(tr.meta).find((s) => s.startsWith('history$'));
+exports.trFromHistory = trFromHistory;

package/dist/es/plugin.js

@@ -18,6 +18,7 @@ import { ChangeSet } from './ChangeSet';
 import { trackTransaction } from './steps/trackTransaction';
 import { TrackChangesStatus } from './types/track';
 import { enableDebug, log } from './utils/logger';
+import { trFromHistory } from './utils/track-utils';
 export const trackChangesPluginKey = new PluginKey('track-changes');
 export const trackChangesPlugin = (opts = { userID: 'anonymous:Anonymous', initialStatus: TrackChangesStatus.enabled }) => {
     const { userID, debug, skipTrsWithMetas = [] } = opts;
@@ -57,9 +58,7 @@ export const trackChangesPlugin = (opts = { userID: 'anonymous:Anonymous', initi
                     return Object.assign(Object.assign({}, pluginState), { changeSet: new ChangeSet() });
                 }
                 let { changeSet } = pluginState, rest = __rest(pluginState, ["changeSet"]);
-                if (getAction(tr, TrackChangesAction.refreshChanges) ||
-                    tr.getMeta('history$') ||
-                    tr.getMeta('history$1')) {
+                if (getAction(tr, TrackChangesAction.refreshChanges) || trFromHistory(tr)) {
                     changeSet = findChanges(newState);
                 }
                 return Object.assign({ changeSet }, rest);
@@ -96,7 +95,7 @@ export const trackChangesPlugin = (opts = { userID: 'anonymous:Anonymous', initi
                     tr.docChanged &&
                     !skipMetaUsed &&
                     !skipTrackUsed &&
-                    !(tr.getMeta('history$') || tr.getMeta('history$1')) &&
+                    !trFromHistory(tr) &&
                     !(wasAppended && tr.getMeta('origin') === 'paragraphs')) {
                     createdTr = trackTransaction(tr, oldState, createdTr, userID);
                 }

package/dist/es/steps/trackReplaceStep.js

@@ -32,7 +32,8 @@ export function trackReplaceStep(step, oldState, newTr, attrs, stepResult, curre
         if (backSpacedText) {
             changeSteps.splice(changeSteps.indexOf(backSpacedText));
         }
-        const textWasDeleted = !!changeSteps.length;
+        const textWasDeleted = !!changeSteps.length && !(fromA === fromB);
+        console.log(textWasDeleted);
         if (!backSpacedText && newSliceContent.size > 0) {
             log.info('newSliceContent', newSliceContent);
             let fragment = setFragmentAsInserted(newSliceContent, trackUtils.createNewInsertAttrs(attrs), oldState.schema);

package/dist/es/utils/track-utils.js

@@ -69,3 +69,4 @@ export const isLiftStep = (step) => {
 export function stepIsLift(gap, node, to) {
     return gap.start < gap.end && gap.insert === 0 && gap.end === to && !node.isText;
 }
+export const trFromHistory = (tr) => Object.keys(tr.meta).find((s) => s.startsWith('history$'));

package/dist/types/utils/track-utils.d.ts

@@ -1,5 +1,5 @@
 import { Node as PMNode, Slice } from 'prosemirror-model';
-import { Selection } from 'prosemirror-state';
+import { Selection, Transaction } from 'prosemirror-state';
 import { ReplaceAroundStep, ReplaceStep } from 'prosemirror-transform';
 import { NewDeleteAttrs, NewEmptyAttrs, NewInsertAttrs, NewReferenceAttrs, NewSplitNodeAttrs, NewUpdateAttrs } from '../types/track';
 export declare function createNewInsertAttrs(attrs: NewEmptyAttrs): NewInsertAttrs;
@@ -17,3 +17,4 @@ export declare function stepIsLift(gap: {
     slice: Slice;
     insert: number;
 }, node: PMNode, to: number): boolean;
+export declare const trFromHistory: (tr: Transaction) => string | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@manuscripts/track-changes-plugin",
-  "version": "1.10.1",
+  "version": "1.10.2-LEAN-4382.0",
   "author": "Atypon Systems LLC",
   "license": "Apache-2.0",
   "homepage": "https://github.com/Atypon-OpenSource/manuscripts-track-changes-plugin",