@danielsimonjr/mathts-plot 0.2.0

package/README.md

@@ -0,0 +1,142 @@
+# @danielsimonjr/mathts-plot
+
+Headless SVG 2D/3D plotting for [MathTS](https://github.com/danielsimonjr/mathts).
+
+Pure functions returning self-contained SVG strings — no browser, no canvas, no runtime
+dependencies beyond the MathTS bedrock (`core`/`functions`/`expression`). Every function
+coerces its input and never throws on bad data: empty, `NaN`, or `Infinity` inputs render a
+"no data" placeholder SVG instead of crashing. See
+`docs/superpowers/specs/2026-07-07-plotting-design.md` for the design.
+
+## Install
+
+```sh
+npm install @danielsimonjr/mathts-plot
+```
+
+## Usage
+
+Every function below returns a self-contained SVG string (`<svg ...>...</svg>`) — render it
+directly in an `<img src="data:image/svg+xml,...">`, write it to a `.svg` file, or drop it
+into HTML.
+
+### `line` — one series, or overlaid with others
+
+```ts
+import { line } from '@danielsimonjr/mathts-plot';
+
+const svg = line([0, 1, 2, 3], [0, 1, 4, 9], { title: 'squares', xLabel: 'x', yLabel: 'y' });
+// svg === '<svg ...>...</svg>'
+```
+
+### `overlay` — combine several layers on shared, auto-scaled axes
+
+```ts
+import { overlay } from '@danielsimonjr/mathts-plot';
+
+const svg = overlay(
+  [
+    { type: 'line', x: [0, 1, 2], y: [0, 1, 2], label: 'model' },
+    { type: 'scatter', x: [0, 1, 2], y: [0.1, 1.2, 1.8], label: 'data' },
+  ],
+  { legend: true }
+);
+```
+
+### `surface` — 3D surface via orthographic projection + painter's algorithm
+
+```ts
+import { surface } from '@danielsimonjr/mathts-plot';
+
+const z = [
+  [0, 1, 2],
+  [1, 2, 3],
+  [2, 3, 4],
+]; // z[row][col]
+const svg = surface(z, { kind: 'filled', azim: 45, elev: 25 });
+```
+
+### `plot` — generic, polymorphic entry point (including expression strings)
+
+```ts
+import { plot } from '@danielsimonjr/mathts-plot';
+
+// numeric series → line
+plot([0, 1, 4, 9]);
+plot([0, 1, 2, 3], [0, 1, 4, 9]);
+
+// expression string, sampled via functions/expression → line
+plot('sin(x)', { from: 0, to: Math.PI, samples: 200 });
+
+// two free variables → contour (default) or 3D surface
+plot('x^2 + y^2', { from: -2, to: 2 });
+plot('x^2 + y^2', { from: -2, to: 2, kind: 'surface' });
+
+// array of Layer2D → overlay
+plot([
+  { type: 'line', x: [0, 1, 2], y: [0, 1, 2] },
+  { type: 'scatter', x: [0, 1, 2], y: [0.1, 1.2, 1.8] },
+]);
+```
+
+### TikZ / LaTeX output
+
+Every function also accepts `{ format: 'tikz' }` (default is `'svg'`), and there's a
+generic `toTikZ()` mirroring `plot()`. The geometry matches the SVG output exactly (a
+deterministic y-flip maps SVG's top-left origin to TikZ's bottom-left); only
+`\usepackage{tikz}` is required to compile the result.
+
+```ts
+import { toTikZ, line, surface } from '@danielsimonjr/mathts-plot';
+
+// generic entry point, expression source → line
+const tex = toTikZ('sin(x)', { from: 0, to: Math.PI });
+
+// per-type function via the format option
+const tex2 = line([0, 1, 2, 3], [0, 1, 4, 9], { format: 'tikz' });
+
+// standalone: false → a bare tikzpicture for \input, not a compilable document
+const z = [
+  [0, 1, 2],
+  [1, 2, 3],
+  [2, 3, 4],
+];
+const fragment = surface(z, { format: 'tikz', tikz: { standalone: false } });
+```
+
+`toTikZ`/`{ format: 'tikz' }` return a LaTeX string, not SVG. With `standalone`
+(default `true`) the string is a complete `\documentclass{...}` document you can
+compile as-is; `standalone: false` returns just the `tikzpicture` environment, meant
+to be pulled in via `\input{...}` from a larger document.
+
+## What it provides
+
+Per-type mark functions, each `(x, y, opts?) => string` unless noted:
+
+- **2D**: `line`, `scatter`, `bar`, `area`, `step`, `errorbar(x, y, yerr, opts?)`,
+  `quiver(x, y, u, v, opts?)`.
+- **`histogram(data, opts?)`** — bins via `functions.histogram`, then renders bar heights at
+  bin centers.
+- **`heatmap(z, opts?)`** — viridis-colored grid, `z` as `z[row][col]`.
+- **`contour(z, opts?)`** — marching squares over a `z[row][col]` grid.
+- **`overlay(layers, opts?)`** — several `Layer2D`s on shared, auto-scaled axes.
+- **3D**: `surface(z, opts?)` (wireframe or painter's-algorithm filled),
+  `scatter3d(x, y, z, opts?)`, `curve3d(x, y, z, opts?)` — all projected with an orthographic
+  camera (`azim`/`elev`).
+- **`plot(...)`** — generic polymorphic dispatch over numeric series, layer arrays, and
+  expression-source strings (evaluated via `@danielsimonjr/mathts-expression` /
+  `@danielsimonjr/mathts-functions`).
+- **`viridis(t)`** — the perceptually-uniform colormap used by `heatmap`/`contour`/`surface`,
+  exposed for reuse.
+
+Notes:
+
+- Pure ESM, `strict` TypeScript, no runtime dependencies beyond the MathTS bedrock
+  (`core`/`functions`/`expression`).
+- SVG-only in v1 — no PNG/canvas rendering.
+- `workbook` renders its charts through this package (its former private `svg.ts` plotter was
+  removed).
+
+## License
+
+MIT (c) Daniel Simon Jr.

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+/** Anything the plotter accepts as a data series: numbers, typed arrays, or core values. */
+type Data = unknown;
+/** A 2-D coordinate axis. */
+interface AxisSpec {
+    label?: string;
+    scale?: 'linear' | 'log';
+}
+/** Options shared by all plot functions (each uses the subset it needs). */
+interface PlotOptions {
+    title?: string;
+    xLabel?: string;
+    yLabel?: string;
+    x?: AxisSpec;
+    y?: AxisSpec;
+    width?: number;
+    height?: number;
+    theme?: 'light' | 'dark';
+    palette?: readonly string[];
+    legend?: boolean;
+    from?: number;
+    to?: number;
+    samples?: number;
+    kind?: '2d' | '3d' | 'surface';
+    scope?: Record<string, unknown>;
+    format?: 'svg' | 'tikz';
+    tikz?: {
+        standalone?: boolean;
+        scale?: number;
+    };
+}
+/** One drawable 2-D layer for the shared draw2D core / overlay. */
+interface Layer2D {
+    type: 'line' | 'scatter' | 'bar' | 'area' | 'step' | 'errorbar' | 'quiver';
+    x?: Data;
+    y: Data;
+    yerr?: Data;
+    u?: Data;
+    v?: Data;
+    label?: string;
+    color?: string;
+}
+
+/**
+ * Generic entry point. Data forms:
+ *   plot(y, opts?)            → line, x = 0..n-1
+ *   plot(x, y, opts?)         → line
+ *   plot(layers[], opts?)     → overlay
+ *   plot(source, opts?)       → expression sampling (line / contour / surface)
+ */
+declare function plot(a: unknown, b?: unknown, c?: PlotOptions): string;
+/** Generic TikZ entry — same polymorphism as plot(), forced to the TikZ backend. */
+declare function toTikZ(a: unknown, b?: unknown, c?: PlotOptions): string;
+
+/** Public: line chart of one or many series. */
+declare function line(x: Layer2D['x'], y: Layer2D['y'], opts?: PlotOptions): string;
+/** Public: scatter plot of one or many series. */
+declare function scatter(x: Layer2D['x'], y: Layer2D['y'], opts?: PlotOptions): string;
+/** Public: bar chart of one or many series. */
+declare function bar(x: Layer2D['x'], y: Layer2D['y'], opts?: PlotOptions): string;
+/** Public: filled area under one or many series. */
+declare function area(x: Layer2D['x'], y: Layer2D['y'], opts?: PlotOptions): string;
+/** Public: step chart (horizontal-then-vertical) of one or many series. */
+declare function step(x: Layer2D['x'], y: Layer2D['y'], opts?: PlotOptions): string;
+/** Public: vertical error bars (whisker + point) for one or many series. */
+declare function errorbar(x: Layer2D['x'], y: Layer2D['y'], yerr: Layer2D['yerr'], opts?: PlotOptions): string;
+/** Public: 2-D vector field (arrows) of one or many series. */
+declare function quiver(x: Layer2D['x'], y: Layer2D['y'], u: Layer2D['u'], v: Layer2D['v'], opts?: PlotOptions): string;
+
+/** Histogram: bins via functions.histogram, then renders bar heights at bin centers. */
+declare function histogram(data: unknown, opts?: PlotOptions & {
+    bins?: number;
+}): string;
+
+/** Heatmap of a 2-D grid z[row][col], colored by viridis over the data range. */
+declare function heatmap(z: unknown, opts?: PlotOptions): string;
+
+/** Contour plot via marching squares over grid z[row][col]. */
+declare function contour(z: unknown, opts?: PlotOptions & {
+    levels?: number;
+}): string;
+
+/** Draw several 2-D layers (of any mix of types) on shared auto-scaled axes. */
+declare function overlay(layers: Layer2D[], opts?: PlotOptions): string;
+
+/** 3-D surface z[row][col], projected to 2-D SVG. Painter's algorithm for `filled`. */
+declare function surface(z: unknown, opts?: Omit<PlotOptions, 'kind'> & {
+    azim?: number;
+    elev?: number;
+    kind?: 'wireframe' | 'filled';
+}): string;
+
+interface P3Opts extends PlotOptions {
+    azim?: number;
+    elev?: number;
+}
+/** 3-D scatter of (x,y,z) point triples, projected to 2-D SVG. */
+declare function scatter3d(x: unknown, y: unknown, z: unknown, opts?: P3Opts): string;
+/** Parametric 3-D curve through (x,y,z) coordinate arrays. */
+declare function curve3d(x: unknown, y: unknown, z: unknown, opts?: P3Opts): string;
+
+/** viridis colormap: t in [0,1] → "#rrggbb". */
+declare function viridis(t: number): string;
+
+/** @danielsimonjr/mathts-plot — headless SVG 2D/3D plotting for MathTS. */
+declare const VERSION = "0.2.0";
+
+export { type AxisSpec, type Data, type Layer2D, type PlotOptions, VERSION, area, bar, contour, curve3d, errorbar, heatmap, histogram, line, overlay, plot, quiver, scatter, scatter3d, step, surface, toTikZ, viridis };