@manuscripts/track-changes-plugin 0.0.4 → 0.3.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/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;