legends - 2

README.md

@@ -220,6 +220,42 @@ const plot2 = Plot.plot({…, color: plot1.scale("color")});
 
 The returned scale object represents the actual (or “materialized”) values encountered in the plot, including the domain, range, interpolate function, *etc.* The scale’s label, if any, is also returned; however, note that other axis properties are not currently exposed. 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 chart’s *color* scale, Plot can generate a legend:
+
+#### chart.legend(*name*[, *options*])
+
+A suitable legend is returned for the chart’s scale 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*.**columns** - the number of swatches per row
+* *options*.**format** - 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*.**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*.**tickSize** - the tick size
+* *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
+* *options*.**ticks** - number of ticks
+* *options*.**tickFormat** - a format function for the legend’s ticks
+* *options*.**tickValues** - the legend’s tick values
+
+#### Plot.legend({*name*: *scale*, ...*options*})
+
+Builds a legend from a scale description object, passing the options described in the previous section. The only supported name for now is *color*.
+
 ### Position options
 
 The position scales (*x*, *y*, *fx*, and *fy*) support additional options:
@@ -269,7 +305,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/figure.js

@@ -0,0 +1,12 @@
+
+// Wrap the plot in a figure with a caption, if desired.
+export function figureWrap(svg, {width}, caption) {
+  if (caption == null) return svg;
+  const figure = document.createElement("figure");
+  figure.style = `max-width: ${width}px`;
+  figure.appendChild(svg);
+  const figcaption = document.createElement("figcaption");
+  figcaption.appendChild(caption instanceof Node ? caption : document.createTextNode(caption));
+  figure.appendChild(figcaption);
+  return figure;
+}

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,5 @@
+import {legendColor} from "./legends/color.js";
+
+export function legend({color, ...options}) {
+  if (color) return legendColor({...color, ...options});
+}

src/legends/color.js

@@ -0,0 +1,16 @@
+import {Scale} from "../scales.js";
+import {legendRamp} from "./ramp.js";
+import {legendSwatches} from "./swatches.js";
+
+export function legendColor({legend, ...options}) {
+  const scale = Scale("color", undefined, options);
+  if (legend === undefined) legend = scale.type === "ordinal" || scale.type === "categorical" ? "swatches" : "ramp";
+  switch (legend) {
+    case "swatches":
+      return legendSwatches({...scale, ...options});
+    case "ramp":
+      return legendRamp({...scale, ...options});
+    default:
+      throw new Error(`unknown legend type ${legend}`);
+  }
+}

src/legends/ramp.js

@@ -0,0 +1,154 @@
+import {create, scaleLinear, quantize, interpolate, interpolateRound, quantile, range, format, scaleBand, axisBottom} from "d3";
+
+export function legendRamp({
+  label,
+  tickSize = 6,
+  width = 240, 
+  height = 44 + tickSize,
+  marginTop = 18,
+  marginRight = 0,
+  marginBottom = 16 + tickSize,
+  marginLeft = 0,
+  ticks = width / 64,
+  tickFormat,
+  tickValues,
+  scale: color
+} = {}) {
+  const svg = create("svg")
+      .attr("width", width)
+      .attr("height", height)
+      .attr("viewBox", [0, 0, width, height])
+      .style("overflow", "visible")
+      .style("display", "block");
+
+  let tickAdjust = g => g.selectAll(".tick line").attr("y1", marginTop + marginBottom - height);
+  let x;
+
+  // Continuous
+  if (color.interpolate) {
+    const n = Math.min(color.domain().length, color.range().length);
+    x = color.copy().rangeRound(quantize(interpolate(marginLeft, width - marginRight), n));
+    let color2 = color.copy().domain(quantize(interpolate(0, 1), n));
+    // special case for log scales
+    if (color.base) {
+      const p = scaleLinear(
+        quantize(interpolate(0, 1), color.domain().length),
+        color.domain().map(d => Math.log(d))
+      );
+      color2 = t => color(Math.exp(p(t)));
+    }
+    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(color2).toDataURL());
+  }
+
+  // Sequential
+  else if (color.interpolator) {
+    x = Object.assign(color.copy()
+        .interpolator(interpolateRound(marginLeft, width - marginRight)),
+        {range() { return [marginLeft, width - marginRight]; }});
+
+    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(color.interpolator()).toDataURL());
+
+    // scaleSequentialQuantile doesn’t implement ticks or tickFormat.
+    if (!x.ticks) {
+      if (tickValues === undefined) {
+        const n = Math.round(ticks + 1);
+        tickValues = range(n).map(i => quantile(color.domain(), i / (n - 1)));
+      }
+      if (typeof tickFormat !== "function") {
+        tickFormat = format(tickFormat === undefined ? ",f" : tickFormat);
+      }
+    }
+  }
+
+  // Threshold
+  else if (color.invertExtent) {
+    const thresholds
+        = color.thresholds ? color.thresholds() // scaleQuantize
+        : color.quantiles ? color.quantiles() // scaleQuantile
+        : color.domain(); // scaleThreshold
+
+    const thresholdFormat
+        = tickFormat === undefined ? d => d
+        : typeof tickFormat === "string" ? format(tickFormat)
+        : tickFormat;
+
+    x = scaleLinear()
+        .domain([-1, color.range().length - 1])
+        .rangeRound([marginLeft, width - marginRight]);
+
+    svg.append("g")
+      .selectAll("rect")
+      .data(color.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);
+
+    tickValues = range(thresholds.length);
+    tickFormat = i => thresholdFormat(thresholds[i], i);
+  }
+
+  // Ordinal
+  else {
+    x = scaleBand()
+        .domain(color.domain())
+        .rangeRound([marginLeft, width - marginRight]);
+
+    svg.append("g")
+      .selectAll("rect")
+      .data(color.domain())
+      .join("rect")
+        .attr("x", x)
+        .attr("y", marginTop)
+        .attr("width", Math.max(0, x.bandwidth() - 1))
+        .attr("height", height - marginTop - marginBottom)
+        .attr("fill", color);
+
+    tickAdjust = () => {};
+  }
+
+  svg.append("g")
+      .attr("transform", `translate(0,${height - marginBottom})`)
+      .call(axisBottom(x)
+        .ticks(ticks, typeof tickFormat === "string" ? tickFormat : undefined)
+        .tickFormat(typeof tickFormat === "function" ? tickFormat : undefined)
+        .tickSize(tickSize)
+        .tickValues(tickValues))
+      .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")
+        .attr("text-anchor", "start")
+        .attr("font-weight", "bold")
+        .attr("class", "label")
+        .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;
+}

src/legends/swatches.js

@@ -0,0 +1,115 @@
+import {create} from "d3";
+import {maybeClassName} from "../style.js";
+
+// TODO: once we inline, is this smart variable handling any
+// better than inline styles?
+const styles = uid => `
+.${uid} {
+  display: flex;
+  align-items: center;
+  margin-left: var(--marginLeft);
+  min-height: 33px;
+  font: 10px sans-serif;
+  margin-bottom: 0.5em;
+}
+
+.${uid} > div {
+  width: 100%;
+}
+
+.${uid} .swatch-item {
+  break-inside: avoid;
+  display: flex;
+  align-items: center;
+  padding-bottom: 1px;
+}
+
+.${uid} .swatch-label {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: calc(100% - var(--swatchWidth) - 0.5em);
+}
+
+.${uid} .swatch-block {
+  width: var(--swatchWidth);
+  height: var(--swatchHeight);
+  margin: 0 0.5em 0 0;
+}
+
+.${uid} .plot-swatch {
+  display: inline-flex;
+  align-items: center;
+  margin-right: 1em;
+}
+
+.${uid} .plot-swatch::before {
+  content: "";
+  width: var(--swatchWidth);
+  height: var(--swatchHeight);
+  margin-right: 0.5em;
+  background: var(--color);
+}
+`;
+
+export function legendSwatches({
+  columns = null,
+  format = x => x,
+  label,
+  swatchSize = 15,
+  swatchWidth = swatchSize,
+  swatchHeight = swatchSize,
+  marginLeft = 0,
+  className,
+  uid = maybeClassName(className),
+  style = styles(uid),
+  width,
+  scale: color
+} = {}) {
+  const swatches = create("div")
+    .classed(uid, true)
+    .attr("style", `--marginLeft: ${+marginLeft}px; --swatchWidth: ${+swatchWidth}px; --swatchHeight: ${+swatchHeight}px;${
+      width === undefined ? "" : ` width: ${width}px;`
+    }`);
+  swatches.append("style").text(style);
+
+  if (columns !== null) {
+    const elems = swatches.append("div")
+      .style("columns", columns);
+    for (const value of color.domain()) {
+      const d = elems.append("div").classed("swatch-item", true);
+      d.append("div")
+        .classed("swatch-block", true)
+        .style("background", color(value));
+      const label = format(value);
+      d.append("div")
+        .classed("swatch-label", true)
+        .text(label)
+        .attr("title", label.replace(/["&]/g, entity));
+    }
+  } else {
+    swatches
+      .selectAll()
+      .data(color.domain())
+      .join("span")
+      .classed("plot-swatch", true)
+      .style("--color", color)
+      .text(format);
+  }
+
+  return label == null
+  ? swatches.node()
+  : create("div")
+      .call(div => div.append("div")
+        .style("font-weight", "bold")
+        .style("font-family", "sans-serif")
+        .style("font-size", "10px")
+        .style("margin", "5px 0 -5px 0")
+        .text(label))
+      .call(div => div.append(() => swatches.node()))
+      .node();
+}
+
+function entity(character) {
+  return `&#${character.charCodeAt(0).toString()};`;
+}

src/plot.js

@@ -1,6 +1,8 @@
 import {create} from "d3";
 import {Axes, autoAxisTicks, autoScaleLabels} from "./axes.js";
 import {facets} from "./facet.js";
+import {figureWrap} from "./figure.js";
+import { legend } from "./legends.js";
 import {markify} from "./mark.js";
 import {Scales, autoScaleRange, applyScales, exposeScales, isOrdinalScale} from "./scales.js";
 import {filterStyles, maybeClassName, offset} from "./style.js";
@@ -108,15 +110,9 @@ export function plot(options = {}) {
   }
 
   // Wrap the plot in a figure with a caption, if desired.
-  let figure = svg;
-  if (caption != null) {
-    figure = document.createElement("figure");
-    figure.appendChild(svg);
-    const figcaption = figure.appendChild(document.createElement("figcaption"));
-    figcaption.appendChild(caption instanceof Node ? caption : document.createTextNode(caption));
-  }
-
+  const figure = figureWrap(svg, dimensions, caption);
   figure.scale = exposeScales(scaleDescriptors);
+  figure.legend = (type, options = {}) => legend({[type]: figure.scale(type), ...options});
   return figure;
 }