@magic-marker/prosemirror-suggest-changes 0.1.8

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Handle with Care Collective
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,425 @@
+# @handlewithcare/prosemirror-suggest-changes
+
+Check out
+[the demo](https://handlewithcarecollective.github.io/prosemirror-suggest-changes)!
+
+Development of this library is sponsored by the kind folks at
+[dskrpt.de](https://dskrpt.de/)!
+
+## Installation
+
+Install `@handlewithcare/prosemirror-suggest-changes` and its peer dependencies:
+
+npm:
+
+```sh
+npm install @handlewithcare/prosemirror-suggest-changes prosemirror-view prosemirror-transform prosemirror-state prosemirror-model
+```
+
+yarn:
+
+```sh
+yarn add @handlewithcare/prosemirror-suggest-changes prosemirror-view prosemirror-transform prosemirror-state prosemirror-model
+```
+
+<!-- toc -->
+
+- [Usage](#usage)
+- [How it works](#how-it-works)
+- [API](#api)
+  - [Schema](#schema)
+    - [`insertion`](#insertion)
+    - [`deletion`](#deletion)
+    - [`modification`](#modification)
+    - [`addSuggestionMarks`](#addsuggestionmarks)
+  - [Commands](#commands)
+    - [`selectSuggestion`](#selectsuggestion)
+    - [`revertSuggestion`](#revertsuggestion)
+    - [`revertSuggestions`](#revertsuggestions)
+    - [`revertSuggestionsInRange`](#revertsuggestionsinrange)
+    - [`applySuggestion`](#applysuggestion)
+    - [`applySuggestions`](#applysuggestions)
+    - [`applySuggestionsInRange`](#applysuggestionsinrange)
+    - [`enableSuggestChanges`](#enablesuggestchanges)
+    - [`disableSuggestChanges`](#disablesuggestchanges)
+    - [`toggleSuggestChanges`](#togglesuggestchanges)
+  - [Plugin](#plugin)
+    - [`suggestChanges`](#suggestchanges)
+    - [`suggestChangesKey`](#suggestchangeskey)
+    - [`isSuggestChangesEnabled`](#issuggestchangesenabled)
+  - [`dispatchTransaction` Decorator](#dispatchtransaction-decorator)
+    - [`withSuggestChanges`](#withsuggestchanges)
+
+<!-- tocstop -->
+
+## Usage
+
+First, add the suggestion marks to your schema:
+
+```ts
+import { addSuggestionMarks } from "@handlewithcare/prosemirror-suggest-changes";
+
+export const schema = new Schema({
+  nodes: {
+    ...nodes,
+    doc: {
+      ...nodes.doc,
+      // We need to allow these marks as block marks as well,
+      // to support block-level suggestions, like inserting a
+      // new list item
+      marks: "insertion modification deletion",
+    },
+  },
+  marks: addSuggestionMarks(marks),
+});
+```
+
+Then, add the plugin to your editor state:
+
+```ts
+import { suggestChanges } from "@handlewithcare/prosemirror-suggest-changes";
+
+const editorState = EditorState.create({
+  schema,
+  doc,
+  plugins: [
+    // ... your other plugins
+    suggestChanges(),
+  ],
+});
+```
+
+Use the `dispatchTransaction` decorator to intercept and transform transactions,
+and add suggestion decorations:
+
+```ts
+import {
+  withSuggestChanges,
+  getSuggestionDecorations,
+} from "@handlewithcare/prosemirror-suggest-changes";
+
+const editorEl = document.getElementById("editor")!;
+
+const view = new EditorView(editorEl, {
+  state: editorState,
+  decorations: getSuggestionDecorations,
+  dispatchTransaction: withSuggestChanges(),
+});
+```
+
+And finally, use the commands to control the suggest changes state, apply
+suggestions, and revert suggestions. Here’s a sample view plugin that renders a
+simple menu with some suggestion-related commands:
+
+```ts
+import {
+  toggleSuggestChanges,
+  applySuggestions,
+  revertSuggestions,
+  isSuggestChangesEnabled,
+} from "@handlewithcare/prosemirror-suggest-changes";
+
+const suggestChangesViewPlugin = new Plugin({
+  view(view) {
+    const toggleButton = document.createElement("button");
+    toggleButton.appendChild(document.createTextNode("Enable suggestions"));
+    toggleButton.addEventListener("click", () => {
+      toggleSuggestChanges(view.state, view.dispatch);
+      view.focus();
+    });
+
+    const applyAllButton = document.createElement("button");
+    applyAllButton.appendChild(document.createTextNode("Apply all"));
+    applyAllButton.addEventListener("click", () => {
+      applySuggestions(view.state, view.dispatch);
+      view.focus();
+    });
+
+    const revertAllButton = document.createElement("button");
+    revertAllButton.appendChild(document.createTextNode("Revert all"));
+    revertAllButton.addEventListener("click", () => {
+      revertSuggestions(view.state, view.dispatch);
+      view.focus();
+    });
+
+    const commandsContainer = document.createElement("div");
+    commandsContainer.append(applyAllButton, revertAllButton);
+
+    const container = document.createElement("div");
+    container.classList.add("menu");
+    container.append(toggleButton, commandsContainer);
+
+    view.dom.parentElement?.prepend(container);
+
+    return {
+      update() {
+        if (isSuggestChangesEnabled(view.state)) {
+          toggleButton.replaceChildren(
+            document.createTextNode("Disable suggestions"),
+          );
+        } else {
+          toggleButton.replaceChildren(
+            document.createTextNode("Enable suggestions"),
+          );
+        }
+      },
+      destroy() {
+        container.remove();
+      },
+    };
+  },
+});
+```
+
+## How it works
+
+This library provides three mark types:
+
+- `insertion` represents newly inserted content, including new text content and
+  new block nodes
+- `deletion` represents content that is marked as deleted, including text and
+  block nodes
+- `modification` represents nodes whose marks or attrs have changed, but whose
+  content has not changed
+
+Additionally, this library provides:
+
+- A plugin, which keeps track of whether suggestions are enabled or not
+- A decoration set factory, which renders pilcrows (¶) to make it clear to users
+  when block nodes have been deleted or inserted
+- A set of commands (`applySuggestions`, `revertSuggestions`, `applySuggestion`,
+  etc), for working with suggestions
+- A "`dispatchTransaction` decorator", `withSuggestChanges`
+
+`withSuggestChanges` is a function that optionally takes a `dispatchTransaction`
+function and returns a decorated `dispatchTransaction` function. This decorated
+function will, when suggestions are enabled, intercept transactions before they
+are applied to the state, and produce transformed transactions that suggest the
+intended changes, instead of directly applying them. For example, a transaction
+that attempts to delete the text between positions 2 and 5 in the document will
+be replaced with a transaction that adds the `deletion` mark to the text between
+positions 2 and 5.
+
+If you already have a custom `dispatchTransaction` implementation, you can pass
+it to `withSuggestChanges`. Otherwise, it will rely on the default
+implementation (`view.setState(view.state.apply(tr))`).
+
+```ts
+const view = new EditorView(editorEl, {
+  state: editorState,
+  plugins,
+  decorations: getSuggestionDecorations,
+  dispatchTransaction: withSuggestChanges(
+    /** An example dispatchTransaction that integrates with an external redux store */
+    function dispatchTransaction(this: EditorView, tr: Transaction) {
+      store.dispatch(transactionDispatched({ tr }));
+    },
+  ),
+});
+```
+
+## API
+
+### Schema
+
+#### `insertion`
+
+Represents newly inserted content, including new text content and new block
+nodes
+
+```ts
+const insertion: MarkSpec;
+```
+
+#### `deletion`
+
+Represents content that is marked as deleted, including text and block nodes
+
+```ts
+const deletion: MarkSpec;
+```
+
+#### `modification`
+
+Represents nodes whose marks or attrs have changed, but whose content has not
+changed
+
+```ts
+const modification: MarkSpec;
+```
+
+#### `addSuggestionMarks`
+
+Add the deletion, insertion, and modification marks to the provided MarkSpec
+map.
+
+```ts
+function addSuggestionMarks<Marks extends string>(
+  marks: Record<Marks, MarkSpec>,
+): Record<Marks | "deletion" | "insertion" | "modification", MarkSpec>;
+```
+
+### Commands
+
+#### `selectSuggestion`
+
+Command that updates the selection to cover an existing change.
+
+```ts
+function selectSuggestion(suggestionId: number): Command;
+```
+
+#### `revertSuggestion`
+
+Command that reverts a given tracked change in a document.
+
+This means that all content within the insertion mark will be deleted. The
+deletion mark will be removed, and their contents left in the doc. Modifications
+tracked in modification marks will be reverted.
+
+```ts
+function revertSuggestion(suggestionId: number): Command;
+```
+
+#### `revertSuggestions`
+
+Command that reverts all tracked changes in a document.
+
+This means that all content within insertion marks will be deleted. Deletion
+marks will be removed, and their contents left in the doc. Modifications tracked
+in modification marks will be reverted.
+
+```ts
+const revertSuggestions: Command;
+```
+
+#### `revertSuggestionsInRange`
+
+Command that reverts all tracked changes between two positions in the document.
+
+If `from` is not supplied, it will default to the beginning of the document. If
+`to` is not supplied, it will default to the end of the document.
+
+This means that all content within deletion marks will be deleted. Insertion
+marks and modification marks will be removed, and their contents left in the
+doc.
+
+```ts
+function revertSuggestionsInRange(from?: number, to?: number): Command;
+```
+
+#### `applySuggestion`
+
+Command that applies a given tracked change to a document.
+
+This means that all content within the deletion mark will be deleted. The
+insertion mark and modification mark will be removed, and their contents left in
+the doc.
+
+```ts
+function applySuggestion(suggestionId: number): Command;
+```
+
+#### `applySuggestions`
+
+Command that applies all tracked changes in a document.
+
+This means that all content within deletion marks will be deleted. Insertion
+marks and modification marks will be removed, and their contents left in the
+doc.
+
+```ts
+const applySuggestions: Command;
+```
+
+#### `applySuggestionsInRange`
+
+Command that applies all tracked changes between two positions in the document.
+
+If `from` is not supplied, it will default to the beginning of the document. If
+`to` is not supplied, it will default to the end of the document.
+
+This means that all content within deletion marks will be deleted. Insertion
+marks and modification marks will be removed, and their contents left in the
+doc.
+
+```ts
+function applySuggestionsInRange(from?: number, to?: number): Command;
+```
+
+#### `enableSuggestChanges`
+
+Command that enables suggest changes
+
+```ts
+const enableSuggestChanges: Command;
+```
+
+#### `disableSuggestChanges`
+
+Command that disables suggest changes
+
+```ts
+const disableSuggestChanges: Command;
+```
+
+#### `toggleSuggestChanges`
+
+Command that toggles suggest changes on or off
+
+```ts
+const toggleSuggestChanges: Command;
+```
+
+### Plugin
+
+#### `suggestChanges`
+
+A plugin that tracks whether suggest changes is enabled. It also provides
+decorations that are useful for clarifying suggestions, such as pilcrows to mark
+when paragraph breaks have been deleted or inserted.
+
+```ts
+function suggestChanges(): Plugin<{ enabled: boolean }>;
+```
+
+#### `suggestChangesKey`
+
+A plugin key for the `suggestChanges` plugin
+
+```ts
+const suggestChangesKey: PluginKey<{ enabled: boolean }>;
+```
+
+#### `isSuggestChangesEnabled`
+
+A helper function to check whether suggest changes is enabled.
+
+```ts
+function isSuggestChangesEnabled(state: EditorState): boolean;
+```
+
+### `dispatchTransaction` Decorator
+
+#### `withSuggestChanges`
+
+A `dispatchTransaction` decorator. Wrap your existing `dispatchTransaction`
+function with `withSuggestChanges`, or pass no arguments to use the default
+implementation (`view.setState(view.state.apply(tr))`).
+
+The result is a `dispatchTransaction` function that will intercept and modify
+incoming transactions when suggest changes is enabled. These modified
+transactions will suggest changes instead of directly applying them, e.g. by
+marking a range with the deletion mark rather than removing it from the
+document.
+
+```ts
+function withSuggestChanges(
+  dispatchTransaction?: EditorView["dispatch"],
+  generateId?: (schema: Schema, doc?: Node) => SuggestionId,
+): EditorView["dispatch"];
+```
+
+`generateId` can be used to customize the unique ids assigned to suggestion
+marks. If undefined, the default implementation (an auto-incrementing integer)
+will be used.

package/dist/addMarkStep.d.ts

@@ -0,0 +1,12 @@
+import { type Node } from "prosemirror-model";
+import { type EditorState, type Transaction } from "prosemirror-state";
+import { type AddMarkStep, type Step } from "prosemirror-transform";
+import { type SuggestionId } from "./generateId.js";
+/**
+ * Transform an add mark step into its equivalent tracked steps.
+ *
+ * Add mark steps are treated as replace steps in this model. An
+ * equivalent replace step will be generated, and then processed via
+ * trackReplaceStep().
+ */
+export declare function trackAddMarkStep(trackedTransaction: Transaction, state: EditorState, doc: Node, step: AddMarkStep, prevSteps: Step[], suggestionId: SuggestionId): boolean;

package/dist/addMarkStep.js

@@ -0,0 +1,17 @@
+import { replaceStep } from "prosemirror-transform";
+import { applySuggestionsToRange } from "./commands.js";
+import { suggestReplaceStep } from "./replaceStep.js";
+/**
+ * Transform an add mark step into its equivalent tracked steps.
+ *
+ * Add mark steps are treated as replace steps in this model. An
+ * equivalent replace step will be generated, and then processed via
+ * trackReplaceStep().
+ */ export function trackAddMarkStep(trackedTransaction, state, doc, step, prevSteps, suggestionId) {
+    const applied = step.apply(doc).doc;
+    if (!applied) return false;
+    const slice = applySuggestionsToRange(applied, step.from, step.to);
+    const replace = replaceStep(doc, step.from, step.to, slice);
+    if (!replace) return false;
+    return suggestReplaceStep(trackedTransaction, state, doc, replace, prevSteps, suggestionId);
+}

package/dist/addNodeMarkStep.d.ts

@@ -0,0 +1,11 @@
+import { type Node } from "prosemirror-model";
+import { type EditorState, type Transaction } from "prosemirror-state";
+import { type AddNodeMarkStep, type Step } from "prosemirror-transform";
+import { type SuggestionId } from "./generateId.js";
+/**
+ * Transform an add node mark step into its equivalent tracked steps.
+ *
+ * Add node mark steps are processed normally, and then a modification
+ * mark is added to the node as well, to track the change.
+ */
+export declare function trackAddNodeMarkStep(trackedTransaction: Transaction, state: EditorState, _doc: Node, step: AddNodeMarkStep, prevSteps: Step[], suggestionId: SuggestionId): boolean;

package/dist/addNodeMarkStep.js

@@ -0,0 +1,36 @@
+import { rebasePos } from "./rebasePos.js";
+import { getSuggestionMarks } from "./utils.js";
+/**
+ * Transform an add node mark step into its equivalent tracked steps.
+ *
+ * Add node mark steps are processed normally, and then a modification
+ * mark is added to the node as well, to track the change.
+ */ export function trackAddNodeMarkStep(trackedTransaction, state, _doc, step, prevSteps, suggestionId) {
+    const { modification } = getSuggestionMarks(state.schema);
+    const rebasedPos = rebasePos(step.pos, prevSteps, trackedTransaction.steps);
+    const $pos = trackedTransaction.doc.resolve(rebasedPos);
+    const node = $pos.nodeAfter;
+    let marks = node?.marks ?? [];
+    const existingMods = marks.filter((mark)=>mark.type === modification && mark.attrs["type"] === "mark" && step.mark.type.excludes(state.schema.markFromJSON(mark.attrs["newValue"]).type));
+    existingMods.forEach((mark)=>{
+        marks = mark.removeFromSet(marks);
+    });
+    let newMarks = step.mark.addToSet(marks);
+    let previousValue = null;
+    for (const mark of marks){
+        if (!newMarks.some((m)=>m.eq(mark))) {
+            previousValue = mark;
+            break;
+        }
+    }
+    newMarks = modification.create({
+        id: suggestionId,
+        type: "mark",
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        previousValue: previousValue?.toJSON(),
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        newValue: step.mark.toJSON()
+    }).addToSet(newMarks);
+    trackedTransaction.setNodeMarkup(rebasedPos, null, null, newMarks);
+    return true;
+}

package/dist/attrStep.d.ts

@@ -0,0 +1,11 @@
+import { type Node } from "prosemirror-model";
+import { type EditorState, type Transaction } from "prosemirror-state";
+import { type AttrStep, type Step } from "prosemirror-transform";
+import { type SuggestionId } from "./generateId.js";
+/**
+ * Transform an attr mark step into its equivalent tracked steps.
+ *
+ * Attr steps are processed normally, and then a modification
+ * mark is added to the node as well, to track the change.
+ */
+export declare function trackAttrStep(trackedTransaction: Transaction, state: EditorState, _doc: Node, step: AttrStep, prevSteps: Step[], suggestionId: SuggestionId): boolean;

package/dist/attrStep.js

@@ -0,0 +1,33 @@
+import { rebasePos } from "./rebasePos.js";
+import { getSuggestionMarks } from "./utils.js";
+/**
+ * Transform an attr mark step into its equivalent tracked steps.
+ *
+ * Attr steps are processed normally, and then a modification
+ * mark is added to the node as well, to track the change.
+ */ export function trackAttrStep(trackedTransaction, state, _doc, step, prevSteps, suggestionId) {
+    const { modification } = getSuggestionMarks(state.schema);
+    const rebasedPos = rebasePos(step.pos, prevSteps, trackedTransaction.steps);
+    const $pos = trackedTransaction.doc.resolve(rebasedPos);
+    const node = $pos.nodeAfter;
+    let marks = node?.marks ?? [];
+    const existingMod = marks.find((mark)=>mark.type === modification && mark.attrs["type"] === "attr" && mark.attrs["attrName"] === step.attr);
+    if (existingMod) {
+        marks = existingMod.removeFromSet(marks);
+    }
+    marks = modification.create({
+        id: suggestionId,
+        type: "attr",
+        attrName: step.attr,
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        previousValue: node?.attrs[step.attr],
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        newValue: step.value
+    }).addToSet(marks);
+    trackedTransaction.setNodeMarkup(rebasedPos, null, // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    {
+        ...node?.attrs,
+        [step.attr]: step.value
+    }, marks);
+    return true;
+}

package/dist/commands.d.ts

@@ -0,0 +1,64 @@
+import { type Node } from "prosemirror-model";
+import { type Command, type EditorState } from "prosemirror-state";
+import { type EditorView } from "prosemirror-view";
+import { type SuggestionId } from "./generateId.js";
+export declare function applySuggestionsToNode(node: Node): Node;
+export declare function applySuggestionsToRange(doc: Node, from: number, to: number): import("prosemirror-model").Slice;
+/**
+ * Command that applies all tracked changes in a document.
+ *
+ * This means that all content within deletion marks will be deleted.
+ * Insertion marks and modification marks will be removed, and their
+ * contents left in the doc.
+ */
+export declare function applySuggestions(state: EditorState, dispatch?: EditorView["dispatch"]): boolean;
+/**
+ * Command that applies all tracked changes in specified range.
+ *
+ * This means that all content within deletion marks will be deleted.
+ * Insertion marks and modification marks will be removed, and their
+ * contents left in the doc.
+ */
+export declare function applySuggestionsInRange(from?: number, to?: number): Command;
+/**
+ * Command that applies a given tracked change to a document.
+ *
+ * This means that all content within the deletion mark will be deleted.
+ * The insertion mark and modification mark will be removed, and their
+ * contents left in the doc.
+ */
+export declare function applySuggestion(suggestionId: SuggestionId, from?: number, to?: number): Command;
+/**
+ * Command that reverts all tracked changes in a document.
+ *
+ * This means that all content within insertion marks will be deleted.
+ * Deletion marks will be removed, and their contents left in the doc.
+ * Modifications tracked in modification marks will be reverted.
+ */
+export declare function revertSuggestions(state: EditorState, dispatch?: EditorView["dispatch"]): boolean;
+/**
+ * Command that reverts all tracked changes in specified range.
+ *
+ * This means that all content within insertion marks will be deleted.
+ * Deletion marks will be removed, and their contents left in the doc.
+ * Modifications tracked in modification marks will be reverted.
+ */
+export declare function revertSuggestionsInRange(from?: number, to?: number): Command;
+/**
+ * Command that reverts a given tracked change in a document.
+ *
+ * This means that all content within the insertion mark will be deleted.
+ * The deletion mark will be removed, and their contents left in the doc.
+ * Modifications tracked in modification marks will be reverted.
+ */
+export declare function revertSuggestion(suggestionId: SuggestionId, from?: number, to?: number): Command;
+/**
+ * Command that updates the selection to cover an existing change.
+ */
+export declare function selectSuggestion(suggestionId: SuggestionId): Command;
+/** Command that enables suggest changes */
+export declare function enableSuggestChanges(state: EditorState, dispatch?: EditorView["dispatch"]): boolean;
+/** Command that disables suggest changes */
+export declare function disableSuggestChanges(state: EditorState, dispatch?: EditorView["dispatch"]): boolean;
+/** Command that toggles suggest changes on or off */
+export declare function toggleSuggestChanges(state: EditorState, dispatch?: EditorView["dispatch"]): boolean;