@peter.prib/renderengine 0.10.0 → 0.13.0

package/src/charting/pivot/PivotView.js

@@ -0,0 +1,740 @@
+import { TableChart } from '../charts/TableChart.js';
+
+/**
+ * PivotView — the state of a pivot grid (a cube's grid: dimensions on a row axis and a column axis,
+ * measures in the cells), kept apart from drawing so all of it can be tested without a DOM: the
+ * header trees of both axes, which members are collapsed, which axis is which, and the menus a grid
+ * offers on a member and on the grid itself (as PopupMenu item specs).
+ *
+ * The grid never computes a total. Subtotals come in the rows, as a rolled-up query returns them
+ * (sqlengine's GROUP BY ROLLUP; semanticengine's `rollup`): a `_rollup` column says, as bits over
+ * `dimensions` (first highest), which dimensions a row totals. Adding up cells here would be wrong for
+ * any measure that does not add up (an average, a balance), so without subtotal rows a member simply
+ * has no total to show, and cannot be collapsed onto one.
+ *
+ * Expanding and collapsing a member is the grid's own; drilling to a level the rows do not have is the
+ * host's: the member menu's "Drill down" / "Drill up" call `onDrill({ axis, dimension, direction,
+ * member })`, and the host answers the new question and calls `update()`. Every change calls
+ * `onChange(view)`; the host redraws.
+ *
+ * The layout is the host's too (Alphablox's PresentBlox): with `onLayout`, each dimension's menu moves
+ * it between the rows, the columns and the page filters (a dimension held to one member, or all),
+ * adds one from `available`, or removes it; the view says the new layout, `{ rowAxis, columnAxis,
+ * pageAxis, members }`, and the host asks that question and calls `update()`. A page filter's members
+ * come from `members(dimension)`, the host's. A member's menu keeps only it or removes it
+ * (`members`: `{ dimension, keep }` or `{ dimension, remove }`) — filters the host asks again, never
+ * rows hidden here, so every total stays the total of what is showing.
+ */
+export class PivotView {
+    static ROLLUP_COLUMN = '_rollup';
+
+    /**
+     * @param {Array<object>} rows result rows: dimension values, measure values, and `_rollup`
+     * @param {object} [options]
+     * @param {string[]} [options.rowAxis] dimensions down the side, outermost first
+     * @param {string[]} [options.columnAxis] dimensions across the top, outermost first
+     * @param {string[]} [options.measures] the cells' values; by default every numeric column not on an axis
+     * @param {Array<{name, kind, dimensions?}>} [options.columns] column hints (semanticengine's `columns`):
+     *   the `kind: 'rollup'` one names the rollup column and the dimensions its bits are over
+     * @param {string[]} [options.dimensions] the dimensions the rollup bits are over, first highest
+     *   (from `columns` when given there; else the row axis then the column axis)
+     * @param {function} [options.onChange] called with the view after every change
+     * @param {function} [options.onDrill] ({ axis, dimension, direction: 'down'|'up', member }) — the host drills
+     * @param {{list, open, save, remove}} [options.views] saved views, the host's (where they are stored is
+     *   its choice): list() → names; open(name), save(), remove(name) — the grid's Views menu calls them
+     * @param {function} [options.onDrillThrough] ({ cell, measure }) — the host shows the rows behind a cell;
+     *   `cell` names its members, `{ dimension: value }` (a total names fewer)
+     * @param {object} [options.menus] the host's own items: { member, grid } → items
+     * @param {Array<{dimension, value}>} [options.pageAxis] page filters: a dimension held to `value`, or to all when null
+     * @param {Array<{dimension, keep?, remove?}>} [options.memberFilters] members kept only, or removed, per dimension
+     * @param {string[]} [options.available] dimensions the layout may add (those placed are left out)
+     * @param {function} [options.onLayout] ({ rowAxis, columnAxis, pageAxis }) — the host asks the new layout's question
+     * @param {function} [options.members] (dimension) → its members, for a page filter's menu
+     * @param {Array<{measure?, below?, atLeast?, fill, label?}>} [options.trafficLights] the host's rules:
+     *   the first whose measure (any, when absent) and range match colours a detail cell
+     * @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.
+     */
+    constructor(rows, options = {}) {
+        this.onChange = options.onChange ?? null;
+        this.onDrill = options.onDrill ?? null;
+        this.onDrillThrough = options.onDrillThrough ?? null;
+        this.views = options.views ?? null;
+        this.onLayout = options.onLayout ?? null;
+        this.members = options.members ?? null;
+        this.menus = options.menus ?? {};
+        this.copy = options.copy ?? PivotView.clipboard;
+        this.format = options.format ?? null;
+        this._listeners = new Set();
+        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;
+        this._load(rows, options);
+    }
+
+    static clipboard(text) {
+        return globalThis.navigator?.clipboard?.writeText(text);
+    }
+
+    /** New rows and axes (the host's answer to a drill), keeping what is collapsed where it still applies. */
+    update(rows, options = {}) {
+        this._load(rows, { ...this._options, ...options });
+        this._changed();
+    }
+
+    _load(rows, options) {
+        this._options = options;
+        this.rows = rows;
+        this.rowAxis = [...(options.rowAxis ?? [])];
+        this.columnAxis = [...(options.columnAxis ?? [])];
+        this.pageAxis = (options.pageAxis ?? []).map(p => ({ dimension: p.dimension, value: p.value ?? null }));
+        this.available = [...(options.available ?? [])];
+        this.memberFilters = (options.memberFilters ?? []).map(m => ({ ...m }));
+        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);
+        this.collapsed = { rows: new Set(this.collapsed?.rows ?? []), columns: new Set(this.collapsed?.columns ?? []) };
+        this._index();
+    }
+
+    _defaultMeasures(rows, columns) {
+        const onAxis = new Set([...this.rowAxis, ...this.columnAxis, this.rollupColumn]);
+        if (columns) return columns.filter(c => c.kind === 'numeric' && !onAxis.has(c.name)).map(c => c.name);
+        const first = rows[0] ?? {};
+        return Object.keys(first).filter(k => !onAxis.has(k) && rows.every(r => r[k] == null || typeof r[k] === 'number'));
+    }
+
+    // ── The cube's cells and header trees ──────────────────────────────────────
+
+    /** Whether `row` totals `dimension` (its rollup bit is set). */
+    isTotal(row, dimension) {
+        const bits = row[this.rollupColumn];
+        const i = this.dimensions.indexOf(dimension);
+        if (typeof bits !== 'number' || i < 0) return false;
+        return Math.floor(bits / 2 ** (this.dimensions.length - 1 - i)) % 2 === 1;
+    }
+
+    /**
+     * How many of an axis's dimensions `row` is grouped by: the leading ones not totalled. A row that
+     * totals an outer dimension but not an inner one (as a CUBE has) has no place on the axis: null.
+     */
+    _depth(row, axis) {
+        const totalled = axis.map(d => this.isTotal(row, d));
+        const depth = totalled.indexOf(true) < 0 ? axis.length : totalled.indexOf(true);
+        return totalled.slice(depth).every(Boolean) ? depth : null;
+    }
+
+    _index() {
+        this.cells = new Map();
+        this.unplaced = 0;
+        this.rowRoot = PivotView._node([], null);
+        this.columnRoot = PivotView._node([], null);
+        for (const row of this.rows) {
+            const rd = this._depth(row, this.rowAxis);
+            const cd = this._depth(row, this.columnAxis);
+            if (rd === null || cd === null) { this.unplaced++; continue; }
+            const r = PivotView._add(this.rowRoot, this.rowAxis.slice(0, rd).map(d => row[d]));
+            const c = PivotView._add(this.columnRoot, this.columnAxis.slice(0, cd).map(d => row[d]));
+            this.cells.set(`${r.key}|${c.key}`, row);
+            r.hasCells = true;
+            c.hasCells = true;
+        }
+    }
+
+    static _node(path, parent) {
+        return { path, key: JSON.stringify(path), parent, children: new Map(), hasCells: false };
+    }
+
+    static _add(root, values) {
+        let node = root;
+        for (const value of values) {
+            const k = JSON.stringify(value);
+            if (!node.children.has(k)) node.children.set(k, PivotView._node([...node.path, value], node));
+            node = node.children.get(k);
+        }
+        return node;
+    }
+
+    /** The row holding the cells where a row-axis member and a column-axis member meet, or null. */
+    cell(rowNode, columnNode) { return this.cells.get(`${rowNode.key}|${columnNode.key}`) ?? null; }
+
+    /** A member's label: its value as the table shows one; '(empty)' for a NULL in the data. */
+    static label(node) {
+        if (node.path.length === 0) return 'Total';
+        const value = node.path.at(-1);
+        return value == null ? '(empty)' : TableChart.cellText(value);
+    }
+
+    /** Whether a member can be collapsed onto its own total: it has members below, and a total to show. */
+    collapsible(node) { return node.children.size > 0 && node.hasCells; }
+
+    isCollapsed(axis, node) { return this.collapsed[axis].has(node.key); }
+
+    // ── What is showing ───────────────────────────────────────────────────────
+
+    /**
+     * 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 }`.
+     */
+    visibleRows() {
+        const out = [];
+        const walk = (node) => {
+            for (const child of node.children.values()) {
+                out.push({ node: child, depth: child.path.length - 1 });
+                if (!this.isCollapsed('rows', child)) walk(child);
+            }
+        };
+        walk(this.rowRoot);
+        if (this.rowRoot.hasCells || this.rowAxis.length === 0) out.push({ node: this.rowRoot, depth: 0 });
+        return out;
+    }
+
+    /**
+     * 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.
+     * `{ node, measure, total }` — `total` when the column is a member's total beside its members.
+     */
+    visibleColumns() {
+        const members = [];
+        const walk = (node) => {
+            for (const child of node.children.values()) {
+                if (child.children.size > 0 && !this.isCollapsed('columns', child)) {
+                    walk(child);
+                    if (child.hasCells) members.push({ node: child, total: true });
+                } else {
+                    members.push({ node: child, total: false });
+                }
+            }
+        };
+        walk(this.columnRoot);
+        if (this.columnRoot.hasCells) members.push({ node: this.columnRoot, total: this.columnAxis.length > 0 });
+        return members.flatMap(m => this.measures.map(measure => ({ ...m, measure })));
+    }
+
+    /**
+     * The header above the value columns: a line per column-axis dimension (and one for the measures
+     * when there are several), each a list of `{ text, span, node }` — a member spans the columns
+     * beneath it; `node` is set where the text is a member, so it can take a click.
+     */
+    columnHeaders() {
+        const columns = this.visibleColumns();
+        const levels = this.columnAxis.length;
+        const lines = [];
+        for (let level = 0; level < levels; level++) {
+            const cells = columns.map((c) => {
+                const depth = c.node.path.length;   // a member at depth d is labelled on line d - 1
+                if (level < depth) {
+                    const owner = PivotView._ancestor(c.node, level + 1);
+                    return { id: owner.key, text: PivotView.label(owner), node: owner };
+                }
+                if (level === depth && c.total) return { id: `total|${c.node.key}`, text: 'Total', node: null };
+                return { id: null, text: '', node: null };
+            });
+            lines.push(PivotView._spans(cells));
+        }
+        if (this.measures.length > 1 || levels === 0) {
+            lines.push(columns.map(c => ({ text: c.measure, span: 1, node: null })));
+        }
+        return lines;
+    }
+
+    /** The member on `node`'s path at `depth` (1 = outermost). */
+    static _ancestor(node, depth) {
+        let n = node;
+        while (n.path.length > depth) n = n.parent;
+        return n;
+    }
+
+    /** Runs of the same member merged into one spanning cell. */
+    static _spans(cells) {
+        const out = [];
+        for (const cell of cells) {
+            const last = out.at(-1);
+            if (last && cell.id !== null && last.id === cell.id) last.span++;
+            else out.push({ ...cell, span: 1 });
+        }
+        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. */
+    value(rowNode, column) {
+        const row = this.cell(rowNode, column.node);
+        return row === null ? null : row[column.measure] ?? null;
+    }
+
+    // ── Changes ───────────────────────────────────────────────────────────────
+
+    toggle(axis, node) {
+        if (!this.collapsible(node)) return;
+        const set = this.collapsed[axis];
+        if (set.has(node.key)) set.delete(node.key); else set.add(node.key);
+        this._changed();
+    }
+
+    /** Collapse (or expand) every member of an axis that can be. */
+    collapseAll(axis, collapse = true) {
+        this.collapsed[axis].clear();
+        if (collapse) {
+            const walk = (node) => { for (const c of node.children.values()) { if (this.collapsible(c)) this.collapsed[axis].add(c.key); walk(c); } };
+            walk(axis === 'rows' ? this.rowRoot : this.columnRoot);
+        }
+        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._index();
+        this._changed();
+    }
+
+    _changed() {
+        this.onChange?.(this);
+        for (const listener of this._listeners) listener(this);
+    }
+
+    /** Another listener for every change, beside onChange — a linked chart. Returns what removes it. */
+    listen(listener) {
+        this._listeners.add(listener);
+        return () => this._listeners.delete(listener);
+    }
+
+    // ── Layout (PresentBlox) ───────────────────────────────────────────────────
+
+    /** The layout as showing: what the host asks a question for. */
+    layout() {
+        return {
+            rowAxis: [...this.rowAxis], columnAxis: [...this.columnAxis], pageAxis: this.pageAxis.map(p => ({ ...p })),
+            members: this.memberFilters.map(m => ({ ...m })),
+        };
+    }
+
+    /** Where a dimension is: 'rows', 'columns', 'page', 'available', or null. */
+    zoneOf(dimension) {
+        if (this.rowAxis.includes(dimension)) return 'rows';
+        if (this.columnAxis.includes(dimension)) return 'columns';
+        if (this.pageAxis.some(p => p.dimension === dimension)) return 'page';
+        return this.available.includes(dimension) ? 'available' : null;
+    }
+
+    /** The dimensions that may be added: available, and not placed. */
+    addable() { return this.available.filter(d => this.zoneOf(d) === 'available'); }
+
+    /** The layout with `dimension` moved to `zone` ('rows', 'columns', 'page', or null to remove it). */
+    moved(dimension, zone) {
+        const layout = this.layout();
+        layout.rowAxis = layout.rowAxis.filter(d => d !== dimension);
+        layout.columnAxis = layout.columnAxis.filter(d => d !== dimension);
+        layout.pageAxis = layout.pageAxis.filter(p => p.dimension !== dimension);
+        // Removed, or held to one member on the page: a keep or remove of its members no longer applies.
+        if (zone === null || zone === 'page') layout.members = layout.members.filter(m => m.dimension !== dimension);
+        if (zone === 'rows') layout.rowAxis.push(dimension);
+        if (zone === 'columns') layout.columnAxis.push(dimension);
+        if (zone === 'page') layout.pageAxis.push({ dimension, value: null });
+        return layout;
+    }
+
+    /** The layout with `dimension` one place outward (-1) or inward (+1) on its axis. */
+    shifted(dimension, by) {
+        const layout = this.layout();
+        const axis = layout.rowAxis.includes(dimension) ? layout.rowAxis : layout.columnAxis;
+        const at = axis.indexOf(dimension);
+        [axis[at], axis[at + by]] = [axis[at + by], axis[at]];
+        return layout;
+    }
+
+    /** The layout with page filter `dimension` held to `value` (null: all members). */
+    paged(dimension, value) {
+        const layout = this.layout();
+        layout.pageAxis = layout.pageAxis.map(p => (p.dimension === dimension ? { dimension, value } : p));
+        return layout;
+    }
+
+    /** The keep or remove of a dimension's members, or null. */
+    memberFilterOf(dimension) { return this.memberFilters.find(m => m.dimension === dimension) ?? null; }
+
+    /** How a chip says a dimension's keep or remove: " (only West)", " (without 2)", or nothing. */
+    memberFilterText(dimension) {
+        const m = this.memberFilterOf(dimension);
+        if (!m) return '';
+        const values = m.keep ?? m.remove;
+        const what = values.length === 1 ? TableChart.cellText(values[0]) : String(values.length);
+        return m.keep ? ` (only ${what})` : ` (without ${what})`;
+    }
+
+    /** The layout keeping only `value` of `dimension`. */
+    keptOnly(dimension, value) {
+        const layout = this.layout();
+        layout.members = [...layout.members.filter(m => m.dimension !== dimension), { dimension, keep: [value] }];
+        return layout;
+    }
+
+    /**
+     * The layout without `value` of `dimension`: added to its removed members, or taken from its kept
+     * ones. Null when that would keep nothing — then the menu does not offer it.
+     */
+    removedMember(dimension, value) {
+        const layout = this.layout();
+        const current = layout.members.find(m => m.dimension === dimension);
+        const others = layout.members.filter(m => m.dimension !== dimension);
+        if (current?.keep) {
+            const keep = current.keep.filter(v => v !== value);
+            if (keep.length === 0) return null;
+            layout.members = [...others, { dimension, keep }];
+        } else {
+            layout.members = [...others, { dimension, remove: [...(current?.remove ?? []), value] }];
+        }
+        return layout;
+    }
+
+    /** The layout showing every member of `dimension` again. */
+    allMembers(dimension) {
+        const layout = this.layout();
+        layout.members = layout.members.filter(m => m.dimension !== dimension);
+        return layout;
+    }
+
+    /** 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 [];
+        const value = node.path.at(-1);
+        const ask = (layout) => () => this.onLayout(layout);
+        const items = [];
+        if (value != null) {
+            const label = PivotView.label(node);
+            items.push({ label: `Keep only ${label}`, action: ask(this.keptOnly(dimension, value)) });
+            const removed = this.removedMember(dimension, value);
+            if (removed) items.push({ label: `Remove ${label}`, action: ask(removed) });
+        }
+        if (this.memberFilterOf(dimension)) items.push({ label: `Show all ${dimension}`, action: ask(this.allMembers(dimension)) });
+        return items.length > 0 ? [{ separator: true }, ...items] : [];
+    }
+
+    /** The most members a page filter's menu lists. */
+    static MAX_PAGE_MEMBERS = 30;
+
+    /**
+     * A dimension's layout menu: for a page filter, its members to hold it to (and All); then where
+     * to move it — rows, columns, page — outward or inward on its axis, or remove it. Each item gives
+     * the host the new layout (`onLayout`). Empty without onLayout.
+     */
+    layoutMenu(dimension) {
+        if (!this.onLayout) return [];
+        const zone = this.zoneOf(dimension);
+        const ask = (layout) => () => this.onLayout(layout);
+        const items = [];
+        if (zone === 'page') {
+            const current = this.pageAxis.find(p => p.dimension === dimension).value;
+            const members = this.members?.(dimension) ?? [];
+            const listed = members.slice(0, PivotView.MAX_PAGE_MEMBERS);
+            items.push({ label: `All${current === null ? ' ✓' : ''}`, action: ask(this.paged(dimension, null)) });
+            for (const m of listed) items.push({ label: `${TableChart.cellText(m)}${m === current ? ' ✓' : ''}`, action: ask(this.paged(dimension, m)) });
+            if (members.length > listed.length) items.push({ label: `(${members.length - listed.length} more not listed)`, disabled: true });
+            items.push({ separator: true });
+        }
+        if (zone !== 'rows') items.push({ label: 'Move to rows', action: ask(this.moved(dimension, 'rows')) });
+        if (zone !== 'columns') items.push({ label: 'Move to columns', action: ask(this.moved(dimension, 'columns')) });
+        if (zone !== 'page') items.push({ label: 'Move to filters', action: ask(this.moved(dimension, 'page')) });
+        if (zone === 'rows' || zone === 'columns') {
+            const axis = this.axisOf(zone);
+            if (axis.indexOf(dimension) > 0) items.push({ label: 'Move outward', action: ask(this.shifted(dimension, -1)) });
+            if (axis.indexOf(dimension) < axis.length - 1) items.push({ label: 'Move inward', action: ask(this.shifted(dimension, 1)) });
+        }
+        if (this.memberFilterOf(dimension)) items.push({ separator: true }, { label: `Show all ${dimension}`, action: ask(this.allMembers(dimension)) });
+        if (zone !== 'available') items.push({ separator: true }, { label: 'Remove', action: ask(this.moved(dimension, null)) });
+        return items;
+    }
+
+    // ── As a chart (ChartBlox) ─────────────────────────────────────────────────
+
+    /**
+     * What the grid shows, shaped for a chart: a row per row-axis member that is showing and not
+     * broken down further on screen (collapsed, or at the finest level showing), and a numeric
+     * column per such column-axis member (per measure, when there are several). A member and its
+     * parts never both appear, and totals are left out, so no value is drawn twice. Labels are the
+     * members' own, or their paths when two would read the same.
+     * @returns {{ rows, columns, complete, members: Map<string, object> }} rows and column hints for
+     *   ChartChooser; `members` maps a row's label back to its member, for a click on the chart
+     */
+    chartData() {
+        const showing = (axis, node) => node.children.size === 0 || this.isCollapsed(axis, node);
+        const rowNodes = this.rowAxis.length === 0
+            ? [this.rowRoot]
+            : this.visibleRows().map(r => r.node).filter(n => n.path.length > 0 && showing('rows', n));
+        const columns = this.visibleColumns().filter(c => !c.total && (this.columnAxis.length === 0 || c.node.path.length > 0));
+        const rowLabels = PivotView._labels(rowNodes);
+        const columnLabels = PivotView._labels(columns.map(c => c.node));
+        const seriesName = (c, i) => (this.columnAxis.length === 0 ? c.measure
+            : this.measures.length > 1 ? `${columnLabels[i]} · ${c.measure}` : columnLabels[i]);
+        const category = this.rowAxis.length === 0 ? 'Total' : this.rowAxis.join(' › ');
+        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)]),
+        ]));
+        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;
+        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: new Map(rowNodes.map((node, r) => [rowLabels[r], node])),
+        };
+    }
+
+    /** Each member's label; its path (` › `) only where two members' labels would read the same. */
+    static _labels(nodes) {
+        const short = nodes.map(n => PivotView.label(n));
+        const count = new Map();
+        for (const s of short) count.set(s, (count.get(s) ?? 0) + 1);
+        return nodes.map((n, i) => (count.get(short[i]) === 1 ? short[i]
+            : n.path.map((_, d) => PivotView.label({ path: n.path.slice(0, d + 1) })).join(' › ')));
+    }
+
+    /**
+     * 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.
+     */
+    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';
+        }
+        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';
+        }
+        return null;
+    }
+
+    // ── Menus ─────────────────────────────────────────────────────────────────
+
+    axisOf(axis) { return axis === 'rows' ? this.rowAxis : this.columnAxis; }
+
+    /**
+     * A member's menu: expand or collapse it; drill down from the axis's innermost level, or up to a
+     * member's level from a finer one (the host's, through `onDrill`); expand or collapse the axis.
+     */
+    memberMenu(axis, node) {
+        const dims = this.axisOf(axis);
+        const depth = node.path.length;
+        const dimension = dims[depth - 1];
+        const items = [];
+        if (this.collapsible(node)) {
+            items.push(this.isCollapsed(axis, node)
+                ? { label: `Expand ${PivotView.label(node)}`, action: () => this.toggle(axis, node) }
+                : { label: `Collapse ${PivotView.label(node)}`, action: () => this.toggle(axis, node) });
+        }
+        if (this.onDrill && depth > 0) {
+            if (depth === dims.length) {
+                items.push({ label: `Drill down from ${dimension}`, action: () => this.onDrill({ axis, dimension, direction: 'down', member: node.path }) });
+            }
+            if (depth < dims.length) {
+                items.push({ label: `Drill up to ${dimension}`, action: () => this.onDrill({ axis, dimension, direction: 'up', member: node.path }) });
+            }
+        }
+        items.push(...this._memberFilterItems(dimension, 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 })];
+    }
+
+    // ── Traffic lights ─────────────────────────────────────────────────────────
+
+    static LIGHTS = { low: '#f6d3cf', mid: '#fbe7b0', high: '#d3ebd4' };
+
+    /**
+     * Whether a cell is a detail cell — a member at the finest level of both axes — the only cells
+     * traffic lights colour: a subtotal is on another scale from the cells it sums, so one set of
+     * thresholds would colour it wrongly.
+     */
+    isDetail(rowNode, column) {
+        return rowNode.path.length === this.rowAxis.length && column.node.path.length === this.columnAxis.length;
+    }
+
+    /** Shows traffic lights: null (off), 'rules', 'thirds-high' or 'thirds-low'. */
+    setLights(mode) {
+        this.lights = mode === 'rules' && !this.lightRules ? null : mode;
+        this._changed();
+    }
+
+    /**
+     * By thirds: per measure, the values below which a third, and two thirds, of the detail cells
+     * showing fall. A cell under the first is the low third, under the second the middle, else the high.
+     */
+    thirds() {
+        const values = new Map();
+        const rows = this.visibleRows().map(r => r.node);
+        for (const c of this.visibleColumns()) {
+            for (const node of rows) {
+                const v = this.value(node, c);
+                if (typeof v !== 'number' || !this.isDetail(node, c)) continue;
+                if (!values.has(c.measure)) values.set(c.measure, []);
+                values.get(c.measure).push(v);
+            }
+        }
+        const cuts = new Map();
+        for (const [measure, list] of values) {
+            const sorted = [...list].sort((a, b) => a - b);
+            const at = (q) => sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * q))];
+            cuts.set(measure, [at(1 / 3), at(2 / 3)]);
+        }
+        return cuts;
+    }
+
+    /** The fill traffic lights give a cell, or null: off, not a detail cell, not a number, or no rule matching. */
+    cellFill(rowNode, column, cuts = null) {
+        if (!this.lights || !this.isDetail(rowNode, column)) return null;
+        const v = this.value(rowNode, column);
+        if (typeof v !== 'number') return null;
+        if (this.lights === 'rules') {
+            const rule = this.lightRules.find(r => (r.measure === undefined || r.measure === column.measure)
+                && (r.below === undefined || v < r.below) && (r.atLeast === undefined || v >= r.atLeast));
+            return rule?.fill ?? null;
+        }
+        const [t1, t2] = (cuts ?? this.thirds()).get(column.measure) ?? [];
+        if (t1 === undefined) return null;
+        const band = v < t1 ? 'low' : v < t2 ? 'mid' : 'high';
+        const good = this.lights === 'thirds-high' ? band : band === 'low' ? 'high' : band === 'high' ? 'low' : band;
+        return PivotView.LIGHTS[good];
+    }
+
+    /** A measure's value as the grid shows it, in the measure's `format` when there is one. */
+    valueText(measure, value, nullText = '—') {
+        return TableChart.cellText(value, nullText, TableChart.formatFor(this.format, measure));
+    }
+
+    /** The traffic lights in words, for a line under the grid; null when off. */
+    lightsLegend() {
+        if (!this.lights) return null;
+        const tail = ' (detail cells; totals not coloured)';
+        if (this.lights === 'rules') {
+            const said = this.lightRules.map(r => r.label ?? [
+                r.measure, r.atLeast !== undefined ? '≥ ' + this.valueText(r.measure, r.atLeast) : null,
+                r.below !== undefined ? '< ' + this.valueText(r.measure, r.below) : null,
+            ].filter(Boolean).join(' '));
+            return 'Traffic lights: ' + said.join('; ') + tail;
+        }
+        const better = this.lights === 'thirds-high' ? 'higher' : 'lower';
+        const cuts = [...this.thirds()].map(([m, [a, b]]) => m + ' ' + this.valueText(m, a) + ' / ' + this.valueText(m, b)).join('; ');
+        return 'Traffic lights by thirds, ' + better + ' is better — cut at ' + (cuts || 'no values') + tail;
+    }
+
+    // ── Saved views ────────────────────────────────────────────────────────────
+
+    /**
+     * How the grid shows its rows, as plain data a saved view keeps beside its layout: the members
+     * 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 };
+    }
+
+    /**
+     * Shows the rows as a saved view's display state says. A member the rows no longer have is simply
+     * not collapsed; host rules' traffic lights only when the host gives rules.
+     */
+    restoreDisplay(state = {}) {
+        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._changed();
+    }
+
+    /** The Views submenu: open a saved view, save this one, delete one — each the host's. */
+    _viewItems() {
+        if (!this.views) return [];
+        const names = this.views.list?.() ?? [];
+        const none = [{ label: '(none saved)', disabled: true }];
+        return [{
+            label: 'Views',
+            items: [
+                ...(names.length ? names.map(name => ({ label: name, action: () => this.views.open(name) })) : none),
+                { separator: true },
+                { label: 'Save this view…', action: () => this.views.save() },
+                { label: 'Delete', items: names.length ? names.map(name => ({ label: name, danger: true, action: () => this.views.remove(name) })) : none },
+            ],
+        }];
+    }
+
+    // ── Drill-through ──────────────────────────────────────────────────────────
+
+    /** A cell's members, `{ dimension: value }`: its row member's path and its column member's (a total names fewer). */
+    cellMembers(rowNode, column) {
+        return Object.fromEntries([
+            ...rowNode.path.map((value, i) => [this.rowAxis[i], value]),
+            ...column.node.path.map((value, i) => [this.columnAxis[i], value]),
+        ]);
+    }
+
+    /** Whether a cell's menu has anything: drill-through, or the host's own cell items. */
+    cellHasMenu() { return typeof this.onDrillThrough === 'function' || typeof this.menus?.cell === 'function'; }
+
+    /**
+     * A value cell's menu: the rows behind it (the host's, through onDrillThrough) — not offered for a
+     * cell of an empty member, which no filter can hold to — then the host's own cell items.
+     */
+    cellMenu(rowNode, column) {
+        const cell = this.cellMembers(rowNode, column);
+        const items = [];
+        if (this.onDrillThrough) {
+            const empty = Object.entries(cell).find(([, value]) => value == null);
+            items.push(empty
+                ? { label: `Show the rows behind this (not for an empty ${empty[0]})`, disabled: true }
+                : { label: 'Show the rows behind this', action: () => this.onDrillThrough({ cell, measure: column.measure }) });
+        }
+        const extra = this._extra('cell', { cell, measure: column.measure, row: this.cell(rowNode, column.node) });
+        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. */
+    gridMenu() {
+        const light = (label, mode) => ({ label: label + (this.lights === mode ? ' ✓' : ''), action: () => this.setLights(mode) });
+        return [
+            { label: 'Swap rows and columns', action: () => this.swapAxes() },
+            { label: 'Expand all', action: () => { this.collapsed.rows.clear(); this.collapsed.columns.clear(); this._changed(); } },
+            {
+                label: 'Traffic lights',
+                items: [
+                    light('Off', null),
+                    light('By thirds — higher is better', 'thirds-high'),
+                    light('By thirds — lower is better', 'thirds-low'),
+                    ...(this.lightRules ? [light('The rules given', 'rules')] : []),
+                ],
+            },
+            ...this._viewItems(),
+            { separator: true },
+            { label: 'Copy grid', action: () => this.copy(this.asTsv()) },
+            ...this._extra('grid', {}),
+        ];
+    }
+
+    _extra(kind, context) {
+        const items = this.menus?.[kind]?.({ view: this, ...context }) ?? [];
+        return items.length > 0 ? [{ separator: true }, ...items] : [];
+    }
+
+    /** The grid as showing, tab-separated: the column headers' lines, then a line per row. */
+    asTsv() {
+        const indent = this.rowAxis.length > 0 ? 1 : 0;
+        const head = this.columnHeaders().map(line => [...Array(indent).fill(''), ...line.flatMap(c => [c.text, ...Array(c.span - 1).fill('')])]);
+        const columns = this.visibleColumns();
+        const body = this.visibleRows().map(({ node, depth }) => [
+            ...(indent ? [`${'  '.repeat(depth)}${PivotView.label(node)}`] : []),
+            ...columns.map(c => { const v = this.value(node, c); return v == null ? '' : String(v); }),
+        ]);
+        return [...head, ...body].map(r => r.join('\t')).join('\n');
+    }
+}