@manuscripts/track-changes-plugin 0.2.0 → 0.4.1

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'
@@ -34,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'
@@ -54,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
 
@@ -130,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
@@ -53,11 +54,6 @@ export declare class ChangeSet {
      * @param changes
      */
     static flattenTreeToIds(changes: TrackedChange[]): string[];
-    /**
-     * Determines whether a change should not be deleted when applying it to the document.
-     * @param change
-     */
-    static shouldNotDelete(change: TrackedChange): boolean;
     /**
      * Determines whether a change should be deleted when applying it to the document.
      * @param change
@@ -65,9 +61,10 @@ export declare class ChangeSet {
     static shouldDeleteChange(change: TrackedChange): boolean;
     /**
      * Checks whether change attributes contain all TrackedAttrs keys with non-undefined values
-     * @param attrs
+     * @param dataTracked
      */
-    static isValidTrackedAttrs(attrs?: Partial<TrackedAttrs>): boolean;
+    static isValidDataTracked(dataTracked?: 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

@@ -51,3 +51,10 @@ export declare function getAction<K extends keyof TrackChangesActionParams>(tr:
  * @param payload
  */
 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(matchedDeleted: 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/changes/applyChanges.d.ts

@@ -0,0 +1,28 @@
+/*!
+ * © 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 { Transaction } from 'prosemirror-state';
+import { Mapping } from 'prosemirror-transform';
+import { TrackedChange } from '../types/change';
+/**
+ * Applies the accepted/rejected changes in the current document and sets them untracked
+ *
+ * @param tr
+ * @param schema
+ * @param changes
+ * @param deleteMap
+ */
+export declare function applyAcceptedRejectedChanges(tr: Transaction, schema: Schema, changes: TrackedChange[], deleteMap?: Mapping): Mapping;

package/dist/changes/findChanges.d.ts

@@ -0,0 +1,27 @@
+/*!
+ * © 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 { EditorState } from 'prosemirror-state';
+import { ChangeSet } from '../ChangeSet';
+/**
+ * Finds all changes (basically text marks or node attributes) from document
+ *
+ * This could be possibly made more efficient by only iterating the sections of doc
+ * where changes have been applied. This could attempted with eg findDiffStart
+ * but it might be less robust than just using doc.descendants
+ * @param state
+ * @returns
+ */
+export declare function findChanges(state: EditorState): ChangeSet;

package/dist/changes/fixInconsistentChanges.d.ts

@@ -0,0 +1,29 @@
+/*!
+ * © 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 { Transaction } from 'prosemirror-state';
+import { ChangeSet } from '../ChangeSet';
+/**
+ * Iterates over a ChangeSet to check all changes have their required attributes
+ *
+ * This inconsistency might happen due to a bug in the track changes implementation or by a user somehow applying an empty insert/delete mark that doesn't contain proper data. Also this checks the track IDs for duplicates.
+ * @param changeSet
+ * @param currentUser
+ * @param newTr
+ * @param schema
+ * @return docWasChanged, a boolean
+ */
+export declare function fixInconsistentChanges(changeSet: ChangeSet, currentUserID: string, newTr: Transaction, schema: Schema): boolean;

package/dist/changes/updateChangeAttrs.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 { Transaction } from 'prosemirror-state';
+import { Mapping } from 'prosemirror-transform';
+import { IncompleteChange, TrackedAttrs, TrackedChange } from '../types/change';
+export declare function updateChangeAttrs(tr: Transaction, change: IncompleteChange, trackedAttrs: Partial<TrackedAttrs>, schema: Schema): Transaction;
+export declare function updateChangeChildrenAttributes(changes: TrackedChange[], tr: Transaction, mapping: Mapping): void;

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/compute/nodeHelpers.d.ts

@@ -0,0 +1,28 @@
+/*!
+ * © 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, Schema } from 'prosemirror-model';
+import { CHANGE_OPERATION, TrackedAttrs } from '../types/change';
+export declare function addTrackIdIfDoesntExist(attrs: Partial<TrackedAttrs>): Partial<TrackedAttrs>;
+export declare function getTextNodeTrackedMarkData(node: PMNode | undefined | null, schema: Schema): (Omit<Partial<TrackedAttrs>, "operation"> & {
+    operation: CHANGE_OPERATION;
+}) | undefined;
+export declare function getBlockInlineTrackedData(node: PMNode): Partial<TrackedAttrs>[] | 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): (Omit<Partial<TrackedAttrs>, "operation"> & {
+    operation: CHANGE_OPERATION;
+}) | null;

package/dist/compute/setFragmentAsInserted.d.ts

@@ -0,0 +1,18 @@
+/*!
+ * © 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 { Fragment, Schema } from 'prosemirror-model';
+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;
+};