inkplot-scratch 0.0.0-stage → 1.0.0-beta.1

package/src/figures.ts

@@ -0,0 +1,105 @@
+/**
+ * What a source module hands over, checked and described: shared by the command (in node) and the app (in a browser),
+ * so what the agent is told about a figure is what the person sees.
+ *
+ *   export default [chart1, { name: 'Histogram', caption: 'Bins of 0.5', chart: chart2 }];
+ */
+import { type Axis, type Chart, Plane, SeriesRenderer, StringPlatform, toSvgString } from 'inkplot';
+
+export interface Figure {
+  /** A file-safe name, numbered in order: `01-histogram`. */
+  readonly id: string;
+  /** What the figure is called: the `name` given, else the chart's `meta.title`, else `Figure 3`. */
+  readonly title: string;
+  readonly caption?: string;
+  /** Whether the page adds pan/zoom, a crosshair and a tooltip. Default true; `interactive: false` on an item turns it off. */
+  readonly interactive: boolean;
+  readonly chart: Chart;
+}
+
+/** `orientation` is the axis's place: bottom, left, top, right on a Cartesian plane, angle or radius on a polar one. */
+export interface AxisFacts { title?: string; orientation: string; min: number; max: number; ticks: string[] }
+export interface SeriesFacts { name: string; points: number; shown: boolean }
+export interface Facts { id: string; title: string; caption?: string; width: number; height: number; series: SeriesFacts[]; axes: AxisFacts[]; problems: string[] }
+
+export class FigureError extends Error {}
+
+// oxlint-disable-next-line typescript/consistent-type-assertions -- a type guard: the members are probed before use, on a value of unknown type
+const looksLikeChart = (x: unknown): x is Chart => typeof x === 'object' && x !== null && typeof (x as Chart).attach === 'function' && typeof (x as Chart).flush === 'function' && 'attrs' in x;
+const describe = (x: unknown) => (x === null ? 'null' : Array.isArray(x) ? 'an array' : typeof x === 'object' ? `an object${x.constructor?.name && x.constructor.name !== 'Object' ? ` (${x.constructor.name})` : ` with keys ${Object.keys(x).slice(0, 5).join(', ') || '(none)'}`}` : `${typeof x} ${String(x).slice(0, 30)}`);
+const slug = (s: string) => s.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '').slice(0, 40);
+
+/** The figures in a module's default export: an array of charts or `{ chart, name?, caption?, interactive? }`. A lone chart is one figure. */
+export function figuresOf(module: Record<string, unknown>): Figure[] {
+  if (!('default' in module)) throw new FigureError('The module has no default export. End the file with: export default [chart1, chart2];');
+  const given = module.default;
+  const list = Array.isArray(given) ? given : [given];
+  if (list.length === 0) throw new FigureError('The default export is an empty array: put at least one chart in it.');
+  const width = String(list.length).length < 2 ? 2 : String(list.length).length;
+  const taken = new Set<string>(), charts = new Map<unknown, number>();
+  return list.map((item, i): Figure => {
+    const at = `export default [...] item ${i + 1}`;
+    const wrapped = typeof item === 'object' && item !== null && !looksLikeChart(item) && 'chart' in item;
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- `wrapped` was checked just above: the item is a `{ chart }` wrapper
+    const chart = wrapped ? (item as { chart: unknown }).chart : item;
+    if (!looksLikeChart(chart)) {
+      throw new FigureError(`${at} is ${describe(chart)}, not a Chart. Each item is a <Chart> / new Chart(...), or { chart, name?, caption? }.`);
+    }
+    const earlier = charts.get(chart);
+    if (earlier !== undefined) throw new FigureError(`${at} is the same chart object as item ${earlier + 1}. One chart can be one figure: build a second one (a function that returns a new chart works well).`);
+    charts.set(chart, i);
+    // oxlint-disable-next-line typescript/consistent-type-assertions -- the wrapper's fields are read as `unknown` and checked one by one below
+    const o = (wrapped ? item : {}) as { name?: unknown; caption?: unknown; interactive?: unknown };
+    const title = typeof o.name === 'string' && o.name ? o.name : chart.attrs.meta?.title ?? `Figure ${i + 1}`;
+    let id = `${String(i + 1).padStart(width, '0')}-${slug(title) || 'figure'}`;
+    while (taken.has(id)) id += '-';
+    taken.add(id);
+    return { id, title, ...(typeof o.caption === 'string' && { caption: o.caption }), interactive: o.interactive !== false, chart };
+  });
+}
+
+export interface SizeOptions { width?: number; height?: number }
+
+/** The chart as an SVG document, at its own size (the options only fill in what it leaves out). */
+export const svgOf = (figure: Figure, size: SizeOptions = {}): string => toSvgString(figure.chart, size);
+
+const round = (n: number) => Number(n.toPrecision(12));
+
+/** What the chart holds once laid out. The chart is attached (to `platform`, or a string one) for the look and detached again. */
+export function factsOf(figure: Figure, size: SizeOptions = {}): Facts {
+  const { chart } = figure, a = chart.attrs;
+  const platform = new StringPlatform({ width: a.width ?? size.width ?? 640, height: a.height ?? size.height ?? 400 });
+  chart.attach(platform).flush();
+  const series: SeriesFacts[] = [], axes: AxisFacts[] = [], problems: string[] = [], seen = new Set<Axis>();
+  let n = 0;
+  for (const plane of chart) {
+    if (!(plane instanceof Plane)) continue;
+    for (const s of plane.allSeries) {
+      n++;
+      const f = { name: s.attrs.name ?? s.attrs.meta?.title ?? `series ${n}`, points: s.points.count, shown: s.shown };
+      series.push(f);
+      if (![...s].some((c) => c instanceof SeriesRenderer)) problems.push(`${f.name} has no renderer, so nothing is drawn for it: add one after its data (LinePath, BarPath, BoxPath, a marker, …)`);
+      else if (f.shown && f.points === 0) problems.push(`${f.name} has no points: the data is empty, or its domain misses the axis range`);
+    }
+    for (const axis of plane.axes) {
+      if (seen.has(axis)) continue;
+      seen.add(axis);
+      const ticks = axis.getTicks(axis.ruler.length);
+      if (ticks.length < 2) { problems.push(`the ${axis.orientation} axis${axis.attrs.title ? ` "${axis.attrs.title}"` : ''} has fewer than two ticks`); continue; }
+      axes.push({ ...(axis.attrs.title && { title: axis.attrs.title }), orientation: axis.orientation, min: round(axis.range.min), max: round(axis.range.max), ticks: ticks.map((t) => t.label) });
+    }
+  }
+  const { width, height } = platform.size(), svg = platform.toString();
+  chart.detach();
+  if (/NaN|Infinity/.test(svg)) problems.push('the SVG contains NaN or Infinity: a value, scale or size is not a finite number');
+  return { id: figure.id, title: figure.title, ...(figure.caption !== undefined && { caption: figure.caption }), width, height, series, axes, problems };
+}
+
+/** The facts as the lines `--check` prints. */
+export function checkText(f: Facts): string {
+  const lines = [`${f.id}  "${f.title}"  ${f.width}x${f.height}`];
+  for (const s of f.series) lines.push(`  series ${JSON.stringify(s.name)}: ${s.points} points${s.shown ? '' : ' (hidden)'}`);
+  for (const a of f.axes) lines.push(`  ${a.orientation} axis${a.title ? ` ${JSON.stringify(a.title)}` : ''}: range ${a.min} to ${a.max}; ticks ${a.ticks.length > 12 ? [...a.ticks.slice(0, 6), '…', ...a.ticks.slice(-3)].join(' ') : a.ticks.join(' ')}`);
+  for (const p of f.problems) lines.push(`  WARNING ${p}`);
+  return lines.join('\n');
+}

package/src/interact.ts

@@ -0,0 +1,39 @@
+/**
+ * The standard interactive elements, added to a chart that is about to go on the page: pan and zoom, drag-a-box zoom, a
+ * crosshair and a tooltip. It adds only what the chart does not already have, so a module that sets these up itself is left alone.
+ * It runs after the chart has been rendered for export, so no SVG file, PNG or fact ever includes them.
+ */
+import { type AnyElement, BoxZoom, CartesianPlane, type Chart, ChartTooltip, Crosshair, Cursor, PanZoom, Plane } from 'inkplot';
+
+
+/** What was added, by name: for the page's hint line and for tests. */
+export function makeInteractive(chart: Chart): string[] {
+  const added = new Set<string>();
+  const children = (parent: AnyElement): AnyElement[] => [...parent];
+  const planes = children(chart).filter((c): c is Plane => c instanceof Plane);
+  for (const plane of planes) {
+    const kids = children(plane);
+    if (plane instanceof CartesianPlane && !kids.some((k) => k instanceof BoxZoom)) {
+      // A box takes a press, so it goes before whatever else does (PanZoom, a Brush, a PointerListener).
+      const first = kids.find((k) => k.claimsPress) ?? null;
+      // `first` is one of the plane's own children, which the iteration types more loosely than `insertBefore` takes.
+      // oxlint-disable-next-line typescript/consistent-type-assertions -- `first` is any child of the plane; `insertBefore` takes the plane's own child union, and the wildcard child cannot be narrowed to it
+      plane.insertBefore(new BoxZoom(), first as Parameters<Plane['insertBefore']>[1]);
+      added.add('boxzoom');
+    }
+    if (!kids.some((k) => k instanceof PanZoom)) { plane.append(new PanZoom()); added.add('panzoom'); }
+  }
+  if (planes.length > 0 && !children(chart).some((c) => c instanceof Cursor)) {
+    chart.append(new Cursor({}, new Crosshair(), new ChartTooltip()));
+    added.add('cursor');
+  }
+  return [...added];
+}
+
+/** The hint under a figure's title for what is now on it. */
+export function hintFor(added: readonly string[]): string {
+  const parts: string[] = [];
+  if (added.includes('panzoom')) parts.push('drag to pan', 'scroll to zoom', 'double-click to reset');
+  if (added.includes('boxzoom')) parts.push('Shift-drag for a zoom box');
+  return parts.length ? parts.join(' · ') : '';
+}

package/src/template.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Charts</title>
+<style>
+:root { color-scheme: light dark; --bg: #f6f7f9; --card: #fff; --ink: #1d2733; --muted: #5d6b7a; --line: #d9dee5; --accent: #2a6df4; --warn: #9a5b00; }
+@media (prefers-color-scheme: dark) { :root { --bg: #14181d; --card: #1d232b; --ink: #e6ebf1; --muted: #9aa7b5; --line: #323b46; --accent: #7aa7ff; --warn: #f0b45a; } }
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--ink); font: 15px/1.5 system-ui, sans-serif; }
+main { max-width: 1040px; margin: 0 auto; padding: 16px; }
+.top { display: flex; flex-wrap: wrap; gap: 8px 16px; align-items: center; justify-content: space-between; margin: 8px 0 16px; }
+h1 { font-size: 22px; margin: 0; } h2 { font-size: 17px; margin: 0; }
+.figure { background: var(--card); border: 1px solid var(--line); border-radius: 10px; padding: 14px 16px 16px; margin: 0 0 18px; }
+.figure header { display: flex; flex-wrap: wrap; gap: 8px 16px; align-items: center; justify-content: space-between; margin-bottom: 8px; }
+.buttons { display: flex; flex-wrap: wrap; gap: 6px; }
+button { font: inherit; font-size: 13px; padding: 4px 10px; border-radius: 6px; border: 1px solid var(--line); background: transparent; color: var(--ink); cursor: pointer; }
+button:hover { border-color: var(--accent); color: var(--accent); }
+.plot { width: 100%; background: #fff; border-radius: 6px; }
+.caption { color: var(--muted); margin: 0 0 8px; }
+.hint { color: var(--muted); font-size: 12.5px; margin: 0 0 6px; }
+.stats { margin: 10px 0 0; padding: 10px; background: var(--bg); border-radius: 6px; font-size: 12.5px; overflow: auto; }
+.warning { color: var(--warn); margin: 8px 0 0; }
+.error { color: #b3261e; white-space: pre-wrap; }
+#note { position: fixed; left: 50%; bottom: 20px; transform: translateX(-50%); background: var(--ink); color: var(--bg); padding: 8px 14px; border-radius: 8px; opacity: 0; transition: opacity .2s; pointer-events: none; max-width: 90vw; }
+#note.on { opacity: 1; }
+</style>
+</head>
+<body>
+<main>
+  <div class="top"><h1 id="title">Charts</h1><div class="buttons"><button id="all-svg" type="button">All SVG ↓</button><button id="all-png" type="button">All PNG ↓</button></div></div>
+  <div id="figures"></div>
+</main>
+<div id="note" role="status" aria-live="polite"></div>
+<script>/*SCRIPT*/</script>
+</body>
+</html>