@svgrid/grid 3.0.2 → 3.0.4

package/dist/chart-pivot.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Pivot result -> chart spec.
+ *
+ * Turns the `{ rows, columns }` a pivot engine produces (the enterprise
+ * engine, through the `pivot` prop or `SvPivotDesigner`) into a {@link
+ * ChartSpec}, so one pivot layout drives both the table and a chart. The
+ * grid's own Chart panel runs this in pivot mode; enterprise's
+ * `pivotToChartSpec` is this function with its own types.
+ *
+ * Mapping:
+ *   - categories = the row-axis LEAF rows (subtotals and the grand-total row
+ *     are skipped). With nested rows the parents become a second axis tier
+ *     (`categoryGroups`). With no row dims, the single total row.
+ *   - series     = the column-axis leaf value columns (one per col-path x
+ *     measure). The grand-total column is excluded unless `includeTotals`.
+ *   - values     = each leaf row's aggregated cell for that series column; an
+ *     empty cell (an average over no rows is null) is a gap, not a zero.
+ */
+import type { CellFormatConfig } from './core.js';
+import type { ChartSpec, ChartType } from './chart-types.js';
+/** What {@link pivotResultToChartSpec} reads: the engine's rows and column tree, loosely typed so either package's result fits. */
+export type PivotResultLike = {
+    rows: ReadonlyArray<Record<string, unknown>>;
+    columns: ReadonlyArray<unknown>;
+};
+/** Options for {@link pivotResultToChartSpec}. */
+export type PivotResultChartOptions = {
+    /** Chart type. Default `'bar'`. A type that reads rows directly (scatter, gauge, box plot, histogram, ranges, bullet, candles) cannot be built from a pivot; see {@link pivotChartType}. */
+    type?: ChartType;
+    /** Stack the series. Default false. */
+    stacked?: boolean;
+    /** Stack to 100%. Implies `stacked`. */
+    stacked100?: boolean;
+    /** Include the grand-total column / row as a series / category. Default false. */
+    includeTotals?: boolean;
+    /** Cap the number of categories (row leaves) charted. */
+    maxCategories?: number;
+    /**
+     * The measure's cell format, carried to the chart as `valueFormat` (with
+     * `currency` and `locale`), so a cell the table shows as "$469,662" charts
+     * as "$470k" on the axis and "$469,662" in the tooltip rather than "470k".
+     * With several measures in different formats, pass none.
+     */
+    format?: CellFormatConfig;
+    /**
+     * The layout's measures, each with its cell `format`, when the caller has
+     * them rather than one format: used as `format` when they agree, ignored
+     * when a layout mixes a currency and a count (a "$" on the count would be
+     * wrong).
+     */
+    measures?: ReadonlyArray<{
+        format?: unknown;
+    }>;
+    /** Name the value axis. Default: the measure's label when the layout has one measure, nothing otherwise; `null` for none. */
+    yAxisTitle?: string | null;
+    /** Series colours, when the caller has a palette. */
+    palette?: string[];
+};
+/** The type a pivot chart can draw: the one asked for, or a bar chart when that type cannot be built from a pivot. */
+export declare function pivotChartType(type: ChartType | undefined): ChartType;
+/**
+ * The grid column a click on a pivot chart filters: the innermost row
+ * dimension, when the grid has a column for that field. A category of the
+ * chart is one value of it, so a value filter there narrows the source rows
+ * and the pivot with them.
+ */
+export declare function pivotFilterColumn(rowFields: ReadonlyArray<string>, columns: ReadonlyArray<{
+    id: string;
+}>, fieldOf: (id: string) => string | undefined): string | null;
+/**
+ * Server aggregates as a spec: the grid panel's `charting.getAggregate` hands
+ * back `{ category, series?, value }` buckets and this lays them out as one
+ * series per distinct `series` (or a single one), categories in first-seen
+ * order, a missing cell as 0.
+ */
+export declare function bucketsToChartSpec(buckets: ReadonlyArray<{
+    category: string;
+    series?: string;
+    value: number;
+}>, type: ChartType, hasSeries: boolean): ChartSpec;
+/**
+ * A computed pivot as a chart spec. Row leaves become the categories (nested
+ * rows a grouped axis), column leaves the series, totals are left out unless
+ * asked for, the measure's format and name come along, and an empty cell is
+ * a gap.
+ */
+export declare function pivotResultToChartSpec(result: PivotResultLike, opts?: PivotResultChartOptions): ChartSpec;

package/dist/chart-pivot.js

@@ -0,0 +1,156 @@
+/** Types that read rows one by one or need a shape a pivot does not have. */
+const UNSHAPED = new Set([
+    'scatter', 'gauge', 'boxplot', 'histogram', 'range-bar', 'range-area', 'dumbbell', 'bullet', 'candlestick', 'ohlc',
+]);
+/** The type a pivot chart can draw: the one asked for, or a bar chart when that type cannot be built from a pivot. */
+export function pivotChartType(type) {
+    return !type || UNSHAPED.has(type) ? 'bar' : type;
+}
+/**
+ * The grid column a click on a pivot chart filters: the innermost row
+ * dimension, when the grid has a column for that field. A category of the
+ * chart is one value of it, so a value filter there narrows the source rows
+ * and the pivot with them.
+ */
+export function pivotFilterColumn(rowFields, columns, fieldOf) {
+    const field = rowFields[rowFields.length - 1];
+    return (field && columns.find((c) => fieldOf(c.id) === field)?.id) || null;
+}
+/**
+ * Server aggregates as a spec: the grid panel's `charting.getAggregate` hands
+ * back `{ category, series?, value }` buckets and this lays them out as one
+ * series per distinct `series` (or a single one), categories in first-seen
+ * order, a missing cell as 0.
+ */
+export function bucketsToChartSpec(buckets, type, hasSeries) {
+    const cats = [];
+    const catIdx = new Map();
+    const seriesMap = new Map();
+    for (const b of buckets) {
+        let ci = catIdx.get(b.category);
+        if (ci === undefined) {
+            ci = cats.length;
+            catIdx.set(b.category, ci);
+            cats.push(b.category);
+        }
+        const key = hasSeries ? (b.series ?? '') : 'value';
+        let arr = seriesMap.get(key);
+        if (!arr) {
+            arr = [];
+            seriesMap.set(key, arr);
+        }
+        arr[ci] = (arr[ci] ?? 0) + b.value;
+    }
+    return {
+        type,
+        categories: cats,
+        series: [...seriesMap.entries()].map(([label, values]) => ({ label, values: cats.map((_, i) => values[i] ?? 0) })),
+    };
+}
+/** The chart fields a cell format maps to. Dates have no place on a value axis. */
+function chartFormat(f) {
+    if (!f)
+        return {};
+    const locale = Array.isArray(f.locales) ? f.locales[0] : f.locales;
+    const base = locale ? { locale } : {};
+    if (f.type === 'number')
+        return { ...base, valueFormat: 'number' };
+    if (f.type === 'currency')
+        return { ...base, valueFormat: 'currency', currency: f.currency ?? 'USD' };
+    if (f.type === 'percent') {
+        // The chart's percent format multiplies by 100 the way Intl does; cells
+        // that hold percentage points already read "42", so they take a
+        // formatter that only appends the sign.
+        if (f.valueIsPercentPoints)
+            return { ...base, yAxis: { formatter: (v) => `${v}%` } };
+        return { ...base, valueFormat: 'percent' };
+    }
+    return {};
+}
+/**
+ * A computed pivot as a chart spec. Row leaves become the categories (nested
+ * rows a grouped axis), column leaves the series, totals are left out unless
+ * asked for, the measure's format and name come along, and an empty cell is
+ * a gap.
+ */
+export function pivotResultToChartSpec(result, opts = {}) {
+    const type = pivotChartType(opts.type);
+    // Category rows: the row-axis leaves. Fall back to the grand-total (single
+    // "All") row when no row dims are configured, then to every row.
+    let catRows = result.rows.filter((r) => r.__pivotKind === 'leaf');
+    if (!catRows.length)
+        catRows = result.rows.filter((r) => r.__pivotKind === 'grandTotal');
+    if (!catRows.length)
+        catRows = result.rows.slice();
+    if (opts.maxCategories && catRows.length > opts.maxCategories)
+        catRows = catRows.slice(0, opts.maxCategories);
+    // Categories are the leaf's OWN label; when rows are nested, emit a parent
+    // tier (categoryGroups) so the axis reads "Americas | Canada, USA ..." as a
+    // grouped axis rather than colliding on a bare repeated leaf label.
+    const byId = new Map(result.rows.map((r) => [r.__pivotId, r]));
+    const ownLabel = (r) => String(r.__pivotLabel ?? '').trim() || '(blank)';
+    const categories = catRows.map(ownLabel);
+    const parentOf = (r) => (r.__pivotParentId ? byId.get(r.__pivotParentId) : undefined);
+    const nested = catRows.length > 0 && catRows.every((r) => parentOf(r) !== undefined);
+    let categoryGroups;
+    if (nested) {
+        categoryGroups = [];
+        let prevId;
+        for (const r of catRows) {
+            const pid = r.__pivotParentId;
+            const last = categoryGroups[categoryGroups.length - 1];
+            if (last && pid === prevId)
+                last.span += 1;
+            else {
+                categoryGroups.push({ label: ownLabel(parentOf(r)), span: 1 });
+                prevId = pid;
+            }
+        }
+    }
+    const leaves = [];
+    const walk = (cols, path) => {
+        for (const c of cols ?? []) {
+            if (!c || c.id === '__pivotRowHeader')
+                continue;
+            // Skip the grand-total column group (and its leaves) unless asked for.
+            if (!opts.includeTotals && typeof c.id === 'string' && c.id.startsWith('pv_group__grand'))
+                continue;
+            if (Array.isArray(c.columns))
+                walk(c.columns, [...path, String(c.header ?? '')]);
+            else if (typeof c.id === 'string')
+                leaves.push({ id: c.id, path, header: String(c.header ?? '') });
+        }
+    };
+    walk(result.columns, []);
+    const filtered = opts.includeTotals ? leaves : leaves.filter((l) => !l.id.includes('__total'));
+    const uniqueHeaders = new Set(filtered.map((l) => l.header));
+    const series = filtered.map((l) => ({
+        label: l.path.length === 0 ? l.header : uniqueHeaders.size > 1 ? [...l.path, l.header].join(' · ') : l.path.join(' · '),
+        values: catRows.map((r) => {
+            const v = r[l.id];
+            // An empty cell (an average over no rows is null) is a gap in the
+            // chart, not a zero bar; a sum over no rows is the 0 the engine wrote.
+            if (v == null || v === '')
+                return Number.NaN;
+            return typeof v === 'number' ? v : Number(v);
+        }),
+    }));
+    // With one measure the value axis can carry its name; the series are then
+    // the column-axis values and say nothing about what is measured.
+    const measureLabel = uniqueHeaders.size === 1 && filtered.length ? filtered[0].header : '';
+    const yAxisTitle = opts.yAxisTitle === undefined ? measureLabel : opts.yAxisTitle;
+    const formats = (opts.measures ?? []).map((m) => m.format);
+    const agreed = formats[0] && formats.every((f) => f && JSON.stringify(f) === JSON.stringify(formats[0])) ? formats[0] : undefined;
+    const fmt = chartFormat(opts.format ?? agreed);
+    return {
+        type,
+        categories,
+        series,
+        ...(categoryGroups && categoryGroups.length > 1 ? { categoryGroups } : {}),
+        ...(opts.stacked || opts.stacked100 ? { stacked: true } : {}),
+        ...(opts.stacked100 ? { stacked100: true } : {}),
+        ...(opts.palette ? { palette: opts.palette } : {}),
+        ...fmt,
+        ...(yAxisTitle ? { yAxis: { ...fmt.yAxis, title: yAxisTitle } } : {}),
+    };
+}

package/dist/chart-polar.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Polar layouts: pie / donut, radar, the gauge dial, and the arc family
+ * (sunburst, radial bar / column, nightingale, chord).
+ */
+import type { ChartGeometry, LayoutCtx } from './chart-types.js';
+/** @internal Lay out the radar family. Called by buildChart. */
+export declare function layoutRadar(ctx: LayoutCtx): ChartGeometry;
+/** @internal Lay out the gauge family. Called by buildChart. */
+export declare function layoutGauge(ctx: LayoutCtx): ChartGeometry;
+/** @internal Lay out the pie family. Called by buildChart. */
+export declare function layoutPie(ctx: LayoutCtx): ChartGeometry;
+/**
+ * An annular sector from angle `a0` to `a1` between radii `r0` and `r1`, as
+ * an SVG path. `r0 = 0` gives a wedge; a span of a full turn gives a ring.
+ * Exposed so a custom mark can match the built-in polar types exactly.
+ */
+export declare function arcPath(cx: number, cy: number, r0: number, r1: number, a0: number, a1: number): string;
+/** @internal Lay out the sunburst family. Called by buildChart. */
+export declare function layoutSunburst(ctx: LayoutCtx): ChartGeometry;
+/** @internal Lay out the radial bar family. Called by buildChart. */
+export declare function layoutRadialBar(ctx: LayoutCtx): ChartGeometry;
+/** @internal Lay out the radial column and nightingale families. Called by buildChart. */
+export declare function layoutRadialColumn(ctx: LayoutCtx): ChartGeometry;
+/** @internal Lay out the chord family. Called by buildChart. */
+export declare function layoutChord(ctx: LayoutCtx): ChartGeometry;