@jarenjs/charts 0.34.0

package/dist/types/types/map.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @file The map chart type: GeoJSON drawn in Web Mercator, optionally
+ * shaded by a feature property (a choropleth). Data shape:
+ *
+ *   data   = { features: <FeatureCollection | Feature[] | Feature>,
+ *              points?: [{ at: [lon, lat], label?, value? }] }
+ *   config = { type:'map', title?, value?, label?, log?, simplify?, aspect? }
+ *
+ * `value` names the feature property to shade by and `label` the one to
+ * name features by (default `'name'`); `points` is the convenience path
+ * for a caller holding a list of places rather than GeoJSON, and folds
+ * into the same shape list at build time so the AST has one.
+ *
+ * The AST is unit-space rings, lines and dots plus a normalized
+ * magnitude per shape — the projection and the simplification happen in
+ * the build (they are geometry *of the data*, not of the drawing), the
+ * colors, the stroke widths and the ramp legend in the render.
+ *
+ * Two things are worth knowing about the projection. It is Web Mercator
+ * because that is what every reader's mental model of a map already is,
+ * and it is applied **only here**: nothing measures on the result, and
+ * `@jarenjs/core/geo` keeps its area and distance functions on the
+ * sphere for exactly that reason. And it is fitted uniformly — the map
+ * is centred in whichever axis has room left over rather than stretched
+ * to fill the frame, which is the single most common way to make a map
+ * look wrong.
+ */
+export type MapShapeAST = {
+    label: string;
+    /**
+     * the shading property, when the feature had one
+     */
+    value: number | null;
+    /**
+     * normalized magnitude (0..1), null when unshaded
+     */
+    t: number | null;
+    /**
+     * polygon rings in unit space,
+     * exterior first then holes; `[u, v]` with v growing downward
+     */
+    rings: Array<Array<number[]>>;
+    /**
+     * line strings in unit space
+     */
+    lines: Array<Array<number[]>>;
+    /**
+     * point positions in unit space
+     */
+    dots: Array<number[]>;
+};
+export type MapAST = {
+    type: 'map';
+    title: string | null;
+    /**
+     * layout width:height ratio
+     */
+    aspect: number;
+    /**
+     * the geographic extent drawn, `[w,s,e,n]`
+     */
+    bbox: number[] | null;
+    shapes: MapShapeAST[];
+    /**
+     * shading extent (null = unshaded)
+     */
+    domain: {
+        min: number;
+        max: number;
+    } | null;
+    /**
+     * positions read vs kept
+     */
+    vertices: {
+        source: number;
+        drawn: number;
+    };
+};
+/**
+ * @typedef {object} MapShapeAST
+ * @property {string} label
+ * @property {number|null} value the shading property, when the feature had one
+ * @property {number|null} t normalized magnitude (0..1), null when unshaded
+ * @property {Array<Array<number[]>>} rings polygon rings in unit space,
+ *  exterior first then holes; `[u, v]` with v growing downward
+ * @property {Array<Array<number[]>>} lines line strings in unit space
+ * @property {Array<number[]>} dots point positions in unit space
+ */
+/**
+ * @typedef {object} MapAST
+ * @property {'map'} type
+ * @property {string|null} title
+ * @property {number} aspect layout width:height ratio
+ * @property {number[]|null} bbox the geographic extent drawn, `[w,s,e,n]`
+ * @property {MapShapeAST[]} shapes
+ * @property {{min: number, max: number}|null} domain shading extent (null = unshaded)
+ * @property {{source: number, drawn: number}} vertices positions read vs kept
+ */
+/**
+ * Default simplification tolerance, as a fraction of the frame's width.
+ * At the default 560px-wide chart this is about a third of a pixel, so
+ * the simplification is invisible by construction: it can only remove
+ * vertices that would have landed on a neighbour's pixel anyway. A
+ * caller drawing much larger passes a smaller number, and `false`
+ * switches it off. Exported because the streaming map accumulator
+ * simplifies on arrival with the same default.
+ */
+export declare const MAP_SIMPLIFY = 0.0006;
+/**
+ * Build the geometry-free map AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {MapAST}
+ */
+export declare function buildMapAST(data: any, config?: any): MapAST;
+/**
+ * Render a map AST to a pure-vnode SVG: one filled path per shape (all
+ * its rings as subpaths, `evenodd` so holes punch through whichever way
+ * the producer wound them), stroked paths for lines, dots for points,
+ * and a ramp key in the legend slot when the map is shaded.
+ * @param {MapAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, ramp?: readonly string[], width?: number,
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {any}
+ */
+export declare function renderMapAST(ast: MapAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    ramp?: readonly string[];
+    width?: number;
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+}): any;

package/dist/types/types/pie.d.ts

@@ -0,0 +1,146 @@
+/**
+ * @file The pie chart type, split into the geometry-free AST build and
+ * the SVG render (the two-stage contract every chart type follows).
+ * This is the extraction of the mermaid pie: `@jarenjs/mermaid` now
+ * delegates its `pie` diagrams here, passing its own class names,
+ * palette and theme through `render` options so its output is unchanged
+ * — charts never imports mermaid (the dependency arrow is one-way).
+ */
+export type PieSliceAST = {
+    label: string;
+    value: number;
+    /**
+     * fraction of the total (0..1)
+     */
+    frac: number;
+    /**
+     * start angle (radians, 12 o'clock = -π/2)
+     */
+    start: number;
+    /**
+     * end angle (radians)
+     */
+    end: number;
+};
+export type PieAST = {
+    type: 'pie';
+    title: string | null;
+    total: number;
+    /**
+     * donut hole radius as a fraction of the outer radius (null = solid pie)
+     */
+    inner: number | null;
+    slices: PieSliceAST[];
+};
+/**
+ * @typedef {object} PieSliceAST
+ * @property {string} label
+ * @property {number} value
+ * @property {number} frac fraction of the total (0..1)
+ * @property {number} start start angle (radians, 12 o'clock = -π/2)
+ * @property {number} end end angle (radians)
+ */
+/**
+ * @typedef {object} PieAST
+ * @property {'pie'} type
+ * @property {string|null} title
+ * @property {number} total
+ * @property {number|null} inner donut hole radius as a fraction of the outer radius (null = solid pie)
+ * @property {PieSliceAST[]} slices
+ */
+/**
+ * Build the geometry-free pie AST: labels/values → fractions and
+ * accumulated start/end angles, starting at 12 o'clock. `config.donut`
+ * turns the pie into a donut: `true` uses the default hole fraction,
+ * a number in (0, 1) sets it directly.
+ * @param {{slices?: {label: string, value: number}[]}} data
+ * @param {{title?: string|null, donut?: boolean|number}} [config]
+ * @returns {PieAST}
+ */
+export declare function buildPieAST(data: {
+    slices?: {
+        label: string;
+        value: number;
+    }[];
+}, config?: {
+    title?: string | null;
+    donut?: boolean | number;
+}): PieAST;
+export type PieRenderOptions = {
+    /**
+     * the root `<svg>` class
+     */
+    rootClass?: string;
+    /**
+     * vnode key prefix (`<prefix><hash>`)
+     */
+    keyPrefix?: string;
+    /**
+     * class per slice `<path>`
+     */
+    sliceClass?: string;
+    /**
+     * class per legend `<g>`
+     */
+    legendClass?: string;
+    /**
+     * slice colors
+     */
+    palette?: readonly string[];
+    /**
+     * title/legend text fill
+     */
+    textColor?: string;
+    /**
+     * slice separator stroke
+     */
+    sliceStroke?: string;
+    /**
+     * per-slice hover `<title>` (default true).
+     * `@jarenjs/mermaid` turns it off: a mermaid pie is a *diagram*, and
+     * its emitted SVG is a byte-stable contract that hover text would
+     * break — the delegation exists to share geometry, not to change what
+     * mermaid renders.
+     */
+    titles?: boolean;
+    /**
+     * pointer bindings for a floating-tooltip host
+     */
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+};
+/**
+ * @typedef {object} PieRenderOptions
+ * @property {string} [rootClass] the root `<svg>` class
+ * @property {string} [keyPrefix] vnode key prefix (`<prefix><hash>`)
+ * @property {string} [sliceClass] class per slice `<path>`
+ * @property {string} [legendClass] class per legend `<g>`
+ * @property {readonly string[]} [palette] slice colors
+ * @property {string} [textColor] title/legend text fill
+ * @property {string} [sliceStroke] slice separator stroke
+ * @property {boolean} [titles] per-slice hover `<title>` (default true).
+ *  `@jarenjs/mermaid` turns it off: a mermaid pie is a *diagram*, and
+ *  its emitted SVG is a byte-stable contract that hover text would
+ *  break — the delegation exists to share geometry, not to change what
+ *  mermaid renders.
+ * @property {import('../core/marks.js').ChartTooltipSpec} [tooltip]
+ *  pointer bindings for a floating-tooltip host
+ */
+/**
+ * Render a pie AST to a pure-vnode SVG: angles → arc paths, plus a
+ * swatch legend with percentages and an optional title. With
+ * `ast.inner === null` (no `donut` in the config) the slice path is
+ * emitted by the same wedge template as before the donut variant
+ * existed — solid-pie output is byte-stable, which is what keeps the
+ * mermaid delegation byte-identical; the annular geometry lives
+ * entirely in the other branch. Every slice carries a label/value
+ * `<title>` unless `options.titles` is false (mermaid's opt-out).
+ * @param {PieAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash content hash for the vnode key
+ * @param {PieRenderOptions} [options]
+ * @returns {any} an SVG vnode
+ */
+export declare function renderPieAST(ast: PieAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: PieRenderOptions): any;

package/dist/types/types/radar.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @file The radar chart type: N named axes as spokes from a shared
+ * center, one polygon per series over a common 0..top value domain.
+ * Data shape:
+ *
+ *   data   = { axes: string[], series: [{ name, values: number[] }] }
+ *   config = { type:'radar', title?, max? }
+ *
+ * The AST stays polar and geometry-free: axis angles in radians
+ * (12 o'clock = -π/2, clockwise), ring and vertex radii as fractions of
+ * the (unknown) outer radius. Non-finite or negative samples become
+ * `null` vertices — the polygon simply skips them, mirroring how the
+ * line type breaks its path on unplottable samples.
+ */
+export type RadarAST = {
+    type: 'radar';
+    title: string | null;
+    /**
+     * value at the outer ring
+     */
+    top: number;
+    axes: {
+        label: string;
+        angle: number;
+        labeled: boolean;
+    }[];
+    /**
+     * spoke-label stride (1 = label every axis)
+     */
+    labelEvery: number;
+    /**
+     * tick fractions (0..1]
+     */
+    rings: {
+        r: number;
+        label: string;
+    }[];
+    series: {
+        name: string;
+        points: ({
+            angle: number;
+            r: number;
+        } | null)[];
+    }[];
+    legend: {
+        name: string;
+        swatch: number;
+    }[] | null;
+};
+/**
+ * @typedef {object} RadarAST
+ * @property {'radar'} type
+ * @property {string|null} title
+ * @property {number} top value at the outer ring
+ * @property {{label: string, angle: number, labeled: boolean}[]} axes
+ * @property {number} labelEvery spoke-label stride (1 = label every axis)
+ * @property {{r: number, label: string}[]} rings tick fractions (0..1]
+ * @property {{name: string, points: ({angle: number, r: number}|null)[]}[]} series
+ * @property {{name: string, swatch: number}[]|null} legend
+ */
+/**
+ * Build the geometry-free radar AST.
+ * `config.labelEvery` overrides the spoke-label stride; by default it
+ * is derived from the axis count (see {@link radarLabelEvery}).
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {RadarAST}
+ */
+export declare function buildRadarAST(data: any, config?: any): RadarAST;
+/**
+ * Render a radar AST to a pure-vnode SVG: ring polygons and spokes for
+ * the scale, one translucent polygon with vertex dots per series, a
+ * swatch legend on the right.
+ * @param {RadarAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, palette?: readonly string[],
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {any}
+ */
+export declare function renderRadarAST(ast: RadarAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    palette?: readonly string[];
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+}): any;

package/dist/types/types/sankey.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @file The sankey chart type: named nodes in flow layers joined by
+ * value-proportional ribbons. Data shape:
+ *
+ *   data   = { nodes?: (string | { name })[],
+ *              links: [{ source, target, value }] }   // by name or node index
+ *   config = { type:'sankey', title? }
+ *
+ * Names referenced only by links are added as nodes automatically. A
+ * link that would close a cycle is dropped (a sankey is a DAG); so are
+ * self-links and non-positive values. Layout: a node's layer is its
+ * longest path from the sources; within a layer nodes stack in input
+ * order, sized by throughput (max of in-flow and out-flow) on one
+ * global scale, centered vertically. The AST is unit-square with `y`
+ * growing downward (no axes — reading order wins, as in the treemap).
+ */
+export type SankeyNodeAST = {
+    name: string;
+    layer: number;
+    x0: number;
+    x1: number;
+    y0: number;
+    y1: number;
+};
+export type SankeyLinkAST = {
+    /**
+     * node index
+     */
+    source: number;
+    /**
+     * node index
+     */
+    target: number;
+    value: number;
+    sy0: number;
+    /**
+     * ribbon extent at the source
+     */
+    sy1: number;
+    ty0: number;
+    /**
+     * ribbon extent at the target
+     */
+    ty1: number;
+};
+export type SankeyAST = {
+    type: 'sankey';
+    title: string | null;
+    nodes: SankeyNodeAST[];
+    links: SankeyLinkAST[];
+};
+/**
+ * @typedef {object} SankeyNodeAST
+ * @property {string} name
+ * @property {number} layer
+ * @property {number} x0 @property {number} x1
+ * @property {number} y0 @property {number} y1
+ */
+/**
+ * @typedef {object} SankeyLinkAST
+ * @property {number} source node index @property {number} target node index
+ * @property {number} value
+ * @property {number} sy0 @property {number} sy1 ribbon extent at the source
+ * @property {number} ty0 @property {number} ty1 ribbon extent at the target
+ */
+/**
+ * @typedef {object} SankeyAST
+ * @property {'sankey'} type
+ * @property {string|null} title
+ * @property {SankeyNodeAST[]} nodes
+ * @property {SankeyLinkAST[]} links
+ */
+/**
+ * Build the geometry-free sankey AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {SankeyAST}
+ */
+export declare function buildSankeyAST(data: any, config?: any): SankeyAST;
+/**
+ * Render a sankey AST to a pure-vnode SVG: categorical node bars,
+ * translucent muted ribbons with flow `<title>`s, node labels beside
+ * the bar on its open side.
+ * @param {SankeyAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, palette?: readonly string[], width?: number,
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {any}
+ */
+export declare function renderSankeyAST(ast: SankeyAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    palette?: readonly string[];
+    width?: number;
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+}): any;

package/dist/types/types/scatter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file The scatter chart type: points over numeric or log axes,
+ * per-point semantic tone (win/loss), and an optional horizontal
+ * reference line (e.g. ratio = 1). Data shape:
+ *
+ *   data   = { points: [{x, y, tone?: 'win'|'loss'}] }
+ *   config = { type:'scatter', title?, xLog?, yLog?, refY?, refLabel?,
+ *              xLabel?, yLabel? }
+ */
+export type ScatterAST = {
+    type: 'scatter';
+    title: string | null;
+    x: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    y: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    /**
+     *  unit position plus the raw sample the hover text reports
+     */
+    points: {
+        u: number;
+        v: number;
+        tone: 'win' | 'loss' | null;
+        x: number;
+        y: number;
+    }[];
+    ref: {
+        v: number;
+        label: string | null;
+    } | null;
+};
+/**
+ * @typedef {object} ScatterAST
+ * @property {'scatter'} type
+ * @property {string|null} title
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} x
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} y
+ * @property {{u:number,v:number,tone:'win'|'loss'|null,x:number,y:number}[]} points
+ *  unit position plus the raw sample the hover text reports
+ * @property {{v: number, label: string|null}|null} ref
+ */
+/**
+ * Build the geometry-free scatter AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {ScatterAST}
+ */
+export declare function buildScatterAST(data: any, config?: any): ScatterAST;
+/**
+ * Render a scatter AST to a pure-vnode SVG. Each dot carries its raw
+ * `(x, y)` as a `<title>`: on a log axis a pixel position is not
+ * readable back to a value, so the hover text is the only honest way to
+ * name the sample.
+ * @param {ScatterAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, palette?: readonly string[], width?: number,
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {any}
+ */
+export declare function renderScatterAST(ast: ScatterAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    palette?: readonly string[];
+    width?: number;
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+}): any;

package/dist/types/types/streamgraph.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @file The streamgraph chart type: stacked series as flowing bands
+ * around a silhouette baseline (the stack centered on its running
+ * total, so the outline stays symmetric). Data shape:
+ *
+ *   data   = { series: [{ name, values: number[] }], xs?: number[] }
+ *   config = { type:'streamgraph', title?, xLabel? }
+ *
+ * `values` align by index across series; `xs` optionally places the
+ * samples on a numeric x axis (index positions otherwise). Negative
+ * and non-finite samples read as 0 — a streamgraph stacks
+ * non-negative magnitudes. The y axis is deliberately unlabeled:
+ * silhouette offsets make absolute y positions meaningless; band
+ * thickness is the encoding, and each band carries its name as hover
+ * text.
+ */
+export type StreamgraphAST = {
+    type: 'streamgraph';
+    title: string | null;
+    x: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    legend: {
+        name: string;
+        swatch: number;
+    }[] | null;
+    layers: {
+        name: string;
+        points: {
+            u: number;
+            lo: number;
+            hi: number;
+        }[];
+    }[];
+};
+/**
+ * @typedef {object} StreamgraphAST
+ * @property {'streamgraph'} type
+ * @property {string|null} title
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} x
+ * @property {{name: string, swatch: number}[]|null} legend
+ * @property {{name: string, points: {u:number, lo:number, hi:number}[]}[]} layers
+ */
+/**
+ * Build the geometry-free streamgraph AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {StreamgraphAST}
+ */
+export declare function buildStreamgraphAST(data: any, config?: any): StreamgraphAST;
+/**
+ * Render a streamgraph AST to a pure-vnode SVG: one closed band path
+ * per layer (top edge forward, bottom edge back), separated by the
+ * slice-stroke hairline the pie uses between touching fills.
+ * @param {StreamgraphAST} ast
+ * @param {{tokens: Record<string,string>, cssVars: Record<string,string>}} theme
+ * @param {string} hash
+ * @param {{rootClass?: string, keyPrefix?: string, palette?: readonly string[], width?: number,
+ *   tooltip?: import('../core/marks.js').ChartTooltipSpec}} [options]
+ * @returns {any}
+ */
+export declare function renderStreamgraphAST(ast: StreamgraphAST, theme: {
+    tokens: Record<string, string>;
+    cssVars: Record<string, string>;
+}, hash: string, options?: {
+    rootClass?: string;
+    keyPrefix?: string;
+    palette?: readonly string[];
+    width?: number;
+    tooltip?: import('../core/marks.js').ChartTooltipSpec;
+}): any;