@stocksharp/diagram 0.4.0 → 0.5.0

package/src/canvas-renderer.ts

@@ -1,3 +1,5 @@
+import type { DrawSurface } from './draw-surface.js';
+import { SvgSurface } from './svg-surface.js';
 // Internal dependency-free canvas renderer used by StockSharpDiagram.
 //
 // Dependency-free, pure 2D canvas. Demonstrates the hard parts: typed
@@ -507,7 +509,9 @@ function colorLuminance(color: string | undefined): number {
 export class Diagram {
     private readonly host: HTMLElement;
     private readonly canvas: HTMLCanvasElement;
-    private ctx: CanvasRenderingContext2D;
+    // Typed as the surface, not the context: the on-screen path still passes the browser's own
+    // 2D context (it satisfies the interface structurally), while export can hand in an SVG one.
+    private ctx: DrawSurface;
     private readonly opts: DiagramOptions;
 
     private nodes: NodeModel[] = [];
@@ -1332,6 +1336,65 @@ export class Diagram {
             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.
+    private exportLayout(scope: DiagramScreenshotScope, options: DiagramScreenshotOptions) {
         const pixelRatio = this.positiveScreenshotNumber(options.pixelRatio ?? this.dpr, 'pixelRatio');
         const exportScale = scope === 'content'
             ? this.positiveScreenshotNumber(options.scale ?? 1, 'scale')
@@ -1348,17 +1411,41 @@ export class Diagram {
             : this.height;
         const pixelWidth = Math.ceil(width * pixelRatio);
         const pixelHeight = Math.ceil(height * pixelRatio);
+
         if (pixelWidth > 16384 || pixelHeight > 16384 || pixelWidth * pixelHeight > 268_435_456) {
             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: DiagramScreenshotOptions = {}): string {
+        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,
@@ -1369,19 +1456,19 @@ 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,
@@ -1398,9 +1485,9 @@ 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();
     }
 
     private positiveScreenshotNumber(value: number, name: string): number {
@@ -3072,7 +3159,7 @@ export class Diagram {
     }
 }
 
-function roundRect(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, r: number): void {
+function roundRect(ctx: DrawSurface, x: number, y: number, w: number, h: number, r: number): void {
     const rr = Math.min(r, w / 2, h / 2);
     ctx.beginPath();
     ctx.moveTo(x + rr, y);

package/src/diagram/api.ts

@@ -18,6 +18,12 @@ export interface DiagramOptions {
     catalog: import('./catalog.js').StockSharpCatalog;
     /** Show the built-in top-right fullscreen request button. Defaults to true. */
     showFullscreenButton?: boolean;
+    /**
+     * Show the built-in context menu on right-click. Defaults to true, because the control
+     * suppresses the browser's own menu regardless. Turn it off to draw your own from
+     * `contextMenuRequested`, which is emitted either way.
+     */
+    showContextMenu?: boolean;
     /** Tooltip/aria text for that button. Defaults to English. */
     fullscreenLabels?: DiagramFullscreenLabels;
     overviewContainer?: HTMLElement | null;
@@ -112,7 +118,18 @@ export interface FullscreenRequestedPayload {
     fullscreen: boolean;
 }
 
-export type ContextCommand = 'undo' | 'redo' | 'cut' | 'copy' | 'paste' | 'open' | 'delete' | 'properties' | 'help';
+export type ContextCommand =
+    | 'undo' | 'redo'
+    | 'cut' | 'copy' | 'paste'
+    | 'open' | 'delete'
+    | 'exportDocument' | 'exportPng' | 'exportSvg'
+    | 'properties' | 'help';
+
+/**
+ * Names a submenu rather than something to run. Deliberately outside ContextCommand:
+ * `executeContextCommand` takes commands, and a submenu label has nothing to execute.
+ */
+export type ContextCommandGroup = 'export';
 
 export interface ContextCommandPayload {
     command: ContextCommand;
@@ -125,6 +142,32 @@ export interface ContextCommandState {
     enabled: boolean;
 }
 
+/** A submenu: its own enabled state, plus the items to show when it opens. */
+export interface ContextCommandGroupState {
+    group: ContextCommandGroup;
+    enabled: boolean;
+    commands: ContextCommandState[];
+}
+
+/**
+ * One entry of the menu, in the order it should be drawn. Discriminate on `group`:
+ * an entry that has it is a submenu, an entry that does not is a command.
+ */
+export type ContextMenuItemState = ContextCommandState | ContextCommandGroupState;
+
+/** What an export request asks the host to produce. */
+export type ExportFormat = 'document' | 'png' | 'svg';
+
+/**
+ * The user picked something from the export submenu. Like `nodeProperties`, this is a
+ * request and nothing more: the control does not write files or open dialogs, so the
+ * host fulfils it with `saveDocument()`, `takeScreenshot()` or `takeSvg()` and its own
+ * options for scope, padding and background.
+ */
+export interface ExportRequestedPayload {
+    format: ExportFormat;
+}
+
 export interface ContextMenuRequestedPayload {
     x: number;
     y: number;
@@ -132,7 +175,7 @@ export interface ContextMenuRequestedPayload {
     link: Link | null;
     port: Port | null;
     portDirection: PortDirection | null;
-    commands: ContextCommandState[];
+    commands: ContextMenuItemState[];
 }
 
 export interface NodeSelectedPayload {
@@ -251,6 +294,7 @@ export interface DiagramEvents {
     loadFinished: LoadFinishedPayload;
     contextCommand: ContextCommandPayload;
     contextMenuRequested: ContextMenuRequestedPayload;
+    exportRequested: ExportRequestedPayload;
     undoRequested: NodeChangePayload & LinkChangePayload;
     redoRequested: NodeChangePayload & LinkChangePayload;
     nodeEdit: NodeChangePayload;

package/src/diagram/context-menu.ts

@@ -0,0 +1,298 @@
+import { t } from '../i18n.js';
+import type { ContextCommand, ContextCommandGroup, ContextMenuItemState } from './api.js';
+
+/**
+ * The control's own context menu.
+ *
+ * It exists because right-click already suppresses the browser's menu whether or not anyone
+ * is listening. A control that takes the native menu away owes one back, so this is on by
+ * default; a host with its own menu turns it off (`showContextMenu: false`) and keeps using
+ * `contextMenuRequested`, which is emitted either way.
+ *
+ * Styling follows the fullscreen button: inline styles driven by `--ssdiagram-*` custom
+ * properties with sensible fallbacks, so the menu is usable with no stylesheet at all and
+ * retintable without one. Class names are stable for hosts that would rather use CSS.
+ */
+
+const ROOT_CLASS = 'ssdiagram-context-menu';
+const ITEM_CLASS = 'ssdiagram-context-menu-item';
+const SUBMENU_CLASS = 'ssdiagram-context-menu-submenu';
+const SEPARATOR_CLASS = 'ssdiagram-context-menu-separator';
+const LABEL_CLASS = 'ssdiagram-context-menu-label';
+const ARROW_CLASS = 'ssdiagram-context-menu-arrow';
+
+/** A rule below these entries, so related commands read as blocks rather than one long list. */
+const SEPARATE_AFTER: ReadonlySet<string> = new Set(['redo', 'paste', 'delete']);
+
+function label(id: ContextCommand | ContextCommandGroup): string {
+    switch (id) {
+        case 'undo': return t('undo', 'Undo');
+        case 'redo': return t('redo', 'Redo');
+        case 'cut': return t('cut', 'Cut');
+        case 'copy': return t('copy', 'Copy');
+        case 'paste': return t('paste', 'Paste');
+        case 'open': return t('ctxOpen', 'Open');
+        case 'delete': return t('delete', 'Delete');
+        case 'export': return t('ctxExportAs', 'Export as');
+        case 'exportDocument': return t('ctxExportDocument', 'Scheme');
+        case 'exportPng': return t('ctxExportPng', 'PNG image');
+        case 'exportSvg': return t('ctxExportSvg', 'SVG image');
+        case 'properties': return t('properties', 'Properties');
+        case 'help': return t('ctxHelp', 'Help');
+    }
+}
+
+const PANEL_STYLE: Partial<CSSStyleDeclaration> = {
+    position: 'fixed',
+    zIndex: '2147483000',
+    minWidth: '176px',
+    padding: '4px',
+    border: '1px solid var(--ssdiagram-menu-border, var(--ssdiagram-control-border, var(--t-border, #3a4250)))',
+    borderRadius: '7px',
+    background: 'var(--ssdiagram-menu-background, var(--ssdiagram-control-background, var(--t-panel, #181a20)))',
+    color: 'var(--ssdiagram-menu-color, var(--ssdiagram-control-color, var(--t-text, #eaecef)))',
+    boxShadow: '0 12px 32px rgba(0, 0, 0, 0.45)',
+    font: 'var(--ssdiagram-menu-font, 12.5px/1.35 system-ui, -apple-system, "Segoe UI", sans-serif)',
+    boxSizing: 'border-box',
+    userSelect: 'none',
+};
+
+const ITEM_STYLE: Partial<CSSStyleDeclaration> = {
+    display: 'flex',
+    alignItems: 'center',
+    gap: '10px',
+    width: '100%',
+    padding: '6px 10px',
+    border: '0',
+    borderRadius: '4px',
+    background: 'transparent',
+    color: 'inherit',
+    font: 'inherit',
+    textAlign: 'left',
+    whiteSpace: 'nowrap',
+    cursor: 'pointer',
+    boxSizing: 'border-box',
+};
+
+const HOVER_BACKGROUND = 'var(--ssdiagram-menu-hover, var(--t-hover, rgba(255, 255, 255, 0.08)))';
+const DISABLED_COLOR = 'var(--ssdiagram-menu-disabled-color, var(--t-text-dim, #848e9c))';
+
+export interface ContextMenuViewOptions {
+    /** Where the menu is appended. The diagram mount point, so it survives a fullscreened panel. */
+    container: HTMLElement;
+    /** Runs the picked command. The same entry point a host menu would use. */
+    execute: (command: ContextCommand) => void;
+}
+
+export class ContextMenuView {
+    private readonly container: HTMLElement;
+    private readonly execute: (command: ContextCommand) => void;
+    private root: HTMLElement | null = null;
+    private submenu: HTMLElement | null = null;
+    private readonly detach: Array<() => void> = [];
+
+    constructor(options: ContextMenuViewOptions) {
+        this.container = options.container;
+        this.execute = options.execute;
+    }
+
+    get isOpen(): boolean {
+        return this.root !== null;
+    }
+
+    show(x: number, y: number, items: readonly ContextMenuItemState[]): void {
+        this.hide();
+        const owner = this.container.ownerDocument ?? document;
+        const root = this.panel(owner);
+        root.className = ROOT_CLASS;
+        root.setAttribute('role', 'menu');
+
+        items.forEach((item, index) => {
+            if ('group' in item) root.appendChild(this.groupEntry(owner, item));
+            else root.appendChild(this.commandEntry(owner, item.command, item.enabled, true));
+            const id = 'group' in item ? item.group : item.command;
+            if (SEPARATE_AFTER.has(id) && index < items.length - 1) root.appendChild(this.separator(owner));
+        });
+
+        this.container.appendChild(root);
+        this.root = root;
+        this.place(root, x, y);
+        this.watchForDismissal(owner);
+    }
+
+    hide(): void {
+        for (const dispose of this.detach.splice(0)) dispose();
+        this.submenu = null;
+        this.root?.remove();
+        this.root = null;
+    }
+
+    destroy(): void {
+        this.hide();
+    }
+
+    private panel(owner: Document): HTMLElement {
+        const panel = owner.createElement('div');
+        Object.assign(panel.style, PANEL_STYLE);
+        return panel;
+    }
+
+    private separator(owner: Document): HTMLElement {
+        const rule = owner.createElement('div');
+        rule.className = SEPARATOR_CLASS;
+        Object.assign(rule.style, {
+            height: '1px',
+            margin: '4px 6px',
+            background: 'var(--ssdiagram-menu-border, var(--t-border, #3a4250))',
+        });
+        return rule;
+    }
+
+    private item(owner: Document, text: string, enabled: boolean, arrow: boolean): HTMLButtonElement {
+        const button = owner.createElement('button');
+        button.type = 'button';
+        button.className = ITEM_CLASS;
+        button.setAttribute('role', 'menuitem');
+        Object.assign(button.style, ITEM_STYLE);
+        if (!enabled) {
+            button.disabled = true;
+            button.style.color = DISABLED_COLOR;
+            button.style.cursor = 'default';
+        }
+
+        const caption = owner.createElement('span');
+        caption.className = LABEL_CLASS;
+        caption.textContent = text;
+        caption.style.flex = '1';
+        button.appendChild(caption);
+
+        if (arrow) {
+            const chevron = owner.createElement('span');
+            chevron.className = ARROW_CLASS;
+            chevron.textContent = '›';
+            chevron.setAttribute('aria-hidden', 'true');
+            Object.assign(chevron.style, { flex: 'none', opacity: '0.7', fontSize: '14px' });
+            button.appendChild(chevron);
+        }
+        return button;
+    }
+
+    // `closesSubmenu` separates the two places an item can live. A top-level item shuts any
+    // open submenu when the pointer arrives, the way menus everywhere behave. An item inside
+    // the submenu must not: reaching it means the pointer has entered that very panel, and
+    // closing it there would pull it out from under the pointer and drop the click on the
+    // canvas behind.
+    private commandEntry(owner: Document, command: ContextCommand, enabled: boolean, closesSubmenu: boolean): HTMLElement {
+        const button = this.item(owner, label(command), enabled, false);
+        this.on(button, 'pointerenter', () => {
+            if (closesSubmenu) this.closeSubmenu();
+            if (enabled) button.style.background = HOVER_BACKGROUND;
+        });
+        this.on(button, 'pointerleave', () => { button.style.background = 'transparent'; });
+        this.on(button, 'click', () => {
+            if (!enabled) return;
+            // Hide first: a command may open a dialog, and a menu left on top of it looks stuck.
+            this.hide();
+            this.execute(command);
+        });
+        return button;
+    }
+
+    private groupEntry(owner: Document, group: { group: ContextCommandGroup; enabled: boolean; commands: readonly { command: ContextCommand; enabled: boolean }[] }): HTMLElement {
+        const host = owner.createElement('div');
+        host.style.position = 'relative';
+
+        const button = this.item(owner, label(group.group), group.enabled, true);
+        host.appendChild(button);
+
+        const panel = this.panel(owner);
+        panel.className = SUBMENU_CLASS;
+        panel.setAttribute('role', 'menu');
+        Object.assign(panel.style, { position: 'absolute', left: '100%', top: '-5px', display: 'none' });
+        for (const child of group.commands) panel.appendChild(this.commandEntry(owner, child.command, child.enabled, false));
+        host.appendChild(panel);
+
+        const open = (): void => {
+            if (!group.enabled) return;
+            button.style.background = HOVER_BACKGROUND;
+            panel.style.display = 'block';
+            this.submenu = panel;
+            this.keepOnScreen(panel);
+        };
+        this.on(button, 'pointerenter', open);
+        // Tap opens it too: a touch device never sends pointerenter on its own.
+        this.on(button, 'click', open);
+        this.on(host, 'pointerleave', () => {
+            if (this.submenu !== panel) return;
+            button.style.background = 'transparent';
+            panel.style.display = 'none';
+            this.submenu = null;
+        });
+        return host;
+    }
+
+    private closeSubmenu(): void {
+        if (this.submenu === null) return;
+        this.submenu.style.display = 'none';
+        this.submenu = null;
+    }
+
+    /** Keeps the panel inside the viewport, flipping it left when it would run off the edge. */
+    private keepOnScreen(panel: HTMLElement): void {
+        if (typeof panel.getBoundingClientRect !== 'function' || typeof window === 'undefined') return;
+        const box = panel.getBoundingClientRect();
+        if (box.right > window.innerWidth - 4) {
+            panel.style.left = 'auto';
+            panel.style.right = '100%';
+        }
+        if (box.bottom > window.innerHeight - 4) {
+            panel.style.top = 'auto';
+            panel.style.bottom = '-5px';
+        }
+    }
+
+    private place(root: HTMLElement, x: number, y: number): void {
+        root.style.left = `${x}px`;
+        root.style.top = `${y}px`;
+        if (typeof root.getBoundingClientRect !== 'function' || typeof window === 'undefined') return;
+        const box = root.getBoundingClientRect();
+        // Flip rather than clamp: a menu shoved back onto the screen would cover the very
+        // thing that was right-clicked.
+        if (box.right > window.innerWidth - 4) root.style.left = `${Math.max(4, x - box.width)}px`;
+        if (box.bottom > window.innerHeight - 4) root.style.top = `${Math.max(4, y - box.height)}px`;
+    }
+
+    private watchForDismissal(owner: Document): void {
+        const dismiss = (): void => this.hide();
+        const outside = (event: Event): void => {
+            // Duck-typed rather than `target instanceof Node`: this runs in whatever document
+            // the host mounted us in, and a cross-document Node fails that check.
+            const root = this.root;
+            const target = event.target as Node | null;
+            if (root !== null && target !== null && typeof root.contains === 'function' && root.contains(target)) return;
+            this.hide();
+        };
+        this.on(owner, 'pointerdown', outside, true);
+        this.on(owner, 'keydown', (event: Event) => {
+            if ((event as KeyboardEvent).key === 'Escape') this.hide();
+        });
+        if (typeof window !== 'undefined') {
+            // Scroll and resize move the diagram out from under the menu, which would otherwise
+            // hang in place pointing at nothing.
+            this.on(window, 'blur', dismiss);
+            this.on(window, 'resize', dismiss);
+            this.on(window, 'scroll', dismiss, true);
+        }
+    }
+
+    private on(
+        target: { addEventListener?: (type: string, listener: EventListener, options?: boolean) => void; removeEventListener?: (type: string, listener: EventListener, options?: boolean) => void },
+        type: string,
+        listener: EventListener,
+        capture = false,
+    ): void {
+        if (typeof target.addEventListener !== 'function') return;
+        target.addEventListener(type, listener, capture);
+        this.detach.push(() => target.removeEventListener?.(type, listener, capture));
+    }
+}