@stocksharp/diagram 0.4.0 → 0.5.0

package/src/diagram/stocksharp-diagram.ts

@@ -27,11 +27,15 @@ import {
     type PortModel,
 } from '../canvas-renderer.js';
 import { StockSharpCatalog } from './catalog.js';
+import { ContextMenuView } from './context-menu.js';
 import { EventEmitter } from './event-emitter.js';
 import type {
     DiagramEvents,
     DiagramClipboard,
     ContextCommand,
+    ContextCommandGroup,
+    ContextCommandState,
+    ContextMenuItemState,
     DiagramLoadOptions,
     DiagramFullscreenLabels,
     DiagramGridSettings,
@@ -58,8 +62,28 @@ interface ContextActionContext {
     selection: DiagramSelection;
     nodes: DiagramNode[];
     links: Link[];
+    /** The whole diagram, not the selection: export offers the picture as a whole. */
+    document: DiagramDocument;
 }
 
+type ContextMenuEntry = ContextCommand | { group: ContextCommandGroup; commands: readonly ContextCommand[] };
+
+/**
+ * Menu order, and the only place the nesting is declared. The registry is flat because
+ * every command must be runnable by id, so the shape of the menu cannot live there.
+ * A command missing from this list would be executable and never offered; the test suite
+ * walks both and refuses to let the two drift.
+ */
+const CONTEXT_MENU: readonly ContextMenuEntry[] = [
+    'undo', 'redo',
+    'cut', 'copy', 'paste',
+    'open',
+    'delete',
+    { group: 'export', commands: ['exportDocument', 'exportPng', 'exportSvg'] },
+    'properties',
+    'help',
+];
+
 export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
     private readonly div: HTMLElement;
     private readonly catalog: StockSharpCatalog;
@@ -79,6 +103,7 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
     private fullscreenButtonVisible = true;
     private fullscreenLabels: DiagramFullscreenLabels = { enter: 'Enter fullscreen', exit: 'Exit fullscreen' };
     private readonly contextActions = new DiagramActionRegistry<ContextCommand, ContextActionContext>();
+    private contextMenu: ContextMenuView | null = null;
 
     constructor(options: DiagramOptions) {
         super();
@@ -98,6 +123,7 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         this.prepareFullscreenButtonHost();
         this.fullscreenButton = this.createFullscreenButton();
         this.updateFullscreenButton();
+        this.setContextMenuEnabled(options.showContextMenu ?? true);
         this.registerContextActions();
         this.bindCanvasEvents();
         this.disposables.push(this.catalog.on('portTypesChanged', () => this.applySocketTheme()));
@@ -372,6 +398,11 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         return this.canvas.takeScreenshot(options);
     }
 
+    /** The same picture as takeScreenshot, as an SVG document. */
+    takeSvg(options: DiagramScreenshotOptions = {}): string {
+        return this.canvas.takeSvg(options);
+    }
+
     getSelection(): DiagramSnapshot<DiagramSelection> {
         return this.canvas.getSelection();
     }
@@ -509,11 +540,42 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         return fallback !== null && this.canvas.pasteDocument(fallback).length > 0;
     }
 
-    getContextCommands(): Array<{ command: ContextCommand; enabled: boolean }> {
-        return this.contextActions.states(this.contextActionContext()).map(({ id, enabled }) => ({
-            command: id,
-            enabled,
-        }));
+    /**
+     * Turns the built-in menu on or off. Off leaves `contextMenuRequested` untouched, so a
+     * host that draws its own is only trading one menu for another, never losing the event.
+     */
+    setContextMenuEnabled(enabled: boolean): void {
+        if (enabled === (this.contextMenu !== null)) return;
+        if (!enabled) {
+            this.contextMenu?.destroy();
+            this.contextMenu = null;
+            return;
+        }
+        this.contextMenu = new ContextMenuView({
+            container: this.div,
+            // Through the public entry point, so the built-in menu is exactly as privileged
+            // as a host's own -- same guards, same contextCommand event.
+            execute: (command) => { this.executeContextCommand(command); },
+        });
+    }
+
+    isContextMenuEnabled(): boolean {
+        return this.contextMenu !== null;
+    }
+
+    getContextCommands(): ContextMenuItemState[] {
+        const context = this.contextActionContext();
+        const state = (command: ContextCommand): ContextCommandState => ({
+            command,
+            enabled: this.contextActions.canExecute(command, context),
+        });
+        return CONTEXT_MENU.map((entry) => {
+            if (typeof entry === 'string') return state(entry);
+            const commands = entry.commands.map(state);
+            // A submenu that opens onto nothing but greyed items is itself dead, and
+            // saying so here spares every host from working the same thing out again.
+            return { group: entry.group, enabled: commands.some(({ enabled }) => enabled), commands };
+        });
     }
 
     executeContextCommand(command: ContextCommand): boolean {
@@ -588,6 +650,8 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
     destroy(): void {
         if (this.destroyed) return;
         this.destroyed = true;
+        this.contextMenu?.destroy();
+        this.contextMenu = null;
         for (const dispose of this.disposables.splice(0).reverse()) dispose();
         this.canvas.destroy();
     }
@@ -752,6 +816,7 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
             }),
             this.canvas.on('undoStackChanged', (state) => this.emit('undoStackChanged', state)),
             this.canvas.on('contextMenu', ({ x, y, node, link, port }) => {
+                const commands = this.getContextCommands();
                 this.emit('contextMenuRequested', {
                     x,
                     y,
@@ -759,8 +824,11 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
                     link: link === null ? null : this.fromCanvasLink(link),
                     port: port === null ? null : this.fromCanvasPort(port.port),
                     portDirection: port?.port.direction ?? null,
-                    commands: this.getContextCommands(),
+                    commands,
                 });
+                // After the event, so a host that draws its own menu has already been told
+                // and can have switched this one off in the handler.
+                this.contextMenu?.show(x, y, commands);
             }),
         );
     }
@@ -800,6 +868,24 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
                     && (selection.nodeIds.length > 0 || selection.linkIds.length > 0),
                 execute: () => this.canvas.deleteSelection(),
             },
+            // Export asks rather than does. Where the result goes -- a download, an upload,
+            // a clipboard, a print preview -- is the host's decision, and so is which options
+            // to render with, so the control reports the request and stops there.
+            // Availability follows the diagram, not the selection: all three export the whole
+            // picture, and an empty diagram has none to give. They stay on in read-only mode,
+            // which forbids changing the diagram, not looking at it.
+            exportDocument: {
+                canExecute: ({ document }) => document.nodes.length > 0,
+                execute: () => this.emit('exportRequested', { format: 'document' }),
+            },
+            exportPng: {
+                canExecute: ({ document }) => document.nodes.length > 0,
+                execute: () => this.emit('exportRequested', { format: 'png' }),
+            },
+            exportSvg: {
+                canExecute: ({ document }) => document.nodes.length > 0,
+                execute: () => this.emit('exportRequested', { format: 'svg' }),
+            },
             properties: {
                 canExecute: ({ nodes }) => nodes.length > 0,
                 execute: ({ nodes }) => this.emit('nodeProperties', { nodes }),
@@ -818,6 +904,7 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         const linkIds = new Set(selection.linkIds);
         return {
             selection,
+            document,
             nodes: document.nodes
                 .filter((node) => nodeIds.has(node.id))
                 .map((node) => this.fromCanvasInit(node)),

package/src/draw-surface.ts

@@ -0,0 +1,61 @@
+/**
+ * The drawing operations the renderer actually uses, and nothing more.
+ *
+ * The renderer paints straight onto a 2D context, which means the picture only ever exists as
+ * pixels: a screenshot can be taken, but there is no vector form to export. Naming the surface it
+ * draws against is what makes a second backend possible without a second renderer -- one that emits
+ * SVG. Two renderers would be two truths about how a node looks, and they would drift.
+ *
+ * The member list is deliberately a subset of CanvasRenderingContext2D with identical names and
+ * semantics. TypeScript matches types structurally, so the browser's own context satisfies this
+ * without a wrapper: the on-screen path keeps calling the real thing directly, at no cost and with
+ * no behaviour to re-verify.
+ */
+export interface DrawSurface {
+    // ----- state -----
+    fillStyle: string | CanvasGradient | CanvasPattern;
+    strokeStyle: string | CanvasGradient | CanvasPattern;
+    lineWidth: number;
+    lineJoin: CanvasLineJoin;
+    lineCap: CanvasLineCap;
+    globalAlpha: number;
+    font: string;
+    textAlign: CanvasTextAlign;
+    textBaseline: CanvasTextBaseline;
+
+    save(): void;
+    restore(): void;
+    setLineDash(segments: readonly number[]): void;
+
+    // ----- transform -----
+    setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void;
+    translate(x: number, y: number): void;
+    rotate(angle: number): void;
+
+    // ----- paths -----
+    beginPath(): void;
+    closePath(): void;
+    moveTo(x: number, y: number): void;
+    lineTo(x: number, y: number): void;
+    arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, counterclockwise?: boolean): void;
+    arcTo(x1: number, y1: number, x2: number, y2: number, radius: number): void;
+    fill(): void;
+    stroke(): void;
+    clip(): void;
+
+    // ----- rectangles -----
+    clearRect(x: number, y: number, w: number, h: number): void;
+    fillRect(x: number, y: number, w: number, h: number): void;
+    strokeRect(x: number, y: number, w: number, h: number): void;
+
+    // ----- text -----
+    fillText(text: string, x: number, y: number, maxWidth?: number): void;
+    /**
+     * Only `width` is read by the renderer. An SVG backend has no font engine of its own and
+     * borrows a real 2D context for this, so text lands in exactly the same place in both outputs.
+     */
+    measureText(text: string): { width: number };
+
+    // ----- images -----
+    drawImage(image: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
+}

package/src/i18n.ts

@@ -95,6 +95,13 @@ export interface DesignerI18n {
     copy?: string;
     paste?: string;
     ctxOpen?: string;
+    // Submenu title, and deliberately not `ctxExport` -- that one is the solution
+    // explorer's "export this strategy", a different action that a host may well word
+    // differently. Reads as its own item too: "Export as > SVG image".
+    ctxExportAs?: string;
+    ctxExportDocument?: string;
+    ctxExportPng?: string;
+    ctxExportSvg?: string;
     properties?: string;
     ctxHelp?: string;
     collapse?: string;

package/src/index.ts

@@ -32,6 +32,9 @@ export type {
     DiagramDocumentPort,
     DiagramDocumentPortInput,
     DiagramDocumentVersion,
+    DiagramDocumentZone,
+    DiagramDocumentZoneInput,
+    DiagramLinkStyle,
     DiagramParameterSchema,
     JsonObject,
     JsonPrimitive,
@@ -84,9 +87,14 @@ export {
 
 export type {
     ContextCommand,
+    ContextCommandGroup,
+    ContextCommandGroupState,
     ContextCommandPayload,
     ContextCommandState,
+    ContextMenuItemState,
     ContextMenuRequestedPayload,
+    ExportFormat,
+    ExportRequestedPayload,
     DiagramEvents,
     DiagramClipboard,
     DiagramGridSettings,