@stocksharp/diagram 0.4.1 → 0.5.0

package/README.md

@@ -188,6 +188,48 @@ Socket input is reported separately through `portClicked`, with
 never starts a wire. `contextMenuRequested` also includes the exact port when
 the menu was opened over a socket.
 
+### The context menu
+
+The control has no menu widget: right-click suppresses the browser's own menu
+and emits `contextMenuRequested` with page coordinates, whatever was hit, and
+the menu contents already resolved. Draw it however the host draws menus, then
+send the choice back through `executeContextCommand()`.
+
+`commands` is a tree in display order. An entry with a `group` is a submenu;
+anything else is a command. `enabled` is computed for both — a submenu is off
+when every item inside it is:
+
+```ts
+diagram.on('contextMenuRequested', ({ x, y, commands }) => {
+  showMenu(x, y, commands.map((item) => 'group' in item
+    ? { label: t(item.group), enabled: item.enabled, items: item.commands }
+    : { label: t(item.command), enabled: item.enabled }));
+});
+
+menu.on('pick', (command) => diagram.executeContextCommand(command));
+```
+
+`undo`, `redo`, `cut`, `copy`, `paste` and `delete` are carried out by the
+control itself. The rest are requests it cannot answer alone: `open`,
+`properties` and `help` raise `nodeOpen` / `nodeProperties` / `nodeHelp`, and
+the `export` submenu raises `exportRequested` with the chosen format. Nothing
+is produced until the host acts on it — only the host knows where the result
+should go, and with which options:
+
+```ts
+diagram.on('exportRequested', ({ format }) => {
+  if (format === 'document') return download('strategy.json', diagram.saveDocument());
+  const options = { scope: 'content', padding: 40 };
+  if (format === 'svg') return download('strategy.svg', diagram.takeSvg(options));
+  diagram.takeScreenshot(options).toBlob((blob) => download('strategy.png', blob));
+});
+```
+
+Export is offered whenever the diagram has a node, including in read-only mode,
+because it only reads. Menu labels come from the host's i18n bundle
+(`ctxExportAs`, `ctxExportDocument`, `ctxExportPng`, `ctxExportSvg`, and the
+keys named after the other commands).
+
 Runtime failures flash the node border before leaving it red. Errors found
 while loading a scheme use a red background. Hovering either state shows the
 full error text in a tooltip:

package/dist/esm/canvas-renderer.js

@@ -1,3 +1,4 @@
+import { SvgSurface } from './svg-surface.js';
 // Internal dependency-free canvas renderer used by StockSharpDiagram.
 //
 // Dependency-free, pure 2D canvas. Demonstrates the hard parts: typed
@@ -1100,6 +1101,65 @@ export class Diagram {
             copyContext.drawImage(this.canvas, 0, 0);
             return copy;
         }
+        const layout = this.exportLayout(scope, options);
+        const { pixelRatio, exportScale, padding, bounds, width, height, pixelWidth, pixelHeight } = layout;
+        const output = document.createElement('canvas');
+        output.width = pixelWidth;
+        output.height = pixelHeight;
+        output.style.width = `${width}px`;
+        output.style.height = `${height}px`;
+        const outputContext = output.getContext('2d');
+        if (outputContext === null)
+            throw new Error('ssdiagram: screenshot 2d context unavailable');
+        const previous = {
+            ctx: this.ctx,
+            width: this.width,
+            height: this.height,
+            dpr: this.dpr,
+            scale: this.scale,
+            offX: this.offX,
+            offY: this.offY,
+            overviewVisible: this.overviewVisible,
+            background: this.opts.background,
+        };
+        try {
+            this.ctx = outputContext;
+            this.width = width;
+            this.height = height;
+            this.dpr = pixelRatio;
+            this.scale = exportScale;
+            this.offX = scope === 'content' && bounds !== null ? padding - bounds.minX * exportScale : previous.offX;
+            this.offY = scope === 'content' && bounds !== null ? padding - bounds.minY * exportScale : previous.offY;
+            this.overviewVisible = options.includeOverview ?? (scope === 'viewport' && previous.overviewVisible);
+            if (options.background !== undefined)
+                this.opts.background = options.background;
+            outputContext.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0);
+            this.draw({
+                grid: options.includeGrid ?? true,
+                overview: this.overviewVisible,
+                selection: options.includeSelection ?? scope === 'viewport',
+                runtime: options.includeRuntimeState ?? true,
+                transient: false,
+            });
+        }
+        finally {
+            this.ctx = previous.ctx;
+            this.width = previous.width;
+            this.height = previous.height;
+            this.dpr = previous.dpr;
+            this.scale = previous.scale;
+            this.offX = previous.offX;
+            this.offY = previous.offY;
+            this.overviewVisible = previous.overviewVisible;
+            this.opts.background = previous.background;
+        }
+        return output;
+    }
+    // Everything an export needs to know about size and placement, for either output. Shared on
+    // purpose: a raster and a vector export of the same scope must frame the picture identically,
+    // and two copies of this arithmetic would eventually disagree about padding or where the origin
+    // sits. A block comment here would be lifted onto the next public member in the .d.ts.
+    exportLayout(scope, options) {
         const pixelRatio = this.positiveScreenshotNumber(options.pixelRatio ?? this.dpr, 'pixelRatio');
         const exportScale = scope === 'content'
             ? this.positiveScreenshotNumber(options.scale ?? 1, 'scale')
@@ -1119,14 +1179,33 @@ export class Diagram {
         if (pixelWidth > 16384 || pixelHeight > 16384 || pixelWidth * pixelHeight > 268435456) {
             throw new RangeError(`ssdiagram: screenshot is too large (${pixelWidth}x${pixelHeight})`);
         }
-        const output = document.createElement('canvas');
-        output.width = pixelWidth;
-        output.height = pixelHeight;
-        output.style.width = `${width}px`;
-        output.style.height = `${height}px`;
-        const outputContext = output.getContext('2d');
-        if (outputContext === null)
-            throw new Error('ssdiagram: screenshot 2d context unavailable');
+        return { pixelRatio, exportScale, padding, bounds, width, height, pixelWidth, pixelHeight };
+    }
+    /**
+     * The same picture takeScreenshot produces, as SVG.
+     *
+     * It is the renderer that draws it -- the surface underneath simply records instead of paints --
+     * so the vector output cannot drift from what the screen and the raster export show. Text keeps
+     * the on-screen metrics by measuring through a real 2D context.
+     *
+     * Scale and pixelRatio still frame the picture (they decide the viewBox), but nothing is
+     * resampled: the result is resolution-independent, which is the point of asking for it.
+     */
+    takeSvg(options = {}) {
+        if (this.destroyed)
+            throw new Error('ssdiagram: cannot export a destroyed diagram');
+        const scope = options.scope ?? 'viewport';
+        if (scope !== 'viewport' && scope !== 'content') {
+            throw new RangeError(`ssdiagram: unsupported screenshot scope "${String(scope)}"`);
+        }
+        const { exportScale, padding, bounds, width, height } = this.exportLayout(scope, options);
+        const metrics = this.canvas.getContext('2d');
+        const surface = new SvgSurface({
+            width,
+            height,
+            background: options.background ?? this.opts.background ?? '#1b1b1f',
+            metrics: metrics ?? undefined,
+        });
         const previous = {
             ctx: this.ctx,
             width: this.width,
@@ -1136,20 +1215,17 @@ export class Diagram {
             offX: this.offX,
             offY: this.offY,
             overviewVisible: this.overviewVisible,
-            background: this.opts.background,
         };
         try {
-            this.ctx = outputContext;
+            this.ctx = surface;
             this.width = width;
             this.height = height;
-            this.dpr = pixelRatio;
+            // 1: an SVG has no device pixels to multiply by, and the viewBox carries the size.
+            this.dpr = 1;
             this.scale = exportScale;
             this.offX = scope === 'content' && bounds !== null ? padding - bounds.minX * exportScale : previous.offX;
             this.offY = scope === 'content' && bounds !== null ? padding - bounds.minY * exportScale : previous.offY;
             this.overviewVisible = options.includeOverview ?? (scope === 'viewport' && previous.overviewVisible);
-            if (options.background !== undefined)
-                this.opts.background = options.background;
-            outputContext.setTransform(pixelRatio, 0, 0, pixelRatio, 0, 0);
             this.draw({
                 grid: options.includeGrid ?? true,
                 overview: this.overviewVisible,
@@ -1167,9 +1243,8 @@ export class Diagram {
             this.offX = previous.offX;
             this.offY = previous.offY;
             this.overviewVisible = previous.overviewVisible;
-            this.opts.background = previous.background;
         }
-        return output;
+        return surface.toSvg();
     }
     positiveScreenshotNumber(value, name) {
         if (!Number.isFinite(value) || value <= 0) {