flatten the mark facet/facet filter API and simplify the code

Author: Fil

README.md

@@ -699,9 +699,10 @@ Faceting can be explicitly enabled or disabled on a mark with the *facet* option
 * *include* (or true) - draw the subset of the mark’s data in the current facet
 * *exclude* - draw the subset of the mark’s data *not* in the current facet
 * null (or false) - repeat this mark’s data across all facets (i.e., no faceting)
-* an object with a xFilter or yFilter option
 
-The facet filter option can be one of:
+By default, the data points shown in each facet are those that exactly match the facet value. Use the **xFilter** and **yFilter** options to change that behavior for, respectively, the *x* and *y* facets:
+
+The xFilter or yFilter option can be one of:
 * *eq* (default) - the data points shown in each facet are those that exactly match the facet value
 * *lte* - the data points shown in each facet are those that are lower than or equal to the facet value
 * *gte* - the data points shown in each facet are those that are greater than or equal to the facet value
@@ -725,15 +726,16 @@ Plot.plot({
 
 When the *include* or *exclude* facet mode is chosen, the mark data must be parallel to the facet data: the mark data must have the same length and order as the facet data. If the data are not parallel, then the wrong data may be shown in each facet. The default *auto* therefore requires strict equality (`===`) for safety, and using the facet data as mark data is recommended when using the *exclude* facet mode. (To construct parallel data safely, consider using [*array*.map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/map) on the facet data.)
 
-Alternatively, facets can be defined from each mark, by specifying the facet option as an object with an x or y channel option.
+Alternatively, facets can be defined from each mark by specifying the channel options **fx** or **fy**.
 
 ```js
 Plot.plot({
   marks: [
     Plot.dot(penguins, {
       x: "culmen_length_mm",
       y: "culmen_depth_mm",
-      facet: {x: "sex", y: "island"}
+      fx: "sex",
+      fy: "island"
     })
   ]
 })

src/facet.js

@@ -1,44 +1,31 @@
-import {keyword, isObject, isTypedArray, labelof, range, slice, valueof} from "./options.js";
+import {keyword, isTypedArray, range, slice} from "./options.js";
 import {warn} from "./warnings.js";
 
 // facet filter, by mark
-export function filterFacets(facetCells, {x, xFilter, y, yFilter}, facetChannels) {
-  const vx = x != null ? x : facetChannels?.fx?.value;
-  const vy = y != null ? y : facetChannels?.fy?.value;
+export function filterFacets(facetCells, {xFilter, yFilter}, {fx, fy}, facetChannels) {
+  const vx = fx != null ? fx.value : facetChannels?.fx?.value;
+  const vy = fy != null ? fy.value : facetChannels?.fy?.value;
+  if (!vx && !vy) return; // ignore facet filter without facets
   const I = range(vx || vy);
   return facetCells.map(([x, y]) => {
     let index = I;
-    if (xFilter && vx) index = xFilter(index, vx, x);
-    if (yFilter && vy) index = yFilter(index, vy, y);
+    if (vx) index = facetFilter(xFilter, "x")(index, vx, x);
+    if (vy) index = facetFilter(yFilter, "y")(index, vy, y);
     return index;
   });
 }
 
-export function maybeFacet(facet, data) {
-  if (facet == null || facet === false) return null;
+export function maybeFacet(options) {
+  const {fx, xFilter, fy, yFilter, facet = "auto"} = options;
+  if (fx !== undefined || fy !== undefined || xFilter !== undefined || yFilter !== undefined)
+    return {x: fx, xFilter, y: fy, yFilter};
+  if (facet === null || facet === false) return null;
   if (facet === true) return "include";
   if (typeof facet === "string") return keyword(facet, "facet", ["auto", "include", "exclude"]);
-  // local facets can be defined as facet: {x: accessor, xFilter: "lte"}
-  if (!isObject(facet)) throw new Error(`Unsupported facet ${facet}`);
-  const {x, xFilter = "eq", y, yFilter = "eq"} = facet;
-  let xv, yv;
-  if (x !== undefined) {
-    xv = valueof(data, x);
-    if (xv != null) xv.label = labelof(x);
-  }
-  if (y !== undefined) {
-    yv = valueof(data, y);
-    if (yv != null) yv.label = labelof(y);
-  }
-  return {
-    ...(xv && {x: xv}),
-    ...(yv && {y: yv}),
-    xFilter: maybeFacetFilter(xFilter, "x"),
-    yFilter: maybeFacetFilter(yFilter, "y")
-  };
+  if (facet) throw new Error(`Unsupported facet ${facet}`);
 }
 
-function maybeFacetFilter(filter = "eq", x /* string */) {
+function facetFilter(filter = "eq", x) {
   if (typeof filter === "function") return facetFunction(filter);
   switch (`${filter}`.toLowerCase()) {
     case "lt":

src/plot.js

@@ -420,12 +420,16 @@ export function plot(options = {}) {
       if (mark.facet.x !== undefined) {
         const channels = channelsByScale.get("fx") || [];
         channelsByScale.set("fx", channels);
-        channels.push(Channel(mark.data, {value: mark.facet.x, scale: "fx"}));
+        const channel = Channel(mark.data, {value: mark.facet.x, scale: "fx"});
+        stateByMark.get(mark).fx = channel;
+        channels.push(channel);
       }
       if (mark.facet.y !== undefined) {
         const channels = channelsByScale.get("fy") || [];
         channelsByScale.set("fy", channels);
-        channels.push(Channel(mark.data, {value: mark.facet.y, scale: "fy"}));
+        const channel = Channel(mark.data, {value: mark.facet.y, scale: "fy"});
+        stateByMark.get(mark).fy = channel;
+        channels.push(channel);
       }
     }
   }
@@ -449,9 +453,10 @@ export function plot(options = {}) {
   let facetIndex; // index over the facet data, e.g. [0, 1, 2, 3, …]
   let facetsExclude; // lazily-constructed opposite of facetsIndex
   for (const mark of marks) {
-    if (mark.facet === null) {
-      continue;
-    }
+    if (mark.facet === null) continue;
+    const state = stateByMark.get(mark);
+
+    // top-level facet with no filter: optimize by computing facetIndex once
     if (typeof mark.facet === "string") {
       if (!facet || (mark.facet === "auto" && mark.data !== facet.data)) continue;
       if (!facetsIndex) {
@@ -461,10 +466,12 @@ export function plot(options = {}) {
           facetIndex.filter((i) => (!fx || fx.value[i] === kx) && (!fy || fy.value[i] === ky))
         );
       }
-      stateByMark.get(mark).facetsIndex = facetsIndex;
+      state.facetsIndex = facetsIndex;
       continue;
     }
-    stateByMark.get(mark).facetsIndex = filterFacets(facetCells, mark.facet, facetChannels);
+
+    // Otherwise, compute specific indexes for that mark
+    if (facetCells) state.facetsIndex = filterFacets(facetCells, mark.facet, state, facetChannels);
   }
 
   // A facet is empty if none of the faceted index has contents for any mark
@@ -495,7 +502,7 @@ export function plot(options = {}) {
     // Warn for the common pitfall of wanting to facet mapped data.
     if (
       facet &&
-      facetCells.length > 1 && // non-trivial faceting
+      facetCells?.length > 1 && // non-trivial faceting
       mark.facet === "auto" && // no explicit mark facet option
       mark.data !== facet.data && // mark not implicitly faceted (different data)
       arrayify(mark.data)?.length === facetChannels.size // mark data seems parallel to facet data
@@ -718,12 +725,12 @@ export function plot(options = {}) {
 
 export class Mark {
   constructor(data, channels = {}, options = {}, defaults) {
-    const {facet = "auto", sort, dx, dy, clip, channels: extraChannels} = options;
+    const {sort, dx, dy, clip, channels: extraChannels} = options;
     this.data = data;
     this.sort = isDomainSort(sort) ? sort : null;
     this.initializer = initializer(options).initializer;
     this.transform = this.initializer ? options.transform : basic(options).transform;
-    this.facet = maybeFacet(facet, data);
+    this.facet = maybeFacet(options, data);
     channels = maybeNamed(channels);
     if (extraChannels !== undefined) channels = {...maybeNamed(extraChannels), ...channels};
     if (defaults !== undefined) channels = {...styles(this, options, defaults), ...channels};

test/plots/multiplication-table.js

@@ -9,19 +9,20 @@ export default async function () {
     color: {type: "ordinal", scheme: "tableau10"},
     fx: {axis: "top"},
     marks: [
-      Plot.rect(nums, {facet: {y: nums}, fill: nums}),
+      Plot.rect(nums, {fy: nums, fill: nums}),
       Plot.dot(nums, {
         frameAnchor: "middle",
         r: 19,
-        fill: (d) => d,
+        fill: nums,
         stroke: "white",
-        facet: {x: (d) => d}
+        fx: nums
       }),
       Plot.text(d3.cross(nums, nums), {
         frameAnchor: "middle",
         text: ([a, b]) => a * b,
         fill: "white",
-        facet: {x: (d) => d[1], y: (d) => d[0]}
+        fx: (d) => d[1],
+        fy: (d) => d[0]
       })
     ]
   });

test/plots/penguins-facet-annotated-x.js

@@ -15,14 +15,14 @@ export default async function () {
           {
             y: "species",
             fill: "sex",
-            facet: {x: "island"}
+            fx: "island"
           }
         )
       ),
       Plot.text(["Torgersen Island\nonly has\nAdelie\npenguins!"], {
         frameAnchor: "right",
         dx: -10,
-        facet: {x: ["Torgersen"]}
+        fx: ["Torgersen"]
       })
     ]
   });

test/plots/penguins-facet-annotated.js

@@ -17,14 +17,14 @@ export default async function () {
           {
             y: "species",
             fill: "sex",
-            facet: {y: "island"}
+            fy: "island"
           }
         )
       ),
       Plot.text(["↞ Torgersen Island only has Adelie penguins!"], {
         frameAnchor: "top-right",
         dx: -10,
-        facet: {y: ["Torgersen"]}
+        fy: ["Torgersen"]
       })
     ]
   });

test/plots/walmart-expansion-bar.js

@@ -20,7 +20,8 @@ export default async function () {
           {x: "count"},
           {
             fill: "year",
-            facet: {y: "year", yFilter: "lte"},
+            fy: "year",
+            yFilter: "lte",
             stroke: "white",
             offset: "expand"
           }

test/plots/walmart-expansion.js

@@ -24,7 +24,7 @@ export default async function () {
         y: "1",
         fill: "#ccc",
         r: 2,
-        facet: {yFilter: "lt"}
+        yFilter: "lt"
       }),
       Plot.dot(walmart, {
         x: "0",