plotagents 0.5.0 → 0.7.0

package/AGENTS.md

@@ -24,6 +24,7 @@ const svg = plot({ type, data, x, y, series, title, subtitle, source });
 | 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 |
+| A project plan or schedule | `gantt` | `task`, `start`, `end` (or `duration`), `group?`, `progress?`, `dependsOn?`, `today?`, `collapsed?` |
 | 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"` | |
@@ -35,28 +36,37 @@ const svg = plot({ type, data, x, y, series, title, subtitle, source });
 | 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` |
+| A value per region, state or country | `choropleth` (`symbolmap` for totals) | `geo: "chile" \| "usa" \| "world"` or any GeoJSON/TopoJSON object, `key`, `value` (text → one color per category) |
+| Dots at real places on a street map | `pointmap` | `lon`, `lat` (auto-detected), `size?`, `hue?`, `value?`, `label?`; `tiles: "osm"` (default) / `"esri-gray"` / `"esri-dark"`, or carto-* / mapbox-* with `tilesKey` |
+| Who is connected to whom | `network` | edges `from`, `to`, `value?`; `nodes?` with `group`; `layout?` |
 | 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 }]` |
+| What comes up most in text | `wordcloud` | `text` (field or raw text), `value?`, `series?`; prefer `bar` + `top` to compare exactly |
 
 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.
+- `highlight: "Ñuble"`: emphasize one category or series and mute the rest. `exclude: ["Maule"]` drops entries and recomputes the chart; colors stay put.
+- `legend: "top" | "bottom" | "left" | "right" | false`: where the legend goes (top by default).
+- `colorScale: "viridis"`: any matplotlib colormap for heatmaps, maps and treemaps by change (`"RdBu"` diverges around 0; `_r` reverses; or a list of colors). `palette: "tab10"` for categories.
 - `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"`.
+- `time: "year"`: one period at a time (the latest) with % change vs the previous one. Time controls are **off by default**: add `slider: true` only when the person asks to move through periods (buttons for ≤ 8 periods, a minimal slider otherwise; `"buttons"` / `"slider"` force one, `play: false` hides play). 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.
+- Your own map: `geo: <GeoJSON or TopoJSON>`; the matching property is found for you (`featureKey` to force it). Add `markers: [{ lon, lat, label }]`, `layers: [{ geo, label }]` for rivers or routes, and `fitTo: ["Biobío"]` or a `[lonMin, latMin, lonMax, latMax]` box to zoom.
+- `gantt`: day `end` dates are inclusive; a row without `end` is a milestone. Always set `today` on a live plan. `collapsed: ["Phase 2"]` (or `true`) folds phases into one summary bar; in the browser a click on a phase toggles it.
+- `network` + `layout: "force" | "circular" | "radial" | "concentric" | "clusters" | "tree" | "grid"` picks the placement; `curveness: 0` straightens edges.
+- `pointmap` draws on OpenStreetMap tiles by default (`tiles: "esri-gray"`, `"mapbox-light"` + `tilesKey`, or your own `{ url, attribution }`). Tiles load only when the SVG is inline or in `toHTML`, not inside `<img>`.
+- Your own look for every chart: `registerTheme("acme", { background, text, grid: { color, dash }, categorical: "tab10", font })` then `configure({ theme: "acme" })`.
 - `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
@@ -69,6 +79,16 @@ seaborn names work (`histplot`, `kdeplot`, `boxplot`, `violinplot`, `lmplot`, `s
 - Numbers as text ("1.234,5", "12%", "$ 3.000") → parsed automatically.
 - Tens of thousands of points → drawn as batched paths, still fast.
 
+## Dashboards
+
+When someone asks for a dashboard, call `safeDashboard({ title, subtitle, source, data, kpis, charts, filters })` (tool: `toolDefinition({ kind: 'dashboard' })`). Layout, widths, shared colors and filters are decided for you:
+
+- `title` is the **question** the dashboard answers; every chart still gets its finding as title.
+- At most **5 KPIs**, computed from `data` when possible: `{ label, field, agg: "sum", compare: { field: "year", current: 2025, previous: 2024 }, trendBy: "month" }`.
+- **4–6 charts**. The first time series (or the one with `primary: true`) goes full width; the rest fill balanced rows.
+- `filters: ["region", "channel"]` become buttons that filter every chart and KPI.
+- No more than one donut; one `source` for the page.
+
 ## Outputs
 
 - `plot(spec)` → SVG string. Drop it into HTML, Markdown, an `.svg` file or a PDF.

package/README.md

@@ -4,14 +4,12 @@
 
 **[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.
+Data and field names go in; an accessible SVG comes out, with careful typography, colorblind-safe colors and tooltips. 34 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, flow charts and Gantt charts, plus word clouds, a dashboard builder with best-practice layouts, opt-in time controls, small multiples and fully JSON-configurable themes. Zero dependencies. Runs in Node, Deno, Bun and the browser.
 
 ```bash
-npm install github:carlosnavarreteliz/plotagents
+npm install 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';
 
@@ -42,11 +40,12 @@ Agents are good at data and bad at charts: dual axes, 12-slice pies, titles that
 - **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.
+- **Color follows the entity.** Eight validated colors in a fixed order; "Copper" keeps its color when you filter, drill down or move through periods. One solid color per category.
+- **Legend and chart are connected.** Hover a legend key to light up its marks, click to pin, shift + click to drop that entry (axes and shares recompute, colors stay put). In treemaps a click zooms the whole plot to the category. The legend goes top by default, or `legend: "bottom" | "left" | "right"`.
+- **Tooltips that never cover the title.** They sit next to the hovered mark, stay inside the chart, and their header wears the mark's color with white or dark text picked by contrast. Arrow keys walk through the data.
 - **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.
+- **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. Moving through years, colors glide from one to the next.
+- **Networks you can explore.** Curved edges in the source node's color, sized nodes and labels that never pile up. Pick the placement with `layout` (force, circular, radial, concentric, clusters, tree, grid). 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`.
 
@@ -60,11 +59,14 @@ Agents are good at data and bad at charts: dual axes, 12-slice pies, titles that
 | 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` |
+| Maps | `choropleth` (Chile by region, US by state, world by country, or your own GeoJSON / TopoJSON with markers, layers and framing), `symbolmap`, `pointmap` (lat/lon dots over OpenStreetMap or Mapbox tiles) |
+| Projects | `gantt` (`timeline`, `roadmap`): phases that fold and unfold, progress, milestones, dependencies and a today line |
 | Networks and flows | `network`, `chord`, `sankey`, `flowchart` (with swimlanes) |
 | Populations | `pyramid` |
 | Grids | `heatmap` |
 | Numbers | `kpi` |
+| Text | `wordcloud` (words sized by frequency, or raw text to count) |
+| Dashboards | `dashboard({ title, kpis, charts, filters })`: a whole HTML dashboard with best-practice layout ([guide](docs/dashboards.md)) |
 
 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).
 
@@ -78,11 +80,12 @@ Leave `type` out and it is inferred: dates → `line`, two measures → `scatter
 ## 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' });
+// One period at a time (the latest). Controls are opt-in: `slider: true` adds
+// period buttons (few periods) or a minimal slider (many), with a play button.
+plot({ type: 'treemap', data, path: ['sector', 'product'], value: 'value', time: 'year', slider: true });
 
-// Time series: in the browser, render() adds a range slider with an overview.
-render('#chart', { type: 'line', data, x: 'month', y: 'sales', series: 'region' });
+// Time series: `slider: true` adds a two-handle range in the browser.
+render('#chart', { type: 'line', data, x: 'month', y: 'sales', series: 'region', slider: true });
 
 // Small multiples (seaborn's col / col_wrap) with shared scales and colors.
 plot({ type: 'area', data, x: 'month', y: 'sales', facet: 'region', columns: 3 });
@@ -125,6 +128,15 @@ plot({
 });
 ```
 
+Register it once and every chart uses it; the default look never changes unless you ask:
+
+```js
+registerTheme('acme', { background: '#FFF', text: '#111827', grid: { color: '#EEF0F4', dash: '2 3' }, categorical: 'tab10', font: 'Inter' });
+configure({ theme: 'acme' });
+```
+
+Every matplotlib colormap works by name for heatmaps, maps and treemaps by change: `colorScale: 'viridis'`, `'RdBu_r'`, or your own list of colors ([color scales](docs/colorscales.md)).
+
 `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
@@ -149,7 +161,7 @@ import { plot, safePlot, lint, describe, render, toHTML, schema, toolDefinition,
 | `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. |
+| `render(el, spec)` | Browser: tooltips, responsive width, drill-down, and time controls when the spec asks for them. |
 | `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 }`. |

package/bin/plotagents.js

@@ -1,48 +1,72 @@
 #!/usr/bin/env node
-// CLI: plotagents spec.json [-o salida.svg|.html] [--lint] [--schema] [--tool]
+// CLI: plotagents spec.json [-o salida.svg|.html] [--lint] [--schema] [--tool [openai] [dashboard]]
 //   cat spec.json | plotagents > grafico.svg
+// A spec with a `charts` list is a dashboard: it renders to a self-contained HTML page.
 import { readFileSync, writeFileSync } from 'node:fs';
-import { plot, toHTML, lint, schema, toolDefinition, describe } from '../src/index.js';
+import { plot, toHTML, lint, schema, toolDefinition, describe, dashboard, lintDashboard, dashboardSchema } from '../src/index.js';
+
+// `plotagents … | head` closes the pipe early: exit quietly instead of crashing.
+for (const stream of [process.stdout, process.stderr]) {
+  stream.on('error', (e) => { if (e && e.code === 'EPIPE') process.exit(0); throw e; });
+}
 
 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');
+const VALUE_FLAGS = new Set(['-o', '--out', '--tool']);
+const TOOL_ARGS = new Set(['openai', 'anthropic', 'dashboard', 'chart']);
+const input = args.find((a, i) => !a.startsWith('-') && !VALUE_FLAGS.has(args[i - 1]) && !(TOOL_ARGS.has(a) && args.slice(0, i).includes('--tool')));
+const print = (s) => process.stdout.write(s.endsWith('\n') ? s : s + '\n');
 
 if (flag('-h') || flag('--help')) {
-  console.log(`plotagents — gráficos bellos desde un spec JSON
+  print(`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 tablero.json -o tablero.html  dashboard (un spec con \`charts: [...]\`)
   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
+  plotagents --schema [dashboard]      JSON Schema del spec (o del dashboard)
+  plotagents --tool [openai] [dashboard]  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); }
+// Tool and schema flags accept "openai" and/or "dashboard" in any order after the flag.
+const after = (f) => { const i = args.indexOf(f); return i >= 0 ? args.slice(i + 1).filter((a) => TOOL_ARGS.has(a)) : []; };
+if (flag('--schema')) { print(JSON.stringify(after('--schema').includes('dashboard') ? dashboardSchema : schema, null, 2)); process.exit(0); }
+if (flag('--tool')) {
+  const t = after('--tool');
+  print(JSON.stringify(toolDefinition({ flavor: t.includes('openai') ? 'openai' : 'anthropic', kind: t.includes('dashboard') ? 'dashboard' : 'chart' }), 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); }
 
+const isDashboard = (s) => !!s && typeof s === 'object' && !Array.isArray(s) && Array.isArray(s.charts);
+
 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));
+  const out = list.map((s) => (isDashboard(s) ? lintDashboard(s) : lint(s)));
+  print(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);
+  if (isDashboard(spec)) {
+    if (flag('--describe')) { print([spec.title, ...spec.charts.map((c) => { try { return describe({ data: spec.data, ...c }); } catch (e) { return e.message.split('\n')[0]; } })].filter(Boolean).join('\n')); process.exit(0); }
+    const html = dashboard(spec);
+    if (outFile) { writeFileSync(outFile, html); console.error(`✓ ${outFile}`); } else process.stdout.write(html);
+  } else {
+    if (flag('--describe')) { print((Array.isArray(spec) ? spec : [spec]).map(describe).join('\n')); process.exit(0); }
+    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);

package/dist/plotagents-geo.js

@@ -1,4 +1,4 @@
-/*! plotagents 0.5.0 · MIT · https://github.com/carlosnavarreteliz/plotagents */
+/*! plotagents 0.7.0 · MIT · https://github.com/carlosnavarreteliz/plotagents */
 (function (global) {
 'use strict';
 var __defs = {}, __cache = {};