@manuscripts/track-changes-plugin 0.1.1 → 0.4.0

package/README.md

@@ -2,15 +2,12 @@
 
 ProseMirror plugin to track inserts/deletes to nodes and text.
 
-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).
-
-[More detailed overview](https://github.com/Atypon-OpenSource/manuscripts-quarterback/blob/main/quarterback-packages/track-changes-plugin/OVERVIEW.md)
-
 ## How to use
 
-First install the plugin: `npm i @manuscripts/track-changes-plugin`
+Requires normal ProseMirror editor dependencies.
 
-Then add the plugin to ProseMirror plugins:
+1. Install the plugin: `npm i @manuscripts/track-changes-plugin`
+2. Add it to ProseMirror plugins:
 
 ```ts
 import { EditorState } from 'prosemirror-state'
@@ -20,9 +17,11 @@ import { trackChangesPlugin } from '@manuscripts/track-changes-plugin'
 
 import { schema } from './schema'
 
-const plugins = exampleSetup({ schema }).concat(trackChangesPlugin({
-  debug: true
-}))
+const plugins = exampleSetup({ schema }).concat(
+  trackChangesPlugin({
+    debug: true,
+  })
+)
 const state = EditorState.create({
   schema,
   plugins,
@@ -32,9 +31,9 @@ const view = new EditorView(document.querySelector('#editor') as HTMLElement, {
 })
 ```
 
-where `schema` is https://github.com/Atypon-OpenSource/manuscripts-quarterback/blob/main/quarterback-packages/track-changes-plugin/test/utils/schema.ts
+where `schema` contains `dataTracked` attributes for tracked nodes and `tracked_insert` & `tracked_delete` marks as shown here: https://github.com/Atypon-OpenSource/manuscripts-quarterback/blob/main/quarterback-packages/track-changes-plugin/test/utils/schema.ts
 
-Enable or disable the plugin with:
+3. That should start tracking all transactions. You can use the following commands to enable/disable/enter read-only mode:
 
 ```ts
 import { trackCommands, TrackChangesStatus } from '@manuscripts/track-changes-plugin'
@@ -52,7 +51,11 @@ trackCommands.setTrackingStatus(TrackChangesStatus.disabled))(view.state, view.d
 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
+See an example app at https://github.com/Atypon-OpenSource/manuscripts-quarterback/tree/main/examples-packages/client for a more complete boilerplate.
+
+**NOTE**: 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).
+
+[More detailed overview](https://github.com/Atypon-OpenSource/manuscripts-quarterback/blob/main/quarterback-packages/track-changes-plugin/OVERVIEW.md)
 
 ## API
 
@@ -128,44 +131,16 @@ export const refreshChanges = () => Command
 
 ### Actions
 
-Actions are used to access/set transaction meta fields. I don't think you ever would need to use other than `TrackChangesAction.skipTrack` but they are all exposed, nonetheless.
+Actions are used to access/set transaction meta fields internally. `skipTracking` is exposed publicly to set track-changes to skip certain transaction.
 
 ```ts
-export type TrackChangesActionParams = {
-  [TrackChangesAction.skipTrack]: boolean
-  [TrackChangesAction.setUserID]: string
-  [TrackChangesAction.setPluginStatus]: TrackChangesStatus
-  [TrackChangesAction.setChangeStatuses]: {
-    status: CHANGE_STATUS
-    ids: string[]
-  }
-  [TrackChangesAction.updateChanges]: string[]
-  [TrackChangesAction.refreshChanges]: boolean
-  [TrackChangesAction.applyAndRemoveChanges]: boolean
-}
 /**
- * Gets the value of a meta field, action payload, of a defined track-changes action.
+ * Skip tracking for a transaction, use this with caution to avoid race-conditions or just to otherwise
+ * omitting applying of track attributes or marks.
  * @param tr
- * @param action
+ * @returns
  */
-export function getAction<K extends keyof TrackChangesActionParams>(tr: Transaction, action: K) {
-  return tr.getMeta(action) as TrackChangesActionParams[K] | undefined
-}
-
-/**
- * Use this function to set meta keys to transactions that are consumed by the track-changes-plugin.
- * For example, you can skip tracking of a transaction with setAction(tr, TrackChangesAction.skipTrack, true)
- * @param tr
- * @param action
- * @param payload
- */
-export function setAction<K extends keyof TrackChangesActionParams>(
-  tr: Transaction,
-  action: K,
-  payload: TrackChangesActionParams[K]
-) {
-  return tr.setMeta(action, payload)
-}
+export const skipTracking = (tr: Transaction) => setAction(tr, TrackChangesAction.skipTrack, true)
 ```
 
 ### Types

package/dist/ChangeSet.d.ts

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { NodeChange, IncompleteChange, TextChange, TrackedAttrs, TrackedChange } from './types/change';
+import { NodeChange, IncompleteChange, TextChange, TrackedAttrs, TrackedChange, NodeAttrChange } from './types/change';
 /**
  * ChangeSet is a data structure to contain the tracked changes with some utility methods and computed
  * values to allow easier operability.
@@ -37,6 +37,7 @@ export declare class ChangeSet {
     get rejected(): TrackedChange[];
     get textChanges(): TrackedChange[];
     get nodeChanges(): TrackedChange[];
+    get nodeAttrChanges(): TrackedChange[];
     get isEmpty(): boolean;
     /**
      * Used to determine whether `fixInconsistentChanges` has to be executed to replace eg duplicate ids or
@@ -70,4 +71,5 @@ export declare class ChangeSet {
     static isValidTrackedAttrs(attrs?: Partial<TrackedAttrs>): boolean;
     static isTextChange(change: TrackedChange): change is TextChange;
     static isNodeChange(change: TrackedChange): change is NodeChange;
+    static isNodeAttrChange(change: TrackedChange): change is NodeAttrChange;
 }

package/dist/actions.d.ts

@@ -50,4 +50,11 @@ export declare function getAction<K extends keyof TrackChangesActionParams>(tr:
  * @param action
  * @param payload
  */
-export declare function setAction<K extends keyof TrackChangesActionParams>(tr: Transaction, action: K, payload: TrackChangesActionParams[K]): Transaction<any>;
+export declare function setAction<K extends keyof TrackChangesActionParams>(tr: Transaction, action: K, payload: TrackChangesActionParams[K]): Transaction;
+/**
+ * Skip tracking for a transaction, use this with caution to avoid race-conditions or just to otherwise
+ * omitting applying of track attributes or marks.
+ * @param tr
+ * @returns
+ */
+export declare const skipTracking: (tr: Transaction) => Transaction;

package/dist/change-steps/diffChangeSteps.d.ts

@@ -0,0 +1,21 @@
+/*!
+ * © 2021 Atypon Systems LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Schema } from 'prosemirror-model';
+import type { Transaction } from 'prosemirror-state';
+import { ExposedFragment } from '../types/pm';
+import { ChangeStep, InsertSliceStep } from '../types/step';
+export declare function matchInserted(inDeleted: number, deleted: ChangeStep[], inserted: ExposedFragment, newTr: Transaction, schema: Schema): [number, ChangeStep[]];
+export declare function diffChangeSteps(deleted: ChangeStep[], inserted: InsertSliceStep[], newTr: Transaction, schema: Schema): ChangeStep[];

package/dist/change-steps/processChangeSteps.d.ts

@@ -0,0 +1,21 @@
+/*!
+ * © 2021 Atypon Systems LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Schema } from 'prosemirror-model';
+import type { Transaction } from 'prosemirror-state';
+import { Mapping } from 'prosemirror-transform';
+import { ChangeStep } from '../types/step';
+import { NewEmptyAttrs } from '../types/track';
+export declare function processChangeSteps(changes: ChangeStep[], startPos: number, newTr: Transaction, emptyAttrs: NewEmptyAttrs, schema: Schema): [Mapping, number];

package/dist/commands.d.ts

@@ -13,8 +13,8 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import { Command } from 'prosemirror-state';
 import { CHANGE_STATUS } from './types/change';
-import type { Command } from './types/editor';
 import { TrackChangesStatus } from './types/track';
 /**
  * Sets track-changes plugin's status to any of: 'enabled' 'disabled' 'viewSnapshots'. Passing undefined will

package/dist/{track/node-utils.d.ts → compute/nodeHelpers.d.ts}

@@ -14,21 +14,14 @@
  * limitations under the License.
  */
 import { Node as PMNode, Schema } from 'prosemirror-model';
-import { Transaction } from 'prosemirror-state';
 import { CHANGE_OPERATION, TrackedAttrs } from '../types/change';
 export declare function addTrackIdIfDoesntExist(attrs: Partial<TrackedAttrs>): Partial<TrackedAttrs>;
-/**
- * Not in use, maybe for ReplaceAroundSteps but we'll see
- * @param pos
- * @param tr
- */
-export declare function liftNode(pos: number, tr: Transaction): Transaction<any> | undefined;
-export declare function getInlineNodeTrackedMarkData(node: PMNode | undefined | null, schema: Schema): {
+export declare function getInlineNodeTrackedMarkData(node: PMNode | undefined | null, schema: Schema): (Omit<Partial<TrackedAttrs>, "operation"> & {
     operation: CHANGE_OPERATION;
-} | undefined;
+}) | undefined;
 export declare function getNodeTrackedData(node: PMNode | undefined | null, schema: Schema): Partial<TrackedAttrs> | undefined;
 export declare function equalMarks(n1: PMNode, n2: PMNode): boolean;
 export declare function shouldMergeTrackedAttributes(left?: Partial<TrackedAttrs>, right?: Partial<TrackedAttrs>): boolean;
-export declare function getMergeableMarkTrackedAttrs(node: PMNode | undefined | null, attrs: Partial<TrackedAttrs>, schema: Schema): {
+export declare function getMergeableMarkTrackedAttrs(node: PMNode | undefined | null, attrs: Partial<TrackedAttrs>, schema: Schema): (Omit<Partial<TrackedAttrs>, "operation"> & {
     operation: CHANGE_OPERATION;
-} | null;
+}) | null;

package/dist/{track/steps → compute}/setFragmentAsInserted.d.ts

@@ -14,5 +14,5 @@
  * limitations under the License.
  */
 import { Fragment, Schema } from 'prosemirror-model';
-import { NewInsertAttrs } from '../../types/track';
+import { NewInsertAttrs } from '../types/track';
 export declare function setFragmentAsInserted(inserted: Fragment, insertAttrs: NewInsertAttrs, schema: Schema): Fragment;

package/dist/compute/splitSliceIntoMergedParts.d.ts

@@ -0,0 +1,41 @@
+/*!
+ * © 2021 Atypon Systems LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { Node as PMNode } from 'prosemirror-model';
+import { ExposedFragment, ExposedSlice } from '../types/pm';
+/**
+ * Filters merged nodes from an open insertSlice to manually merge them to prevent unwanted deletions
+ *
+ * So instead of joining the slice by its open sides, possibly deleting previous nodes, we can push the
+ * changed content manually inside the merged nodes.
+ * Eg. instead of doing `|<p>asdf</p><p>|bye</p>` automatically, we extract the merged nodes first:
+ * {
+ *  updatedSliceNodes: [<p>asdf</p>],
+ *  firstMergedNode: <p>bye</p>,
+ *  lastMergedNode: undefined,
+ * }
+ * @param insertSlice inserted slice
+ */
+export declare function splitSliceIntoMergedParts(insertSlice: ExposedSlice, mergeEqualSides?: boolean): {
+    updatedSliceNodes: PMNode[];
+    firstMergedNode: {
+        mergedNodeContent: ExposedFragment;
+        unmergedContent: ExposedFragment | undefined;
+    } | undefined;
+    lastMergedNode: {
+        mergedNodeContent: ExposedFragment;
+        unmergedContent: ExposedFragment | undefined;
+    } | undefined;
+};