@peter.prib/renderengine 0.12.0 → 0.14.0

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/Hierarchy.js

@@ -145,6 +145,34 @@ export class Hierarchy {
         return result;
     }
 
+    /**
+     * Recursive rectangular partition (icicle / flame graph) layout over a node tree.
+     * Partitions `width` proportionally to node value at each level and steps down by `bandHeight` per depth.
+     * @returns {Array<{node: object, x: number, y: number, width: number, height: number, depth: number, isLeaf: boolean, topAncestor: object}>}
+     */
+    static icicleLayout(nodes, x, y, width, bandHeight, depth = 0, topAncestors = null) {
+        const items = (nodes ?? [])
+            .map(node => ({ node, value: Hierarchy.value(node) }))
+            .filter(it => it.value > 0);
+        const total = items.reduce((s, it) => s + it.value, 0) || 1;
+
+        const result = [];
+        let cursorX = x;
+        for (const it of items) {
+            const { node } = it;
+            const spanW = (it.value / total) * width;
+            const isLeaf = !node.children?.length;
+            const topAncestor = topAncestors ? topAncestors.get(node) : node;
+            result.push({ node, x: cursorX, y, width: spanW, height: bandHeight, depth, isLeaf, topAncestor });
+            if (!isLeaf) {
+                const childTopAncestors = new Map(node.children.map(c => [c, topAncestor]));
+                result.push(...Hierarchy.icicleLayout(node.children, cursorX, y + bandHeight, spanW, bandHeight, depth + 1, childTopAncestors));
+            }
+            cursorX += spanW;
+        }
+        return result;
+    }
+
     /**
      * Flat, pre-order list of *visible* rows for an outline view. A branch
      * present in `collapsed` contributes its own row but none of its

package/src/charting/ModelFileFormat.js

@@ -1,5 +1,6 @@
 import { pickFile } from './toolbar/pickFile.js';
 import { downloadBlob } from '../exportImage.js';
+import { FormDialog } from './FormDialog.js';
 
 /**
  * ModelFileFormat — one file format a model is exported to and imported
@@ -100,6 +101,52 @@ export function modelFileMenuItems(formats, {
     return groups.flatMap((group, i) => (i ? [{ separator: true }, ...group] : group));
 }
 
+/**
+ * The part of pasted text that is a model in `format`: the text as it is when
+ * the format recognizes it; else, as an assistant or a page would wrap it, a
+ * fenced block (```json … ```), or the text from its first { (or [) to its
+ * last } (or ]). Null when none is.
+ * @param {ModelFileFormat} format - one that reads text
+ * @param {string} text
+ * @returns {string|null}
+ */
+export function findPayload(format, text) {
+    const candidates = [String(text ?? '').trim()];
+    for (const m of candidates[0].matchAll(/```[\w-]*[ \t]*\r?\n([\s\S]*?)```/g)) candidates.push(m[1].trim());
+    for (const [open, close] of [['{', '}'], ['[', ']']]) {
+        const from = candidates[0].indexOf(open), to = candidates[0].lastIndexOf(close);
+        if (from >= 0 && to > from) candidates.push(candidates[0].slice(from, to + 1));
+    }
+    return candidates.find(c => c && format.recognizes(c)) ?? null;
+}
+
+/**
+ * Import a model from pasted text rather than a file: a dialog with a text
+ * box; what is pasted may be wrapped in other text (findPayload). The new
+ * model goes to `onImport`; text with no model in it is refused in the dialog.
+ * @param {ModelFileFormat} format - one that reads text
+ * @returns {FormDialog}
+ */
+export function askPasteImport(format, { onImport, document: doc = globalThis.document } = {}) {
+    let model = null;
+    const dialog = new FormDialog({
+        title: `Paste ${format.label}`,
+        description: `Paste the ${format.label} text: a file's contents, or an answer or page that has it in it (in a \`\`\` block, say).`,
+        fields: [{ key: 'text', label: 'Text', type: 'textarea', rows: 14, value: '' }],
+        submitLabel: 'Import',
+        idPrefix: 'paste-import-',
+        document: doc,
+        validate: ({ text }) => {
+            const payload = findPayload(format, text);
+            if (!payload) return `No ${format.label} found in what is pasted`;
+            try { model = format.import(payload); return null; } catch (err) { return `It could not be read: ${err.message}`; }
+        },
+        onApply: () => onImport(model),
+    });
+    dialog.open();
+    return dialog;
+}
+
 /**
  * Ask for a file and import it in `format`; resolves to the new model, or
  * null when no file was chosen or it could not be read (reported).