@stocksharp/diagram 0.4.1 → 0.6.0

package/src/diagram/stocksharp-diagram.ts

@@ -27,11 +27,16 @@ import {
     type PortModel,
 } from '../canvas-renderer.js';
 import { StockSharpCatalog } from './catalog.js';
+import { ContextMenuView } from './context-menu.js';
+import { t } from '../i18n.js';
 import { EventEmitter } from './event-emitter.js';
 import type {
     DiagramEvents,
     DiagramClipboard,
     ContextCommand,
+    ContextCommandGroup,
+    ContextCommandState,
+    ContextMenuItemState,
     DiagramLoadOptions,
     DiagramFullscreenLabels,
     DiagramGridSettings,
@@ -58,8 +63,34 @@ 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'] },
+    'overview',
+    'properties',
+    'help',
+];
+
+/** Commands that toggle rather than do, so the menu reports their state instead of just enabling them. */
+const CONTEXT_CHECKED: Partial<Record<ContextCommand, (diagram: StockSharpDiagram) => boolean>> = {
+    overview: (diagram) => diagram.getViewState().overviewVisible,
+};
+
 export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
     private readonly div: HTMLElement;
     private readonly catalog: StockSharpCatalog;
@@ -77,8 +108,12 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
     private destroyed = false;
     private fullscreen = false;
     private fullscreenButtonVisible = true;
-    private fullscreenLabels: DiagramFullscreenLabels = { enter: 'Enter fullscreen', exit: 'Exit fullscreen' };
+    // null means the host never named the button, so its wording comes from the shared bundle.
+    // Keeping the two apart is what lets an explicit label win while an untouched control still
+    // follows the page's language instead of being stuck in English.
+    private fullscreenLabels: DiagramFullscreenLabels | null = null;
     private readonly contextActions = new DiagramActionRegistry<ContextCommand, ContextActionContext>();
+    private contextMenu: ContextMenuView | null = null;
 
     constructor(options: DiagramOptions) {
         super();
@@ -94,10 +129,11 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
             gridSize: options.gridSize,
         });
         this.fullscreenButtonVisible = options.showFullscreenButton ?? true;
-        this.fullscreenLabels = options.fullscreenLabels ?? this.fullscreenLabels;
+        this.fullscreenLabels = options.fullscreenLabels ?? null;
         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 +408,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();
     }
@@ -412,8 +453,24 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         this.updateFullscreenButton();
     }
 
+    /**
+     * Re-reads the shared bundle for text the control renders itself. Call it after changing
+     * the page language: the context menu is rebuilt on every open and needs nothing, but the
+     * fullscreen button is drawn once and would otherwise keep the old wording.
+     */
+    refreshLabels(): void {
+        this.updateFullscreenButton();
+    }
+
     getFullscreenLabels(): DiagramSnapshot<DiagramFullscreenLabels> {
-        return { ...this.fullscreenLabels };
+        return { ...this.resolveFullscreenLabels() };
+    }
+
+    private resolveFullscreenLabels(): DiagramFullscreenLabels {
+        return this.fullscreenLabels ?? {
+            enter: t('fullscreenEnter', 'Enter fullscreen'),
+            exit: t('fullscreenExit', 'Exit fullscreen'),
+        };
     }
 
     /** Updates only the control's state after the host changed its own layout. */
@@ -509,11 +566,46 @@ 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 => {
+            const checked = CONTEXT_CHECKED[command];
+            return {
+                command,
+                enabled: this.contextActions.canExecute(command, context),
+                ...(checked === undefined ? {} : { checked: checked(this) }),
+            };
+        };
+        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 +680,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();
     }
@@ -645,7 +739,8 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
 
     private updateFullscreenButton(): void {
         const fullscreen = this.fullscreen;
-        const label = fullscreen ? this.fullscreenLabels.exit : this.fullscreenLabels.enter;
+        const labels = this.resolveFullscreenLabels();
+        const label = fullscreen ? labels.exit : labels.enter;
         const path = fullscreen
             ? 'M4 9h5V4M20 9h-5V4M4 15h5v5M20 15h-5v5'
             : 'M9 4H4v5M15 4h5v5M9 20H4v-5M15 20h5v-5';
@@ -752,6 +847,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 +855,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 +899,30 @@ 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' }),
+            },
+            // Always available: it shows the overview as readily as it hides it, and an empty
+            // diagram is exactly when someone may want the panel out of the way.
+            overview: {
+                canExecute: () => true,
+                execute: () => this.setOverviewVisible(!this.getViewState().overviewVisible),
+            },
             properties: {
                 canExecute: ({ nodes }) => nodes.length > 0,
                 execute: ({ nodes }) => this.emit('nodeProperties', { nodes }),
@@ -818,6 +941,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/embed.ts

@@ -1,3 +1,4 @@
+import { t } from './i18n.js';
 // Shared read-only diagram embed layer. Rendering, palette loading and theming
 // live next to the diagram engine so web applications do not copy that logic.
 //
@@ -407,7 +408,7 @@ async function renderSchemeAtRevision(
 		diagram.setLinkValidator(() => true);
 		diagram.setOverviewVisible(false);
 		const missingTypeTemplate = div.dataset.diagramMissingElement
-			?? 'Element type "{typeId}" is missing from the palette.';
+			?? t('embedMissingElement', 'Element type "{typeId}" is missing from the palette.');
 		const converted = toDiagramNodes(
 			scheme,
 			catalog,
@@ -508,10 +509,12 @@ interface EmbedErrorTexts {
 // default would never fire and the note would render blank.
 function errorTexts(div: HTMLElement): EmbedErrorTexts {
 	const parts = (div.dataset.diagramErrors ?? '').split('|');
+	// The attribute stays the override; without it the wording comes from the shared bundle, so
+	// a page that already translated the menu does not have to repeat itself per embed.
 	return {
-		load: parts[0] || 'Diagram source could not be loaded.',
-		empty: parts[1] || 'Diagram is empty or malformed.',
-		draw: parts[2] || 'Diagram could not be rendered.',
+		load: parts[0] || t('embedErrorLoad', 'Diagram source could not be loaded.'),
+		empty: parts[1] || t('embedErrorEmpty', 'Diagram is empty or malformed.'),
+		draw: parts[2] || t('embedErrorDraw', 'Diagram could not be rendered.'),
 	};
 }
 

package/src/i18n.ts

@@ -95,8 +95,35 @@ export interface DesignerI18n {
     copy?: string;
     paste?: string;
     ctxOpen?: string;
+    // Deletes the selected nodes and links. Deliberately not the solution explorer's
+    // `delete`, which removes a whole strategy: same English word, but the object differs,
+    // and a language that declines it -- or a host that writes "Delete strategy..." -- cannot
+    // serve both from one key.
+    ctxDelete?: 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;
+    ctxOverview?: string;
     properties?: string;
     ctxHelp?: string;
+
+    // Everything else the control renders by itself. Each of these also has a per-instance
+    // override -- the fullscreenLabels option, or a data-diagram-* attribute on an embedded
+    // host -- and that override wins; these are the defaults when none was given.
+    fullscreenEnter?: string;
+    fullscreenExit?: string;
+    embedErrorLoad?: string;
+    embedErrorEmpty?: string;
+    embedErrorDraw?: string;
+    embedMissingElement?: string;
+
+    // Not the diagram menu: it has no collapse/expand command. Kept for hosts already
+    // shipping them, but moved out of the block above so nobody translates them expecting
+    // to see them in the context menu.
     collapse?: string;
     expand?: string;
 
@@ -198,13 +225,21 @@ export interface DesignerI18n {
     opterr_plotly_missing?: string;
 }
 
-const i18n: DesignerI18n =
-    typeof window === 'undefined'
-        ? {}
-        : (window as unknown as { __designerI18n?: DesignerI18n }).__designerI18n ?? {};
-
 /// Localized string for `key`, or `fallback` (English) when the host
 /// didn't provide it.
+///
+/// The bundle is read on every call rather than captured when this module loads. Capturing
+/// it meant the host had to assign `window.__designerI18n` before the bundle evaluated --
+/// the opposite of the usual order, and impossible for a lazily loaded chunk -- and a host
+/// that assigned it afterwards silently got English with nothing to explain why. Reading it
+/// live also makes assigning and mutating the object behave the same, and lets the language
+/// change mid-session: the only thing reading these keys is the context menu, and it is
+/// built fresh on every right-click.
+///
+/// An empty string counts as missing. Half-finished translation exports routinely emit one,
+/// and a blank menu entry is worse than an English one.
 export function t(key: keyof DesignerI18n, fallback: string): string {
-    return i18n[key] ?? fallback;
+    if (typeof window === 'undefined') return fallback;
+    const value = (window as unknown as { __designerI18n?: DesignerI18n }).__designerI18n?.[key];
+    return value === undefined || value === '' ? fallback : value;
 }

package/src/index.ts

@@ -85,11 +85,21 @@ export {
     StockSharpDiagram,
 } from './diagram/stocksharp-diagram.js';
 
+// The menu resolves its labels through this, so a host needs the type to write a bundle the
+// compiler can check. Without it the key names get hand-copied, and a typo shows up only as an
+// English label on screen.
+export type { DesignerI18n } from './i18n.js';
+
 export type {
     ContextCommand,
+    ContextCommandGroup,
+    ContextCommandGroupState,
     ContextCommandPayload,
     ContextCommandState,
+    ContextMenuItemState,
     ContextMenuRequestedPayload,
+    ExportFormat,
+    ExportRequestedPayload,
     DiagramEvents,
     DiagramClipboard,
     DiagramGridSettings,