plotto 0.4.0 → 0.5.0

package/README.md

@@ -197,7 +197,8 @@ One-time setup:
 Each release (`main` takes changes only through a reviewed pull request):
 
 ```bash
-# 1. Merge your changes into main through a pull request
+# 1. Merge your changes into main through a pull request,
+#    with a line for each change under "## Unreleased" in CHANGELOG.md
 
 # 2. Prepare the release
 git switch main && git pull && source .venv/bin/activate
@@ -211,7 +212,7 @@ scripts/release.sh tag    # answer y
 npm view plotto version && pip index versions python-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 X.Y.Z` checks that `main` is current, that the version is new and that `CHANGELOG.md` has changes under "Unreleased". 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`, moves the "Unreleased" changes to a dated `X.Y.Z` section, 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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plotto",
-  "version": "0.4.0",
+  "version": "0.5.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

@@ -109,12 +109,12 @@ class Builder {
   // A key/value table about the data or the experiment: info({ location: "hayama" }, { position: "right" }). null removes it.
   info(entries, options = {}) {
     checkKeys(options, GRAMMAR.info, "info()");
-    const position = options.position ?? "right";
-    if (!GRAMMAR.infoPosition.includes(position)) fail("info()", "position", position, GRAMMAR.infoPosition);
+    const { position } = options;
+    if (position !== undefined && !GRAMMAR.infoPosition.includes(position)) fail("info()", "position", position, GRAMMAR.infoPosition);
     if (entries === null || entries === undefined) return this.#with({ info: null });
     const pairs = Array.isArray(entries) ? entries : typeof entries === "object" ? Object.entries(entries) : null;
     if (!pairs) throw new Error("info(): entries must be an object or a list of [key, value] pairs");
-    return this.#with({ info: { entries: pairs.map((pair) => infoEntry(pair)), position } });
+    return this.#with({ info: { entries: pairs.map((pair) => infoEntry(pair)), ...(position ? { position } : {}) } });
   }
 
   theme(style = "pastel", options = {}) {

package/src/figure.js

@@ -16,6 +16,8 @@ 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
+const SHRINK_STEP = 0.05; // a format with "shrink" tries the legend and info text smaller by this share at each step
+const ROOM_TOLERANCE = 0.1; // it keeps the largest text whose panel area is at most this share below the best layout
 
 // 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() } = {}) {
@@ -25,27 +27,52 @@ export function figure(spec, { document: doc = globalThis.document, width, domai
   const reflowed = width && theme.reflow && !theme.fixedHeight;
   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);
   const kind = { x: axisKind(ns, "x"), y: axisKind(ns, "y") };
   const color = colorScale(ns);
   const ctx = { ns, kind, colorLevels: color.domain ?? [], edges: layerEdges(ns) };
   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 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 }) };
+  // One layout: the place of the legend and of the info card (right or bottom), and their text size (share k).
+  // cut counts what does not show well: legend labels and info keys with an ellipsis, a second legend column,
+  // the "+N more" entries of the info card.
+  const arrange = (H, where, k) => {
+    const base = fontSizes(theme);
+    const f = { ...base, legend: Math.round(base.legend * k * 10) / 10 };
+    const info = infoModel(ns, f, { W, H, narrow: W < NARROW, place: where.info });
+    const above = info?.position === "right" ? info.height + f.base : 0; // the info card sits above a right legend
+    const legend = legendModel(ns, color, f, { horizontal: where.legend === "bottom", maxWidth: W * 0.9, maxHeight: H * 0.8 - above });
+    const layout = place({ ns, grid, kind, home, legend, info, fonts: f, W, H });
+    const items = legend?.items ?? [];
+    const cut = items.filter((it) => it.lines.at(-1).endsWith("…")).length + (items.some((it) => !legend.horizontal && it.x > 0) ? 1 : 0) + (info?.cut ?? 0);
+    const p = layout.panels[0];
+    const usual = where.legend === theme.legend && where.info === ns.info?.position; // the places of the theme and spec
+    return { fonts: f, info, legend, layout, k, cut, usual, area: p.innerW * p.innerH };
   };
-  let { info, legend, layout } = arrange(H);
+  // The layout to draw. A screen plot keeps the places of the theme and the text size. A fixed size (slide, report,
+  // a set height) also tries the legend and the info card on the right and at the bottom, unless the spec sets
+  // their place; a format with "shrink" (slide) also tries smaller text, down to that share. Of the layouts that cut
+  // the least and whose panel area is at most ROOM_TOLERANCE below the best, it keeps the largest text, then the
+  // usual places, then the largest area.
+  const choose = (H) => {
+    const fixed = !theme.fitHeight;
+    const legends = fixed && !theme.legendSet && theme.legend === "right" ? ["right", "bottom"] : [theme.legend];
+    const infos = fixed && ns.info && !ns.info.set ? ["right", "bottom"] : [ns.info?.position];
+    const scales = [];
+    for (let k = 1; k >= (theme.shrink ?? 1) - 1e-9; k -= SHRINK_STEP) scales.push(k);
+    const all = legends.flatMap((l) => infos.flatMap((i) => scales.map((k) => arrange(H, { legend: l, info: i }, k))));
+    const fewest = d3.min(all, (a) => a.cut);
+    const pool = all.filter((a) => a.cut === fewest);
+    const best = d3.max(pool, (a) => a.area);
+    return pool.filter((a) => a.area >= best * (1 - ROOM_TOLERANCE)).sort((a, b) => b.k - a.k || b.usual - a.usual || b.area - a.area)[0];
+  };
+  let { fonts, info, legend, layout } = choose(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));
+    ({ fonts, info, legend, layout } = choose(H));
   }
 
   const svg = svgElement(doc, "svg", {
@@ -60,7 +87,7 @@ export function figure(spec, { document: doc = globalThis.document, width, domai
   svg.append(svgElement(doc, "rect", { width: W, height: H, fill: theme.background }));
   for (const t of layout.texts) svg.append(svgText(doc, t.text, t.attrs));
   if (info) svg.append(drawInfo(doc, info, theme, layout.info));
-  for (const s of layout.strips) svg.append(strip(doc, s, theme, fonts));
+  for (const s of layout.strips) svg.append(strip(doc, s, theme));
   const state = { spec, ns, doc, svg, theme, fonts, grid, kind, color, ctx, legend, info, layout, home, W, H };
   state.domains = domains ?? home;
   state.hidden = hidden;
@@ -199,13 +226,13 @@ function homeDomain(ns, axis, kind, panels) {
   return limits ? [limits[0] ?? trained[0], limits[1] ?? trained[1]] : trained;
 }
 
-function strip(doc, s, theme, fonts) {
+function strip(doc, s, theme) {
   const g = svgElement(doc, "g", { class: "pt-strip" });
   g.append(svgElement(doc, "rect", { x: s.x, y: s.y, width: s.w, height: s.h, fill: theme.strip }));
   const attrs = s.vertical
     ? { transform: `translate(${s.x + s.w / 2},${s.y + s.h / 2}) rotate(90)`, dy: "0.35em" }
     : { x: s.x + s.w / 2, y: s.y + s.h / 2, dy: "0.35em" };
-  const text = svgText(doc, s.text, { ...attrs, "text-anchor": "middle", "font-weight": "bold", "font-size": fonts.strip, fill: theme.ink });
+  const text = svgText(doc, s.text, { ...attrs, "text-anchor": "middle", "font-weight": "bold", "font-size": s.size, fill: theme.ink });
   if (s.text !== String(s.full)) text.append(svgText(doc, s.full, {}, "title"));
   g.append(text);
   return g;

package/src/info.js

@@ -10,9 +10,9 @@ const MAX_HEIGHT = { right: 0.6, bottom: 0.3 }; // share of the figure height; t
 const MAX_COLUMNS = 3; // columns of entries in a bottom card
 
 // The info model with its position and size. narrow: a right placement moves to the bottom.
-export function infoModel(ns, fonts, { W, H, narrow }) {
+export function infoModel(ns, fonts, { W, H, narrow, place = ns.info?.position }) {
   if (!ns.info) return null;
-  const position = narrow ? "bottom" : ns.info.position;
+  const position = narrow ? "bottom" : place;
   return model(ns, fonts, ns.info.entries, position, W, H * MAX_HEIGHT[position]);
 }
 
@@ -45,11 +45,13 @@ function model(ns, fonts, entries, position, W, maxHeight) {
   const table = (rows) => {
     let columns;
     if (position === "bottom") {
-      const natural = d3.max(rows, (r) => width(r.key) + keyGap + width(r.value)) ?? 0;
-      const k = Math.max(1, Math.min(MAX_COLUMNS, rows.length, Math.floor((inner + colGap) / (natural + colGap))));
-      const perColumn = Math.ceil(rows.length / k);
-      const colW = (inner - colGap * (k - 1)) / k;
-      columns = d3.range(k).map((j) => column(rows.slice(j * perColumn, (j + 1) * perColumn), colW));
+      // The most columns (up to 3) whose entries fit on one line each in the width; else one column that wraps.
+      const split = (k) => {
+        const perColumn = Math.ceil(rows.length / k);
+        return d3.range(k).map((j) => column(rows.slice(j * perColumn, (j + 1) * perColumn), Infinity));
+      };
+      const fit = d3.range(Math.min(MAX_COLUMNS, rows.length), 1, -1).map(split).find((c) => d3.sum(c, (col) => col.width) + colGap * (c.length - 1) <= inner);
+      columns = fit ?? [column(rows, inner)];
     } else columns = [column(rows, inner)];
     let x = pad;
     for (const c of columns) (c.x = x), (x += c.width + colGap);
@@ -62,7 +64,9 @@ function model(ns, fonts, entries, position, W, maxHeight) {
     kept--;
     t = table([...all.slice(0, kept), { key: `+${all.length - kept} more`, value: "" }]);
   }
-  return { position, size, pad, lineH, keyGap, ...t };
+  // cut: the entries that do not show, plus the keys that end with an ellipsis.
+  const keys = t.columns.flatMap((c) => c.rows).filter((r) => r.key !== r.full).length;
+  return { position, size, pad, lineH, keyGap, cut: all.length - kept + keys, ...t };
 }
 
 // The table as an SVG group at (x, y): keys in the muted color, values in the ink color, on a strip-colored card.

package/src/layout.js

@@ -19,13 +19,20 @@ export function place({ ns, grid, kind, home, legend, info, fonts, W, H }) {
   const gap = Math.round(s * 0.8);
   const { title, subtitle, caption, x: xTitle, y: yTitle } = ns.labels;
   const at = (position) => (info?.position === position ? info : null);
-  const headW = W - 2 * pad - Math.min(180, W * TOOLBAR);
+  const xt = xTitle ? fonts.axisTitle * 1.7 : 0;
+  const yt = yTitle ? fonts.axisTitle * 1.7 : 0;
+  // The title starts at the left edge of the panels. A screen plot keeps room on the right for the toolbar; a fixed
+  // format (copied as a picture) uses the full width, less the y axis title and tick labels on the left.
+  const yLabels = d3.max(grid.panels, (p, i) => {
+    const t = ticks(kind.y, home[i].y, 5, ns.scales.y?.format);
+    return d3.max(t.major, (v) => tw(t.format(v), fonts.tick));
+  });
+  const left = yt + (yLabels ?? 0) + TICK.size + TICK.padding + 3;
+  const headW = W - 2 * pad - (theme.fixedFormat ? left : Math.min(180, W * TOOLBAR));
   const titleLines = title ? wrapText(title, fonts.title, headW, true, metrics) : [];
   const subtitleLines = subtitle ? wrapText(subtitle, fonts.subtitle, headW, false, metrics) : [];
   const head = titleLines.length * fonts.title * 1.25 + subtitleLines.length * fonts.subtitle * 1.4;
   const top = pad + head + (head ? s * 0.7 : 0);
-  const xt = xTitle ? fonts.axisTitle * 1.7 : 0;
-  const yt = yTitle ? fonts.axisTitle * 1.7 : 0;
   const cap = caption ? fonts.tick * 1.8 : 0;
   const rightW = Math.max(legend && !legend.horizontal ? legend.width : 0, at("right")?.width ?? 0);
   const right = rightW ? rightW + s * 1.5 : 0;
@@ -138,13 +145,17 @@ export function place({ ns, grid, kind, home, legend, info, fonts, W, H }) {
     showY: showY(p),
   }));
 
+  // A format with "shrink" makes the strip text smaller (all strips the same) before it cuts a label.
+  const stripRoom = (p) => [p.strips.top != null && [p.strips.top, innerW], p.strips.right != null && [p.strips.right, innerH]].filter(Boolean);
+  const stripScale = Math.max(theme.shrink ?? 1, Math.min(1, d3.min(grid.panels.flatMap(stripRoom), ([t, w]) => (w - 8) / tw(t, fonts.strip, true)) ?? 1));
+  const stripSize = Math.round(fonts.strip * stripScale * 10) / 10;
   const strips = [];
   grid.panels.forEach((p, i) => {
     const b = panels[i];
     const left = b.x + b.ml;
-    const label = (text, width) => fitText(text, fonts.strip, width - 8, true, metrics);
-    if (p.strips.top != null) strips.push({ x: left, y: b.y - wrapStrip - topStrip, w: innerW, h: strip, text: label(p.strips.top, innerW), full: p.strips.top });
-    if (p.strips.right != null) strips.push({ x: left + innerW + 2, y: b.y, w: strip, h: innerH, text: label(p.strips.right, innerH), full: p.strips.right, vertical: true });
+    const label = (text, width) => fitText(text, stripSize, width - 8, true, metrics);
+    if (p.strips.top != null) strips.push({ x: left, y: b.y - wrapStrip - topStrip, w: innerW, h: strip, text: label(p.strips.top, innerW), full: p.strips.top, size: stripSize });
+    if (p.strips.right != null) strips.push({ x: left + innerW + 2, y: b.y, w: strip, h: innerH, text: label(p.strips.right, innerH), full: p.strips.right, vertical: true, size: stripSize });
   });
 
   const first = panels[0];

package/src/spec.js

@@ -7,12 +7,13 @@ export function normalize(spec, overrides = {}) {
   if (typeof spec?.spec === "function") spec = spec.spec(); // a builder
   if (spec?.version !== 1) throw new Error("plotto: unknown spec version");
   const theme = resolveTheme({ ...spec.theme, ...overrides });
+  theme.legendSet = (overrides.legend ?? spec.theme?.legend) != null; // a legend place from the spec, not the default
   const tables = spec.data.map(toTable);
   const layers = spec.layers.map((l) => resolveLayer(l, spec.mapping ?? {}, tables, theme));
   if (!layers.length) throw new Error("plotto: the plot has no layers. Add one, for example .line() or .point()");
   const facet = resolveFacet(spec.facet);
   const labels = { ...defaultLabels(layers), ...spec.labels };
-  const info = spec.info?.entries?.length ? { entries: spec.info.entries, position: spec.info.position ?? "right" } : null;
+  const info = spec.info?.entries?.length ? { entries: spec.info.entries, position: spec.info.position ?? "right", set: !!spec.info.position } : null;
   return { tables, layers, facet, scales: spec.scales ?? {}, labels, info, theme };
 }
 

package/src/theme.js

@@ -27,6 +27,7 @@ export function resolveTheme({ style = "pastel", format = "screen", legend = "ri
   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.fixedFormat = !f.reflow; // report, slide: a picture of a fixed size, often copied without its toolbar
   theme.palette = palette(theme, theme.palette);
   return theme;
 }

package/theme.json

@@ -142,6 +142,7 @@
       "width": 960,
       "height": 600,
       "size": 22,
+      "shrink": 0.7,
       "line": 2.5,
       "point": 4,
       "reflow": false