Engine

Import these from @grafloria/engine.

Functions

isValidDiagramMode

Type guard to check if a string is a valid DiagramMode

ts
Copy
function isValidDiagramMode(mode: string): mode is DiagramMode

Classes

DiagramEngine

ts
Copy
class DiagramEngine

Properties

Methods

• constructor(config: DiagramEngineConfig = {})
• getDiagram(): DiagramModel | null — Get current diagram
• getConfig(): DiagramEngineConfig — Get configuration
• getInteractionConfig(): InteractionConfig — Get interaction configuration Returns the current interaction mode settings
• setInteractionConfig(config: Partial<InteractionConfig>): void — Set interaction configuration Updates interaction mode settings and emits event
• getConnectionStateManager(): ConnectionStateManager — Get connection state manager Used for managing connection drag operations
• getReconnectionPreview(): ReconnectionPreview | null — Current endpoint-reconnection preview, or null when no endpoint is being dragged. The renderer reads this to draw a ghost link.
• setReconnectionPreview(preview: ReconnectionPreview | null): void — Set (or clear, with null) the endpoint-reconnection preview. Called by the interaction layer on start/move/end of an endpoint drag. Does not emit — the interaction layer already triggers re-render.
• getProximityPreview(): ProximityPreview | null — The proximity-connect proposal the renderer draws as a live wire, or null.
• setProximityPreview(preview: ProximityPreview | null): void — Set (or clear, with null) the proximity-connect proposal. Does not emit — the node drag that drives it already triggers re-renders.
• getSnapGuides(): SnapGuideSegment[] | null — The live snap-guide segments a node drag is showing, or null.
• setSnapGuides(guides: SnapGuideSegment[] | null): void — Set (or clear, with null) the live snap guides. Does not emit — the node drag that drives them already triggers re-renders.
• getRoutingEngine(): RoutingEngine — Get routing engine Used for calculating link paths with various algorithms
• enableLiveRerouting(): void — Enable live rerouting Automatically updates link paths when nodes move or resize
• disableLiveRerouting(): void — Disable live rerouting
• getLiveReroutingEngine(): LiveReroutingEngine | null — Get live rerouting engine
• setDiagram(diagram: DiagramModel | null): void — Set diagram
• createDiagram(name: string = 'Untitled'): DiagramModel — Create new diagram
• clearDiagram(): void — Clear diagram
• async addNode(config: { type: string; position: Point; size?: Size; data?: any; }): Promise<NodeModel> — Add node (from config) Add node (pre-created NodeModel) Add node implementation
• async addNode(node: NodeModel): Promise<NodeModel> — Add node (from config) Add node (pre-created NodeModel) Add node implementation
• async addNode(configOrNode: { type: string; position: Point; size?: Size; data?: any } | NodeModel): Promise<NodeModel> — Add node (from config) Add node (pre-created NodeModel) Add node implementation
• async removeNode(nodeId: string): Promise<void> — Remove node
• async addLink(config: { sourcePortId: string; targetPortId: string; type?: string; data?: any; }): Promise<LinkModel> — Add link
• async removeLink(linkId: string): Promise<void> — Remove link
• async addGroup(config: { name: string }): Promise<GroupModel> — Add group
• async removeGroup(groupId: string): Promise<void> — Remove group
• async addToGroup(groupId: string, entityId: string): Promise<void> — Add entity to group
• async removeFromGroup(groupId: string, entityId: string): Promise<void> — Remove entity from group
• async expandGroup(groupId: string): Promise<void> — Expand group
• async collapseGroup(groupId: string, options?: CollapseOptions): Promise<void> — Collapse group
• getGroup(groupId: string): GroupModel | undefined — Get group by ID
• getGroups(): GroupModel[] — Get all groups
• async setLayout( groupId: string, layoutType: 'flexbox' | 'grid', layoutConfig: LayoutConfig ): Promise<void> — Set layout configuration on a group
• async clearLayout(groupId: string): Promise<void> — Clear layout configuration from a group
• getLayout(groupId: string): { type: LayoutType; config?: LayoutConfig } | undefined — Get layout configuration from a group
• async setFlexItem(nodeId: string, flexConfig: FlexItemConfig): Promise<void> — Set flex item configuration on a node
• async setGridItem(nodeId: string, gridConfig: GridItemConfig): Promise<void> — Set grid item configuration on a node
• async copy(options?: { includeGroups?: boolean; includeLinks?: boolean }): Promise<void> — Copy selected entities to clipboard
• async paste(options?: { offset?: Point; selectPasted?: boolean }): Promise<void> — Paste entities from clipboard
• async duplicate(options?: { offset?: Point; selectDuplicated?: boolean }): Promise<void> — Duplicate selected entities
• async deleteSelection(options?: { deleteChildren?: boolean; deleteLinks?: boolean }): Promise<void> — Delete selected entities
• getClipboardData() — Get clipboard data
• hasClipboardData(): boolean — Check if clipboard has data
• clearClipboard(): void — Clear clipboard
• getClipboardStats() — Get clipboard statistics
• validateDiagram(options?: { validateTypes?: boolean; validateConnections?: boolean; validatePorts?: boolean; strict?: boolean }): ValidationResult — Validate the entire diagram
• validateNode(nodeId: string, options?: { validateTypes?: boolean; validateConnections?: boolean; validatePorts?: boolean; strict?: boolean }): ValidationResult — Validate a specific node
• validateLink(linkId: string, options?: { validateTypes?: boolean; validateConnections?: boolean; validatePorts?: boolean; strict?: boolean }): ValidationResult — Validate a specific link
• validatePort(portId: string, nodeId: string, options?: { validateTypes?: boolean; validateConnections?: boolean; validatePorts?: boolean; strict?: boolean }): ValidationResult — Validate a specific port
• validateLayout(groupId: string, options?: { strict?: boolean }): ValidationResult — Validate layout configuration for a group
• registerNodeType(definition: NodeTypeDefinition): void — Register a node type definition
• registerPortType(definition: PortTypeDefinition): void — Register a port type definition
• registerLinkType(definition: LinkTypeDefinition): void — Register a link type definition
• registerGroupType(definition: GroupTypeDefinition): void — Register a group type definition
• enableRealTimeValidation(): void — Enable real-time validation
• disableRealTimeValidation(): void — Disable real-time validation
• isRealTimeValidationEnabled(): boolean — Check if real-time validation is enabled
• selectNodes(nodeIds: string[]): void — Select nodes
• selectLinks(linkIds: string[]): void — Select links
• clearSelection(): void — Clear selection
• async undo(): Promise<void> — Undo
• async redo(): Promise<void> — Redo
• canUndo(): boolean — Can undo
• canRedo(): boolean — Can redo
• validate(): ValidationResult — Validate diagram
• serialize(): SerializedDiagram | null — Serialize diagram (with mode)
• deserialize(data: SerializedDiagram, options?: import('../models/DiagramModel').DiagramLoadOptions): DiagramModel — Deserialize diagram (with mode)
• loadFromJSON( json: string | SerializedDiagram, options?: import('../models/DiagramModel').DiagramLoadOptions ): DiagramModel — Load diagram from JSON (with mode)
• saveToJSON(): string | null — Save diagram to JSON
• async registerPlugin(plugin: Plugin): Promise<void> — Register a plugin AND bring it to life.
• getPlugin(name: string): Plugin | undefined — Get plugin
• setViewport(viewport: Viewport): void — Set viewport
• setZoom(zoom: number): void — Set zoom
• getPerformanceReport(): PerformanceReport — Get performance report
• getMode(): DiagramMode — Get current diagram mode
• setMode(mode: DiagramMode): void — Set diagram mode
• isDesignerMode(): boolean — Check if in designer mode
• isRunningMode(): boolean — Check if in running mode
• isViewMode(): boolean — Check if in view mode
• isDebugMode(): boolean — Check if in debug mode
• isPresentationMode(): boolean — Check if in presentation mode
• isReadOnlyMode(): boolean — Check if in read-only mode (any mode except designer)
• addModeGuard(name: string, guard: ModeGuardFunction): void — Add mode transition guard
• removeModeGuard(name: string): void — Remove mode transition guard
• clearModeGuards(): void — Clear all mode transition guards
• configureModeViewport(mode: DiagramMode, settings: ModeViewportSettings): void — Configure viewport settings for specific mode
• getModeViewportSettings(mode: DiagramMode): ModeViewportSettings — Get viewport settings for specific mode
• getModeHistory(): ModeHistoryEntry[] — Get mode history
• clearModeHistory(): void — Clear mode history
• previousMode(): void — Navigate to previous mode
• nextMode(): void — Navigate to next mode
• pushMode(mode: DiagramMode): void — Push mode onto stack (save current, switch to new)
• popMode(): void — Pop mode from stack (return to previous)
• getModeAnalytics(): ModeAnalytics — Get mode analytics
• beforeModeChange(hook: ModeChangeHook): () => void — Register before mode change hook
• afterModeChange(hook: ModeChangeHook): () => void — Register after mode change hook
• getLinkBehaviorForMode(baseBehavior: Partial<{ deletable: boolean; selectable: boolean }>): { deletable: boolean; selectable: boolean; } — Get link behavior adjusted for current mode
• initialize(): void — Initialize the engine
• getStore(): DiagramStore — Get the store
• on(event: string, listener: (...args: any[]) => void): void — Subscribe to events
• off(event: string, listener: (...args: any[]) => void): void — Unsubscribe from events
• destroy(): void — Destroy engine
• refreshGroupObstacles(): void — Reconcile the shared ObstacleMap with the diagram's GROUP state, idempotently:
• setLayoutService(service: { applyLayout(diagram: DiagramModel, config: any): Promise<any>; }): void — Set layout service for diagram layouts
• getLayoutRegistry(): LayoutRegistry — The named-algorithm registry, with the built-ins already registered.
• async layout( name: string = DEFAULT_LAYOUT_NAME, options: UnifiedLayoutOptions = {} ): Promise<UnifiedLayoutResult> — Lay out the whole diagram.
• async layoutIncremental( options: IncrementalOptions & { name?: string } & UnifiedLayoutOptions = {} ): Promise<UnifiedLayoutResult & { movement: MovementReport; tween: TweenPlan }> — Mental-map-preserving incremental layout.
• setLayoutPort(port?: LayoutPort): void — Run layout off the main thread.
• async applyLayout(config: { adapter: string | any; options?: any; animate?: boolean; animationDuration?: number; fit?: boolean; canvasDimensions?: { width: number; height: number }; }): Promise<{ nodePositions: Map<string, { x: number; y: number }>; bounds: { x: number; y: number; width: number; height: number }; metadata?: any; }> — Apply layout to current diagram
• async applyDagreLayout( options?: { rankdir?: 'TB' | 'BT' | 'LR' | 'RL'; align?: 'UL' | 'UR' | 'DL' | 'DR'; nodesep?: number; edgesep?: number; ranksep?: number; marginx?: number; marginy?: number; ranker?: 'network-simplex' | 'tight-tree' | 'longest-path'; }, canvasDimensions?: { width: number; height: number } ): Promise<any> — Quick helper: Apply Dagre layout
• async applyELKLayout( options?: { algorithm?: 'layered' | 'force' | 'stress' | 'mrtree' | 'radial' | 'disco'; 'elk.direction'?: 'RIGHT' | 'LEFT' | 'DOWN' | 'UP'; 'elk.spacing.nodeNode'?: number; [key: string]: any; }, canvasDimensions?: { width: number; height: number } ): Promise<any> — Quick helper: Apply ELK layout
• dispose(): void — Cleanup and dispose of all resources Should be called when the engine is no longer needed

Interfaces

DiagramEngineConfig

ts
Copy
interface DiagramEngineConfig

Properties

ModeChangeEvent

Mode change event payload

ts
Copy
interface ModeChangeEvent

Properties

ProximityPreview

The port pair a proximity-connect DROP would link, while a node drag is inside the radius. The renderer reads this to draw the proposed wire itself, not only the two ports. Same seam shape as {@link ReconnectionPreview}: interaction layer writes, renderer reads, cleared on drop/cancel.

ts
Copy
interface ProximityPreview

Properties

ReconnectionPreview

Transient state for the endpoint-reconnection live preview. Set by the interaction layer while an endpoint handle is being dragged; read by the renderer to draw a ghost link from the stationary endpoint to the cursor. Deliberately separate from {@link ConnectionStateManager} (which owns NEW-link creation) so the two previews never double-render.

ts
Copy
interface ReconnectionPreview

Properties

SnapGuideSegment

One drawable snap-guide segment, in world coordinates. The interaction layer computes alignment / equal-spacing guides during a node drag and publishes them here; the renderer draws them as dashed overlay lines (spacing segments may carry a gap label). Cleared (null) when the drag ends or nothing is within snapping distance.

ts
Copy
interface SnapGuideSegment

Properties

Enums

DiagramMode

Diagram mode enum - defines the operational mode of the diagram engine

ts
Copy
enum DiagramMode

Members

• DESIGNER = 'designer' — Designer mode - Full editing capabilities (default) - All node/link operations enabled - Create, edit, delete, move, resize nodes - Create and delete links
• RUNNING = 'running' — Running mode - Execution/simulation mode - Editing disabled - Nodes selectable for execution flow visualization - No structural changes allowed
• VIEW = 'view' — View mode - Read-only viewing - All editing disabled - Nodes selectable for inspection - Pure viewing experience
• DEBUG = 'debug' — Debug mode - Debugging mode - Similar to running but with debug capabilities - Breakpoints, step-through, inspection - No structural changes allowed
• PRESENTATION = 'presentation' — Presentation mode - Clean presentation view - All editing disabled - Nodes selectable for navigation - Clean UI without clutter