transforms can declare channels (#899)

* transforms can declare channels

* default dodge to sort by reverse r (if r is a channel)

* derive scale labels after the reinitializers have run (#900)

* derive scale labels after the reinitializers have run

* tweak style

Co-authored-by: Mike Bostock <[email protected]>

* only if both sort and reverse are undefined

* fix tests

* Update README

Co-authored-by: Philippe Rivière <[email protected]>

Author: mbostock

README.md

@@ -2213,6 +2213,8 @@ Initializers can be used to transform and derive new channels prior to rendering
 
 The **anchor** option may one of *middle*, *right*, and *left* for dodgeX, and one of *middle*, *top*, and *bottom* for dodgeY. With the *middle* anchor the piles will grow from the center in both directions; with the other anchors, the piles will grow from the specified anchor towards the opposite direction.
 
+The dodge layout is highly dependent on the input data order: the circles placed first will be closest to the dodge anchor. When using the dodge layout with circles of varying radius, the data is sorted by descending radius by default; you can disable this behavior by setting the **sort** or **reverse** option.
+
 #### Plot.dodgeY([*layoutOptions*, ]*options*)
 
 ```js
@@ -2262,7 +2264,9 @@ See also the [hexgrid](#hexgrid) mark.
 
 ### Custom initializers
 
-You can specify a custom initializer by specifying a function as the mark *initializer* option. This function is called after the scales have been computed, and receives as inputs the (possibly transformed) array of *data*, the *facets* index of elements of this array that belong to each facet, the input *channels* (as an object of named channels), the *scales*, and the *dimensions*. The mark itself is the *this* context. The initializer function must return an object with *data*, *facets*, and new *channels*. Any new channels are merged with existing channels, replacing channels of the same name.
+You can specify a custom initializer by specifying a function as the mark **initializer** option. This function is called after the scales have been computed, and receives as inputs the (possibly transformed) array of *data*, the *facets* index of elements of this array that belong to each facet, the input *channels* (as an object of named channels), the *scales*, and the *dimensions*. The mark itself is the *this* context. The initializer function must return an object with *data*, *facets*, and new *channels*. Any new channels are merged with existing channels, replacing channels of the same name.
+
+If an initializer desires a channel that is not supported by the downstream mark, additional channels can be declared using the mark **channels** option.
 
 ## Curves
 

src/plot.js

@@ -87,7 +87,6 @@ export function plot(options = {}) {
   const dimensions = Dimensions(scaleDescriptors, axes, options);
 
   autoScaleRange(scaleDescriptors, dimensions);
-  autoScaleLabels(channelsByScale, scaleDescriptors, axes, dimensions, options);
   autoAxisTicks(scaleDescriptors, axes);
 
   const {fx, fy} = scales;
@@ -118,6 +117,8 @@ export function plot(options = {}) {
     Object.assign(scales, newScales);
   }
 
+  autoScaleLabels(channelsByScale, scaleDescriptors, axes, dimensions, options);
+
   // Compute value objects, applying scales as needed.
   for (const state of stateByMark.values()) {
     state.values = valueObject(state.channels, scales);
@@ -247,15 +248,16 @@ export function plot(options = {}) {
 
 export class Mark {
   constructor(data, channels = [], options = {}, defaults) {
-    const {facet = "auto", sort, dx, dy, clip, initializer} = options;
+    const {facet = "auto", sort, dx, dy, clip, initializer, channels: extraChannels} = options;
     const names = new Set();
     this.data = data;
     this.sort = isOptions(sort) ? sort : null;
     this.initializer = this.sort?.channel == null ? initializer : channelSort(initializer, this.sort);
     this.facet = facet == null || facet === false ? null : keyword(facet === true ? "include" : facet, "facet", ["auto", "include", "exclude"]);
     const {transform} = basic(options);
     this.transform = transform;
-    if (defaults !== undefined) channels = styles(this, options, channels, defaults);
+    if (extraChannels !== undefined) channels = [...channels, ...extraChannels.filter(e => !channels.some(c => c.name === e.name))];
+    if (defaults !== undefined) channels = [...channels, ...styles(this, options, defaults)];
     this.channels = channels.filter(channel => {
       const {name, value, optional} = channel;
       if (value == null) {

src/style.js

@@ -32,7 +32,6 @@ export function styles(
     paintOrder,
     shapeRendering
   },
-  channels,
   {
     ariaLabel: cariaLabel,
     fill: defaultFill = "currentColor",
@@ -125,7 +124,6 @@ export function styles(
   mark.shapeRendering = impliedString(shapeRendering, "auto");
 
   return [
-    ...channels,
     {name: "title", value: title, optional: true},
     {name: "href", value: href, optional: true},
     {name: "ariaLabel", value: variaLabel, optional: true},

src/transforms/dodge.js

@@ -17,7 +17,7 @@ function maybeAnchor(anchor) {
 }
 
 export function dodgeX(dodgeOptions = {}, options = {}) {
-  if (arguments.length === 1) [options, dodgeOptions] = [dodgeOptions, options];
+  if (arguments.length === 1) ([dodgeOptions, options] = mergeOptions(dodgeOptions));
   let {anchor = "left", padding = 1} = maybeAnchor(dodgeOptions);
   switch (`${anchor}`.toLowerCase()) {
     case "left": anchor = anchorXLeft; break;
@@ -29,7 +29,7 @@ export function dodgeX(dodgeOptions = {}, options = {}) {
 }
 
 export function dodgeY(dodgeOptions = {}, options = {}) {
-  if (arguments.length === 1) [options, dodgeOptions] = [dodgeOptions, options];
+  if (arguments.length === 1) ([dodgeOptions, options] = mergeOptions(dodgeOptions));
   let {anchor = "bottom", padding = 1} = maybeAnchor(dodgeOptions);
   switch (`${anchor}`.toLowerCase()) {
     case "top": anchor = anchorYTop; break;
@@ -40,7 +40,18 @@ export function dodgeY(dodgeOptions = {}, options = {}) {
   return dodge("y", "x", anchor, number(padding), options);
 }
 
+function mergeOptions(options) {
+  const {padding, ...rest} = options;
+  return [{padding}, rest];
+}
+
 function dodge(y, x, anchor, padding, options) {
+  const {r} = options;
+  if (r != null && typeof r !== "number") {
+    const {channels, sort, reverse} = options;
+    options = {...options, channels: [...channels ?? [], {name: "r", value: r, scale: "r"}]};
+    if (sort === undefined && reverse === undefined) options.sort = r, options.reverse = true;
+  }
   return initializer(options, function(data, facets, {[x]: X, r: R}, scales, dimensions) {
     if (!X) throw new Error(`missing channel: ${x}`);
     X = coerceNumbers(valueof(X.value, scales[X.scale] || identity));