@stocksharp/diagram 0.1.0

package/src/core/state.ts

@@ -0,0 +1,148 @@
+export type DiagramPortDirection = 'in' | 'out';
+export type DiagramNodeErrorKind = 'runtime' | 'load';
+export type DiagramGlobalErrorKind = 'invalid' | 'load' | 'locked' | 'encrypted';
+
+export interface DiagramErrorState<TKind extends string> {
+    kind: TKind;
+    message: string;
+    /** Incrementing this value requests a fresh renderer animation. */
+    pulse: number;
+}
+
+export interface DiagramPortRuntimeState {
+    active: boolean;
+    selected: boolean;
+    breakpoint: boolean;
+    breakpointActive: boolean;
+    value: string | null;
+    error: string | null;
+}
+
+export interface DiagramNodePortRuntimeState {
+    in: Record<string, DiagramPortRuntimeState>;
+    out: Record<string, DiagramPortRuntimeState>;
+}
+
+export interface DiagramNodeRuntimeState {
+    active: boolean;
+    error: DiagramErrorState<DiagramNodeErrorKind> | null;
+    ports: DiagramNodePortRuntimeState;
+}
+
+export interface DiagramRuntimeState {
+    activeNodeId: string | null;
+    nodes: Record<string, DiagramNodeRuntimeState>;
+    globalError: DiagramErrorState<DiagramGlobalErrorKind> | null;
+}
+
+export interface DiagramViewState {
+    zoom: number;
+    panX: number;
+    panY: number;
+    overviewVisible: boolean;
+}
+
+export interface DiagramSelectedPort {
+    nodeId: string;
+    portId: string;
+    direction: DiagramPortDirection;
+}
+
+export interface DiagramSelection {
+    nodeIds: string[];
+    linkIds: string[];
+    port: DiagramSelectedPort | null;
+    primaryNodeId: string | null;
+    primaryLinkId: string | null;
+}
+
+export interface DiagramInteractionPermissions {
+    select: boolean;
+    inspect: boolean;
+    copy: boolean;
+    moveNodes: boolean;
+    createLinks: boolean;
+    deleteSelection: boolean;
+    paste: boolean;
+    history: boolean;
+}
+
+export function createDiagramRuntimeState(): DiagramRuntimeState {
+    return { activeNodeId: null, nodes: {}, globalError: null };
+}
+
+export function cloneDiagramRuntimeState(state: DiagramRuntimeState): DiagramRuntimeState {
+    return {
+        activeNodeId: state.activeNodeId,
+        globalError: state.globalError === null ? null : { ...state.globalError },
+        nodes: Object.fromEntries(Object.entries(state.nodes).map(([nodeId, node]) => [nodeId, {
+            active: node.active,
+            error: node.error === null ? null : { ...node.error },
+            ports: {
+                in: Object.fromEntries(Object.entries(node.ports.in)
+                    .map(([portId, port]) => [portId, { ...port }])),
+                out: Object.fromEntries(Object.entries(node.ports.out)
+                    .map(([portId, port]) => [portId, { ...port }])),
+            },
+        }])),
+    };
+}
+
+export function createDiagramViewState(): DiagramViewState {
+    return { zoom: 1, panX: 0, panY: 0, overviewVisible: true };
+}
+
+export function createDiagramSelection(): DiagramSelection {
+    return {
+        nodeIds: [],
+        linkIds: [],
+        port: null,
+        primaryNodeId: null,
+        primaryLinkId: null,
+    };
+}
+
+export function createDiagramPortRuntimeState(): DiagramPortRuntimeState {
+    return {
+        active: false,
+        selected: false,
+        breakpoint: false,
+        breakpointActive: false,
+        value: null,
+        error: null,
+    };
+}
+
+export function createEditableDiagramPermissions(): DiagramInteractionPermissions {
+    return {
+        select: true,
+        inspect: true,
+        copy: true,
+        moveNodes: true,
+        createLinks: true,
+        deleteSelection: true,
+        paste: true,
+        history: true,
+    };
+}
+
+export function createReadOnlyDiagramPermissions(): DiagramInteractionPermissions {
+    return {
+        select: true,
+        inspect: true,
+        copy: true,
+        moveNodes: false,
+        createLinks: false,
+        deleteSelection: false,
+        paste: false,
+        history: false,
+    };
+}
+
+export function createDiagramNodeRuntimeState(): DiagramNodeRuntimeState {
+    return {
+        active: false,
+        error: null,
+        ports: { in: {}, out: {} },
+    };
+}

package/src/core/view-state.ts

@@ -0,0 +1,82 @@
+import { createDiagramViewState, type DiagramViewState } from './state.js';
+
+export const DIAGRAM_VIEW_STATE_VERSION = 1 as const;
+
+export interface DiagramViewStateDocument {
+    version: typeof DIAGRAM_VIEW_STATE_VERSION;
+    view: DiagramViewState;
+}
+
+export class DiagramViewStateError extends Error {
+    constructor(message: string, readonly path: string = '$') {
+        super(`${path}: ${message}`);
+        this.name = 'DiagramViewStateError';
+    }
+}
+
+export function createDiagramViewStateDocument(
+    view: DiagramViewState = createDiagramViewState(),
+): DiagramViewStateDocument {
+    return {
+        version: DIAGRAM_VIEW_STATE_VERSION,
+        view: normalizeView(view),
+    };
+}
+
+export function parseDiagramViewState(source: string | unknown): DiagramViewState {
+    let value: unknown = source;
+    if (typeof source === 'string') {
+        try {
+            value = JSON.parse(source) as unknown;
+        } catch (error) {
+            const reason = error instanceof Error ? error.message : 'invalid JSON';
+            throw new DiagramViewStateError(reason);
+        }
+    }
+
+    const root = requireObject(value, '$');
+    const version = requireFiniteNumber(root.version, '$.version');
+    if (version !== DIAGRAM_VIEW_STATE_VERSION) {
+        throw new DiagramViewStateError(`unsupported view-state version ${version}`, '$.version');
+    }
+    return normalizeView(requireObject(root.view, '$.view'));
+}
+
+export function serializeDiagramViewState(view: DiagramViewState, space?: number): string {
+    return JSON.stringify(createDiagramViewStateDocument(view), null, space);
+}
+
+function normalizeView(value: unknown): DiagramViewState {
+    const view = requireObject(value, '$.view');
+    const zoom = requireFiniteNumber(view.zoom, '$.view.zoom');
+    if (zoom <= 0) throw new DiagramViewStateError('expected a positive number', '$.view.zoom');
+    return {
+        zoom,
+        panX: requireFiniteNumber(view.panX, '$.view.panX'),
+        panY: requireFiniteNumber(view.panY, '$.view.panY'),
+        overviewVisible: requireBoolean(view.overviewVisible, '$.view.overviewVisible'),
+    };
+}
+
+function requireObject(value: unknown, path: string): Record<string, unknown> {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new DiagramViewStateError('expected an object', path);
+    }
+    const prototype = Object.getPrototypeOf(value) as object | null;
+    if (prototype !== Object.prototype && prototype !== null) {
+        throw new DiagramViewStateError('expected a plain object', path);
+    }
+    return value as Record<string, unknown>;
+}
+
+function requireFiniteNumber(value: unknown, path: string): number {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new DiagramViewStateError('expected a finite number', path);
+    }
+    return value;
+}
+
+function requireBoolean(value: unknown, path: string): boolean {
+    if (typeof value !== 'boolean') throw new DiagramViewStateError('expected a boolean', path);
+    return value;
+}

package/src/diagram/api.ts

@@ -0,0 +1,257 @@
+import type { DiagramDocument } from '../core/model.js';
+import type {
+    DiagramRuntimeState,
+    DiagramSelection,
+    DiagramViewState,
+} from '../core/state.js';
+import type { DiagramNode, Link, Port, PortDirection } from './types.js';
+
+export interface DiagramOptions {
+    div: HTMLElement;
+    catalog: import('./catalog.js').StockSharpCatalog;
+    /** Show the built-in top-right fullscreen request button. Defaults to true. */
+    showFullscreenButton?: boolean;
+    overviewContainer?: HTMLElement | null;
+    zoomLabel?: HTMLElement | null;
+    /** Optional system clipboard adapter. Pass null to force memory-only clipboard. */
+    clipboard?: DiagramClipboard | null;
+    /** Snap pointer-dragged nodes to the grid. Defaults to true. */
+    gridSnap?: boolean;
+    /** Positive world-space grid step. Defaults to 28. */
+    gridSize?: number;
+}
+
+export interface DiagramGridSettings {
+    enabled: boolean;
+    size: number;
+}
+
+export interface DiagramPoint {
+    x: number;
+    y: number;
+}
+
+export interface DiagramNodeBounds extends DiagramPoint {
+    width: number;
+    height: number;
+}
+
+export type DiagramScreenshotScope = 'viewport' | 'content';
+
+export interface DiagramScreenshotOptions {
+    /** Current viewport or the complete graph bounds. Defaults to viewport. */
+    scope?: DiagramScreenshotScope;
+    /** World-to-CSS-pixel scale for content export. Defaults to 1. */
+    scale?: number;
+    /** CSS-pixel padding around content export. Defaults to 32. */
+    padding?: number;
+    /** Output pixel density. Defaults to the current device pixel ratio. */
+    pixelRatio?: number;
+    /** Optional export-only background override. */
+    background?: string;
+    /** Defaults to true. */
+    includeGrid?: boolean;
+    /** Defaults to the current value for viewport and false for content. */
+    includeOverview?: boolean;
+    /** Defaults to true for viewport and false for content. */
+    includeSelection?: boolean;
+    /** Include debugger and error state. Defaults to true. */
+    includeRuntimeState?: boolean;
+}
+
+export interface DiagramClipboard {
+    readText(): Promise<string>;
+    writeText(value: string): Promise<void>;
+}
+
+export interface DiagramThemeOptions {
+    diagramBackground?: string;
+    overviewBackground?: string;
+    gridColor?: string;
+    linkMaxLightness?: number;
+    overviewBorderColor?: string;
+    overviewViewportColor?: string;
+    overviewViewportFill?: string;
+}
+
+export type NodeErrorKind = 'runtime' | 'load';
+
+export interface NodeErrorOptions {
+    kind?: NodeErrorKind;
+    animate?: boolean;
+}
+
+export interface DiagramLoadOptions {
+    /** Transient per-node errors discovered while restoring a scheme. */
+    nodeErrors?: Readonly<Record<string, string>>;
+}
+
+export interface DocumentLoadFailedPayload {
+    message: string;
+    error: Error;
+}
+
+export interface FullscreenChangedPayload {
+    fullscreen: boolean;
+}
+
+/** Requested host layout state. The component never enters fullscreen itself. */
+export interface FullscreenRequestedPayload {
+    fullscreen: boolean;
+}
+
+export type ContextCommand = 'undo' | 'redo' | 'cut' | 'copy' | 'paste' | 'open' | 'delete' | 'properties' | 'help';
+
+export interface ContextCommandPayload {
+    command: ContextCommand;
+    nodes: DiagramNode[];
+    links: Link[];
+}
+
+export interface ContextCommandState {
+    command: ContextCommand;
+    enabled: boolean;
+}
+
+export interface ContextMenuRequestedPayload {
+    x: number;
+    y: number;
+    node: DiagramNode | null;
+    link: Link | null;
+    port: Port | null;
+    portDirection: PortDirection | null;
+    commands: ContextCommandState[];
+}
+
+export interface NodeSelectedPayload {
+    node: DiagramNode;
+    selected: boolean;
+}
+
+export interface NodeHoverPayload {
+    node: DiagramNode;
+    hovering: boolean;
+}
+
+export interface PortSelectedPayload {
+    node: DiagramNode;
+    port: Port;
+    direction: PortDirection;
+}
+
+export interface PortHoverPayload extends PortSelectedPayload {
+    hovering: boolean;
+}
+
+export type PortClickAction = 'leftClick' | 'rightClick';
+
+export interface PortClickedPayload extends PortSelectedPayload {
+    action: PortClickAction;
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    metaKey: boolean;
+}
+
+export interface LinkSelectedPayload {
+    link: Link;
+    selected: boolean;
+}
+
+export interface LinkHoverPayload {
+    link: Link;
+    hovering: boolean;
+}
+
+export interface NodeMovedPayload {
+    node: DiagramNode;
+}
+
+export interface NodeChangePayload {
+    nodes: DiagramNode[];
+}
+
+export interface LinkChangePayload {
+    links: Link[];
+}
+
+export interface LinkRelinkedPayload {
+    link: Link;
+    previous: Link;
+}
+
+export interface LoadFinishedPayload {
+    nodes: DiagramNode[];
+    links: Link[];
+}
+
+export interface LinkValidationPayload {
+    fromNode: DiagramNode;
+    fromPort: Port;
+    toNode: DiagramNode;
+    toPort: Port;
+    allowed: boolean;
+    reason: LinkValidationReason;
+}
+
+export type LinkValidationReason =
+    | 'allowed'
+    | 'missing-link'
+    | 'missing-node'
+    | 'missing-port'
+    | 'same-node'
+    | 'invalid-direction'
+    | 'incompatible-type'
+    | 'duplicate-link'
+    | 'source-limit'
+    | 'target-limit'
+    | 'host-rejected';
+
+export interface LinkValidationResult {
+    allowed: boolean;
+    reason: LinkValidationReason;
+}
+
+export interface LinkValidatorArgs {
+    fromNode: DiagramNode;
+    fromPort: Port;
+    toNode: DiagramNode;
+    toPort: Port;
+}
+
+export type LinkValidator = (args: LinkValidatorArgs) => boolean;
+
+export interface DiagramEvents extends Record<string, unknown> {
+    nodeAdded: NodeChangePayload;
+    nodeRemoved: NodeChangePayload;
+    linkAdded: LinkChangePayload;
+    linkRemoved: LinkChangePayload;
+    linkRelinked: LinkRelinkedPayload;
+    nodeMoved: NodeMovedPayload;
+    nodeSelected: NodeSelectedPayload;
+    nodeHover: NodeHoverPayload;
+    portSelected: PortSelectedPayload;
+    portClicked: PortClickedPayload;
+    portHover: PortHoverPayload;
+    linkSelected: LinkSelectedPayload;
+    linkHover: LinkHoverPayload;
+    linkValidation: LinkValidationPayload;
+    loadFinished: LoadFinishedPayload;
+    contextCommand: ContextCommandPayload;
+    contextMenuRequested: ContextMenuRequestedPayload;
+    undoRequested: NodeChangePayload & LinkChangePayload;
+    redoRequested: NodeChangePayload & LinkChangePayload;
+    nodeEdit: NodeChangePayload;
+    nodeProperties: NodeChangePayload;
+    nodeOpen: NodeChangePayload;
+    nodeHelp: NodeChangePayload;
+    zoomChanged: DiagramViewState;
+    viewChanged: DiagramViewState;
+    selectionChanged: DiagramSelection;
+    runtimeStateChanged: { state: DiagramRuntimeState };
+    undoStackChanged: { canUndo: boolean; canRedo: boolean };
+    documentLoaded: { document: DiagramDocument };
+    documentLoadFailed: DocumentLoadFailedPayload;
+    fullscreenRequested: FullscreenRequestedPayload;
+    fullscreenChanged: FullscreenChangedPayload;
+}

package/src/diagram/catalog.ts

@@ -0,0 +1,55 @@
+import { EventEmitter } from './event-emitter.js';
+import { Node, NodeInit, PortType, PortTypeInit } from './types.js';
+
+export interface CatalogEvents extends Record<string, unknown> {
+    portTypesChanged: PortType[];
+    nodeTypesChanged: Node[];
+}
+
+export class StockSharpCatalog extends EventEmitter<CatalogEvents> {
+    private readonly portTypes = new Map<string, PortType>();
+    private readonly nodeTypes = new Map<string, Node>();
+
+    addPortType(portType: PortType | PortTypeInit): void {
+        const pt = portType instanceof PortType ? portType : new PortType(portType);
+        this.portTypes.set(pt.name, pt);
+        this.emit('portTypesChanged', this.getPortTypes());
+    }
+
+    removePortType(name: string): void {
+        this.portTypes.delete(name);
+        this.emit('portTypesChanged', this.getPortTypes());
+    }
+
+    getPortType(name: string): PortType | null {
+        return this.portTypes.get(name) ?? null;
+    }
+
+    getPortTypes(): PortType[] {
+        return Array.from(this.portTypes.values());
+    }
+
+    // Keyed by lower-cased typeId: element GUIDs are case-insensitive,
+    // but the seeded palette uses upper-case while desktop-schema imports
+    // serialize lower-case. A case-sensitive Map.get would miss every
+    // 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);
+        this.nodeTypes.set(n.id.toLowerCase(), n);
+        this.emit('nodeTypesChanged', this.getNodeTypes());
+    }
+
+    removeNodeType(id: string): void {
+        this.nodeTypes.delete(id.toLowerCase());
+        this.emit('nodeTypesChanged', this.getNodeTypes());
+    }
+
+    getNodeType(id: string): Node | null {
+        return this.nodeTypes.get(id.toLowerCase()) ?? null;
+    }
+
+    getNodeTypes(): Node[] {
+        return Array.from(this.nodeTypes.values());
+    }
+}

package/src/diagram/event-emitter.ts

@@ -0,0 +1,44 @@
+export type EventHandler<T> = (payload: T) => void;
+
+export class EventEmitter<TEvents extends Record<string, unknown>> {
+    private readonly handlers = new Map<keyof TEvents, Set<EventHandler<unknown>>>();
+
+    on<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): () => void {
+        let set = this.handlers.get(event);
+        if (set === undefined) {
+            set = new Set();
+            this.handlers.set(event, set);
+        }
+        set.add(handler as EventHandler<unknown>);
+        return () => this.off(event, handler);
+    }
+
+    off<K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>): void {
+        const set = this.handlers.get(event);
+        if (set === undefined) {
+            return;
+        }
+        set.delete(handler as EventHandler<unknown>);
+        if (set.size === 0) {
+            this.handlers.delete(event);
+        }
+    }
+
+    protected emit<K extends keyof TEvents>(event: K, payload: TEvents[K]): void {
+        const set = this.handlers.get(event);
+        if (set === undefined) {
+            return;
+        }
+        for (const handler of set) {
+            try {
+                (handler as EventHandler<TEvents[K]>)(payload);
+            } catch (err) {
+                console.error(err);
+            }
+        }
+    }
+
+    protected clearEventHandlers(): void {
+        this.handlers.clear();
+    }
+}