@peter.prib/renderengine 0.12.0 → 0.13.0

package/documentation/REFERENCE.md

@@ -1057,7 +1057,10 @@ types — see `ARCHITECTURE.md`):
 
   **In the workbench:** `DataModelPart` (type `data-model`, `RenderEngineWorkspace.DataModelPart`) shows one
   model: File ▸ Open…, Save, Save As… (Ctrl+O, Ctrl+S; `part.file`, the `ModelFile` editors use, • while changed,
-  asking before the page is left with changes unsaved), and hosted by a `ModelsPart` (`editorType: 'data-model'`)
+  asking before the page is left with changes unsaved), File ▸ **Import from pasted text (.datamodel.json)…** (a model from
+  pasted text rather than a file: a file's contents, or an assistant's answer or a page with the JSON in a ``` block
+  or between other words, found by `findPayload(format, text)`; `askPasteImport(format, { onImport })`; every
+  `ModelHosted` part offers it for its text formats, `part.pasteItems()`; it opens as Open… does), and hosted by a `ModelsPart` (`editorType: 'data-model'`)
   New ▸ (New model, From base: …), Duplicate model, Close model and This browser ▸ (with `keep`: kept in this browser
   as it changes, reopened next time, backed up to a folder chosen once, as the modeller's models are); Edit ▸ Undo
   and Redo; Tools ▸ Compare with and Merge from (the other open models and the bases; a merge is one undo step); Model ▸ New / Edit / Delete perspective and context (those dialogs), Perspective and Context selects (when
@@ -1081,6 +1084,13 @@ this to `line`/`area`/`stackedBar`/etc. is the same three-line change: call
 `this._drawYAxisTicks(x, y, width, height, rawMax)` before drawing marks, and scale against its
 return value instead of the raw max — not done yet for the rest, tracked as a follow-up.
 
+**Negative values.** `bar` and `groupedBar` (and so `pivotChart`, which charts through the grouped
+bar) take in the smallest value as well as the largest: when one is negative the axis goes below zero
+on one common step (`Axis.niceRange(min, max)`, drawn by `Axis.drawYRange`), a zero line is drawn
+across the plot where it crosses, and a negative bar hangs down from it, its value written below it.
+Money signed both ways (income positive, spending negative) charts as it is, and a total over both is
+the net. Without a negative value nothing changes: the axis starts at 0 at the bottom.
+
 ### Choosing a chart for result rows — `ChartChooser`
 
 `new ChartChooser().choose(rows, columns?, { complete? })` says which chart types fit a set of result rows (a query
@@ -1138,6 +1148,7 @@ const view = new RenderEngine(container, { rendererType: 'svg' }).resultView(row
     pageSize: 50,
     menus: { row: ({ row }) => [{ label: 'Open order', action: () => open(row.id) }] },
     highlight: (row) => row.id === selectedId,   // rows drawn highlighted: the host's selection
+    format: { Revenue: new Intl.NumberFormat('en-AU', { style: 'currency', currency: 'AUD' }) },
 });
 ```
 
@@ -1159,6 +1170,12 @@ or `chartHeight`, 360); pass `fitHeight: false` to size it yourself. A host adds
 any menu with `menus: { cell, row, column, table }`, each `(context) → PopupMenu items`, shown after
 a separator.
 
+**Number format.** `format` says how numbers show: a function (number → text) or an
+`Intl.NumberFormat` for every number, or an object naming either per column, where a column it does
+not name stays plain (116028; a fraction to at most 4 decimals). Only the cells' text changes: sorting
+and filtering use the values, and every copy (the table, a column, a row, a value) keeps the raw
+numbers, so a pasted copy still adds up. `pivotView` takes the same `format`, per measure.
+
 Interaction needs the SVG renderer (its shapes take clicks); on canvas the same table is drawn
 without it. `TableView` (`src/charting/table/TableView.js`) holds all of the state and builds every
 menu as data, so it can be driven and tested without a DOM; `TableViewChart` draws it.
@@ -1211,6 +1228,10 @@ grid, as `resultView`'s does. `PivotView` (`src/charting/pivot/`) holds all the
 menus as data, so it can be tested without a DOM; `PivotGridChart` draws it, with the interactive
 table's click handling (SVG for clicks; canvas draws the grid without them).
 
+`format` (as `resultView`'s, per measure: `{ Revenue: new Intl.NumberFormat(…) }`, or one for every
+measure) writes the cells, the totals and the traffic lights' cut-offs ("Revenue ≥ $3,000.00"); the
+grid copy keeps the raw numbers.
+
 #### Saved views
 
 A saved view is plain data: the layout (`view.layout()`) and how the grid shows it
@@ -2098,8 +2119,32 @@ colour by, then a colour for each of its values (a soft palette by default, `Dia
 colour" leaves a value's shapes as they are), and whether to add a legend. Each shape takes its value's colour as
 its own fill, so the colours are kept like any other (an Archi file included), and one undo puts them back. The
 template editor colours by the kind of shape; the ArchiMate canvas by **Layer**, **Type**, **Specialization** or any
-**property** its elements have (notes and pictures have no value and stay as they are). A legend is a title and a
-box per value in its colour, in a row under the drawing (notes; on a canvas, stickies). **Add legend of the kinds
+**property** its elements have (notes and pictures have no value and stay as they are), and two more:
+
+- **Change (create, update, delete)**, offered when the model has a deliverable or work package: each element related
+  to one (either way round) takes the change the relationship's name says, or, when the relationship has no name, the
+  deliverable's or work package's name. Synonyms count, in any form: delete, remove, retire, decommission, drop,
+  sunset, phase out, shut down, …; create, add, new, introduce, build, implement, set up, launch, …; update, change,
+  modify, upgrade, enhance, migrate, replace, … (`CHANGE_WORDS`, whole words only). Where an element is given more
+  than one, the one with most consequence wins: delete, then create, then update. The colours offered are
+  **Create** yellow #FDD835, **Update** blue #1E88E5 and **Delete** magenta #D81B60 (`CHANGE_COLOURS`), each still
+  changeable (`changeAction(text)`, `elementChange(model, elementId)`). The lines are coloured too: each relationship
+  to a deliverable or work package is drawn in the colour of the change it says itself (`relationshipChange(model,
+  rel)`), so an element changed two ways shows both on its lines; other lines keep their colour. Lines only drawn
+  (derived ones) are left as they are (`editor.colourEdgeValue(edge, key)`, which a subclass overrides to colour
+  lines by a key).
+- **A formula over properties…**, offered when elements have properties: a number from each element's numeric
+  properties, in the formula language `colorCol` uses (`kernelExpr.js`: arithmetic, comparisons, `a ? b : c`,
+  maths functions), each property by its name with anything but letters, digits and _ made _ ("Risk score" is
+  `Risk_score`), e.g. `Cost * Risk_score` or `Cost > 10000 ? 1 : 0`. A formula naming no property is refused
+  with what the names are. An element without a number for a property the formula uses is left as it is. Up to
+  eight different results are each a value; more are put in five equal bands, smallest first (a band with nothing in
+  it left out), and the colours offered run light to dark (`expressionValues`, `resultBands`,
+  `sequentialColours`; the key is `expression:<formula>`).
+
+A legend is a box under the
+drawing, titled at its top-left, holding a box per value in its colour (in rows of up to four,
+`DiagramEditor.legendLayout`), all grouped so they move as one (notes; on a canvas, stickies). **Add legend of the kinds
 shown** adds one for the kinds of shape (ArchiMate: the element types) in the colour of each's first shape. A
 locked shape keeps its colour. `colourKeys()`, `colourValue(template, key)`, `colourValues(key)`,
 `colourByCommand(key, colours, { legend })`, `kindLegendEntries()` and `legendCommand(entries, title)`, which a
@@ -2224,7 +2269,23 @@ label shown, in the same box (or none), with the same lines drawn (each relation
 thing at the other end), as one undo step with its lines (`view.repeatedBoxes()`, `editor.removeRepeatedBoxes()`).
 The first box stays; a box holding others is never taken off. The **File** menu (`EditorPart`'s, and the ArchiMate editor's) exports the current view
 as an image: PNG, SVG or a copy to the clipboard (`editor.exportImage('png' | 'svg' | 'copy')`, without the grid
-or selection; the ArchiMate editor's is off with `features.exportImage: false`). **Generate View For This**, on
+or selection; the ArchiMate editor's is off with `features.exportImage: false`), and so does a right-click on empty
+canvas (**Export image**, `editor.canvasContextMenu(at)`). By default a picture takes in **the whole drawing**,
+wherever the view is scrolled: every shape and line, line labels and arrowheads included, with 20px clear all round
+so nothing touches the edge (`editor.drawingBounds({ margin })`), at **100%**. **Export image…** asks the format,
+the area (the whole drawing, or only what is in sight) and the scale in percent, and the quick items use its last
+choice (`editor.exportOptions`, `setExportOptions({ area, scale })`; `exportImage(format, { area, scale })`).
+**⚙ Settings ▸ Export area** shows where the whole drawing's picture ends as a faint dashed box, never itself
+exported (`editor.showExportArea`). An SVG cropped to a viewBox keeps a white background over all of it.
+
+**🗑 Delete from model…**, on an element's menu in the tree and on its box's menu in the diagram (the elements
+selected, when it is one of them), takes it out of the model rather than off one view, as Archi's "Delete from
+Model". First a dialog says where it is used: each view it is on (with how many boxes), and each relationship that
+goes too (those ending on it, and those ending on such a relationship); **Delete from model** goes ahead. Every
+box and line of them goes from every view, with any view's own connection to one of its boxes, as one undo step
+that puts it all back, ids and all (`model.usage(elementIds)`, `model.deleteFromModelCommand(elementIds)`,
+`editor.askDeleteFromModel(ids)` / `deleteFromModel(ids)`, `deleteFromModelMessage(model, ids)`;
+`elementMenuItems` offers it when the host gives `deleteFromModel`). **Generate View For This**, on
 an element's menu in the diagram or the tree, makes a view of the element with everything related to it
 around it and every relationship between them (`model.generateView(elementIds, { name, related })`, Archi's
 "Generate View For").
@@ -2587,7 +2648,7 @@ single list of cascading properties:
 | Key | Values (default first) |
 |---|---|
 | `routing` | `straight`, `orthogonal`, `curved`, `polyline` (bends around other shapes) |
-| `attach` | `floating` (outline, aimed at the other end), `sides` (middle of the facing side) |
+| `attach` | `shortest` (the default, as Archi draws: where two shapes face each other across a gap with their widths or heights overlapping, a straight line straight across the middle of the overlap, outline to outline; otherwise as `floating`), `floating` (outline, aimed at the other end), `sides` (middle of the facing side). `shortest` leaves a line with bends, a pinned end, routing other than straight, or a rotated shape as `floating` draws it |
 | `lineStyle` | `solid`, `dashed`, `dotted` (same dash patterns as `GraphDiagram`, via `LINE_STYLE_DASH`) |
 | `strokeColor`, `strokeWidth` | `#666666`, `2` |
 | `startMarker`, `endMarker` | `none`, or an `EdgeMarker` key |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peter.prib/renderengine",
-  "version": "0.12.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",

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/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 =====