plotagents 0.0.0-stage → 0.5.0

package/AGENTS.md

@@ -0,0 +1,78 @@
+# plotagents · guide for AI agents
+
+One function, one JSON object. No design decisions: the library makes them.
+
+```js
+import { plot, safePlot } from 'plotagents';
+const svg = plot({ type, data, x, y, series, title, subtitle, source });
+```
+
+## Rules for a good chart
+
+1. **`title` is the finding**, a full sentence with the key number: "Biobío accounts for 30% of sales", not "Sales by region".
+2. **`subtitle` says how to read it**: measure, unit and period.
+3. **Always set `source`.** If the data is made up, use `source: "illustrative data"`.
+4. `data` is a list of rows (`[{ region: "Biobío", sales: 1240 }]`). For a wide table, pass `y: ["revenue", "costs"]`.
+5. Call `safePlot(spec)` as your tool: it never throws and returns `errors`, `warnings` and `suggestions`, each with a `fix`. If `ok` is `false`, fix the spec and call again.
+6. Set `locale: "en"` for English number formats (default is Spanish: `1.234,5`).
+
+## Which type
+
+| To show | `type` | Key fields |
+|---|---|---|
+| Compare categories | `bar` | `x`, `y`, `series?`, `stack?` (`true` / `"percent"`), `top?` |
+| Count rows per category | `countplot` | `x` |
+| Mean per category with a CI | `barplot` or `point` | `x`, `y`, `hue?` |
+| Change over time | `line` | `x` date (`"2024-03"`) or year, `y`, `series?`; `ci: true` with several observations per x |
+| Volume over time | `area` | like `line`; stacks with `series` |
+| Measures on different scales | `line` + `index: true`, or `facet` | **there is no dual axis** |
+| Exponential growth | `line` + `yScale: "log"` | |
+| Relationship between two measures | `regplot` (fit + CI) / `scatter` / `bubble` | `x`, `y`, `hue?`, `size?`, `label?` |
+| Relationship + marginals | `jointplot` | `x`, `y` |
+| Distribution of one measure | `hist` (`kde: true`), `kde`, `ecdf` | `x`, `hue?` |
+| Distribution by category | `box`, `violin`, `strip`, `swarm` | `x` category, `y` measure, `hue?` |
+| Multi-dimensional profile | `radar` | `axis`, `value`, `series` (≤ 4 series) |
+| Hierarchical part-to-whole | `treemap` or `sunburst` | `path: [level1, level2, …]`, `value` |
+| Part-to-whole, ≤ 6 parts | `donut` / `pie` | `label`, `value`; `half: true` for a semicircle |
+| Magnitude on a grid | `heatmap` | `x`, `y`, `value` |
+| A value per region, state or country | `choropleth` (`symbolmap` for totals) | `geo: "chile" \| "usa" \| "world"`, `key`, `value` |
+| Who is connected to whom | `network` | edges `from`, `to`, `value?`; `nodes?` with `group` |
+| Exchanges between a few groups | `chord` | `from`, `to`, `value` |
+| Age structure | `pyramid` | `age`, `sex`, `value` |
+| A process with decisions | `flowchart` | `nodes` (`type`, `lane`), `edges` (`label`) |
+| Flows between stages | `sankey` | `from`, `to`, `value` |
+| One or more numbers | `kpi` | `items: [{ label, value, delta, period, trend, target, good }]` |
+
+seaborn names work (`histplot`, `kdeplot`, `boxplot`, `violinplot`, `lmplot`, `stripplot`, `swarmplot`, `pointplot`), and `hue` is an alias of `series`. Leave `type` out to infer it from the data.
+
+## Most useful options
+
+- `highlight: "Ñuble"`: emphasize one category or series and mute the rest.
+- `dashed` for what is not a firm number (estimates, projections, provisional figures): a name, a list, or a data field (`dashed: "provisional"`). Shapes keep their color, with a hatched fill and a dashed outline. On a time axis, `dashedFrom: 2025` dashes lines, areas and columns from that year on. **Always set `dashedLabel`** ("Projection", "Preliminary") so readers know what the hatching means.
+- `facet: "region"` (+ `columns`): one panel per value, on a shared scale.
+- `time: "year"`: one period at a time (the latest) with % change vs the previous one; in the browser, a slider with play (`slider: false` / `play: false` to turn them off). Treemaps can be colored by change with `colorBy: "change"`.
+- `refLines: [{ y: 600, label: "Target" }]` and `annotations: [{ x: "2024-01", label: "New branch" }]`.
+- `format: "percent" | "currency" | "compact" | "integer"` or `{ prefix, suffix, decimals }`.
+- `xScale` / `yScale: "log"`.
+- `theme: "noche"` or a JSON object (`{ extends, categorical, type, marks, font }`); `palette: [...]` for your own colors.
+- `font: "Poppins"` and `textScale: 1.5` (presentation mode); `configure({ font, textScale })` sets them for every chart.
+- `network` + `focus: "node id"`: center a node and highlight its neighbors.
+- `geo: "usa"`: states match by postal code ("TX"), English or Spanish name, or FIPS ("48"). Alaska and Hawaii are insets; Puerto Rico appears only when your data has it. In the browser, maps zoom on click, Ctrl/⌘ + scroll or pinch.
+
+## Mistakes the library already handles
+
+- More than 8 series → the 9th onward turn gray; `lint` suggests `highlight` or `facet`.
+- Colliding line labels → spread apart with leader lines.
+- Donut with more than 6 parts → folds into "Other".
+- Long category labels → switches to horizontal.
+- Hard-to-tell custom palette → `lint` names the offending pair.
+- Numbers as text ("1.234,5", "12%", "$ 3.000") → parsed automatically.
+- Tens of thousands of points → drawn as batched paths, still fast.
+
+## Outputs
+
+- `plot(spec)` → SVG string. Drop it into HTML, Markdown, an `.svg` file or a PDF.
+- `toHTML([spec1, spec2])` → self-contained page with tooltips, sliders and drill-down.
+- `describe(spec)` → alt text for the chart.
+- `schema` / `toolDefinition()` → JSON Schema and tool definition (Anthropic or OpenAI).
+- CLI: `npx plotagents spec.json -o chart.svg`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Navarrete
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,206 @@
-# Temporary Holding Version
+# plotagents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**Beautiful charts from a single JSON spec, built for AI agents.**
+
+**[Documentation, live examples and playground →](https://carlosnavarrete.cl/plotagents/)**
+
+Data and field names go in; an accessible SVG comes out, with careful typography, colorblind-safe colors and tooltips. 32 chart types: the ones people reach for in seaborn, multi-level treemaps and sunbursts, choropleth maps of Chile, the United States and the world, networks, chord diagrams, population pyramids and flow charts, plus time sliders, small multiples and fully JSON-configurable themes. Zero dependencies. Runs in Node, Deno, Bun and the browser.
+
+```bash
+npm install github:carlosnavarreteliz/plotagents
+```
+
+plotagents is not on the npm registry yet, so install it from GitHub for now; `npm install plotagents` will work once it is published.
+
+```js
+import { plot } from 'plotagents';
+
+const svg = plot({
+  title: 'Biobío accounts for 30% of southern sales',
+  subtitle: 'Sales by region, CLP millions, 2025',
+  source: 'illustrative data',
+  data: [
+    { region: 'Biobío', sales: 1240 },
+    { region: 'Araucanía', sales: 880 },
+    { region: 'Ñuble', sales: 610 },
+  ],
+  x: 'region',
+  y: 'sales',
+  locale: 'en',
+});
+```
+
+![Columns](examples/svg/barras.svg)
+
+The [interactive gallery](https://carlosnavarrete.cl/plotagents/examples/), 61 charts with the code for each one, is also in [`examples/index.html`](examples/index.html). Try any spec live in the [playground](https://carlosnavarrete.cl/plotagents/playground/).
+
+## Why
+
+Agents are good at data and bad at charts: dual axes, 12-slice pies, titles that say nothing. plotagents takes design decisions out of the agent's hands. The rules come from data-visualization teaching for management (Wilke's *Fundamentals of Data Visualization*, the Data Viz Catalogue, the Atlas of Economic Complexity) and are written into the code:
+
+- **The title states the finding.** `lint` nudges toward it and `describe` writes the alt text.
+- **One axis.** There is no dual axis; `index: true` rebases series to 100 and `facet` draws panels on a shared scale.
+- **Labels at the end of every line**, always. When they collide they are spread apart and joined to their point by a thin leader line; a legend appears only when needed.
+- **Every pixel for the data.** The y axis sits inside the plot on its gridline; margins and type scale down on phones; treemaps, sunbursts, horizontal bars, heatmaps and KPI tiles size their own height.
+- **Color follows the entity.** Eight validated colors in a fixed order; "Copper" keeps its color when you filter, drill down or move the time slider. One solid color per category.
+- **Legend and chart are connected.** Hover a legend key to light up its marks, click to pin; line labels and tooltip headers wear their series color.
+- **Estimates look like estimates.** `dashed` hatches the shapes that are projections or provisional figures (same color, striped fill, dashed outline) and `dashedFrom: 2025` turns lines, areas and columns dashed from that point on, over a soft labeled band. The legend says what the hatching means; hovering it lights up just those shapes.
+- **Maps you can explore.** Click a state or region to zoom to it, Ctrl/⌘ + scroll or pinch to zoom, drag to pan; +/−/reset buttons for the keyboard. Hovering outlines the shape instead of dimming the map, and each color class in the legend lights up its regions. With a time slider, colors glide from one year to the next.
+- **Networks you can explore.** Click a node and it glides to the center with its connections highlighted; click again or press Esc to go back.
+- **Thin marks, quiet grid.** 4 px rounded data ends, 2.25 px lines, 2 px surface gaps instead of borders.
+- **Locale-aware numbers.** Spanish (Chile) by default: `1.234,5`, `56,1%`, `$18.500`. `locale: 'en'` gives `1,234.5`.
+
+## Chart types
+
+| Purpose | `type` (aliases) |
+|---|---|
+| Compare categories | `bar` (`barplot` with confidence intervals), `count` (`countplot`) |
+| Change over time | `line` (`lineplot`, `ci` for a confidence band), `area` |
+| Relationships | `scatter`, `bubble`, `regplot` (`lmplot`), `residplot`, `jointplot` |
+| Profiles | `radar` (`spider`) |
+| Distributions | `hist` (`histplot`), `kde` (`kdeplot`), `ecdf`, `box` (`boxplot`), `violin`, `strip`, `swarm` (`beeswarm`), `point` (`pointplot`) |
+| Part-to-whole | `treemap` (any depth, with % change over time), `sunburst`, `donut`, `pie` |
+| Maps | `choropleth` (Chile by region, US by state, world by country, any GeoJSON), `symbolmap` |
+| Networks and flows | `network`, `chord`, `sankey`, `flowchart` (with swimlanes) |
+| Populations | `pyramid` |
+| Grids | `heatmap` |
+| Numbers | `kpi` |
+
+Leave `type` out and it is inferred: dates → `line`, two measures → `scatter`, `source`/`target` → `sankey`, `path` → `treemap`, categories → `bar`. Every option is documented in [`docs/charts.md`](docs/charts.md).
+
+| | | |
+|---|---|---|
+| ![](examples/svg/lineas.svg) | ![](examples/svg/treemap-niveles.svg) | ![](examples/svg/regresion.svg) |
+| ![](examples/svg/violin.svg) | ![](examples/svg/sunburst.svg) | ![](examples/svg/histograma.svg) |
+| ![](examples/svg/radar.svg) | ![](examples/svg/sankey.svg) | ![](examples/svg/conjunto.svg) |
+| ![](examples/svg/mapa-chile.svg) | ![](examples/svg/cuerdas.svg) | ![](examples/svg/piramide.svg) |
+
+## Time, panels and drill-down
+
+```js
+// One period at a time with a slider and a play button (d3plus-style `time`).
+plot({ type: 'treemap', data, path: ['sector', 'product'], value: 'value', time: 'year' });
+
+// Time series: in the browser, render() adds a range slider with an overview.
+render('#chart', { type: 'line', data, x: 'month', y: 'sales', series: 'region' });
+
+// Small multiples (seaborn's col / col_wrap) with shared scales and colors.
+plot({ type: 'area', data, x: 'month', y: 'sales', facet: 'region', columns: 3 });
+
+// Treemaps and sunbursts of any depth; click a group to drill down.
+plot({ type: 'sunburst', data, path: ['area', 'unit', 'item'], value: 'amount', focus: ['Teaching'] });
+
+// Log scales with 1-2-5 ticks and no empty decades.
+plot({ type: 'line', data, x: 'month', y: 'users', series: 'platform', yScale: 'log' });
+```
+
+## One switch for fonts and text size
+
+```js
+import { configure } from 'plotagents';
+
+configure({ font: 'Poppins', textScale: 1.5 });   // every chart from now on
+plot({ ...spec, textScale: 2 });                  // or per chart: presentation mode
+configure(null);                                  // back to defaults
+```
+
+`font` takes a Google Fonts name (it is loaded for you in the browser and in `toHTML()`), a CSS stack or `{ family, import }`. `textScale` multiplies every text size and the layout is recomputed with the real sizes, so labels at ×2 still never overlap. `configure()` also accepts `locale`, `theme`, `palette` or any other spec option.
+
+## Themes are JSON
+
+Everything visual is a JSON object merged over a base theme, so an agent can apply a brand without touching code. See [`docs/themes.md`](docs/themes.md).
+
+```js
+plot({
+  ...spec,
+  theme: {
+    extends: 'papel',              // or 'noche' (dark)
+    categorical: 'okabe-ito',      // palette name or a list of colors in fixed order
+    surface: '#FFFFFF',
+    font: { family: "'Poppins', sans-serif" },
+    type: { title: 22, titleWeight: 700 },
+    marks: { lineWidth: 3, barRadius: 8, barMax: 44 },
+    axes: { inside: false },
+  },
+});
+```
+
+`validatePalette(colors)` checks a custom palette with the same tests the built-in one passed (lightness band, chroma floor, colorblind separation, normal-vision separation), and `lint` runs it for you.
+
+## SVG, not Canvas
+
+plotagents renders SVG. Dense charts (more than 1,500 points) are drawn automatically as one path per color, with a nearest-point tooltip layer, which paints faster than Canvas while keeping vector output, server-side rendering and accessible text. The benchmark and the reasoning are in [`docs/rendering.md`](docs/rendering.md).
+
+| Points | SVG, one node per point | Canvas | plotagents (batched SVG) |
+|---|---|---|---|
+| 5,000 | 62 ms | 30 ms | 12 ms |
+| 20,000 | 671 ms | 100 ms | 38 ms |
+| 50,000 | 1,468 ms | 357 ms | 123 ms |
+
+## API
+
+```js
+import { plot, safePlot, lint, describe, render, toHTML, schema, toolDefinition, validatePalette } from 'plotagents';
+```
+
+| Function | Returns |
+|---|---|
+| `plot(spec)` | SVG string. Throws `PlotError` with a fix hint. |
+| `safePlot(spec)` | `{ ok, svg, description, errors, warnings, suggestions }`. Never throws. |
+| `lint(spec)` | Review of the spec without drawing: errors and design suggestions. |
+| `describe(spec)` | Alt text ("Highest: Biobío with 1,240 (30%)…"). |
+| `render(el, spec)` | Browser: tooltips, responsive width, time sliders and drill-down. |
+| `toHTML(specs)` | A self-contained, interactive HTML page in one file. |
+| `schema` / `toolDefinition({ flavor })` | JSON Schema of the spec and a tool definition for Claude (`anthropic`) or OpenAI (`openai`). |
+| `validatePalette(colors, opts)` | `{ ok, checks }`. |
+
+In the browser without a bundler, `<script src="dist/plotagents.js"></script>` defines `window.plotagents`. Full types are in [`index.d.ts`](index.d.ts) and every option in [`schema.json`](schema.json).
+
+## As an agent tool
+
+```js
+import Anthropic from '@anthropic-ai/sdk';
+import { safePlot, toolDefinition } from 'plotagents';
+
+const client = new Anthropic();
+const res = await client.messages.create({
+  model: process.env.ANTHROPIC_MODEL, // the model you use
+  max_tokens: 4096,
+  tools: [toolDefinition()],
+  messages: [{ role: 'user', content: 'Plot the distribution of service times per clinic: …' }],
+});
+const call = res.content.find((b) => b.type === 'tool_use');
+const { ok, svg, errors, suggestions } = safePlot(call.input);
+// If !ok, send `errors` back as the tool_result: every error carries a `fix`.
+```
+
+[`AGENTS.md`](AGENTS.md) is a short guide meant to be pasted into an agent's system prompt.
+
+## CLI
+
+```bash
+npx plotagents spec.json -o chart.svg       # SVG
+npx plotagents specs.json -o report.html    # several interactive charts on one page
+npx plotagents spec.json --lint             # review and suggestions
+npx plotagents --tool                       # tool definition
+```
+
+## Built-in palette
+
+| Theme | Surface | Categorical (fixed order) |
+|---|---|---|
+| `papel` | `#FCFBF9` | `#3A47B8` `#D42A5E` `#E8A33D` `#1E9C89` `#7B5CD6` `#B5562E` `#5BA3E0` `#8E9A2F` |
+| `noche` | `#0B0F2B` | `#6170E0` `#E63369` `#C4851C` `#22A892` `#9780E8` `#D06A3E` `#499BDA` `#909D2D` |
+
+Both pass the lightness, chroma, colorblind (adjacent ΔE OKLab ≥ 8) and normal-vision (≥ 15) checks. The order is part of the validation. Typeface: Mozilla Text, falling back to `system-ui`.
+
+## Development
+
+```bash
+npm test                 # tests (node:test)
+npm run build            # dist/plotagents.js for the browser
+npm run examples         # regenerates examples/svg and examples/index.html
+npm run site             # builds the GitHub Pages site into _site/ (docs, gallery, playground)
+```
+
+MIT © Carlos Navarrete

package/bin/plotagents.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+// CLI: plotagents spec.json [-o salida.svg|.html] [--lint] [--schema] [--tool]
+//   cat spec.json | plotagents > grafico.svg
+import { readFileSync, writeFileSync } from 'node:fs';
+import { plot, toHTML, lint, schema, toolDefinition, describe } from '../src/index.js';
+
+const args = process.argv.slice(2);
+const flag = (f) => args.includes(f);
+const opt = (f) => { const i = args.indexOf(f); return i >= 0 ? args[i + 1] : undefined; };
+const input = args.find((a, i) => !a.startsWith('-') && args[i - 1] !== '-o' && args[i - 1] !== '--out');
+
+if (flag('-h') || flag('--help')) {
+  console.log(`plotagents — gráficos bellos desde un spec JSON
+
+Uso:
+  plotagents spec.json                 SVG a la salida estándar
+  plotagents spec.json -o grafico.svg  guarda SVG
+  plotagents spec.json -o reporte.html página HTML interactiva (acepta un arreglo de specs)
+  plotagents spec.json --lint          revisa el spec y sugiere mejoras (JSON)
+  plotagents spec.json --describe      descripción en texto del gráfico
+  plotagents --schema                  JSON Schema del spec
+  plotagents --tool [openai]           definición de herramienta para agentes
+  cat spec.json | plotagents           también lee de stdin`);
+  process.exit(0);
+}
+if (flag('--schema')) { console.log(JSON.stringify(schema, null, 2)); process.exit(0); }
+if (flag('--tool')) { console.log(JSON.stringify(toolDefinition({ flavor: opt('--tool') === 'openai' ? 'openai' : 'anthropic' }), null, 2)); process.exit(0); }
+
+let raw;
+try { raw = input ? readFileSync(input, 'utf8') : readFileSync(0, 'utf8'); } catch (e) { console.error('No pude leer el spec:', e.message); process.exit(2); }
+let spec;
+try { spec = JSON.parse(raw); } catch (e) { console.error('El spec no es JSON válido:', e.message); process.exit(2); }
+
+if (flag('--lint')) {
+  const list = Array.isArray(spec) ? spec : [spec];
+  const out = list.map(lint);
+  console.log(JSON.stringify(Array.isArray(spec) ? out : out[0], null, 2));
+  process.exit(out.every((r) => r.ok) ? 0 : 1);
+}
+try {
+  if (flag('--describe')) { console.log((Array.isArray(spec) ? spec : [spec]).map(describe).join('\n')); process.exit(0); }
+  const outFile = opt('-o') ?? opt('--out');
+  const html = (outFile && outFile.endsWith('.html')) || flag('--html') || Array.isArray(spec);
+  const result = html ? toHTML(spec, { title: (Array.isArray(spec) ? spec[0] : spec).title || 'plotagents' }) : plot(spec);
+  if (outFile) { writeFileSync(outFile, result); console.error(`✓ ${outFile}`); } else process.stdout.write(result);
+} catch (e) {
+  console.error(e.message);
+  process.exit(1);
+}