Library for efficiently diffing and patching DOM fragments.
npm install skatejs-dom-diffSkate's DOM Diff is a virtual DOM library for diffing, patching and converting between virtual and real DOM trees.
- Serialise to and from read DOM trees
- Diff virtual trees and patch real trees
- Web worker support
``sh`
npm install skatejs-dom-diff
Where options are accepted, you may provide:
- done If specified, diffing is performed in a web worker and this callback is called when it's done.
Diffs two virtual trees.
`js
/ @jsx h /
import { diff, h } from 'skatejs-dom-diff';
const source =
The
is an array that can be passed to patch() to update the source tree. Before passing the instructions to patch(), however, your source tree must be associated to real DOM nodes. This can be done by using mount() or by converting them to a tree using toDom().$3
Creates a virtual fragment. You can pass nothing to create an empty fragment:
`js
import { fragment } from 'skatejs-dom-diff';const vFrag = fragment();
`A single virtual node:
js
import { fragment } from 'skatejs-dom-diff';const vFrag = fragment(
);
`An array of virtual nodes:
js
import { fragment } from 'skatejs-dom-diff';const vFrag = fragment([
, ]);
`Or even a virtual fragment:
js
import { fragment } from 'skatejs-dom-diff';const vFrag = fragment(fragment(
));
`$3
Creates a virtual node.
js
// text or...
h('div', { className: 'my-class' }, 'text or...', h('span'));
`Or you could just use JSX:
js
/ @jsx h /
// text or...
text or...
`#### Attributes
By default,
only sets properties, but you can specify attributes you want to set by passing the special attributes prop:`js
//
`#### Aria attributes
You can pass
attributes using attributes but you can also specify the aria prop:`js
//
`#### Data attributes
Like the
prop, you can also use the data prop:`js
//
`#### Events
Events are bound using the special
prop:`js
const click = e => doSomethingWith(e);
`$3
The
function is convenience for calling diff() and patch() sequentially. As with diff(), you must ensure the source virtual tree has been associated to real nodes first.`js
/ @jsx h /
import { diff, h } from 'skatejs-dom-diff';const source =
source;
const target = target;
const dom = mount(source);
merge(source, target);
`$3
Mounts the
to the real root DOM node. It returns the root node. If the root node was not specified, it automatically creates a and returns it.`js
/ @jsx h /
import { h, mount } from 'skatejs-dom-diff';const div = mount(
some text
);
`Is the same thing as:
js
/ @jsx h /
import { h, mount } from 'skatejs-dom-diff';const div = document.createElement('div');
mount(
some text
, div);
`It's more than likely that you'll just mount it directly to the document:
js
/ @jsx h /
import { h, mount } from 'skatejs-dom-diff';mount(
some text
, document.getElementById('app'));
`$3
Takes instructiosn created using
and performs them on the associated DOM nodes that each instructions is for.`js
/ @jsx h /
import { diff, h, mount, patch } from 'skatejs-dom-diff';const source =
source tree
;
const target = target tree
;
const instructions = diff(source, target);mount(source, document.getElementById('app'));
patch(instructions);
`$3
A highly convenient function for continually rendering a given template.
js
/ @jsx h /
import { h, render } from 'skatejs-dom-diff';const root = document.getElementById('app');
const renderer = render((root) => (
{root.someProp}
));// Set the prop to render with
root.someProp = 'test 1';
// Initial render:
test 1
renderer(root);// Update the prop
root.someProp = 'test 2';
// Re-render:
test 2
renderer(root);
`$3
Returns a virtual text node:
js
import { text } from 'skatejs-dom-diff';const vText = text('my text node');
`$3
Convers a virtual tree to a real DOM tree, event listeners and all:
js
import { toDom } from 'skatejs-dom-diff';const vdom =
I will soon be real!
const dom = toDom(vdom);//
I will soon be real!
console.log(dom.outerHTML);
`$3
Converts a real DOM tree into a virtual tree. It only copies over attributes. Event listeners can't be copied because the standard DOM APIs don't provide a way to get bound listeners.
Properties currently aren't copied either, but is being worked on.
js
import { toVdom } from 'skatejs-dom-diff';const dom = document.createElement('p');
dom.textContent = 'I will soon be fake!';
const vdom = toVdom(dom);
`$3
The types of patches that can occur. Currently these are:
js
import { types } from 'skatejs-dom-diff';const {
APPEND_CHILD,
REMOVE_CHILD,
REMOVE_ATTRIBUTE,
REPLACE_CHILD,
SET_ATTRIBUTE,
SET_EVENT,
SET_PROPERTY,
TEXT_CONTENT
} = types;
`$3
You can tell the differ to do its work in a web worker simply by passing a
callback option to any of the three major entry functions (diff(), merge(), render()).####
diff(source, target, options)In the case of
, it's called once the diffing algorithm has finished in the worker and passed the instructions. The patch instructions are the only argument passed into the callback.`js
/* @jsx h /
import { h, diff } from 'skatejs-dom-diff';function done (instructions) {
patch(instructions);
}
diff(
source
, target
, { done });
`####
For
, it's passed in the same exact way. The only difference is that it's called after the patch is performed but it's still passed the instructions that were performed by the patch algorithm.`js
/* @jsx h /
import { h, merge } from 'skatejs-dom-diff';function done (instructions) {
// The DOM has been updated, do what you want here.
}
merge(
source
, target
, { done });
`####
And for
, it is the same as the merge() function. So once the vDOM is rendered and DOM is patched, done() is called with the instructions that were performed.`js
import { h, render } from 'skatejs-dom-diff';function done (instructions) {
// Renering and patching is done...
}
const root = document.createElement('div');
const doRender = render((root) => (
{root.test}
));div.test = 'initial text';
doRender(div, done);
div.test = 'updated text';
doRender(div, done);
``