Visually compare snapshots of your documents

npm install @tiptap-pro/extension-snapshot-compare

const provider = new TiptapCollabProvider({
  // ...
})

const editor = new Editor({
  // ...
  extensions: [
    // ...
    SnapshotCompare.configure({
      provider,
    }),
  ],
})

SnapshotCompare.configure({
  mapDiffToDecorations: ({ diff, tr, editor, defaultMapDiffToDecorations }) => {
    if (diff.type === 'inline-insert') {
      // return prosemirror decoration(s) or null
      return Decoration.inline(
        diff.from,
        diff.to,
        {
          class: 'diff',
          style: {
            backgroundColor: diff.attribution.color.backgroundColor,
          },
        },
        // pass the diff as the decoration's spec, this is required for `extractAttributeChanges`
        { diff },
      )
    }

    // fallback to the default mapping
    return defaultMapDiffToDecorations({
      diff,
      tr,
      editor,
      attributes: {
        // add custom attributes to the decorations
        'data-tiptap-user-id': myUserIdMapping[diff.attribution.userId],
      },
    })
  },
})

if (editor.storage.snapshotCompare.isPreviewing) {
  // The diff view is currently active
}

editor.storage.snapshotCompare.diffs

editor.chain().compareVersions({
  fromVersion: 1,
})

const colorMapping = new Map([
  ['user-1', '#ff0000'],
  ['user-2', '#00ff00'],
  ['user-3', '#0000ff'],
])

editor.chain().compareVersions({
  fromVersion: 1,
  toVersion: 3,
  hydrateUserData: ({ userId }) => {
    return {
      color: {
        backgroundColor: colorMapping.get(userId),
      },
    }
  },
})

editor.storage.snapshotCompare.diffs[0].attribution.color.backgroundColor // '#ff0000'

editor.chain().compareVersions({
  fromVersion: 1,
  toVersion: 3,
  onCompare: (ctx) => {
    if (ctx.error) {
      // handle errors that occurred in the diffing process
      console.error(ctx.error)
      return
    }

    // filter the diffs to display only the changes made by a specific user
    const diffsToDisplay = ctx.diffSet.filter((diff) => diff.attribution.userId === 'user-1')

    editor.commands.showDiff(ctx.tr, { diffs: diffsToDisplay })
  },
})

// This will display the changes that change tracking transform recorded in the editor
editor.commands.showDiff(tr)

// This will display only the diffs made by the user with the ID 'user-1'
const diffsToDisplay = tr.toDiff().filter((diff) => diff.attribution.userId === 'user-1')

editor.commands.showDiff(tr, { diffs: diffsToDisplay })

// This will hide the diff view and restore the previous content
editor.commands.hideDiff()

import { extractAttributeChanges } from '@tiptap-pro/extension-snapshot-compare'

const Heading = BaseHeading.extend({
  addNodeView() {
    return ReactNodeViewRenderer(({ node, decorations }) => {
      const { before, after, isDiffing } = extractAttributeChanges(decorations)

      return (
        <NodeViewWrapper style={{ position: 'relative' }}>
          {isDiffing && before.level !== after.level && (
            <span
              style={{
                position: 'absolute',
                right: '100%',
                fontSize: '14px',
                color: '#999',
                backgroundColor: '#f0f0f070',
              }}
              // Display the difference in level attribute
            >
              #<s>{before.level}</s>
              {after.level}
            </span>
          )}
          <NodeViewContent as={`h${node.attrs.level ?? 1}`} />
        </NodeViewWrapper>
      )
    })
  },
})

const diffsToDisplay = diffSet.filter((diff) => diff.attribution.userId === 'user-1')

// Show the filtered diffs in the editor
editor.commands.showDiff(tr, { diffs: diffsToDisplay })

declare module '@tiptap-pro/extension-snapshot-compare' {
  interface Attribution {
    userName: string
  }
}

declare module '@tiptap/core' {
  interface Commands<ReturnType> {
    snapshotCompare: {
      /**
       * Given a change tracking transform, show the diff within the editor
       */
      showDiff: (tr: ChangeTrackingTransform, options?: { diffs?: DiffSet }) => ReturnType
      /**
       * Hide the diff and restore the previous content
       */
      hideDiff: () => ReturnType
      /**
       * Diffs two versions and renders the diff into the editor
       */
      compareVersions: <
        T extends Pick<Attribution, 'color'> & Record<string, any> = Pick<Attribution, 'color'> &
          Record<string, any>,
      >(options: {
        /**
         * The version to start the diff from
         */
        fromVersion: number
        /**
         * The version to end the diff at
         * If not provided, the latest snapshot will be used
         */
        toVersion?: number
        /**
         * Allows adding contextual data to each users changes
         */
        hydrateUserData?: (context: {
          /**
           * The type of event
           */
          type: 'added' | 'removed'
          /**
           * The userId that manipulated this content
           */
          userId: string | undefined
          /**
           * The yjs identifier of the content
           */
          id?: y.ID
        }) => T
        /**
         * If provided, allows customizing the behavior of rendering the diffs to the editor.
         * @note The default behavior would be to just display the diff immediately.
         */
        onCompare?: (
          context:
            | {
                error?: undefined
                /**
                 * The editor instance
                 */
                editor: Editor
                /**
                 * All of the changes as a transform with attribution metadata
                 */
                tr: ChangeTrackingTransform<Attribution & T>
                /**
                 * The changes represented as an array of diffs
                 */
                diffSet: DiffSet<Attribution & T>
              }
            | {
                error: Error
              },
        ) => void
        /**
         * Verbosely log the diffing process to help track down where things went wrong
         */
        enableDebugging?: boolean
      }) => ReturnType
    }
  }
}

export type SnapshotCompareOptions = {
  /**
   * The tiptap provider instance. This is required for the extension to compute the diffs, but not to display them.
   * It is also possible to pass a TiptapCollabProvider instance.
   */
  provider: TiptapCollabProvider | null
  /**
   * This allows you to control mapping of a diff into a decoration to display the content of that diff
   */
  mapDiffToDecorations?: (options: {
    /**
     * The diff to map to a decoration
     */
    diff: Diff
    /**
     * The editor instance
     */
    editor: Editor
    /**
     * The change tracking transform
     */
    tr: ChangeTrackingTransform
    /**
     * The default implementation of how to map a diff to a decoration
     */
    defaultMapDiffToDecorations: typeof defaultMapDiffToDecorations
  }) => ReturnType<typeof defaultMapDiffToDecorations>
}

export type SnapshotCompareStorageInactive = {
  /**
   * Whether the diff view is currently active
   */
  isPreviewing: false
  /**
   * The content before the diff view was applied
   */
  previousContent: null
  /**
   * The change tracking transform that was applied
   * It is currently empty because the diff view is not active
   */
  diffs: DiffSet
  /**
   * The change tracking transform that was applied
   */
  tr: null
}

export type SnapshotCompareStorageActive = {
  /**
   * Whether the diff view is currently active
   */
  isPreviewing: true
  /**
   * The content before the diff view was applied
   */
  previousContent: JSONContent
  /**
   * The change tracking transform that was applied
   */
  diffs: DiffSet
  /**
   * The change tracking transform that was applied
   */
  tr: ChangeTrackingTransform
}

export type SnapshotCompareStorage = SnapshotCompareStorageInactive | SnapshotCompareStorageActive