DiagramCanvasComponent

Import it from @grafloria/angular.

DiagramCanvasComponent

Standalone, OnPush, signal-based Angular canvas over the framework-agnostic SVGRenderer + engine. A thin shell on purpose: every decision it makes is delegated down into @grafloria/renderer (InteractionController, SVGRenderer, applyNodes/applyEdges) or @grafloria/engine (commands, IncrementalCapture).

Inputs are input() / model() signals, outputs are output(): no NgZone dependency, no EventEmitter, so the component runs under provideZonelessChangeDetection(). Everything the template binds is a signal (marquee, htmlNodes, htmlLayerTransform, linkToolbarTarget) — that is what lets the zoneless scheduler see a change with no zone tick. The SVG layer is painted imperatively (VNode → DOM patcher) and never went through change detection at all.

viewport and zoom are model() signals because the canvas WRITES them (pan, cursor-anchored zoom, fit-to-content), so [(zoom)] / [(viewport)] round-trip. zoomChanged / viewportChanged are kept alongside for backwards compatibility (viewportChanged emits the VISIBLE world rect — the viewBox — whereas the model's viewportChange emits the camera rect the viewport input IS).

Two modes, both supported:

• Uncontrolled (legacy): bind [engine] and mutate the engine yourself. Unchanged behaviour.
• Controlled: bind [(nodes)] / [(edges)] — the same NodeSpec / EdgeSpec data the React wrapper and <grafloria-flow> take. They are reconciled against the live model by applyNodes / applyEdges from @grafloria/renderer (the shared reconciler — Angular does not get a second diff algorithm), and model mutations come back out as nodesChange / edgesChange (the next array — Angular's two-way contract) plus modelChange (a DiagramIncremental: precisely which entities were added / removed / modified — GoJS's IncrementalData). [skipModelUpdate]="true" suspends the inbound half (GoJS's skipsDiagramUpdate).

ts
Copy
@Component({
    selector: 'grafloria-diagram-canvas',
    imports: [CommonModule, HtmlNodeRendererDirective, GrafloriaHandleDirective, LinkToolbarComponent],
    templateUrl: './diagram-canvas.component.html',
    styleUrls: ['./diagram-canvas.component.css'],
    changeDetection: ChangeDetectionStrategy.OnPush
})
export class DiagramCanvasComponent implements AfterViewInit, OnDestroy

Use it as <grafloria-diagram-canvas> in a template.

Inputs

Outputs

• nodesChange
• edgesChange
• viewportChange
• zoomChange
• collabReady — The live SyncAdapter, right after join().
• layoutDone — Fires after each declarative or imperative layout completes.
• viewportChanged — The VISIBLE world rect (the SVG viewBox) after a pan/zoom. NOT the same as the
• zoomChanged — Zoom after a pan/zoom gesture. (zoomChange is the two-way twin.)
• modelChange — The incremental patch describing what the MODEL just changed — added /
• selectionChange — The selection changed: the selected nodes and edges AFTER the change. Same

Properties

Methods

• nodeTemplateFor(node: any): TemplateRef<GrafloriaNodeTemplateContext> | null
• nodeTemplateContext(node: any): GrafloriaNodeTemplateContext
• getCommentStore(): CommentStore | null — The live comment store, when [comments] is enabled.
• viewportController(): ViewportController | undefined — The live viewport controller — the world↔screen transform this canvas is painting with. Use it to anchor HTML overlays (floating toolbars, badges, callouts) to world coordinates: viewportController().worldToClient(x, y, hostRect) returns client pixels, and onChange fires on every pan/zoom so the overlay can re-anchor. Same instance the minimap/controls plugins drive, so overlays and plugins stay in lockstep. Returns undefined only before the view initialises.
• async applyLayout(request?: string | GrafloriaLayoutRequest): Promise<unknown | undefined> — Re-run the bound layout, or run any registry layout imperatively.
• exportDiagram( format: 'svg' | 'png' | 'jpeg' | 'webp' | 'pdf' = 'svg', options: ExportOptions = {} ): Promise<string> — Async export — the full pipeline, the same one createDiagram().export() runs.
• exportSvg(options: ExportOptions = {}): SvgExportResult — Synchronous SVG export. Custom nodes are captured from the HTML node layer as they stand now; NOTHING is fetched, so an external image stays a URL (with a warning) — use await exportDiagram('svg') to embed it, or pass options.resolvedAssets.
• exportPdf(options: ExportOptions = {}): PdfExportResult — Synchronous vector-PDF export. Custom nodes are captured as they stand now; nothing is fetched, so an external image is MISSING from the PDF (and reported in warnings) — use await exportDiagram('pdf') to embed it.
• snapshot(): SerializedDiagram | null — Serialize the current diagram — feed the result back to loadSnapshot.
• loadSnapshot(data: SerializedDiagram): void — Restore a snapshot()-ed document by reconciling INTO the live diagram — applyNodes/applyEdges are full reconcilers, so removals happen and the renderer, listeners, and plugins stay attached to the same model.
• exportText(options?: unknown): string — Mermaid-compatible text export (lossless sidecar by default).
• loadText(text: string, options?: unknown): unknown — Parse Mermaid-compatible text (sidecar-aware) and reconcile it into the live diagram — same mechanics as loadSnapshot.
• get effectiveLinkToolbarActions(): LinkToolbarAction[]
• onLinkToolbarPointerOver(isOver: boolean): void
• constructor()
• ngAfterViewInit(): void
• ngOnDestroy(): void
• flushModelChange(): void — Force the pending outbound emission to happen NOW (tests, imperative hosts).
• get overlayViewBox(): string — viewBox for the world-space overlay
• get overlayStroke(): number — Stroke width that stays 1 CSS px in a world-space overlay.
• handleSide(handle: ToolHandle): number — Square side of a tool handle in world units (constant on screen).
• get overlayFontSize(): number — Font size for overlay glyphs/labels, constant on screen.
• toolGlyph(handle: ToolHandle): string — Glyph drawn inside a click-tool button.
• get toolFrameTransform(): string | null — SVG transform that rotates the selection frame with a rotated node.
• highlighterTransform(h: Highlighter): string | null — Rotation transform for one highlighter box (rotated nodes).
• pointsAttr(points?: Point[]): string — Polyline points attribute for a link highlighter / focus ring.
• spacingLabelX(segment: { x1: number; x2: number }): number — Midpoint of a spacing segment (where its distance label is drawn).
• spacingLabelY(segment: { y1: number; y2: number }): number
• undo(): Promise<void> — Undo the last command (Ctrl/Cmd+Z).
• redo(): Promise<void> — Redo the last undone command (Ctrl/Cmd+Shift+Z or Ctrl+Y).
• copySelection(): Promise<void> — Copy the selection to the clipboard (Ctrl/Cmd+C).
• cutSelection(): Promise<void> — Cut the selection: clipboard + delete, as ONE undo step (Ctrl/Cmd+X).
• deleteSelection(): Promise<void> — Delete the selection as ONE undo step (Delete / Backspace).
• pasteClipboard(): Promise<void> — Paste the clipboard, dropping it under the cursor (Ctrl/Cmd+V).
• scheduleRender(): void — The ONE coalescing entry point for every re-render.
• getPerformanceMetrics(): { fps: number; frameTime: number; droppedFrames: number; sampleCount: number; } — Real render-loop metrics, computed from the ring buffers (replaces any hardcoded/estimated FPS). - fps: rolling frames-per-second across the last N painted frames - frameTime: average render duration (ms) over the same window - droppedFrames: cumulative frames whose render blew the ~60fps budget - sampleCount: number of frames currently in the window
• @HostListener('window:keyup', ['$event']) onKeyUp(event: KeyboardEvent): void — Handle keyup to exit pan mode (Space key)
• @HostListener('wheel', ['$event']) onWheel(event: WheelEvent): void — Wheel: ctrl/⌘ (and trackpad pinch, which the browser reports as ctrl+wheel) ZOOMS at the cursor; a plain wheel SCROLLS the canvas (shift → horizontal). This is the Figma/Miro/VS Code convention — the previous behaviour zoomed on every wheel event around the viewport CENTRE, which is the "feels wrong" competitors were compared against.
• zoomAtClient(targetZoom: number, clientX: number, clientY: number): void — Zoom to targetZoom keeping the world point under (clientX, clientY) pinned to that same screen pixel.
• zoomBy(factor: number): void — Zoom keeping the canvas centre fixed (keyboard zoom, toolbar buttons).
• zoomIn(): void — Ctrl/⌘ + '='
• zoomOut(): void — Ctrl/⌘ + '-'
• resetZoom(): void — Ctrl/⌘ + '0' — back to 100%, canvas centre unchanged.
• fitToContent(padding = 40): void — Fit every node in the diagram into view (Shift+1) — and every group and lane FRAME, captions included: a frame reaches past its members (a pool's title strip and empty lanes), and fitting to node boxes alone clipped it. Picks the largest zoom (within [minZoom, maxZoom]) at which the content's bounding box fits inside the canvas with padding screen px to spare, then centres the viewport on that box.
• zoomToSelection(padding = 40): void — Fit the CURRENT SELECTION into view (Shift+2); falls back to everything.
• @HostListener('pointerdown', ['$event']) onPointerDown(event: PointerEvent): void — Pointer events — the primary pipeline (mouse, pen AND touch), mirroring DomEventBinder.onPointerDown/Move/Up/Cancel. Touch forks to the shared gesture controller; mouse/pen falls through to the existing ladder (a PointerEvent IS a MouseEvent, so the methods take it as-is).
• @HostListener('pointermove', ['$event']) onPointerMove(event: PointerEvent): void
• @HostListener('pointerup', ['$event']) onPointerUp(event: PointerEvent): void
• @HostListener('pointercancel', ['$event']) onPointerCancel(event: PointerEvent): void
• @HostListener('contextmenu', ['$event']) onContextMenu(event: MouseEvent): void — The native context menu: on touch the long-press already produced our own gesture, so the OS menu would sit on top of the canvas mid-interaction.
• @HostListener('mousedown', ['$event']) onCompatMouseDown(event: MouseEvent): void
• @HostListener('mousemove', ['$event']) onCompatMouseMove(event: MouseEvent): void
• @HostListener('mouseup', ['$event']) onCompatMouseUp(event: MouseEvent): void
• onMouseDown(event: MouseEvent): void — Handle mouse down for panning and node selection Supports: - Left click: Select/drag nodes - Ctrl + Left click: Multi-select - Middle mouse button: Pan - Space + Left click: Pan
• onMouseMove(event: MouseEvent): void — Handle mouse move for panning, node dragging, and hover
• onMouseUp(event: MouseEvent): void — Handle mouse up to stop panning, node dragging, and connections
• @HostListener('mouseleave') onCompatMouseLeave(): void — mouseleave stays UN-gated on sawPointerEvent (mirrors DomEventBinder: its cleanup is idempotent and there is no pointerleave twin wired), but it must never abort a live TOUCH gesture — the touch resize path drives the SAME SelectionToolsController this handler cancels.
• onMouseLeave(): void — Handle mouse leave to stop panning and node dragging
• @HostListener('dblclick', ['$event']) onDoubleClick(event: MouseEvent): void — Double-click on a link. - On a label: open an inline text editor in place. - On the link body: insert a waypoint at the double-clicked point.
• worldToScreen(worldX: number, worldY: number): { screenX: number; screenY: number } — Inverse of {@link clientToWorld}: world → canvas-local screen px. Exposed (public) because it is the invariant the cursor-anchored zoom is defined by, and the zoom tests assert on it.
• @HostListener('window:keydown', ['$event']) onKeyDown(event: KeyboardEvent): void — Handle keyboard events (Option 1: Node Interaction) - Space: Pan mode cursor - Delete/Backspace: Delete selection (undoable) - Escape: Clear selection - Ctrl+A: Select all
• getAbsoluteX(node: any): number — Get absolute X position for a node (including parent offset and transforms) CRITICAL FIX: Use getWorldPosition() for simple cases, getGlobalPosition() for transforms This properly handles rotation, scale, and nested hierarchies
• getAbsoluteY(node: any): number — Get absolute Y position for a node (including parent offset and transforms) CRITICAL FIX: Use getWorldPosition() for simple cases, getGlobalPosition() for transforms This properly handles rotation, scale, and nested hierarchies
• getNodeX(node: any): number — Get node X position for HTML rendering — in WORLD units.
• getNodeY(node: any): number — Get node Y position for HTML rendering — in WORLD units (see getNodeX).
• shouldRenderPort(port: PortModel, node: NodeModel): boolean — Check if a port should be rendered as an HTML handle Respects port visibility settings and template configuration
• getPortPosition(port: PortModel, node: NodeModel, axis: 'top' | 'left'): string — Get port position CSS value for top or left CRITICAL FIX: Use shape-aware positioning from getPortPositionForShape() This ensures HTML ports align with SVG ports for all shape types

Example

html
Copy
<!-- uncontrolled -->
<grafloria-diagram-canvas [engine]="engine" [(zoom)]="zoom" />

<!-- controlled -->
<grafloria-diagram-canvas
  [(nodes)]="nodes"
  [(edges)]="edges"
  (modelChange)="persist($event)" />