frame channels (#1509)

* frame channels

* tider

* faithful fill

* frame facet channels; update documentation

* copy edit

Author: mbostock

docs/marks/frame.md

@@ -2,11 +2,17 @@
 
 import * as Plot from "@observablehq/plot";
 import * as d3 from "d3";
-import {ref} from "vue";
+import {ref, shallowRef, onMounted} from "vue";
 import penguins from "../data/penguins.ts";
 
 const framed = ref(true);
 
+const faithful = shallowRef([]);
+
+onMounted(() => {
+  d3.tsv("../data/faithful.tsv", d3.autoType).then((data) => (faithful.value = data));
+});
+
 </script>
 
 # Frame mark
@@ -50,6 +56,43 @@ Plot.frame({stroke: "red"}).plot({x: {domain: [0, 1], grid: true}})
 ```
 :::
 
+While options are often specified in literal values, such as <span style="border-bottom: solid 2px var(--vp-c-red);">*red*</span> above, the standard [mark channels](../features/marks.md#mark-options) such as **fill** and **stroke** can also be specified as abstract values. For example, in the density heatmap below comparing the delay between eruptions of the Old Faithful geyser (*waiting*) in *x*→ and the duration of the eruption (*eruptions*) in *y*↑, both in minutes, we fill the frame with <span :style="{borderBottom: `solid 2px ${d3.interpolateTurbo(0)}`}">black</span> representing zero density.
+
+:::plot defer
+```js
+Plot.plot({
+  inset: 30,
+  marks: [
+    Plot.frame({fill: 0}),
+    Plot.density(faithful, {x: "waiting", y: "eruptions", fill: "density"})
+  ]
+})
+```
+:::
+
+:::tip
+This is equivalent to a [rect](./rect.md): `Plot.rect({length: 1}, {fill: 0})`.
+:::
+
+You can also place a frame on a specific facet using the **fx** or **fy** option. Below, a frame emphasizes the *Gentoo* facet, say to draw attention to how much bigger they are. 🐧
+
+:::plot
+```js
+Plot.plot({
+  marginLeft: 80,
+  inset: 10,
+  marks: [
+    Plot.frame({fy: "Gentoo"}),
+    Plot.dot(penguins, {x: "body_mass_g", fy: "species"})
+  ]
+})
+```
+:::
+
+:::tip
+Or: `Plot.rect({length: 1}, {fy: ["Gentoo"], stroke: "currentColor"})`.
+:::
+
 The **anchor** option, if specified to a value of *left*, *right*, *top* or *bottom*, draws only that side of the frame. In that case, the **fill** and **rx**, **ry** options are ignored.
 
 :::plot
@@ -68,7 +111,7 @@ Plot.plot({
 
 ## Frame options
 
-The frame mark supports the [standard mark options](../features/marks.md#mark-options), and the **rx** and **ry** options to set the [*x* radius](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/rx) and [*y* radius](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/ry) for rounded corners. It does not accept any data or support channels. The default **stroke** is *currentColor*, and the default **fill** is *none*.
+The frame mark supports the [standard mark options](../features/marks.md#mark-options), and the **rx** and **ry** options to set the [*x* radius](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/rx) and [*y* radius](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/ry) for rounded corners. It does not accept any data. The default **stroke** is *currentColor*, and the default **fill** is *none*.
 
 If the **anchor** option is specified as one of *left*, *right*, *top*, or *bottom*, that side is rendered as a single line (and the **fill**, **fillOpacity**, **rx**, and **ry** options are ignored).
 

src/mark.js

@@ -1,8 +1,7 @@
-import {createChannels, channelDomain, valueObject} from "./channel.js";
+import {channelDomain, createChannels, valueObject} from "./channel.js";
 import {defined} from "./defined.js";
 import {maybeFacetAnchor} from "./facet.js";
-import {arrayify, isDomainSort, isOptions, range} from "./options.js";
-import {keyword, maybeNamed} from "./options.js";
+import {arrayify, isDomainSort, isOptions, keyword, maybeNamed, range, singleton} from "./options.js";
 import {maybeProject} from "./projection.js";
 import {maybeClip, styles} from "./style.js";
 import {basic, initializer} from "./transforms/basic.js";
@@ -33,8 +32,8 @@ export class Mark {
       this.facet = null;
     } else {
       this.facet = keyword(facet === true ? "include" : facet, "facet", ["auto", "include", "exclude", "super"]);
-      this.fx = fx;
-      this.fy = fy;
+      this.fx = data === singleton && typeof fx === "string" ? [fx] : fx;
+      this.fy = data === singleton && typeof fy === "string" ? [fy] : fy;
     }
     this.facetAnchor = maybeFacetAnchor(facetAnchor);
     channels = maybeNamed(channels);
@@ -43,10 +42,15 @@ export class Mark {
     this.channels = Object.fromEntries(
       Object.entries(channels)
         .map(([name, channel]) => {
-          const {value} = channel;
-          if (isOptions(value)) {
-            channel = {...channel, value: value.value};
-            if (value.scale !== undefined) channel.scale = value.scale;
+          if (isOptions(channel.value)) {
+            // apply scale overrides
+            const {value, scale = channel.scale} = channel.value;
+            channel = {...channel, scale, value};
+          }
+          if (data === singleton && typeof channel.value === "string") {
+            // convert field names to singleton values for decoration marks (e.g., frame)
+            const {value} = channel;
+            channel = {...channel, value: [value]};
           }
           return [name, channel];
         })

src/marks/frame.js

@@ -1,7 +1,7 @@
 import {create} from "../context.js";
 import {Mark} from "../mark.js";
-import {maybeKeyword, number} from "../options.js";
-import {applyDirectStyles, applyIndirectStyles, applyTransform} from "../style.js";
+import {maybeKeyword, number, singleton} from "../options.js";
+import {applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyTransform} from "../style.js";
 
 const defaults = {
   ariaLabel: "frame",
@@ -28,7 +28,7 @@ export class Frame extends Mark {
       rx,
       ry
     } = options;
-    super(undefined, undefined, options, anchor == null ? defaults : lineDefaults);
+    super(singleton, undefined, options, anchor == null ? defaults : lineDefaults);
     this.anchor = maybeKeyword(anchor, "anchor", ["top", "right", "bottom", "left"]);
     this.insetTop = number(insetTop);
     this.insetRight = number(insetRight);
@@ -45,8 +45,10 @@ export class Frame extends Mark {
     const y1 = marginTop + insetTop;
     const y2 = height - marginBottom - insetBottom;
     return create(anchor ? "svg:line" : "svg:rect", context)
+      .datum(0)
       .call(applyIndirectStyles, this, dimensions, context)
       .call(applyDirectStyles, this)
+      .call(applyChannelStyles, this, channels)
       .call(applyTransform, this, {})
       .call(
         anchor === "left"

src/marks/hexgrid.js

@@ -1,7 +1,7 @@
 import {create} from "../context.js";
 import {Mark} from "../mark.js";
-import {number} from "../options.js";
-import {applyDirectStyles, applyIndirectStyles, applyTransform, offset} from "../style.js";
+import {number, singleton} from "../options.js";
+import {applyChannelStyles, applyDirectStyles, applyIndirectStyles, applyTransform, offset} from "../style.js";
 import {sqrt4_3} from "../symbol.js";
 import {ox, oy} from "../transforms/hexbin.js";
 
@@ -18,7 +18,7 @@ export function hexgrid(options) {
 
 export class Hexgrid extends Mark {
   constructor({binWidth = 20, clip = true, ...options} = {}) {
-    super(undefined, undefined, {clip, ...options}, defaults);
+    super(singleton, undefined, {clip, ...options}, defaults);
     this.binWidth = number(binWidth);
   }
   render(index, scales, channels, dimensions, context) {
@@ -45,9 +45,10 @@ export class Hexgrid extends Mark {
       }
     }
     return create("svg:g", context)
+      .datum(0)
       .call(applyIndirectStyles, this, dimensions, context)
       .call(applyTransform, this, {}, offset + ox, offset + oy)
-      .call((g) => g.append("path").call(applyDirectStyles, this).attr("d", d))
+      .call((g) => g.append("path").call(applyDirectStyles, this).call(applyChannelStyles, this, channels).attr("d", d))
       .node();
   }
 }

src/options.js

@@ -38,6 +38,7 @@ function floater(f) {
   return (d, i) => coerceNumber(f(d, i));
 }
 
+export const singleton = [null]; // for data-less decoration marks, e.g. frame
 export const field = (name) => (d) => d[name];
 export const indexOf = {transform: range};
 export const identity = {transform: (d) => d};

test/marks/frame-test.js

@@ -3,7 +3,7 @@ import assert from "assert";
 
 it("frame(options) has the expected defaults", () => {
   const frame = Plot.frame();
-  assert.strictEqual(frame.data, undefined);
+  assert.deepStrictEqual(frame.data, [null]);
   assert.strictEqual(frame.transform, undefined);
   assert.deepStrictEqual(frame.channels, {});
   assert.strictEqual(frame.fill, "none");