plotagents 0.5.0 → 0.8.0

package/index.d.ts

@@ -5,15 +5,46 @@ export type ChartType =
   | 'regplot' | 'residplot' | 'jointplot' | 'hist' | 'kde' | 'ecdf'
   | 'box' | 'violin' | 'strip' | 'swarm' | 'point' | 'radar'
   | 'treemap' | 'sunburst' | 'donut' | 'pie' | 'heatmap' | 'sankey' | 'kpi'
+  | 'network' | 'chord' | 'pyramid' | 'flowchart' | 'gantt' | 'wordcloud' | 'choropleth' | 'symbolmap' | 'pointmap' | 'table' | 'corr' | 'pairplot'
   // Aliases (seaborn and others)
   | 'barplot' | 'countplot' | 'lineplot' | 'scatterplot' | 'histplot' | 'kdeplot' | 'ecdfplot'
-  | 'lmplot' | 'boxplot' | 'violinplot' | 'stripplot' | 'swarmplot' | 'beeswarm' | 'pointplot' | 'spider';
+  | 'lmplot' | 'boxplot' | 'violinplot' | 'stripplot' | 'swarmplot' | 'beeswarm' | 'pointplot' | 'spider'
+  | 'timeline' | 'roadmap' | 'schedule' | 'cronograma' | 'map' | 'mapa' | 'tabla' | 'datatable'
+  | 'correlation' | 'corrplot' | 'clustermap' | 'pairs' | 'splom' | 'scattermatrix';
+
+export type Locale = 'es' | 'en' | 'pt' | 'fr' | 'de' | 'auto';
+
+/** table: one column. A bare field name infers everything. */
+export interface TableColumn {
+  field?: string;
+  label?: string;
+  /** Indicator. Inferred when omitted: bar on the main measure, delta on change fields, sparkline on lists of numbers, progress on 0–1 goals, badge on status words, check on booleans. */
+  type?: 'text' | 'number' | 'bar' | 'heat' | 'delta' | 'sparkline' | 'progress' | 'badge' | 'check' | 'date' | 'link' | 'rank';
+  format?: Format;
+  align?: 'left' | 'right' | 'center';
+  width?: number;
+  /** delta/progress: whether up is good (default) or down (costs). */
+  good?: 'up' | 'down';
+  /** progress: field or number to compare against. */
+  target?: string | number;
+  /** heat: matplotlib colormap or colors. */
+  colorScale?: string | string[] | { name?: string; colors?: string[]; reverse?: boolean; mid?: number };
+  /** Totals row for this column. */
+  total?: boolean | 'sum' | 'mean' | 'min' | 'max' | 'count';
+  /** Text: lines before truncating (default 2, 3 for long text). */
+  lines?: number;
+  /** link: field with the text shown instead of the URL. */
+  text?: string;
+  /** badge: { value: "#hex" }. */
+  colors?: Record<string, string>;
+  sortable?: boolean;
+}
 
 export type Row = Record<string, string | number | Date | null | undefined>;
 
 export type Format =
   | 'number' | 'compact' | 'percent' | 'currency' | 'integer'
-  | { type?: string; prefix?: string; suffix?: string; decimals?: number; currency?: string; scale?: number };
+  | { type?: 'number' | 'compact' | 'percent' | 'currency' | 'integer'; prefix?: string; suffix?: string; /** 0–20. */ decimals?: number; currency?: string; scale?: number };
 
 export interface KpiItem {
   label: string;
@@ -49,8 +80,31 @@ export interface Theme {
 }
 
 type DeepPartial<T> = { [K in keyof T]?: T[K] extends object ? (T[K] extends any[] ? T[K] | string : DeepPartial<T[K]>) : T[K] };
-/** JSON theme: deep-merged over `extends` (default "papel"). */
-export type ThemeInput = 'papel' | 'noche' | 'light' | 'dark' | (DeepPartial<Theme> & { extends?: 'papel' | 'noche' })
+/** Simple theme tokens, mapped onto the full theme. */
+export interface ThemeTokens {
+  /** Alias of surface. */
+  background?: string;
+  /** Alias of ink. */
+  text?: string;
+  /** First series color. */
+  accent?: string;
+  /** Grid color, or { color, dash, width }. */
+  grid?: string | { color?: string; dash?: string; width?: number };
+  axis?: string;
+  tooltip?: { bg?: string; ink?: string };
+  /** Corner radius of bars and tiles. */
+  radius?: number;
+  barRadius?: number;
+  font?: string | { family?: string; mono?: string; import?: string };
+}
+/** JSON theme: deep-merged over `extends` (default "papel"). Strings: built-in or registerTheme() names. */
+export type ThemeInput = 'papel' | 'noche' | 'light' | 'dark' | (string & {}) | (Omit<DeepPartial<Theme>, 'grid' | 'font'> & ThemeTokens & { extends?: 'papel' | 'noche' | (string & {}) })
+
+/** matplotlib colormap name (case-insensitive, `_r` reverses), a list of hex colors, or { name | colors, reverse, mid }. */
+export type ColorScale = string | string[] | { name?: string; colors?: string[]; reverse?: boolean; mid?: number };
+export type LegendPosition = 'top' | 'bottom' | 'left' | 'right';
+export type TileProvider = 'osm' | 'esri-gray' | 'esri-dark' | 'carto-light' | 'carto-dark' | 'mapbox-light' | 'mapbox-dark';
+export type NetworkLayout = 'force' | 'circular' | 'radial' | 'concentric' | 'clusters' | 'tree' | 'grid' | 'circle';
 
 export interface Spec {
   type?: ChartType;
@@ -75,7 +129,7 @@ export interface Spec {
   yFormat?: Format;
   stack?: boolean | 'percent';
   horizontal?: boolean;
-  sort?: 'desc' | 'asc' | 'none' | 'alpha';
+  sort?: 'desc' | 'asc' | 'none' | 'alpha' | 'start';
   top?: number;
   highlight?: string | string[];
   /** Dashed shapes (hatched fill + dashed outline): names, a data field, { field, equals } or true. */
@@ -86,10 +140,10 @@ export interface Spec {
   dashedLabel?: string | false;
   labels?: boolean | 'auto' | number | string[];
   labelsFor?: Record<string, string>;
-  refLines?: RefLine[];
+  refLines?: RefLine[] | RefLine;
   annotations?: Annotation[];
   index?: boolean;
-  curve?: 'linear' | 'smooth';
+  curve?: 'linear' | 'smooth' | 'step';
   zero?: boolean;
   points?: boolean;
   xScale?: 'linear' | 'log';
@@ -100,6 +154,7 @@ export interface Spec {
   aggregate?: 'sum' | 'mean' | 'max' | 'min' | 'count' | 'last' | 'first';
   colors?: Record<string, string>;
   theme?: ThemeInput;
+  /** Palette name ("okabe-ito", "tab10", "Set2"…, or any colormap, sampled) or a list of colors. */
   palette?: string | string[];
   ramp?: string | string[];
   hue?: string;
@@ -110,8 +165,6 @@ export interface Spec {
   panelHeight?: number;
   time?: string;
   timeValue?: string | number;
-  slider?: boolean;
-  play?: boolean;
   compare?: 'previous' | 'first' | string | number | false;
   compareData?: Row[];
   colorBy?: 'group' | 'change' | 'label';
@@ -141,15 +194,42 @@ export interface Spec {
   lowess?: boolean;
   logx?: boolean;
   annotate?: boolean;
+  /** jointplot: center plot. pairplot: "reg" adds a fit line to every scatter panel. */
   kind?: 'scatter' | 'reg';
+  /** corr/pairplot: numeric fields to relate (default: all numeric; pairplot: first 6). */
+  vars?: string[];
+  /** corr: "pearson" (default) or "spearman". */
+  method?: 'pearson' | 'spearman';
+  /** corr: "lower" (default) or "full" (default with `cluster`). */
+  triangle?: 'lower' | 'full' | boolean;
+  /** corr: hierarchical clustering order + dendrogram (clustermap). */
+  cluster?: boolean;
+  dendrogram?: boolean;
+  /** corr: grey out cells with p ≥ alpha. */
+  alpha?: number;
+  cellSize?: number;
+  /** pairplot: diagonal panels ("kde" by default with hue). */
+  diag?: 'hist' | 'kde';
+  /** pairplot: above the diagonal. */
+  upper?: 'corr' | 'scatter' | false;
+  corner?: boolean;
+  panelSize?: number;
   marginal?: 'hist' | 'kde';
-  inner?: 'box' | 'quartiles' | 'points' | 'none';
+  inner?: 'box' | 'quartiles' | 'points' | 'stick' | 'none';
   split?: boolean;
   axis?: string;
   axes?: string[];
   normalize?: boolean;
-  legend?: boolean;
-  locale?: 'es' | 'en';
+  /** Legend on/off or position (default top; left/right fall back to bottom under 520px). */
+  legend?: boolean | LegendPosition | { position?: LegendPosition };
+  legendTitle?: string;
+  /** Drop legend entries (series, first level, group); colors stay fixed and the entries stay in the legend, faded. */
+  exclude?: string | string[];
+  /** Continuous color scale. Aliases: cmap, colormap. */
+  colorScale?: ColorScale;
+  cmap?: ColorScale;
+  colormap?: ColorScale;
+  locale?: Locale;
   width?: number;
   height?: number;
   padding?: number;
@@ -161,11 +241,136 @@ export interface Spec {
   centerLabel?: string;
   midpoint?: number;
   diverging?: boolean;
-  /** choropleth/symbolmap: "chile" (default), "usa", "world", a registered name or a GeoJSON FeatureCollection. */
-  geo?: 'chile' | 'usa' | 'world' | string | object;
+  /** choropleth/symbolmap: "chile" (default), "usa", "world", a registered name, your own GeoJSON (FeatureCollection, Feature, Feature[] or geometry) or TopoJSON. In the browser, render() also accepts a URL. */
+  geo?: 'chile' | 'usa' | 'world' | string | object | object[];
+  /** TopoJSON: object to draw (default: the first). */
+  geoObject?: string;
   key?: string;
-  projection?: 'mercator' | 'equalEarth' | 'albersUsa';
-  columns?: number;
+  /** Feature property matched against `key` (auto-detected when omitted). */
+  featureKey?: string;
+  /** Feature property with the display name. */
+  nameKey?: string;
+  projection?: 'mercator' | 'equalEarth' | 'albersUsa' | 'equirectangular' | 'conic' | 'identity' | 'planar' | { type: string; parallels?: [number, number]; rotate?: number; center?: [number, number] };
+  /** Zoom to regions, a [lonMin, latMin, lonMax, latMax] box, or "markers". */
+  fitTo?: string | string[] | [number, number, number, number];
+  markers?: Array<{ lon: number; lat: number; label?: string; value?: number; color?: string }> | { data: Row[]; lon?: string; lat?: string; label?: string; size?: string; color?: string; legend?: string; maxRadius?: number; radius?: number; labels?: boolean };
+  layers?: Array<{ geo: object | string; label?: string; stroke?: string; width?: number; fill?: string; dash?: boolean | string; opacity?: number; below?: boolean; object?: string }>;
+  borderColor?: string;
+  borderWidth?: number;
+  pointRadius?: number;
+  /** network: node rows (id, group, size). flowchart: steps (id, label, type, lane). */
+  nodes?: Row[];
+  /** flowchart: connections (from, to, label). Same as `data`. */
+  edges?: Row[];
+  layout?: NetworkLayout;
+  /** network: edge curvature, 0 straight (default 0.3). */
+  curveness?: number;
+  nodeId?: string;
+  nodeLabel?: string;
+  /** Largest node / circle radius in px. */
+  maxRadius?: number;
+  /** network: force-layout iterations. */
+  iterations?: number;
+  /** chord: square flow matrix with `names`. */
+  matrix?: number[][];
+  names?: string[];
+  directed?: boolean;
+  ribbonColor?: 'source' | 'smaller' | 'larger';
+  labelOrientation?: 'horizontal' | 'radial';
+  direction?: 'TB' | 'LR';
+  /** pyramid */
+  age?: string;
+  sex?: string;
+  percent?: boolean;
+  /** pointmap: tile basemap with lat/lon dots. */
+  lat?: string;
+  lon?: string;
+  tiles?: TileProvider | { url: string; attribution?: string; subdomains?: string; maxZoom?: number; retina?: boolean } | false;
+  /** Public token / API key for the tile provider (a secret Mapbox "sk." token is rejected). */
+  tilesKey?: string;
+  tileStyle?: 'muted' | 'original';
+  tileOpacity?: number;
+  zoom?: number;
+  /** [lon, lat] */
+  center?: [number, number];
+  /** choropleth */
+  missing?: 'hatch' | 'plain';
+  thresholds?: number[];
+  classes?: number;
+  scale?: 'quantile' | 'equal' | 'continuous' | 'categorical' | number[] | string;
+  values?: boolean;
+  tall?: boolean;
+  /** Seaborn-style options */
+  orient?: 'v' | 'h';
+  valueDomain?: [number, number];
+  bandwidth?: number;
+  bwAdjust?: number;
+  cut?: number;
+  jitter?: number | boolean;
+  dodge?: boolean;
+  hueOrder?: string[];
+  showMeans?: boolean;
+  cumulative?: boolean;
+  rug?: boolean;
+  complementary?: boolean;
+  radius?: number;
+  endLabels?: boolean;
+  /** treemap/sunburst */
+  showValues?: boolean;
+  hole?: number;
+  thickness?: number;
+  cellHeight?: number;
+  facetOrder?: string[];
+  /** gantt */
+  task?: string;
+  start?: string;
+  end?: string;
+  duration?: string;
+  progress?: string;
+  dependsOn?: string;
+  milestone?: string;
+  today?: string | number | boolean;
+  groupHeaders?: boolean | 'compact';
+  rowHeight?: number;
+  /** gantt: phases drawn collapsed into a summary row; true for all. Click toggles in the browser. */
+  collapsed?: boolean | string | string[];
+  collapsible?: boolean;
+  /** gantt: highlight the zero-slack chain along dependsOn. */
+  critical?: boolean;
+  criticalColor?: string;
+  /** gantt: shade weekends on day plans of up to 120 days (default true). */
+  weekends?: boolean;
+  todayColor?: string;
+  /** Browser time controls, off by default: true (buttons or slider), "buttons" or "slider". */
+  slider?: boolean | 'buttons' | 'slider';
+  play?: boolean;
+  /** wordcloud: words field, or raw text to count. */
+  text?: string | string[];
+  textField?: string;
+  /** facet/kpi: panels or tiles per row. table: the columns. */
+  columns?: number | Array<string | TableColumn>;
+  /** table: column to sort by (field or label). */
+  sortBy?: string;
+  sortOrder?: 'asc' | 'desc';
+  /** table: rows per page (default: all up to 15, then 10). false shows every row. */
+  pageSize?: number | false;
+  page?: number;
+  /** table: keep rows containing these words (accent- and case-insensitive). */
+  query?: string;
+  /** table: browser search box (default: on above 20 rows). */
+  search?: boolean;
+  /** table: totals row. */
+  total?: boolean | 'sum' | 'mean' | 'min' | 'max' | Record<string, string | boolean>;
+  totalLabel?: string;
+  /** table: "#" column with the position. */
+  rank?: boolean;
+  /** table: one card per row. "auto" (default) when the columns do not fit. */
+  cards?: boolean | 'auto';
+  density?: 'compact' | 'normal' | 'comfortable';
+  striped?: boolean;
+  /** table: false disables the automatic data bar. */
+  bars?: boolean;
+  sortable?: boolean;
   [key: string]: unknown;
 }
 
@@ -194,19 +399,69 @@ export declare function resolve(spec: Spec): Spec;
 export declare const schema: Record<string, unknown>;
 /** Library-wide defaults (font, textScale, locale, theme, palette…). The spec always wins. `configure(null)` resets. */
 export declare function configure(options?: Partial<Spec> | null): Partial<Spec>;
-export declare function registerGeo(name: string, featureCollection: object, aliases?: string[]): object;
+export interface DashboardSpec {
+  title?: string; subtitle?: string; source?: string; updated?: string; note?: string;
+  locale?: Locale; theme?: Spec['theme']; font?: Spec['font']; palette?: string | string[];
+  data?: Row[];
+  kpis?: Array<{ label: string; value?: number; delta?: number; period?: string; previous?: number; display?: string; trend?: number[]; good?: 'up' | 'down'; format?: Format;
+    field?: string; agg?: 'sum' | 'mean' | 'median' | 'min' | 'max' | 'count' | 'distinct' | 'ratio'; over?: string; scale?: number;
+    compare?: { field: string; current: string | number; previous: string | number }; trendBy?: string }>;
+  /** Optional when there are `kpis`. */
+  charts?: Array<Spec & { primary?: boolean; size?: 'full' | 'large' | 'medium' | 'small'; span?: number }>;
+  filters?: Array<string | { field: string; label?: string; control?: 'buttons' | 'select'; value?: string }>;
+  layout?: 'auto' | 'executive' | 'grid';
+  colors?: Record<string, string>;
+  /** "given" keeps the charts in the order written (otherwise the main time series goes first). */
+  order?: 'given';
+  ramp?: string | string[];
+  textScale?: number;
+}
+/** Self-contained HTML dashboard with best-practice layout, shared colors, KPIs and filters. */
+export declare function dashboard(spec: DashboardSpec): string;
+/** Never throws: { ok, html, plan, errors, warnings, suggestions }. */
+export declare function safeDashboard(spec: DashboardSpec): { ok: boolean; html: string | null; plan: object | null; errors: Issue[]; warnings: Issue[]; suggestions: Issue[] };
+export declare function lintDashboard(spec: DashboardSpec): { ok: boolean; errors: Issue[]; warnings: Issue[]; suggestions: Issue[] };
+export declare function planDashboard(spec: DashboardSpec): object;
+/** Browser: draws a dashboard into an element. */
+/** Browser: wires the filters and charts of a dashboard already in the DOM. */
+export declare function mountDashboard(root: Element, plan: object): { plan: object; update(): void; destroy(): void };
+export declare function packRows(spans: number[]): Array<Array<{ i: number; span: number }>>;
+export declare function balancedRows(spans: number[], hasPrimary?: boolean): Array<Array<{ i: number; span: number }>>;
+export declare function renderDashboard(target: string | Element, spec: DashboardSpec): { update(): void; destroy(): void };
+export declare const dashboardSchema: Record<string, unknown>;
+/** Raw text → [{ text, value }] word counts without stopwords. */
+export declare function countWords(text: string | string[], opts?: { minLength?: number; stopwords?: string[] }): { text: string; value: number }[];
+export declare function getGeo(geo: string | object, objectName?: string): object;
+export declare function registeredGeo(): string[];
+export declare function registerGeo(name: string, geo: object, aliases?: string[]): object;
+/** Any GeoJSON / TopoJSON shape → FeatureCollection. */
+export declare function toFeatureCollection(geo: object | object[], objectName?: string): object;
+/** Browser: downloads (once per URL) a GeoJSON or TopoJSON. */
+export declare function loadGeo(url: string): Promise<object>;
 export declare const palettes: Record<string, string[]>;
 export declare const ramps: Record<string, string[]>;
 export declare function themeFor(spec: Spec): Theme;
 export declare function timeValues(spec: Spec): (string | number)[];
 export declare function validatePalette(colors: string[], opts?: { mode?: 'light' | 'dark'; surface?: string; pairs?: 'adjacent' | 'all' }): { ok: boolean; checks: { name: string; status: 'pass' | 'warn' | 'fail'; detail: string }[] };
-export declare function bundleSource(): string | null;
-export declare function toolDefinition(opts?: { name?: string; flavor?: 'anthropic' | 'openai' }): Record<string, unknown>;
-export declare const themes: Record<'papel' | 'noche' | 'light' | 'dark', Theme>;
+export declare function bundleSource(file?: string): string | null;
+export declare function toolDefinition(opts?: { name?: string; flavor?: 'anthropic' | 'openai'; kind?: 'chart' | 'dashboard' }): Record<string, unknown>;
+export declare const themes: Record<'papel' | 'noche' | 'light' | 'dark', Theme> & Record<string, Theme>;
 export declare function getTheme(t?: Spec['theme']): Theme;
+/** Registers a named theme (merged over `extends`, default papel); use it as theme: "name" or configure({ theme: "name" }). */
+export declare function registerTheme(name: string, theme: ThemeInput): Theme;
+/** Resolves a color scale to its stops, or null when the name is unknown. */
+export declare function resolveColorScale(v: ColorScale): { name: string; stops: string[]; kind: 'sequential' | 'diverging' | 'cyclic' | 'qualitative' } | null;
+/** Available colormap and palette names by kind. */
+export declare function colorScaleNames(): { sequential: string[]; diverging: string[]; cyclic: string[]; qualitative: string[] };
+/** Color at t ∈ [0, 1] along `stops` (OKLab). */
+export declare function interpolateColor(stops: string[], t: number): string;
+export declare const COLORMAPS: Record<string, string>;
+export declare const QUALITATIVE: Record<string, string>;
 export declare const TYPES: ChartType[];
 export declare function squarify<T extends { value: number }>(items: T[], x: number, y: number, w: number, h: number): (T & { x: number; y: number; w: number; h: number })[];
 export declare function makeFormat(fmt?: Format, locale?: string, values?: number[]): ((v: number) => string) & { type: string };
+/** Most likely language of some texts ('es' | 'en' | 'pt' | 'fr' | 'de'), or null. */
+export declare function detectLocale(texts: string | string[]): 'es' | 'en' | 'pt' | 'fr' | 'de' | null;
 export declare function formatNumber(v: number, decimals?: number, locale?: string, trim?: boolean): string;
 export declare function formatCompact(v: number, locale?: string, decimals?: number): string;
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "plotagents",
-  "version": "0.5.0",
-  "description": "Beautiful charts from one JSON spec, built for AI agents: bars, lines, multi-level treemaps, sunbursts, sankeys and seaborn-style plots (regplot, hist, kde, box, violin…). Accessible SVG, time sliders, JSON themes, zero dependencies.",
+  "version": "0.8.0",
+  "description": "The chart protocol for AI agents: one JSON spec in, a finished accessible SVG out. Bars, lines, Gantt charts, treemaps, sankeys, maps from any GeoJSON/TopoJSON, networks and seaborn-style plots. Zero dependencies.",
   "type": "module",
   "main": "./src/index.js",
   "module": "./src/index.js",
@@ -25,6 +25,7 @@
     "src",
     "dist",
     "docs",
+    "skills",
     "bin",
     "index.d.ts",
     "schema.json",
@@ -38,7 +39,7 @@
     "bench": "node scripts/bench.js",
     "prepublishOnly": "node scripts/bundle.js && node --test test/*.test.js",
     "examples": "node examples/build.js",
-    "site": "node scripts/build-site.js",
+    "site": "node scripts/build-site.js && node scripts/build-site.js --lang es",
     "schema": "node -e \"import('./src/index.js').then(m=>process.stdout.write(JSON.stringify(m.schema,null,2)))\" > schema.json"
   },
   "keywords": [
@@ -57,7 +58,13 @@
     "ai",
     "agents",
     "llm",
-    "tool-use"
+    "tool-use",
+    "gantt",
+    "timeline",
+    "geojson",
+    "topojson",
+    "choropleth",
+    "map"
   ],
   "author": "Carlos Navarrete <cnavarreteliz@gmail.com>",
   "license": "MIT",