@stocksharp/diagram 0.2.2 → 0.3.0

package/src/diagram/api.ts

@@ -2,15 +2,24 @@ import type { DiagramDocument } from '../core/model.js';
 import type {
     DiagramRuntimeState,
     DiagramSelection,
+    DiagramSnapshot,
     DiagramViewState,
 } from '../core/state.js';
 import type { DiagramNode, Link, Port, PortDirection } from './types.js';
 
+/** What the fullscreen button calls itself, in the host page's language. */
+export interface DiagramFullscreenLabels {
+    enter: string;
+    exit: string;
+}
+
 export interface DiagramOptions {
     div: HTMLElement;
     catalog: import('./catalog.js').StockSharpCatalog;
     /** Show the built-in top-right fullscreen request button. Defaults to true. */
     showFullscreenButton?: boolean;
+    /** Tooltip/aria text for that button. Defaults to English. */
+    fullscreenLabels?: DiagramFullscreenLabels;
     overviewContainer?: HTMLElement | null;
     zoomLabel?: HTMLElement | null;
     /** Optional system clipboard adapter. Pass null to force memory-only clipboard. */
@@ -224,7 +233,7 @@ export interface LinkValidatorArgs {
 
 export type LinkValidator = (args: LinkValidatorArgs) => boolean;
 
-export interface DiagramEvents extends Record<string, unknown> {
+export interface DiagramEvents {
     nodeAdded: NodeChangePayload;
     nodeRemoved: NodeChangePayload;
     linkAdded: LinkChangePayload;
@@ -248,10 +257,10 @@ export interface DiagramEvents extends Record<string, unknown> {
     nodeProperties: NodeChangePayload;
     nodeOpen: NodeChangePayload;
     nodeHelp: NodeChangePayload;
-    zoomChanged: DiagramViewState;
-    viewChanged: DiagramViewState;
-    selectionChanged: DiagramSelection;
-    runtimeStateChanged: { state: DiagramRuntimeState };
+    zoomChanged: DiagramSnapshot<DiagramViewState>;
+    viewChanged: DiagramSnapshot<DiagramViewState>;
+    selectionChanged: DiagramSnapshot<DiagramSelection>;
+    runtimeStateChanged: { state: DiagramSnapshot<DiagramRuntimeState> };
     undoStackChanged: { canUndo: boolean; canRedo: boolean };
     documentLoaded: { document: DiagramDocument };
     documentLoadFailed: DocumentLoadFailedPayload;

package/src/diagram/catalog.ts

@@ -1,7 +1,7 @@
 import { EventEmitter } from './event-emitter.js';
 import { Node, NodeInit, PortType, PortTypeInit } from './types.js';
 
-export interface CatalogEvents extends Record<string, unknown> {
+export interface CatalogEvents {
     portTypesChanged: PortType[];
     nodeTypesChanged: Node[];
 }
@@ -35,21 +35,33 @@ export class StockSharpCatalog extends EventEmitter<CatalogEvents> {
     // imported node ("Element type is missing from the palette"). Node.id
     // keeps its original casing so save/load round-trips unchanged.
     addNodeType(node: Node | NodeInit): void {
-        const n = node instanceof Node ? node : new Node(node);
+        // Copied on the way in as well as on the way out: otherwise the caller
+        // keeps a handle on the stored definition and can edit it afterwards.
+        // The clone covers the init branch too -- Node's constructor keeps the
+        // caller's Port instances and parameters array as they are.
+        const n = (node instanceof Node ? node : new Node(node)).clone();
         this.nodeTypes.set(n.id.toLowerCase(), n);
-        this.emit('nodeTypesChanged', this.getNodeTypes());
+        this.emitNodeTypesChanged();
     }
 
     removeNodeType(id: string): void {
         this.nodeTypes.delete(id.toLowerCase());
-        this.emit('nodeTypesChanged', this.getNodeTypes());
+        this.emitNodeTypesChanged();
     }
 
     getNodeType(id: string): Node | null {
-        return this.nodeTypes.get(id.toLowerCase()) ?? null;
+        return this.nodeTypes.get(id.toLowerCase())?.clone() ?? null;
     }
 
     getNodeTypes(): Node[] {
-        return Array.from(this.nodeTypes.values());
+        return Array.from(this.nodeTypes.values(), (node) => node.clone());
+    }
+
+    // Node definitions are mutable, so the payload has to be a copy of each one.
+    // Building a catalog is a loop of addNodeType calls, which would make that
+    // quadratic; skipping it while nobody listens keeps catalog construction --
+    // where no subscriber exists yet -- as cheap as it was.
+    private emitNodeTypesChanged(): void {
+        if (this.hasHandlers('nodeTypesChanged')) this.emit('nodeTypesChanged', this.getNodeTypes());
     }
 }

package/src/diagram/event-emitter.ts

@@ -1,6 +1,9 @@
 export type EventHandler<T> = (payload: T) => void;
 
-export class EventEmitter<TEvents extends Record<string, unknown>> {
+// TEvents is constrained to object rather than Record<string, unknown>: the
+// latter forces every event map to carry a string index signature, which
+// collapses keyof TEvents to string and lets any misspelled name compile.
+export class EventEmitter<TEvents extends object> {
     private readonly handlers = new Map<keyof TEvents, Set<EventHandler<unknown>>>();
 
     on<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): () => void {
@@ -38,6 +41,14 @@ export class EventEmitter<TEvents extends Record<string, unknown>> {
         }
     }
 
+    /**
+     * Whether anyone is listening. Lets a subject skip building a payload that
+     * is expensive to produce and that nothing would read.
+     */
+    protected hasHandlers<K extends keyof TEvents>(event: K): boolean {
+        return (this.handlers.get(event)?.size ?? 0) > 0;
+    }
+
     protected clearEventHandlers(): void {
         this.handlers.clear();
     }

package/src/diagram/palette.ts

@@ -22,7 +22,7 @@ export interface PaletteContextMenuPayload extends PaletteNodePayload {
     y: number;
 }
 
-export interface PaletteEvents extends Record<string, unknown> {
+export interface PaletteEvents {
     selectionChanged: PaletteSelectionChangedPayload;
     nodeActivated: PaletteNodePayload;
     contextMenuRequested: PaletteContextMenuPayload;

package/src/diagram/stocksharp-diagram.ts

@@ -6,7 +6,7 @@ import {
     parseDiagramViewState,
     serializeDiagramViewState,
 } from '../core/view-state.js';
-import type { DiagramDocument } from '../core/model.js';
+import type { DiagramDocument, PortDynamicMode } from '../core/model.js';
 import { DiagramActionRegistry } from '../core/action-registry.js';
 import type {
     DiagramGlobalErrorKind,
@@ -14,6 +14,7 @@ import type {
     DiagramPortRuntimeState,
     DiagramRuntimeState,
     DiagramSelection,
+    DiagramSnapshot,
     DiagramViewState,
 } from '../core/state.js';
 import {
@@ -32,6 +33,7 @@ import type {
     DiagramClipboard,
     ContextCommand,
     DiagramLoadOptions,
+    DiagramFullscreenLabels,
     DiagramGridSettings,
     DiagramNodeBounds,
     DiagramPoint,
@@ -75,7 +77,7 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
     private destroyed = false;
     private fullscreen = false;
     private fullscreenButtonVisible = true;
-    private linkValidator: LinkValidator | null = null;
+    private fullscreenLabels: DiagramFullscreenLabels = { enter: 'Enter fullscreen', exit: 'Exit fullscreen' };
     private readonly contextActions = new DiagramActionRegistry<ContextCommand, ContextActionContext>();
 
     constructor(options: DiagramOptions) {
@@ -92,6 +94,7 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
             gridSize: options.gridSize,
         });
         this.fullscreenButtonVisible = options.showFullscreenButton ?? true;
+        this.fullscreenLabels = options.fullscreenLabels ?? this.fullscreenLabels;
         this.prepareFullscreenButtonHost();
         this.fullscreenButton = this.createFullscreenButton();
         this.updateFullscreenButton();
@@ -102,7 +105,6 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
     }
 
     setLinkValidator(validator: LinkValidator | null): void {
-        this.linkValidator = validator;
         this.canvas.setLinkValidator(validator === null ? null : ({ fromNode, fromPort, toNode, toPort }) => validator({
             fromNode: this.fromCanvasNode(fromNode),
             fromPort: this.fromCanvasPort(fromPort),
@@ -175,7 +177,7 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         this.canvas.setGridSnap(enabled, size);
     }
 
-    getGridSnap(): DiagramGridSettings {
+    getGridSnap(): DiagramSnapshot<DiagramGridSettings> {
         return this.canvas.getGridSnap();
     }
 
@@ -199,29 +201,33 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         this.canvas.removeLink(this.toCanvasLink(link));
     }
 
-    addPort(nodeId: string, direction: PortDirection, port: Port): void {
-        this.canvas.addPort(nodeId, direction, this.toCanvasPort(port));
+    /** False when nothing changed: no such node or port, or the edit was a no-op. */
+    addPort(nodeId: string, direction: PortDirection, port: Port): boolean {
+        return this.canvas.addPort(nodeId, direction, this.toCanvasPort(port));
     }
 
-    removePort(nodeId: string, direction: PortDirection, portId: string): void {
-        this.canvas.removePort(nodeId, direction, portId);
+    /** False when nothing changed: no such node or port, or the edit was a no-op. */
+    removePort(nodeId: string, direction: PortDirection, portId: string): boolean {
+        return this.canvas.removePort(nodeId, direction, portId);
     }
 
-    updatePortType(nodeId: string, direction: PortDirection, portId: string, type: string): void {
-        this.canvas.updatePortType(nodeId, direction, portId, type);
+    /** False when nothing changed: no such node or port, or the edit was a no-op. */
+    updatePortType(nodeId: string, direction: PortDirection, portId: string, type: string): boolean {
+        return this.canvas.updatePortType(nodeId, direction, portId, type);
     }
 
     updatePort(nodeId: string, direction: PortDirection, portId: string, patch: PortUpdate): boolean {
         return this.canvas.updatePort(nodeId, direction, portId, patch);
     }
 
+    /** False when nothing changed: no such node or port, or the edit was a no-op. */
     setNodePorts(
         nodeId: string,
-        inPorts: ReadonlyArray<{ key: string; name: string; description: string; type: string; maxLinks: number; availableTypes?: string[]; isDynamic?: boolean; dynamicMode?: string }>,
-        outPorts: ReadonlyArray<{ key: string; name: string; description: string; type: string; maxLinks: number; availableTypes?: string[]; isDynamic?: boolean; dynamicMode?: string }>,
-    ): void {
+        inPorts: ReadonlyArray<{ key: string; name: string; description: string; type: string; maxLinks: number; availableTypes?: string[]; isDynamic?: boolean; dynamicMode?: PortDynamicMode }>,
+        outPorts: ReadonlyArray<{ key: string; name: string; description: string; type: string; maxLinks: number; availableTypes?: string[]; isDynamic?: boolean; dynamicMode?: PortDynamicMode }>,
+    ): boolean {
         const current = this.canvas.findNode(nodeId);
-        if (current === undefined) return;
+        if (current === undefined) return false;
         const convert = (port: typeof inPorts[number]): CanvasPortInit => ({
             id: port.key,
             name: port.name,
@@ -240,15 +246,17 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         for (const sibling of current.outPorts.filter((port) => port.isSibling)) {
             if (!nextOut.some((port) => port.id === sibling.id)) nextOut.push(sibling.toInit());
         }
-        this.canvas.setNodePorts(nodeId, nextIn, nextOut);
+        return this.canvas.setNodePorts(nodeId, nextIn, nextOut);
     }
 
-    updateNode(nodeId: string, patch: { name?: string; description?: string; color?: string; border?: string }): void {
-        this.canvas.updateNode(nodeId, patch);
+    /** False when nothing changed: no such node or port, or the edit was a no-op. */
+    updateNode(nodeId: string, patch: { name?: string; description?: string; color?: string; border?: string }): boolean {
+        return this.canvas.updateNode(nodeId, patch);
     }
 
-    setNodeMessage(nodeId: string, message: string): void {
-        this.canvas.updateNode(nodeId, { message });
+    /** False when nothing changed: no such node or port, or the edit was a no-op. */
+    setNodeMessage(nodeId: string, message: string): boolean {
+        return this.canvas.updateNode(nodeId, { message });
     }
 
     setNodeError(nodeId: string, message: string, options: NodeErrorOptions = {}): boolean {
@@ -259,11 +267,11 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         return this.canvas.clearNodeError(nodeId, kind);
     }
 
-    getRuntimeState(): DiagramRuntimeState {
+    getRuntimeState(): DiagramSnapshot<DiagramRuntimeState> {
         return this.canvas.getRuntimeState();
     }
 
-    setRuntimeState(state: DiagramRuntimeState): void {
+    setRuntimeState(state: DiagramSnapshot<DiagramRuntimeState>): void {
         this.canvas.setRuntimeState(state);
     }
 
@@ -288,12 +296,14 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         this.canvas.setGlobalError(message, kind);
     }
 
-    setNodeParamValue(nodeId: string, paramName: string, value: string | undefined): void {
-        this.canvas.setNodeParamValue(nodeId, paramName, value);
+    /** False when nothing changed: no such node or port, or the edit was a no-op. */
+    setNodeParamValue(nodeId: string, paramName: string, value: string | undefined): boolean {
+        return this.canvas.setNodeParamValue(nodeId, paramName, value);
     }
 
-    setNodeName(nodeId: string, value: string): void {
-        this.canvas.updateNode(nodeId, { name: value });
+    /** False when nothing changed: no such node or port, or the edit was a no-op. */
+    setNodeName(nodeId: string, value: string): boolean {
+        return this.canvas.updateNode(nodeId, { name: value });
     }
 
     /** Groups host-driven document edits into one undo/redo operation. */
@@ -309,7 +319,7 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         this.canvas.setReadOnly(readonly);
     }
 
-    getInteractionPermissions(): DiagramInteractionPermissions {
+    getInteractionPermissions(): DiagramSnapshot<DiagramInteractionPermissions> {
         return this.canvas.getInteractionPermissions();
     }
 
@@ -338,11 +348,11 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         this.canvas.setZoom(scale);
     }
 
-    getViewState(): DiagramViewState {
+    getViewState(): DiagramSnapshot<DiagramViewState> {
         return this.canvas.getViewState();
     }
 
-    setViewState(state: DiagramViewState): void {
+    setViewState(state: DiagramSnapshot<DiagramViewState>): void {
         this.canvas.setViewState(state);
         this.overviewContainer?.classList.toggle('hidden', !state.overviewVisible);
     }
@@ -362,7 +372,7 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         return this.canvas.takeScreenshot(options);
     }
 
-    getSelection(): DiagramSelection {
+    getSelection(): DiagramSnapshot<DiagramSelection> {
         return this.canvas.getSelection();
     }
 
@@ -396,6 +406,16 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
         return this.fullscreenButtonVisible;
     }
 
+    /** Text of the fullscreen button, for a host that renders in another language. */
+    setFullscreenLabels(labels: DiagramSnapshot<DiagramFullscreenLabels>): void {
+        this.fullscreenLabels = labels;
+        this.updateFullscreenButton();
+    }
+
+    getFullscreenLabels(): DiagramSnapshot<DiagramFullscreenLabels> {
+        return { ...this.fullscreenLabels };
+    }
+
     /** Updates only the control's state after the host changed its own layout. */
     setFullscreenState(fullscreen: boolean): void {
         if (this.fullscreen === fullscreen) return;
@@ -625,7 +645,7 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
 
     private updateFullscreenButton(): void {
         const fullscreen = this.fullscreen;
-        const label = fullscreen ? 'Exit fullscreen' : 'Enter fullscreen';
+        const label = fullscreen ? this.fullscreenLabels.exit : this.fullscreenLabels.enter;
         const path = fullscreen
             ? 'M4 9h5V4M20 9h-5V4M4 15h5v5M20 15h-5v5'
             : 'M9 4H4v5M15 4h5v5M9 20H4v-5M15 20h5v-5';
@@ -747,51 +767,47 @@ export class StockSharpDiagram extends EventEmitter<DiagramEvents> {
 
     private registerContextActions(): void {
         const permissions = () => this.canvas.getInteractionPermissions();
-        this.contextActions.register({
-            id: 'undo',
-            canExecute: () => this.canUndo(),
-            execute: () => this.undo(),
-        });
-        this.contextActions.register({
-            id: 'redo',
-            canExecute: () => this.canRedo(),
-            execute: () => this.redo(),
-        });
-        this.contextActions.register({
-            id: 'cut',
-            canExecute: ({ nodes }) => nodes.length > 0 && permissions().copy && permissions().deleteSelection,
-            execute: () => this.cutSelection(),
-        });
-        this.contextActions.register({
-            id: 'copy',
-            canExecute: ({ nodes }) => nodes.length > 0 && permissions().copy,
-            execute: () => this.copySelection(),
-        });
-        this.contextActions.register({
-            id: 'paste',
-            canExecute: () => this.canvas.hasClipboard() && permissions().paste,
-            execute: () => this.pasteSelection(),
-        });
-        this.contextActions.register({
-            id: 'open',
-            canExecute: ({ nodes }) => nodes.length === 1 && nodes[0].openAction.length > 0,
-            execute: ({ nodes }) => this.emit('nodeOpen', { nodes }),
-        });
-        this.contextActions.register({
-            id: 'delete',
-            canExecute: ({ selection }) => permissions().deleteSelection
-                && (selection.nodeIds.length > 0 || selection.linkIds.length > 0),
-            execute: () => this.canvas.deleteSelection(),
-        });
-        this.contextActions.register({
-            id: 'properties',
-            canExecute: ({ nodes }) => nodes.length > 0,
-            execute: ({ nodes }) => this.emit('nodeProperties', { nodes }),
-        });
-        this.contextActions.register({
-            id: 'help',
-            canExecute: ({ nodes }) => this.helpEnabled && nodes.length > 0,
-            execute: ({ nodes }) => this.emit('nodeHelp', { nodes }),
+        // Keyed by ContextCommand, so a command added to the union without an
+        // entry here fails to compile rather than quietly missing from the menu.
+        // Key order is menu order.
+        this.contextActions.registerAll({
+            undo: {
+                canExecute: () => this.canUndo(),
+                execute: () => this.undo(),
+            },
+            redo: {
+                canExecute: () => this.canRedo(),
+                execute: () => this.redo(),
+            },
+            cut: {
+                canExecute: ({ nodes }) => nodes.length > 0 && permissions().copy && permissions().deleteSelection,
+                execute: () => this.cutSelection(),
+            },
+            copy: {
+                canExecute: ({ nodes }) => nodes.length > 0 && permissions().copy,
+                execute: () => this.copySelection(),
+            },
+            paste: {
+                canExecute: () => this.canvas.hasClipboard() && permissions().paste,
+                execute: () => this.pasteSelection(),
+            },
+            open: {
+                canExecute: ({ nodes }) => nodes.length === 1 && nodes[0].openAction.length > 0,
+                execute: ({ nodes }) => this.emit('nodeOpen', { nodes }),
+            },
+            delete: {
+                canExecute: ({ selection }) => permissions().deleteSelection
+                    && (selection.nodeIds.length > 0 || selection.linkIds.length > 0),
+                execute: () => this.canvas.deleteSelection(),
+            },
+            properties: {
+                canExecute: ({ nodes }) => nodes.length > 0,
+                execute: ({ nodes }) => this.emit('nodeProperties', { nodes }),
+            },
+            help: {
+                canExecute: ({ nodes }) => this.helpEnabled && nodes.length > 0,
+                execute: ({ nodes }) => this.emit('nodeHelp', { nodes }),
+            },
         });
     }
 

package/src/diagram/types.ts

@@ -1,4 +1,5 @@
-import type { JsonObject } from '../core/model.js';
+import { toPortDynamicMode } from '../core/model.js';
+import type { JsonObject, PortDynamicMode } from '../core/model.js';
 
 // Core data model — node/port catalog (palette) and the live diagram (DiagramNode + Link).
 
@@ -29,7 +30,7 @@ export interface PortInit {
     /// True when this port can be added/removed at runtime on a node.
     isDynamic?: boolean;
     /// "" / "manual" / "onConnect" — see PalettePortDto.dynamicMode docs.
-    dynamicMode?: string;
+    dynamicMode?: PortDynamicMode;
     /// True when this port was spawned by the grow-on-connect pipeline.
     /// Distinguishes anchor + runtime siblings on save (only siblings are
     /// persisted in the diagram blob; anchors come from the palette schema).
@@ -47,7 +48,7 @@ export class Port {
     maxLinks: number;
     availableTypes: string[];
     isDynamic: boolean;
-    dynamicMode: string;
+    dynamicMode: PortDynamicMode;
     isSibling: boolean;
 
     constructor(init: PortInit) {
@@ -58,7 +59,7 @@ export class Port {
         this.maxLinks = typeof init.maxLinks === 'number' ? init.maxLinks : 0;
         this.availableTypes = init.availableTypes ?? [];
         this.isDynamic = init.isDynamic ?? false;
-        this.dynamicMode = init.dynamicMode ?? '';
+        this.dynamicMode = toPortDynamicMode(init.dynamicMode);
         this.isSibling = init.isSibling ?? false;
     }
 
@@ -268,7 +269,7 @@ export interface PortData {
     /// the anchor port spawns a sibling
     /// on each link drop and the link is rerouted to the sibling.
     isDynamic?: boolean;
-    dynamicMode?: string;
+    dynamicMode?: PortDynamicMode;
     /// True when this port was spawned by the dynamic-growth pipeline rather
     /// than declared on the palette element. Persists in the diagram blob so
     /// reload restores the same set of sibling sockets.