plotto 0.3.1 → 0.4.0

package/README.md

@@ -26,7 +26,7 @@ p.interactive()                     # the same plot with zoom, pan, hover and le
 p.theme("wota")                     # another style
 p.color(palette="aizome")           # another palette
 p.save("fig.png")                   # PNG; .svg for vector files
-p.theme("wota", format="slide").save("slide.png")   # 1280 × 720 px, large text
+p.theme("wota", format="slide").save("slide.png")   # 960 × 600 px, large text
 ```
 
 ```js
@@ -111,6 +111,7 @@ The table is a card on the right of the plot, or below it. A plot narrower than
 - A legend click hides or shows a series. Two quick clicks on the same entry (within 300 ms) show only that series.
 - The toolbar shows at the top right when the pointer is on the plot:
   - copy as PNG;
+  - copy for a slide: the current view in the slide format, which pastes into Google Slides at 6.72 × 4.2 in (75% of the slide height), sharp;
   - download as PNG or SVG;
   - in interactive mode, also zoom box, pan, zoom in, zoom out and reset.
 - The output loads d3 and Observable Plot from `cdn.jsdelivr.net`. GitHub, nbviewer, or a page without network access shows the static SVG in the output.
@@ -125,10 +126,11 @@ The table is a card on the right of the plot, or below it. A plot narrower than
 
 | Target | Use |
 |---|---|
-| Google Slides | PNG: `p.save("fig.png")`. Google Slides does not accept SVG. |
+| Google Slides | The "Copy for a slide" button, then paste under the slide title: 6.72 × 4.2 in, with room for comments on the right. Or a PNG: `p.save("fig.png")`. Google Slides does not accept SVG. |
 | PowerPoint, Keynote, documents | SVG: `p.save("fig.svg")`. The SVG uses the installed fonts. |
-| A slide layout | `p.theme(style, format="slide")`: 1280 × 720 px with large text |
+| A slide layout | `p.theme(style, format="slide")`: 960 × 600 px with large text |
 | A report column | `p.theme(style, format="report")`: 640 × 400 px |
+| Square panels | `p.theme(aspect=1)`, for observed-against-predicted plots. Give x and y the same `limits`. |
 | A given size | `p.save("fig.png", width=1600)` lays the plot out again at 1600 px. |
 | From the notebook | Use the copy button, which copies the current view as PNG. |
 
@@ -192,30 +194,26 @@ One-time setup:
 
 4. On npmjs.com, open the package `plotto` → Settings → Trusted publishing → GitHub Actions: repository `theoradusz/plotto`, workflow `release.yml`. Later versions then publish from GitHub with no token. The workflow skips a version that is already on npm.
 
-Each release:
+Each release (`main` takes changes only through a reviewed pull request):
 
-`main` takes changes only through a reviewed pull request, so a release has two steps.
+```bash
+# 1. Merge your changes into main through a pull request
 
-1. On `main`, with no uncommitted changes and the Python environment of the repo active, prepare the release:
+# 2. Prepare the release
+git switch main && git pull && source .venv/bin/activate
+scripts/release.sh 0.3.1
+#    → the pull request page opens: create it, get it approved and merged
 
-   ```
-   scripts/release.sh 0.3.0
-   ```
-
-   The script:
-   - checks that `main` is up to date with `origin/main` and that the version is new and higher;
-   - runs `npm test`, `npm run browser-test`, `pytest python/tests`, `ruff` and `black`;
-   - on a new branch `release/v0.3.0`, sets the version in `package.json`, `package-lock.json` and `python/plotto/__init__.py`, and builds the site in `docs/`;
-   - commits "release 0.3.0", pushes the branch and opens the pull request page.
-2. Create the pull request, then have it reviewed and merged.
-3. Tag the merged `main`:
+# 3. Publish
+scripts/release.sh tag    # answer y
 
-   ```
-   scripts/release.sh tag
-   ```
+# 4. Check
+npm view plotto version && pip index versions python-plotto
+```
 
-   The script pulls `main` and reads the version. It asks before it tags and pushes `v0.3.0`, then deletes the release branch.
-4. The pushed tag starts the release in the Actions tab. The packages are then at pypi.org/project/python-plotto and npmjs.com/package/plotto.
+- `scripts/release.sh X.Y.Z` checks that `main` is current and the version is new. It runs every test and lint. Then, on the branch `release/vX.Y.Z`, it sets the version in `package.json`, `package-lock.json` and `python/plotto/__init__.py`, builds `docs/`, commits and pushes.
+- `scripts/release.sh tag` tags the merged `main` as `vX.Y.Z`, asks before it pushes the tag, and deletes the release branch.
+- The pushed tag runs `.github/workflows/release.yml`, which publishes to PyPI and npm. Follow it in the Actions tab.
 
 To upgrade Observable Plot or d3:
 

package/grammar.json

@@ -46,7 +46,7 @@
   "grid": ["free"],
   "free": ["x", "y", "both"],
   "labels": ["title", "subtitle", "x", "y", "color", "caption"],
-  "theme": ["format", "width", "height", "size", "legend"],
+  "theme": ["format", "width", "height", "size", "legend", "aspect"],
   "legend": ["right", "bottom", "none"],
   "info": ["position"],
   "infoPosition": ["right", "bottom"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plotto",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Grammar-of-graphics plots for notebooks, web pages and slides with one renderer.",
   "license": "MIT",
   "homepage": "https://theoradusz.github.io/plotto/",

package/src/builder.js

@@ -122,6 +122,7 @@ class Builder {
     if (!(style in THEMES.styles)) fail("theme()", "style", style, Object.keys(THEMES.styles));
     if (options.format !== undefined && !(options.format in THEMES.formats)) fail("theme()", "format", options.format, Object.keys(THEMES.formats));
     if (options.legend !== undefined && !GRAMMAR.legend.includes(options.legend)) fail("theme()", "legend", options.legend, GRAMMAR.legend);
+    if (options.aspect != null && !(typeof options.aspect === "number" && options.aspect > 0)) throw new Error("theme(): aspect must be a positive number (panel height / width), for example 1 for square panels");
     return this.#with({ theme: { style, ...options } });
   }
 

package/src/copy.js

@@ -3,10 +3,17 @@
 const SCALE = 2; // PNG px per figure px
 
 // Copies a PNG to the clipboard; if the browser refuses, downloads it. Returns "Copied" or "Downloaded".
-export async function copyPNG(svg) {
-  const png = rasterize(svg);
+// size: the display size in px of the pasted image. The PNG then has scale times these pixels, and an HTML <img>
+// with this size goes along: Google Slides pastes the HTML at that size (96 px per inch) and keeps the sharp PNG.
+export async function copyPNG(svg, size, scale = SCALE) {
+  const png = rasterize(svg, size ? (scale * size.width) / svg.viewBox.baseVal.width : scale);
+  const items = { "image/png": png.then(toBlob) };
+  if (size) {
+    const img = (c) => `<img src="${c.toDataURL("image/png")}" width="${size.width}" height="${size.height}">`;
+    items["text/html"] = png.then((c) => new Blob([img(c)], { type: "text/html" }));
+  }
   try {
-    await navigator.clipboard.write([new ClipboardItem({ "image/png": png.then(toBlob) })]);
+    await navigator.clipboard.write([new ClipboardItem(items)]);
     return "Copied";
   } catch {
     save((await png).toDataURL("image/png"), "plot.png");
@@ -22,14 +29,14 @@ export function downloadSVG(svg) {
   save(dataURL(svg), "plot.svg");
 }
 
-async function rasterize(svg) {
+async function rasterize(svg, scale = SCALE) {
   const img = new Image();
   img.src = dataURL(svg);
   await img.decode();
   const { width, height } = svg.viewBox.baseVal;
   const canvas = document.createElement("canvas");
-  canvas.width = width * SCALE;
-  canvas.height = height * SCALE;
+  canvas.width = Math.round(width * scale);
+  canvas.height = Math.round(height * scale);
   canvas.getContext("2d").drawImage(img, 0, 0, canvas.width, canvas.height);
   return canvas;
 }

package/src/figure.js

@@ -6,7 +6,7 @@ import { facetPanels } from "./facets.js";
 import { drawInfo, infoModel } from "./info.js";
 import { LAYERS } from "./layers.js";
 import { drawLegend, legendModel } from "./legend.js";
-import { place, TICK } from "./layout.js";
+import { LINE, place, TICK } from "./layout.js";
 import { AXIS_CHANNELS, axisKind, colorScale, ticks, trainDomain } from "./scales.js";
 import { normalize } from "./spec.js";
 import { svgElement, svgText } from "./svg.js";
@@ -15,6 +15,7 @@ import { layerEdges, makeView } from "./views.js";
 
 const NARROW = 560; // px: below this width, a right legend moves to the bottom
 const MIN_HEIGHT = 240; // px: the smallest height of a reflowed figure
+const ASPECT_GROWTH = 1.2; // a theme aspect makes a reflowed figure at most this much taller
 
 // options: document (the browser or jsdom), width (lay out at this width), domains and hidden (keep a view after a resize).
 export function figure(spec, { document: doc = globalThis.document, width, domains, hidden = new Set() } = {}) {
@@ -22,7 +23,7 @@ export function figure(spec, { document: doc = globalThis.document, width, domai
   const theme = ns.theme;
   const W = Math.round(width ?? theme.width);
   const reflowed = width && theme.reflow && !theme.fixedHeight;
-  const H = reflowed ? Math.max(MIN_HEIGHT, Math.round((W * theme.height) / theme.width)) : theme.height;
+  let H = reflowed ? Math.max(MIN_HEIGHT, Math.round((W * theme.height) / theme.width)) : theme.height;
   if (theme.legend === "right" && W < NARROW) theme.legend = "bottom";
   const fonts = fontSizes(theme);
   const grid = facetPanels(ns);
@@ -32,10 +33,20 @@ export function figure(spec, { document: doc = globalThis.document, width, domai
   for (const p of grid.panels) p.views = ns.layers.map((layer, li) => makeView(ctx, layer, p.rows[li], new Set()));
   const home = homeDomains(ns, grid, kind);
   const horizontal = theme.legend === "bottom";
-  const info = infoModel(ns, fonts, { W, H, narrow: W < NARROW });
-  const above = info?.position === "right" ? info.height + fonts.base : 0; // the info card sits above a right legend
-  const legend = legendModel(ns, color, fonts, { horizontal, maxWidth: W * 0.9, maxHeight: H * 0.8 - above });
-  const layout = place({ ns, grid, kind, home, legend, info, fonts, W, H });
+  const arrange = (H) => {
+    const info = infoModel(ns, fonts, { W, H, narrow: W < NARROW });
+    const above = info?.position === "right" ? info.height + fonts.base : 0; // the info card sits above a right legend
+    const legend = legendModel(ns, color, fonts, { horizontal, maxWidth: W * 0.9, maxHeight: H * 0.8 - above });
+    return { info, legend, layout: place({ ns, grid, kind, home, legend, info, fonts, W, H }) };
+  };
+  let { info, legend, layout } = arrange(H);
+  // aspect: when the height follows the width, it changes so that the panels get their shape, up to 1.2 times the
+  // usual height; beyond that, the panels get narrower.
+  if (theme.aspect && theme.fitHeight) {
+    const fit = H + grid.nrow * (layout.room.w * theme.aspect - layout.room.h);
+    H = Math.round(Math.min(H * ASPECT_GROWTH, Math.max(MIN_HEIGHT, fit)));
+    ({ info, legend, layout } = arrange(H));
+  }
 
   const svg = svgElement(doc, "svg", {
     xmlns: "http://www.w3.org/2000/svg",
@@ -106,7 +117,9 @@ function drawPanel(state, p, i) {
   marks.push(...layers.flatMap((l) => l.marks));
   if (box.showX) {
     const rotate = box.rotateX ? { tickRotate: -40, textAnchor: "end" } : {};
-    marks.push(Plot.axisX(ax.major, { ...axisStyle, ...rotate, anchor: "bottom", tickFormat: ax.format }));
+    const wrapped = (v) => box.wrapX.get(String(v))?.join("\n") ?? ax.format(v);
+    const wrap = box.wrapX.size ? { tickFormat: wrapped, lineHeight: LINE } : { tickFormat: ax.format };
+    marks.push(Plot.axisX(ax.major, { ...axisStyle, ...rotate, anchor: "bottom", ...wrap }));
   }
   if (box.showY) marks.push(Plot.axisY(ay.major, { ...axisStyle, anchor: "left", tickFormat: ay.format }));
   const plot = Plot.plot({

package/src/hover.js

@@ -5,6 +5,7 @@
 // - points (and error bars): the nearest point. It stays picked until another point is clearly nearer.
 import * as d3 from "d3";
 import { hoverFormat } from "./scales.js";
+import { boxStats } from "./stats.js";
 
 const RADIUS = 40; // px: the largest distance to a point or a line
 const CLOSE = 10; // px: a point this close wins over the lines
@@ -242,12 +243,7 @@ function boxUnder({ state, sx }, layer, view, c, x) {
   });
   if (k === undefined) return null;
   const key = String(view.cols.x[k]);
-  const values = d3.range(view.n).filter((j) => String(view.cols.x[j]) === key).map((j) => view.cols.y[j]).filter((v) => v !== null).sort(d3.ascending);
-  const [q1, median, q3] = [0.25, 0.5, 0.75].map((p) => d3.quantile(values, p));
-  const iqr = q3 - q1;
-  const low = d3.min(values.filter((v) => v >= q1 - 1.5 * iqr));
-  const high = d3.max(values.filter((v) => v <= q3 + 1.5 * iqr));
-  const outliers = values.filter((v) => v < low || v > high).length;
+  const { n, q1, median, q3, low, high, outliers } = boxStats(d3.range(view.n).filter((j) => String(view.cols.x[j]) === key).map((j) => view.cols.y[j]));
   const f = (v) => fmt(state, "y", v);
   const rows = [
     { label: "max (whisker)", value: f(high) },
@@ -255,9 +251,9 @@ function boxUnder({ state, sx }, layer, view, c, x) {
     { label: "median", value: f(median), strong: true },
     { label: "q1", value: f(q1) },
     { label: "min (whisker)", value: f(low) },
-    { label: "n", value: String(values.length) },
+    { label: "n", value: String(n) },
   ];
-  if (outliers) rows.push({ label: "outliers", value: String(outliers) });
+  if (outliers.length) rows.push({ label: "outliers", value: String(outliers.length) });
   const x0 = sx.apply(view.cols.x[k]);
   const color = layer.channels.color?.column ? seriesColor(state, layer, view, c, k) : state.theme.ink;
   return { color, header: `${view.hover.fields[0].label}  ${key}`, rows, marks: [], anchor: { x: x0 + sx.bandwidth, y: null } };

package/src/interact.js

@@ -12,6 +12,18 @@ const DRAG_MIN = 5; // px: a smaller drag is a click
 const MIN_WIDTH = 320; // px
 const ZOOM_STEP = 0.75; // zoom in keeps 75% of the range
 const DOUBLE = 300; // ms: two legend clicks within this time are a double-click
+// The pasted size of "Copy for a slide", at 96 px per inch: 6.72 × 4.2 in, 75% of the height of a 16:9 Google slide.
+export const SLIDE_SIZE = { width: 645, height: 403 };
+// PNG px per pasted px: 288 px per inch, and 1935 px wide, under the ~2000 px above which Slides may compress images.
+const SLIDE_SCALE = 3;
+
+// The current view (zoom and hidden series) drawn again in the slide format, for "Copy for a slide".
+export function slideFigure(spec, state) {
+  const s = typeof spec?.spec === "function" ? spec.spec() : spec;
+  const theme = { ...s.theme, format: "slide", width: null, height: null, size: null };
+  const domains = state.domains === state.home ? undefined : state.domains;
+  return figure({ ...s, theme }, { document: state.doc, domains, hidden: state.hidden });
+}
 
 // Returns a controller: { state (the current figure), redraw(), destroy() }.
 export function draw(spec, el, { interactive = false, width } = {}) {
@@ -42,6 +54,7 @@ export function draw(spec, el, { interactive = false, width } = {}) {
   const groups = [
     [
       { name: "copy", title: "Copy as PNG", action: (b) => copyPNG(ctl.state.svg).then((how) => bar.flash("copy", how)) },
+      { name: "slide", title: "Copy for a slide", action: () => copyPNG(slideFigure(spec, ctl.state).svg, SLIDE_SIZE, SLIDE_SCALE).then((how) => bar.flash("slide", how)) },
       { name: "download", title: "Download", menu: [["PNG", () => downloadPNG(ctl.state.svg)], ["SVG", () => downloadSVG(ctl.state.svg)]] },
     ],
   ];

package/src/layers.js

@@ -3,6 +3,7 @@
 // To add a layer type: add one entry here, one entry in grammar.json and, for a statistic, a case in views.js.
 import * as Plot from "@observablehq/plot";
 import * as d3 from "d3";
+import { boxStats } from "./stats.js";
 
 const DASH = { solid: undefined, dashed: "6,4", dotted: "1.5,3", dashdot: "6,3,1.5,3" };
 const clip = "frame";
@@ -121,9 +122,28 @@ export const LAYERS = {
     return [rule, cap("ymin"), cap("ymax")];
   },
 
-  box: (c) => [
-    Plot.boxY(c.index, { x: c.v("x"), y: c.v("y"), fill: c.colors(c.theme.strip), fillOpacity: c.options.alpha ?? 1, stroke: c.theme.ink, strokeWidth: 1, r: c.theme.point, clip }),
-  ],
+  // One Tukey box per category, in the series color: a light box from q1 to q3, a bold median, whiskers with caps,
+  // and the outliers as small dots (they blend with jittered points drawn on top).
+  box: (c) => {
+    const [x, y, colors] = [c.v("x"), c.v("y"), c.colors(c.theme.muted)]; // gray without a color mapping
+    const boxes = [];
+    for (const [key, rows] of d3.group(c.index, (i) => x[i])) {
+      const stats = boxStats(rows.map((i) => y[i]));
+      if (stats.n) boxes.push({ key, color: Array.isArray(colors) ? colors[rows[0]] : colors, ...stats });
+    }
+    const outliers = boxes.flatMap((b) => b.outliers.map((v) => ({ key: b.key, v, color: b.color })));
+    const inset = (share) => ({ insetLeft: c.bandwidth.x * share, insetRight: c.bandwidth.x * share });
+    const line = { x: "key", stroke: "color", strokeWidth: 1.25, clip };
+    return [
+      Plot.ruleX(boxes, { ...line, y1: "q3", y2: "high" }),
+      Plot.ruleX(boxes, { ...line, y1: "low", y2: "q1" }),
+      Plot.tickY(boxes, { ...line, y: "high", ...inset(0.38) }),
+      Plot.tickY(boxes, { ...line, y: "low", ...inset(0.38) }),
+      Plot.barY(boxes, { ...line, y1: "q1", y2: "q3", fill: "color", fillOpacity: c.options.alpha ?? 0.3, ...inset(0.22) }),
+      Plot.tickY(boxes, { x: "key", y: "median", stroke: c.theme.ink, strokeWidth: 2.25, ...inset(0.22), clip }),
+      Plot.dot(outliers, { x: "key", y: "v", fill: "color", r: c.theme.point, clip }),
+    ];
+  },
 };
 
 // Overlaid fills are see-through, stacked fills are solid.

package/src/layout.js

@@ -6,6 +6,8 @@ import { fitText, textWidth, wrapText } from "./text.js";
 
 export const TICK = { size: 4, padding: 3 };
 const ROTATE = 40; // degrees of rotated category labels
+const WRAP_LINES = 3; // a category label wider than its band wraps to this many lines, before any rotation
+export const LINE = 1.15; // line height of wrapped category labels, in em
 const TOOLBAR = 0.22; // share of the width kept free of the title, for the toolbar
 
 export function place({ ns, grid, kind, home, legend, info, fonts, W, H }) {
@@ -43,38 +45,83 @@ export function place({ ns, grid, kind, home, legend, info, fonts, W, H }) {
   // Two passes: the tick count depends on the panel size, and the margins depend on the tick labels.
   let innerW = area.w / grid.ncol;
   let innerH = area.h / grid.nrow;
-  let ml, mb, count, rotateX;
+  let ml, mb, mt, count, rotateX, wrapX;
   for (let pass = 0; pass < 2; pass++) {
     count = { x: Math.max(2, innerW / (kind.x === "time" ? 110 : 75)), y: Math.max(2, innerH / 45) };
     ml = Array(grid.ncol).fill(0);
     mb = Array(grid.nrow).fill(0);
     rotateX = false;
+    wrapX = new Map();
+    mt = 0;
     let xLabelW = 0;
     grid.panels.forEach((p, i) => {
       if (showY(p)) {
         const t = ticks(kind.y, home[i].y, count.y, ns.scales.y?.format);
         const w = d3.max(t.major, (v) => tw(t.format(v), fonts.tick)) ?? 0;
         ml[p.col] = Math.max(ml[p.col], Math.ceil(w + TICK.size + TICK.padding + 3));
+        // A tick at the top edge has half its label above the panel: move the panels down to keep it off the subtitle.
+        if (p.row === 0 && !wrapStrip && !topStrip && kind.y !== "category") {
+          const [lo, hi] = home[i].y;
+          const y = (kind.y === "log" ? d3.scaleLog() : d3.scaleLinear()).domain([lo, hi]).range([innerH, 0]);
+          const top = d3.max(t.major.filter((v) => +v >= +lo && +v <= +hi));
+          if (top !== undefined) mt = Math.max(mt, Math.ceil(fonts.tick * 0.6 - y(top)));
+        }
       }
       if (kind.x === "category" && showX(p, i)) {
         const labels = home[i].x;
-        const w = d3.max(labels, (v) => tw(v, fonts.tick)) ?? 0;
-        xLabelW = Math.max(xLabelW, w);
-        if (w > (innerW / (labels.length + 0.2)) * 0.95) rotateX = true;
+        const room = (innerW / (labels.length + 0.2)) * 0.95;
+        for (const v of labels) {
+          const w = tw(v, fonts.tick);
+          xLabelW = Math.max(xLabelW, w);
+          if (w <= room) continue;
+          // Wrap at spaces first; a word that is still too wide, or a label that needs more lines, rotates them all.
+          const lines = wrapText(v, fonts.tick, room, false, metrics, WRAP_LINES);
+          if (lines.at(-1).endsWith("…") || d3.max(lines, (l) => tw(l, fonts.tick)) > room) rotateX = true;
+          else wrapX.set(String(v), lines);
+        }
       }
     });
-    const xLabelH = rotateX ? Math.min(xLabelW, innerH * 0.6) * Math.sin((ROTATE * Math.PI) / 180) + fonts.tick : fonts.tick * 1.2;
+    // Rotated labels get 60% of the panel height (at least 10 em); a longer one ends with an ellipsis.
+    const rotated = Math.min(xLabelW, Math.max(innerH * 0.6, fonts.tick * 10));
+    if (rotateX) {
+      wrapX.clear();
+      grid.panels.forEach((p, i) => {
+        if (kind.x !== "category" || !showX(p, i)) return;
+        for (const v of home[i].x) if (tw(v, fonts.tick) > rotated) wrapX.set(String(v), [fitText(v, fonts.tick, rotated, false, metrics)]);
+      });
+    }
+    const xLines = rotateX ? 1 : (d3.max(wrapX.values(), (l) => l.length) ?? 1);
+    const xLabelH = rotateX ? rotated * Math.sin((ROTATE * Math.PI) / 180) + fonts.tick : fonts.tick * (1.2 + LINE * (xLines - 1));
+    // A rotated label reaches left of its tick: widen the left margin so that the first one is not cut off.
+    if (rotateX) {
+      grid.panels.forEach((p, i) => {
+        if (p.col !== 0 || !showX(p, i)) return;
+        const step = innerW / (home[i].x.length + 0.2);
+        const first = Math.min(tw(home[i].x[0], fonts.tick), rotated);
+        const reach = first * Math.cos((ROTATE * Math.PI) / 180) + fonts.tick * 0.5;
+        ml[0] = Math.max(ml[0], Math.ceil(reach - 0.6 * step));
+      });
+    }
     grid.panels.forEach((p, i) => {
       if (showX(p, i)) mb[p.row] = Math.max(mb[p.row], Math.ceil(xLabelH + TICK.size + TICK.padding + 3));
     });
     innerW = (area.w - d3.sum(ml) - gap * (grid.ncol - 1) - rightStrip) / grid.ncol;
-    innerH = (area.h - d3.sum(mb) - grid.nrow * wrapStrip - topStrip - gap * (grid.nrow - 1)) / grid.nrow;
+    innerH = (area.h - mt - d3.sum(mb) - grid.nrow * wrapStrip - topStrip - gap * (grid.nrow - 1)) / grid.nrow;
   }
   innerW = Math.max(20, innerW);
   innerH = Math.max(20, innerH);
+  // theme aspect (panel height / width): the panels shrink in one direction to get that shape.
+  const room = { w: innerW, h: innerH }; // the panel size before the aspect
+  if (theme.aspect) {
+    if (innerH > innerW * theme.aspect) innerH = innerW * theme.aspect;
+    else innerW = innerH / theme.aspect;
+  }
+  // The space the aspect leaves free goes half on each side, so the panels stay centered.
+  const slackY = ((room.h - innerH) * grid.nrow) / 2;
+  const slackX = ((room.w - innerW) * grid.ncol) / 2;
 
-  const colX = d3.cumsum([area.x, ...ml.slice(0, -1).map((m) => m + innerW + gap)]);
-  const rowY = d3.cumsum([area.y + topStrip, ...mb.slice(0, -1).map((m) => wrapStrip + innerH + m + gap)]);
+  const colX = d3.cumsum([area.x + slackX, ...ml.slice(0, -1).map((m) => m + innerW + gap)]);
+  const rowY = d3.cumsum([area.y + mt + topStrip + slackY, ...mb.slice(0, -1).map((m) => wrapStrip + innerH + m + gap)]);
   const panels = grid.panels.map((p, i) => ({
     x: colX[p.col],
     y: rowY[p.row] + wrapStrip,
@@ -86,6 +133,7 @@ export function place({ ns, grid, kind, home, legend, info, fonts, W, H }) {
     innerH,
     count,
     rotateX,
+    wrapX,
     showX: showX(p, i),
     showY: showY(p),
   }));
@@ -103,7 +151,7 @@ export function place({ ns, grid, kind, home, legend, info, fonts, W, H }) {
   const lastCol = panels.find((b, i) => grid.panels[i].col === grid.ncol - 1) ?? first;
   const innerLeft = first.x + first.ml;
   const innerRight = lastCol.x + lastCol.w;
-  const panelsBottom = area.y + area.h;
+  const panelsBottom = d3.max(panels, (b) => b.y + b.h);
   const texts = [];
   let y = pad;
   for (const line of titleLines) texts.push({ text: line, attrs: { x: innerLeft, y: (y += fonts.title * 1.05), "font-size": fonts.title, "font-weight": "bold", fill: theme.ink, "text-anchor": "start" } }), (y += fonts.title * 0.2);
@@ -111,10 +159,12 @@ export function place({ ns, grid, kind, home, legend, info, fonts, W, H }) {
   if (xTitle) texts.push({ text: xTitle, attrs: { x: (innerLeft + innerRight) / 2, y: panelsBottom + fonts.axisTitle * 1.35, "text-anchor": "middle", "font-size": fonts.axisTitle, fill: theme.muted } });
   if (yTitle) {
     const cy = area.y + (area.h - d3.sum(mb)) / 2;
-    texts.push({ text: yTitle, attrs: { transform: `translate(${pad + fonts.axisTitle * 0.85},${cy}) rotate(-90)`, "text-anchor": "middle", "font-size": fonts.axisTitle, fill: theme.muted } });
+    texts.push({ text: yTitle, attrs: { transform: `translate(${pad + slackX + fonts.axisTitle * 0.85},${cy}) rotate(-90)`, "text-anchor": "middle", "font-size": fonts.axisTitle, fill: theme.muted } });
   }
   if (caption) texts.push({ text: fitText(caption, fonts.tick, W - 2 * pad, false, metrics), attrs: { x: innerLeft, y: H - pad - (bottom ? bottom : 0) + fonts.tick * 0.2, "font-size": fonts.tick, fill: theme.muted, "text-anchor": "start" } });
-  const rightX = W - pad - rightW;
+  // The right column is at the right edge, or next to the panels when the aspect makes them narrower.
+  const beside = innerRight + rightStrip + s * 1.5;
+  const rightX = beside < W - pad - rightW - 1 ? beside : W - pad - rightW;
   const infoAt = !info
     ? null
     : info.position === "right"
@@ -126,5 +176,5 @@ export function place({ ns, grid, kind, home, legend, info, fonts, W, H }) {
     : legend.horizontal
       ? { x: Math.max(pad, (innerLeft + innerRight - legend.width) / 2), y: H - pad - legend.height }
       : { x: rightX, y: area.y + above + Math.max(0, (area.h - d3.sum(mb) - above - legend.height) / 2) };
-  return { panels, strips, texts, legend: legendAt, info: infoAt, area, rotateX };
+  return { panels, strips, texts, legend: legendAt, info: infoAt, area, room, rotateX };
 }

package/src/legend.js

@@ -2,11 +2,13 @@
 import * as d3 from "d3";
 import { ticks } from "./scales.js";
 import { svgElement, svgText } from "./svg.js";
-import { fitText, textWidth } from "./text.js";
+import { fitText, textWidth, wrapText } from "./text.js";
 
 const KEY = 18; // swatch width, px
 const GAP = 6;
 const RAMP = { thick: 12, long: 150, slices: 48 };
+const LABEL_LINES = 3; // a long label of a right legend wraps to this many lines
+const LINE = 1.25; // line height of wrapped labels, in em
 const LINE_LAYERS = ["line", "path", "step", "density", "smooth", "hline", "vline", "abline", "segment", "errorbar"];
 const FILL_LAYERS = ["bar", "hist", "area", "ribbon", "rect", "tile", "box"];
 
@@ -31,22 +33,33 @@ export function legendModel(ns, color, fonts, { horizontal, maxWidth, maxHeight
   const mapped = ns.layers.filter((l) => l.channels.color?.column);
   const key = mapped.some((l) => FILL_LAYERS.includes(l.type)) ? "square" : mapped.some((l) => LINE_LAYERS.includes(l.type)) ? "line" : "point";
   const rowH = Math.round(fonts.legend * 1.75);
-  const maxLabel = Math.max(80, (horizontal ? maxWidth : 220) - KEY - GAP);
+  const lineH = fonts.legend * LINE;
+  // A right legend keeps a narrow column: its long labels wrap. A bottom legend has one line per label.
+  const maxLabel = horizontal ? Math.max(80, maxWidth - KEY - GAP) : Math.max(110, Math.min(200, maxWidth * 0.2));
   const items = color.domain.map((value) => {
-    const label = fitText(value, fonts.legend, maxLabel, false, metrics);
-    return { value, label, color: color.apply(value), w: KEY + GAP + width(label, fonts.legend) };
+    const lines = horizontal ? [fitText(value, fonts.legend, maxLabel, false, metrics)] : wrapText(value, fonts.legend, maxLabel, false, metrics, LABEL_LINES);
+    const w = KEY + GAP + (d3.max(lines, (l) => width(l, fonts.legend)) ?? 0);
+    return { value, label: lines.join(" "), lines, color: color.apply(value), w, h: rowH + (lines.length - 1) * lineH };
   });
   if (!horizontal) {
     // Columns of rows, so that a long legend fits the panel height.
-    const perColumn = Math.max(1, Math.floor((maxHeight - titleH) / rowH));
-    const columns = d3.range(Math.ceil(items.length / perColumn)).map((k) => items.slice(k * perColumn, (k + 1) * perColumn));
+    const columns = [[]];
+    let y = titleH;
+    for (const it of items) {
+      if (y + it.h > maxHeight && columns.at(-1).length) {
+        columns.push([]);
+        y = titleH;
+      }
+      columns.at(-1).push(Object.assign(it, { y }));
+      y += it.h;
+    }
     let x = 0;
     for (const column of columns) {
-      column.forEach((it, i) => Object.assign(it, { x, y: titleH + i * rowH }));
+      for (const it of column) it.x = x;
       x += (d3.max(column, (it) => it.w) ?? 0) + fonts.legend;
     }
-    const rows = Math.min(items.length, perColumn);
-    return { kind: "swatches", title, titleH, key, rowH, items, width: Math.max(titleW, x - fonts.legend), height: titleH + rows * rowH, horizontal };
+    const height = d3.max(columns, (column) => column.at(-1).y + column.at(-1).h) ?? titleH;
+    return { kind: "swatches", title, titleH, key, rowH, lineH, items, width: Math.max(titleW, x - fonts.legend), height, horizontal };
   }
   let x = 0;
   let y = titleH;
@@ -56,7 +69,7 @@ export function legendModel(ns, color, fonts, { horizontal, maxWidth, maxHeight
     x += it.w + fonts.legend * 1.5;
   }
   const w = Math.max(titleW, d3.max(items, (it) => it.x + it.w) ?? 0);
-  return { kind: "swatches", title, titleH, key, rowH, items, width: w, height: y + rowH, horizontal };
+  return { kind: "swatches", title, titleH, key, rowH, lineH, items, width: w, height: y + rowH, horizontal };
 }
 
 export function drawLegend(doc, model, theme, fonts, hidden = new Set()) {
@@ -70,14 +83,16 @@ export function drawLegend(doc, model, theme, fonts, hidden = new Set()) {
 function swatch(doc, model, it, i, theme, off) {
   const mid = model.rowH / 2;
   const g = svgElement(doc, "g", { class: "pt-key", "data-index": i, transform: `translate(${it.x},${it.y})`, opacity: off ? 0.35 : 1 });
-  const hit = svgElement(doc, "rect", { width: it.w, height: model.rowH, fill: "transparent" });
+  const hit = svgElement(doc, "rect", { width: it.w, height: it.h, fill: "transparent" });
   const mark =
     model.key === "line"
       ? svgElement(doc, "line", { x1: 1, x2: KEY - 1, y1: mid, y2: mid, stroke: it.color, "stroke-width": Math.max(2.5, theme.line + 1) })
       : model.key === "point"
         ? svgElement(doc, "circle", { cx: KEY / 2, cy: mid, r: Math.max(3.5, theme.point + 1), fill: it.color })
         : svgElement(doc, "rect", { x: 3, y: mid - 6, width: 12, height: 12, fill: it.color });
-  const label = svgText(doc, it.label, { x: KEY + GAP, y: mid, dy: "0.35em", fill: theme.muted, "text-decoration": off ? "line-through" : null });
+  const label = svgElement(doc, "text", { x: KEY + GAP, y: mid, dy: "0.35em", fill: theme.muted, "text-decoration": off ? "line-through" : null });
+  it.lines.forEach((line, k) => label.append(k ? svgText(doc, line, { x: KEY + GAP, dy: model.lineH }, "tspan") : doc.createTextNode(line)));
+  if (it.lines.at(-1).endsWith("…")) label.append(svgText(doc, it.value, {}, "title"));
   g.append(hit, mark, label);
   return g;
 }

package/src/stats.js

@@ -102,6 +102,16 @@ export function bin(cols, n, edges, density) {
   return out;
 }
 
+// Tukey box of one group: quartiles, whiskers at the last values within 1.5 IQR of the box, and the outliers.
+export function boxStats(values) {
+  const v = values.filter((y) => y !== null && Number.isFinite(y)).sort(d3.ascending);
+  const [q1, median, q3] = [0.25, 0.5, 0.75].map((p) => d3.quantile(v, p));
+  const iqr = q3 - q1;
+  const low = d3.min(v.filter((y) => y >= q1 - 1.5 * iqr));
+  const high = d3.max(v.filter((y) => y <= q3 + 1.5 * iqr));
+  return { n: v.length, q1, median, q3, low, high, outliers: v.filter((y) => y < low || y > high) };
+}
+
 // Gaussian kernel density per color, with the Silverman bandwidth, on a grid that covers the data ± 3 bandwidths.
 export function density(cols, n) {
   const out = { x: [], y: [], color: [], group: [] };

package/src/theme.js

@@ -26,6 +26,7 @@ export function resolveTheme({ style = "pastel", format = "screen", legend = "ri
   // A set height alone keeps the reflow of the width and fixes the height.
   if (overrides.width != null && overrides.height == null) theme.height = Math.round((overrides.width * f.height) / f.width);
   theme.fixedHeight = overrides.height != null;
+  theme.fitHeight = f.reflow && !theme.fixedHeight; // a screen plot: its height may follow the panel aspect
   theme.palette = palette(theme, theme.palette);
   return theme;
 }

package/src/toolbar.js

@@ -10,6 +10,7 @@ const ICONS = {
   zoomOut: '<path d="M5 12h14"/>',
   home: '<path d="M4 11l8-7 8 7M6 9.5V20h12V9.5"/>',
   copy: '<rect x="8.5" y="8.5" width="11" height="11"/><path d="M15.5 8.5V4.5h-11v11h4"/>',
+  slide: '<rect x="3.5" y="4.5" width="17" height="11"/><path d="M12 15.5v4M8 19.5h8M7 12.5l3-3 2.5 2 4.5-4"/>',
   download: '<path d="M12 4v11M7.5 10.5L12 15l4.5-4.5M5 19.5h14"/>',
   check: '<path d="M5 12.5l4.5 4.5L19 7.5"/>',
 };

package/theme.json

@@ -139,9 +139,9 @@
       "reflow": false
     },
     "slide": {
-      "width": 1280,
-      "height": 720,
-      "size": 20,
+      "width": 960,
+      "height": 600,
+      "size": 22,
       "line": 2.5,
       "point": 4,
       "reflow": false