@peter.prib/renderengine 0.13.0 → 0.15.0

package/src/charting/pivot/PivotView.js

@@ -1,4 +1,5 @@
 import { TableChart } from '../charts/TableChart.js';
+import { compileFormula } from '../../kernelExpr.js';
 
 /**
  * PivotView — the state of a pivot grid (a cube's grid: dimensions on a row axis and a column axis,
@@ -28,6 +29,16 @@ import { TableChart } from '../charts/TableChart.js';
 export class PivotView {
     static ROLLUP_COLUMN = '_rollup';
 
+    static AGGREGATIONS = [
+        { key: 'sum', label: 'Sum' },
+        { key: 'count', label: 'Count' },
+        { key: 'avg', label: 'Average' },
+        { key: 'median', label: 'Median' },
+        { key: 'min', label: 'Minimum' },
+        { key: 'max', label: 'Maximum' },
+        { key: 'stddev', label: 'Std Dev' },
+    ];
+
     /**
      * @param {Array<object>} rows result rows: dimension values, measure values, and `_rollup`
      * @param {object} [options]
@@ -55,6 +66,7 @@ export class PivotView {
      * @param {function} [options.copy] writes text to the clipboard (navigator.clipboard by default)
      * @param {function|Intl.NumberFormat|object} [options.format] how numbers show, for every measure or per
      *   measure (`TableChart.formatFor`): cells, totals and the traffic lights' cut-offs. A copy keeps the raw numbers.
+     * @param {string[]} [options.visibleMeasures] subset of `measures` currently shown in the grid and chart
      */
     constructor(rows, options = {}) {
         this.onChange = options.onChange ?? null;
@@ -70,6 +82,18 @@ export class PivotView {
         this.lightRules = options.trafficLights ?? null;
         /** Traffic lights showing: null (off), 'rules' (the host's), 'thirds-high' or 'thirds-low' (by thirds, higher or lower is better). */
         this.lights = this.lightRules ? 'rules' : null;
+        /** Optional sort on the row axis: `{ columnKey, measure, direction: 'asc'|'desc' }`, or null. */
+        this.rowSort = null;
+        /** Optional Top-N / Bottom-N filter on row siblings: `{ count, columnKey, measure, direction: 'desc'|'asc' }`, or null. */
+        this.topN = null;
+        /** Post-rollup derived formula measures: `Map<name, { name, formula, params, fn }>`. */
+        this.derivedMeasures = new Map();
+        /** Summary / aggregation mode: `'sum'`, `'count'`, `'avg'`, `'median'`, `'min'`, `'max'`, or `'stddev'`. */
+        this.aggregation = PivotView.AGGREGATIONS.some(a => a.key === options.aggregation) ? options.aggregation : 'sum';
+        /** Optional raw fact rows behind the cube, enabling exact cell-level Count, Average, Median, Min, Max, and Std Dev. */
+        this.facts = Array.isArray(options.facts) ? options.facts : null;
+        /** How cell values are shown: `'value'`, `'rowPercent'`, `'columnPercent'`, or `'totalPercent'`. */
+        this.valueMode = ['rowPercent', 'columnPercent', 'totalPercent'].includes(options.valueMode) ? options.valueMode : 'value';
         this._load(rows, options);
     }
 
@@ -86,6 +110,10 @@ export class PivotView {
     _load(rows, options) {
         this._options = options;
         this.rows = rows;
+        if (Array.isArray(options.facts)) this.facts = options.facts;
+        if (options.aggregation && PivotView.AGGREGATIONS.some(a => a.key === options.aggregation)) {
+            this.aggregation = options.aggregation;
+        }
         this.rowAxis = [...(options.rowAxis ?? [])];
         this.columnAxis = [...(options.columnAxis ?? [])];
         this.pageAxis = (options.pageAxis ?? []).map(p => ({ dimension: p.dimension, value: p.value ?? null }));
@@ -94,9 +122,42 @@ export class PivotView {
         const rollup = (options.columns ?? []).find(c => c.kind === 'rollup');
         this.rollupColumn = rollup?.name ?? PivotView.ROLLUP_COLUMN;
         this.dimensions = options.dimensions ?? rollup?.dimensions ?? [...this.rowAxis, ...this.columnAxis];
-        this.measures = options.measures ?? this._defaultMeasures(rows, options.columns);
+        if (Array.isArray(options.derivedMeasures)) {
+            this.derivedMeasures.clear();
+            for (const spec of options.derivedMeasures) {
+                if (spec?.name && spec.formula) this.derivedMeasures.set(spec.name, PivotView._compileDerived(spec));
+            }
+        }
+        const baseMeasures = options.measures ?? this._defaultMeasures(rows, options.columns);
+        const derivedNames = [...this.derivedMeasures.keys()].filter(m => !baseMeasures.includes(m));
+        this.allMeasures = [...baseMeasures, ...derivedNames];
+        const keptMeasures = (options.visibleMeasures ?? this.measures ?? this.allMeasures).filter(m => this.allMeasures.includes(m));
+        this.measures = keptMeasures.length > 0 ? keptMeasures : [...this.allMeasures];
         this.collapsed = { rows: new Set(this.collapsed?.rows ?? []), columns: new Set(this.collapsed?.columns ?? []) };
         this._index();
+        if (options.topN && options.topN.count > 0) {
+            this.topN = {
+                count: options.topN.count,
+                columnKey: options.topN.columnKey ?? this.columnRoot.key,
+                measure: options.topN.measure ?? this.measures[0],
+                direction: options.topN.direction === 'asc' ? 'asc' : 'desc',
+            };
+        }
+    }
+
+    static _compileDerived({ name, formula, params = null }) {
+        if (typeof formula === 'function') {
+            return { name, formula, params, fn: (row) => formula(row) };
+        }
+        const builtins = new Set(['abs', 'min', 'max', 'sqrt', 'log', 'exp', 'floor', 'ceil', 'round', 'clamp']);
+        const paramList = Array.isArray(params) && params.length > 0
+            ? params
+            : [...new Set((String(formula).match(/[A-Za-z_][A-Za-z0-9_]*/g) ?? []).filter(id => !builtins.has(id)))];
+        const compiled = compileFormula(String(formula), paramList);
+        const fn = (row) => (paramList.some(p => typeof row[p] !== 'number')
+            ? null
+            : compiled(...paramList.map(p => row[p])));
+        return { name, formula, params: paramList, fn };
     }
 
     _defaultMeasures(rows, columns) {
@@ -128,6 +189,7 @@ export class PivotView {
 
     _index() {
         this.cells = new Map();
+        this._sampleCache = new Map();
         this.unplaced = 0;
         this.rowRoot = PivotView._node([], null);
         this.columnRoot = PivotView._node([], null);
@@ -176,12 +238,35 @@ export class PivotView {
 
     /**
      * The rows drawn, top to bottom: each member with its own totals, then (unless collapsed) the
-     * members below it, indented; the grand total last. `{ node, depth }`.
+     * members below it, indented; the grand total last. `{ node, depth }`. When `rowSort` is set,
+     * siblings at each level are ordered by that column/measure (nulls last).
      */
     visibleRows() {
         const out = [];
+        const sortList = (list, spec) => {
+            const { columnKey, measure, direction } = spec;
+            const sign = direction === 'desc' ? -1 : 1;
+            const colNode = this._findColumnNode(columnKey) ?? this.columnRoot;
+            const col = { node: colNode, measure: this.measures.includes(measure) ? measure : this.measures[0] };
+            return [...list].sort((a, b) => {
+                const va = this.value(a, col), vb = this.value(b, col);
+                if (va == null) return vb == null ? 0 : 1;
+                if (vb == null) return -1;
+                return sign * (va - vb);
+            });
+        };
+        const order = (children) => {
+            let list = [...children.values()];
+            if (this.topN && this.topN.count > 0) {
+                list = sortList(list, this.topN).slice(0, this.topN.count);
+            }
+            if (this.rowSort) {
+                list = sortList(list, this.rowSort);
+            }
+            return list;
+        };
         const walk = (node) => {
-            for (const child of node.children.values()) {
+            for (const child of order(node.children)) {
                 out.push({ node: child, depth: child.path.length - 1 });
                 if (!this.isCollapsed('rows', child)) walk(child);
             }
@@ -191,6 +276,19 @@ export class PivotView {
         return out;
     }
 
+    _findColumnNode(key) {
+        if (!key || key === this.columnRoot.key) return this.columnRoot;
+        const walk = (node) => {
+            for (const child of node.children.values()) {
+                if (child.key === key) return child;
+                const found = walk(child);
+                if (found) return found;
+            }
+            return null;
+        };
+        return walk(this.columnRoot);
+    }
+
     /**
      * The value columns drawn, left to right: each column-axis member's members (unless it is
      * collapsed, or has none), then its own total; the grand total last. One per measure for each.
@@ -258,10 +356,140 @@ export class PivotView {
         return out.map(({ id, ...cell }) => cell);
     }
 
-    /** The value at a row and column, from the row the data gave for that pair; null when it gave none. */
+    /** Evaluates `measure` on a single data or fact row (handling derived formulas). */
+    _rowMeasureValue(row, measure) {
+        if (!row) return null;
+        if (this.derivedMeasures.has(measure)) {
+            let scope = row;
+            if (this.derivedMeasures.size > 1) {
+                scope = { ...row };
+                for (const [name, d] of this.derivedMeasures) {
+                    const val = d.fn(scope);
+                    scope[name] = Number.isFinite(val) ? Math.round(val * 1000) / 1000 : null;
+                    if (name === measure) return scope[name];
+                }
+            }
+            const d = this.derivedMeasures.get(measure);
+            const v = d.fn(scope);
+            return Number.isFinite(v) ? Math.round(v * 1000) / 1000 : null;
+        }
+        return row[measure] ?? null;
+    }
+
+    /**
+     * Collects the sample of numeric values behind `(rowNode, colNode, measure)` for statistical
+     * aggregations (`count`, `avg`, `median`, `min`, `max`, `stddev`):
+     * 1) From `this.facts` when raw fact rows are supplied,
+     * 2) Else from `row._values?.[measure]` when pre-attached,
+     * 3) Else from the descendant leaf cells in `this.cells`.
+     */
+    _cellSample(rowNode, colNode, measure) {
+        const cacheKey = `${rowNode.key}|${colNode.key}|${measure}`;
+        if (this._sampleCache?.has(cacheKey)) return this._sampleCache.get(cacheKey);
+        let values = [];
+        const row = this.cell(rowNode, colNode);
+        if (Array.isArray(this.facts) && this.facts.length > 0) {
+            const matching = this.facts.filter(f => rowNode.path.every((v, i) => f[this.rowAxis[i]] === v)
+                && colNode.path.every((v, j) => f[this.columnAxis[j]] === v)
+                && this.pageAxis.every(p => p.value === null || String(f[p.dimension]) === String(p.value))
+                && this.memberFilters.every(m => (m.keep ? m.keep.includes(f[m.dimension]) : !m.remove?.includes(f[m.dimension]))));
+            values = matching.map(f => this._rowMeasureValue(f, measure)).filter(v => typeof v === 'number' && Number.isFinite(v));
+        } else if (Array.isArray(row?._values?.[measure])) {
+            values = row._values[measure].filter(v => typeof v === 'number' && Number.isFinite(v));
+        } else {
+            const leaves = (node) => {
+                if (node.children.size === 0) return [node];
+                const out = [];
+                for (const c of node.children.values()) out.push(...leaves(c));
+                return out;
+            };
+            const rLeaves = leaves(rowNode);
+            const cLeaves = leaves(colNode);
+            for (const r of rLeaves) {
+                for (const c of cLeaves) {
+                    const leafRow = this.cell(r, c);
+                    const v = this._rowMeasureValue(leafRow, measure);
+                    if (typeof v === 'number' && Number.isFinite(v)) values.push(v);
+                }
+            }
+        }
+        this._sampleCache?.set(cacheKey, values);
+        return values;
+    }
+
+    /** Computes `mode` (`'sum'|'count'|'avg'|'median'|'min'|'max'|'stddev'`) over `values`. */
+    static aggregateValues(values, mode = 'sum', sumValue = null, countOverride = null) {
+        if (mode === 'count') {
+            if (typeof countOverride === 'number') return countOverride;
+            return Array.isArray(values) ? values.length : 0;
+        }
+        if (!Array.isArray(values) || values.length === 0) {
+            return mode === 'sum' ? sumValue : null;
+        }
+        const round3 = (n) => (Number.isFinite(n) ? Math.round(n * 1000) / 1000 : null);
+        switch (mode) {
+            case 'sum':
+                return sumValue !== null ? sumValue : round3(values.reduce((a, b) => a + b, 0));
+            case 'avg': {
+                if (typeof countOverride === 'number' && countOverride > 0 && typeof sumValue === 'number') {
+                    return round3(sumValue / countOverride);
+                }
+                return round3(values.reduce((a, b) => a + b, 0) / values.length);
+            }
+            case 'median': {
+                const sorted = [...values].sort((a, b) => a - b);
+                const mid = Math.floor(sorted.length / 2);
+                const med = sorted.length % 2 === 1 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+                return round3(med);
+            }
+            case 'min':
+                return round3(Math.min(...values));
+            case 'max':
+                return round3(Math.max(...values));
+            case 'stddev': {
+                const mean = values.reduce((a, b) => a + b, 0) / values.length;
+                const variance = values.reduce((acc, v) => acc + (v - mean) ** 2, 0) / values.length;
+                return round3(Math.sqrt(variance));
+            }
+            default:
+                return sumValue;
+        }
+    }
+
+    /** The value at a row and column, from the row the data gave for that pair (or a post-rollup derived formula, or the active `aggregation`); null when it gave none. */
     value(rowNode, column) {
         const row = this.cell(rowNode, column.node);
-        return row === null ? null : row[column.measure] ?? null;
+        if (row === null) return null;
+        const raw = this._rowMeasureValue(row, column.measure);
+        if (!this.aggregation || this.aggregation === 'sum') return raw;
+        const sample = this._cellSample(rowNode, column.node, column.measure);
+        return PivotView.aggregateValues(sample, this.aggregation, raw, row._count);
+    }
+
+    /**
+     * The value at a row and column in the active `valueMode`: the raw value (`'value'`), or its share
+     * (`0..100`) of the row total (`'rowPercent'`), column total (`'columnPercent'`), or grand total
+     * (`'totalPercent'`). Returns null when the cell or its reference total is missing or zero.
+     */
+    displayValue(rowNode, column) {
+        const v = this.value(rowNode, column);
+        if (this.valueMode === 'value' || typeof v !== 'number') return v;
+        const base = this.valueMode === 'rowPercent'
+            ? this.value(rowNode, { node: this.columnRoot, measure: column.measure })
+            : this.valueMode === 'columnPercent'
+                ? this.value(this.rowRoot, column)
+                : this.value(this.rowRoot, { node: this.columnRoot, measure: column.measure });
+        if (typeof base !== 'number' || base === 0) return null;
+        return Math.round((v / base) * 1000) / 10;
+    }
+
+    /** How a cell at `(rowNode, column)` is formatted for display in the grid. */
+    cellText(rowNode, column, nullText = '—') {
+        const row = this.cell(rowNode, column.node);
+        if (row === null) return '';
+        if (this.valueMode === 'value') return this.valueText(column.measure, this.value(rowNode, column), nullText);
+        const pct = this.displayValue(rowNode, column);
+        return pct == null ? nullText : `${pct.toFixed(1)}%`;
     }
 
     // ── Changes ───────────────────────────────────────────────────────────────
@@ -283,14 +511,135 @@ export class PivotView {
         this._changed();
     }
 
+    /**
+     * Expands an axis to `level` (1 = outermost dimension only, 2 = first two dimensions, etc.) by
+     * expanding collapsible members above `level` and collapsing those at or below `level`.
+     */
+    expandToLevel(axis, level) {
+        const root = axis === 'rows' ? this.rowRoot : this.columnRoot;
+        this.collapsed[axis].clear();
+        const walk = (node) => {
+            for (const c of node.children.values()) {
+                if (c.path.length >= level && this.collapsible(c)) this.collapsed[axis].add(c.key);
+                walk(c);
+            }
+        };
+        walk(root);
+        this._changed();
+    }
+
+    /** Sets how cell values are shown: `'value'`, `'rowPercent'`, `'columnPercent'`, or `'totalPercent'`. */
+    setValueMode(mode) {
+        this.valueMode = ['rowPercent', 'columnPercent', 'totalPercent'].includes(mode) ? mode : 'value';
+        this._changed();
+    }
+
+    /**
+     * Sets the summary / aggregation function for cube cells:
+     * `'sum'`, `'count'`, `'avg'`, `'median'`, `'min'`, `'max'`, or `'stddev'`.
+     */
+    setAggregation(mode) {
+        this.aggregation = PivotView.AGGREGATIONS.some(a => a.key === mode) ? mode : 'sum';
+        this._changed();
+    }
+
     /** Rows become columns and columns rows. */
     swapAxes() {
         [this.rowAxis, this.columnAxis] = [this.columnAxis, this.rowAxis];
         this.collapsed = { rows: this.collapsed.columns, columns: this.collapsed.rows };
+        this.rowSort = null;
+        this.topN = null;
         this._index();
         this._changed();
     }
 
+    /**
+     * Sorts row members within each level by `column` (`{ node?, columnKey?, measure }`) in `direction`
+     * ('asc', 'desc', or null to clear).
+     */
+    sortRowsBy(column, direction = 'desc') {
+        if (!direction || !column) {
+            this.rowSort = null;
+        } else {
+            const columnKey = column.columnKey ?? column.node?.key ?? this.columnRoot.key;
+            const measure = column.measure ?? this.measures[0];
+            this.rowSort = { columnKey, measure, direction };
+        }
+        this._changed();
+    }
+
+    /** Clears any row sort, returning row members to their data order. */
+    clearRowSort() {
+        this.rowSort = null;
+        this._changed();
+    }
+
+    /**
+     * Filters sibling row members at each level to the top (`direction = 'desc'`) or bottom
+     * (`direction = 'asc'`) `count` members by `measure` / `column`. Pass `count <= 0` or `null` to clear.
+     */
+    setTopN(count, { column = null, columnKey = null, measure = null, direction = 'desc' } = {}) {
+        if (!count || count <= 0) {
+            this.topN = null;
+        } else {
+            this.topN = {
+                count: Math.floor(count),
+                columnKey: columnKey ?? column?.columnKey ?? column?.node?.key ?? this.columnRoot.key,
+                measure: measure ?? column?.measure ?? this.measures[0],
+                direction: direction === 'asc' ? 'asc' : 'desc',
+            };
+        }
+        this._changed();
+    }
+
+    /** Clears any Top-N / Bottom-N row filter, showing all row members again. */
+    clearTopN() {
+        this.topN = null;
+        this._changed();
+    }
+
+    /**
+     * Adds or updates a post-rollup derived formula measure (`{ name, formula, params? }`), evaluated at
+     * every detail, subtotal, and grand-total cell via `compileFormula`.
+     */
+    addDerivedMeasure({ name, formula, params = {} }) {
+        if (!name || !formula) return;
+        this.derivedMeasures.set(name, PivotView._compileDerived({ name, formula, params }));
+        if (!this.allMeasures.includes(name)) this.allMeasures.push(name);
+        if (!this.measures.includes(name)) this.measures.push(name);
+        this._changed();
+    }
+
+    /** Removes a derived formula measure by name. */
+    removeDerivedMeasure(name) {
+        if (!this.derivedMeasures.has(name)) return;
+        this.derivedMeasures.delete(name);
+        this.allMeasures = this.allMeasures.filter(m => m !== name);
+        const next = this.measures.filter(m => m !== name);
+        this.measures = next.length > 0 ? next : [...this.allMeasures];
+        this._changed();
+    }
+
+    /** Shows or hides a measure (`allMeasures` holds every available measure; at least one stays visible). */
+    toggleMeasure(measure) {
+        if (!this.allMeasures.includes(measure)) return;
+        if (this.measures.includes(measure)) {
+            if (this.measures.length <= 1) return;
+            this.measures = this.measures.filter(m => m !== measure);
+        } else {
+            this.measures = this.allMeasures.filter(m => this.measures.includes(m) || m === measure);
+        }
+        this._changed();
+    }
+
+    /** Sets the visible measures (kept in `allMeasures` order; ignored if none match). */
+    setMeasures(measures) {
+        const next = this.allMeasures.filter(m => measures.includes(m));
+        if (next.length === 0) return;
+        this.measures = next;
+        this._changed();
+    }
+
     _changed() {
         this.onChange?.(this);
         for (const listener of this._listeners) listener(this);
@@ -397,6 +746,88 @@ export class PivotView {
         return layout;
     }
 
+    /**
+     * The layout keeping only the specified `values` for `dimension` (multi-selection slice & dice).
+     * @param {string} dimension
+     * @param {Array<any>|any} values
+     * @returns {object} layout
+     */
+    withMemberKeep(dimension, values) {
+        const keep = Array.isArray(values) ? values : [values];
+        const layout = this.layout();
+        layout.members = [...layout.members.filter(m => m.dimension !== dimension), { dimension, keep }];
+        return layout;
+    }
+
+    /**
+     * The layout excluding the specified `values` for `dimension`.
+     * @param {string} dimension
+     * @param {Array<any>|any} values
+     * @returns {object} layout
+     */
+    withMemberRemove(dimension, values) {
+        const removeList = Array.isArray(values) ? values : [values];
+        const layout = this.layout();
+        const current = layout.members.find(m => m.dimension === dimension);
+        const others = layout.members.filter(m => m.dimension !== dimension);
+        const combined = Array.from(new Set([...(current?.remove ?? []), ...removeList]));
+        layout.members = [...others, { dimension, remove: combined }];
+        return layout;
+    }
+
+    /**
+     * Returns unique member values for a given dimension across facts or rows.
+     * @param {string} dimension
+     * @returns {Array<any>}
+     */
+    uniqueMembersOf(dimension) {
+        const pool = this.facts ?? this.rows;
+        const set = new Set();
+        pool.forEach(r => {
+            const val = r[dimension];
+            if (val != null) set.add(val);
+        });
+        return Array.from(set);
+    }
+
+    /**
+     * Opens a multi-member slice & dice filter dialog for `dimension`.
+     * @param {string} dimension
+     */
+    showMemberFilterDialog(dimension) {
+        if (!this.onLayout || !dimension) return;
+        const all = this.uniqueMembersOf(dimension);
+        if (!all.length) return;
+        const currentFilter = this.memberFilterOf(dimension);
+        const selected = currentFilter
+            ? (currentFilter.keep ?? all.filter(m => !currentFilter.remove?.includes(m)))
+            : all;
+
+        if (typeof document !== 'undefined') {
+            import('../FormDialog.js').then(({ FormDialog }) => {
+                new FormDialog({
+                    title: `Filter ${dimension}`,
+                    fields: [
+                        {
+                            key: 'members',
+                            label: 'Members to include',
+                            type: 'checklist',
+                            choices: all.map(m => [m, TableChart.cellText(m)]),
+                            value: selected,
+                        },
+                    ],
+                    onApply: ({ members }) => {
+                        if (!members || members.length === all.length) {
+                            this.onLayout(this.allMembers(dimension));
+                        } else {
+                            this.onLayout(this.withMemberKeep(dimension, members));
+                        }
+                    },
+                }).open();
+            }).catch(() => {});
+        }
+    }
+
     /** A member's keep-or-remove items, the host's through onLayout; none for a NULL member (no filter holds one). */
     _memberFilterItems(dimension, node) {
         if (!this.onLayout || !dimension) return [];
@@ -473,22 +904,83 @@ export class PivotView {
         const names = columns.map(seriesName);
         const rows = rowNodes.map((node, r) => Object.fromEntries([
             [category, rowLabels[r]],
-            ...columns.map((c, i) => [names[i], this.value(node, c)]),
+            ...columns.map((c, i) => [names[i], this.displayValue(node, c)]),
         ]));
         const hint = (name) => (this._options.columns ?? []).find(c => c.name === name) ?? {};
         const depths = new Set(rowNodes.map(n => n.path.length));
         const innermost = depths.size === 1 ? this.rowAxis[[...depths][0] - 1] : null;
         const measureOf = (c) => hint(c.measure).measure ?? null;
+        const primaryMeasure = this.measures[0] ?? null;
+        const totalCol = this.columnRoot.hasCells && primaryMeasure ? { node: this.columnRoot, measure: primaryMeasure } : null;
+        const rowTotals = totalCol
+            ? rowNodes.map((node, r) => ({ label: rowLabels[r], value: this.displayValue(node, totalCol) })).filter(d => d.value != null)
+            : null;
         return {
             rows,
             columns: [
                 { name: category, kind: hint(innermost).kind === 'time' ? 'time' : 'categorical' },
                 ...columns.map((c, i) => ({ name: names[i], kind: 'numeric', measure: measureOf(c) })),
             ],
-            // Members not broken down further cover the whole answer between them, unless rows went unplaced.
-            complete: this.unplaced === 0,
+            // Members not broken down further cover the whole answer between them, unless rows went unplaced or Top-N filtered.
+            complete: this.unplaced === 0 && !this.topN,
             members: new Map(rowNodes.map((node, r) => [rowLabels[r], node])),
+            columnMembers: new Map(columns.map((c, i) => [names[i], c.node])),
+            rowTotals,
+            primaryMeasure: primaryMeasure ? { name: primaryMeasure, measure: measureOf({ measure: primaryMeasure }) } : null,
+            hierarchy: this.hierarchyData(),
+        };
+    }
+
+    /**
+     * The row-axis member tree shaped for hierarchical charts (`treemap`, `sunburst`, `outline`, `icicle`):
+     * `Array<{ label, value?, children? }>`, using the single column/measure showing (or the row totals
+     * column when multiple column members are showing) when the measure is additive and all values are
+     * non-negative, or null when hierarchical part-of-whole does not fit.
+     */
+    hierarchyData() {
+        if (this.unplaced > 0 || this.topN || this.rowAxis.length < 1) return null;
+        const columns = this.visibleColumns().filter(c => !c.total && (this.columnAxis.length === 0 || c.node.path.length > 0));
+        const col = columns.length === 1
+            ? columns[0]
+            : (columns.length > 1 && this.columnRoot.hasCells && this.measures.length > 0
+                ? { node: this.columnRoot, measure: this.measures[0] }
+                : null);
+        if (!col) return null;
+        const hint = (this._options.columns ?? []).find(c => c.name === col.measure) ?? {};
+        if (hint.measure !== 'additive') return null;
+        const allNodes = [];
+        const collect = (node) => {
+            for (const child of node.children.values()) {
+                allNodes.push(child);
+                if (!this.isCollapsed('rows', child)) collect(child);
+            }
+        };
+        collect(this.rowRoot);
+        if (allNodes.length === 0) return null;
+        const labelMap = new Map(allNodes.map((n, i) => [n, PivotView._labels(allNodes)[i]]));
+        let hasDeep = false;
+        let negative = false;
+        const build = (parent) => {
+            const list = [];
+            for (const child of parent.children.values()) {
+                const label = labelMap.get(child) ?? PivotView.label(child);
+                if (child.children.size > 0 && !this.isCollapsed('rows', child)) {
+                    const children = build(child);
+                    if (children.length > 0) {
+                        hasDeep = true;
+                        list.push({ label, children });
+                    }
+                } else {
+                    const v = this.value(child, col);
+                    if (typeof v === 'number' && v < 0) negative = true;
+                    if (typeof v === 'number' && v > 0) list.push({ label, value: v });
+                }
+            }
+            return list;
         };
+        const tree = build(this.rowRoot);
+        if (negative || tree.length === 0 || (!hasDeep && this.rowAxis.length < 2)) return null;
+        return { tree, members: new Map(allNodes.map(n => [labelMap.get(n) ?? PivotView.label(n), n])), measure: col.measure };
     }
 
     /** Each member's label; its path (` › `) only where two members' labels would read the same. */
@@ -501,19 +993,33 @@ export class PivotView {
     }
 
     /**
-     * A click on a charted member (ChartBlox): a collapsed member expands; a member at the row axis's
-     * finest level drills down (the host's, through onDrill). Says which it did, or null.
+     * A click on a charted member (ChartBlox): a collapsed member expands; a member at the axis's
+     * finest level drills down (the host's, through onDrill). `axis` defaults to `'rows'`, or if a
+     * row label does not match and `series` is given, tries `'columns'`. Says which it did, or null.
      */
-    drillFrom(label) {
-        const node = this.chartData().members.get(label);
-        if (!node || node.path.length === 0) return null;
-        if (this.isCollapsed('rows', node)) {
-            this.toggle('rows', node);
-            return 'expanded';
+    drillFrom(label, series = null) {
+        const data = this.chartData();
+        const rowNode = data.members.get(label) ?? data.hierarchy?.members.get(label);
+        if (rowNode && rowNode.path.length > 0) {
+            if (this.isCollapsed('rows', rowNode)) {
+                this.toggle('rows', rowNode);
+                return 'expanded';
+            }
+            if (rowNode.path.length === this.rowAxis.length && this.onDrill) {
+                this.onDrill({ axis: 'rows', dimension: this.rowAxis.at(-1), direction: 'down', member: rowNode.path });
+                return 'drilled';
+            }
         }
-        if (node.path.length === this.rowAxis.length && this.onDrill) {
-            this.onDrill({ axis: 'rows', dimension: this.rowAxis.at(-1), direction: 'down', member: node.path });
-            return 'drilled';
+        const colNode = series ? data.columnMembers.get(series) : data.columnMembers.get(label);
+        if (colNode && colNode.path.length > 0) {
+            if (this.isCollapsed('columns', colNode)) {
+                this.toggle('columns', colNode);
+                return 'expanded';
+            }
+            if (colNode.path.length === this.columnAxis.length && this.onDrill) {
+                this.onDrill({ axis: 'columns', dimension: this.columnAxis.at(-1), direction: 'down', member: colNode.path });
+                return 'drilled';
+            }
         }
         return null;
     }
@@ -545,12 +1051,26 @@ export class PivotView {
             }
         }
         items.push(...this._memberFilterItems(dimension, node));
+        if (axis === 'columns') items.push(...this._columnSortItems(node));
         items.push({ separator: true },
             { label: `Expand all ${axis}`, action: () => this.collapseAll(axis, false) },
             { label: `Collapse all ${axis}`, action: () => this.collapseAll(axis, true) });
         return [...items, ...this._extra('member', { axis, node, dimension })];
     }
 
+    _columnSortItems(node) {
+        if (this.rowAxis.length === 0 || !node.hasCells) return [];
+        const measure = this.measures[0];
+        const active = this.rowSort?.columnKey === node.key && this.rowSort?.measure === measure ? this.rowSort.direction : null;
+        const label = PivotView.label(node);
+        return [
+            { separator: true },
+            { label: `Sort rows by ${label} descending${active === 'desc' ? ' ✓' : ''}`, action: () => this.sortRowsBy({ node, measure }, 'desc') },
+            { label: `Sort rows by ${label} ascending${active === 'asc' ? ' ✓' : ''}`, action: () => this.sortRowsBy({ node, measure }, 'asc') },
+            ...(this.rowSort ? [{ label: 'Clear row sort', action: () => this.clearRowSort() }] : []),
+        ];
+    }
+
     // ── Traffic lights ─────────────────────────────────────────────────────────
 
     static LIGHTS = { low: '#f6d3cf', mid: '#fbe7b0', high: '#d3ebd4' };
@@ -639,7 +1159,13 @@ export class PivotView {
      * collapsed on each axis, and the traffic lights. The layout itself is `layout()`.
      */
     displayState() {
-        return { collapsed: { rows: [...this.collapsed.rows], columns: [...this.collapsed.columns] }, lights: this.lights };
+        const state = { collapsed: { rows: [...this.collapsed.rows], columns: [...this.collapsed.columns] }, lights: this.lights };
+        if (this.rowSort) state.rowSort = { ...this.rowSort };
+        if (this.topN) state.topN = { ...this.topN };
+        if (this.allMeasures.length > 1 && this.measures.length < this.allMeasures.length) state.measures = [...this.measures];
+        if (this.valueMode !== 'value') state.valueMode = this.valueMode;
+        if (this.aggregation !== 'sum') state.aggregation = this.aggregation;
+        return state;
     }
 
     /**
@@ -650,6 +1176,16 @@ export class PivotView {
         this.collapsed = { rows: new Set(state.collapsed?.rows ?? []), columns: new Set(state.collapsed?.columns ?? []) };
         const lights = state.lights ?? null;
         this.lights = ['thirds-high', 'thirds-low'].includes(lights) || (lights === 'rules' && this.lightRules) ? lights : null;
+        this.rowSort = state.rowSort && ['asc', 'desc'].includes(state.rowSort.direction) ? { ...state.rowSort } : null;
+        this.topN = state.topN && state.topN.count > 0 && ['asc', 'desc'].includes(state.topN.direction) ? { ...state.topN } : null;
+        if (Array.isArray(state.measures)) {
+            const kept = this.allMeasures.filter(m => state.measures.includes(m));
+            if (kept.length > 0) this.measures = kept;
+        } else {
+            this.measures = [...this.allMeasures];
+        }
+        this.valueMode = ['rowPercent', 'columnPercent', 'totalPercent'].includes(state.valueMode) ? state.valueMode : 'value';
+        this.aggregation = PivotView.AGGREGATIONS.some(a => a.key === state.aggregation) ? state.aggregation : 'sum';
         this._changed();
     }
 
@@ -699,12 +1235,81 @@ export class PivotView {
         return items.length === 0 ? extra.slice(1) : [...items, ...extra];
     }
 
-    /** The grid's menu: swap the axes, expand or collapse everything, traffic lights, copy the grid. */
+    /** The grid's menu: swap the axes, expand or collapse everything, traffic lights, measures, sort, copy the grid. */
     gridMenu() {
         const light = (label, mode) => ({ label: label + (this.lights === mode ? ' ✓' : ''), action: () => this.setLights(mode) });
+        const measureItems = this.allMeasures.length > 1 ? [{
+            label: 'Measures',
+            items: this.allMeasures.map(m => ({
+                label: `${m}${this.measures.includes(m) ? ' ✓' : ''}`,
+                disabled: this.measures.length === 1 && this.measures[0] === m,
+                action: () => this.toggleMeasure(m),
+            })),
+        }] : [];
+        const sortItems = this.rowAxis.length > 0 && this.rowRoot.children.size > 1 && this.columnRoot.hasCells ? [{
+            label: 'Sort rows',
+            items: [
+                ...this.measures.flatMap(m => [
+                    {
+                        label: `By ${this.measures.length > 1 ? m + ' total' : 'total'} — highest first${this.rowSort?.columnKey === this.columnRoot.key && this.rowSort?.measure === m && this.rowSort?.direction === 'desc' ? ' ✓' : ''}`,
+                        action: () => this.sortRowsBy({ node: this.columnRoot, measure: m }, 'desc'),
+                    },
+                    {
+                        label: `By ${this.measures.length > 1 ? m + ' total' : 'total'} — lowest first${this.rowSort?.columnKey === this.columnRoot.key && this.rowSort?.measure === m && this.rowSort?.direction === 'asc' ? ' ✓' : ''}`,
+                        action: () => this.sortRowsBy({ node: this.columnRoot, measure: m }, 'asc'),
+                    },
+                ]),
+                ...(this.rowSort ? [{ separator: true }, { label: 'Default order', action: () => this.clearRowSort() }] : []),
+            ],
+        }] : [];
+        const topNChoice = (count, direction, label) => {
+            const m = this.measures[0];
+            const active = this.topN?.count === count && this.topN?.direction === direction && this.topN?.measure === m;
+            return {
+                label: `${label}${active ? ' ✓' : ''}`,
+                action: () => this.setTopN(count, { node: this.columnRoot, measure: m, direction }),
+            };
+        };
+        const topNItems = this.rowAxis.length > 0 && this.rowRoot.children.size > 1 && this.columnRoot.hasCells ? [{
+            label: 'Top / Bottom N',
+            items: [
+                topNChoice(3, 'desc', 'Top 3'),
+                topNChoice(5, 'desc', 'Top 5'),
+                topNChoice(10, 'desc', 'Top 10'),
+                { separator: true },
+                topNChoice(3, 'asc', 'Bottom 3'),
+                topNChoice(5, 'asc', 'Bottom 5'),
+                ...(this.topN ? [{ separator: true }, { label: 'Show all rows', action: () => this.clearTopN() }] : []),
+            ],
+        }] : [];
+        const aggregationItems = (this.rowRoot.hasCells || this.columnRoot.hasCells) ? [{
+            label: 'Summary (Count / Avg / Median)',
+            items: PivotView.AGGREGATIONS.map(a => ({
+                label: `${a.label}${this.aggregation === a.key ? ' ✓' : ''}`,
+                action: () => this.setAggregation(a.key),
+            })),
+        }] : [];
+        const valueModeChoice = (label, mode) => ({
+            label: `${label}${this.valueMode === mode ? ' ✓' : ''}`,
+            action: () => this.setValueMode(mode),
+        });
+        const valueModeItems = (this.rowRoot.hasCells || this.columnRoot.hasCells) ? [{
+            label: 'Show values as',
+            items: [
+                valueModeChoice('Values', 'value'),
+                ...(this.columnAxis.length > 0 && this.columnRoot.hasCells ? [valueModeChoice('% of row total', 'rowPercent')] : []),
+                ...(this.rowAxis.length > 0 && this.rowRoot.hasCells ? [valueModeChoice('% of column total', 'columnPercent')] : []),
+                ...(this.rowRoot.hasCells && this.columnRoot.hasCells ? [valueModeChoice('% of grand total', 'totalPercent')] : []),
+            ],
+        }] : [];
         return [
             { label: 'Swap rows and columns', action: () => this.swapAxes() },
             { label: 'Expand all', action: () => { this.collapsed.rows.clear(); this.collapsed.columns.clear(); this._changed(); } },
+            ...sortItems,
+            ...topNItems,
+            ...measureItems,
+            ...aggregationItems,
+            ...valueModeItems,
             {
                 label: 'Traffic lights',
                 items: [