@peter.prib/renderengine 0.9.0 → 0.12.0

package/src/charting/table/TableView.js

@@ -51,8 +51,9 @@ export class TableView {
      * @param {object} [options.menus] the host's own items: { cell, row, column, table } → items
      * @param {function} [options.copy] writes text to the clipboard (navigator.clipboard by default)
      * @param {ChartChooser} [options.chooser]
+     * @param {function} [options.highlight] row → true for a row drawn highlighted (a host's selection)
      */
-    constructor(rows, { columns = null, complete = true, pageSize = 50, onChange = null, menus = {}, copy = null, chooser = null } = {}) {
+    constructor(rows, { columns = null, complete = true, pageSize = 50, onChange = null, menus = {}, copy = null, chooser = null, highlight = null } = {}) {
         this.rows = rows;
         this.columns = ChartChooser.describe(rows, columns);
         this.complete = complete;
@@ -61,7 +62,9 @@ export class TableView {
         this.menus = menus;
         this.copy = copy ?? TableView.clipboard;
         this.chooser = chooser ?? new ChartChooser();
-        this.sort = null;            // { column, direction: 'asc' | 'desc' }
+        this.highlight = highlight;
+        /** The sort keys, most significant first: `{ column, direction: 'asc' | 'desc' }`. */
+        this.sorts = [];
         this.filters = [];           // { column, op, value }
         this.hidden = new Set();
         this.page = 0;
@@ -75,19 +78,44 @@ export class TableView {
 
     visibleColumns() { return this.columns.filter(c => !this.hidden.has(c.name)); }
 
+    /** Whether a row is drawn highlighted: the host's `highlight` says (its selection, say). */
+    isHighlighted(row) { return this.highlight?.(row) === true; }
+
     filtered() {
         return this.filters.length === 0 ? this.rows
             : this.rows.filter(r => this.filters.every(f => FILTER_OPS[f.op](r[f.column], f.value)));
     }
 
-    /** The filtered rows in sort order (a copy; equal values keep their order). */
+    /** The first sort key, or null — the one a single-column sort has. */
+    get sort() { return this.sorts[0] ?? null; }
+
+    /** Where `column` is among the sort keys: `{ direction, rank }` (rank from 1), or null. */
+    sortOf(column) {
+        const at = this.sorts.findIndex(s => s.column === column);
+        return at < 0 ? null : { direction: this.sorts[at].direction, rank: at + 1 };
+    }
+
+    /**
+     * The filtered rows in sort order (a copy): by the first key, then the next among equals, and so
+     * on; rows equal on every key keep their order.
+     */
     ordered() {
         const rows = this.filtered();
-        if (this.sort === null) return rows;
-        const { column, direction } = this.sort;
-        const sign = direction === 'desc' ? -1 : 1;
-        // Nulls stay last whichever way: a reader looks for values, not for blanks.
-        return [...rows].sort((a, b) => (a[column] == null || b[column] == null ? compareValues(a[column], b[column]) : sign * compareValues(a[column], b[column])));
+        if (this.sorts.length === 0) return rows;
+        const keys = this.sorts.map(({ column, direction }) => ({ column, sign: direction === 'desc' ? -1 : 1 }));
+        return [...rows].sort((a, b) => {
+            for (const { column, sign } of keys) {
+                // Nulls stay last whichever way: a reader looks for values, not for blanks.
+                const c = a[column] == null || b[column] == null ? compareValues(a[column], b[column]) : sign * compareValues(a[column], b[column]);
+                if (c !== 0) return c;
+            }
+            return 0;
+        });
+    }
+
+    /** "Region ▲, then Revenue ▼", or '' when unsorted. */
+    describeSort() {
+        return this.sorts.map(s => `${s.column} ${s.direction === 'asc' ? '▲' : '▼'}`).join(', then ');
     }
 
     pageCount() {
@@ -114,14 +142,41 @@ export class TableView {
         this.onChange?.(this);
     }
 
-    /** A header click: unsorted → ascending → descending → unsorted. */
-    toggleSort(column) {
-        const current = this.sort?.column === column ? this.sort.direction : null;
-        this.sortBy(column, current === null ? 'asc' : current === 'asc' ? 'desc' : null);
+    /**
+     * A header click: unsorted → ascending → descending → unsorted, by this column alone. With
+     * `{ then: true }` (a shift-click) the column is a further key instead: added after the others,
+     * or, if it is one already, cycled in its place — the other keys stay.
+     */
+    toggleSort(column, { then = false } = {}) {
+        const next = (d) => (d === null ? 'asc' : d === 'asc' ? 'desc' : null);
+        if (then) {
+            this.thenSortBy(column, next(this.sortOf(column)?.direction ?? null));
+            return;
+        }
+        const alone = this.sorts.length === 1 && this.sorts[0].column === column ? this.sorts[0].direction : null;
+        this.sortBy(column, next(alone));
     }
 
+    /** Sorts by `column` alone (null: unsorted). */
     sortBy(column, direction) {
-        this.sort = direction === null ? null : { column, direction };
+        this.sorts = direction === null ? [] : [{ column, direction }];
+        this.page = 0;
+        this.changed();
+    }
+
+    /** `column` as a further sort key: its direction changed in place, appended if new, removed with null. */
+    thenSortBy(column, direction) {
+        const at = this.sorts.findIndex(s => s.column === column);
+        if (direction === null) this.sorts = this.sorts.filter(s => s.column !== column);
+        else if (at >= 0) this.sorts = this.sorts.map(s => (s.column === column ? { column, direction } : s));
+        else this.sorts = [...this.sorts, { column, direction }];
+        this.page = 0;
+        this.changed();
+    }
+
+    /** Unsorted: rows in the order given. */
+    clearSort() {
+        this.sorts = [];
         this.page = 0;
         this.changed();
     }
@@ -201,13 +256,23 @@ export class TableView {
     }
 
     columnMenu(column) {
-        const sorted = this.sort?.column === column ? this.sort.direction : null;
+        const key = this.sortOf(column);
+        const alone = this.sorts.length === 1 && key !== null;
+        const sorted = alone ? key.direction : null;
+        // A further key: offered once something else is sorted (so this column is never the only key
+        // here); ticked where this column already is one.
+        const further = this.sorts.some(s => s.column !== column) ? [
+            { label: 'Then sort ascending', checked: key?.direction === 'asc', action: () => this.thenSortBy(column, 'asc') },
+            { label: 'Then sort descending', checked: key?.direction === 'desc', action: () => this.thenSortBy(column, 'desc') },
+            ...(key !== null ? [{ label: 'Stop sorting by this column', action: () => this.thenSortBy(column, null) }] : []),
+        ] : [];
         const values = [...new Set(this.filtered().map(r => r[column]))].sort(compareValues);
         const listed = values.slice(0, TableView.MAX_FILTER_VALUES);
         return [
             { label: 'Sort ascending', checked: sorted === 'asc', action: () => this.sortBy(column, 'asc') },
             { label: 'Sort descending', checked: sorted === 'desc', action: () => this.sortBy(column, 'desc') },
-            ...(sorted ? [{ label: 'Clear sort', action: () => this.sortBy(column, null) }] : []),
+            ...further,
+            ...(this.sorts.length > 0 ? [{ label: 'Clear sort', action: () => this.clearSort() }] : []),
             { separator: true },
             {
                 label: 'Filter to',

package/src/charting/table/TableViewChart.js

@@ -16,6 +16,7 @@ export class TableViewChart extends TableChart {
     static GUTTER_W = 44;
     static MENU_GLYPH = '▾';
     static TABLE_GLYPH = '⋮';
+    static HIGHLIGHT_FILL = '#fdeeb5';
 
     /**
      * @param renderer
@@ -57,13 +58,15 @@ export class TableViewChart extends TableChart {
 
         columns.forEach((c, i) => {
             const left = x0 + i * colW;
-            const sorted = view.sort?.column === c.key ? (view.sort.direction === 'asc' ? ' ▲' : ' ▼') : '';
+            // ▲ / ▼, and with several keys their order: "Region ▲1", "Revenue ▼2".
+            const key = view.sortOf(c.key);
+            const sorted = key === null ? '' : ` ${key.direction === 'asc' ? '▲' : '▼'}${view.sorts.length > 1 ? key.rank : ''}`;
             // In words: an arrow-like mark here read as a second sort arrow.
             const filtered = view.filters.some(f => f.column === c.key) ? ' (filtered)' : '';
             const head = this.renderer.rect(left, top, colW, ROW_H, TableChart.HEADER_FILL, null);
             // The label leaves room at the right for the ▾.
             const label = this._cell(`${c.label}${sorted}${filtered}`, c, left, top, colW - 16, { fontWeight: 'bold', fill: '#333' });
-            this._on(interactive, [head, label], () => view.toggleSort(c.key), 'Sort');
+            this._on(interactive, [head, label], (e) => view.toggleSort(c.key, { then: e?.shiftKey === true }), 'Sort (shift-click: then sort by)');
             const glyph = this._text(TableViewChart.MENU_GLYPH, left + colW - 8, top, { textAnchor: 'middle', fill: '#777' });
             this._on(interactive, [glyph], (e) => this.showMenu(e.clientX, e.clientY, view.columnMenu(c.key)), `${c.label} menu`);
         });
@@ -72,7 +75,8 @@ export class TableViewChart extends TableChart {
 
         // Rows: a number in the gutter (row menu), a cell per column (cell menu).
         view.pageRows().forEach(({ row, index }, r) => {
-            if (r % 2 === 1) this.renderer.rect(box.x, top, box.width, ROW_H, TableChart.STRIPE_FILL, null);
+            if (view.isHighlighted(row)) this.renderer.rect(box.x, top, box.width, ROW_H, TableViewChart.HIGHLIGHT_FILL, null);
+            else if (r % 2 === 1) this.renderer.rect(box.x, top, box.width, ROW_H, TableChart.STRIPE_FILL, null);
             const number = this._text(String(index + 1), box.x + gutter - PAD_X, top, { textAnchor: 'end', fill: '#999', fontSize: '11px' });
             this._on(interactive, [number], (e) => this.showMenu(e.clientX, e.clientY, view.rowMenu(row)), 'Row menu');
             columns.forEach((c, i) => {

package/src/datawindow/BoundedWindow.js

@@ -2,7 +2,7 @@
  * Abstract base for "own a bounded collection, push one more item, drop the
  * oldest once past a cap" — the one behavior every streamable chart data
  * shape shares, however differently each stores its collection(s). See
- * ARCHITECTURE.md's "Data windows — streaming" section for the concrete
+ * documentation/ARCHITECTURE.md's "Data windows — streaming" section for the concrete
  * subtypes and why each exists as its own class rather than a branch here.
  */
 export class BoundedWindow {

package/src/datawindow/GraphDataWindow.js

@@ -2,7 +2,7 @@ import { BoundedWindow } from './BoundedWindow.js';
 
 /**
  * A nodes+edges pair — the shape behind `graphDiagram`/`graphDiagram3D`.
- * Not a `CHART_CATALOG` entry (see ARCHITECTURE.md), so it isn't dispatched
+ * Not a `CHART_CATALOG` entry (see documentation/ARCHITECTURE.md), so it isn't dispatched
  * through `createDataWindow`/`streamShape`; `RenderEngine.addGraphNode`
  * constructs it directly. Trimming drops the oldest nodes FIFO, then any
  * edge left dangling off a removed node — dropping nodes without this would