draft-js-diff

Create side-by-side text editors with highlighted diffs, using DraftJS.

Table of content:

• Demo
• Usage
  • Using the DiffEditor
  • Using Decorators Strategies
• Shortcomings
• API Reference

Demo

Live demo here

Or you can serve the demo locally by cloning this repository and:

> npm install
> npm run start

... then visit http://127.0.0.1:9090

Usage

Adds the NPM package as dependency, then require:

var DraftDiff = require('draft-js-diff');

Using the DiffEditor

You can use the base React component shown in the demo to simply display two side-by-side editors with highlighted differences:

var DiffEditor = DraftDiff.DiffEditor;

ReactDOM.render(
    <DiffEditor before={before}
                after={after}>
    </DiffEditor>,
    document.getElementById('target')
);

Differences will be enclosed in span with classes so you can apply styling on it:

.diff-delete {
    background-color: #fee
}
.diff-equal {
    background-color: #ffe
}
.diff-insert {
    background-color: #efe
}

Be sure to include the DraftJS stylesheet too.

Creating CompositeDecorator strategies

You don't have to use the demo DiffEditor, you can just create decorators and use them for your own Draft.Editor. To do so, you need to create decorator strategies after diffing both texts. The source code of the DiffEditor is a good example of this.

Computing the diffs

var diffs = DraftDiff.diffWordMode(oldText, newText);

Creating strategies for the diffs

From an array of diff, you can create strategies for a CompositeDecorator. Strategies are different for the editor containing the old text and the editor with the new text. And they will only work if the editors contain the whole old or new text. So you need to generate strategies for both editors.

// Create strategies for the old text
var oldTextStrategies = DraftDiff.diffDecoratorStrategies(diffs, false, blockMap1);
// Create strategies for the editor containing the new text
var newTextStrategies = DraftDiff.diffDecoratorStrategies(diffs, true, blockMap2);

// 3 functions that works as strategy to decorate spans of text that were...
newTextStrategies.getEqualStrategy() // ... unchanged
newTextStrategies.getInsertStrategy() // ... inserted
newTextStrategies.getDeleteStrategy() // ... deleted

Creating decorators

Here is an example of decorator, based on the created strategies. Just set this decorator on the EditorState used to create the strategies.

When content change

When the texts changed (and the diffs too), you need to re-create strategies from the new diff. That's a limitation of using decorators, they are only aware of the blocks they decorate, and not the whole texts, so you need to create them anew to update the diffs.

Shortcomings

Can't do more than word-level diffing

We cannot make diffs at a character level because the created spans mess up with the edition (see https://github.com/facebook/draft-js/issues/414). Instead, we limit ourselves to diffs at a word level diffs. That's why we provide a word-level diffing implementation based on the diff_match_patch library, which originally works at a character level.

Diffing is costly

Everytime one of the diffed text changes, we need to compute a whole new diff (in the future, we could work on optimizing this depending on the kind of change).

Here are rough order of magnitudes for the diff_match_patch algorithm with default options.

| Characters count | Diffs count | Time (ms) | | ---------------- | --------- | --------- | | 1000 (~5 paragraph) | 40 | 1-5 | | 6000 (~30 paragraphs) | 300 | 60 |

As the texts grow, the editing becomes laggy. You might want to stop trying to re-compute the diffs as the user types, and instead delay this calculation, for example using debouncing.

API Reference

DiffEditor

/**
 * Displays two Draft.Editor decorated with diffs.
 * @prop {Number} [debounceWait=-1] Milliseconds. Delay for the
 * updating the diffs. -1 to disable debouncing.
 * @prop {Object} [before] Props for the before editor (containing the old text)
 * Same options than `after`.
 * @prop {Object} [after] Props for the after editor (containing the new text)
 * @prop {String} [after.initial=''] The initial after text
 * @prop {Boolean} [after.hidden=false] Whether to actually display an editor
 * @prop {Boolean} [after.readOnly=false] Make the after editor read only.
 * @prop {Function} [after.onChange] Callback called with the after EditorState changes.
 * @prop {Draft.EditorState} [after.state] Be sure to pass back the
 * updated state if you listen to after.onChange.
 */
DraftDiff.DiffEditor // React Component

diffWordMode

/**
 * Find the differences between two texts, at a word level
 * @param {String} oldText
 * @param {String} newText
 * @returns {Array<diff_match_patch.Diff>} Array of diff tuples
 */
DraftDiff.diffWordMode = function (oldText, newText)

diffDecoratorStrategies

/**
 * @param {Array<diff_match_patch.Diff>} diffs
 * @param {Boolean} forNewText True if the text in blockMap is the new text.
 * @param {DraftJS.BlockMap} blockMap The BlockMap of the ContentState to decorate
 * @return {Strategies} Three strategies that identify ranges of text for each type of diff.
 * Only two of them will actually be relevant (equal and insert for
 * new text, or equal and delete for old text).
 */
DraftDiff.diffDecoratorStrategies = function (diffs, forNewText, blockMap)