Support D3 4.x

[jakezatecky]

D3 4.x is out, but includes a variety of backwards-incompatible changes. Will still need to support 3.x for a while.

[jakezatecky]

I almost think Mike Bostock got a kick out of making the upgrade to D3 v4.x as painful and under-documented as possible. For some reason, all of the examples assume that the d3 has been loaded in a <script> tag and no examples are provided for ES6. What was once easy using import d3 from 'd3'; has become an exercise in sifting through issues and debugging in order to make up for the deficiencies or just plain inaccuracies in the documentation. Contrary to statements otherwise, not all of the API can be resolved from D3's index.js.

General API

Generally, anything that was previously accessible from d3 is still available, with some major exceptions. The key difference is how this information is imported:

// Old
import d3 from 'd3';

d3.range(0, 10);

// New
import * as d3 from 'd3';

d3.range(0, 10);

Multi-attributes

As documented, selection.attr() has been reduced to single value settings and selection.attrs() must be used for setting multiple attributes (similar for selection.styles()). What is not documented is the very particular import process; thankfully, there's an issue for that.

// Old
import d3 from 'd3';

d3.select('#a').attr({ class: 'b'});

// New
import { select } from 'd3-selection';
import 'd3-selection-multi';  // Will NOT work on `import * as d3 from 'd3';`

select('#a').attrs({ class: 'b' });

Events

Events have been overhauled to support ES6 arrow functions, which is good. What's not good is the lack of documentation. The new behavior is weakly mentioned in an issue. What is not mentioned is that d3.event will always be null, contrary to the documentation.

// Old
import d3 from 'd3';

d3.select('#target').on('mouseover', () => {
    const node = d3.event.target;
});

// New
import { select } from 'd3-selection';

select('#target').on('mouseover', (data, groupIndex, nodes) => {
    const node = nodes[0];
});

DOM Nodes

In D3 v3.x, there was no good way to get the individual nodes from a selectAll result. Nevertheless, since selections were similar to arrays, nodes could be accessed through indices. D3 v4.x got rid of this in favor of selection.node() and selection.nodes(), and in a surprising twist, this was documented:

// Old
import d3 from 'd3';

const node = d3.select('#target')[0];
const nodes = d3.selectAll('#target path')[0];

// New
import { select, selectAll } from 'd3-selection';

const node = select('#target').node();
const nodes = selectAll('#target path').nodes();