@peter.prib/renderengine 0.13.0 → 0.15.0

package/src/charting/pivot/PivotChart.js

@@ -15,16 +15,210 @@ export class PivotChart {
      * @param {string} [options.type] a catalog key to prefer while it fits (else ChartChooser's best)
      * @param {ChartChooser} [options.chooser]
      */
-    constructor(view, { type = null, chooser = null } = {}) {
+    constructor(view, { type = null, chooser = null, facetBy = null } = {}) {
         this.view = view;
         this.type = type;
+        this.facetBy = facetBy;
         this.chooser = chooser ?? new ChartChooser();
     }
 
     /** The charts that fit what the grid shows, best first. The grid itself is the table. */
     choices() {
-        const { rows, columns, complete } = this.view.chartData();
-        return this.chooser.choose(rows, columns, { complete }).filter(c => c.key !== 'table');
+        const chartData = this.view.chartData();
+        const { rows, columns, complete } = chartData;
+        const base = this.chooser.choose(rows, columns, { complete }).filter(c => c.key !== 'table');
+        const seen = new Set(base.map(c => c.key));
+        const extra = this._cubeChoices(chartData).filter(c => !seen.has(c.key) && this.chooser.registry.get(c.key));
+        return [...base, ...extra];
+    }
+
+    /**
+     * Additional chart types suited to a cube's hierarchy, series, and matrix structure beyond the
+     * general flat-table defaults in `ChartChooser`.
+     */
+    _cubeChoices({ rows, columns, complete, hierarchy, rowTotals = null, primaryMeasure = null }) {
+        if (!rows || rows.length === 0) return [];
+        const categories = columns.filter(c => c.kind !== 'numeric');
+        const numbers = columns.filter(c => c.kind === 'numeric');
+        if (categories.length !== 1 || numbers.length === 0) return [];
+        const category = categories[0];
+        const add = (key, reason, data, options) => ({
+            key,
+            label: this.chooser.registry.get(key)?.label ?? key,
+            reason,
+            data,
+            ...(options ? { options } : {}),
+        });
+        const out = [];
+
+        if (numbers.length === 1) {
+            const number = numbers[0];
+            const points = rows.filter(r => r[number.name] != null).map(r => ({
+                label: String(r[category.name]),
+                value: r[number.name],
+            }));
+            if (points.length < 2) return out;
+            this._addSingleSeriesChoices(out, add, category, number, points, complete, hierarchy, false);
+            return out;
+        }
+
+        // Multi-series (2+ numeric series from column-axis members or multiple measures).
+        const gaps = rows.some(r => numbers.some(n => r[n.name] == null));
+        if (gaps) return out;
+
+        const names = numbers.map(n => n.name).join(', ');
+        const seriesData = numbers.map(n => ({
+            name: n.name,
+            values: rows.map(r => ({ label: String(r[category.name]), value: r[n.name] })),
+        }));
+        const allNonNeg = rows.every(r => numbers.every(n => r[n.name] >= 0));
+        const additiveNonNeg = allNonNeg && numbers.every(n => n.measure !== 'semi-additive' && n.measure !== 'non-additive');
+
+        if (additiveNonNeg) {
+            out.push(add('stackedBar', `${names} stacked for each ${category.name}`, seriesData));
+            out.push(add('marimekko', `${names} share and total across ${category.name}, as a Marimekko mosaic`, seriesData));
+        }
+        out.push(add('lollipop', `${names} for each ${category.name}, as stems and dots`, seriesData));
+        if (allNonNeg && rows.length >= 2) {
+            out.push(add('area', `${names} across ${category.name}, filled`, seriesData));
+        }
+        if (additiveNonNeg && rows.length >= 2) {
+            out.push(add('stackedArea', `${names} stacked across ${category.name}`, seriesData));
+            out.push(add('streamGraph', `${names} flowing across ${category.name}`, seriesData));
+        }
+        if (allNonNeg && rows.length >= 2) {
+            out.push(add('pipe', `${names} tapering across ${category.name}`, seriesData.map(s => ({
+                name: s.name,
+                values: s.values.map(v => ({ label: v.label, value: v.value, metric: v.value })),
+            }))));
+        }
+        const heatData = rows.flatMap(r => numbers.map(n => ({
+            x: String(r[category.name]),
+            y: n.name,
+            value: r[n.name],
+        })));
+        out.push(add('heatmap', `${names} for each ${category.name}, as a colour grid`, heatData));
+        if (allNonNeg && rows.length >= 3 && rows.length <= 12) {
+            out.push(add('radar', `${names} across ${category.name} axes`, seriesData.map(s => ({
+                name: s.name,
+                values: s.values.map(v => ({ axis: v.label, value: v.value })),
+            }))));
+        }
+        if (rows.length >= 2) {
+            out.push(add('parallelCoordinates', `${names} across parallel axes for each ${category.name}`,
+                rows.map(r => ({
+                    label: String(r[category.name]),
+                    category: String(r[category.name]),
+                    ...Object.fromEntries(numbers.map(n => [n.name, r[n.name]])),
+                })),
+                { dimensions: numbers.map(n => n.name) }));
+            if (allNonNeg) {
+                out.push(add('populationPyramid', `${numbers[0].name} vs ${numbers[1].name} for each ${category.name}`,
+                    rows.map(r => ({ label: String(r[category.name]), left: r[numbers[0].name], right: r[numbers[1].name] })),
+                    { leftLabel: numbers[0].name, rightLabel: numbers[1].name, showValues: true }));
+                out.push(add('dumbbell', `${numbers[0].name} to ${numbers[1].name} gap for each ${category.name}`,
+                    rows.map(r => ({ label: String(r[category.name]), start: r[numbers[0].name], end: r[numbers[1].name] })),
+                    { startLabel: numbers[0].name, endLabel: numbers[1].name, showDelta: true }));
+                out.push(add('slopegraph', `${names} trajectory across ${category.name}`,
+                    rows.map(r => ({ label: String(r[category.name]), values: numbers.map(n => r[n.name]) })),
+                    { stageLabels: numbers.map(n => n.name) }));
+                const flowLinks = rows.flatMap(r => numbers
+                    .filter(n => r[n.name] > 0)
+                    .map(n => ({ source: String(r[category.name]), target: n.name, value: r[n.name] })));
+                if (flowLinks.length > 0) {
+                    out.push(add('sankey', `flow from ${category.name} to ${names}`, { links: flowLinks }));
+                    out.push(add('chord', `chords between ${category.name} and ${names}`, { links: flowLinks }));
+                }
+            }
+            if (rows.length >= 3) {
+                const distData = numbers.map(n => ({ label: n.name, values: rows.map(r => r[n.name]) }));
+                out.push(add('boxPlot', `distribution of ${category.name} values for each of ${names}`, distData));
+                out.push(add('density', `density curve of ${category.name} values for each of ${names}`, distData));
+                out.push(add('violin', `violin distribution of ${category.name} values for each of ${names}`, distData));
+                out.push(add('ridgeline', `ridgeline joy plot of ${category.name} values for each of ${names}`, distData));
+                out.push(add('beeswarm', `beeswarm raincloud plot of ${category.name} values for each of ${names}`, distData));
+            }
+            out.push(add('scatter', `${numbers[0].name} against ${numbers[1].name} for each ${category.name}`,
+                rows.map(r => ({ x: r[numbers[0].name], y: r[numbers[1].name], label: String(r[category.name]) }))));
+            if (numbers.length >= 3 || (rowTotals && rowTotals.length === rows.length)) {
+                out.push(add('bubble', `${numbers[0].name} and ${numbers[1].name} sized by ${numbers[2]?.name ?? (primaryMeasure?.name || 'Total')}`,
+                    rows.map((r, idx) => ({
+                        x: r[numbers[0].name],
+                        y: r[numbers[1].name],
+                        z: Math.max(1, numbers[2] ? r[numbers[2].name] : rowTotals[idx].value),
+                        label: String(r[category.name]),
+                    }))));
+            }
+        }
+        if (allNonNeg) {
+            out.push(add('bar3DOrbit', `${names} for each ${category.name}, in 3D`,
+                rows.flatMap(r => numbers.map(n => ({ x: String(r[category.name]), z: n.name, value: r[n.name] })))));
+            if (rows.length >= 2 && numbers.length >= 2) {
+                out.push(add('surface3D', `3D surface mesh of ${names} across ${category.name}`,
+                    rows.flatMap(r => numbers.map(n => ({ x: String(r[category.name]), z: n.name, value: r[n.name] })))));
+            }
+        }
+        if (additiveNonNeg) {
+            out.push(add('stackedBar3DOrbit', `${names} stacked for each ${category.name}, in 3D`,
+                rows.map(r => ({ x: String(r[category.name]), z: category.name, values: numbers.map(n => r[n.name]) })),
+                { seriesLabels: numbers.map(n => n.name) }));
+        }
+        if (rowTotals && rowTotals.length >= 2 && primaryMeasure) {
+            this._addSingleSeriesChoices(out, add, category, primaryMeasure, rowTotals, complete, hierarchy, true);
+        }
+        return out;
+    }
+
+    _addSingleSeriesChoices(out, add, category, number, points, complete, hierarchy, includeBase = false) {
+        const nonNeg = points.every(d => d.value >= 0);
+        if (includeBase) {
+            out.push(add('bar', `total ${number.name} for each ${category.name}`, points));
+            if (nonNeg && complete && number.measure === 'additive' && points.length <= 8) {
+                out.push(add('pie', `share of total ${number.name} across ${category.name}`, points, { exploded: 'max', hoverExplode: true }));
+                out.push(add('donut', `share of total ${number.name} across ${category.name}, as a ring`, points, { exploded: 'max', hoverExplode: true, showTotal: true }));
+                out.push(add('pie3D', `share of total ${number.name} across ${category.name}, in 3D`, points, { exploded: 'max', hoverExplode: true }));
+                out.push(add('donut3D', `share of total ${number.name} across ${category.name}, as a 3D ring`, points, { exploded: 'max', hoverExplode: true }));
+            }
+        } else if (nonNeg && complete && number.measure === 'additive' && points.length <= 8) {
+            out.push(add('pie3D', `share of total ${number.name} across ${category.name}, in 3D`, points, { exploded: 'max', hoverExplode: true }));
+            out.push(add('donut3D', `share of total ${number.name} across ${category.name}, as a 3D ring`, points, { exploded: 'max', hoverExplode: true }));
+        }
+        if (hierarchy) {
+            out.push(add('treemap', `${number.name} across the ${category.name} hierarchy`, hierarchy.tree));
+            out.push(add('sunburst', `${number.name} across the ${category.name} hierarchy, in rings`, hierarchy.tree));
+            out.push(add('circlePack', `${number.name} across the ${category.name} hierarchy, as packed circles`, hierarchy.tree));
+            out.push(add('icicle', `${number.name} across the ${category.name} hierarchy, as an icicle partition`, hierarchy.tree));
+            out.push(add('outline', `${number.name} across the ${category.name} hierarchy, as an outline`, hierarchy.tree));
+        }
+        if (number.measure === 'additive') {
+            out.push(add('waterfall', `how each ${category.name} adds to ${number.name}`, points));
+            if (nonNeg && complete) {
+                out.push(add('pareto', `cumulative share of ${number.name} across ${category.name}`, points));
+            }
+        }
+        if (!includeBase) {
+            out.push(add('lollipop', `${number.name} for each ${category.name}, as stems and dots`, points));
+            if (nonNeg && points.length >= 2) {
+                out.push(add('pipe', `${number.name} tapering across ${category.name}`,
+                    points.map(d => ({ label: d.label, value: d.value, metric: d.value }))));
+            }
+        }
+        if (nonNeg && points.length <= 12) {
+            out.push(add('funnel', `${number.name} across ${category.name} stages`, points));
+            out.push(add('radialBar', `${number.name} for each ${category.name}, around a circle`, points));
+            out.push(add('polarArea', `${number.name} for each ${category.name}, as a 3D Nightingale Rose`, points, { extrude3D: true, exploded: 'max', hoverExplode: true }));
+            if (!includeBase && points.length >= 3) {
+                out.push(add('radar', `${number.name} across ${category.name} axes`, points.map(d => ({ axis: d.label, value: d.value }))));
+            }
+            out.push(add('wordCloud', `${category.name} sized by ${number.name}`, points.map(d => ({ text: d.label, value: d.value }))));
+            out.push(add('bar3D', `${number.name} for each ${category.name}, in 3D`, points));
+        }
+        if (points.length >= 3) {
+            const sample = points.map(d => d.value);
+            out.push(add('histogram', `frequency distribution of ${number.name} across ${category.name}`, sample));
+            out.push(add('qq', `normal Q-Q plot of ${number.name} across ${category.name}`, sample));
+            out.push(add('lag', `lag-1 autocorrelation of ${number.name} across ${category.name}`, sample));
+        }
     }
 
     /** The chart to draw: the one asked for while it still fits, else the best; null when none fits. */
@@ -33,18 +227,121 @@ export class PivotChart {
         return choices.find(c => c.key === this.type) ?? choices[0] ?? null;
     }
 
-    /** The chart's menu: "Chart as" each chart that fits, the one showing ticked. */
-    menu(redraw) {
+    /** Sets the preferred chart type key (e.g. `'stackedBar'`, `'line'`, `'bar'`, `'pareto'`) and redraws if attached. */
+    setType(type) {
+        this.type = type;
+        this.redraw?.();
+        return this.chosen();
+    }
+
+    /** Sets or clears the facet dimension for small-multiples grids. */
+    setFacetBy(dimension) {
+        this.facetBy = dimension;
+        this.redraw?.();
+        return this.facetBy;
+    }
+
+    /** Dimensions available to facet small-multiples charts by. */
+    facetChoices() {
+        const pool = [...(this.view.pageAxis?.map(p => p.dimension) ?? []), ...this.view.rowAxis, ...this.view.columnAxis];
+        return Array.from(new Set(pool));
+    }
+
+    /**
+     * Splits chart data into small-multiple facets by `facetDimension`, calculating unified global scale bounds.
+     * @param {string} [facetDimension]
+     * @returns {{ facetDimension: string, facets: Array<object>, globalMax: number, globalMin: number }|null}
+     */
+    facetData(facetDimension = this.facetBy) {
+        if (!facetDimension) return null;
+        const chartData = this.view.chartData();
+        const { rows, columns, complete } = chartData;
+        if (!rows || rows.length === 0) return null;
+
+        // Group rows by facetDimension
+        const groups = new Map();
+        rows.forEach(r => {
+            const key = r[facetDimension] ?? 'All';
+            if (!groups.has(key)) groups.set(key, []);
+            groups.get(key).push(r);
+        });
+
+        if (groups.size <= 1) return null;
+
+        const numCols = columns.filter(c => c.kind === 'numeric').map(c => c.name);
+        let globalMax = -Infinity;
+        let globalMin = Infinity;
+        rows.forEach(r => {
+            numCols.forEach(col => {
+                const val = r[col];
+                if (typeof val === 'number' && Number.isFinite(val)) {
+                    if (val > globalMax) globalMax = val;
+                    if (val < globalMin) globalMin = val;
+                }
+            });
+        });
+
+        const chosenChart = this.chosen();
+        const baseKey = chosenChart?.key ?? 'bar';
+
+        const facets = [];
+        groups.forEach((groupRows, facetValue) => {
+            const subChart = this.chooser.choose(groupRows, columns, { complete }).find(c => c.key === baseKey)
+                ?? this.chooser.choose(groupRows, columns, { complete })[0];
+            facets.push({
+                key: facetValue,
+                label: String(facetValue),
+                chartKey: subChart?.key ?? baseKey,
+                data: subChart?.data ?? groupRows,
+                options: { ...(subChart?.options || {}), maxValue: globalMax, minValue: globalMin },
+            });
+        });
+
+        return {
+            facetDimension,
+            facets,
+            globalMax: Number.isFinite(globalMax) ? globalMax : 1,
+            globalMin: Number.isFinite(globalMin) ? globalMin : 0,
+        };
+    }
+
+    /** The chart's menu: "Chart as" each chart that fits (plus quick top-level items), the one showing ticked. */
+    menu(redraw = () => this.redraw?.()) {
         const current = this.chosen()?.key;
-        return [{
-            label: 'Chart as',
-            items: this.choices().map(c => ({
-                label: `${c.label}${c.key === current ? ' ✓' : ''}`,
-                action: () => { this.type = c.key; redraw(); },
+        const all = this.choices();
+        const toItem = (c) => ({
+            label: `${c.label}${c.key === current ? ' ✓' : ''}`,
+            action: () => { this.type = c.key; redraw(); },
+        });
+        const quickKeys = new Set([
+            'groupedBar', 'stackedBar', 'bar', 'line', 'area', 'stackedArea',
+            'pareto', 'waterfall', 'marimekko', 'lollipop', 'heatmap', 'radar',
+            'treemap', 'sunburst', 'icicle', 'sankey', 'pie', 'donut', 'pie3D', 'donut3D', 'polarArea', 'surface3D',
+        ]);
+        const quickItems = all.filter(c => quickKeys.has(c.key)).map(toItem);
+
+        const facetDims = this.facetChoices();
+        const facetItems = [
+            { label: `(None)${!this.facetBy ? ' ✓' : ''}`, action: () => { this.setFacetBy(null); redraw(); } },
+            ...facetDims.map(d => ({
+                label: `${d}${this.facetBy === d ? ' ✓' : ''}`,
+                action: () => { this.setFacetBy(d); redraw(); },
             })),
-        }];
+        ];
+
+        return [
+            {
+                label: 'Chart as',
+                items: all.map(toItem),
+            },
+            ...(facetDims.length > 0 ? [{
+                label: 'Facet by (Small Multiples)',
+                items: facetItems,
+            }] : []),
+            ...(quickItems.length > 0 ? [{ separator: true }, ...quickItems] : []),
+        ];
     }
 
-    /** A click on a charted value: drill the grid at its member. */
-    click(datum) { return this.view.drillFrom(datum.label); }
+    /** A click on a charted value: drill the grid at its member (or its series' column member). */
+    click(datum) { return this.view.drillFrom(datum.label, datum.series ?? null); }
 }