@sipemu/ggplot-rs 0.38.0 → 0.39.0

package/README.md

@@ -85,7 +85,7 @@ const spec: PlotSpec = {
     color: { palette: 'Dark2' },            // or { values: { OJ: '#e69f00', VC: '#56b4e9' } }
   },
   facet: { wrap: 'supp' },                  // or { rows: 'a', cols: 'b', scales: 'free_y' }
-  coord: 'cartesian',                       // 'flip' | 'polar' | 'fixed' | 'radar' | { type, xlim, ylim, ratio }
+  coord: 'cartesian',                       // 'flip' | 'polar' | 'fixed' | 'radar' | 'sf' | { type, xlim, ylim, ratio }
   labels: { title: 'Tooth growth', subtitle: 'by supplement', y: 'Length' },
   theme: { base: 'bw', title: { size: 16, face: 'bold' } }, // or just 'classic'
   legend: 'bottom',                         // 'none' | 'inside' | [x, y] …
@@ -96,10 +96,10 @@ const spec: PlotSpec = {
 
 | Field | What it does |
 |---|---|
-| `layers[].geom` | One of `geoms()`. That covers point, line, path, step, area, ribbon, col, bar, histogram, freqpoly, density, boxplot, violin, dotplot, smooth, text, label, errorbar, linerange, pointrange, crossbar, segment, rect, tile, raster, polygon, rug, count, bin2d, hex, density2d, contour, qq, qq_line, hline, vline, abline and blank, plus the chart types waterfall, pareto, sankey, chord, treemap, sunburst, icicle, funnel, stream, lollipop, dumbbell, candlestick, ohlc and calendar. |
+| `layers[].geom` | One of `geoms()` — every `geom_*` of the Rust crate (a test enforces this): the basic geoms (point, line, path, step, area, ribbon, col, bar, segment, curve, rect, tile, raster, polygon, text, label, text_repel, …), reference lines (hline, vline, abline), distributions (histogram, freqpoly, density, density_ridges, boxplot, violin, dotplot, smooth, count, bin2d, hex, density2d, contour, contour_filled, qq, qq_line, qq_band), intervals (errorbar, errorbarh, linerange, pointrange, crossbar, xrange), business charts (waterfall, pareto, funnel, pyramid, lollipop, dumbbell, bullet, marimekko, waffle, parliament, tilemap, wordcloud, venn, timeline, calendar, …), hierarchies and networks (treemap, sunburst, icicle, dendrogram, sankey, chord, arcdiagram, network, stream), finance (candlestick, ohlc, hlc, heikin_ashi, renko, point_figure) and spatial (sf, sf_text, sf_label, flow). |
 | `layers[].aes` | A layer-level mapping, merged over the plot `aes`. |
 | `layers[].data` | Layer-specific data. |
-| `layers[].params` | `bins` (histogram), `method`/`span`/`se` (smooth), `yintercept`/`xintercept`/`slope`/`intercept` (reference lines), `levels` (sunburst/icicle). |
+| `layers[].params` | `bins` (histogram), `method`/`span`/`se` (smooth), `yintercept`/`xintercept`/`slope`/`intercept` (reference lines), `levels` (sunburst/icicle), `rows` (waffle/parliament), `box_size`/`reversal` (renko/point_figure), `shape` (tilemap), `speed`/`direction` (windbarb), `censor` (censor_marks), `projection` (sf, sf_text, sf_label, flow), `target`/`ranges` (bullet). |
 | `layers[].position` | `identity`, `stack`, `fill`, `dodge`, `dodge2`, `jitter` or `nudge`. Use an object such as `{ type: 'dodge', width: 0.8 }` to set parameters. |
 | `layers[].stat` | `'identity'`, which plots values as given (e.g. `bar` with precomputed heights). |
 | `theme` | A preset name (`gray`, `bw`, `minimal`, `classic`, `dark`, `light`, `void`, `linedraw`) or a partial overlay. The overlay uses the same schema as the ggplot-rs CLI's `--theme-config` (`base`, `primary`, `palette`, per-element `title`/`axis_text_x`/`panel_grid_major` …). The default is `minimal`. |
@@ -129,6 +129,22 @@ the package was built from. The lower-level functions used by the live demo
 (`render_plot`, `render_geo`, `geo_bounds`, `render_bar`, `render_hist` and
 `scatter_frame`) are exported too.
 
+### Same spec as the CLI and Rust
+
+The spec is the crate's `ggplot_rs::spec` module, so the `ggplot-rs` CLI
+accepts the same JSON (`ggplot-rs --spec chart.json --parquet data.parquet`)
+and Rust code can call `ggplot_rs::spec::render_json` (feature `spec`).
+
+### Agent skill
+
+The package ships an agent skill at `skills/ggplot-rs-js/SKILL.md`, a
+how-to for LLM coding agents (Claude Code and others). To use it with Claude
+Code, copy or link it into your project:
+
+```sh
+mkdir -p .claude/skills && cp -r node_modules/@sipemu/ggplot-rs/skills/ggplot-rs-js .claude/skills/
+```
+
 ## Fidelity to ggplot2
 
 The statistical layers (binning, density/`bw.nrd0`, loess, boxplot

package/dist/ggplot_rs.d.ts

@@ -14,14 +14,22 @@ export type Aesthetic =
 /** Aesthetic → column name. */
 export type AesMap = Partial<Record<Aesthetic, string>>;
 
+/** Every geom `render()` accepts — `geoms()` returns the same list at runtime. */
 export type GeomName =
-| "point" | "jitter" | "line" | "path" | "step" | "area" | "ribbon" | "col" | "bar"
-| "histogram" | "freqpoly" | "density" | "boxplot" | "violin" | "dotplot" | "smooth"
-| "text" | "label" | "errorbar" | "linerange" | "pointrange" | "crossbar" | "segment"
-| "rect" | "tile" | "raster" | "polygon" | "rug" | "count" | "bin2d" | "hex"
-| "density2d" | "contour" | "qq" | "qq_line" | "hline" | "vline" | "abline" | "blank"
-| "waterfall" | "pareto" | "sankey" | "chord" | "treemap" | "sunburst" | "icicle"
-| "funnel" | "stream" | "lollipop" | "dumbbell" | "candlestick" | "ohlc" | "calendar";
+| "point" | "jitter" | "line" | "path" | "step" | "area" | "ribbon" | "stepribbon"
+| "col" | "bar" | "segment" | "curve" | "spoke" | "rect" | "tile" | "raster" | "polygon"
+| "text" | "label" | "text_repel" | "label_repel" | "rug" | "blank" | "hline" | "vline"
+| "abline" | "histogram" | "freqpoly" | "density" | "density_ridges" | "boxplot"
+| "violin" | "dotplot" | "smooth" | "count" | "bin2d" | "hex" | "density2d" | "contour"
+| "contour_filled" | "qq" | "qq_line" | "qq_band" | "censor_marks" | "errorbar"
+| "errorbarh" | "linerange" | "pointrange" | "crossbar" | "xrange" | "waterfall"
+| "pareto" | "funnel" | "pyramid" | "lollipop" | "dumbbell" | "bullet"
+| "bullet_vertical" | "marimekko" | "variwide" | "waffle" | "parliament" | "tilemap"
+| "packed_bubble" | "variable_pie" | "wordcloud" | "venn" | "timeline" | "calendar"
+| "flags" | "windbarb" | "treemap" | "sunburst" | "icicle" | "dendrogram" | "tree"
+| "sankey" | "chord" | "arcdiagram" | "network" | "stream" | "candlestick" | "ohlc"
+| "hlc" | "heikin_ashi" | "renko" | "point_figure" | "sf" | "sf_text" | "sf_label"
+| "flow";
 
 export interface LayerParams {
     /** histogram: bin count. */
@@ -41,6 +49,26 @@ export interface LayerParams {
     intercept?: number;
     /** sunburst / icicle (required): hierarchy columns, outermost first. */
     levels?: string[];
+    /** waffle (default 10) / parliament (default 6): rows. */
+    rows?: number;
+    /** renko / point_figure (required): price box size. */
+    box_size?: number;
+    /** point_figure: reversal in boxes (default 3). */
+    reversal?: number;
+    /** tilemap tile shape (default "square"). */
+    shape?: "square" | "hexagon" | "circle" | "diamond";
+    /** windbarb (required): speed column (knots). */
+    speed?: string;
+    /** windbarb (required): direction column (degrees the wind comes from). */
+    direction?: string;
+    /** censor_marks (required): 0/1 censoring-indicator column. */
+    censor?: string;
+    /** sf / sf_text / sf_label / flow: map projection (default "platecarree"). */
+    projection?: "platecarree" | "mercator" | "equal-earth" | "albers-usa" | "albers-europe" | `utm:${string}`;
+    /** bullet / bullet_vertical: target column. */
+    target?: string;
+    /** bullet / bullet_vertical: qualitative range band upper bounds. */
+    ranges?: number[];
 }
 
 export type PositionName = "identity" | "stack" | "fill" | "dodge" | "dodge2" | "jitter" | "nudge";
@@ -85,7 +113,7 @@ export type Facet =
 | { wrap: string; ncol?: number; scales?: "fixed" | "free" | "free_x" | "free_y" }
 | { rows?: string; cols?: string; scales?: "fixed" | "free" | "free_x" | "free_y" };
 
-export type CoordName = "cartesian" | "flip" | "polar" | "fixed" | "equal" | "radar";
+export type CoordName = "cartesian" | "flip" | "polar" | "fixed" | "equal" | "radar" | "sf";
 export type Coord =
 | CoordName
 | { type: CoordName; ratio?: number; xlim?: [number, number]; ylim?: [number, number] };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sipemu/ggplot-rs",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Grammar-of-graphics charts (ggplot2-style) rendered to SVG — WebAssembly build of the ggplot-rs Rust crate, no runtime dependencies",
   "type": "module",
   "main": "./dist/ggplot_rs.js",
@@ -19,6 +19,7 @@
     "dist/ggplot_rs.d.ts",
     "dist/ggplot_rs_bg.wasm",
     "dist/ggplot_rs_bg.wasm.d.ts",
+    "skills/",
     "README.md",
     "LICENSE-MIT",
     "LICENSE-APACHE"

package/skills/ggplot-rs-js/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: ggplot-rs-js
+description: Render ggplot2-style (Grammar of Graphics) charts to SVG in JavaScript/TypeScript — browser or Node — with the `@sipemu/ggplot-rs` npm package (WebAssembly build of the ggplot-rs crate). Use when writing JS/TS that charts data with `@sipemu/ggplot-rs`, when package.json depends on it, or when asked for ggplot-style charts in a web page, Observable, or a Node script without a DOM.
+---
+
+# Charts in JS/TS with `@sipemu/ggplot-rs`
+
+A typed, layered **plot spec in → SVG string out**. No runtime dependencies,
+no DOM needed (works in Node), the same engine as the `ggplot-rs` Rust crate
+and CLI (the npm version always equals the crate version). Statistical layers
+match R ggplot2 4.x.
+
+```sh
+npm i @sipemu/ggplot-rs
+```
+
+## Initialise once, then render
+
+```js
+// Browser / Vite / any bundler
+import init, { render } from "@sipemu/ggplot-rs";
+await init();                       // fetches ggplot_rs_bg.wasm next to the module
+document.querySelector("#chart").innerHTML = render(spec);
+```
+
+```js
+// Node ≥ 18 (no fetch from file: hand the bytes over)
+import { readFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { initSync, render } from "@sipemu/ggplot-rs";
+const require = createRequire(import.meta.url);
+initSync({ module: await readFile(require.resolve("@sipemu/ggplot-rs/ggplot_rs_bg.wasm")) });
+```
+
+Exports: `render(spec)` → SVG string (throws `Error` naming the bad field),
+`renderWithWarnings(spec)` → `{ svg, warnings }`, `geoms()` → accepted geom
+names, `version()`. Types: `PlotSpec`, `Layer`, `GeomName`, `LayerParams`, …
+
+## The spec
+
+```js
+const svg = render({
+  data: { dose: [0.5, 1, 2, 0.5, 1, 2],          // column-oriented, equal lengths
+          len: [13.2, 22.7, 26.1, 8.0, 16.8, 26.1],
+          supp: ["OJ", "OJ", "OJ", "VC", "VC", "VC"] },
+  aes: { x: "dose", y: "len", color: "supp" },   // inherited by every layer
+  layers: [
+    { geom: "point" },
+    { geom: "line" },
+    { geom: "hline", params: { yintercept: 20 } },
+  ],
+  scales: { x: { trans: "log2", name: "Dose (mg)" }, color: { palette: "Dark2" } },
+  facet: { wrap: "supp" },
+  labels: { title: "Tooth growth", y: "Length" },
+  theme: { base: "bw", title: { size: 16, face: "bold" } },
+  legend: "bottom",
+  width: 640, height: 400,
+});
+if (!svg.startsWith("<svg")) throw new Error("render failed");
+```
+
+| Field | Values |
+|---|---|
+| `data` | `{ col: (number \| string \| boolean \| null)[] }` — numbers continuous, strings/booleans categorical |
+| `aes` / `layers[].aes` | aesthetic → column: `x y color fill size shape alpha group linetype linewidth label weight xmin xmax ymin ymax xend yend angle radius tooltip from to subgroup open high low close lower middle upper fontface class` |
+| `layers[].geom` | see Geoms |
+| `layers[].params` | `bins` · `method` (`"lm"`/`"loess"`) `span` `se` · `yintercept` `xintercept` `slope` `intercept` · `levels` · `rows` · `box_size` `reversal` · `shape` · `speed` `direction` · `censor` · `projection` · `target` `ranges` |
+| `layers[].position` | `identity stack fill dodge dodge2 jitter nudge`, or `{ type: "dodge", width: 0.8 }` |
+| `layers[].stat` | `"identity"` (plot precomputed values, e.g. bar heights) |
+| `layers[].data` | layer-specific data |
+| `scales.x/y` | `{ trans, limits: [lo, hi], breaks: [...], name }`; trans `log10 log2 ln sqrt reverse logit probit pseudo_log reciprocal exp` |
+| `scales.color/fill` | `{ palette }` (`Set1 Dark2 Paired npg …` categorical; `viridis magma plasma inferno` numeric), `{ values: { level: "#rrggbb" } }`, `{ gradient: ["#lo", "#hi"] }`, `{ levels: [...] }` |
+| `facet` | `{ wrap, ncol?, scales? }` or `{ rows?, cols?, scales? }`; scales `fixed free free_x free_y` |
+| `coord` | `cartesian flip polar fixed radar sf`, or `{ type, xlim, ylim, ratio }` |
+| `labels` | `title subtitle caption tag x y` (axis titles are not auto-filled from column names) |
+| `theme` | preset `gray bw minimal classic dark light void linedraw` (default `minimal`), or an overlay `{ base, primary: [r,g,b], palette, title: {...}, panel_grid_major: {...}, … }` |
+| `legend` | `right left top bottom none inside` or `[x, y]` inside the panel |
+
+## Geoms
+
+- basic: `point jitter line path step area ribbon stepribbon col bar segment curve
+  spoke rect tile raster polygon text label text_repel label_repel rug blank`
+- reference lines: `hline vline abline` (params `yintercept` / `xintercept` / `slope`)
+- distributions: `histogram freqpoly density density_ridges boxplot violin dotplot
+  smooth count bin2d hex density2d contour contour_filled qq qq_line qq_band
+  censor_marks`
+- intervals: `errorbar errorbarh linerange pointrange crossbar xrange`
+- business: `waterfall pareto funnel pyramid lollipop dumbbell bullet
+  bullet_vertical marimekko variwide waffle parliament tilemap packed_bubble
+  variable_pie wordcloud venn timeline calendar flags windbarb`
+- hierarchies & networks: `treemap sunburst icicle dendrogram tree sankey chord
+  arcdiagram network stream`
+- finance: `candlestick ohlc hlc heikin_ashi renko point_figure`
+- spatial: `sf sf_text sf_label flow` (a WKT `geometry` column + `params.projection`)
+
+Special aesthetics: sankey/chord `from`/`to`/`weight`; treemap `weight`
+(+ `subgroup`, `label`); sunburst/icicle `params.levels`; candlestick/ohlc
+`open`/`high`/`low`/`close`; intervals `ymin`/`ymax`.
+
+```js
+const svg = render({
+  data: { src: ["a", "a", "b"], dst: ["b", "c", "c"], n: [3, 2, 1] },
+  aes: { from: "src", to: "dst", weight: "n" },
+  layers: [{ geom: "sankey" }],
+});
+if (!svg.includes("<svg")) throw new Error("sankey failed");
+```
+
+```js
+const { svg, warnings } = renderWithWarnings({
+  data: { x: [1, 2, 3, 4], y: [1, null, 3, 4], g: ["a", "a", "b", "b"] },
+  aes: { x: "x", y: "y", fill: "g" },
+  layers: [{ geom: "col", position: { type: "dodge", width: 0.8 } }],
+  scales: { fill: { values: { a: "#e69f00", b: "#56b4e9" } } },
+  coord: "flip",
+});
+if (!Array.isArray(warnings) || !svg) throw new Error("bad result");
+```
+
+## Workflow & pitfalls
+
+1. Shape data column-wise (`{ col: [...] }`); convert row arrays with
+   `Object.fromEntries(keys.map(k => [k, rows.map(r => r[k])]))`.
+2. Use numbers for continuous and strings for categorical columns — a numeric
+   `color` column gets a gradient, and a discrete palette name then errors.
+3. Develop with `renderWithWarnings` and read the warnings.
+4. On a thrown `Error`, read the message: it names the field
+   (`layers[0].aes.x: column 'wieght' not found (available: …)`) and lists the
+   valid choices.
+5. For huge data, aggregate first (e.g. DuckDB-Wasm) — SVG becomes slow past
+   ~50k marks.