plotagents 0.0.0-stage → 0.5.0

package/index.d.ts

@@ -0,0 +1,213 @@
+// plotagents type declarations.
+
+export type ChartType =
+  | 'auto' | 'bar' | 'column' | 'count' | 'line' | 'area' | 'scatter' | 'bubble'
+  | 'regplot' | 'residplot' | 'jointplot' | 'hist' | 'kde' | 'ecdf'
+  | 'box' | 'violin' | 'strip' | 'swarm' | 'point' | 'radar'
+  | 'treemap' | 'sunburst' | 'donut' | 'pie' | 'heatmap' | 'sankey' | 'kpi'
+  // Aliases (seaborn and others)
+  | 'barplot' | 'countplot' | 'lineplot' | 'scatterplot' | 'histplot' | 'kdeplot' | 'ecdfplot'
+  | 'lmplot' | 'boxplot' | 'violinplot' | 'stripplot' | 'swarmplot' | 'beeswarm' | 'pointplot' | 'spider';
+
+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 };
+
+export interface KpiItem {
+  label: string;
+  value: number;
+  /** Relative change as a fraction (0.12 = +12%). */
+  delta?: number;
+  previous?: number;
+  period?: string;
+  good?: 'up' | 'down';
+  trend?: number[];
+  target?: number;
+  format?: Format;
+  display?: string;
+  note?: string;
+}
+
+export interface RefLine { y?: number; x?: number; value?: number; label?: string; color?: string }
+export interface Annotation { x: string | number | Date; label?: string }
+
+export interface Theme {
+  name: string;
+  mode: 'light' | 'dark';
+  surface: string; ink: string; lede: string; muted: string;
+  grid: string; axis: string; tint: string; tint2: string; dim: string; other: string;
+  link: number;
+  categorical: string[]; sequential: string[]; diverging: string[];
+  status: { good: string; warning: string; critical: string };
+  font: { family: string; mono: string; import: string };
+  type: { title: number; subtitle: number; label: number; axis: number; legend: number; source: number; titleWeight: number };
+  marks: { barRadius: number; barMax: number; barMaxH: number; lineWidth: number; pointRadius: number; gap: number; ring: number; areaOpacity: number; bandOpacity: number; dotOpacity: number };
+  axes: { inside: boolean; grid: boolean };
+  layout: { padding: number; paddingSmall: number };
+}
+
+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' })
+
+export interface Spec {
+  type?: ChartType;
+  data?: Row[] | Record<string, number>;
+  title?: string;
+  subtitle?: string;
+  source?: string;
+  x?: string;
+  y?: string | string[];
+  series?: string;
+  color?: string;
+  value?: string;
+  label?: string;
+  group?: string;
+  path?: string[];
+  size?: string;
+  from?: string;
+  to?: string;
+  items?: KpiItem[];
+  format?: Format;
+  xFormat?: Format;
+  yFormat?: Format;
+  stack?: boolean | 'percent';
+  horizontal?: boolean;
+  sort?: 'desc' | 'asc' | 'none' | 'alpha';
+  top?: number;
+  highlight?: string | string[];
+  /** Dashed shapes (hatched fill + dashed outline): names, a data field, { field, equals } or true. */
+  dashed?: string | string[] | boolean | { field: string; equals?: unknown };
+  /** line/area/bar on a time axis: dashed from this x on (a projection). */
+  dashedFrom?: string | number;
+  /** Meaning of the dashed shapes: legend, band label and tooltip. */
+  dashedLabel?: string | false;
+  labels?: boolean | 'auto' | number | string[];
+  labelsFor?: Record<string, string>;
+  refLines?: RefLine[];
+  annotations?: Annotation[];
+  index?: boolean;
+  curve?: 'linear' | 'smooth';
+  zero?: boolean;
+  points?: boolean;
+  xScale?: 'linear' | 'log';
+  yScale?: 'linear' | 'log';
+  trend?: boolean;
+  xLabel?: string;
+  yLabel?: string;
+  aggregate?: 'sum' | 'mean' | 'max' | 'min' | 'count' | 'last' | 'first';
+  colors?: Record<string, string>;
+  theme?: ThemeInput;
+  palette?: string | string[];
+  ramp?: string | string[];
+  hue?: string;
+  facet?: string;
+  col?: string;
+  sharey?: boolean;
+  sharex?: boolean;
+  panelHeight?: number;
+  time?: string;
+  timeValue?: string | number;
+  slider?: boolean;
+  play?: boolean;
+  compare?: 'previous' | 'first' | string | number | false;
+  compareData?: Row[];
+  colorBy?: 'group' | 'change' | 'label';
+  shade?: boolean;
+  change?: boolean;
+  playInterval?: number;
+  xRange?: [string | number, string | number];
+  xDomain?: [number, number];
+  yDomain?: [number, number];
+  ci?: boolean | number;
+  errorbar?: 'ci' | 'sd' | 'se' | 'pi' | 'none' | false;
+  estimator?: 'mean' | 'median' | 'sum' | 'count';
+  focus?: string | string[];
+  font?: string | { family: string; import?: string };
+  textScale?: number;
+  fontScale?: number;
+  labelScale?: number;
+  depth?: number;
+  half?: boolean;
+  bins?: number;
+  binWidth?: number;
+  stat?: 'count' | 'percent' | 'density' | 'probability';
+  kde?: boolean;
+  multiple?: 'layer' | 'stack' | 'dodge' | 'fill';
+  fill?: boolean;
+  order?: number | string[];
+  lowess?: boolean;
+  logx?: boolean;
+  annotate?: boolean;
+  kind?: 'scatter' | 'reg';
+  marginal?: 'hist' | 'kde';
+  inner?: 'box' | 'quartiles' | 'points' | 'none';
+  split?: boolean;
+  axis?: string;
+  axes?: string[];
+  normalize?: boolean;
+  legend?: boolean;
+  locale?: 'es' | 'en';
+  width?: number;
+  height?: number;
+  padding?: number;
+  fontFamily?: string;
+  fontImport?: boolean;
+  background?: boolean;
+  maxSlices?: number;
+  centerValue?: string;
+  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;
+  key?: string;
+  projection?: 'mercator' | 'equalEarth' | 'albersUsa';
+  columns?: number;
+  [key: string]: unknown;
+}
+
+export interface Issue { code: string; message: string; fix?: string }
+export interface LintReport { ok: boolean; type: ChartType; errors: Issue[]; warnings: Issue[]; suggestions: Issue[] }
+export interface SafeResult extends Omit<LintReport, 'ok'> { ok: boolean; svg: string | null; description: string }
+
+export declare class PlotError extends Error { hint?: string }
+
+/** Draws and returns an SVG string. Throws PlotError with a fix hint when the spec cannot be drawn. */
+export declare function plot(spec: Spec): string;
+/** Never throws: returns the SVG plus errors, warnings and design suggestions. */
+export declare function safePlot(spec: Spec): SafeResult;
+/** Reviews a spec and suggests improvements without drawing. */
+export declare function lint(spec: Spec): LintReport;
+/** Text description of the chart (also in the SVG <desc>). */
+export declare function describe(spec: Spec): string;
+/** Browser: draws into an element with tooltips, responsive width, time sliders and drill-down. */
+export declare function render(target: string | Element, spec: Spec, opts?: { controls?: boolean }): { readonly svg: SVGSVGElement | null; readonly spec: Spec; update(spec: Spec): unknown; destroy(): void };
+/** Self-contained HTML page with one or more interactive charts. */
+export declare function toHTML(specs: Spec | Spec[], opts?: { title?: string; lang?: string; columns?: number }): string;
+/** Adds tooltips to a container that already holds a plotagents SVG. */
+export declare function attach(root: Element): void;
+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 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 getTheme(t?: Spec['theme']): Theme;
+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 };
+export declare function formatNumber(v: number, decimals?: number, locale?: string, trim?: boolean): string;
+export declare function formatCompact(v: number, locale?: string, decimals?: number): string;
+
+export default plot;

package/package.json

@@ -1,6 +1,76 @@
 {
   "name": "plotagents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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.",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./schema.json": "./schema.json",
+    "./browser": "./dist/plotagents.js",
+    "./browser/geo": "./dist/plotagents-geo.js",
+    "./geo/chile": "./src/geo/chile.js",
+    "./geo/world": "./src/geo/world.js",
+    "./geo/usa": "./src/geo/usa.js"
+  },
+  "bin": {
+    "plotagents": "bin/plotagents.js"
+  },
+  "files": [
+    "src",
+    "dist",
+    "docs",
+    "bin",
+    "index.d.ts",
+    "schema.json",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "build": "node scripts/bundle.js",
+    "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",
+    "schema": "node -e \"import('./src/index.js').then(m=>process.stdout.write(JSON.stringify(m.schema,null,2)))\" > schema.json"
+  },
+  "keywords": [
+    "chart",
+    "plot",
+    "svg",
+    "dataviz",
+    "visualization",
+    "treemap",
+    "sankey",
+    "seaborn",
+    "regplot",
+    "violin",
+    "radar",
+    "sunburst",
+    "ai",
+    "agents",
+    "llm",
+    "tool-use"
+  ],
+  "author": "Carlos Navarrete <cnavarreteliz@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carlosnavarreteliz/plotagents.git"
+  },
+  "homepage": "https://carlosnavarrete.cl/plotagents/",
+  "bugs": {
+    "url": "https://github.com/carlosnavarreteliz/plotagents/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false
+}