@svgrid/grid 3.0.2 → 3.0.4

package/dist/chart-samples.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A small sample spec per chart type, for a type gallery: the builder's
+ * thumbnails, the docs. One tiny seeded dataset, so every card draws the
+ * same numbers and the shapes are what differ. Lives in its own module and
+ * is imported only by the builder, so a grid that never opens it never pays.
+ */
+import type { ChartSpec, ChartType } from './chart-types.js';
+/** The label a type gallery shows for each type. */
+export declare const CHART_TYPE_LABELS: Record<ChartType, string>;
+/**
+ * A complete, small spec of the given type, drawn from the shared sample
+ * dataset. Pass a `palette` to colour it like the chart it stands in for.
+ */
+export declare function sampleChartSpec(type: ChartType, palette?: string[]): ChartSpec;
+/** A sample spec trimmed for a thumbnail: no titles, no axis labels, small. */
+export declare function sampleChartThumb(type: ChartType, palette?: string[], width?: number, height?: number): ChartSpec;

package/dist/chart-samples.js

@@ -0,0 +1,153 @@
+import { rowsToBoxSpec, rowsToChartSpec, rowsToHistogramSpec, rowsToRangeSpec, rowsToScatterSpec, specToCalendar, specToSankey, specToTreemap } from './chart.js';
+let cached = null;
+function rows() {
+    if (cached)
+        return cached;
+    let seed = 7;
+    const rnd = () => ((seed = (seed * 1103515245 + 12345) % 2147483648) / 2147483648);
+    const regions = ['North', 'South', 'East', 'West'];
+    const channels = ['Web', 'Retail', 'Partner'];
+    const out = [];
+    const start = Date.UTC(2026, 0, 1);
+    for (let i = 0; i < 160; i += 1) {
+        const day = new Date(start + Math.floor(rnd() * 180) * 86400000).toISOString().slice(0, 10);
+        const units = 1 + Math.floor(rnd() * 12);
+        const price = 40 + rnd() * 160;
+        const revenue = Math.round(units * price);
+        out.push({ day, region: regions[Math.floor(rnd() * 4)], channel: channels[Math.floor(rnd() * 3)], units, cost: Math.round(revenue * (0.5 + rnd() * 0.3)), revenue });
+    }
+    cached = out;
+    return out;
+}
+/** The label a type gallery shows for each type. */
+export const CHART_TYPE_LABELS = {
+    bar: 'Bar', line: 'Line', area: 'Area', pie: 'Pie', scatter: 'Scatter', heatmap: 'Heat map', waterfall: 'Waterfall',
+    funnel: 'Funnel', radar: 'Radar', calendar: 'Calendar', gauge: 'Gauge', treemap: 'Tree map', sankey: 'Sankey',
+    candlestick: 'Candlestick', ohlc: 'OHLC', boxplot: 'Box plot', histogram: 'Histogram', 'range-bar': 'Range bar',
+    'range-area': 'Range area', lollipop: 'Lollipop', dumbbell: 'Dumbbell', pareto: 'Pareto', stream: 'Stream',
+    sunburst: 'Sunburst', 'radial-bar': 'Radial bar', 'radial-column': 'Radial column', nightingale: 'Nightingale',
+    chord: 'Chord', bullet: 'Bullet',
+};
+/**
+ * A complete, small spec of the given type, drawn from the shared sample
+ * dataset. Pass a `palette` to colour it like the chart it stands in for.
+ */
+export function sampleChartSpec(type, palette) {
+    const data = rows();
+    const byRegion = rowsToChartSpec(data, { type: 'bar', category: 'region', value: 'revenue' });
+    const byRegionChannel = rowsToChartSpec(data, { type: 'bar', category: 'region', value: 'revenue', series: 'channel' });
+    const byMonth = rowsToChartSpec(data, { type: 'line', category: 'day', value: 'revenue', bucket: 'month' });
+    const byMonthChannel = rowsToChartSpec(data, { type: 'area', category: 'day', value: 'revenue', series: 'channel', bucket: 'month' });
+    const ranged = () => rowsToRangeSpec(byRegion.categories.map((c, i) => ({ region: c, cost: byRegion.series[0].values[i] * 0.6, revenue: byRegion.series[0].values[i] })), { category: 'region', low: 'cost', high: 'revenue' });
+    const ohlc = () => {
+        const v = byMonth.series[0].values;
+        const bars = v.map((c, i) => { const o = i ? v[i - 1] : c * 0.95; return { o, c, h: Math.max(o, c) * 1.04, l: Math.min(o, c) * 0.96 }; });
+        return { categories: byMonth.categories, series: [{ label: 'Revenue', values: v, ohlc: bars }], xType: 'ordinal-time' };
+    };
+    let spec;
+    switch (type) {
+        case 'line':
+            spec = { ...byMonthChannel, type: 'line' };
+            break;
+        case 'area':
+            spec = { ...byMonthChannel, type: 'area', stacked: true };
+            break;
+        case 'lollipop':
+            spec = { ...byRegion, type: 'lollipop' };
+            break;
+        case 'dumbbell':
+            spec = { ...ranged(), type: 'dumbbell' };
+            break;
+        case 'range-bar':
+            spec = ranged();
+            break;
+        case 'range-area':
+            spec = { ...byMonth, type: 'range-area', series: [{ label: 'Band', values: byMonth.series[0].values.map((v) => v * 1.15), lowValues: byMonth.series[0].values.map((v) => v * 0.85) }] };
+            break;
+        case 'pareto':
+            spec = { ...rowsToChartSpec(data, { type: 'bar', category: 'channel', value: 'units' }), type: 'pareto' };
+            break;
+        case 'radial-column':
+            spec = { ...byRegionChannel, type: 'radial-column', stacked: true };
+            break;
+        case 'radial-bar':
+            spec = { ...byRegion, type: 'radial-bar' };
+            break;
+        case 'nightingale':
+            spec = { ...byMonth, type: 'nightingale' };
+            break;
+        case 'pie':
+            spec = { ...byRegion, type: 'pie', innerRadius: 0.55 };
+            break;
+        case 'treemap':
+            spec = { ...byRegionChannel, type: 'treemap', treemap: specToTreemap(byRegionChannel) };
+            break;
+        case 'sunburst':
+            spec = { ...byRegionChannel, type: 'sunburst', tree: specToTreemap(byRegionChannel) };
+            break;
+        case 'funnel':
+            spec = { type: 'funnel', categories: ['Visits', 'Sign-ups', 'Trials', 'Paid'], series: [{ label: 'Users', values: [12400, 5100, 2300, 880] }] };
+            break;
+        case 'waterfall':
+            spec = { type: 'waterfall', categories: ['Start', 'Web', 'Retail', 'Partner', 'Returns', 'End'], series: [{ label: 'P&L', values: [120, 48, 31, 22, -19, 0] }], waterfallTotals: [true, false, false, false, false, true] };
+            break;
+        case 'sankey': {
+            const f = specToSankey(byRegionChannel);
+            spec = { ...byRegionChannel, type: 'sankey', sankeyNodes: f.nodes, sankeyLinks: f.links };
+            break;
+        }
+        case 'chord': {
+            const f = specToSankey(byRegionChannel);
+            spec = { ...byRegionChannel, type: 'chord', sankeyNodes: f.nodes, sankeyLinks: f.links };
+            break;
+        }
+        case 'radar':
+            spec = { ...byRegionChannel, type: 'radar' };
+            break;
+        case 'heatmap':
+            spec = { ...byRegionChannel, type: 'heatmap' };
+            break;
+        case 'scatter':
+            spec = rowsToScatterSpec(data.slice(0, 80), { x: 'cost', y: 'revenue', series: 'channel', r: 'units' });
+            break;
+        case 'boxplot':
+            spec = rowsToBoxSpec(data, { category: 'region', value: 'revenue' });
+            break;
+        case 'histogram':
+            spec = rowsToHistogramSpec(data, { value: 'revenue', bins: 10 });
+            break;
+        case 'gauge':
+            spec = { type: 'gauge', categories: [], series: [], gaugeValue: 72, gaugeMin: 0, gaugeMax: 100, gaugeTarget: 80, gaugeUnit: '%', gaugeRanges: [{ from: 0, to: 50, color: '#ef4444' }, { from: 50, to: 75, color: '#f59e0b' }, { from: 75, to: 100, color: '#16a34a' }] };
+            break;
+        case 'bullet':
+            spec = { type: 'bullet', categories: byRegion.categories, series: [{ label: 'Revenue', values: byRegion.series[0].values, targets: byRegion.series[0].values.map((v, i) => v * (0.9 + (i % 3) * 0.1)) }] };
+            break;
+        case 'calendar': {
+            const daily = rowsToChartSpec(data, { type: 'bar', category: 'day', value: 'units' });
+            spec = { ...daily, type: 'calendar', calendarValues: specToCalendar(daily) };
+            break;
+        }
+        case 'stream':
+            spec = { ...byMonthChannel, type: 'stream', stacked: true, stackOffset: 'wiggle' };
+            break;
+        case 'candlestick':
+            spec = { type: 'candlestick', ...ohlc() };
+            break;
+        case 'ohlc':
+            spec = { type: 'ohlc', ...ohlc() };
+            break;
+        case 'bar':
+        default: spec = { ...byRegionChannel, type: 'bar' };
+    }
+    return palette ? { ...spec, palette } : spec;
+}
+/** A sample spec trimmed for a thumbnail: no titles, no axis labels, small. */
+export function sampleChartThumb(type, palette, width = 150, height = 92) {
+    const s = sampleChartSpec(type, palette);
+    return {
+        ...s, width, height, title: undefined, yAxisTitle: undefined, xAxisTitle: undefined, referenceLines: undefined,
+        xAxis: { ...(s.xAxis ?? {}), labels: false, title: undefined },
+        yAxis: { ...(s.yAxis ?? {}), labels: false, title: undefined },
+        y2Axis: { ...(s.y2Axis ?? {}), labels: false, title: undefined },
+    };
+}

package/dist/chart-scale.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Scales, ticks, number and date formatting, and the colour helpers the chart
+ * engine shares across every chart family. DOM-free.
+ */
+import type { ChartCategoryTick, NiceScale } from './chart-types.js';
+export { fmtTick, formatChartValue } from './chart-format.js';
+/** Series colours used when a {@link ChartSeries} sets none, in order. */
+export declare const DEFAULT_PALETTE: string[];
+/** @internal Two-decimal rounding for SVG coordinates. */
+export declare function round(n: number): number;
+/** @internal Nice-number rounding used by niceScale. */
+export declare function niceNum(range: number, roundIt: boolean): number;
+/** @internal Pick the colour-ramp stops for a heatmap / calendar. */
+export declare function resolveColorScale(scale: 'sequential' | 'diverging' | string[] | undefined, vMin: number, vMax: number, theme?: 'light' | 'dark'): string[];
+/** Sample a hex color from an array of hex stops at fractional position t.
+ *  Linearly interpolates between the two nearest stops in RGB space. */
+export declare function sampleGradient(stops: string[], t: number): string;
+/** Pick a black or white text color that has the better contrast against
+ *  the given background. Uses the WCAG relative-luminance heuristic. */
+export declare function pickContrastText(bgHex: string): string;
+/** Pick the largest power of 10 that fits at the bottom of [min,max], and
+ *  the smallest that covers the top, then enumerate decade boundaries. Used
+ *  by log-scale axes (yScale: 'log'). */
+export declare function niceLogScale(min: number, max: number): NiceScale;
+/**
+ * @internal Tick values for a logarithmic axis between two positive bounds:
+ * every decade, plus the 2 and 5 of each decade when the range spans fewer
+ * than three, so a two-decade axis does not read as three lonely labels.
+ */
+export declare function logTicks(min: number, max: number): number[];
+/** @internal Map a value to a fractional position [0..1] across the axis domain.
+ *  Pass the appropriate fn into projection code so linear / log share the
+ *  same plumbing. Returns null for non-positive values on log. */
+export declare function project(value: number, min: number, max: number, isLog: boolean): number | null;
+/** Round a [min,max] domain out to nice tick boundaries. */
+export declare function niceScale(min: number, max: number, tickCount?: number): NiceScale;
+/**
+ * A value-axis domain that honours an axis config on top of the data extent:
+ * a pinned `min` / `max` (hard edges - marks past them are clipped), an exact
+ * `tickInterval`, a `tickCount`, and `nice: false` for the raw extent with
+ * evenly spaced ticks. With no config this is exactly {@link niceScale}.
+ */
+export declare function axisScale(dataMin: number, dataMax: number, axis?: {
+    min?: number;
+    max?: number;
+    nice?: boolean;
+    tickCount?: number;
+    tickInterval?: number;
+}): NiceScale;
+/** @internal One day in milliseconds. */
+export declare const DAY = 86400000;
+/**
+ * @internal Calendar-aligned tick timestamps across [min, max], at most about
+ * `target` of them.
+ *
+ * The unit is the finest of day, week (Mondays), month, quarter, year and
+ * multiples of years whose count fits the target, and every tick sits on a
+ * calendar boundary in UTC (the axis parses 'YYYY-MM-DD' categories as UTC
+ * midnight). The old version stepped a fixed 30 or 365 days from the epoch,
+ * so a tick labelled "2025" stood weeks away from New Year and a thirty-month
+ * axis carried two labels on a plot with room for eight.
+ */
+export declare function dateTicks(tMin: number, tMax: number, target?: number): number[];
+/**
+ * Tick positions for an ordinal (evenly spaced) date axis, as INDICES into
+ * `times`.
+ *
+ * A time axis can put a tick anywhere, because x is a function of the
+ * timestamp. An ordinal axis cannot: x is a function of the index, so a tick
+ * has to land on a point that exists. This picks the first point of each
+ * calendar unit - day, week, month, year, whichever gets closest to `target`
+ * ticks without going over - so labels sit on real sessions and a weekend or a
+ * holiday never stretches the spacing.
+ */
+export declare function ordinalDateTicks(times: number[], target?: number): number[];
+/** @internal Date label sized to the gap between ticks: days and weeks read
+ *  "Jan 5", months and quarters "Jun 25", years "2025". Read in UTC: the axis
+ *  parses 'YYYY-MM-DD' as UTC midnight, and a local-time read of that in the
+ *  Americas labelled every tick with the day before. Sized to the tick step
+ *  rather than the axis span, so a thirty-month axis on quarters does not
+ *  read "2024, 2024, 2024, 2025". */
+export declare function fmtDate(t: number, step: number): string;
+/**
+ * @internal A category on a date axis, written out for a tooltip or a
+ * crosshair pill: "Jun 2025" when every category is the first of a month,
+ * "2025" when every one is New Year, otherwise "Jun 1, 2025". `grain` is
+ * what {@link dateGrain} found for the axis.
+ */
+export declare function fmtDateFull(t: number, grain?: 'day' | 'month' | 'year'): string;
+/** @internal The calendar grain a list of UTC timestamps sits on. */
+export declare function dateGrain(times: number[]): 'day' | 'month' | 'year';
+/**
+ * @internal Category-axis labels, thinned so they do not overlap.
+ *
+ * A category axis used to emit one tick per category however many there were.
+ * At 5000 categories that is 5000 `<text>` nodes stacked into an unreadable
+ * grey band - the labels were the single biggest thing the renderer had to put
+ * in the DOM, and none of them could be read. The time and ordinal-time axes
+ * already thinned themselves (`dateTicks` / `ordinalDateTicks`); this brings
+ * the plain category axis in line.
+ *
+ * The first category always gets a label, so a thinned axis still starts where
+ * the data does.
+ */
+export declare function thinCategoryTicks(categories: string[], xCenter: (i: number) => number, slot: number, rotated: boolean): ChartCategoryTick[];
+/** @internal Normalize one `errors` entry to an absolute low/high pair around `value`. */
+export declare function errorSpan(e: number | {
+    lo: number;
+    hi: number;
+} | null | undefined, value: number): {
+    lo: number;
+    hi: number;
+} | null;