legends - 2

README.md

@@ -224,6 +224,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 chart’s *color* scale, 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*.**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:
@@ -273,7 +309,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/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,21 @@
+import {exposeScale, Scale} from "./scales.js";
+import {legendColor} from "./legends/color.js";
+
+export function legend({color, ...options}) {
+  if (color != null) {
+    return legendColor(exposeScale(Scale("color", undefined, color)), {
+      // ...color,
+      label: color.label,
+      // ticks: color.ticks, // maybe?
+      // tickFormat: color.tickFormat, // maybe?
+      // tickValues: color.tickValues, // maybe?
+      // format: color.format, // maybe?
+      ...options
+    });
+  }
+  throw new Error(`unsupported legend type`);
+}
+
+export function exposeLegends(type, options) {
+  return legend({...options, [type]: this.scale(type)});
+}

src/legends/color.js

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

src/legends/ramp.js

@@ -0,0 +1,162 @@
+import {Scale} from "../scales.js";
+import {create, quantize, interpolateNumber, piecewise, format, scaleBand, scaleLinear, axisBottom} from "d3";
+import {applyInlineStyles, maybeClassName} from "../style.js";
+
+export function legendRamp(scale, {
+  label,
+  tickSize = 6,
+  width = 240,
+  height = 44 + tickSize,
+  marginTop = 18,
+  marginRight = 0,
+  marginBottom = 16 + tickSize,
+  marginLeft = 0,
+  style,
+  ticks = width / 64,
+  tickFormat,
+  tickValues,
+  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;
+
+  const {type, domain, range, interpolate, apply} = scale;
+
+  // 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 = interpolate.length === 1
+        ? interpolate
+        : piecewise(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 = Scale("color", undefined, scale).scale.rangeRound(
+      quantize(
+        interpolateNumber(marginLeft, width - marginRight),
+        Math.min(
+          domain.length + (scale.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 = scaleLinear()
+        .domain([-1, range.length - 1])
+        .rangeRound([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);
+
+    tickValues = Array.from(thresholds, (_, i) => i);
+    tickFormat = i => thresholdFormat(thresholds[i], i);
+  }
+
+  // Ordinal (hopefully!)
+  else {
+    x = scaleBand()
+        .domain(domain)
+        .rangeRound([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", apply);
+
+    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))
+      .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;
+}

src/legends/swatches.js

@@ -0,0 +1,100 @@
+import {create} from "d3";
+import {applyInlineStyles, maybeClassName} from "../style.js";
+
+export function legendSwatches(color, {
+  columns,
+  format = x => x,
+  // TODO label,
+  swatchSize = 15,
+  swatchWidth = swatchSize,
+  swatchHeight = swatchSize,
+  marginLeft = 0,
+  className,
+  style,
+  width
+} = {}) {
+  className = maybeClassName(className);
+
+  const swatches = create("div")
+      .attr("class", className)
+      .attr("style", `
+        --swatchWidth: ${+swatchWidth}px;
+        --swatchHeight: ${+swatchHeight}px;
+      `);
+
+  let extraStyle;
+
+  if (columns != null) {
+    extraStyle = `
+      .${className}-swatch {
+        display: flex;
+        align-items: center;
+        break-inside: avoid;
+        padding-bottom: 1px;
+      }
+      .${className}-swatch::before {
+        flex-shrink: 0;
+      }
+      .${className}-label {
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+    `;
+
+    swatches
+        .style("columns", columns)
+      .selectAll()
+      .data(color.domain)
+      .join("div")
+        .attr("class", `${className}-swatch`)
+        .style("--color", color.apply)
+        .call(item => item.append("div")
+            .attr("class", `${className}-label`)
+            .attr("title", format)
+            .text(format));
+  } else {
+    extraStyle = `
+      .${className} {
+        display: flex;
+        align-items: center;
+        min-height: 33px;
+      }
+      .${className}-swatch {
+        display: inline-flex;
+        align-items: center;
+        margin-right: 1em;
+      }
+    `;
+
+    swatches
+      .selectAll()
+      .data(color.domain)
+      .join("span")
+        .attr("class", `${className}-swatch`)
+        .style("--color", color.apply)
+        .text(format);
+  }
+
+  return swatches
+      .call(div => div.insert("style", "*").text(`
+        .${className} {
+          font-family: system-ui, sans-serif;
+          font-size: 10px;
+          font-variant: tabular-nums;
+          margin-bottom: 0.5em;${marginLeft === undefined ? "" : `
+          margin-left: ${+marginLeft}px;`}${width === undefined ? "" : `
+          width: ${width}px;`}
+        }
+        .${className}-swatch::before {
+          content: "";
+          width: var(--swatchWidth);
+          height: var(--swatchHeight);
+          margin-right: 0.5em;
+          background: var(--color);
+        }
+        ${extraStyle}
+      `))
+      .call(applyInlineStyles, style)
+    .node();
+}

src/plot.js

@@ -1,9 +1,10 @@
 import {create} from "d3";
 import {Axes, autoAxisTicks, autoScaleLabels} from "./axes.js";
 import {facets} from "./facet.js";
+import {exposeLegends} from "./legends.js";
 import {markify} from "./mark.js";
 import {Scales, autoScaleRange, applyScales, exposeScales, isOrdinalScale} from "./scales.js";
-import {filterStyles, maybeClassName, offset} from "./style.js";
+import {applyInlineStyles, filterStyles, maybeClassName, offset} from "./style.js";
 
 export function plot(options = {}) {
   const {facet, style, caption} = options;
@@ -93,10 +94,7 @@ export function plot(options = {}) {
           white-space: pre;
         }
       `))
-      .each(function() {
-        if (typeof style === "string") this.style = style;
-        else Object.assign(this.style, style);
-      })
+      .call(applyInlineStyles, style)
     .node();
 
   for (const mark of marks) {
@@ -117,6 +115,7 @@ export function plot(options = {}) {
   }
 
   figure.scale = exposeScales(scaleDescriptors);
+  figure.legend = exposeLegends;
   return figure;
 }