@svgrid/grid 3.0.2 → 3.0.4

package/dist/chart-grid.js

@@ -0,0 +1,190 @@
+import { round, formatChartValue, resolveColorScale, sampleGradient, pickContrastText, thinCategoryTicks } from './chart-scale.js';
+// ---- Calendar heatmap --------------------------------------------
+// GitHub-style year-of-days view: 7 rows (Sun..Sat) x N weeks. Each
+// cell is a small square shaded by `calendarValues[i].value` via the
+// sequential color scale. Days with no value render blank (border only)
+// so missing data is visually obvious.
+/** @internal Lay out the calendar family. Called by buildChart. */
+export function layoutCalendar(ctx) {
+    const { spec, width, height, theme, empty, frame } = ctx;
+    const values = spec.calendarValues ?? [];
+    if (!values.length && !spec.calendarStart)
+        return { ...empty };
+    // Build a value lookup + figure out the date range.
+    const valueByDate = new Map();
+    let vMin = Infinity, vMax = -Infinity;
+    for (const v of values) {
+        valueByDate.set(v.date, v.value);
+        if (Number.isFinite(v.value)) {
+            if (v.value < vMin)
+                vMin = v.value;
+            if (v.value > vMax)
+                vMax = v.value;
+        }
+    }
+    if (vMin === Infinity) {
+        vMin = 0;
+        vMax = 1;
+    }
+    if (vMin === vMax)
+        vMax = vMin + 1;
+    const stops = resolveColorScale(spec.colorScale, vMin, vMax, theme);
+    const colorAt = (v) => sampleGradient(stops, (v - vMin) / (vMax - vMin));
+    // Determine date range. If calendarStart/End set, use them, otherwise
+    // span the data + round to whole weeks (Sun..Sat).
+    const sorted = values.map((v) => v.date).sort();
+    const startStr = spec.calendarStart ?? sorted[0] ?? '2026-01-01';
+    const endStr = spec.calendarEnd ?? sorted[sorted.length - 1] ?? startStr;
+    const start = new Date(startStr + 'T00:00:00Z');
+    const end = new Date(endStr + 'T00:00:00Z');
+    // Roll start back to its Sunday, end forward to its Saturday.
+    start.setUTCDate(start.getUTCDate() - start.getUTCDay());
+    end.setUTCDate(end.getUTCDate() + (6 - end.getUTCDay()));
+    const totalDays = Math.round((end.getTime() - start.getTime()) / 86400000) + 1;
+    const weeks = Math.ceil(totalDays / 7);
+    const padL = 36, padR = 80, padT = 26 + frame.top, padB = 16 + frame.bottom;
+    const plotW = Math.max(1, width - padL - padR);
+    const plotH = Math.max(1, height - padT - padB);
+    // Cell size: fit weeks across width, 7 rows down height.
+    const cellW = Math.floor(plotW / weeks);
+    const cellH = Math.floor(plotH / 7);
+    const cellSize = Math.max(6, Math.min(cellW, cellH));
+    const plot = { x: padL, y: padT, w: cellSize * weeks, h: cellSize * 7 };
+    const cells = [];
+    let lastMonth = -1;
+    const monthTicks = [];
+    for (let i = 0; i < totalDays; i += 1) {
+        const day = new Date(start.getTime() + i * 86400000);
+        const col = Math.floor(i / 7);
+        const row = i % 7;
+        const date = day.toISOString().slice(0, 10);
+        const has = valueByDate.has(date);
+        const v = valueByDate.get(date) ?? 0;
+        cells.push({
+            x: padL + col * cellSize,
+            y: padT + row * cellSize,
+            size: cellSize,
+            date, value: v,
+            defined: has,
+            color: has ? colorAt(v) : 'transparent',
+        });
+        // A month label only for a month inside the range: the end is rolled
+        // forward to its Saturday, and a December that ends on a Thursday used
+        // to pick up a "Jan" for the two padding days of the next year.
+        if (day.getUTCDate() === 1 && day.getUTCMonth() !== lastMonth && date >= startStr && date <= endStr) {
+            lastMonth = day.getUTCMonth();
+            monthTicks.push({
+                label: day.toLocaleDateString(undefined, { month: 'short' }),
+                x: padL + col * cellSize,
+            });
+        }
+    }
+    const legend = Array.from({ length: 5 }, (_, i) => {
+        const t = i / 4;
+        const value = legendValue(vMin, vMax, t);
+        return { value, color: colorAt(value), label: formatChartValue(value, spec.valueFormat, spec) };
+    });
+    return {
+        ...empty,
+        plot,
+        calendarCells: cells,
+        calendarMonthTicks: monthTicks,
+        calendarLegend: legend,
+    };
+}
+// ---- Heatmap ------------------------------------------------------
+// Each series is one row, series.values are the cells across categories.
+// Color comes from a sequential/diverging/custom palette mapped to the
+// global value range. Cell text contrasts black/white against the cell.
+/**
+ * A legend step between the extremes, rounded to the precision the range
+ * earns: whole numbers when the steps are a unit or more apart, so a count
+ * legend reads "20, 94, 167" rather than "20, 93.5, 167", and enough
+ * decimals to tell the steps apart when they are not.
+ */
+function legendValue(vMin, vMax, t) {
+    const raw = vMin + (vMax - vMin) * t;
+    const step = Math.abs(vMax - vMin) / 4;
+    if (!(step > 0))
+        return raw;
+    const decimals = step >= 1 ? 0 : Math.min(6, Math.ceil(-Math.log10(step)) + 1);
+    return Number(raw.toFixed(decimals));
+}
+/** @internal Lay out the heatmap family. Called by buildChart. */
+export function layoutHeatmap(ctx) {
+    const { spec, series, width, height, theme, empty, frame } = ctx;
+    if (!series.length || !spec.categories.length)
+        return { ...empty, plot: { x: 0, y: 0, w: width, h: height } };
+    // Layout: left gutter for row labels, bottom for column labels.
+    const maxRowLabel = series.reduce((m, s) => Math.max(m, s.label.length), 0);
+    const padL = 12 + Math.min(180, Math.max(60, maxRowLabel * 7));
+    const padR = 64; // room for the right-side legend bar
+    const padT = 12 + frame.top;
+    const padB = 32 + frame.bottom;
+    const plotW = Math.max(1, width - padL - padR);
+    const plotH = Math.max(1, height - padT - padB);
+    const plot = { x: padL, y: padT, w: plotW, h: plotH };
+    const cellW = plotW / spec.categories.length;
+    const cellH = plotH / series.length;
+    // Resolve value range across the whole matrix.
+    let vMin = Infinity, vMax = -Infinity;
+    for (const s of series)
+        for (const v of s.values) {
+            if (!Number.isFinite(v))
+                continue;
+            if (v < vMin)
+                vMin = v;
+            if (v > vMax)
+                vMax = v;
+        }
+    if (vMin === Infinity) {
+        vMin = 0;
+        vMax = 1;
+    }
+    if (vMin === vMax)
+        vMax = vMin + 1;
+    // Pick the palette stops.
+    const stops = resolveColorScale(spec.colorScale, vMin, vMax, theme);
+    const colorAt = (v) => sampleGradient(stops, (v - vMin) / (vMax - vMin));
+    const heatmapCells = [];
+    series.forEach((s, ri) => {
+        s.values.forEach((v, ci) => {
+            if (!Number.isFinite(v))
+                return;
+            const color = colorAt(v);
+            heatmapCells.push({
+                x: round(padL + cellW * ci),
+                y: round(padT + cellH * ri),
+                w: round(cellW),
+                h: round(cellH),
+                color,
+                textColor: pickContrastText(color),
+                value: v,
+                rowLabel: s.label,
+                colLabel: spec.categories[ci] ?? '',
+            });
+        });
+    });
+    const heatmapRowTicks = series.map((s, i) => ({
+        value: i,
+        y: round(padT + cellH * i + cellH / 2),
+        label: s.label,
+    }));
+    // Column labels thin out the way a bar chart's do: twenty-four hours at
+    // 33px a cell wrote "00:0001:0002:00" across the foot of the matrix.
+    const heatmapColTicks = thinCategoryTicks(spec.categories, (i) => round(padL + cellW * i + cellW / 2), cellW, false);
+    // Legend: sample 5 stops across the range.
+    const heatmapLegend = Array.from({ length: 5 }, (_, i) => {
+        const t = i / 4;
+        const value = legendValue(vMin, vMax, t);
+        return { value, color: colorAt(value), label: formatChartValue(value, spec.valueFormat, spec) };
+    });
+    return {
+        ...empty,
+        plot,
+        heatmapCells,
+        heatmapRowTicks,
+        heatmapColTicks,
+        heatmapLegend,
+    };
+}

package/dist/chart-hierarchy.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Hierarchy layouts: the squarified tree-map.
+ */
+import type { TreeNode, ChartGeometry, LayoutCtx } from './chart-types.js';
+/** @internal Lay out the treemap family. Called by buildChart. */
+export declare function layoutTreemap(ctx: LayoutCtx): ChartGeometry;
+/**
+ * The subtree at `path` (a list of node names from the root's children down),
+ * or the tree itself for an empty path. What a drilldown shows after each
+ * click: the clicked node becomes the root. Null when the path does not exist.
+ */
+export declare function drillTree(tree: TreeNode, path: ReadonlyArray<string>): TreeNode | null;
+/**
+ * The path (node names from the root's children) to the first node called
+ * `name`, depth first, or null. What a click on a leaf's label needs.
+ */
+export declare function pathTo(tree: TreeNode, name: string): string[] | null;

package/dist/chart-hierarchy.js

@@ -0,0 +1,146 @@
+import { round, pickContrastText, DEFAULT_PALETTE } from './chart-scale.js';
+// ---- Tree-map -----------------------------------------------------
+// Squarified tree-map (Bruls et al. 2000): each level recursively
+// partitions its rectangle in proportion to its children, picking the
+// split orientation that keeps aspect ratios closest to 1.
+/** @internal Lay out the treemap family. Called by buildChart. */
+export function layoutTreemap(ctx) {
+    const { spec, width, height, empty, frame } = ctx;
+    const root = spec.treemap ?? spec.tree;
+    if (!root)
+        return { ...empty };
+    const padL = 4, padR = 4, padT = 4 + frame.top, padB = 4 + frame.bottom;
+    const plotW = Math.max(1, width - padL - padR);
+    const plotH = Math.max(1, height - padT - padB);
+    const plot = { x: padL, y: padT, w: plotW, h: plotH };
+    const palette = spec.palette ?? DEFAULT_PALETTE;
+    const cells = [];
+    function totalOf(n) {
+        if (n.children?.length)
+            return n.children.reduce((s, c) => s + totalOf(c), 0);
+        return Math.max(0, n.value ?? 0);
+    }
+    function squarify(items, x, y, w, h, depth) {
+        if (!items.length || w <= 0 || h <= 0)
+            return;
+        const totals = items.map(totalOf);
+        const sum = totals.reduce((a, b) => a + b, 0);
+        if (sum <= 0)
+            return;
+        // Process largest-first so big items dominate the first row.
+        const ordered = items
+            .map((n, i) => ({ node: n, value: totals[i] }))
+            .sort((a, b) => b.value - a.value);
+        let cx = x, cy = y, cw = w, ch = h, remaining = sum;
+        let row = [];
+        const worstRatio = (vals, shortSide, rowSum, scale) => {
+            if (rowSum <= 0)
+                return Infinity;
+            const rowArea = rowSum * scale;
+            const rowSide = rowArea / shortSide;
+            let worst = 0;
+            for (const v of vals) {
+                const cell = v * scale;
+                const long = cell / rowSide;
+                const r = Math.max(shortSide / long, long / shortSide);
+                if (r > worst)
+                    worst = r;
+            }
+            return worst;
+        };
+        function flushRow() {
+            if (!row.length)
+                return;
+            const rowSum = row.reduce((a, b) => a + b.value, 0);
+            const scale = (cw * ch) / remaining;
+            const horizontal = cw >= ch;
+            const shortSide = horizontal ? ch : cw;
+            const rowSide = (rowSum * scale) / shortSide;
+            let offset = 0;
+            for (const it of row) {
+                const cellSize = (it.value * scale) / rowSide;
+                const cx2 = horizontal ? cx : cx + offset;
+                const cy2 = horizontal ? cy + offset : cy;
+                const ww = horizontal ? rowSide : cellSize;
+                const hh = horizontal ? cellSize : rowSide;
+                const color = it.node.color ?? palette[(depth + cells.length) % palette.length];
+                // Leaf: emit a cell. Branch: recurse into the rect minus a label gutter.
+                if (it.node.children?.length) {
+                    cells.push({
+                        x: round(cx2), y: round(cy2), w: round(ww), h: round(hh),
+                        color, textColor: pickContrastText(color),
+                        name: it.node.name, value: it.value, depth,
+                    });
+                    const labelH = Math.min(18, hh * 0.25);
+                    squarify(it.node.children, cx2 + 1, cy2 + labelH, ww - 2, hh - labelH - 1, depth + 1);
+                }
+                else {
+                    cells.push({
+                        x: round(cx2), y: round(cy2), w: round(ww), h: round(hh),
+                        color, textColor: pickContrastText(color),
+                        name: it.node.name, value: it.value, depth,
+                    });
+                }
+                offset += cellSize;
+            }
+            // Shrink the remaining strip.
+            if (horizontal) {
+                cx += rowSide;
+                cw -= rowSide;
+            }
+            else {
+                cy += rowSide;
+                ch -= rowSide;
+            }
+            remaining -= rowSum;
+            row = [];
+        }
+        for (const it of ordered) {
+            const scale = (cw * ch) / remaining;
+            const shortSide = Math.min(cw, ch);
+            const rowSum = row.reduce((a, b) => a + b.value, 0);
+            const currWorst = worstRatio(row.map((r) => r.value), shortSide, rowSum, scale);
+            const nextWorst = worstRatio([...row.map((r) => r.value), it.value], shortSide, rowSum + it.value, scale);
+            if (row.length && nextWorst > currWorst) {
+                flushRow();
+            }
+            row.push(it);
+        }
+        flushRow();
+    }
+    const seedItems = root.children ?? [root];
+    squarify(seedItems, padL, padT, plotW, plotH, 0);
+    return { ...empty, plot, treemapCells: cells };
+}
+/**
+ * The subtree at `path` (a list of node names from the root's children down),
+ * or the tree itself for an empty path. What a drilldown shows after each
+ * click: the clicked node becomes the root. Null when the path does not exist.
+ */
+export function drillTree(tree, path) {
+    let node = tree;
+    for (const name of path) {
+        node = node?.children?.find((c) => c.name === name);
+        if (!node)
+            return null;
+    }
+    return node ?? null;
+}
+/**
+ * The path (node names from the root's children) to the first node called
+ * `name`, depth first, or null. What a click on a leaf's label needs.
+ */
+export function pathTo(tree, name) {
+    const walk = (n, acc) => {
+        for (const c of n.children ?? []) {
+            const next = [...acc, c.name];
+            if (c.name === name)
+                return next;
+            const deeper = walk(c, next);
+            if (deeper)
+                return deeper;
+        }
+        return null;
+    };
+    return walk(tree, []);
+}

package/dist/chart-indicators.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Technical indicators for financial charts: the overlays that sit on the
+ * price (Bollinger bands, VWAP, weighted moving average) and the oscillators
+ * that get a pane of their own (RSI, MACD, stochastic, ATR, OBV, volume).
+ *
+ * Every function is pure, takes plain arrays and returns arrays of the same
+ * length, NaN-padded where the window is not full yet, so the result lines up
+ * with `categories` and draws as a gap rather than as a fake zero. Wilder's
+ * smoothing (RSI, ATR) seeds with a simple average over the first period and
+ * then smooths recursively, which is what every charting terminal shows.
+ */
+import type { ChartSpec, OhlcBar, SeriesOverlay } from './chart-types.js';
+import { type RegressionFit } from './chart-stats.js';
+/** Which indicator a pane shows, and with what parameters. */
+export type ChartIndicatorSpec = {
+    kind: 'rsi' | 'macd' | 'stochastic' | 'atr' | 'obv' | 'volume';
+    /** The series (by label) the indicator reads. Defaults to the first
+     *  series with `ohlc`, else the first series. */
+    source?: string;
+    /** Periods: `period` (RSI / ATR / stochastic %K), `fast` / `slow` /
+     *  `signal` (MACD), `smooth` (stochastic %D). Each has the usual default. */
+    params?: {
+        period?: number;
+        fast?: number;
+        slow?: number;
+        signal?: number;
+        smooth?: number;
+    };
+    /** Pane height in px; the default is a third of the main chart. */
+    height?: number;
+};
+/** Weighted moving average: the latest value weighs `period`, the oldest 1. */
+export declare function wma(values: ReadonlyArray<number>, period: number): number[];
+/**
+ * Bollinger bands: a simple moving average with a band `k` standard
+ * deviations either side (population deviation, as the terminals compute it).
+ */
+export declare function bollingerBands(values: ReadonlyArray<number>, period?: number, k?: number): {
+    middle: number[];
+    upper: number[];
+    lower: number[];
+};
+/**
+ * Relative strength index over `period` bars, 0 to 100. The first value lands
+ * at index `period`; before it there is nothing to average.
+ */
+export declare function rsi(values: ReadonlyArray<number>, period?: number): number[];
+/**
+ * Moving average convergence / divergence: the fast EMA minus the slow one,
+ * its signal EMA, and the histogram between them.
+ */
+export declare function macd(values: ReadonlyArray<number>, fast?: number, slow?: number, signal?: number): {
+    macd: number[];
+    signal: number[];
+    histogram: number[];
+};
+/**
+ * Volume-weighted average price, cumulative from the first bar. Reset it per
+ * session by resampling or slicing before calling.
+ */
+export declare function vwap(ohlc: ReadonlyArray<OhlcBar | null | undefined>, volumes: ReadonlyArray<number>): number[];
+/** Average true range with Wilder's smoothing. */
+export declare function atr(ohlc: ReadonlyArray<OhlcBar | null | undefined>, period?: number): number[];
+/**
+ * Stochastic oscillator: %K is where the close sits in the last `period`
+ * bars' range (0 to 100), %D its `smooth`-bar simple average.
+ */
+export declare function stochastic(ohlc: ReadonlyArray<OhlcBar | null | undefined>, period?: number, smooth?: number): {
+    k: number[];
+    d: number[];
+};
+/** On-balance volume: a running total that adds volume on up closes and
+ *  subtracts it on down closes. */
+export declare function obv(closes: ReadonlyArray<number>, volumes: ReadonlyArray<number>): number[];
+/**
+ * Compute overlay values for a series spec like 'sma:7' / 'ema:14' / 'wma:9' /
+ * 'linear'. `'bb:N:K'` returns the band's middle line (the engine draws the
+ * band from `bollingerBands` itself) and `'vwap'` needs bars and volumes, so
+ * it comes back as gaps here; pass `extra` for those two.
+ */
+export declare function computeOverlay(values: number[], spec: SeriesOverlay, extra?: {
+    ohlc?: ReadonlyArray<OhlcBar | null>;
+    volumes?: ReadonlyArray<number>;
+}): number[];
+/**
+ * {@link computeOverlay} plus what a regression knows about itself: its
+ * R-squared and equation. The moving averages, the bands and VWAP carry
+ * neither.
+ */
+export declare function computeOverlayFit(values: number[], spec: SeriesOverlay, extra?: {
+    ohlc?: ReadonlyArray<OhlcBar | null>;
+    volumes?: ReadonlyArray<number>;
+}): {
+    values: number[];
+    r2?: number;
+    equation?: string;
+};
+/**
+ * The regression an overlay string names (`linear`, `poly:N`, `exp`, `log`,
+ * `power`), fitted to `values` on their index or on `xs`; `null` for the
+ * moving averages and bands, which are not regressions. A scatter passes its
+ * points' x and y so the curve is y on x, and reads `predict` to draw it.
+ */
+export declare function regressionFit(values: ReadonlyArray<number>, spec: SeriesOverlay, xs?: ReadonlyArray<number>): RegressionFit | null;
+/** The name a tooltip or legend gives an overlay: `sma:20` reads "SMA 20",
+ *  `poly:3` "poly 3", `bb:20:2` "BB 20", the rest as written. */
+export declare function overlayName(spec: SeriesOverlay): string;
+/**
+ * Build the spec of an indicator pane from a price spec: the same categories
+ * and x axis, the indicator's lines or bars, and the reference lines the
+ * indicator is read against (30 / 70 for RSI, 20 / 80 for the stochastic, a
+ * zero line for MACD). `SvChartPanes` stacks these under the price chart and
+ * syncs them; a pane is also a complete spec for a standalone `SvChart`.
+ */
+export declare function indicatorPane(spec: ChartSpec, ind: ChartIndicatorSpec): ChartSpec;