legends - 2 (#583)

* legends

* Plot.legend takes a scale and options

* Remove Plot.legend, use chart.legend instead.

* reinstate Plot.legend

* unused code

* allow legend: "ramp" as an option

* snapshot test for a lot of color legends

* no random in unit tests

* remove redundant color tests

* accept a label on swatches

* className for legendSwatches

* remove radius and opacity legends for now

* more scope

* only color is available in this branch

* do not expose any class

* error on unknown legend type

* categorical is normalized to ordinal

* show unknown legend type in error

* prEtTieR

* prioritize type; avoid unnecessary default

* non-nullish, not truthy

* div.append(…nodes)

* legends

* Plot.legend takes a scale and options

* Remove Plot.legend, use chart.legend instead.

* reinstate Plot.legend

* unused code

* allow legend: "ramp" as an option

* snapshot test for a lot of color legends

* no random in unit tests

* remove redundant color tests

* accept a label on swatches

* className for legendSwatches

* remove radius and opacity legends for now

* more scope

* only color is available in this branch

* do not expose any class

* error on unknown legend type

* categorical is normalized to ordinal

* show unknown legend type in error

* prEtTieR

* prioritize type; avoid unnecessary default

* non-nullish, not truthy

* div.append(…nodes)

* less duck typing

* remove entity filtering

* reduce duck-typing

* add a test for Plot.legend with options

* styles

* clear up some confusion between scale options and legend options

* className

* apply() rather than color()

* Update README

* revert figure changes

* avoid closure

* applyInlineStyles

* revert diverging scale changes

* inline styles; fix diverging; separate tests

* stringify and lowercase legend option

* normalizeScale

* inherit scale options

* fix ordinal tickFormat function

* explicit ordinal ticks

* use pushState for tests

* round option

* fix for truncated schemes

* opacity legend (#587)

* opacity legend

* add color option

* legend: true

* fix test determinism

* fix inline opacity legends

* arrow key navigation

* ignore style if null

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

Author: Fil

README.md

@@ -225,6 +225,42 @@ For convenience, an apply method is exposed, which returns the scale’s output
 
 The scale object is undefined if the associated plot has no scale with the given *name*, and throws an error if the *name* is invalid (*i.e.*, not one of the known scale names: *x*, *y*, *fx*, *fy*, *r*, *color*, or *opacity*).
 
+### Legends
+
+Given a scale definition, Plot can generate a legend.
+
+#### *chart*.legend(*name*[, *options*])
+
+Returns a suitable legend for the chart’s scale with the given *name*. For now, only *color* legends are supported.
+
+Categorical and ordinal color legends are rendered as swatches, unless *options*.**legend** is set to *ramp*. The swatches can be configured with the following options:
+
+* *options*.**tickFormat** - a format function for the labels
+* *options*.**swatchSize** - the size of the swatch (if square)
+* *options*.**swatchWidth** - the swatches’ width
+* *options*.**swatchHeight** - the swatches’ height
+* *options*.**columns** - the number of swatches per row
+* *options*.**marginLeft** - the legend’s left margin
+* *options*.**className** - a class name, that defaults to a randomly generated string scoping the styles
+
+Continuous color legends are rendered as a ramp, and can be configured with the following options:
+
+* *options*.**label** - the scale’s label
+* *options*.**ticks** - the desired number of ticks, or an array of tick values
+* *options*.**tickFormat** - a format function for the legend’s ticks
+* *options*.**tickSize** - the tick size
+* *options*.**round** - if true (default), round tick positions to pixels
+* *options*.**width** - the legend’s width
+* *options*.**height** - the legend’s height
+* *options*.**marginTop** - the legend’s top margin
+* *options*.**marginRight** - the legend’s right margin
+* *options*.**marginBottom** - the legend’s bottom margin
+* *options*.**marginLeft** - the legend’s left margin
+
+#### Plot.legend({[*name*]: *scale*, ...*options*})
+
+Returns a legend for the given *scale* definition, passing the options described in the previous section. Currently supports only *color* and *opacity* scales. An opacity scale is treated as a color scale with varying transparency.
+
 ### Position options
 
 The position scales (*x*, *y*, *fx*, and *fy*) support additional options:
@@ -274,7 +310,7 @@ Plot automatically generates axes for position scales. You can configure these a
 * *scale*.**labelAnchor** - the label anchor: *top*, *right*, *bottom*, *left*, or *center*
 * *scale*.**labelOffset** - the label position offset (in pixels; default 0, typically for facet axes)
 
-Plot does not currently generate a legend for the *color*, *radius*, or *opacity* scales, but when it does, we expect that some of the above options will also be used to configure legends. Top-level options are also supported as shorthand: **grid** and **line** (for *x* and *y* only; see also [facet.grid](#facet-options)), **label**, **axis**, **inset**, **round**, **align**, and **padding**.
+Top-level options are also supported as shorthand: **grid** (for *x* and *y* only; see [facet.grid](#facet-options)), **label**, **axis**, **inset**, **round**, **align**, and **padding**.
 
 ### Color options
 

package.json

@@ -37,6 +37,7 @@
   "devDependencies": {
     "@rollup/plugin-json": "^4.1.0",
     "@rollup/plugin-node-resolve": "^13.0.4",
+    "canvas": "^2.8.0",
     "eslint": "^7.12.1",
     "htl": "^0.3.0",
     "js-beautify": "^1.13.0",

src/axis.js

@@ -202,14 +202,19 @@ function gridFacetY(index, fx, tx) {
       .attr("d", (index ? take(domain, index) : domain).map(v => `M${fx(v) + tx},0h${dx}`).join(""));
 }
 
-function createAxis(axis, scale, {ticks, tickSize, tickPadding, tickFormat}) {
-  if (!scale.tickFormat && typeof tickFormat !== "function") {
-    // D3 doesn’t provide a tick format for ordinal scales; we want shorthand
-    // when an ordinal domain is numbers or dates, and we want null to mean the
-    // empty string, not the default identity format.
-    tickFormat = tickFormat === undefined ? (isTemporal(scale.domain()) ? formatIsoDate : string)
-      : (typeof tickFormat === "string" ? (isTemporal(scale.domain()) ? utcFormat : format)
+// D3 doesn’t provide a tick format for ordinal scales; we want shorthand when
+// an ordinal domain is numbers or dates, and we want null to mean the empty
+// string, not the default identity format.
+export function maybeTickFormat(tickFormat, domain) {
+  return tickFormat === undefined ? (isTemporal(domain) ? formatIsoDate : string)
+      : typeof tickFormat === "function" ? tickFormat
+      : (typeof tickFormat === "string" ? (isTemporal(domain) ? utcFormat : format)
       : constant)(tickFormat);
+}
+
+function createAxis(axis, scale, {ticks, tickSize, tickPadding, tickFormat}) {
+  if (!scale.tickFormat) {
+    tickFormat = maybeTickFormat(tickFormat, scale.domain());
   }
   return axis(scale)
     .ticks(Array.isArray(ticks) ? null : ticks, typeof tickFormat === "function" ? null : tickFormat)

src/index.js

@@ -22,3 +22,4 @@ export {window, windowX, windowY} from "./transforms/window.js";
 export {selectFirst, selectLast, selectMaxX, selectMaxY, selectMinX, selectMinY} from "./transforms/select.js";
 export {stackX, stackX1, stackX2, stackY, stackY1, stackY2} from "./transforms/stack.js";
 export {formatIsoDate, formatWeekday, formatMonth} from "./format.js";
+export {legend} from "./legends.js";

src/legends.js

@@ -0,0 +1,42 @@
+import {normalizeScale} from "./scales.js";
+import {legendColor} from "./legends/color.js";
+import {legendOpacity} from "./legends/opacity.js";
+import {isObject} from "./mark.js";
+
+const legendRegistry = new Map([
+  ["color", legendColor],
+  ["opacity", legendOpacity]
+]);
+
+export function legend(options = {}) {
+  for (const [key, value] of legendRegistry) {
+    const scale = options[key];
+    if (isObject(scale)) { // e.g., ignore {color: "red"}
+      return value(normalizeScale(key, scale), legendOptions(scale, options));
+    }
+  }
+  throw new Error("unknown legend type");
+}
+
+export function exposeLegends(scales, defaults = {}) {
+  return (key, options) => {
+    if (!legendRegistry.has(key)) throw new Error(`unknown legend type: ${key}`);
+    if (!(key in scales)) return;
+    return legendRegistry.get(key)(scales[key], legendOptions(defaults[key], options));
+  };
+}
+
+function legendOptions({label, ticks, tickFormat} = {}, options = {}) {
+  return {label, ticks, tickFormat, ...options};
+}
+
+export function Legends(scales, options) {
+  const legends = [];
+  for (const [key, value] of legendRegistry) {
+    const o = options[key];
+    if (o && o.legend) {
+      legends.push(value(scales[key], legendOptions(scales[key], o)));
+    }
+  }
+  return legends;
+}

src/legends/color.js

@@ -0,0 +1,14 @@
+import {legendRamp} from "./ramp.js";
+import {legendSwatches} from "./swatches.js";
+
+export function legendColor(color, {
+  legend = true,
+  ...options
+}) {
+  if (legend === true) legend = color.type === "ordinal" ? "swatches" : "ramp";
+  switch (`${legend}`.toLowerCase()) {
+    case "swatches": return legendSwatches(color, options);
+    case "ramp": return legendRamp(color, options);
+    default: throw new Error(`unknown legend type: ${legend}`);
+  }
+}

src/legends/opacity.js

@@ -0,0 +1,20 @@
+import {rgb} from "d3";
+import {legendColor} from "./color.js";
+
+const black = rgb(0, 0, 0);
+
+export function legendOpacity({type, interpolate, ...scale}, {
+  legend = true,
+  color = black,
+  ...options
+}) {
+  if (!interpolate) throw new Error(`${type} opacity scales are not supported`);
+  if (legend === true) legend = "ramp";
+  if (`${legend}`.toLowerCase() !== "ramp") throw new Error(`${legend} opacity legends are not supported`);
+  return legendColor({type, ...scale, interpolate: interpolateOpacity(color)}, {legend, ...options});
+}
+
+function interpolateOpacity(color) {
+  const {r, g, b} = rgb(color) || black; // treat invalid color as black
+  return t => `rgba(${r},${g},${b},${t})`;
+}

src/legends/ramp.js

@@ -0,0 +1,166 @@
+import {create, quantize, interpolateNumber, piecewise, format, scaleBand, scaleLinear, axisBottom} from "d3";
+import {interpolatePiecewise} from "../scales/quantitative.js";
+import {applyInlineStyles, maybeClassName} from "../style.js";
+
+export function legendRamp(color, {
+  label,
+  tickSize = 6,
+  width = 240,
+  height = 44 + tickSize,
+  marginTop = 18,
+  marginRight = 0,
+  marginBottom = 16 + tickSize,
+  marginLeft = 0,
+  style,
+  ticks = (width - marginLeft - marginRight) / 64,
+  tickFormat,
+  round = true,
+  className
+}) {
+  className = maybeClassName(className);
+
+  const svg = create("svg")
+      .attr("class", className)
+      .attr("font-family", "system-ui, sans-serif")
+      .attr("font-size", 10)
+      .attr("font-variant", "tabular-nums")
+      .attr("width", width)
+      .attr("height", height)
+      .attr("viewBox", `0 0 ${width} ${height}`)
+      .call(svg => svg.append("style").text(`
+        .${className} {
+          display: block;
+          background: white;
+          height: auto;
+          height: intrinsic;
+          max-width: 100%;
+          overflow: visible;
+        }
+        .${className} text {
+          white-space: pre;
+        }
+      `))
+      .call(applyInlineStyles, style);
+
+  let tickAdjust = g => g.selectAll(".tick line").attr("y1", marginTop + marginBottom - height);
+
+  let x;
+
+  // Some D3 scales use scale.interpolate, some scale.interpolator, and some
+  // scale.round; this normalizes the API so it works with all scale types.
+  const applyRange = round
+      ? (x, range) => x.rangeRound(range)
+      : (x, range) => x.range(range);
+
+  const {type, domain, range, interpolate, scale, pivot} = color;
+
+  // Continuous
+  if (interpolate) {
+
+    // Often interpolate is a “fixed” interpolator on the [0, 1] interval, as
+    // with a built-in color scheme, but sometimes it is a function that takes
+    // two arguments and is used in conjunction with the range.
+    const interpolator = range === undefined ? interpolate
+        : piecewise(interpolate.length === 1 ? interpolatePiecewise(interpolate)
+        : interpolate, range);
+
+    // Construct a D3 scale of the same type, but with a range that evenly
+    // divides the horizontal extent of the legend. (In the common case, the
+    // domain.length is two, and so the range is simply the extent.) For a
+    // diverging scale, we need an extra point in the range for the pivot such
+    // that the pivot is always drawn in the middle.
+    x = applyRange(
+      scale.copy(),
+      quantize(
+        interpolateNumber(marginLeft, width - marginRight),
+        Math.min(
+          domain.length + (pivot !== undefined),
+          range === undefined ? Infinity : range.length
+        )
+      )
+    );
+
+    svg.append("image")
+        .attr("x", marginLeft)
+        .attr("y", marginTop)
+        .attr("width", width - marginLeft - marginRight)
+        .attr("height", height - marginTop - marginBottom)
+        .attr("preserveAspectRatio", "none")
+        .attr("xlink:href", ramp(interpolator).toDataURL());
+  }
+
+  // Threshold
+  else if (type === "threshold") {
+    const thresholds = domain;
+
+    const thresholdFormat
+        = tickFormat === undefined ? d => d
+        : typeof tickFormat === "string" ? format(tickFormat)
+        : tickFormat;
+
+    // Construct a linear scale with evenly-spaced ticks for each of the
+    // thresholds; the domain extends one beyond the threshold extent.
+    x = applyRange(scaleLinear().domain([-1, range.length - 1]), [marginLeft, width - marginRight]);
+
+    svg.append("g")
+      .selectAll("rect")
+      .data(range)
+      .join("rect")
+        .attr("x", (d, i) => x(i - 1))
+        .attr("y", marginTop)
+        .attr("width", (d, i) => x(i) - x(i - 1))
+        .attr("height", height - marginTop - marginBottom)
+        .attr("fill", d => d);
+
+    ticks = Array.from(thresholds, (_, i) => i);
+    tickFormat = i => thresholdFormat(thresholds[i], i);
+  }
+
+  // Ordinal (hopefully!)
+  else {
+    x = applyRange(scaleBand().domain(domain), [marginLeft, width - marginRight]);
+
+    svg.append("g")
+      .selectAll("rect")
+      .data(domain)
+      .join("rect")
+        .attr("x", x)
+        .attr("y", marginTop)
+        .attr("width", Math.max(0, x.bandwidth() - 1))
+        .attr("height", height - marginTop - marginBottom)
+        .attr("fill", scale);
+
+    tickAdjust = () => {};
+  }
+
+  svg.append("g")
+      .attr("transform", `translate(0,${height - marginBottom})`)
+      .call(axisBottom(x)
+          .ticks(Array.isArray(ticks) ? null : ticks, typeof tickFormat === "string" ? tickFormat : undefined)
+          .tickFormat(typeof tickFormat === "function" ? tickFormat : undefined)
+          .tickSize(tickSize)
+          .tickValues(Array.isArray(ticks) ? ticks : null))
+      .attr("font-size", null)
+      .attr("font-family", null)
+      .call(tickAdjust)
+      .call(g => g.select(".domain").remove())
+      .call(label === undefined ? () => {} : g => g.append("text")
+          .attr("x", marginLeft)
+          .attr("y", marginTop + marginBottom - height - 6)
+          .attr("fill", "currentColor") // TODO move to stylesheet?
+          .attr("text-anchor", "start")
+          .attr("font-weight", "bold")
+          .text(label));
+
+  return svg.node();
+}
+
+function ramp(color, n = 256) {
+  const canvas = create("canvas").attr("width", n).attr("height", 1).node();
+  const context = canvas.getContext("2d");
+  for (let i = 0; i < n; ++i) {
+    context.fillStyle = color(i / (n - 1));
+    context.fillRect(i, 0, 1, 1);
+  }
+  return canvas;
+}