@bpmnkit/canvas 0.0.8

package/dist/types.d.ts

@@ -0,0 +1,177 @@
+import type { BpmnDefinitions, BpmnDiEdge, BpmnDiShape, BpmnFlowElement, BpmnTextAnnotation } from "@bpmnkit/core";
+/** The color theme applied to the canvas. */
+export type Theme = "light" | "dark" | "auto";
+/**
+ * Controls how the diagram is initially positioned in the viewport.
+ * - `"contain"` — scale and center the diagram to fill the available space (default)
+ * - `"center"` — center without scaling
+ * - `"none"` — use the diagram's raw coordinates unchanged
+ */
+export type FitMode = "contain" | "center" | "none";
+/** Configuration options for {@link BpmnCanvas}. */
+export interface CanvasOptions {
+    /** The DOM element to mount the canvas into. */
+    container: HTMLElement;
+    /** BPMN 2.0 XML to render immediately. Can also be provided later via {@link BpmnCanvas.load}. */
+    xml?: string;
+    /**
+     * Color theme. Use `"auto"` to follow the OS preference (prefers-color-scheme).
+     * @default "auto"
+     */
+    theme?: Theme;
+    /**
+     * Show a dot-grid background on the infinite canvas.
+     * @default true
+     */
+    grid?: boolean;
+    /**
+     * How to position the diagram when first rendered.
+     * @default "contain"
+     */
+    fit?: FitMode;
+    /**
+     * Plugins to install. Each plugin receives a {@link CanvasApi} handle and
+     * can extend the canvas with editing, overlays, tooltips, or custom shapes.
+     * @see {@link CanvasPlugin}
+     */
+    plugins?: CanvasPlugin[];
+}
+/** The current pan/zoom state of the canvas viewport. */
+export interface ViewportState {
+    /** Horizontal translation in screen pixels. */
+    tx: number;
+    /** Vertical translation in screen pixels. */
+    ty: number;
+    /** Zoom scale factor. `1.0` = 100%, `0.5` = 50%, `2.0` = 200%. */
+    scale: number;
+}
+/** A rendered BPMN shape with its SVG element and source model data. */
+export interface RenderedShape {
+    /** The BPMN element ID. */
+    readonly id: string;
+    /** The SVG `<g>` element. */
+    readonly element: SVGGElement;
+    /** DI shape data — contains position and size. */
+    readonly shape: BpmnDiShape;
+    /** The matching BPMN flow element from the process model, if found. */
+    readonly flowElement: BpmnFlowElement | undefined;
+    /** Set if this shape represents a text annotation. */
+    readonly annotation?: BpmnTextAnnotation;
+}
+/** A rendered BPMN edge (sequence flow or association) with its SVG element. */
+export interface RenderedEdge {
+    /** The BPMN element ID. */
+    readonly id: string;
+    /** The SVG `<g>` element. */
+    readonly element: SVGGElement;
+    /** DI edge data — contains waypoints and optional label bounds. */
+    readonly edge: BpmnDiEdge;
+}
+/** Events emitted by {@link BpmnCanvas}. */
+export interface CanvasEvents {
+    /** Fired whenever the viewport is panned or zoomed. */
+    "viewport:change": (state: ViewportState) => void;
+    /** Fired when a BPMN element is clicked. */
+    "element:click": (id: string, event: PointerEvent) => void;
+    /** Fired when keyboard focus moves to a BPMN element. */
+    "element:focus": (id: string) => void;
+    /** Fired when keyboard focus leaves all BPMN elements. */
+    "element:blur": () => void;
+    /** Fired after a BPMN diagram is loaded and rendered. */
+    "diagram:load": (defs: BpmnDefinitions) => void;
+    /** Fired when the canvas is cleared. */
+    "diagram:clear": () => void;
+}
+/**
+ * The stable API surface exposed to plugins.
+ *
+ * Plugins receive a `CanvasApi` instance in their `install` method and use it
+ * to observe and interact with the canvas without accessing internals.
+ *
+ * @example
+ * ```typescript
+ * const hoverPlugin: CanvasPlugin = {
+ *   name: "hover-highlight",
+ *   install(api) {
+ *     api.on("element:click", (id) => {
+ *       const shape = api.getShapes().find((s) => s.id === id);
+ *       console.log("Clicked:", shape?.flowElement?.name ?? id);
+ *     });
+ *   },
+ * };
+ * ```
+ */
+export interface CanvasApi {
+    /** The host element passed to {@link CanvasOptions.container}. */
+    readonly container: HTMLElement;
+    /** The root `<svg>` element. */
+    readonly svg: SVGSVGElement;
+    /** The viewport `<g>` element. All diagram content lives inside this group. */
+    readonly viewportEl: SVGGElement;
+    /** Returns the current viewport state (pan + zoom). */
+    getViewport(): ViewportState;
+    /** Programmatically updates viewport. Missing fields are preserved. */
+    setViewport(state: Partial<ViewportState>): void;
+    /** Returns all currently rendered shapes. */
+    getShapes(): RenderedShape[];
+    /** Returns all currently rendered edges. */
+    getEdges(): RenderedEdge[];
+    /** Returns the current color theme. */
+    getTheme(): Theme;
+    /** Sets the color theme. Pass `"auto"` to follow the OS preference. */
+    setTheme(theme: Theme): void;
+    /**
+     * Subscribes to a canvas event. Returns an unsubscribe function.
+     *
+     * @example
+     * ```typescript
+     * const off = api.on("element:click", (id) => console.log(id));
+     * off(); // unsubscribe
+     * ```
+     */
+    on<K extends keyof CanvasEvents>(event: K, handler: CanvasEvents[K]): () => void;
+    /** Emits a canvas event. Intended for use by plugins and internal code. */
+    emit<K extends keyof CanvasEvents>(event: K, ...args: Parameters<CanvasEvents[K]>): void;
+}
+/**
+ * A plugin that extends `BpmnCanvas` without modifying the core.
+ *
+ * Plugins follow a simple install/uninstall lifecycle:
+ * 1. `install(api)` is called once when the plugin is registered.
+ * 2. `uninstall()` is called when the canvas is destroyed.
+ *
+ * Use `install` to hook into events, add overlays, or register keyboard shortcuts.
+ *
+ * @example
+ * ```typescript
+ * // Log all element clicks
+ * const logPlugin: CanvasPlugin = {
+ *   name: "click-logger",
+ *   install(api) {
+ *     api.on("element:click", (id, e) => {
+ *       console.log(`${id} clicked at (${e.clientX}, ${e.clientY})`);
+ *     });
+ *   },
+ * };
+ *
+ * const canvas = new BpmnCanvas({
+ *   container: document.getElementById("app")!,
+ *   plugins: [logPlugin],
+ * });
+ * ```
+ */
+export interface CanvasPlugin {
+    /** A unique name that identifies this plugin. */
+    readonly name: string;
+    /**
+     * Called once when the plugin is installed. Hook into canvas events here.
+     * @param api — The canvas API handle.
+     */
+    install(api: CanvasApi): void;
+    /**
+     * Called when the canvas is destroyed.
+     * Clean up any resources your plugin allocated (DOM nodes, timers, etc.).
+     */
+    uninstall?(): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/viewport.d.ts

@@ -0,0 +1,77 @@
+import type { ViewportState } from "./types.js";
+/**
+ * Controls the pan/zoom viewport of the canvas.
+ *
+ * Uses the Pointer Events API (covering mouse, touch, and pen) with
+ * `requestAnimationFrame`-batched rendering so interactions stay smooth at
+ * 60 fps with no perceptible input lag.
+ *
+ * - **Mouse**: left-button drag to pan, scroll wheel to zoom toward cursor.
+ * - **Touch**: one-finger drag to pan, two-finger pinch to zoom.
+ * - **Keyboard**: handled externally in `keyboard.ts` via `zoomAt` / `set`.
+ */
+export declare class ViewportController {
+    /** The host div — receives the `is-panning` CSS class. */
+    private readonly _host;
+    /** The SVG element that receives pointer/wheel events. */
+    private readonly _svg;
+    /** The `<g>` element whose `transform` attribute is updated. */
+    private readonly _group;
+    /** The dot-grid `<pattern>` element (optional). Kept in sync with the viewport. */
+    private readonly _gridPattern;
+    /** Called on every rendered frame with the new viewport state. */
+    private readonly _onChanged;
+    private _tx;
+    private _ty;
+    private _scale;
+    private _raf;
+    private _dirty;
+    private _dragging;
+    private _lastX;
+    private _lastY;
+    private _dragDist;
+    private _locked;
+    private _activePointers;
+    private _lastPinchDist;
+    constructor(
+    /** The host div — receives the `is-panning` CSS class. */
+    _host: HTMLElement, 
+    /** The SVG element that receives pointer/wheel events. */
+    _svg: SVGSVGElement, 
+    /** The `<g>` element whose `transform` attribute is updated. */
+    _group: SVGGElement, 
+    /** The dot-grid `<pattern>` element (optional). Kept in sync with the viewport. */
+    _gridPattern: SVGPatternElement | null, 
+    /** Called on every rendered frame with the new viewport state. */
+    _onChanged: (state: ViewportState) => void);
+    /** Current viewport state snapshot. */
+    get state(): ViewportState;
+    /**
+     * When locked, pointer-down is ignored (no new pan starts) and pointer-move
+     * does not continue any in-progress pan. Scroll-wheel zoom is unaffected.
+     */
+    lock(locked: boolean): void;
+    /**
+     * Whether the last pointer interaction was a drag (as opposed to a click).
+     * The canvas uses this to suppress `element:click` events after panning.
+     */
+    get didPan(): boolean;
+    /** Programmatically sets viewport state. Any omitted fields are unchanged. */
+    set(state: Partial<ViewportState>): void;
+    /**
+     * Zooms the viewport by `factor`, keeping the point at (`screenX`, `screenY`)
+     * fixed in screen space (zoom-toward-cursor behaviour).
+     */
+    zoomAt(screenX: number, screenY: number, factor: number): void;
+    /** Removes all event listeners and cancels any pending animation frame. */
+    destroy(): void;
+    private _scheduleApply;
+    private _apply;
+    private readonly _onWheel;
+    private readonly _onPointerDown;
+    private readonly _onPointerMove;
+    private readonly _onPointerUp;
+    private _bindEvents;
+    private _unbindEvents;
+}
+//# sourceMappingURL=viewport.d.ts.map

package/dist/viewport.js

@@ -0,0 +1,203 @@
+const MIN_SCALE = 0.05;
+const MAX_SCALE = 10;
+function clamp(v, min, max) {
+    return Math.max(min, Math.min(max, v));
+}
+/**
+ * Controls the pan/zoom viewport of the canvas.
+ *
+ * Uses the Pointer Events API (covering mouse, touch, and pen) with
+ * `requestAnimationFrame`-batched rendering so interactions stay smooth at
+ * 60 fps with no perceptible input lag.
+ *
+ * - **Mouse**: left-button drag to pan, scroll wheel to zoom toward cursor.
+ * - **Touch**: one-finger drag to pan, two-finger pinch to zoom.
+ * - **Keyboard**: handled externally in `keyboard.ts` via `zoomAt` / `set`.
+ */
+export class ViewportController {
+    _host;
+    _svg;
+    _group;
+    _gridPattern;
+    _onChanged;
+    _tx = 0;
+    _ty = 0;
+    _scale = 1;
+    _raf = null;
+    _dirty = false;
+    // Pan state
+    _dragging = false;
+    _lastX = 0;
+    _lastY = 0;
+    _dragDist = 0;
+    _locked = false;
+    // Pinch state
+    _activePointers = new Map();
+    _lastPinchDist = 0;
+    constructor(
+    /** The host div — receives the `is-panning` CSS class. */
+    _host, 
+    /** The SVG element that receives pointer/wheel events. */
+    _svg, 
+    /** The `<g>` element whose `transform` attribute is updated. */
+    _group, 
+    /** The dot-grid `<pattern>` element (optional). Kept in sync with the viewport. */
+    _gridPattern, 
+    /** Called on every rendered frame with the new viewport state. */
+    _onChanged) {
+        this._host = _host;
+        this._svg = _svg;
+        this._group = _group;
+        this._gridPattern = _gridPattern;
+        this._onChanged = _onChanged;
+        this._bindEvents();
+    }
+    /** Current viewport state snapshot. */
+    get state() {
+        return { tx: this._tx, ty: this._ty, scale: this._scale };
+    }
+    /**
+     * When locked, pointer-down is ignored (no new pan starts) and pointer-move
+     * does not continue any in-progress pan. Scroll-wheel zoom is unaffected.
+     */
+    lock(locked) {
+        this._locked = locked;
+    }
+    /**
+     * Whether the last pointer interaction was a drag (as opposed to a click).
+     * The canvas uses this to suppress `element:click` events after panning.
+     */
+    get didPan() {
+        return this._dragDist > 4;
+    }
+    /** Programmatically sets viewport state. Any omitted fields are unchanged. */
+    set(state) {
+        if (state.tx !== undefined)
+            this._tx = state.tx;
+        if (state.ty !== undefined)
+            this._ty = state.ty;
+        if (state.scale !== undefined)
+            this._scale = clamp(state.scale, MIN_SCALE, MAX_SCALE);
+        this._scheduleApply();
+    }
+    /**
+     * Zooms the viewport by `factor`, keeping the point at (`screenX`, `screenY`)
+     * fixed in screen space (zoom-toward-cursor behaviour).
+     */
+    zoomAt(screenX, screenY, factor) {
+        const newScale = clamp(this._scale * factor, MIN_SCALE, MAX_SCALE);
+        const ratio = newScale / this._scale;
+        this._tx = screenX - (screenX - this._tx) * ratio;
+        this._ty = screenY - (screenY - this._ty) * ratio;
+        this._scale = newScale;
+        this._scheduleApply();
+    }
+    /** Removes all event listeners and cancels any pending animation frame. */
+    destroy() {
+        this._unbindEvents();
+        if (this._raf !== null)
+            cancelAnimationFrame(this._raf);
+    }
+    // ── Private ──────────────────────────────────────────────────────
+    _scheduleApply() {
+        this._dirty = true;
+        if (this._raf === null) {
+            this._raf = requestAnimationFrame(() => {
+                this._raf = null;
+                if (this._dirty) {
+                    this._dirty = false;
+                    this._apply();
+                }
+            });
+        }
+    }
+    _apply() {
+        const t = `translate(${this._tx} ${this._ty}) scale(${this._scale})`;
+        this._group.setAttribute("transform", t);
+        if (this._gridPattern) {
+            this._gridPattern.setAttribute("patternTransform", t);
+        }
+        this._onChanged(this.state);
+    }
+    _onWheel = (e) => {
+        e.preventDefault();
+        const rect = this._svg.getBoundingClientRect();
+        const cx = e.clientX - rect.left;
+        const cy = e.clientY - rect.top;
+        // Normalise across deltaMode variants (pixels, lines, pages)
+        const delta = e.deltaMode === 1 ? e.deltaY * 24 : e.deltaMode === 2 ? e.deltaY * 400 : e.deltaY;
+        const factor = Math.exp(-delta * 0.001);
+        this.zoomAt(cx, cy, factor);
+    };
+    _onPointerDown = (e) => {
+        // Only pan with left mouse button (button=0) or touch/pen
+        if (e.pointerType === "mouse" && e.button !== 0)
+            return;
+        if (this._locked)
+            return;
+        this._activePointers.set(e.pointerId, e);
+        this._svg.setPointerCapture(e.pointerId);
+        this._dragDist = 0;
+        if (this._activePointers.size === 1) {
+            this._dragging = true;
+            this._lastX = e.clientX;
+            this._lastY = e.clientY;
+            this._host.classList.add("is-panning");
+        }
+    };
+    _onPointerMove = (e) => {
+        this._activePointers.set(e.pointerId, e);
+        if (this._locked)
+            return;
+        if (this._activePointers.size >= 2) {
+            // Two-finger pinch-to-zoom
+            const pts = [...this._activePointers.values()];
+            const a = pts[0];
+            const b = pts[1];
+            if (!a || !b)
+                return;
+            const dist = Math.hypot(a.clientX - b.clientX, a.clientY - b.clientY);
+            if (this._lastPinchDist > 0) {
+                const cx = (a.clientX + b.clientX) / 2;
+                const cy = (a.clientY + b.clientY) / 2;
+                const rect = this._svg.getBoundingClientRect();
+                this.zoomAt(cx - rect.left, cy - rect.top, dist / this._lastPinchDist);
+            }
+            this._lastPinchDist = dist;
+            return;
+        }
+        if (!this._dragging)
+            return;
+        const dx = e.clientX - this._lastX;
+        const dy = e.clientY - this._lastY;
+        this._dragDist += Math.abs(dx) + Math.abs(dy);
+        this._lastX = e.clientX;
+        this._lastY = e.clientY;
+        this._tx += dx;
+        this._ty += dy;
+        this._scheduleApply();
+    };
+    _onPointerUp = (e) => {
+        this._activePointers.delete(e.pointerId);
+        this._lastPinchDist = 0;
+        if (this._activePointers.size === 0) {
+            this._dragging = false;
+            this._host.classList.remove("is-panning");
+        }
+    };
+    _bindEvents() {
+        this._svg.addEventListener("wheel", this._onWheel, { passive: false });
+        this._svg.addEventListener("pointerdown", this._onPointerDown);
+        this._svg.addEventListener("pointermove", this._onPointerMove);
+        this._svg.addEventListener("pointerup", this._onPointerUp);
+        this._svg.addEventListener("pointercancel", this._onPointerUp);
+    }
+    _unbindEvents() {
+        this._svg.removeEventListener("wheel", this._onWheel);
+        this._svg.removeEventListener("pointerdown", this._onPointerDown);
+        this._svg.removeEventListener("pointermove", this._onPointerMove);
+        this._svg.removeEventListener("pointerup", this._onPointerUp);
+        this._svg.removeEventListener("pointercancel", this._onPointerUp);
+    }
+}
+//# sourceMappingURL=viewport.js.map

package/package.json

@@ -0,0 +1,30 @@
+{
+	"name": "@bpmnkit/canvas",
+	"version": "0.0.8",
+	"type": "module",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"files": ["dist/**/*.js", "dist/**/*.d.ts"],
+	"scripts": {
+		"build": "tsc",
+		"typecheck": "tsc --noEmit",
+		"check": "biome check .",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@bpmnkit/core": "workspace:*"
+	},
+	"description": "Zero-dependency SVG BPMN viewer with pan/zoom, theming, and a plugin API",
+	"keywords": ["bpmn", "viewer", "svg", "canvas", "workflow", "typescript"],
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/bpmnkit/monorepo"
+	}
+}