Finalize the design of the render API

[Fil]

The render API still has a few quirks that we might want to address:

Scales

The scales argument is an object of D3 scale functions. This is inconsistent with how we expose the scales elsewhere. Currently internal marks need the scales for a few operations:

• to scale values out of band (for example, on X and Y for scaleProjection in the geo mark, and on color for the raster/contour/density mark); this can be replaced by scale.apply
• isCollapsed tests the materialized domain (exposed as scale.domain)
• applyTransform needs the materialized bandwidth (in the bar, tick marks…), it's exposed as scale.bandwidth
• axes want to call the scale.ticks function which is not exposed
• …more which I haven't located yet?…

If we passed the same objects that plot.scale("x") returns (i.e. scale descriptors), we need to pass the "ticks" function, or to recreate it from the descriptor.

Facets

The index passed to render is decorated with the facet information : the values of fx and fy for the current facet, as well as a facet index fi. (fi is used internally for the raster mark.) This needs to be documented. Example here.

svg, parent element

Passing the svg, and the parent element, could help to build marks that need to use these (for instance, to add defs to the svg). They could be referenced in the context argument. For example, #1304 experiments with passing the svg in the context. (This was done in 0.6.7.)

Event listeners

A mark wants to listen to events (pointermove…), and send events (setting a value and sending a CustomEvent(input)). Needs an "official" api support rather than the mark fishing for the figure element. (Done in 0.6.7.)

Update

Farther in the future, we might want to have a strategy to update a “layer”; this could happen by passing the previously returned node.

Documentation

Once this is is decided and done (one way or another), a documentation notebook with examples will help advanced users who want to extend Plot.

(for an earlier version of this issue, see #501)

[Fil]

This should also be done in the initializer, see #8 for a use case.

[mbostock]

(Clarified the issue title to make clear that we already have a render API, but that the design isn’t finalized and has the described quirks and outstanding questions.)

[mbostock]

Closing as we have done most of the work here, though there may be follow-up feature enhancements.