@svgrid/grid 1.0.0

package/dist/chart-export.js

@@ -0,0 +1,112 @@
+/**
+ * Export a rendered `SvGridChart` to a standalone SVG file or a PNG image.
+ *
+ * The on-screen chart styles its axes / labels / gridlines with CSS classes
+ * and `--sg-*` theme variables, which don't survive a raw serialization. So
+ * we clone the SVG, read the live computed colors, and inline a small `<style>`
+ * block with concrete values - the export looks like what's on screen.
+ *
+ * Pass the chart's `<svg class="sv-grid-chart-svg">` element (or any ancestor
+ * that contains it).
+ */
+function resolveSvg(el) {
+    if (el instanceof SVGSVGElement)
+        return el;
+    return el.querySelector('svg.sv-grid-chart-svg') ?? el.querySelector('svg');
+}
+function cssVar(el, name, fallback) {
+    const v = getComputedStyle(el).getPropertyValue(name).trim();
+    return v || fallback;
+}
+/** Serialize the chart SVG to a standalone, self-styled SVG string. */
+export function chartToSvgString(source, options = {}) {
+    const svg = resolveSvg(source);
+    if (!svg)
+        throw new Error('chartToSvgString: no <svg> found');
+    const fg = cssVar(svg, '--sg-fg', '#0f172a');
+    const muted = cssVar(svg, '--sg-muted', '#64748b');
+    const border = cssVar(svg, '--sg-border', '#e2e8f0');
+    const bg = options.background ?? cssVar(svg, '--sg-bg', '#ffffff');
+    const vb = svg.viewBox.baseVal;
+    const w = vb && vb.width ? vb.width : svg.clientWidth || 520;
+    const h = vb && vb.height ? vb.height : svg.clientHeight || 300;
+    const clone = svg.cloneNode(true);
+    clone.setAttribute('width', String(w));
+    clone.setAttribute('height', String(h));
+    clone.setAttribute('xmlns', 'http://www.w3.org/2000/svg');
+    // Drop interaction-only hit layers.
+    clone.querySelectorAll('.sv-grid-chart-hit').forEach((n) => n.remove());
+    const style = document.createElementNS('http://www.w3.org/2000/svg', 'style');
+    style.textContent = `
+    .sv-grid-chart-axis { fill: ${muted}; font-size: 10px; font-family: sans-serif; }
+    .sv-grid-chart-gridline { stroke: ${border}; stroke-width: 1; opacity: 0.6; }
+    .sv-grid-chart-gridline.is-zero { stroke: ${muted}; opacity: 0.9; }
+    .sv-grid-chart-datalabel { fill: ${fg}; font-size: 9.5px; font-weight: 600; font-family: sans-serif; }
+    .sv-grid-chart-datalabel.on-bar { fill: #fff; }
+    .sv-grid-chart-donut-total { fill: ${fg}; font-size: 16px; font-weight: 800; font-family: sans-serif; }
+    .sv-grid-chart-donut-label { fill: ${muted}; font-size: 10px; font-family: sans-serif; }
+  `;
+    clone.insertBefore(style, clone.firstChild);
+    const rect = document.createElementNS('http://www.w3.org/2000/svg', 'rect');
+    rect.setAttribute('x', '0');
+    rect.setAttribute('y', '0');
+    rect.setAttribute('width', String(w));
+    rect.setAttribute('height', String(h));
+    rect.setAttribute('fill', bg);
+    clone.insertBefore(rect, style.nextSibling);
+    return new XMLSerializer().serializeToString(clone);
+}
+function triggerDownload(blobUrl, filename) {
+    const a = document.createElement('a');
+    a.href = blobUrl;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+}
+/** Download the chart as an `.svg` file. */
+export function downloadChartSvg(source, filename = 'chart.svg', options = {}) {
+    const svg = chartToSvgString(source, options);
+    const url = URL.createObjectURL(new Blob([svg], { type: 'image/svg+xml' }));
+    triggerDownload(url, filename);
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+/** Rasterize the chart to a PNG `Blob`. */
+export function chartToPngBlob(source, options = {}) {
+    const svgStr = chartToSvgString(source, options);
+    const scale = options.scale ?? 2;
+    const svgEl = resolveSvg(source);
+    const vb = svgEl.viewBox.baseVal;
+    const w = (vb && vb.width ? vb.width : svgEl.clientWidth || 520) * scale;
+    const h = (vb && vb.height ? vb.height : svgEl.clientHeight || 300) * scale;
+    return new Promise((resolve, reject) => {
+        const url = URL.createObjectURL(new Blob([svgStr], { type: 'image/svg+xml' }));
+        const img = new Image();
+        img.onload = () => {
+            const canvas = document.createElement('canvas');
+            canvas.width = Math.round(w);
+            canvas.height = Math.round(h);
+            const ctx = canvas.getContext('2d');
+            if (!ctx) {
+                URL.revokeObjectURL(url);
+                reject(new Error('canvas 2d context unavailable'));
+                return;
+            }
+            ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+            URL.revokeObjectURL(url);
+            canvas.toBlob((blob) => (blob ? resolve(blob) : reject(new Error('toBlob failed'))), 'image/png');
+        };
+        img.onerror = () => {
+            URL.revokeObjectURL(url);
+            reject(new Error('failed to rasterize chart SVG'));
+        };
+        img.src = url;
+    });
+}
+/** Download the chart as a `.png` file. */
+export async function downloadChartPng(source, filename = 'chart.png', options = {}) {
+    const blob = await chartToPngBlob(source, options);
+    const url = URL.createObjectURL(blob);
+    triggerDownload(url, filename);
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+}

package/dist/chart.d.ts

@@ -0,0 +1,226 @@
+/**
+ * Integrated chart geometry. Pure functions that turn categories + numeric
+ * series into SVG primitives - the "chart from a grid range" enterprise
+ * feature without bundling a charting library. The `<SvGridChart>` component
+ * paints the result; this module has no DOM so it is unit-testable.
+ *
+ * Supports: grouped + stacked bars, line, area, pie/donut, combo charts
+ * (per-series type), a secondary (right) Y axis, signed Y domains (negative
+ * values drop below a zero baseline), and nice auto-scaled ticks.
+ */
+export type ChartType = 'bar' | 'line' | 'area' | 'pie' | 'scatter';
+/** A clicked bar / point / slice - the payload of `SvGridChart`'s `onSelect`. */
+export type ChartSelection = {
+    category: string;
+    series: string;
+    value: number;
+};
+/** A single scatter / bubble point. */
+export type ScatterPoint = {
+    x: number;
+    y: number;
+    r?: number;
+    label?: string;
+};
+export type ChartSeries = {
+    label: string;
+    values: number[];
+    color?: string;
+    /** Per-series chart type, for combo charts. Defaults to the spec `type`. */
+    type?: 'bar' | 'line' | 'area';
+    /** Plot against the left (default) or right Y axis. */
+    axis?: 'left' | 'right';
+    /** Scatter / bubble points (used when `type === 'scatter'`). */
+    points?: ScatterPoint[];
+};
+/** A horizontal reference / target line drawn across the plot. */
+export type ChartReferenceLine = {
+    value: number;
+    label?: string;
+    axis?: 'left' | 'right';
+    color?: string;
+    dashed?: boolean;
+};
+export type ChartSpec = {
+    /** Default type for series that don't set their own `type`. */
+    type: ChartType;
+    /** X-axis labels (one per data point). */
+    categories: string[];
+    series: ChartSeries[];
+    width?: number;
+    height?: number;
+    /** Palette used when a series has no explicit `color`. */
+    palette?: string[];
+    /** Stack bar / area series (per axis) instead of grouping them. */
+    stacked?: boolean;
+    /** Stack to 100% (each category normalized to its total). Implies stacked. */
+    stacked100?: boolean;
+    /**
+     * Bar orientation. `'horizontal'` swaps the axes - categories run down the
+     * left, bars grow rightward - which suits long category labels. Only applies
+     * when every series is a bar (combo / line / area fall back to vertical).
+     */
+    orientation?: 'vertical' | 'horizontal';
+    /** Pie only: inner radius as a fraction of the outer radius (0..1) -> donut. */
+    innerRadius?: number;
+    /** Horizontal target / goal / average lines. */
+    referenceLines?: ChartReferenceLine[];
+    /** Treat `categories` as dates -> time-scaled x positions + date ticks. */
+    xType?: 'category' | 'time';
+    /** Axis titles (reserve gutter space + render). */
+    yAxisTitle?: string;
+    y2AxisTitle?: string;
+    xAxisTitle?: string;
+};
+export type ChartBar = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color: string;
+    /** Category (x label) this bar belongs to - for tooltips + labels. */
+    label: string;
+    /** Series label this bar belongs to. */
+    series: string;
+    value: number;
+};
+export type ChartLinePoint = {
+    x: number;
+    y: number;
+    label: string;
+    value: number;
+    /** False for null / NaN values - the line breaks (gap), no dot is drawn. */
+    defined: boolean;
+};
+export type ChartLine = {
+    path: string;
+    areaPath: string;
+    color: string;
+    label: string;
+    points: ChartLinePoint[];
+};
+export type ChartPieSlice = {
+    path: string;
+    color: string;
+    label: string;
+    value: number;
+    percent: number;
+    /** Centroid - anchor point for a data label. */
+    cx: number;
+    cy: number;
+};
+export type ChartAxisTick = {
+    value: number;
+    y: number;
+    label: string;
+};
+export type ChartCategoryTick = {
+    label: string;
+    x: number;
+};
+export type ChartLegendItem = {
+    label: string;
+    color: string;
+};
+export type ChartRefLineGeo = {
+    y: number;
+    label: string;
+    color: string;
+    dashed: boolean;
+};
+/** A vertical reference line (horizontal bar charts) positioned by `x`. */
+export type ChartRefLineGeoV = {
+    x: number;
+    label: string;
+    color: string;
+    dashed: boolean;
+};
+export type ChartScatterDot = {
+    cx: number;
+    cy: number;
+    r: number;
+    color: string;
+    label: string;
+    series: string;
+    x: number;
+    y: number;
+};
+export type ChartGeometry = {
+    type: ChartType;
+    width: number;
+    height: number;
+    plot: {
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    bars: ChartBar[];
+    lines: ChartLine[];
+    slices: ChartPieSlice[];
+    yTicks: ChartAxisTick[];
+    /** Right-axis ticks (combo / dual-axis); empty when there's no right axis. */
+    y2Ticks: ChartAxisTick[];
+    hasRightAxis: boolean;
+    xTicks: ChartCategoryTick[];
+    /** True when x labels are long/many and should be rotated. */
+    xLabelRotated: boolean;
+    legend: ChartLegendItem[];
+    /** Donut centre (pie + innerRadius), for a centre total label. */
+    donut: {
+        cx: number;
+        cy: number;
+        r: number;
+        total: number;
+    } | null;
+    /** Horizontal reference / target lines. */
+    referenceLines: ChartRefLineGeo[];
+    /** Scatter / bubble points (type === 'scatter'). */
+    scatterPoints: ChartScatterDot[];
+    /** Bar orientation. `'horizontal'` uses `valueTicks` / `catTicks` below. */
+    orientation: 'vertical' | 'horizontal';
+    /** Horizontal bars: value-axis ticks along the bottom (label + x). */
+    valueTicks: ChartCategoryTick[];
+    /** Horizontal bars: category labels down the left (label + y; value = index). */
+    catTicks: ChartAxisTick[];
+    /** Horizontal bars: vertical reference / target lines (positioned by x). */
+    referenceLinesV: ChartRefLineGeoV[];
+};
+export declare const DEFAULT_PALETTE: string[];
+export type NiceScale = {
+    min: number;
+    max: number;
+    step: number;
+    ticks: number[];
+};
+/** Round a [min,max] domain out to nice tick boundaries. */
+export declare function niceScale(min: number, max: number, tickCount?: number): NiceScale;
+export declare function buildChart(spec: ChartSpec): ChartGeometry;
+/**
+ * Aggregate flat rows into a chart spec. Group by a category field, reduce a
+ * value field per group. Three multi-series shapes:
+ *   - `value: 'revenue'`            -> one series
+ *   - `value: ['revenue','cost']`   -> one series per value field
+ *   - `value: 'sales', series: 'region'` -> pivot: one series per distinct
+ *                                            value of the `series` field
+ */
+export declare function rowsToChartSpec<T extends Record<string, unknown>>(rows: ReadonlyArray<T>, opts: {
+    type: ChartType;
+    category: keyof T & string;
+    value: (keyof T & string) | Array<keyof T & string>;
+    /** Pivot dimension: one series per distinct value of this field. */
+    series?: keyof T & string;
+    reduce?: 'sum' | 'avg' | 'count';
+    seriesLabel?: string;
+    width?: number;
+    height?: number;
+    stacked?: boolean;
+    stacked100?: boolean;
+    palette?: string[];
+    /** Order categories. Defaults to insertion order (or value-desc when topN). */
+    sort?: 'value-desc' | 'value-asc' | 'category' | 'none';
+    /** Keep only the top N categories; bucket the rest into "Other". */
+    topN?: number;
+    /** Label for the bucketed remainder. Default "Other". */
+    otherLabel?: string;
+}): ChartSpec;