plotagents 0.0.0-stage → 0.7.0

package/docs/dashboards.md

@@ -0,0 +1,79 @@
+# Dashboards
+
+`dashboard(spec)` turns a handful of chart specs into a finished, self-contained HTML dashboard. Like a single chart, the design decisions come built in: you say what goes on the page, and the library decides where and how.
+
+```js
+import { dashboard } from 'plotagents';
+import { writeFileSync } from 'node:fs';
+
+writeFileSync('sales.html', dashboard({
+  title: 'How are southern sales doing?',
+  subtitle: 'Sales by month, region and channel, 2024–2025, CLP millions',
+  source: 'Commercial ERP',
+  updated: '2026-01-05',
+  locale: 'en',
+  data: sales,                              // shared rows
+  kpis: [
+    { label: 'Sales 2025', field: 'sales', agg: 'sum', format: 'compact',
+      compare: { field: 'year', current: 2025, previous: 2024 }, trendBy: 'month' },
+    { label: 'Orders 2025', field: 'orders', agg: 'sum', format: 'compact',
+      compare: { field: 'year', current: 2025, previous: 2024 } },
+    { label: 'Online share', value: 0.361, delta: 0.13, format: 'percent', period: 'vs 2024' },
+  ],
+  filters: ['region', 'channel'],
+  charts: [
+    { type: 'line', x: 'month', y: 'sales', series: 'region', highlight: 'Ñuble',
+      title: 'Ñuble grew 37% this year, faster than any other region' },
+    { type: 'choropleth', geo: 'chile', key: 'region', value: 'sales', fitTo: ['Biobío', 'Ñuble', 'Maule', 'Araucanía'],
+      title: 'Biobío makes 36% of sales' },
+    { type: 'bar', x: 'channel', y: 'sales', series: 'year',
+      title: 'Online is the only channel growing strongly' },
+    { type: 'treemap', path: ['region', 'channel'], value: 'sales',
+      title: 'Physical stores are still half the business' },
+  ],
+}));
+```
+
+The page works without JavaScript: every chart is drawn on the server, so it opens in any browser, prints and converts to PDF. When the browser build is available (it is, in Node), the page also gets tooltips, map zoom and live filters. In a web app, `renderDashboard('#board', spec)` draws the same dashboard into an element.
+
+## What it decides for you
+
+These defaults come from dashboard design practice: Stephen Few's *Information Dashboard Design*, the Z-pattern of reading, and what makes business dashboards hard to read.
+
+| Rule | What plotagents does |
+|---|---|
+| **One question per dashboard** | The `title` is the question ("How are southern sales doing?"). `lintDashboard` warns above 9 charts and suggests splitting above 6. |
+| **Numbers first** | KPIs go in one row at the top, at most 5 (warning above). Each one has a label, the figure, its change with an arrow **and** a sign (never color alone), the comparison period and an optional sparkline. |
+| **Z-pattern reading** | The main chart comes right after the KPIs, at full width: the one marked `primary: true`, or else the first time series. |
+| **Full rows, no holes** | A 12-column grid in balanced rows: 2 charts → 6 + 6 (8 + 4 when one is wide), 3 → 4 + 4 + 4, 4 → two rows of two, 5 → 3 + 2. Panels in a row share a height. |
+| **Width follows the chart** | Time series, Gantt charts, heatmaps and flows read left to right, so they get wide panels. Donuts, KPIs and short rankings get narrow ones. Chile's map gets a narrow column. |
+| **Same thing, same color** | One color map across every chart: "Ñuble" is the same color in the line, the treemap and the bars. `colors` pins colors for the whole page. |
+| **One voice** | One theme, locale and typeface for every panel. The source appears once, at the bottom; a chart keeps its own source only when it differs. |
+| **Filters as buttons** | `filters` become buttons when a field has up to 6 values, and a dropdown when it has more. They filter every chart that has the field, recompute the KPIs and say what is filtered in each subtitle. A filter on a chart's `time` field moves that chart to the chosen period. |
+| **Phones** | One column in reading order; KPIs in two columns. |
+| **Print** | Panels don't break across pages; the filter bar is not sticky on paper. |
+
+## Spec
+
+| Option | Meaning |
+|---|---|
+| `title`, `subtitle` | The question, and the scope (measure, unit, period). |
+| `source`, `updated`, `note` | Footer and header metadata. |
+| `locale`, `theme`, `font`, `palette` | Applied to every chart (`theme: "noche"` for a dark dashboard). |
+| `data` | Shared rows. Charts without `data` use them; computed KPIs and filters work on them. |
+| `kpis` | `[{ label, value, delta, period, trend, good, format }]` (fixed) or `[{ label, field, agg, over, scale, compare, trendBy, format }]` (computed). `agg`: `sum`, `mean`, `median`, `min`, `max`, `count`, `distinct`, `ratio` (with `over`). `compare: { field, current, previous }` shows the current period and its change. `trendBy: "month"` draws the sparkline. |
+| `charts` | Chart specs, as in `plot()`. Per chart: `primary: true`, `size: "full" \| "large" \| "medium" \| "small"` or `span` (of 12). |
+| `filters` | `["region"]` or `[{ field, label, control: "buttons" \| "select", value }]`. |
+| `layout` | `"auto"` (default), `"executive"` (main chart full width, then pairs) or `"grid"` (equal panels). |
+| `colors` | `{ "Biobío": "#3A47B8" }` for every chart. |
+
+## For agents
+
+```js
+import { safeDashboard, toolDefinition } from 'plotagents';
+
+const tool = toolDefinition({ kind: 'dashboard' });   // JSON Schema of the dashboard spec
+const { ok, html, errors, warnings, suggestions } = safeDashboard(input);
+```
+
+`safeDashboard` never throws. It reviews the dashboard as a whole (too many charts or KPIs, several pies, mixed themes, filters on fields no chart has, panels without a title) and every chart in it, tagging each issue with the chart's number and title so the model knows which one to fix. `planDashboard(spec)` returns the layout decisions (panels, widths, rows, colors, filters) without drawing anything.

package/docs/getting-started.md

@@ -0,0 +1,142 @@
+# Getting started
+
+plotagents turns one JSON object into a finished, accessible SVG chart. You pass rows of data and name the fields; the library makes every design decision: chart layout, colors, labels, number formats and spacing.
+
+## Install
+
+```bash
+npm install plotagents
+```
+
+Or straight from GitHub, for the latest unreleased changes:
+
+```bash
+npm install github:carlosnavarreteliz/plotagents
+```
+
+Node 18 or later, Deno and Bun work out of the box. The package has no dependencies.
+
+## Your first chart
+
+```js
+import { plot } from 'plotagents';
+
+const svg = plot({
+  type: 'bar',
+  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',
+});
+```
+
+`svg` is a string. Write it to a `.svg` file, put it in HTML or Markdown, or convert it to PDF or PNG with any SVG tool.
+
+## Anatomy of a spec
+
+| Field | What it is |
+|---|---|
+| `type` | The chart type, such as `bar`, `line` or `treemap`. Leave it out to infer it from the data. |
+| `data` | A list of rows: `[{ region: "Biobío", sales: 1240 }]`. |
+| `x`, `y`, `series` | Which field goes where. Each chart type documents its own roles in the [chart reference](charts.md). |
+| `title` | The finding, as a full sentence with the key number. |
+| `subtitle` | How to read the chart: measure, unit and period. |
+| `source` | Where the data comes from. Use `"illustrative data"` when it is made up. |
+| `locale` | `"es"` (the default, `1.234,5`) or `"en"` (`1,234.5`). |
+
+### Wide tables
+
+When each measure is its own column, pass a list in `y` and each field becomes a series:
+
+```js
+plot({
+  type: 'line',
+  data: [
+    { month: '2025-01', revenue: 120, costs: 90 },
+    { month: '2025-02', revenue: 132, costs: 94 },
+  ],
+  x: 'month',
+  y: ['revenue', 'costs'],
+});
+```
+
+### Numbers written as text
+
+Values such as `"1.234,5"`, `"12%"` or `"$ 3.000"` are parsed automatically, so data copied from a spreadsheet works without cleaning.
+
+## In the browser
+
+Without a bundler, load the browser build and call `render()`. It draws into an element and adds tooltips, responsive width, time sliders and drill-down.
+
+```html
+<div id="chart"></div>
+<script src="https://cdn.jsdelivr.net/gh/carlosnavarreteliz/plotagents@master/dist/plotagents.js"></script>
+<script>
+  plotagents.render('#chart', {
+    type: 'line',
+    data: [
+      { month: '2025-01', sales: 120 },
+      { month: '2025-02', sales: 140 },
+      { month: '2025-03', sales: 135 },
+    ],
+    x: 'month',
+    y: 'sales',
+    title: 'Sales rose 12% in the first quarter',
+    locale: 'en',
+  });
+</script>
+```
+
+The same file ships in the package as `dist/plotagents.js`. Maps need the geometries too: add `dist/plotagents-geo.js` after `plotagents.js`.
+
+`render()` returns a handle with `update(spec)` to redraw with a new spec and `destroy()` to remove the chart and its listeners.
+
+## A whole report in one file
+
+`toHTML()` builds a self-contained, interactive page with the library inlined, so it works offline and from a file.
+
+```js
+import { writeFileSync } from 'node:fs';
+import { toHTML } from 'plotagents';
+
+writeFileSync('report.html', toHTML([spec1, spec2], { title: 'Monthly report', lang: 'en', columns: 2 }));
+```
+
+## From the command line
+
+```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 spec.json --describe         # alt text
+npx plotagents --tool                       # tool definition for an agent
+```
+
+The CLI also reads a spec from standard input: `cat spec.json | npx plotagents > chart.svg`.
+
+## Catching mistakes
+
+`plot()` throws a `PlotError` with a hint when a spec cannot be drawn. `safePlot()` never throws, and `lint()` reviews a spec without drawing it:
+
+```js
+import { safePlot } from 'plotagents';
+
+const { ok, svg, errors, warnings, suggestions } = safePlot(spec);
+if (!ok) console.log(errors.map((e) => `${e.message} → ${e.fix}`));
+```
+
+Every error, warning and suggestion carries a `fix` that says what to change.
+
+## Next steps
+
+- Browse the [gallery](../examples/) to find the chart you need and copy its code.
+- Try specs live in the [playground](../playground/).
+- Read the [chart reference](charts.md) for every option of every type.
+- Give an agent the [agent guide](agents.md) and the tool definition.

package/docs/rendering.md

@@ -0,0 +1,47 @@
+# Rendering: SVG or Canvas?
+
+**Decision: SVG everywhere, with automatic path batching for dense marks.** Canvas was evaluated and rejected: batched SVG is faster than Canvas on every size we tested and keeps the properties that matter for a library used by agents.
+
+## What we measured
+
+Scatter plot, two colors, 720 × 420 px, Chromium (Playwright), time from inserting the markup to the second animation frame. Same machine, same data.
+
+| Points | SVG, one `<circle>` per point | Canvas 2D (`arc` + `fill`) | SVG, one `<path>` per color | plotagents (batched SVG, full chart) |
+|---|---|---|---|---|
+| 1,000 | 32 ms | 29 ms | 22 ms | 26 ms |
+| 5,000 | 62 ms | 30 ms | 13 ms | 12 ms |
+| 20,000 | 671 ms · 2.9 MB | 100 ms | 37 ms | 38 ms · 2.1 MB |
+| 50,000 | 1,468 ms · 7.2 MB | 357 ms | 138 ms | 123 ms · 3.4 MB |
+
+The cost of naive SVG is the DOM: one element per mark. Drawing all circles of one color as arcs inside a single `<path>` removes that cost, and the browser rasterizes one path faster than a script can issue tens of thousands of Canvas calls.
+
+Reproduce it with `node scripts/bench.js` (needs Playwright with Chromium installed).
+
+## Why SVG wins for this library
+
+| Need | SVG | Canvas |
+|---|---|---|
+| Render on a server, in Node, with zero dependencies | Yes: SVG is a string | Needs a native module (`node-canvas`) or a headless browser |
+| An agent can read and check its own output | Yes: titles, labels and values are text | No: a bitmap |
+| Accessibility (`<title>`, `<desc>`, screen readers, text selection) | Built in | Must be rebuilt by hand next to the canvas |
+| Crisp at any zoom, print and PDF | Vector | Fixed resolution; must re-render for each pixel ratio |
+| Paste into slides, Word, Figma, Markdown, email | Works as a file | Only as an image |
+| Theming with CSS, dark mode, hover states | CSS classes | Manual redraw |
+| 50,000+ points | Fast with batching (above) | Fast |
+
+Canvas only wins when a chart needs hundreds of thousands of marks redrawn every frame, such as live streaming or animated particle fields. That is outside what a chart for decisions needs, and well past the point where a heatmap or a density plot (`kde`, `hist`) tells the story better than overplotted points.
+
+## How batching works
+
+`dotLayer()` in `src/svg.js` takes the circles a chart wants to draw:
+
+- **Up to 1,500 points:** one `<circle>` each, with its own tooltip and hover state.
+- **More than 1,500 points:** circles are grouped by style (color, radius, opacity) and each group becomes one `<path>` of arcs. A transparent `<rect class="pa-near">` carries the coordinates and tooltip text of up to 20,000 points, and the browser layer finds the nearest point within 14 px on hover and rings it.
+
+Scatter, bubble, regplot, residplot, jointplot, strip and swarm use it automatically. No option is needed.
+
+## Other performance choices
+
+- **Text measurement without a DOM.** Width tables calibrated for humanist sans faces let labels be fitted, wrapped and truncated identically in Node and in the browser.
+- **Numbers rounded to two decimals** in all coordinates keeps files small.
+- **One file for the browser.** `dist/plotagents.js` (no dependencies) is inlined by `toHTML()` so interactive pages work offline, from a file, or inside an artifact.

package/docs/themes.md

@@ -0,0 +1,116 @@
+# Themes
+
+A theme is a JSON object. Pass a name or an object; objects are deep-merged over a base theme, so you only write what changes.
+
+```js
+plot({ ...spec, theme: 'noche' });                         // built-in dark theme
+plot({ ...spec, theme: { extends: 'noche', marks: { lineWidth: 3 } } });
+plot({ ...spec, palette: 'okabe-ito' });                    // shortcut for theme.categorical
+plot({ ...spec, ramp: 'teal' });                            // shortcut for theme.sequential
+```
+
+## Library-wide defaults
+
+```js
+configure({ font: 'Poppins', textScale: 1.4, theme: { extends: 'papel', marks: { lineWidth: 2.5 } } });
+```
+
+Every later `plot()`, `render()`, `toHTML()` and dashboard starts from these values; the spec always wins. A spec's own `theme` object is deep-merged **over** the global theme, so `configure({ theme: 'noche' })` plus `theme: { marks: { barRadius: 0 } }` stays dark. `configure()` returns the current defaults and `configure(null)` clears them.
+
+## Your own theme, everywhere
+
+The default theme (`papel`) never changes unless you ask. To restyle every chart, register a theme once and make it the default:
+
+```js
+import { registerTheme, configure } from 'plotagents';
+
+registerTheme('acme', {
+  extends: 'papel',              // or 'noche', or another registered theme
+  background: '#FFFFFF',         // alias of surface
+  text: '#111827',               // alias of ink
+  lede: '#4B5563',
+  muted: '#6B7280',
+  grid: { color: '#EEF0F4', dash: '2 3', width: 1 },
+  axis: '#C7CBD6',
+  categorical: 'tab10',          // any palette or matplotlib qualitative map
+  sequential: 'viridis',         // any colormap name
+  tooltip: { bg: '#111827', ink: '#FFFFFF' },
+  radius: 2,                     // bar, tile and swatch corners
+  font: 'Inter',                 // Google Fonts name or CSS stack
+});
+
+configure({ theme: 'acme' });
+```
+
+`theme: 'acme'` also works per chart, and `{ extends: 'acme', … }` builds on it. Colors are validated: anything that is not a CSS color (hex, `rgb()`, `hsl()` or a color name) is dropped and the base value is kept.
+
+## Built-in themes
+
+| Name | Mode | Surface | Use |
+|---|---|---|---|
+| `papel` (alias `light`) | light | `#FCFBF9` paper | default |
+| `noche` (alias `dark`) | dark | `#0B0F2B` deep navy | dark pages, slides |
+
+Both share the same eight hues, stepped separately for each surface and validated on it.
+
+## Keys
+
+| Key | Type | Meaning |
+|---|---|---|
+| `extends` | theme name or object | Base to merge over (default `papel`, or `noche` when `mode: 'dark'`). |
+| `mode` | `'light' \| 'dark'` | Affects tooltips and text-on-fill contrast. |
+| `surface` (alias `background`) | color | Chart background. Also used for 2 px gaps and rings around marks. |
+| `ink` (alias `text`), `lede`, `muted` | color | Primary text, secondary text, axis and source text. |
+| `grid` | color or `{ color, dash, width }` | Gridlines (default 1 px, solid). `dash: '2 3'` draws dotted gridlines. |
+| `axis` | color or `{ color, width }` | Baselines. |
+| `tooltip` | `{ bg, ink }` | Tooltip card colors in the browser (default: white card on light themes, navy on dark). |
+| `radius`, `barRadius` | number | Corner radius of bars (default 4). `radius` sets it for every mark that has corners. |
+| `tint`, `tint2` | color | Quiet fills: KPI tiles, slider tracks, meters. |
+| `dim` | color | Muted marks when `highlight` is used. |
+| `other` | color | The "Other" bucket and series past the 8th. |
+| `categorical` | colors, palette or colormap name | Identity colors, assigned in this order. |
+| `sequential` | colors, ramp or colormap name | Light → dark, for heatmaps and maps. |
+| `diverging` | colors, ramp or colormap name | Two poles with a neutral midpoint. |
+| `status` | `{ good, warning, critical }` | KPI deltas and meters. Never used for series. |
+| `font` | `{ family, mono, import }` | Font stack and optional Google Fonts URL (`fontImport: true` embeds it in the SVG). |
+| `type` | `{ title, subtitle, label, axis, legend, source, titleWeight }` | Type sizes in px. Titles shrink automatically on narrow widths. |
+| `marks` | `{ barRadius, barMax, barMaxH, lineWidth, pointRadius, gap, ring, areaOpacity, bandOpacity, dotOpacity }` | Mark geometry. |
+| `axes` | `{ inside, grid }` | `inside: true` puts y labels on their gridlines inside the plot (more width for data). |
+| `layout` | `{ padding, paddingSmall }` | Outer margin on wide and narrow widths. |
+
+## Named palettes and ramps
+
+| Palettes (`categorical`) | Ramps (`sequential` / `diverging`) |
+|---|---|
+| `cdia` (default), `cdia-noche`, `okabe-ito`, `tableau10`, `udec`, plus matplotlib's `tab10`, `tab20`, `tab20b`, `tab20c`, `Set1`, `Set2`, `Set3`, `Pastel1`, `Pastel2`, `Paired`, `Accent`, `Dark2` | `indigo`, `magenta`, `teal`, `amber`, `indigo-magenta`, `teal-rust`, plus every matplotlib colormap (see [Color scales](colorscales.md)) |
+
+## Validating a palette
+
+```js
+import { validatePalette } from 'plotagents';
+
+validatePalette(['#223C6A', '#E69B0A', '#D21428'], { mode: 'light', surface: '#FFFFFF', locale: 'en' });
+// { ok: false, checks: [
+//   { name: 'lightness', status: 'fail', detail: 'Outside the lightness band 0.43–0.77: #223C6A' }, … ] }
+```
+
+| Check | Threshold | Why |
+|---|---|---|
+| Lightness band | OKLCH L 0.43–0.77 (light), 0.48–0.67 (dark) | Too light disappears, too dark reads as text. |
+| Chroma floor | OKLCH C ≥ 0.10 | Below it a hue reads as gray. |
+| Colorblind separation | ΔE OKLab × 100 ≥ 8 between neighbors, simulated protanopia and deuteranopia (Machado 2009) | Neighbors must stay apart for color-vision deficiencies. |
+| Normal-vision separation | ΔE ≥ 15 | Neighbors must be easy to tell apart for everyone. |
+| Contrast with the surface | ≥ 3:1, warning only | Below it, marks need visible labels. |
+
+Use `pairs: 'all'` for scatter plots and maps, where any two colors can sit next to each other. The built-in palette passes all-pairs for its first three colors, which is why `lint` warns about scatter plots with more than three groups.
+
+`lint(spec)` runs this automatically whenever a spec brings its own palette. Messages follow `locale` (Spanish by default, `'en'` for English).
+
+## Color follows the entity
+
+Colors are assigned to entities, never to positions:
+
+- With `time`, colors are computed over all periods, so a group keeps its color while the slider moves even if its rank changes.
+- With `focus` (drill-down), the subtree keeps its parent's color family.
+- With `facet`, every panel shares one color map.
+- `colors: { "Copper": "#B5562E" }` pins any entity to a color.