@bpmnkit/canvas 0.0.27 → 0.0.29

package/dist/scene.d.ts

@@ -0,0 +1,51 @@
+import type { BpmnDefinitions, BpmnDiPlane } from "@bpmnkit/core";
+import type { RenderedEdge, RenderedShape } from "./types.js";
+/** The four stacked SVG layers a scene renders into (bottom → top). */
+export interface SceneLayers {
+    containers: SVGGElement;
+    edges: SVGGElement;
+    shapes: SVGGElement;
+    labels: SVGGElement;
+}
+/**
+ * Owns a diagram's SVG layers and an id → graphics registry, and renders a DI
+ * plane into them. Beyond the initial full {@link render}, individual elements
+ * can be updated or removed in place ({@link updateElement}/{@link removeElement})
+ * without tearing down the whole scene — the foundation for incremental editing.
+ *
+ * CSS classes added to an element's `<g>` after rendering (markers, selection,
+ * highlights) are preserved across {@link updateElement}.
+ */
+export declare class Scene {
+    private readonly _layers;
+    private readonly _instanceId;
+    private readonly _registry;
+    private _defs;
+    private _plane;
+    private _drillableIds;
+    constructor(_layers: SceneLayers, _instanceId: string);
+    /** Renders a plane from scratch, replacing any current content. */
+    render(defs: BpmnDefinitions, plane: BpmnDiPlane, drillableIds?: ReadonlySet<string>): void;
+    /** Empties the layers and the registry. */
+    clear(): void;
+    /** Returns the registered shape or edge for an id, or `undefined`. */
+    getElement(id: string): RenderedShape | RenderedEdge | undefined;
+    /** Returns the `<g>` graphics element for an id, or `undefined`. */
+    getGraphics(id: string): SVGGElement | undefined;
+    /** Iterates every registered element in insertion order. */
+    forEach(fn: (el: RenderedShape | RenderedEdge) => void): void;
+    /** All rendered shapes, in registry order. */
+    getShapes(): RenderedShape[];
+    /** All rendered edges, in registry order. */
+    getEdges(): RenderedEdge[];
+    /**
+     * Re-renders a single element's `<g>` in place from the current model,
+     * preserving CSS classes (markers/selection) applied after the last render.
+     * No-op if the id is unknown or there is no current plane.
+     */
+    updateElement(id: string): void;
+    /** Removes an element's `<g>` (and its external label) from the scene. */
+    removeElement(id: string): void;
+    private _context;
+}
+//# sourceMappingURL=scene.d.ts.map

package/dist/scene.js

@@ -0,0 +1,140 @@
+import { buildRenderContext, renderEdgeGroup, renderShapeGroup, } from "./renderer.js";
+/**
+ * Owns a diagram's SVG layers and an id → graphics registry, and renders a DI
+ * plane into them. Beyond the initial full {@link render}, individual elements
+ * can be updated or removed in place ({@link updateElement}/{@link removeElement})
+ * without tearing down the whole scene — the foundation for incremental editing.
+ *
+ * CSS classes added to an element's `<g>` after rendering (markers, selection,
+ * highlights) are preserved across {@link updateElement}.
+ */
+export class Scene {
+    _layers;
+    _instanceId;
+    _registry = new Map();
+    _defs = null;
+    _plane = null;
+    _drillableIds = new Set();
+    constructor(_layers, _instanceId) {
+        this._layers = _layers;
+        this._instanceId = _instanceId;
+    }
+    /** Renders a plane from scratch, replacing any current content. */
+    render(defs, plane, drillableIds = new Set()) {
+        this.clear();
+        this._defs = defs;
+        this._plane = plane;
+        this._drillableIds = drillableIds;
+        const ctx = this._context();
+        for (const edge of plane.edges) {
+            const g = renderEdgeGroup(edge, ctx);
+            this._layers.edges.appendChild(g);
+            this._registry.set(edge.bpmnElement, {
+                rendered: { id: edge.bpmnElement, element: g, edge },
+                label: null,
+                kind: "edge",
+            });
+        }
+        for (const shape of plane.shapes) {
+            const { group, layer, label, rendered } = renderShapeGroup(shape, ctx);
+            this._layers[layer].appendChild(group);
+            if (label)
+                this._layers.labels.appendChild(label);
+            this._registry.set(shape.bpmnElement, { rendered, label, kind: "shape" });
+        }
+    }
+    /** Empties the layers and the registry. */
+    clear() {
+        this._layers.containers.replaceChildren();
+        this._layers.edges.replaceChildren();
+        this._layers.shapes.replaceChildren();
+        this._layers.labels.replaceChildren();
+        this._registry.clear();
+    }
+    /** Returns the registered shape or edge for an id, or `undefined`. */
+    getElement(id) {
+        return this._registry.get(id)?.rendered;
+    }
+    /** Returns the `<g>` graphics element for an id, or `undefined`. */
+    getGraphics(id) {
+        return this._registry.get(id)?.rendered.element;
+    }
+    /** Iterates every registered element in insertion order. */
+    forEach(fn) {
+        for (const entry of this._registry.values())
+            fn(entry.rendered);
+    }
+    /** All rendered shapes, in registry order. */
+    getShapes() {
+        const out = [];
+        for (const entry of this._registry.values()) {
+            if (entry.kind === "shape")
+                out.push(entry.rendered);
+        }
+        return out;
+    }
+    /** All rendered edges, in registry order. */
+    getEdges() {
+        const out = [];
+        for (const entry of this._registry.values()) {
+            if (entry.kind === "edge")
+                out.push(entry.rendered);
+        }
+        return out;
+    }
+    /**
+     * Re-renders a single element's `<g>` in place from the current model,
+     * preserving CSS classes (markers/selection) applied after the last render.
+     * No-op if the id is unknown or there is no current plane.
+     */
+    updateElement(id) {
+        const entry = this._registry.get(id);
+        if (!entry || !this._plane)
+            return;
+        const ctx = this._context();
+        const oldClasses = (entry.rendered.element.getAttribute("class") ?? "")
+            .split(/\s+/)
+            .filter(Boolean);
+        if (entry.kind === "edge") {
+            const edge = this._plane.edges.find((e) => e.bpmnElement === id);
+            if (!edge)
+                return;
+            const g = renderEdgeGroup(edge, ctx);
+            for (const c of oldClasses)
+                g.classList.add(c);
+            entry.rendered.element.replaceWith(g);
+            this._registry.set(id, { rendered: { id, element: g, edge }, label: null, kind: "edge" });
+            return;
+        }
+        const shape = this._plane.shapes.find((s) => s.bpmnElement === id);
+        if (!shape)
+            return;
+        const { group, layer, label, rendered } = renderShapeGroup(shape, ctx);
+        for (const c of oldClasses)
+            group.classList.add(c);
+        entry.rendered.element.replaceWith(group);
+        entry.label?.remove();
+        if (label)
+            this._layers.labels.appendChild(label);
+        // Keep the group in the correct layer if its target changed.
+        if (group.parentNode !== this._layers[layer])
+            this._layers[layer].appendChild(group);
+        this._registry.set(id, { rendered, label, kind: "shape" });
+    }
+    /** Removes an element's `<g>` (and its external label) from the scene. */
+    removeElement(id) {
+        const entry = this._registry.get(id);
+        if (!entry)
+            return;
+        entry.rendered.element.remove();
+        entry.label?.remove();
+        this._registry.delete(id);
+    }
+    _context() {
+        if (!this._defs || !this._plane) {
+            throw new Error("Scene has no rendered plane");
+        }
+        return buildRenderContext(this._defs, this._plane, this._drillableIds, this._instanceId);
+    }
+}
+//# sourceMappingURL=scene.js.map

package/dist/types.d.ts

@@ -1,4 +1,7 @@
-import type { BpmnDefinitions, BpmnDiEdge, BpmnDiShape, BpmnFlowElement, BpmnTextAnnotation } from "@bpmnkit/core";
+import type { BpmnDefinitions, BpmnDiEdge, BpmnDiShape, BpmnFlowElement, BpmnTextAnnotation, DiCompleteness } from "@bpmnkit/core";
+import type { OverlayManager } from "./overlays.js";
+/** Elements in the model that have no diagram interchange (BPMNShape/BPMNEdge). */
+export type ImportWarnings = DiCompleteness;
 /** The color theme applied to the canvas. */
 export type Theme = "light" | "dark" | "auto" | "neon";
 /**
@@ -35,6 +38,15 @@ export interface CanvasOptions {
      * @see {@link CanvasPlugin}
      */
     plugins?: CanvasPlugin[];
+    /**
+     * What to do when the model has elements without diagram interchange
+     * (no `BPMNShape`/`BPMNEdge`), which would otherwise be invisible.
+     * - `"off"` (default) — render only elements that have DI.
+     * - `"all"` — if any DI is missing, auto-layout a copy of the model and
+     *   render that. The caller's model is never mutated.
+     * @default "off"
+     */
+    layoutMissingDi?: "off" | "all";
 }
 /** The current pan/zoom state of the canvas viewport. */
 export interface ViewportState {
@@ -45,6 +57,29 @@ export interface ViewportState {
     /** Zoom scale factor. `1.0` = 100%, `0.5` = 50%, `2.0` = 200%. */
     scale: number;
 }
+/** A rectangle in screen pixels, relative to the canvas host. */
+export interface ScreenBox {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The visible region of the diagram, in diagram coordinates, plus the current
+ * zoom scale. The inverse of the pan/zoom transform applied to the viewport.
+ */
+export interface Viewbox {
+    /** Diagram x-coordinate at the left edge of the viewport. */
+    x: number;
+    /** Diagram y-coordinate at the top edge of the viewport. */
+    y: number;
+    /** Width of the visible region in diagram units. */
+    width: number;
+    /** Height of the visible region in diagram units. */
+    height: number;
+    /** Current zoom scale factor. */
+    scale: number;
+}
 /** A rendered BPMN shape with its SVG element and source model data. */
 export interface RenderedShape {
     /** The BPMN element ID. */
@@ -73,14 +108,42 @@ export interface CanvasEvents {
     "viewport:change": (state: ViewportState) => void;
     /** Fired when a BPMN element is clicked. */
     "element:click": (id: string, event: PointerEvent) => void;
+    /** Fired when the pointer moves onto a BPMN element (once per enter). */
+    "element:hover": (id: string, event: PointerEvent) => void;
+    /** Fired when the pointer leaves the previously-hovered element. */
+    "element:out": (id: string) => void;
+    /** Fired when a BPMN element is double-clicked. */
+    "element:dblclick": (id: string, event: MouseEvent) => void;
+    /**
+     * Fired when a BPMN element is right-clicked. Call `event.preventDefault()`
+     * in the handler to suppress the browser's native context menu.
+     */
+    "element:contextmenu": (id: string, event: MouseEvent) => void;
+    /** Fired when the empty canvas background (no element) is clicked. */
+    "canvas:click": (event: MouseEvent) => 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 after a BPMN diagram is loaded and rendered. `warnings` lists any
+     * model elements that had no diagram interchange (see {@link ImportWarnings}).
+     */
+    "diagram:load": (defs: BpmnDefinitions, warnings: ImportWarnings) => void;
     /** Fired when the canvas is cleared. */
     "diagram:clear": () => void;
+    /**
+     * Fired when the visible plane changes (drilling into a collapsed
+     * sub-process or navigating back). Both ids are DI plane `bpmnElement`s.
+     */
+    "plane:change": (fromPlaneId: string, toPlaneId: string) => void;
+}
+/** A DI plane the canvas can display (a process/collaboration or sub-process). */
+export interface PlaneInfo {
+    /** The plane's `bpmnElement` id (process, collaboration, or sub-process id). */
+    id: string;
+    /** A human-readable label (element name, or a fallback). */
+    name: string;
 }
 /**
  * The stable API surface exposed to plugins.
@@ -120,6 +183,34 @@ export interface CanvasApi {
     getTheme(): Theme;
     /** Sets the color theme. Pass `"auto"` to follow the OS preference. */
     setTheme(theme: Theme): void;
+    /** HTML overlays anchored to diagram elements. */
+    readonly overlays: OverlayManager;
+    /** Adds a CSS class to the element with the given BPMN id. No-op if not found. */
+    addMarker(id: string, cls: string): void;
+    /** Removes a CSS class from the element with the given BPMN id. */
+    removeMarker(id: string, cls: string): void;
+    /** Returns whether the element with the given id currently has the CSS class. */
+    hasMarker(id: string, cls: string): boolean;
+    /** Toggles a CSS class on the element with the given id. */
+    toggleMarker(id: string, cls: string): void;
+    /**
+     * Adjusts the zoom. Pass `"fit"` (or no argument) to fit the whole diagram;
+     * pass a number for an absolute scale, optionally keeping `center`
+     * (screen-space pixels relative to the host) fixed.
+     */
+    zoom(scaleOrFit?: number | "fit", center?: {
+        x: number;
+        y: number;
+    }): void;
+    /** Returns the visible region in diagram coordinates plus the zoom scale. */
+    viewbox(): Viewbox;
+    /** Pans (without changing zoom) so the element with the given id is centred. */
+    scrollToElement(id: string): void;
+    /**
+     * Returns the element's bounding box in screen pixels relative to the host,
+     * or `null` if the element is not found.
+     */
+    getAbsoluteBBox(id: string): ScreenBox | null;
     /**
      * Subscribes to a canvas event. Returns an unsubscribe function.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bpmnkit/canvas",
-  "version": "0.0.27",
+  "version": "0.0.29",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,7 +17,7 @@
     "dist/**/*.d.ts"
   ],
   "dependencies": {
-    "@bpmnkit/core": "0.0.27"
+    "@bpmnkit/core": "0.1.1"
   },
   "description": "Zero-dependency SVG BPMN viewer with pan/zoom, theming, and a plugin API",
   "keywords": [