facet wrap

README.md

@@ -486,6 +486,8 @@ The following *facet* constant options are also supported:
 * facet.**margin** - shorthand for the four margins
 * facet.**grid** - if true, draw grid lines for each facet
 * facet.**label** - if null, disable default facet axis labels
+* facet.**columns** - the number of columns for a grid layout
+* facet.**rows** - the number of rows for a grid layout
 
 Faceting can be explicitly enabled or disabled on a mark with the *facet* option, which accepts the following values:
 
@@ -510,6 +512,8 @@ 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.)
 
+The *columns* option wraps facets on a grid layout with the given number of columns, which defaults to the square root of the number of facets when *columns* is true. If *columns* is not set, the *rows* option similarly wraps facets with the given number of rows. The layout starts from the top-left and expands horizontally if the facet is given by the *x* channel, and vertically if the facet is given by *y*. Facets are sorted in natural ascending order, but a different order can be given by setting an explicit domain for *fx* or *fy*, or by using a mark’s sort option.
+
 ## Legends
 
 Plot can generate legends for *color*, *opacity*, and *symbol* [scales](#scale-options). (An opacity scale is treated as a color scale with varying transparency.) For an inline legend, use the *scale*.**legend** option:

src/axes.js

@@ -5,7 +5,7 @@ import {position, registry} from "./scales/index.js";
 
 export function Axes(
   {x: xScale, y: yScale, fx: fxScale, fy: fyScale},
-  {x = {}, y = {}, fx = {}, fy = {}, axis = true, grid, line, label, facet: {axis: facetAxis = axis, grid: facetGrid, label: facetLabel = label} = {}} = {}
+  {x = {}, y = {}, fx = {}, fy = {}, axis = true, grid, line, label, facet: {columns, rows, axis: facetAxis = axis && !(columns || rows), grid: facetGrid, label: facetLabel = label} = {}} = {}
 ) {
   let {axis: xAxis = axis} = x;
   let {axis: yAxis = axis} = y;

src/plot.js

@@ -1,10 +1,10 @@
-import {create, cross, difference, groups, InternMap, select} from "d3";
+import {create, cross, difference, groups, InternMap, select, sort} from "d3";
 import {Axes, autoAxisTicks, autoScaleLabels} from "./axes.js";
 import {Channel, channelSort} from "./channel.js";
 import {defined} from "./defined.js";
 import {Dimensions} from "./dimensions.js";
 import {Legends, exposeLegends} from "./legends.js";
-import {arrayify, isOptions, keyword, range, second, where} from "./options.js";
+import {arrayify, isOptions, keyword, range, first, second, where} from "./options.js";
 import {Scales, ScaleFunctions, autoScaleRange, applyScales, exposeScales} from "./scales.js";
 import {applyInlineStyles, maybeClassName, maybeClip, styles} from "./style.js";
 import {basic} from "./transforms/basic.js";
@@ -36,7 +36,11 @@ export function plot(options = {}) {
   let facetsIndex; // nested array of facet indexes [[0, 1, 3, …], [2, 5, …], …]
   let facetsExclude; // lazily-constructed opposite of facetsIndex
   if (facet !== undefined) {
-    const {x, y} = facet;
+    const {x, y, columns, rows} = facet;
+    if (columns != null || rows != null) {
+      if (columns != null && rows != null) throw new Error("Only columns or rows can be specified at a time.");
+      if (x != null && y != null) throw new Error("Columns or rows must be applied to one-dimensional facets.");
+    }
     if (x != null || y != null) {
       const facetData = arrayify(facet.data);
       facetChannels = [];
@@ -76,6 +80,40 @@ export function plot(options = {}) {
     stateByMark.set(mark, {index, channels, faceted: markFacets !== undefined});
   }
 
+  // remap grid facet coordinates into fx+fy
+  if (facet !== undefined) {
+    let {x, columns, rows} = facet;
+    if (columns != null || rows != null) {
+      const fz = x ? "fx" : "fy";
+      let domain = options?.[fz]?.domain;
+      if (domain != null) {
+        options = {
+          ...options,
+          ...options.fx && {fx: {...options.fx, domain: undefined}},
+          ...options.fy && {fy: {...options.fy, domain: undefined}}
+        };
+      } else {
+        const f = channelsByScale.get(fz)[0];
+        domain = f.domain !== undefined ? f.domain() : sort(facets.map(first));
+      }
+      if (fz === "fy") ([rows, columns] = [columns, rows]);
+      const len = columns === true ? Math.floor(Math.sqrt(domain.length))
+        : rows === true ? Math.ceil(Math.sqrt(domain.length))
+        : columns != null ? +columns
+        : Math.ceil(domain.length / +rows);
+      let ia = new Map(domain.map((v, i) => [v, i % len]));
+      let ib = new Map(domain.map((v, i) => [v, Math.floor(i / len)]));
+      if (fz === "fy") ([ia, ib] = [ib, ia]);
+      for (const f of facets) {
+        const v = f[0];
+        f[0] = [ia.get(v), ib.get(v)];
+      }
+      channelsByScale.set("fx", [{scale: "fx", value: [], domain: () => ia.values()}]);
+      channelsByScale.set("fy", [{scale: "fy", value: [], domain: () => ib.values()}]);
+      facetChannels = [["fx", {scale: "fx", value: []}], ["fy", {scale: "fy", value: []}]];
+    }
+  }
+
   // Apply scale transforms, mutating channel.value.
   for (const [scale, channels] of channelsByScale) {
     const {percent, transform = percent ? x => x * 100 : undefined} = options[scale] || {};