@peter.prib/renderengine 0.10.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.10.0",
+  "version": "0.13.0",
   "description": "ArchiMate modeller, diagram editor and chart library for the browser, with no runtime dependencies.",
   "type": "module",
   "main": "src/index.js",
@@ -28,7 +28,7 @@
     "archimate": "node scripts/open.mjs examples/archimate.html",
     "diagram": "node scripts/open.mjs examples/diagram-editor.html",
     "datamodel": "node scripts/open.mjs examples/data-model.html",
-    "test": "node --test --test-timeout=10000 ./test/*.js ./test/charting/*.js ./test/charting/charts/*.js ./test/charting/table/*.js ./test/charting/diagrams/*.js ./test/charting/shapes/*.js",
+    "test": "node --test --test-timeout=10000 ./test/*.js ./test/charting/*.js ./test/charting/charts/*.js ./test/charting/table/*.js ./test/charting/pivot/*.js ./test/charting/diagrams/*.js ./test/charting/shapes/*.js",
     "build": "rollup -c",
     "prepublishOnly": "npm test && npm run build",
     "screenshots": "node scripts/screenshots/screenshots.mjs"

package/src/charting/Axis.js

@@ -27,6 +27,30 @@ export class Axis {
         return ticks;
     }
 
+    /**
+     * Ticks over a range that may go below zero: one common "nice" step, from at or below `minVal`
+     * to at or above `maxVal`, always taking in 0 so bars have a baseline. Without a negative it is
+     * `niceTicks(maxVal)`.
+     * @param {number} minVal
+     * @param {number} maxVal
+     * @param {number} [count=4] desired number of intervals
+     * @returns {number[]}
+     */
+    static niceRange(minVal, maxVal, count = 4) {
+        const lo = Math.min(0, minVal || 0);
+        const hi = Math.max(0, maxVal || 0);
+        if (lo === 0) return Axis.niceTicks(hi, count);
+        const raw = (hi - lo) / count;
+        const mag = Math.pow(10, Math.floor(Math.log10(raw)));
+        const frac = raw / mag;
+        const step = frac < 1.5 ? mag : frac < 3.5 ? 2 * mag : frac < 7.5 ? 5 * mag : 10 * mag;
+        const first = Math.floor(lo / step + 1e-9);
+        const last = Math.ceil(hi / step - 1e-9);
+        const ticks = [];
+        for (let i = first; i <= last; i++) ticks.push(parseFloat((i * step).toFixed(10)));
+        return ticks;
+    }
+
     /**
      * How often a category label fits along an axis `width` wide: 1 (every
      * label), 2 (every other), … — so a long series (a minute of samples, a
@@ -71,18 +95,36 @@ export class Axis {
      * @returns {number} the nice domain max the ticks actually span
      */
     drawYAxis(renderer, box, rawMax) {
-        const ticks = Axis.niceTicks(rawMax);
-        const niceMax = ticks[ticks.length - 1] || 1;
+        return this.drawYRange(renderer, box, 0, rawMax).max;
+    }
+
+    /**
+     * Draw a y-axis over a range that may go below zero (`niceRange`): ticks, labels, gridlines,
+     * and, when the range does go below zero, a zero line across the plot where it crosses.
+     *
+     * @param {*} renderer a renderer implementing .path() and .text()
+     * @param {{x:number, y:number, width:number, height:number}} box plot-area box
+     * @param {number} rawMin the raw data minimum (0 or more: the axis starts at 0)
+     * @param {number} rawMax the raw data maximum
+     * @returns {{min:number, max:number}} the nice domain the ticks actually span
+     */
+    drawYRange(renderer, box, rawMin, rawMax) {
+        const ticks = Axis.niceRange(rawMin, rawMax);
+        const min = ticks[0];
+        const max = ticks.length > 1 ? ticks[ticks.length - 1] : 1;
+        const yOf = (v) => box.y + box.height - ((v - min) / (max - min)) * box.height;
         for (const t of ticks) {
-            const ty = box.y + box.height - (t / niceMax) * box.height;
+            const ty = yOf(t);
             renderer.path(`M${box.x - 5},${ty} L${box.x},${ty}`, 'none', { color: '#999', width: 1 });
-            if (t > 0) {
+            if (t !== 0) {
                 renderer.path(`M${box.x},${ty} L${box.x + box.width},${ty}`, 'none', { color: '#eee', width: 1 });
+            } else if (min < 0) {
+                renderer.path(`M${box.x},${ty} L${box.x + box.width},${ty}`, 'none', { color: '#666', width: 1, zeroLine: true });
             }
             renderer.text(Axis.formatValue(t), box.x - 10, ty, {
                 textAnchor: 'end', verticalAlign: 'middle', fontSize: '10px', fill: '#666',
             });
         }
-        return niceMax;
+        return { min, max };
     }
 }

package/src/charting/Chart.js

@@ -4,6 +4,10 @@
  * Subclasses implement `_render()` and are instantiated by RenderEngine's
  * chart methods. Keeping each chart in its own class removes the giant
  * RenderEngine God class one chart at a time.
+ *
+ * A chart that draws one mark per value (a bar, a slice, a point) records it with `_datum()`; when
+ * the options carry `onDatumClick(datum, event)` and the renderer's shapes take clicks (SVG), each
+ * such mark answers a click with its datum, `{ label, series }` — how a host drills from a chart.
  */
 export class Chart {
     /** Registry key / catalog key for this chart type. Subclasses override. */
@@ -16,13 +20,34 @@ export class Chart {
         this.renderer = renderer;
         this.data = data;
         this.options = options;
+        /** The marks drawn for values, `{ shape, datum }`, as the last render() drew them. */
+        this.datums = [];
     }
 
     /** Render the chart. Subclasses implement `_render()`. */
     render() {
         if (!this.renderer) return;
         this.renderer.clear();
+        this.datums = [];
         this._render();
+        this._wireDatums();
+    }
+
+    /** Records that `shape` (what the renderer returned) shows one value, `datum` = { label, series? }. */
+    _datum(shape, datum) {
+        this.datums.push({ shape, datum: { series: null, ...datum } });
+        return shape;
+    }
+
+    /** Gives each recorded mark the host's onDatumClick, where the renderer's shapes take clicks. */
+    _wireDatums() {
+        const handler = this.options?.onDatumClick;
+        if (typeof handler !== 'function' || this.renderer.supportsSceneGraph !== true) return;
+        for (const { shape, datum } of this.datums) {
+            if (typeof shape?.addEventListener !== 'function') continue;
+            shape.addEventListener('click', (event) => { event.stopPropagation?.(); handler(datum, event); });
+            if (shape.style) shape.style.cursor = 'pointer';
+        }
     }
 
     /** Subclasses implement the actual drawing here. */

package/src/charting/ChartChooser.js

@@ -186,14 +186,15 @@ class CategorySeries extends ResultShape {
         const { category } = this;
         const time = category.kind === 'time';
         const rows = time ? inOrder(this.rows, category.name) : this.rows;
-        // lineChart and groupedBarChart have no gap for a missing value: a null would have to be drawn
-        // as 0, a figure the data does not hold. So a result with one is not offered as series.
-        if (rows.some(r => this.numbers.some(n => r[n.name] == null))) return [];
+        // groupedBarChart leaves a gap for a missing value; lineChart has none (a null would have to be
+        // drawn as 0, a figure the data does not hold), so a result with one is offered as bars only.
+        const gaps = rows.some(r => this.numbers.some(n => r[n.name] == null));
         const data = this.numbers.map(n => ({
             name: n.name,
-            values: rows.map(r => ({ label: label(r[category.name]), value: r[n.name] })),
+            values: rows.map(r => ({ label: label(r[category.name]), value: r[n.name] ?? null })),
         }));
         const names = this.numbers.map(n => n.name).join(', ');
+        if (gaps) return [{ key: 'groupedBar', reason: `${names} for each ${category.name} (a gap where there is no value)`, data }];
         return time
             ? [{ key: 'line', reason: `${names} over ${category.name}`, data }, { key: 'groupedBar', reason: `${names} for each ${category.name}`, data }]
             : [{ key: 'groupedBar', reason: `${names} for each ${category.name}`, data }, { key: 'line', reason: `${names} across ${category.name}`, data }];

package/src/charting/DiagramEditor.js

@@ -30,7 +30,7 @@ const SHAPE_FIELD_KEYS = Object.freeze(['name', 'x', 'y', 'zIndex', 'fillColor',
 const WARNING_COLOR = '#e74c3c';
 const WARNING_DASH = '4 3';
 import { EMPHASIS_OPACITY, strongerEmphasis } from './emphasis/EmphasisRule.js';
-import { downloadPng, downloadSvg, copyImage, prepareSvgMarkup } from '../exportImage.js';
+import { downloadPng, downloadSvg, copyImage, prepareSvgMarkup, svgMarkupToPngBlob, copyPngBlob, downloadSvgMarkup, downloadBlob, imageFileName } from '../exportImage.js';
 import { el } from '../workspace/dom.js';
 import { applyViewDecorations } from './viewDecorations.js';
 import { ToolbarButton, ToolbarMenu, ToolbarText } from './toolbar/index.js';
@@ -59,6 +59,15 @@ import {
  * toolbar container) to itself.
  */
 export class DiagramEditor {
+    /** An exported picture's defaults: the whole drawing, at 100%. */
+    static EXPORT_DEFAULTS = Object.freeze({ area: 'drawing', scale: 1 });
+
+    /** Space kept clear round an exported drawing, so nothing touches the picture's edge. */
+    static EXPORT_MARGIN = 20;
+
+    /** How far an arrowhead (or other line-end marker) reaches past its line's end. */
+    static MARKER_REACH = 10;
+
     /** How a selected shape (besides the one with handles) is marked: an outline `pad` outside it, tinted. */
     static SELECTION_OUTLINE = Object.freeze({ pad: 4, stroke: '#0066cc', strokeWidth: 2, dash: '5,3', fill: 'rgba(0, 102, 204, 0.08)' });
 
@@ -122,6 +131,10 @@ export class DiagramEditor {
         /** Off unless asked for (the `showGrid` option, or ⚙ Settings → Grid), as the settings' default says. */
         this.showGrid = options.showGrid ?? false;
         this.gridSize = 20;
+        /** A faint box where an exported picture's edges fall (⚙ Settings → Export area); never exported itself. */
+        this.showExportArea = options.showExportArea ?? false;
+        /** What an exported picture takes in, and at what size (Export image… remembers the last choice). */
+        this.exportOptions = { ...DiagramEditor.EXPORT_DEFAULTS };
 
         // Zoom and pan
         this.zoomLevel = 1.0;
@@ -429,6 +442,17 @@ export class DiagramEditor {
         return [];
     }
 
+    /**
+     * The whole menu a right-click on empty canvas at `at` opens: paste here,
+     * canvasMenuItems, then Export image (imageMenuItems), each set apart.
+     */
+    canvasContextMenu(at) {
+        const paste = this.canClipboardPaste() ? [{ label: '📋 Paste here', action: () => this.paste({ at }) }] : [];
+        const image = this.imageMenuItems();
+        const sections = [paste, this.canvasMenuItems(at), image.length ? [{ label: 'Export image', items: image }] : []].filter(s => s.length);
+        return sections.flatMap((s, i) => (i ? [{ separator: true }, ...s] : s));
+    }
+
     /**
      * The menu for empty canvas at `at` (drawing coordinates); none here, a
      * subclass offers its own (place a template, ...).
@@ -670,6 +694,7 @@ export class DiagramEditor {
 
         // Render edges
         this._renderEdges(group);
+        if (this.showExportArea && container.tagName === 'svg') this._renderExportArea(group);
 
         // The selection's groups and other selected shapes, then the primary shape's handles.
         this._renderArrangement(group);
@@ -768,9 +793,13 @@ export class DiagramEditor {
         ];
     }
 
-    /** Export the current view as a picture: PNG, SVG, or a copy to the clipboard. */
+    /**
+     * Export the current view as a picture: PNG, SVG, or a copy to the clipboard,
+     * as Export image… last chose (the whole drawing at 100% to begin with).
+     */
     imageMenuItems() {
         return [
+            { label: 'Export image…', action: () => this.askExportImage() },
             { label: 'Export image (PNG)', action: () => this.exportImage('png') },
             { label: 'Export image (SVG)', action: () => this.exportImage('svg') },
             { label: 'Copy image', action: () => this.exportImage('copy') },
@@ -800,17 +829,113 @@ export class DiagramEditor {
      * The current view as a picture: 'png' or 'svg' downloads it, 'copy' puts a
      * PNG on the clipboard (or downloads it where the browser cannot). The grid,
      * the selection and its handles are left out.
+     *
+     * `area` 'drawing' (the default) takes in everything drawn, wherever the view
+     * is scrolled to: every shape and line, labels and arrowheads included, with
+     * a margin clear of the edge (drawingBounds). 'view' is what is in sight.
+     * `scale` sizes the picture: 1 is 100%.
      * @param {'png'|'svg'|'copy'} format
+     * @param {{area?: 'drawing'|'view', scale?: number}} [options] - Export image…'s last choice by default
      */
-    exportImage(format = 'png') {
+    exportImage(format = 'png', { area = this.exportOptions.area, scale = this.exportOptions.scale } = {}) {
         const host = this.drawingHost();
         if (!host) return null;
         const name = this.imageName();
-        return this._withPlainDrawing(() => {
-            if (format === 'svg') return downloadSvg(host, { name });
-            if (format === 'copy') return copyImage(host, { name });
-            return downloadPng(host, { name });
+        if (area === 'view' || host.tagName?.toLowerCase() !== 'svg') {
+            return this._withPlainDrawing(() => {
+                if (format === 'svg') return downloadSvg(host, { name, scale });
+                if (format === 'copy') return copyImage(host, { name, scale });
+                return downloadPng(host, { name, scale });
+            });
+        }
+        const viewBox = this.drawingBounds();
+        if (!viewBox) return null;
+        const svg = this._withPlainDrawing(() => this._croppedSvg(host, viewBox, { scale }));
+        if (format === 'svg') return downloadSvgMarkup(svg, { name });
+        const png = svgMarkupToPngBlob(svg, { width: viewBox.width, height: viewBox.height, scale });
+        if (format === 'copy') return png.then(blob => copyPngBlob(blob, { name }));
+        return png.then(blob => downloadBlob(blob, imageFileName(name, 'png')));
+    }
+
+    /** Ask what to export: the format, the whole drawing or what is in sight, and the scale (%). */
+    askExportImage() {
+        const { area, scale } = this.exportOptions;
+        new FormDialog({
+            title: 'Export image',
+            description: 'The whole drawing takes in every shape and line, with a margin; the view, only what is in sight.',
+            fields: [
+                { key: 'format', label: 'Format', type: 'select', value: 'png', choices: [['png', 'PNG'], ['svg', 'SVG'], ['copy', 'Copy to the clipboard (PNG)']] },
+                { key: 'area', label: 'Take in', type: 'select', value: area, choices: [['drawing', 'The whole drawing'], ['view', 'What is in sight']] },
+                { key: 'scale', label: 'Scale (%)', type: 'number', value: Math.round(scale * 100), min: 10, max: 800, step: 10 },
+            ],
+            submitLabel: 'Export',
+            document: this.document ?? globalThis.document,
+            onApply: (values) => this.exportImage(values.format, this.setExportOptions(values)),
+        }).open();
+    }
+
+    /**
+     * Remember an export's area and scale (the scale in %), for the next one.
+     * A scale that is not a positive number keeps the last. Returns the options.
+     */
+    setExportOptions({ area, scale } = {}) {
+        if (area === 'drawing' || area === 'view') this.exportOptions.area = area;
+        const pct = Number(scale);
+        if (Number.isFinite(pct) && pct > 0) this.exportOptions.scale = pct / 100;
+        return { ...this.exportOptions };
+    }
+
+    /**
+     * Where an exported picture of the whole drawing ends (in drawing units):
+     * every shape and line shown, with line labels and arrowheads, and
+     * `margin` clear all round, so nothing touches the picture's edge. Null
+     * when nothing is drawn.
+     * @returns {{x, y, width, height}|null}
+     */
+    drawingBounds({ margin = DiagramEditor.EXPORT_MARGIN } = {}) {
+        const boxes = [...this.templates.values()]
+            .filter(t => t.visible !== false && this.templateEmphasis(t) !== 'hidden')
+            .map(t => ({ left: t.left, top: t.top, right: t.right, bottom: t.bottom }));
+        const cascade = this.edgeStyleCascade();
+        for (const edge of this.getAllEdges()) {
+            if (!edge.visible || this.edgeEmphasis(edge) === 'hidden') continue;
+            const { style } = cascade.resolve(edge);
+            const path = this._edgePath(edge, style);
+            if (!path) continue;
+            // Every point the path names (a curve's control points bound it); half the stroke and an arrowhead past them.
+            const numbers = path.d.match(/-?\d*\.?\d+(?:e[-+]?\d+)?/gi)?.map(Number) ?? [];
+            const reach = (Number(style.strokeWidth) || 1) / 2 + DiagramEditor.MARKER_REACH;
+            for (let i = 0; i + 1 < numbers.length; i += 2) {
+                boxes.push({ left: numbers[i] - reach, top: numbers[i + 1] - reach, right: numbers[i] + reach, bottom: numbers[i + 1] + reach });
+            }
+            if (edge.label) {
+                // As _renderEdges writes it: centred over the middle, 12px text (about 7px a character).
+                const cx = (path.x1 + path.x2) / 2, base = (path.y1 + path.y2) / 2 - 8;
+                const half = String(edge.label).length * 7 / 2;
+                boxes.push({ left: cx - half, top: base - 12, right: cx + half, bottom: base + 4 });
+            }
+        }
+        const bounds = ViewFit.union(boxes);
+        if (!bounds) return null;
+        return { x: bounds.x - margin, y: bounds.y - margin, width: bounds.width + 2 * margin, height: bounds.height + 2 * margin };
+    }
+
+    /** The faint box where an exported picture of the whole drawing ends (drawingBounds). @protected */
+    _renderExportArea(group) {
+        const area = this.drawingBounds();
+        if (!area) return;
+        const rect = this._svg('rect', {
+            id: 'export-area', x: area.x, y: area.y, width: area.width, height: area.height,
+            fill: 'rgba(43, 95, 217, 0.03)', stroke: 'rgba(43, 95, 217, 0.25)', 'stroke-dasharray': '6 4', 'stroke-width': 1,
+            'pointer-events': 'none',
         });
+        group.insertBefore(rect, group.firstChild);
+    }
+
+    /** Show or hide the export area. */
+    setShowExportArea(shown) {
+        this.showExportArea = !!shown;
+        this.render();
     }
 
     /**
@@ -819,8 +944,8 @@ export class DiagramEditor {
      * @protected
      */
     _withPlainDrawing(fn) {
-        const saved = { showGrid: this.showGrid, selectedTemplateId: this.selectedTemplateId, selectedIds: new Set(this.selectedIds), selectedEdgeId: this.selectedEdgeId };
-        Object.assign(this, { showGrid: false, selectedTemplateId: null, selectedIds: new Set(), selectedEdgeId: null });
+        const saved = { showGrid: this.showGrid, showExportArea: this.showExportArea, selectedTemplateId: this.selectedTemplateId, selectedIds: new Set(this.selectedIds), selectedEdgeId: this.selectedEdgeId };
+        Object.assign(this, { showGrid: false, showExportArea: false, selectedTemplateId: null, selectedIds: new Set(), selectedEdgeId: null });
         this.render();
         try {
             return fn();
@@ -843,13 +968,7 @@ export class DiagramEditor {
         if (host?.tagName?.toLowerCase() !== 'svg' || !bounds) return null;
         const viewBox = { x: bounds.x - margin, y: bounds.y - margin, width: bounds.width + 2 * margin, height: bounds.height + 2 * margin };
         return this._withPlainDrawing(() => {
-            const copy = host.cloneNode(true);
-            copy.querySelector('#grid-layer')?.remove();
-            copy.querySelector('#elements')?.removeAttribute('transform');
-            copy.removeAttribute('style');
-            copy.removeAttribute('id');
-            copy.setAttribute('viewBox', `${viewBox.x} ${viewBox.y} ${viewBox.width} ${viewBox.height}`);
-            const svg = prepareSvgMarkup(new (this.document?.defaultView ?? globalThis).XMLSerializer().serializeToString(copy), { width: viewBox.width, height: viewBox.height, background });
+            const svg = this._croppedSvg(host, viewBox, { background });
             const areas = [...this.templates.values()]
                 .filter(t => t.visible !== false && this.templateEmphasis(t) !== 'hidden')
                 .sort((a, b) => (a.zIndex || 0) - (b.zIndex || 0))
@@ -865,6 +984,22 @@ export class DiagramEditor {
     }
 
     /** The drawing's extent in drawing coordinates (ViewFit.union of the visible shapes), or null. */
+    /**
+     * The drawing as standalone SVG markup cut to `viewBox` (drawing units),
+     * unpanned and unzoomed, sized at `scale`. Call it inside _withPlainDrawing.
+     * @protected
+     */
+    _croppedSvg(host, viewBox, { background = '#ffffff', scale = 1 } = {}) {
+        const copy = host.cloneNode(true);
+        copy.querySelector('#grid-layer')?.remove();
+        copy.querySelector('#elements')?.removeAttribute('transform');
+        copy.removeAttribute('style');
+        copy.removeAttribute('id');
+        copy.setAttribute('viewBox', `${viewBox.x} ${viewBox.y} ${viewBox.width} ${viewBox.height}`);
+        const markup = new (this.document?.defaultView ?? globalThis).XMLSerializer().serializeToString(copy);
+        return prepareSvgMarkup(markup, { width: viewBox.width * scale, height: viewBox.height * scale, background });
+    }
+
     contentBounds() {
         return ViewFit.union([...this.templates.values()].filter(t => t.visible !== false)
             .map(t => ({ left: t.left, top: t.top, right: t.right, bottom: t.bottom })));
@@ -968,6 +1103,7 @@ export class DiagramEditor {
         return [
             { label: `Grid: ${this.showGrid ? 'on' : 'off'}`, action: () => { this.showGrid = !this.showGrid; this.render(); } },
             { label: `Grid size: ${this.gridSize}px…`, action: () => this.editGridSize() },
+            { label: `Export area: ${this.showExportArea ? 'shown' : 'hidden'}`, action: () => this.setShowExportArea(!this.showExportArea) },
             ...(this.edgeStyleLevels.length ? [{ separator: true }] : []),
             ...this.edgeStyleLevels.map(level => ({
                 label: `Line style: ${level.label} defaults…`,
@@ -1328,13 +1464,17 @@ export class DiagramEditor {
     /**
      * Geometry of an edge between its templates' outlines, or null if an end is
      * missing. `style.attach === 'sides'` attaches each unpinned end at the middle
-     * of the side facing the other end (or the nearest waypoint); 'polyline'
+     * of the side facing the other end (or the nearest waypoint); 'shortest' (the
+     * default, as Archi draws) runs a straight line straight across where the
+     * shapes overlap, else aims at the other end ('floating'); 'polyline'
      * routing bends around the other shapes.
      */
     _edgePath(edge, style = this.resolveEdgeStyle(edge)) {
         const source = this.getTemplate(edge.sourceId);
         const target = this.getTemplate(edge.targetId);
         if (!source || !target) return null;
+        const across = style.attach === 'shortest' ? this._acrossPath(edge, source, target, style) : null;
+        if (across) return across;
         const box = (t) => ({ w: t.width, h: t.height });
         let sourceSide = edge.sourceSide || 'auto';
         let targetSide = edge.targetSide || 'auto';
@@ -1354,6 +1494,25 @@ export class DiagramEditor {
         );
     }
 
+    /**
+     * The shortest straight line between two shapes that face each other across
+     * a gap (EdgeGeometry.acrossOverlap): straight across the middle of their
+     * overlap, from outline to outline. Null where that does not apply: a line
+     * with bends, a pinned end, other routing, a rotated shape, or no overlap.
+     * @protected
+     */
+    _acrossPath(edge, source, target, style) {
+        if (edge.waypoints.length || (edge.sourceSide || 'auto') !== 'auto' || (edge.targetSide || 'auto') !== 'auto') return null;
+        if ((style.routing ?? 'straight') !== 'straight' || source.rotation || target.rotation) return null;
+        const across = EdgeGeometry.acrossOverlap(source, target);
+        if (!across) return null;
+        const step = across.forward ? 1 : -1;
+        const [a, b] = across.axis === 'v'
+            ? [source.exitPoint(across.at, source.y, 0, step), target.exitPoint(across.at, target.y, 0, -step)]
+            : [source.exitPoint(source.x, across.at, step, 0), target.exitPoint(target.x, across.at, -step, 0)];
+        return { x1: a.x, y1: a.y, x2: b.x, y2: b.y, d: `M${a.x},${a.y} L${b.x},${b.y}` };
+    }
+
     /** Anchors and waypoints in order: the polyline a waypointed edge follows. */
     _edgeVertices(edge, edgePath = this._edgePath(edge)) {
         return [{ x: edgePath.x1, y: edgePath.y1 }, ...edge.waypoints, { x: edgePath.x2, y: edgePath.y2 }];
@@ -1848,12 +2007,9 @@ export class DiagramEditor {
             e.preventDefault();
             this._startMarquee(e, container);
         });
-        // Empty canvas: what canvasMenuItems offers there (a shape's own menu stops the event first).
+        // Empty canvas: canvasContextMenu there (a shape's own menu stops the event first).
         container.addEventListener('contextmenu', (e) => {
-            const at = this._clientToDiagram(e.clientX, e.clientY);
-            const paste = this.canClipboardPaste() ? [{ label: '📋 Paste here', action: () => this.paste({ at }) }] : [];
-            const own = this.canvasMenuItems(at);
-            const items = [...paste, ...(paste.length && own.length ? [{ separator: true }] : []), ...own];
+            const items = this.canvasContextMenu(this._clientToDiagram(e.clientX, e.clientY));
             if (!items.length) return;
             e.preventDefault();
             this._showMenu(e.clientX, e.clientY, items);
@@ -2308,11 +2464,27 @@ export class DiagramEditor {
         return [['kind', 'Kind of shape']];
     }
 
+    /** What a colour key is called (colourKeys' label; a key not listed there, itself). */
+    colourKeyLabel(key) {
+        return this.colourKeys().find(([k]) => k === key)?.[1] ?? key;
+    }
+
+    /** The colours offered for a key's values, in order: the palette's, round again when there are more. */
+    colourDefaults(key, values) {
+        const palette = this.constructor.COLOUR_PALETTE;
+        return values.map((_, i) => palette[i % palette.length]);
+    }
+
     /** A shape's value for a colourKeys key, as text (undefined: it has none, and is left as it is). */
     colourValue(template, key) {
         return key === 'kind' ? this.layoutCategory(template) : undefined;
     }
 
+    /** A line's value for a colourKeys key (undefined: lines are not coloured by it, as here; a subclass's may be). */
+    colourEdgeValue(edge, key) {
+        return undefined;
+    }
+
     /** The values of `key` among the shapes, in order of first appearance, each with its shapes. */
     colourValues(key, templates = [...this.templates.values()].filter(t => t.visible !== false)) {
         const values = new Map();
@@ -2328,19 +2500,26 @@ export class DiagramEditor {
 
     /**
      * Colour the shapes by what `key` says of them (a heat map): each value's
-     * shapes filled with its colour (`colours`, by value; a value left out or
+     * shapes filled with its colour, and lines with a value of their own
+     * (colourEdgeValue) drawn in it (`colours`, by value; a value left out or
      * empty is left as it is), and with `legend` a legend of the colours
      * under the drawing. One undo step; locked shapes are left as they are.
      * @returns {Command|null}
      */
     colourByCommand(key, colours, { legend = false } = {}) {
-        const label = this.colourKeys().find(([k]) => k === key)?.[1] ?? key;
+        const label = this.colourKeyLabel(key);
         const steps = [];
         for (const [value, templates] of this.colourValues(key)) {
             const fillColor = colours[value];
             if (!fillColor) continue;
             for (const t of templates) if (!this.isFixed(t.id) && t.fillColor !== fillColor) steps.push(new SetPropertiesCommand(t, { fillColor }, 'Colour'));
         }
+        // Lines with a value of their own take its colour too (colourEdgeValue).
+        for (const edge of this.getAllEdges()) {
+            if (edge.editable === false) continue;
+            const strokeColor = colours[this.colourEdgeValue(edge, key)];
+            if (strokeColor && edge.strokeColor !== strokeColor) steps.push(new SetStyleCommand(edge, { strokeColor }, 'Colour'));
+        }
         if (legend) {
             const entries = [...this.colourValues(key).keys()].filter(v => colours[v]).map(v => ({ label: v, fillColor: colours[v] }));
             const cmd = entries.length && this.legendCommand(entries, label);
@@ -2366,13 +2545,13 @@ export class DiagramEditor {
     /** The colour of each value of `key` (the palette's by default), then colour by it. @protected */
     askColours(key) {
         const values = [...this.colourValues(key).keys()];
-        const palette = this.constructor.COLOUR_PALETTE;
-        const label = this.colourKeys().find(([k]) => k === key)?.[1] ?? key;
+        const defaults = this.colourDefaults(key, values);
+        const label = this.colourKeyLabel(key);
         if (!values.length) { (globalThis.alert ?? (() => {}))(`No shape here has a value for ${label}.`); return; }
         new FormDialog({
             title: `Colour by ${label}`,
             fields: [
-                ...values.map((value, i) => ({ key: `value-${i}`, label: value, type: 'color', value: palette[i % palette.length] })),
+                ...values.map((value, i) => ({ key: `value-${i}`, label: value, type: 'color', value: defaults[i] })),
                 { key: 'legend', label: 'Add a legend', type: 'checkbox', value: true },
             ],
             submitLabel: 'Colour',
@@ -2412,19 +2591,45 @@ export class DiagramEditor {
     }
 
     /**
-     * The command that adds a legend: a title and a box per entry, in a row
-     * under the drawing (legendPosition). Here, notes; a subclass makes its own
-     * kind of box. Null with no entries.
+     * Where a legend's boxes go, its top-left at `{x, y}`: a frame titled at its
+     * top-left that holds every entry, the entries in rows of up to
+     * `perRow` inside it. Centres and sizes, as boxes are placed.
+     * @returns {{frame: {x, y, width, height}, items: Array<{x, y, width, height}>}}
+     */
+    static legendLayout(count, { x, y }, { perRow = 4, itemWidth = 120, itemHeight = 40, gap = 10, pad = 10, titleHeight = 24 } = {}) {
+        const columns = Math.max(1, Math.min(count, perRow));
+        const rows = Math.max(1, Math.ceil(count / columns));
+        const width = 2 * pad + columns * itemWidth + (columns - 1) * gap;
+        const height = titleHeight + rows * itemHeight + (rows - 1) * gap + pad;
+        const items = Array.from({ length: count }, (_, i) => ({
+            x: x + pad + (i % columns) * (itemWidth + gap) + itemWidth / 2,
+            y: y + titleHeight + Math.floor(i / columns) * (itemHeight + gap) + itemHeight / 2,
+            width: itemWidth, height: itemHeight,
+        }));
+        return { frame: { x: x + width / 2, y: y + height / 2, width, height }, items };
+    }
+
+    /** The legend frame's text: its title, bold at the top-left (as Archi's legends are). */
+    static LEGEND_TITLE_STYLE = Object.freeze({ textAlign: 'left', textPosition: 'top', fontWeight: 'bold' });
+
+    /**
+     * The command that adds a legend under the drawing (legendPosition): a
+     * frame titled `title` with a box per entry inside it, grouped so they move
+     * as one. Here, notes; a subclass makes its own kind of box. Null with no
+     * entries.
      * @param {Array<{label: string, fillColor: string}>} entries
      * @param {string} title
      */
     legendCommand(entries, title) {
         if (!entries.length) return null;
-        const { x, y } = this.legendPosition();
+        const { frame, items } = DiagramEditor.legendLayout(entries.length, this.legendPosition());
         const stamp = Date.now().toString(36);
-        const note = (i, name, fillColor, width = 120) => new NoteTemplate(`legend-${stamp}-${i}`, name, { x: x + width / 2 + i * 130, y: y + 25, width, height: 40, fillColor });
-        const boxes = [note(0, title, '#ffffff'), ...entries.map((e, i) => note(i + 1, e.label, e.fillColor))];
-        return new CompositeCommand(`Add legend: ${title}`, boxes.map(t => new CreateTemplateCommand(this, t)));
+        const note = (i, name, box, more) => new NoteTemplate(`legend-${stamp}-${i}`, name, { ...box, ...more });
+        const boxes = [note(0, title, frame, { fillColor: '#ffffff', ...DiagramEditor.LEGEND_TITLE_STYLE }), ...entries.map((e, i) => note(i + 1, e.label, items[i], { fillColor: e.fillColor }))];
+        return new CompositeCommand(`Add legend: ${title}`, [
+            ...boxes.map(t => new CreateTemplateCommand(this, t)),
+            new GroupCommand(this.arrangement, boxes.map(t => t.id), { name: title }),
+        ]);
     }
 
     // ===== Format painter =====

package/src/charting/Legend.js

@@ -36,6 +36,19 @@ export class Legend {
      * @param {number} drawingWidth - The renderer's width
      * @param {object} options - As the constructor's, without x and y
      */
+    /**
+     * The plot width that leaves room for this legend beside the plot, so it never covers the data:
+     * narrower by as much as the legend would run off the drawing — unless that would leave the plot
+     * under MIN_PLOT_SHARE of its width; then the plot keeps its width and beside() insets the legend.
+     */
+    static plotWidthBeside(box, drawingWidth, options) {
+        const { width } = new Legend({ ...options, x: 0, y: 0 }).size();
+        const over = box.x + box.width + 20 + width - drawingWidth;
+        if (!(drawingWidth > 0) || over <= 0) return box.width;
+        const narrower = box.width - over;
+        return narrower >= box.width * Legend.MIN_PLOT_SHARE ? narrower : box.width;
+    }
+
     static beside(box, drawingWidth, options) {
         const legend = new Legend({ ...options, x: 0, y: 0 });
         const { width } = legend.size();
@@ -99,3 +112,6 @@ export class Legend {
         }
     }
 }
+
+/** The least share of its width a plot keeps when it narrows for a legend beside it. */
+Legend.MIN_PLOT_SHARE = 0.65;