waffle multiple option (#2121)

Author: mbostock

docs/marks/waffle.md

@@ -124,13 +124,22 @@ Plot.waffleX([apples], {y: ["apples"]}).plot({height: 240})
 The number of rows in the waffle above is guaranteed to be an integer, but it might not be a multiple or factor of the *x*-axis tick interval. For example, the waffle might have 15 rows while the *x*-axis shows ticks every 100 units.
 :::
 :::tip
-While you can’t control the number of rows (or columns) directly, you can affect it via the **padding** option on the corresponding band scale. Padding defaults to 0.1; a higher value may produce more rows, while a lower (or zero) value may produce fewer rows.
+To set the number of rows (or columns) directly, use the **multiple** option, though note that manually setting the multiple may result in non-square cells if there isn’t enough room. Alternatively, you can bias the automatic multiple while preserving square cells by setting the **padding** option on the corresponding band scale: padding defaults to 0.1; a higher value may produce more rows, while a lower (or zero) value may produce fewer rows.
 :::
 
 ## Waffle options
 
 For required channels, see the [bar mark](./bar.md). The waffle mark supports the [standard mark options](../features/marks.md), including [insets](../features/marks.md#insets) and [rounded corners](../features/marks.md#rounded-corners). The **stroke** defaults to *none*. The **fill** defaults to *currentColor* if the stroke is *none*, and to *none* otherwise.
 
+The waffle mark supports a few additional options to control the rendering of cells:
+
+* **unit** - the quantity each cell represents; defaults to 1
+* **multiple** - the number of cells per row (or column); defaults to undefined
+* **gap** - the separation between adjacent cells, in pixels; defaults to 1
+* **round** - whether to round values to avoid partial cells; defaults to false
+
+If **multiple** is undefined (the default), the waffle mark will use as many cells per row (or column) that fits within the available bandwidth while ensuring that the cells are square, or one cell per row if square cells are not possible. You can change the rounding behavior by specifying **round** as a function, such as Math.floor or Math.ceil; true is equivalent to Math.round.
+
 ## waffleX(*data*, *options*) {#waffleX}
 
 ```js

src/marks/waffle.d.ts

@@ -3,6 +3,8 @@ import type {BarXOptions, BarYOptions} from "./bar.js";
 
 /** Options for the waffleX and waffleY mark. */
 interface WaffleOptions {
+  /** The number of cells per row or column; defaults to undefined for automatic. */
+  multiple?: number;
   /** The quantity each cell represents; defaults to 1. */
   unit?: number;
   /** The gap in pixels between cells; defaults to 1. */

src/marks/waffle.js

@@ -14,20 +14,22 @@ const waffleDefaults = {
 };
 
 export class WaffleX extends BarX {
-  constructor(data, {unit = 1, gap = 1, round, render, ...options} = {}) {
+  constructor(data, {unit = 1, gap = 1, round, render, multiple, ...options} = {}) {
     super(data, {...options, render: composeRender(render, waffleRender("x"))}, waffleDefaults);
     this.unit = Math.max(0, unit);
     this.gap = +gap;
     this.round = maybeRound(round);
+    this.multiple = maybeMultiple(multiple);
   }
 }
 
 export class WaffleY extends BarY {
-  constructor(data, {unit = 1, gap = 1, round, render, ...options} = {}) {
+  constructor(data, {unit = 1, gap = 1, round, render, multiple, ...options} = {}) {
     super(data, {...options, render: composeRender(render, waffleRender("y"))}, waffleDefaults);
     this.unit = Math.max(0, unit);
     this.gap = +gap;
     this.round = maybeRound(round);
+    this.multiple = maybeMultiple(multiple);
   }
 }
 
@@ -45,16 +47,16 @@ function waffleRender(y) {
     // The length of a unit along y in pixels.
     const scale = unit * scaleof(scales.scales[y]);
 
-    // The number of cells on each row of the waffle.
-    const columns = Math.max(1, Math.floor(Math.sqrt(barwidth / scale)));
+    // The number of cells on each row (or column) of the waffle.
+    const {multiple = Math.max(1, Math.floor(Math.sqrt(barwidth / scale)))} = this;
 
     // The outer size of each square cell, in pixels, including the gap.
-    const cx = Math.min(barwidth, scale * columns);
-    const cy = scale * columns;
+    const cx = Math.min(barwidth / multiple, scale * multiple);
+    const cy = scale * multiple;
 
     // TODO insets?
     const transform = y === "y" ? ([x, y]) => [x * cx, -y * cy] : ([x, y]) => [y * cy, x * cx];
-    const tx = (barwidth - columns * cx) / 2;
+    const tx = (barwidth - multiple * cx) / 2;
     const x0 = typeof barx === "function" ? (i) => barx(i) + tx : barx + tx;
     const y0 = scales[y](0);
 
@@ -96,7 +98,7 @@ function waffleRender(y) {
           .attr(
             "d",
             (i) =>
-              `M${wafflePoints(round(Y1[i] / unit), round(Y2[i] / unit), columns)
+              `M${wafflePoints(round(Y1[i] / unit), round(Y2[i] / unit), multiple)
                 .map(transform)
                 .join("L")}Z`
           )
@@ -183,6 +185,10 @@ function maybeRound(round) {
   return round;
 }
 
+function maybeMultiple(multiple) {
+  return multiple === undefined ? undefined : Math.max(1, Math.floor(multiple));
+}
+
 function scaleof({domain, range}) {
   return spread(range) / spread(domain);
 }

test/output/waffleMultiple.svg

@@ -15,6 +15,16 @@ export function waffleSquished() {
   return Plot.waffleX([10]).plot();
 }
 
+export function waffleMultiple() {
+  return Plot.plot({
+    y: {inset: 12},
+    marks: [
+      Plot.waffleY([4, 9, 24, 46, 66, 7], {multiple: 10, fill: "currentColor"}),
+      Plot.waffleY([-4, -9, -24, -46, -66, -7], {multiple: 10, fill: "red"})
+    ]
+  });
+}
+
 export function waffleShorthand() {
   return Plot.plot({
     y: {inset: 12},