document layouts

[Fil]

note: the custom layout example will change a little if we do #712

[mbostock]

We shouldn’t use/recommend mutation.

[mbostock]

This example does nothing out of the box, because values.fill will always be undefined. Perhaps a more realistic example would be better? For example, maybe you could have a helper function…

function darker(key = "fill", amount = 1) {
  return (index, scales, {fill, ...values}, dimension) => {
    fill = fill.slice();
    for (const i of index) fill[i] = d3.rgb(fill[i]).darker(amount);
    return {...values, fill};
  };
}

And then

Plot.dot(penguins, {fill: "body_mass_g", layout: darker()})

I guess even this feels very contrived, since it’d be better to do this on the scale definition. Maybe we should remove the custom layouts section until we can think of a better motivating example?

[Fil]

layout: contrasting on Plot.text could be short (and fix #540). A good contrasting color not as simple as checking a color's lightness, though, so an official implementation would likely diverge from such an example.

Removing this part for now.

[mbostock]

Choosing a contrasting color sounds interesting and useful. Perhaps the fill input channel specifies the background color (e.g., fill: "imdb_rating" in the Simpsons example), and then the layout outputs a new fill channel where each output color is either light or dark depending on the lightness of the input? Something like:

Plot.text(simpsons, Plot.contrast({
  x: "season",
  y: "number_in_season",
  text: d => d.imdb_rating?.toFixed(1),
  title: "title",
  fill: "imdb_rating"
}))

Though, some sort of magic like this might be better…

Plot.text(simpsons, {
  x: "season",
  y: "number_in_season",
  text: d => d.imdb_rating?.toFixed(1),
  title: "title",
  fill: Plot.contrast("imdb_rating")
})

Which, I guess, would be like a per-channel layout.

[Fil]

I'll open a new issue and prototype :)

[mbostock]

Superseded by #775.