@jarenjs/charts 0.34.0

package/dist/types/transforms/benchmark-adapter.d.ts

@@ -0,0 +1,169 @@
+/**
+ * @file Benchmark interop: pure functions from the published benchmark
+ * data shapes (the jaren website's generated `benchmarks/*.json`) to
+ * `compileChart`-shaped `{config, data}` pairs. No formatting, no
+ * vnodes, no fetching — data in, chart definition out, so every
+ * function is unit-testable against a vendored slice of the real data.
+ *
+ * The suite-wide ratio convention holds: ratio > 1 means "Jaren is N×
+ * faster", and the win/loss semantic tones follow it.
+ */
+export type ChartPair = {
+    config: Record<string, any>;
+    data: Record<string, any>;
+};
+/**
+ * @typedef {{config: Record<string, any>, data: Record<string, any>}} ChartPair
+ */
+/**
+ * The ratio-distribution bar chart: success-only tests bucketed by
+ * ratio. Buckets carry their own predicate and tone.
+ * @param {{ratio: number|null, isSuccessTest?: boolean}[]} results
+ * @param {{label: string, test: (r: number) => boolean, tone: 'win'|'loss'}[]} buckets
+ * @param {string} [title]
+ * @returns {ChartPair}
+ */
+export declare function ratioDistributionBars(results: {
+    ratio: number | null;
+    isSuccessTest?: boolean;
+}[], buckets: {
+    label: string;
+    test: (r: number) => boolean;
+    tone: 'win' | 'loss';
+}[], title?: string): ChartPair;
+/**
+ * The ratio scatter: every success-only test as one point, ranked
+ * fastest-ratio first, log-scale y, reference line at parity.
+ * @param {{ratio: number|null, isSuccessTest?: boolean}[]} results
+ * @param {string} [title]
+ * @returns {ChartPair}
+ */
+export declare function ratioScatter(results: {
+    ratio: number | null;
+    isSuccessTest?: boolean;
+}[], title?: string): ChartPair;
+/**
+ * Per-draft conformance: grouped bars of passed tests per engine.
+ * @param {Record<string, Record<string, {passed: number}>>} engineStats
+ *   engine → draft → {passed, failed, errors}
+ * @param {string} [title]
+ * @returns {ChartPair}
+ */
+export declare function conformanceBars(engineStats: Record<string, Record<string, {
+    passed: number;
+}>>, title?: string): ChartPair;
+/**
+ * Generic engine-comparison bars over `{name, results: {engine: value}}`
+ * profile rows (the toml/markdown/mermaid profile shape).
+ * @param {{name: string, results: Record<string, number>}[]} rows
+ * @param {string[]} engines series order (first = jaren)
+ * @param {{title?: string, log?: boolean, valLabel?: string}} [options]
+ * @returns {ChartPair}
+ */
+export declare function profileBars(rows: {
+    name: string;
+    results: Record<string, number>;
+}[], engines: string[], options?: {
+    title?: string;
+    log?: boolean;
+    valLabel?: string;
+}): ChartPair;
+/**
+ * Scenario-matrix bars over `{scenario|title, engines: {key: nsPerOp}}`
+ * rows (the jsonquery/jslt shape). Log axis — rival engines span orders
+ * of magnitude.
+ * @param {{scenario?: string, title?: string, engines: Record<string, number>}[]} rows
+ * @param {{title?: string, valLabel?: string}} [options]
+ * @returns {ChartPair}
+ */
+export declare function matrixBars(rows: {
+    scenario?: string;
+    title?: string;
+    engines: Record<string, number>;
+}[], options?: {
+    title?: string;
+    valLabel?: string;
+}): ChartPair;
+/**
+ * Suite pass-count bars over an `{engine: {pass, total}}` map (the
+ * toml-compliance / markdown-scorecard shape); the highlighted engine
+ * (ours) carries the win tone.
+ * @param {Record<string, {pass: number, total: number}>} scorecard
+ * @param {{title?: string, highlight?: string, valLabel?: string}} [options]
+ * @returns {ChartPair}
+ */
+export declare function passCountBars(scorecard: Record<string, {
+    pass: number;
+    total: number;
+}>, options?: {
+    title?: string;
+    highlight?: string;
+    valLabel?: string;
+}): ChartPair;
+/**
+ * The jsonpath per-query profile: horizontal grouped bars for the
+ * top-N queries by jaren-vs-rival spread (the rest stay in the table).
+ * @param {{name: string, engines: Record<string, number>}[]} rows
+ * @param {string} rival the comparison engine key (e.g. 'json-p3')
+ * @param {number} topN
+ * @param {string} [title]
+ * @returns {ChartPair}
+ */
+export declare function querySpreadBars(rows: {
+    name: string;
+    engines: Record<string, number>;
+}[], rival: string, topN: number, title?: string): ChartPair;
+/**
+ * Bars over a pointer/patch-style result table:
+ * `{columns, rows: [{name, results: number[]}]}`.
+ * @param {{title?: string, columns: string[], rows: {name: string, results: number[]}[]}} table
+ * @param {{title?: string, log?: boolean, valLabel?: string}} [options]
+ * @returns {ChartPair}
+ */
+export declare function resultTableBars(table: {
+    title?: string;
+    columns: string[];
+    rows: {
+        name: string;
+        results: number[];
+    }[];
+}, options?: {
+    title?: string;
+    log?: boolean;
+    valLabel?: string;
+}): ChartPair;
+/**
+ * Horizontal bars over `{label, ns}` timing rows (the view/charts
+ * benchmark shape). One series in one color: the bars are *nominal*
+ * categories — engines or scenarios — so their identity comes from the
+ * axis label, not from a hue, and the length is the whole message.
+ * Semantic win/loss tones are deliberately not used: on a timing chart
+ * "ours" is not automatically good, and docs/DESIGN.md reserves those tokens
+ * for genuine status.
+ * @param {{label: string, ns: number}[]} rows
+ * @param {{title?: string, log?: boolean, valLabel?: string}} [options]
+ * @returns {ChartPair}
+ */
+export declare function timingBars(rows: {
+    label: string;
+    ns: number;
+}[], options?: {
+    title?: string;
+    log?: boolean;
+    valLabel?: string;
+}): ChartPair;
+/**
+ * Cross-suite ratio bars for the benchmarks overview: one bar per suite
+ * headline, tone by which side of parity it lands on — here the tones
+ * ARE semantic (a ratio below 1 is a genuine loss, reported as one).
+ * @param {{key: string, label: string, ratio: number|null}[]} headlines
+ * @param {{title?: string}} [options]
+ * @returns {ChartPair}
+ */
+export declare function headlineRatioBars(headlines: {
+    key: string;
+    label: string;
+    ratio: number | null;
+}[], options?: {
+    title?: string;
+}): ChartPair;

package/dist/types/transforms/mermaid-adapter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @file Mermaid interop: map a mermaid pie AST (`{title, showData,
+ * slices}`) onto a chart definition + data pair. Lives in charts so the
+ * dependency arrow stays one-way — `@jarenjs/mermaid` imports this,
+ * never the reverse; nothing here touches mermaid code.
+ */
+/**
+ * Convert a mermaid pie AST to `compileChart`-shaped inputs.
+ * @param {{title?: string|null, showData?: boolean, slices: {label: string, value: number}[]}} ast
+ * @returns {{config: {type: 'pie', title: string|null}, data: {slices: {label: string, value: number}[]}}}
+ */
+export declare function mermaidPieToChartAST(ast: {
+    title?: string | null;
+    showData?: boolean;
+    slices: {
+        label: string;
+        value: number;
+    }[];
+}): {
+    config: {
+        type: 'pie';
+        title: string | null;
+    };
+    data: {
+        slices: {
+            label: string;
+            value: number;
+        }[];
+    };
+};

package/dist/types/types/bar.d.ts

@@ -0,0 +1,213 @@
+/**
+ * @file The bar chart type: grouped or stacked, vertical or horizontal,
+ * linear or log value axis. Data shape:
+ *
+ *   data   = { categories: string[],
+ *              series: [{ name, values: number[],
+ *                         tone?: 'win'|'loss', tones?: (('win'|'loss'|null)[]) }] }
+ *   config = { type:'bar', title?, stacked?, log?, orient?: 'v'|'h',
+ *              catLabel?, valLabel? }
+ *
+ * The AST is orientation-agnostic: `u` runs along the category axis,
+ * `v` along the value axis; the render maps them to x/y per `orient`.
+ * Category lookups are hoisted out of the series loop (index-driven,
+ * never `categories.indexOf` per cell — that is O(n²) for wide charts).
+ */
+export type BarAST = {
+    type: 'bar';
+    title: string | null;
+    orient: 'v' | 'h';
+    cat: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    val: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    legend: {
+        name: string;
+        swatch: number;
+    }[] | null;
+    bars: BarMarkAST[];
+    /**
+     * number of categories
+     */
+    count: number;
+    /**
+     * resolved value-axis bounds
+     */
+    domain: [number, number];
+};
+export type BarMarkAST = {
+    u0: number;
+    /**
+     * category-axis band
+     */
+    u1: number;
+    v0: number;
+    /**
+     * value-axis extent
+     */
+    v1: number;
+    /**
+     * series index
+     */
+    series: number;
+    tone: 'win' | 'loss' | null;
+    /**
+     * the category this bar stands in
+     */
+    label: string;
+    /**
+     * the series name
+     */
+    name: string;
+    /**
+     * the drawn value (hover text reports it exactly)
+     */
+    value: number;
+};
+/**
+ * @typedef {object} BarAST
+ * @property {'bar'} type
+ * @property {string|null} title
+ * @property {'v'|'h'} orient
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} cat
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} val
+ * @property {{name: string, swatch: number}[]|null} legend
+ * @property {BarMarkAST[]} bars
+ * @property {number} count number of categories
+ * @property {[number, number]} domain resolved value-axis bounds
+ */
+/**
+ * @typedef {object} BarMarkAST
+ * @property {number} u0 @property {number} u1 category-axis band
+ * @property {number} v0 @property {number} v1 value-axis extent
+ * @property {number} series series index
+ * @property {'win'|'loss'|null} tone
+ * @property {string} label the category this bar stands in
+ * @property {string} name the series name
+ * @property {number} value the drawn value (hover text reports it exactly)
+ */
+/**
+ * Scan the drawn values for the extremes the value axis is resolved
+ * from: the largest bar (a stacked chart's per-category total) and the
+ * smallest positive value a log axis needs for its bottom decade.
+ *
+ * Exported because the incremental session must reach the same bounds
+ * decision from the same numbers — one implementation, no drift.
+ * @param {any} data
+ * @param {boolean} stacked @param {boolean} log
+ * @returns {{maxVal: number, minPos: number}}
+ */
+export declare function scanBarExtremes(data: any, stacked: boolean, log: boolean): {
+    maxVal: number;
+    minPos: number;
+};
+/**
+ * Resolve the value-axis bounds and tick values from the scanned
+ * extremes: a nice-number top over a zero base, or whole decades under
+ * `log`. The AST records the bounds so a later build — or the session —
+ * can detect "unchanged".
+ * @param {{maxVal: number, minPos: number}} ext
+ * @param {boolean} log
+ * @returns {{domain: [number, number], tickValues: number[]}}
+ */
+export declare function resolveBarDomains(ext: {
+    maxVal: number;
+    minPos: number;
+}, log: boolean): {
+    domain: [number, number];
+    tickValues: number[];
+};
+/**
+ * The value scale over a resolved domain — reconstructable by the
+ * session from the AST's domain alone.
+ * @param {[number, number]} domain @param {boolean} log
+ * @returns {(v: number) => number}
+ */
+export declare function barScale(domain: [number, number], log: boolean): (v: number) => number;
+/**
+ * Build the geometry-free bar AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {BarAST}
+ */
+export declare function buildBarAST(data: any, config?: any): BarAST;
+/**
+ * Render one bar as its `<rect>` value mark — the replaceable unit the
+ * incremental session re-emits when a live count changes.
+ * @param {BarMarkAST} bar
+ * @param {BarAST} ast
+ * @param {{x:number,y:number,w:number,h:number}} plot
+ * @param {{tokens: Record<string,string>}} theme
+ * @param {readonly string[]} palette
+ * @param {import('../core/marks.js').ChartTooltip|null} [tooltip]
+ * @returns {any}
+ */
+export declare function barMarkRender(bar: BarMarkAST, ast: BarAST, plot: {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, theme: {
+    tokens: Record<string, string>;
+}, palette: readonly string[], tooltip?: import('../core/marks.js').ChartTooltip | null): any;
+/**
+ * Render a bar AST and return the svg WITH the geometry a session needs
+ * to replace one bar in place: the plot rect and how many chrome
+ * children precede the bars.
+ * @param {BarAST} 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 {{svg: any, plot: {x:number,y:number,w:number,h:number}, chromeLen: number}}
+ */
+export declare function buildBarRender(ast: BarAST, 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;
+}): {
+    svg: any;
+    plot: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    chromeLen: number;
+};
+/**
+ * Render a bar AST to a pure-vnode SVG. Each bar rect carries a
+ * `<title>` naming its series, category and exact value — the axis
+ * shows the rounded tick scale, the hover text shows the datum.
+ * @param {BarAST} 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 renderBarAST(ast: BarAST, 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/boxplot.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @file The boxplot chart type: five-number summaries per category with
+ * Tukey whiskers and outlier dots. Data shape (two forms per box):
+ *
+ *   data   = { boxes: [{ label, values: number[] }                       // raw samples
+ *                    | { label, min, q1, med, q3, max, outliers? }] }    // precomputed
+ *   config = { type:'boxplot', title?, catLabel?, valLabel? }
+ *
+ * Raw samples get the standard treatment: quartiles by linear
+ * interpolation over the sorted values, whiskers at the most extreme
+ * samples inside the 1.5·IQR fences, everything outside them an
+ * outlier. Precomputed summaries are trusted as given (their whiskers
+ * are the stated min/max). The AST is unit-space: `u` along the
+ * category axis, `v` along the value axis.
+ */
+export type BoxAST = {
+    label: string;
+    u0: number;
+    u1: number;
+    /**
+     * whisker low
+     */
+    loV: number;
+    q1V: number;
+    medV: number;
+    q3V: number;
+    /**
+     * whisker high
+     */
+    hiV: number;
+    outliersV: number[];
+    stats: {
+        min: number;
+        q1: number;
+        med: number;
+        q3: number;
+        max: number;
+    };
+};
+export type BoxplotAST = {
+    type: 'boxplot';
+    title: string | null;
+    cat: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    val: {
+        ticks: {
+            pos: number;
+            label: string;
+        }[];
+        label: string | null;
+    };
+    boxes: BoxAST[];
+    /**
+     * number of categories
+     */
+    count: number;
+};
+/**
+ * @typedef {object} BoxAST
+ * @property {string} label
+ * @property {number} u0 @property {number} u1
+ * @property {number} loV whisker low @property {number} q1V
+ * @property {number} medV @property {number} q3V
+ * @property {number} hiV whisker high
+ * @property {number[]} outliersV
+ * @property {{min:number, q1:number, med:number, q3:number, max:number}} stats
+ */
+/**
+ * @typedef {object} BoxplotAST
+ * @property {'boxplot'} type
+ * @property {string|null} title
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} cat
+ * @property {{ticks: {pos:number,label:string}[], label: string|null}} val
+ * @property {BoxAST[]} boxes
+ * @property {number} count number of categories
+ */
+/**
+ * Quantile of an ascending-sorted sample by linear interpolation.
+ * @param {number[]} sorted - Ascending finite samples (non-empty)
+ * @param {number} p - Quantile in [0, 1]
+ * @returns {number}
+ */
+export declare function quantileSorted(sorted: number[], p: number): number;
+/**
+ * Build the geometry-free boxplot AST.
+ * @param {any} data
+ * @param {any} [config]
+ * @returns {BoxplotAST}
+ */
+export declare function buildBoxplotAST(data: any, config?: any): BoxplotAST;
+/**
+ * Render a boxplot AST to a pure-vnode SVG: capped whiskers, a
+ * translucent box with a full-strength median line, outlier dots, and
+ * a summary `<title>` per box.
+ * @param {BoxplotAST} 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 renderBoxplotAST(ast: BoxplotAST, 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;