@manuscripts/track-changes-plugin 0.0.1 → 0.0.4

package/README.md

@@ -1,20 +1,58 @@
-# @manuscripts/track-changes-plugin
+# [@manuscripts/track-changes-plugin](https://github.com/Atypon-OpenSource/manuscripts-quarterback/tree/main/quarterback-packages/track-changes-plugin)
 
-This is a ProseMirror plugin that tracks inserts/deletes to nodes and text.
+ProseMirror plugin to track inserts/deletes to nodes and text.
 
-It uses node attributes inside `dataTracked` object to persist changes for both block and inline nodes and `tracked_insert` & `tracked_delete` marks for text. An example implementation can be found inside the `examples-packages/schema` package. In addition to `dataTracked`, `tracked_insert` and `tracked_delete` code_blocks marks were altered to include track marks: `marks: 'tracked_insert tracked_delete'`. If you have multiple versions of prosemirror packages, ensure that track-changes' dependencies `prosemirror-model` and `prosemirror-transform` are aliased/deduped to same instance. `prosemirror-state` and `prosemirror-view` are only used at type level.
+If you have multiple versions of prosemirror packages, ensure that track-changes' dependencies `prosemirror-model` and `prosemirror-transform` are aliased/deduped to same instance. `prosemirror-state` and `prosemirror-view` are only used at type level. [Example](https://github.com/Atypon-OpenSource/manuscripts-quarterback/blob/main/examples-packages/client/vite.config.js).
 
-This library replaces a previous implementation based on commits as in https://prosemirror.net/examples/track/ which proved unreliable due to non-idempotent nature of transactions when rebased as well as the inability to transition to Yjs syncing. `prosemirror-changeset` was also trialed but it had similar problems and was deemed hard to extend to include tracking formatting changes.
+[More detailed overview](https://github.com/Atypon-OpenSource/manuscripts-quarterback/blob/main/quarterback-packages/track-changes-plugin/OVERVIEW.md)
 
-On a more detailed level, this plugin checks every transaction in an `appendTransaction` hook for any modifications to the document (`tr.docChanged`). If they exist, it prevents that transaction from happening by inverting it and reapplying it with deletions and insertions wrapped in track attributes/marks. It can be bybassed by using `TrackActions.skipTrack` action or by setting `skipTrsWithMetas?: (PluginKey | string)[]` option to skip all transactions based on their meta fields, such as `ySyncPluginKey`. This prevents race conditions where appendTransactions keep firing between 2 or more plugins. `prosemirror-history` transactions are skipped by default.
+## How to use
 
-On every transaction prevented, ChangeSet is generated which contains all the changes found from the document. `tr.setMeta('origin', trackChangesPluginKey)` is applied to id the transaction. Whole document is currently being iterated which may be somewhat inefficient on larger docs. The changes are stored as a flat list yet due to the hierarchy of the changes, a `changeTree` property is generated which wraps all changes within a node change as its children. This is especially helpful when inserting/deleting nodes that require multiple children that are irrelevant to the user. Currently, they are still shown in the example UI but future enhancements will probably hide them. Granular controls are however at times needed when some of the changes can be considered separate or non-contiguous.
+First install the plugin: `npm i @manuscripts/track-changes-plugin`
 
-Yjs collaboration works without further integration with this attribute & mark based approach. However, due to missing feature-parity with Yjs documents and ProseMirror documents it currently does not behave consistently. Notably, Yjs snapshots do not show node attributes which makes using them for viewing snapshots insufficient. Yjs nodes can't also contain marks but this was circumvented by using node attributes for inline nodes too.
+Then add the plugin to ProseMirror plugins:
 
-The plugin also includes logging using `debug` library that can be toggled with either passing `debug?: boolean` option or executing `enableDebug(enabled: boolean)`.
+```ts
+import { EditorState } from 'prosemirror-state'
+import { EditorView } from 'prosemirror-view'
+import { exampleSetup } from 'prosemirror-example-setup'
+import { trackChangesPlugin } from '@manuscripts/track-changes-plugin'
+
+import { schema } from './schema'
+
+const plugins = exampleSetup({ schema }).concat(trackChangesPlugin({
+  debug: true
+}))
+const state = EditorState.create({
+  schema,
+  plugins,
+})
+const view = new EditorView(document.querySelector('#editor') as HTMLElement, {
+  state,
+})
+```
+
+where `schema` is https://github.com/Atypon-OpenSource/manuscripts-quarterback/blob/main/quarterback-packages/track-changes-plugin/test/utils/schema.ts
+
+Enable or disable the plugin with:
+
+```ts
+import { trackCommands, TrackChangesStatus } from '@manuscripts/track-changes-plugin'
 
-CKEditor and Fiduswriter served as its inspiration but everything was written from scratch. Also, this library is open-sourced under the Apache 2 license.
+// toggle
+trackCommands.setTrackingStatus())(view.state, view.dispatch, view)
+
+// enable
+trackCommands.setTrackingStatus(TrackChangesStatus.enabled))(view.state, view.dispatch, view)
+
+// disable
+trackCommands.setTrackingStatus(TrackChangesStatus.disabled))(view.state, view.dispatch, view)
+
+// sets editor's 'editable' prop to false, making it ready-only
+trackCommands.setTrackingStatus(TrackChangesStatus.viewSnapshots))(view.state, view.dispatch, view)
+```
+
+See an example app at https://github.com/Atypon-OpenSource/manuscripts-quarterback/tree/main/examples-packages/client
 
 ## API
 
@@ -133,36 +171,3 @@ export function setAction<K extends keyof TrackChangesActionParams>(
 ### Types
 
 Can be found in `./src/types` and `./src/ChangeSet.ts`
-
-## Feature summary
-
-- tracks block, inline, atom node inserts & deletes as `dataTracked` attribute objects
-- tracks text insert & delete as `tracked_insert` and `tracked_delete` marks
-- joins track marks based on `userID`, `operation` and `status`, uses the oldest `createdAt` value as timestamp
-- allows deletes of block nodes & text if operation is `inserted`
-- does not diff operations next to each other eg `(ins aasdf)(del asdf)` is not reduced to `ins a`
-- does not track block node attribute updates
-- does not track mark inserts & deletes
-- does not track ReplaceAroundSteps
-- has probably bugs regarding the edge cases around copy-pasting complicated slices
-
-## Roadmap
-
-- track block node attribute updates, they currently go undetected
-- test copy-pasting works (slices with varying open endedness)
-- test for race conditions
-- refactor unused code, add better comments
-- more thorough tests
-- track ReplaceAroundSteps
-- track formatting changes, basically handle AddMarkStep and RemoveMarkSteps
-
-## Related reading
-
-- https://ckeditor.com/docs/ckeditor5/latest/features/collaboration/track-changes/track-changes.html
-- https://ckeditor.com/blog/ckeditor-5-comparing-revision-history-with-track-changes/
-- https://github.com/fiduswriter/fiduswriter
-- https://www.ncbi.nlm.nih.gov/books/NBK159965/
-- https://teemukoivisto.github.io/prosemirror-track-changes-example/
-- https://demos.yjs.dev/prosemirror-versions/prosemirror-versions.html
-- https://slab.com/blog/announcing-delta-for-elixir/
-- https://www.inkandswitch.com/peritext/

package/dist/index.es.js

@@ -501,7 +501,9 @@ function applyAcceptedRejectedChanges(tr, schema, changes, deleteMap = new Mappi
         if (change.attrs.status === CHANGE_STATUS.pending) {
             return;
         }
-        const from = deleteMap.map(change.from), node = tr.doc.nodeAt(from), noChangeNeeded = ChangeSet.shouldNotDelete(change);
+        // Map change.from and skip those which dont need to be applied
+        // or were already deleted by an applied block delete
+        const { pos: from, deleted } = deleteMap.mapResult(change.from), node = tr.doc.nodeAt(from), noChangeNeeded = deleted || ChangeSet.shouldNotDelete(change);
         if (!node) {
             log.warn('no node found to update for change', change);
             return;
@@ -1263,16 +1265,10 @@ function trackTransaction(tr, oldState, newTr, userID) {
             // } else if (step instanceof AddMarkStep) {
             // } else if (step instanceof RemoveMarkStep) {
         }
-        // TODO: here we could check whether adjacent inserts & deletes cancel each other out.
-        // However, this should not be done by diffing and only matching node or char by char instead since
-        // it's A easier and B more intuitive to user.
-        const { meta } = tr;
-        // This is quite non-optimal in some sense but to ensure no information is lost
-        // we have to re-add all the old meta keys, such as inputType or uiEvent.
-        // This should prevent bugs incase other plugins/widgets rely upon them existing (and they
-        // are not able to process the transactions before track-changes).
-        // TODO: will this cause race-condition if a meta causes another appendTransaction to fire
-        Object.keys(meta).forEach((key) => newTr.setMeta(key, tr.getMeta(key)));
+        // The old meta keys are not copied to the new transaction since this will cause race-conditions
+        // when a single meta-field is thought to be processed. MAYBE only the generic meta keys, such as
+        // inputType or uiEvent, could be copied over but it remains to be seen if it's necessary.
+        // Object.keys(meta).forEach((key) => newTr.setMeta(key, tr.getMeta(key)))
     });
     // This is kinda hacky solution at the moment to maintain NodeSelections over transactions
     // These are required by at least cross-references that need it to activate the selector pop-up

package/dist/index.js

@@ -509,7 +509,9 @@ function applyAcceptedRejectedChanges(tr, schema, changes, deleteMap = new prose
         if (change.attrs.status === exports.CHANGE_STATUS.pending) {
             return;
         }
-        const from = deleteMap.map(change.from), node = tr.doc.nodeAt(from), noChangeNeeded = ChangeSet.shouldNotDelete(change);
+        // Map change.from and skip those which dont need to be applied
+        // or were already deleted by an applied block delete
+        const { pos: from, deleted } = deleteMap.mapResult(change.from), node = tr.doc.nodeAt(from), noChangeNeeded = deleted || ChangeSet.shouldNotDelete(change);
         if (!node) {
             log.warn('no node found to update for change', change);
             return;
@@ -1271,16 +1273,10 @@ function trackTransaction(tr, oldState, newTr, userID) {
             // } else if (step instanceof AddMarkStep) {
             // } else if (step instanceof RemoveMarkStep) {
         }
-        // TODO: here we could check whether adjacent inserts & deletes cancel each other out.
-        // However, this should not be done by diffing and only matching node or char by char instead since
-        // it's A easier and B more intuitive to user.
-        const { meta } = tr;
-        // This is quite non-optimal in some sense but to ensure no information is lost
-        // we have to re-add all the old meta keys, such as inputType or uiEvent.
-        // This should prevent bugs incase other plugins/widgets rely upon them existing (and they
-        // are not able to process the transactions before track-changes).
-        // TODO: will this cause race-condition if a meta causes another appendTransaction to fire
-        Object.keys(meta).forEach((key) => newTr.setMeta(key, tr.getMeta(key)));
+        // The old meta keys are not copied to the new transaction since this will cause race-conditions
+        // when a single meta-field is thought to be processed. MAYBE only the generic meta keys, such as
+        // inputType or uiEvent, could be copied over but it remains to be seen if it's necessary.
+        // Object.keys(meta).forEach((key) => newTr.setMeta(key, tr.getMeta(key)))
     });
     // This is kinda hacky solution at the moment to maintain NodeSelections over transactions
     // These are required by at least cross-references that need it to activate the selector pop-up

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@manuscripts/track-changes-plugin",
-  "version": "0.0.1",
+  "version": "0.0.4",
   "author": "Atypon Systems LLC",
   "license": "Apache-2.0",
-  "homepage": "https://github.com/Atypon-OpenSource/manuscripts-quarterback",
+  "homepage": "https://github.com/Atypon-OpenSource/manuscripts-quarterback/tree/main/quarterback-packages/track-changes-plugin",
   "main": "dist/index.js",
   "module": "dist/index.es.js",
   "type": "module",
@@ -49,10 +49,10 @@
     "typescript": "^4.6.4"
   },
   "peerDependencies": {
-    "prosemirror-model": "^1.16.1",
-    "prosemirror-state": "^1.3.4",
-    "prosemirror-transform": "^1.3.3",
-    "prosemirror-view": "^1.23.6"
+    "prosemirror-model": ">=1.14.0",
+    "prosemirror-state": ">=1.3.0",
+    "prosemirror-transform": ">=1.3.0",
+    "prosemirror-view": ">=1.18.0"
   },
   "dependencies": {
     "debug": "^4.3.4"