@peter.prib/renderengine 0.10.0 → 0.13.0

package/src/charting/table/TableView.js

@@ -1,4 +1,5 @@
 import { ChartChooser } from '../ChartChooser.js';
+import { TableChart } from '../charts/TableChart.js';
 
 /**
  * TableView — the state of an interactive table over result rows, kept apart from drawing so all of
@@ -52,8 +53,10 @@ export class TableView {
      * @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)
+     * @param {function|Intl.NumberFormat|object} [options.format] how numbers show, for every column or per
+     *   column (`TableChart.formatFor`). A copy keeps the raw numbers.
      */
-    constructor(rows, { columns = null, complete = true, pageSize = 50, onChange = null, menus = {}, copy = null, chooser = null, highlight = null } = {}) {
+    constructor(rows, { columns = null, complete = true, pageSize = 50, onChange = null, menus = {}, copy = null, chooser = null, highlight = null, format = null } = {}) {
         this.rows = rows;
         this.columns = ChartChooser.describe(rows, columns);
         this.complete = complete;
@@ -63,12 +66,19 @@ export class TableView {
         this.copy = copy ?? TableView.clipboard;
         this.chooser = chooser ?? new ChartChooser();
         this.highlight = highlight;
-        this.sort = null;            // { column, direction: 'asc' | 'desc' }
+        this.format = format;
+        /** The sort keys, most significant first: `{ column, direction: 'asc' | 'desc' }`. */
+        this.sorts = [];
         this.filters = [];           // { column, op, value }
         this.hidden = new Set();
         this.page = 0;
     }
 
+    /** A column's value as the table shows it, in the column's `format` when there is one. */
+    valueText(column, value, nullText = '—') {
+        return TableChart.cellText(value, nullText, TableChart.formatFor(this.format, column));
+    }
+
     static clipboard(text) {
         return globalThis.navigator?.clipboard?.writeText(text);
     }
@@ -85,14 +95,36 @@ export class TableView {
             : 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() {
@@ -119,14 +151,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();
     }
@@ -206,13 +265,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

@@ -58,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`);
         });
@@ -80,7 +82,7 @@ export class TableViewChart extends TableChart {
             columns.forEach((c, i) => {
                 const left = x0 + i * colW;
                 const hit = this.renderer.rect(left, top, colW, ROW_H, 'transparent', null);
-                const text = this._cell(TableChart.cellText(row[c.key], nullText), c, left, top, colW, { fill: row[c.key] == null ? '#999' : '#222' });
+                const text = this._cell(view.valueText(c.key, row[c.key], nullText), c, left, top, colW, { fill: row[c.key] == null ? '#999' : '#222' });
                 this._on(interactive, [hit, text], (e) => this.showMenu(e.clientX, e.clientY, view.cellMenu(row, c.key)), null);
             });
             top += ROW_H;

package/src/charting/templates/Template.js

@@ -102,6 +102,16 @@ export class Template {
         return { x: this.x + ux * t, y: this.y + uy * t };
     }
 
+    /**
+     * Where a line from (px, py), a point inside the shape, heading in
+     * direction (dx, dy) leaves its outline (the shape unrotated).
+     * @returns {{x: number, y: number}}
+     */
+    exitPoint(px, py, dx, dy) {
+        const t = rayExitDistance(this.outline(), px, py, dx, dy);
+        return { x: px + dx * t, y: py + dy * t };
+    }
+
     /** Centre of the name text; the z-index line sits just below it. */
     get labelAnchor() { return { x: this.x, y: this.y - 8 }; }
 

package/src/exportImage.js

@@ -31,10 +31,10 @@ export const MAX_IMAGE_PIXELS = 32_000_000;
 /**
  * Work out the bitmap size to rasterize at.
  *
- * `scale` is what the caller asked for (2 = retina-sharp). It is reduced, never
- * the diagram's own dimensions, when the result would be too large: halving the
- * scale of a huge diagram still shows all of it, whereas cropping or shrinking
- * the diagram loses content or legibility.
+ * `scale` is what the caller asked for (1 = 100%, 2 = retina-sharp, 0.5 = half
+ * size). It is reduced, never the diagram's own dimensions, when the result
+ * would be too large: halving the scale of a huge diagram still shows all of
+ * it, whereas cropping or shrinking the diagram loses content or legibility.
  *
  * @returns {{width:number, height:number, scale:number, clamped:boolean}}
  */
@@ -49,10 +49,6 @@ export function imageSize({ width, height, scale = 2, maxPixels = MAX_IMAGE_PIXE
         s = Math.sqrt(maxPixels / (w * h));
         clamped = true;
     }
-    // A scale below 1:1 would be a downscale the caller never asked for, but a
-    // diagram that is itself over the budget leaves no choice.
-    if (s < 1 && w * h <= maxPixels) s = 1;
-
     return { width: Math.max(1, Math.round(w * s)), height: Math.max(1, Math.round(h * s)), scale: s, clamped };
 }
 
@@ -67,8 +63,10 @@ export function imageSize({ width, height, scale = 2, maxPixels = MAX_IMAGE_PIXE
  * @param {number} [options.width]       pixels; omitted leaves what is there
  * @param {number} [options.height]
  * @param {string|null} [options.background='#ffffff']  null for transparent
+ * @param {string} [options.viewBox]  the drawing's own units, when it has none
+ *   (so a picture sized other than as drawn scales rather than crops)
  */
-export function prepareSvgMarkup(markup, { width, height, background = '#ffffff' } = {}) {
+export function prepareSvgMarkup(markup, { width, height, background = '#ffffff', viewBox } = {}) {
     let out = String(markup ?? '').trim();
     const open = out.match(/^<svg\b[^>]*>/i);
     if (!open) return out;          // not an <svg> — hand it back untouched
@@ -87,13 +85,23 @@ export function prepareSvgMarkup(markup, { width, height, background = '#ffffff'
     };
     if (Number.isFinite(width) && width > 0) setAttr('width', Math.round(width));
     if (Number.isFinite(height) && height > 0) setAttr('height', Math.round(height));
+    if (viewBox && !/\sviewBox\s*=/i.test(tag)) setAttr('viewBox', viewBox);
 
     out = tag + out.slice(open[0].length);
 
     if (background) {
-        // First child, so it sits behind everything. Percentages rather than
-        // pixels so it still covers the drawing if a viewBox rescales it.
-        out = out.replace(tag, `${tag}<rect x="0" y="0" width="100%" height="100%" fill="${background}"/>`);
+        // First child, so it sits behind everything. With a viewBox it reaches
+        // a whole viewBox past each side (the picture clips it): a percentage
+        // counts from (0,0), so a viewBox starting elsewhere (a cropped
+        // drawing) would leave a strip bare, and the viewBox alone would leave
+        // the bands a picture of another shape letterboxes it with.
+        // Without one, percentages, so it covers whatever size it is shown at.
+        const box = tag.match(/\sviewBox\s*=\s*["']\s*([-\d.e+]+)[\s,]+([-\d.e+]+)[\s,]+([-\d.e+]+)[\s,]+([-\d.e+]+)\s*["']/i);
+        const [x, y, w, h] = box ? box.slice(1).map(Number) : [];
+        const rect = box
+            ? `<rect x="${x - w}" y="${y - h}" width="${3 * w}" height="${3 * h}" fill="${background}"/>`
+            : `<rect x="0" y="0" width="100%" height="100%" fill="${background}"/>`;
+        out = out.replace(tag, `${tag}${rect}`);
     }
     return out;
 }
@@ -126,12 +134,12 @@ export function findDrawable(host) {
  * Size is taken from the element's laid-out box rather than its attributes,
  * because that is what the user is actually looking at.
  */
-export function serializeSvg(svgEl, { background = '#ffffff', width, height } = {}) {
+export function serializeSvg(svgEl, { background = '#ffffff', width, height, scale = 1 } = {}) {
     const box = svgEl.getBoundingClientRect?.() ?? {};
     const w = width ?? svgEl.width?.baseVal?.value ?? box.width;
     const h = height ?? svgEl.height?.baseVal?.value ?? box.height;
     const markup = new XMLSerializer().serializeToString(svgEl);
-    return prepareSvgMarkup(markup, { width: w, height: h, background });
+    return prepareSvgMarkup(markup, { width: w * scale, height: h * scale, background, viewBox: `0 0 ${w} ${h}` });
 }
 
 /**
@@ -150,9 +158,16 @@ export async function toPngBlob(host, { scale = 2, background = '#ffffff', maxPi
     }
 
     const box = drawable.getBoundingClientRect();
-    const size = imageSize({ width: box.width, height: box.height, scale, maxPixels });
     const markup = serializeSvg(drawable, { background, width: box.width, height: box.height });
+    return svgMarkupToPngBlob(markup, { width: box.width, height: box.height, scale, background, maxPixels });
+}
 
+/**
+ * Rasterize standalone SVG markup (prepareSvgMarkup's) drawn `width` × `height`
+ * to a PNG Blob at `scale`. DOM only.
+ */
+export async function svgMarkupToPngBlob(markup, { width, height, scale = 1, background = '#ffffff', maxPixels = MAX_IMAGE_PIXELS } = {}) {
+    const size = imageSize({ width, height, scale, maxPixels });
     // A data: URL rather than a blob: URL — a blob: URL taints nothing either,
     // but Safari has historically refused to draw SVG from one.
     const url = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(markup)}`;
@@ -200,7 +215,15 @@ export function downloadBlob(blob, filename) {
  * @returns {Promise<{via:'clipboard'|'download', filename?:string}>}
  */
 export async function copyImage(host, { scale = 2, background = '#ffffff', name = 'diagram' } = {}) {
-    const blob = await toPngBlob(host, { scale, background });
+    return copyPngBlob(await toPngBlob(host, { scale, background }), { name });
+}
+
+/**
+ * Put a PNG Blob on the clipboard, or download it where the browser cannot
+ * (as copyImage). DOM only.
+ * @returns {Promise<{via:'clipboard'|'download', filename?:string}>}
+ */
+export async function copyPngBlob(blob, { name = 'diagram' } = {}) {
     const canWrite = typeof ClipboardItem !== 'undefined'
         && typeof navigator !== 'undefined'
         && navigator.clipboard?.write;
@@ -220,10 +243,14 @@ export async function copyImage(host, { scale = 2, background = '#ffffff', name
 }
 
 /** Save a diagram as an SVG file. DOM only. */
-export function downloadSvg(host, { background = '#ffffff', name = 'diagram' } = {}) {
+export function downloadSvg(host, { background = '#ffffff', name = 'diagram', scale = 1 } = {}) {
     const drawable = findDrawable(host);
     if (!drawable || drawable.tagName.toLowerCase() !== 'svg') throw new Error('No <svg> to export');
-    const markup = serializeSvg(drawable, { background });
+    downloadSvgMarkup(serializeSvg(drawable, { background, scale }), { name });
+}
+
+/** Save standalone SVG markup as a file. DOM only. */
+export function downloadSvgMarkup(markup, { name = 'diagram' } = {}) {
     downloadBlob(new Blob([markup], { type: 'image/svg+xml;charset=utf-8' }), imageFileName(name, 'svg'));
 }