@stocksharp/diagram 0.4.1 → 0.6.0

package/README.md

@@ -154,7 +154,9 @@ missing type. Sites can localize that message through
 `data-diagram-missing-element="Missing: {typeId}"` on the host.
 
 Every text the embedded control shows comes from the host, so a translated page
-carries no English leftovers:
+carries no English leftovers. These attributes are per-instance overrides on top
+of the page's translation bundle (see *Translating the control* below); set them
+when one diagram has to read differently from the rest of the page:
 
 | Host attribute | What it renames |
 |---|---|
@@ -163,7 +165,9 @@ carries no English leftovers:
 | `data-diagram-missing-element="Missing: {typeId}"` | the placeholder for an element the palette lacks |
 
 The same labels are available to custom integrations as the `fullscreenLabels`
-option and `setFullscreenLabels()` on `StockSharpDiagram`.
+option and `setFullscreenLabels()` on `StockSharpDiagram`. With neither the
+attribute nor the option, the wording comes from the bundle, so a page that has
+already been translated needs no per-diagram markup at all.
 
 ### Node actions and errors
 
@@ -188,6 +192,105 @@ 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
+
+Right-click opens the control's own menu, with an Export submenu. It is on by
+default, because right-click suppresses the browser's menu either way and a
+control that takes one away owes one back. It needs no stylesheet: it is styled
+inline over `--ssdiagram-*` custom properties (`--ssdiagram-menu-background`,
+`--ssdiagram-menu-border`, `--ssdiagram-menu-color`, `--ssdiagram-menu-hover`,
+`--ssdiagram-menu-disabled-color`, `--ssdiagram-menu-font`), falling back to the
+`--ssdiagram-control-*` values the fullscreen button uses. Its class names —
+`ssdiagram-context-menu`, `-item`, `-label`, `-arrow`, `-submenu`, `-separator` —
+are stable if you would rather use CSS.
+
+To draw your own instead, pass `showContextMenu: false` (or call
+`setContextMenuEnabled(false)`) and handle `contextMenuRequested`, which is
+emitted either way — and emitted *before* the built-in menu opens, so a handler
+can still switch it off.
+
+`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`, `delete` and `overview` are carried out
+by the control itself. `overview` toggles the corner minimap, and reports its
+current state as `checked` on the command so a menu can tick it rather than offer
+a dead show/hide pair. 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.
+
+#### Translating the control
+
+There is one mechanism, and it is `window.__designerI18n`: an object typed by the
+exported `DesignerI18n`, holding every string the package renders itself — the
+menu, the fullscreen button's tooltip, and the embed failure notes. It is read on
+every lookup, so it can be assigned at any point, before or after the bundle
+loads, and reassigned later to change language. A key that is missing or empty
+falls back to English.
+
+Per-instance settings — the `fullscreenLabels` option, `setFullscreenLabels()`,
+and the `data-diagram-*` attributes above — override the bundle for one diagram.
+Resolution is: explicit setting, then bundle, then the built-in English.
+
+The context menu is rebuilt on every open and needs nothing after a language
+change. The fullscreen button is drawn once, so call `refreshLabels()` to
+re-read the bundle for it.
+
+```ts
+import type { DesignerI18n } from '@stocksharp/diagram';
+
+const labels: DesignerI18n = { cut: 'Вырезать', ctxDelete: 'Удалить', /* … */ };
+(window as unknown as { __designerI18n: DesignerI18n }).__designerI18n = labels;
+```
+
+The key is not always the command name, so here is the whole menu:
+
+| command | key | English |
+|---|---|---|
+| `undo` / `redo` | `undo` / `redo` | Undo / Redo |
+| `cut` / `copy` / `paste` | `cut` / `copy` / `paste` | Cut / Copy / Paste |
+| `open` | `ctxOpen` | Open |
+| `delete` | `ctxDelete` | Delete |
+| *(the submenu)* | `ctxExportAs` | Export as |
+| `exportDocument` | `ctxExportDocument` | Scheme |
+| `exportPng` / `exportSvg` | `ctxExportPng` / `ctxExportSvg` | PNG image / SVG image |
+| `overview` | `ctxOverview` | Overview |
+| `properties` | `properties` | Properties |
+| `help` | `ctxHelp` | Help |
+| *(fullscreen button)* | `fullscreenEnter` / `fullscreenExit` | Enter / Exit fullscreen |
+| *(embed failures)* | `embedErrorLoad` / `embedErrorEmpty` / `embedErrorDraw` | the three notes shown in place of a diagram |
+| *(embed placeholder)* | `embedMissingElement` | the missing-element tooltip |
+
+`ctxDelete` is separate from the solution explorer's `delete` on purpose: that
+one removes a whole strategy, this one the selected nodes and links, and a
+language that declines the object cannot serve both from one key. The same goes
+for `ctxExportAs` against `ctxExport`.
+
 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) {
@@ -1801,6 +1876,26 @@ export class Diagram {
         return added.map((node) => node.id);
     }
     // ---- input ------------------------------------------------------
+    // Ends hover and everything hanging off it: highlight, cursor and the delayed tooltip.
+    clearHover() {
+        if (this.hoverPort !== null)
+            this.emit('portHover', { node: this.hoverPort.node, port: this.hoverPort.port, hovering: false });
+        if (this.hoverNode !== null)
+            this.emit('nodeHover', { node: this.hoverNode, hovering: false });
+        if (this.hoveredLink !== null)
+            this.emit('linkHover', { link: this.hoveredLink, hovering: false });
+        this.hoverPort = null;
+        this.hoverNode = null;
+        this.hoveredLink = null;
+        this.tipTarget = null;
+        this.tipShow = false;
+        if (this.tipTimer !== null) {
+            clearTimeout(this.tipTimer);
+            this.tipTimer = null;
+        }
+        this.canvas.style.cursor = 'default';
+        this.scheduleDraw();
+    }
     cancelLongPress() {
         if (this.lpTimer !== null) {
             clearTimeout(this.lpTimer);
@@ -1839,7 +1934,10 @@ export class Diagram {
         this.relinking = null;
         this.relinkCandidate = null;
         this.linkSnap = null;
-        this.scheduleDraw();
+        // A menu is about to cover this spot, and it opens under a cursor that has not moved --
+        // which fires no boundary event, so nothing else would end the hover. Without this the
+        // tooltip armed by the last pointermove appears 400ms later, through the open menu.
+        this.clearHover();
         this.emit('contextMenu', { x: pageX, y: pageY, link, node, port });
     }
     listen(target, type, listener, options) {
@@ -2217,25 +2315,7 @@ export class Diagram {
             this.emitViewChanged(true);
             this.scheduleDraw();
         }, { passive: false });
-        this.listen(this.canvas, 'pointerleave', () => {
-            if (this.hoverPort !== null)
-                this.emit('portHover', { node: this.hoverPort.node, port: this.hoverPort.port, hovering: false });
-            if (this.hoverNode !== null)
-                this.emit('nodeHover', { node: this.hoverNode, hovering: false });
-            if (this.hoveredLink !== null)
-                this.emit('linkHover', { link: this.hoveredLink, hovering: false });
-            this.hoverPort = null;
-            this.hoverNode = null;
-            this.hoveredLink = null;
-            this.tipTarget = null;
-            this.tipShow = false;
-            if (this.tipTimer !== null) {
-                clearTimeout(this.tipTimer);
-                this.tipTimer = null;
-            }
-            this.canvas.style.cursor = 'default';
-            this.scheduleDraw();
-        });
+        this.listen(this.canvas, 'pointerleave', () => this.clearHover());
         this.listen(this.canvas, 'dblclick', (e) => {
             const [sx, sy] = localXY(e);
             const [wx, wy] = this.toWorld(sx, sy);