@bpmnkit/core 0.1.1 → 0.2.0

package/dist/layout/semantic/graph.js

@@ -0,0 +1,242 @@
+/** Flow-node types that end a path — used to score candidate spine edges. */
+const END_TYPES = new Set(["endEvent"]);
+/**
+ * The node a flow leaves from for layout purposes. A flow out of a boundary
+ * event belongs to the host's position, not the event's.
+ */
+function effectiveSource(flow, byId) {
+    const source = byId.get(flow.sourceRef);
+    if (source?.type === "boundaryEvent")
+        return source.attachedToRef;
+    return flow.sourceRef;
+}
+export function buildSemanticGraph(flowElements, sequenceFlows) {
+    const byId = new Map();
+    for (const el of flowElements)
+        byId.set(el.id, el);
+    const nodes = [];
+    const attachers = new Map();
+    for (const el of flowElements) {
+        if (el.type === "boundaryEvent") {
+            const be = el;
+            const list = attachers.get(be.attachedToRef);
+            if (list)
+                list.push(be);
+            else
+                attachers.set(be.attachedToRef, [be]);
+        }
+        else {
+            nodes.push(el);
+        }
+    }
+    const outgoing = new Map();
+    const incoming = new Map();
+    for (const flow of sequenceFlows) {
+        const from = effectiveSource(flow, byId);
+        if (!byId.has(from) || !byId.has(flow.targetRef))
+            continue;
+        const out = outgoing.get(from);
+        if (out)
+            out.push(flow);
+        else
+            outgoing.set(from, [flow]);
+        const inc = incoming.get(flow.targetRef);
+        if (inc)
+            inc.push(flow);
+        else
+            incoming.set(flow.targetRef, [flow]);
+    }
+    const graph = {
+        nodes,
+        byId,
+        outgoing,
+        incoming,
+        attachers,
+        backEdges: new Set(),
+        components: [],
+        starts: [],
+        ranks: new Map(),
+    };
+    findComponents(graph);
+    markBackEdges(graph);
+    assignRanks(graph);
+    return graph;
+}
+/** Weakly connected components, discovered in declaration order. */
+function findComponents(graph) {
+    const seen = new Set();
+    for (const node of graph.nodes) {
+        if (seen.has(node.id))
+            continue;
+        const members = [];
+        const stack = [node.id];
+        while (stack.length > 0) {
+            const id = stack.pop();
+            if (id === undefined || seen.has(id))
+                continue;
+            seen.add(id);
+            members.push(id);
+            for (const f of graph.outgoing.get(id) ?? [])
+                stack.push(f.targetRef);
+            for (const f of graph.incoming.get(id) ?? [])
+                stack.push(effectiveSource(f, graph.byId));
+        }
+        // Declaration order within the component keeps ties deterministic.
+        const order = new Map(graph.nodes.map((n, i) => [n.id, i]));
+        members.sort((a, b) => (order.get(a) ?? 0) - (order.get(b) ?? 0));
+        graph.components.push(members);
+        graph.starts.push(pickStart(members, graph));
+    }
+}
+/**
+ * A component starts at its earliest declared start event, else its earliest
+ * node with no incoming flow, else its earliest declared node.
+ */
+function pickStart(members, graph) {
+    const startEvent = members.find((id) => graph.byId.get(id)?.type === "startEvent");
+    if (startEvent)
+        return startEvent;
+    const source = members.find((id) => (graph.incoming.get(id) ?? []).length === 0);
+    return source ?? members[0] ?? "";
+}
+/**
+ * Depth-first from each semantic start; an edge onto a node already on the
+ * traversal stack closes a cycle and is excluded from ranking.
+ */
+function markBackEdges(graph) {
+    const state = new Map();
+    const visit = (id) => {
+        state.set(id, "open");
+        for (const flow of graph.outgoing.get(id) ?? []) {
+            const target = flow.targetRef;
+            const targetState = state.get(target);
+            if (targetState === "open")
+                graph.backEdges.add(flow.id);
+            else if (targetState === undefined)
+                visit(target);
+        }
+        state.set(id, "done");
+    };
+    for (const start of graph.starts)
+        if (start && !state.has(start))
+            visit(start);
+    // Nodes only reachable through a cycle still need a traversal root.
+    for (const node of graph.nodes)
+        if (!state.has(node.id))
+            visit(node.id);
+}
+const GATEWAY_TYPES = new Set([
+    "exclusiveGateway",
+    "parallelGateway",
+    "inclusiveGateway",
+    "eventBasedGateway",
+    "complexGateway",
+]);
+/** True when a node merges more than one path. */
+function isJoin(graph, id) {
+    return (graph.incoming.get(id) ?? []).length > 1;
+}
+/**
+ * Nested joins of one gateway type may share a rank and connect vertically —
+ * closing an inner branch and the branch around it is one moment in the flow,
+ * not two. Joins of different types keep their forward step, because the change
+ * of gateway is itself part of the story.
+ */
+function sharesRank(graph, flow) {
+    const source = graph.byId.get(flow.sourceRef);
+    const target = graph.byId.get(flow.targetRef);
+    if (!source || !target)
+        return false;
+    if (source.type !== target.type || !GATEWAY_TYPES.has(source.type))
+        return false;
+    return isJoin(graph, source.id) && isJoin(graph, target.id);
+}
+/**
+ * Longest-path ranks over the acyclic remainder, then a bounded fixed point so
+ * a boundary handler never precedes the activity it is attached to.
+ */
+function assignRanks(graph) {
+    const { ranks } = graph;
+    for (const node of graph.nodes)
+        ranks.set(node.id, 0);
+    const forward = (id) => (graph.outgoing.get(id) ?? []).filter((f) => !graph.backEdges.has(f.id));
+    // Longest path: relax every edge until no rank grows. |V| passes suffice
+    // because the remaining graph is acyclic.
+    for (let pass = 0; pass < graph.nodes.length + 1; pass++) {
+        let changed = false;
+        for (const node of graph.nodes) {
+            const rank = ranks.get(node.id) ?? 0;
+            for (const flow of forward(node.id)) {
+                const step = sharesRank(graph, flow) ? 0 : 1;
+                const target = ranks.get(flow.targetRef) ?? 0;
+                if (target < rank + step) {
+                    ranks.set(flow.targetRef, rank + step);
+                    changed = true;
+                }
+            }
+        }
+        if (!changed)
+            break;
+    }
+    // Normalize each component so its start sits at rank 0.
+    for (let i = 0; i < graph.components.length; i++) {
+        const members = graph.components[i];
+        if (!members)
+            continue;
+        let min = Number.POSITIVE_INFINITY;
+        for (const id of members)
+            min = Math.min(min, ranks.get(id) ?? 0);
+        if (min === 0 || !Number.isFinite(min))
+            continue;
+        for (const id of members)
+            ranks.set(id, (ranks.get(id) ?? 0) - min);
+    }
+}
+/**
+ * True when an end event is reachable from `id` without traversing a back edge.
+ * A node other than `id` itself that has no outgoing flow also ends the path.
+ *
+ * The reverse reachability set is computed once per graph, so repeated calls
+ * from the spine tracer stay O(1) instead of re-walking the graph each time.
+ */
+export function reachesEnd(graph, id) {
+    const node = graph.byId.get(id);
+    if (node && END_TYPES.has(node.type))
+        return true;
+    const endReach = graph.endReach ?? buildEndReach(graph);
+    for (const flow of graph.outgoing.get(id) ?? []) {
+        if (!graph.backEdges.has(flow.id) && endReach.has(flow.targetRef))
+            return true;
+    }
+    return false;
+}
+/**
+ * Every node from which a path along non-back edges reaches an end event or a
+ * node with no outgoing flow (both inclusive), found by one reverse walk.
+ */
+function buildEndReach(graph) {
+    const reach = new Set();
+    const stack = [];
+    for (const node of graph.byId.values()) {
+        const out = graph.outgoing.get(node.id);
+        if (END_TYPES.has(node.type) || out === undefined || out.length === 0) {
+            reach.add(node.id);
+            stack.push(node.id);
+        }
+    }
+    while (stack.length > 0) {
+        const id = stack.pop();
+        for (const flow of graph.incoming.get(id) ?? []) {
+            if (graph.backEdges.has(flow.id))
+                continue;
+            const from = effectiveSource(flow, graph.byId);
+            if (!reach.has(from)) {
+                reach.add(from);
+                stack.push(from);
+            }
+        }
+    }
+    graph.endReach = reach;
+    return reach;
+}
+//# sourceMappingURL=graph.js.map

package/dist/layout/semantic/index.d.ts

@@ -0,0 +1,13 @@
+import type { BpmnFlowElement, BpmnLaneSet, BpmnProcess, BpmnSequenceFlow } from "../../bpmn/bpmn-model.js";
+import type { LayoutResult } from "../types.js";
+/**
+ * Lay out a process the way the BPMN reads: ranks carry the flow left to right,
+ * semantic bands carry branch meaning up and down, and lane membership wins over
+ * both.
+ */
+export declare function semanticLayoutProcess(process: BpmnProcess, collapsed?: ReadonlySet<string>): LayoutResult;
+export declare function semanticLayout(flowElements: BpmnFlowElement[], sequenceFlows: BpmnSequenceFlow[], laneSet?: BpmnLaneSet, 
+/** Sub-processes drawn collapsed: their contents go on a plane of their own. */
+collapsed?: ReadonlySet<string>): LayoutResult;
+export type { Placement } from "./place.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/layout/semantic/index.js

@@ -0,0 +1,181 @@
+import { placeEdgeLabels } from "../grid/edge-labels.js";
+import { LABEL_CHAR_WIDTH, LABEL_HEIGHT, LABEL_MIN_WIDTH, SUBPROCESS_PADDING } from "../types.js";
+import { assignBands } from "./bands.js";
+import { buildSemanticGraph } from "./graph.js";
+import { place, sizeOf } from "./place.js";
+import { routeFlows } from "./route.js";
+/** Padding between an expanded sub-process border and its children. */
+const SUB_PADDING = SUBPROCESS_PADDING;
+/** Extra top padding inside a named expanded sub-process, for its title. */
+const TITLE_BAND = 28;
+/** Gap between an event or gateway and its external label. */
+const LABEL_OFFSET = 4;
+const CONTAINER_TYPES = new Set(["subProcess", "adHocSubProcess", "eventSubProcess", "transaction"]);
+const EXTERNAL_LABEL_TYPES = new Set([
+    "startEvent",
+    "endEvent",
+    "intermediateThrowEvent",
+    "intermediateCatchEvent",
+    "boundaryEvent",
+    "exclusiveGateway",
+    "parallelGateway",
+    "inclusiveGateway",
+    "eventBasedGateway",
+    "complexGateway",
+]);
+/**
+ * Lay out a process the way the BPMN reads: ranks carry the flow left to right,
+ * semantic bands carry branch meaning up and down, and lane membership wins over
+ * both.
+ */
+export function semanticLayoutProcess(process, collapsed) {
+    return semanticLayout(process.flowElements, process.sequenceFlows, process.laneSet, collapsed);
+}
+export function semanticLayout(flowElements, sequenceFlows, laneSet, 
+/** Sub-processes drawn collapsed: their contents go on a plane of their own. */
+collapsed = new Set()) {
+    if (flowElements.length === 0)
+        return { nodes: [], edges: [] };
+    const graph = buildSemanticGraph(flowElements, sequenceFlows);
+    const bandLayout = assignBands(graph);
+    // Children first: an expanded sub-process is sized by what it contains, while
+    // a collapsed one stays activity-sized and its contents move to their own plane.
+    const childResults = new Map();
+    const planes = [];
+    const sizes = new Map();
+    for (const el of graph.nodes) {
+        const child = childLayoutOf(el, collapsed);
+        if (!child) {
+            sizes.set(el.id, sizeOf(el));
+            continue;
+        }
+        if (collapsed.has(el.id)) {
+            planes.push({ elementId: el.id, result: child.result });
+            planes.push(...(child.result.planes ?? []));
+            sizes.set(el.id, sizeOf(el));
+        }
+        else {
+            childResults.set(el.id, child.result);
+            planes.push(...(child.result.planes ?? []));
+            sizes.set(el.id, child.size);
+        }
+    }
+    const { bounds, lanes, gutterX } = place(graph, bandLayout, sizes, laneSet);
+    const nodes = [];
+    for (const el of flowElements) {
+        const b = bounds.get(el.id);
+        if (!b)
+            continue;
+        const node = {
+            id: el.id,
+            type: el.type,
+            bounds: b,
+            layer: graph.ranks.get(el.id) ?? 0,
+            position: bandLayout.bands.get(el.id) ?? 0,
+            gridRow: bandLayout.bands.get(el.id) ?? 0,
+        };
+        if (el.name) {
+            node.label = el.name;
+            const labelBounds = externalLabel(el.type, el.name, b);
+            if (labelBounds)
+                node.labelBounds = labelBounds;
+        }
+        if (childResults.has(el.id))
+            node.isExpanded = true;
+        else if (collapsed.has(el.id))
+            node.isExpanded = false;
+        nodes.push(node);
+    }
+    const edges = routeFlows(graph, sequenceFlows, bounds, bandLayout, gutterX);
+    // Drop the children in, translated into their parent's interior.
+    for (const [parentId, child] of childResults) {
+        const parent = bounds.get(parentId);
+        if (!parent)
+            continue;
+        const extent = extentOf(child);
+        if (!extent)
+            continue;
+        const named = graph.byId.get(parentId)?.name !== undefined;
+        const dx = parent.x + SUB_PADDING - extent.x;
+        const dy = parent.y + SUB_PADDING + (named ? TITLE_BAND : 0) - extent.y;
+        for (const node of child.nodes) {
+            node.bounds = shift(node.bounds, dx, dy);
+            if (node.labelBounds)
+                node.labelBounds = shift(node.labelBounds, dx, dy);
+            nodes.push(node);
+        }
+        for (const edge of child.edges) {
+            edge.waypoints = edge.waypoints.map((wp) => ({ x: wp.x + dx, y: wp.y + dy }));
+            if (edge.labelBounds)
+                edge.labelBounds = shift(edge.labelBounds, dx, dy);
+            edges.push(edge);
+        }
+    }
+    const result = { nodes, edges };
+    if (lanes.length > 0)
+        result.lanes = lanes;
+    if (planes.length > 0)
+        result.planes = planes;
+    placeEdgeLabels(edges, new Map(nodes.map((n) => [n.id, n])));
+    return result;
+}
+/** Lay out a container's children and report the size its border needs. */
+function childLayoutOf(el, collapsed) {
+    if (!CONTAINER_TYPES.has(el.type))
+        return null;
+    const container = el;
+    if (!container.flowElements || container.flowElements.length === 0)
+        return null;
+    const result = semanticLayout(container.flowElements, container.sequenceFlows ?? [], container.laneSet, collapsed);
+    const extent = extentOf(result);
+    if (!extent)
+        return null;
+    const titleBand = el.name !== undefined ? TITLE_BAND : 0;
+    return {
+        result,
+        size: {
+            width: extent.width + 2 * SUB_PADDING,
+            height: extent.height + 2 * SUB_PADDING + titleBand,
+        },
+    };
+}
+function extentOf(result) {
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    const consider = (b) => {
+        minX = Math.min(minX, b.x);
+        minY = Math.min(minY, b.y);
+        maxX = Math.max(maxX, b.x + b.width);
+        maxY = Math.max(maxY, b.y + b.height);
+    };
+    for (const node of result.nodes) {
+        consider(node.bounds);
+        if (node.labelBounds)
+            consider(node.labelBounds);
+    }
+    for (const edge of result.edges) {
+        for (const wp of edge.waypoints)
+            consider({ x: wp.x, y: wp.y, width: 0, height: 0 });
+    }
+    if (!Number.isFinite(minX))
+        return null;
+    return { x: minX, y: minY, width: maxX - minX, height: maxY - minY };
+}
+function shift(b, dx, dy) {
+    return { x: b.x + dx, y: b.y + dy, width: b.width, height: b.height };
+}
+/** Events and gateways carry their name outside the shape; activities do not. */
+function externalLabel(type, name, bounds) {
+    if (!EXTERNAL_LABEL_TYPES.has(type))
+        return undefined;
+    const width = Math.max(name.length * LABEL_CHAR_WIDTH, LABEL_MIN_WIDTH);
+    return {
+        x: bounds.x + bounds.width / 2 - width / 2,
+        y: bounds.y + bounds.height + LABEL_OFFSET,
+        width,
+        height: LABEL_HEIGHT,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/layout/semantic/place.d.ts

@@ -0,0 +1,40 @@
+import type { BpmnFlowElement, BpmnLaneSet } from "../../bpmn/bpmn-model.js";
+import type { Bounds } from "../types.js";
+import type { BandLayout } from "./bands.js";
+import type { SemanticGraph } from "./graph.js";
+/** Geometry constants. Layout may add space beyond these; it never takes any back. */
+export declare const H_GAP = 100;
+export declare const V_GAP = 80;
+export declare const COMPONENT_GAP = 80;
+export declare const LANE_PADDING = 40;
+export declare const BOUNDARY_SIZE = 36;
+export interface Placement {
+    /** Absolute bounds per flow node, boundary events included. */
+    bounds: Map<string, Bounds>;
+    /** Lane bands in top-to-bottom order, empty when the scope has no lanes. */
+    lanes: Array<{
+        id: string;
+        bounds: Bounds;
+    }>;
+    /**
+     * Mid-x of the empty gutter in front of each rank. Vertical runs belong
+     * here: placement never puts a shape in a gutter, so these lines are clear.
+     */
+    gutterX: Map<number, number>;
+}
+export declare function sizeOf(el: BpmnFlowElement, childExtent?: Bounds): {
+    width: number;
+    height: number;
+};
+/**
+ * Turn ranks and bands into coordinates.
+ *
+ * Ranks become columns sized by their widest node, bands become rows sized by
+ * their tallest. Nodes are centred in both, so any two nodes sharing a band
+ * share a centre line and the spine routes as one straight segment.
+ */
+export declare function place(graph: SemanticGraph, bandLayout: BandLayout, sizes: Map<string, {
+    width: number;
+    height: number;
+}>, laneSet: BpmnLaneSet | undefined): Placement;
+//# sourceMappingURL=place.d.ts.map