@bpmnkit/core 0.0.8

package/README.md

@@ -0,0 +1,185 @@
+<div align="center">
+  <img src="https://raw.githubusercontent.com/bpmn-sdk/monorepo/main/doc/logos/logo-2-gateway.svg" width="72" height="72" alt="BPMN Kit logo">
+  <h1>@bpmnkit/core</h1>
+  <p>TypeScript-first BPMN 2.0 SDK — parse, build, layout, and optimize diagrams</p>
+
+  [![npm](https://img.shields.io/npm/v/@bpmnkit/core?style=flat-square&color=6244d7)](https://www.npmjs.com/package/@bpmnkit/core)
+  [![license](https://img.shields.io/npm/l/@bpmnkit/core?style=flat-square)](https://github.com/bpmnkit/monorepo/blob/main/LICENSE)
+  [![typescript](https://img.shields.io/badge/TypeScript-strict-6244d7?style=flat-square&logo=typescript&logoColor=white)](https://github.com/bpmnkit/monorepo)
+
+  [Documentation](https://bpmn-sdk-docs.pages.dev) · [GitHub](https://github.com/bpmnkit/monorepo) · [Changelog](https://github.com/bpmnkit/monorepo/blob/main/packages/core/CHANGELOG.md)
+</div>
+
+---
+
+## Overview
+
+`@bpmnkit/core` is the foundation of the BPMN Kit. It gives you everything to work with BPMN 2.0, DMN 1.3, and Camunda Form definitions in pure TypeScript — no XML wrestling, no runtime dependencies.
+
+```
+Parse → Modify → Validate → Export
+```
+
+## Features
+
+- **BPMN 2.0** — parse, create, and export process diagrams with full Zeebe/Camunda 8 extension support
+- **Fluent Builder API** — construct valid processes programmatically, never touch raw XML
+- **Sugiyama Layout Engine** — auto-position elements with clean orthogonal edge routing
+- **DMN 1.3** — decision tables, including FEEL expression support
+- **Camunda Form Definitions** — type-safe form schema builder
+- **Optimizer** — built-in rule engine to detect and auto-fix anti-patterns
+- **Compact Format** — 70% smaller token-efficient JSON representation for AI/LLM workflows
+- **Zero Dependencies** — runs in browsers, Node.js, Deno, Bun, and edge runtimes
+
+## Installation
+
+```sh
+npm install @bpmnkit/core
+pnpm add @bpmnkit/core
+```
+
+## Quick Start
+
+### Build a process from code
+
+```typescript
+import { Bpmn } from "@bpmnkit/core"
+
+const process = Bpmn.createProcess("order-flow", "Order Flow")
+  .startEvent("start", "Order Received")
+  .serviceTask("validate", "Validate Order", {
+    type: "order-validator",
+    inputs: [{ source: "=order", target: "order" }],
+    outputs: [{ source: "=valid", target: "isValid" }],
+  })
+  .exclusiveGateway("check", "Order Valid?")
+  .sequenceFlow("check", "fulfill", "=isValid = true")
+  .serviceTask("fulfill", "Fulfill Order", { type: "fulfillment-service" })
+  .endEvent("end", "Order Complete")
+  .sequenceFlow("check", "reject", "=isValid = false")
+  .endEvent("reject-end", "Order Rejected")
+  .build()
+
+const xml = Bpmn.export(process)
+```
+
+### Parse and modify existing BPMN
+
+```typescript
+import { Bpmn } from "@bpmnkit/core"
+
+const defs = Bpmn.parse(xml)
+const process = defs.processes[0]
+
+// Access flow elements
+for (const el of process.flowElements) {
+  console.log(el.type, el.id, el.name)
+}
+
+// Serialize back to XML
+const updated = Bpmn.export(defs)
+```
+
+### Auto-layout a process
+
+```typescript
+import { Bpmn, layoutProcess } from "@bpmnkit/core"
+
+const defs = Bpmn.parse(xml)
+const result = layoutProcess(defs.processes[0])
+// result.defs now has updated DI coordinates
+const laid = Bpmn.export(result.defs)
+```
+
+### Optimize a diagram
+
+```typescript
+import { Bpmn, optimize } from "@bpmnkit/core"
+
+const defs = Bpmn.parse(xml)
+const report = optimize(defs)
+
+console.log(`${report.summary.total} findings`)
+
+for (const finding of report.findings) {
+  console.log(`[${finding.severity}] ${finding.message}`)
+  if (finding.applyFix) {
+    const { description } = finding.applyFix(defs)
+    console.log("Fixed:", description)
+  }
+}
+```
+
+### Compact format for AI/LLM workflows
+
+```typescript
+import { Bpmn, compactify, expand } from "@bpmnkit/core"
+
+// Shrink for AI prompt
+const defs = Bpmn.parse(xml)
+const compact = compactify(defs)          // ~70% smaller JSON
+const json = JSON.stringify(compact)      // send to LLM
+
+// Restore full BPMN from AI response
+const restored = expand(JSON.parse(json))
+const outXml = Bpmn.export(restored)
+```
+
+## API Reference
+
+### BPMN
+
+| Export | Description |
+|--------|-------------|
+| `Bpmn.parse(xml)` | Parse BPMN XML → `BpmnDefinitions` |
+| `Bpmn.export(defs)` | Serialize `BpmnDefinitions` → XML |
+| `Bpmn.createProcess(id, name?)` | Start a `ProcessBuilder` |
+| `Bpmn.makeEmpty(processId?, name?)` | Minimal BPMN XML with one start event |
+| `Bpmn.SAMPLE_XML` | 3-node sample diagram string |
+
+### DMN
+
+| Export | Description |
+|--------|-------------|
+| `Dmn.parse(xml)` | Parse DMN XML → `DmnDefinitions` |
+| `Dmn.export(defs)` | Serialize → XML |
+| `Dmn.createDecisionTable(id, name?)` | Start a `DecisionTableBuilder` |
+| `Dmn.makeEmpty()` | Minimal DMN with one empty decision table |
+
+### Form
+
+| Export | Description |
+|--------|-------------|
+| `Form.create()` | Start a `FormBuilder` |
+| `Form.parse(json)` | Parse a form schema |
+| `Form.export(schema)` | Serialize → JSON string |
+
+### Layout & Optimization
+
+| Export | Description |
+|--------|-------------|
+| `layoutProcess(process)` | Auto-layout all elements; returns `LayoutResult` |
+| `optimize(defs)` | Run all optimization rules; returns `OptimizeReport` |
+| `compactify(defs)` | Convert to compact `CompactDiagram` |
+| `expand(compact)` | Restore full `BpmnDefinitions` |
+| `generateId(prefix)` | Generate a unique short ID |
+
+---
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@bpmnkit/canvas`](https://www.npmjs.com/package/@bpmnkit/canvas) | Zero-dependency SVG BPMN viewer |
+| [`@bpmnkit/editor`](https://www.npmjs.com/package/@bpmnkit/editor) | Full-featured interactive BPMN editor |
+| [`@bpmnkit/engine`](https://www.npmjs.com/package/@bpmnkit/engine) | Lightweight BPMN process execution engine |
+| [`@bpmnkit/feel`](https://www.npmjs.com/package/@bpmnkit/feel) | FEEL expression language parser & evaluator |
+| [`@bpmnkit/plugins`](https://www.npmjs.com/package/@bpmnkit/plugins) | 22 composable canvas plugins |
+| [`@bpmnkit/api`](https://www.npmjs.com/package/@bpmnkit/api) | Camunda 8 REST API TypeScript client |
+| [`@bpmnkit/ascii`](https://www.npmjs.com/package/@bpmnkit/ascii) | Render BPMN diagrams as Unicode ASCII art |
+| [`@bpmnkit/profiles`](https://www.npmjs.com/package/@bpmnkit/profiles) | Shared auth, profile storage, and client factories for CLI & proxy |
+| [`@bpmnkit/operate`](https://www.npmjs.com/package/@bpmnkit/operate) | Monitoring & operations frontend for Camunda clusters |
+
+## License
+
+[MIT](https://github.com/bpmnkit/monorepo/blob/main/LICENSE) © bpmn-sdk

package/dist/bpmn/auto-layout.d.ts

@@ -0,0 +1,10 @@
+import type { BpmnDefinitions } from "./bpmn-model.js";
+/**
+ * Apply auto-layout to all processes in a BpmnDefinitions, replacing the
+ * diagram interchange (BPMNDi) with freshly computed positions.
+ *
+ * - Handles plain processes (no collaboration) and collaborations with pools.
+ * - When pools have lanes, lane shapes are tiled vertically around the process content.
+ */
+export declare function applyAutoLayout(defs: BpmnDefinitions): BpmnDefinitions;
+//# sourceMappingURL=auto-layout.d.ts.map

package/dist/bpmn/auto-layout.js

@@ -0,0 +1,203 @@
+import { layoutProcess } from "../layout/layout-engine.js";
+const POOL_HEADER = 30;
+const LANE_HEADER = 30;
+const PADDING = 20;
+const POOL_GAP = 30;
+function contentBbox(nodes) {
+    let minX = Number.POSITIVE_INFINITY;
+    let minY = Number.POSITIVE_INFINITY;
+    let maxX = Number.NEGATIVE_INFINITY;
+    let maxY = Number.NEGATIVE_INFINITY;
+    for (const n of nodes) {
+        minX = Math.min(minX, n.bounds.x);
+        minY = Math.min(minY, n.bounds.y);
+        maxX = Math.max(maxX, n.bounds.x + n.bounds.width);
+        maxY = Math.max(maxY, n.bounds.y + n.bounds.height);
+        if (n.labelBounds) {
+            minX = Math.min(minX, n.labelBounds.x);
+            minY = Math.min(minY, n.labelBounds.y);
+            maxX = Math.max(maxX, n.labelBounds.x + n.labelBounds.width);
+            maxY = Math.max(maxY, n.labelBounds.y + n.labelBounds.height);
+        }
+    }
+    return { minX, minY, maxX, maxY };
+}
+function nodeToShape(node, dx, dy) {
+    const shape = {
+        id: `${node.id}_di`,
+        bpmnElement: node.id,
+        bounds: {
+            x: Math.round(node.bounds.x + dx),
+            y: Math.round(node.bounds.y + dy),
+            width: Math.round(node.bounds.width),
+            height: Math.round(node.bounds.height),
+        },
+        unknownAttributes: {},
+    };
+    if (node.isExpanded !== undefined)
+        shape.isExpanded = node.isExpanded;
+    if (node.labelBounds) {
+        shape.label = {
+            bounds: {
+                x: Math.round(node.labelBounds.x + dx),
+                y: Math.round(node.labelBounds.y + dy),
+                width: Math.round(node.labelBounds.width),
+                height: Math.round(node.labelBounds.height),
+            },
+        };
+    }
+    return shape;
+}
+function edgeToShape(edge, dx, dy) {
+    const diEdge = {
+        id: `${edge.id}_di`,
+        bpmnElement: edge.id,
+        waypoints: edge.waypoints.map((wp) => ({
+            x: Math.round(wp.x + dx),
+            y: Math.round(wp.y + dy),
+        })),
+        unknownAttributes: {},
+    };
+    if (edge.labelBounds) {
+        diEdge.label = {
+            bounds: {
+                x: Math.round(edge.labelBounds.x + dx),
+                y: Math.round(edge.labelBounds.y + dy),
+                width: Math.round(edge.labelBounds.width),
+                height: Math.round(edge.labelBounds.height),
+            },
+        };
+    }
+    return diEdge;
+}
+function buildLaneShapes(lanes, nodes, dx, dy, poolY, poolHeaderWidth, laneContentWidth, poolHeight) {
+    const elemToLane = new Map();
+    for (const lane of lanes) {
+        for (const ref of lane.flowNodeRefs) {
+            elemToLane.set(ref, lane.id);
+        }
+    }
+    // Compute per-lane mean Y (after shift) to sort lanes top-to-bottom
+    const laneAccum = new Map();
+    for (const lane of lanes)
+        laneAccum.set(lane.id, { sum: 0, count: 0 });
+    for (const node of nodes) {
+        const laneId = elemToLane.get(node.id);
+        if (!laneId)
+            continue;
+        const acc = laneAccum.get(laneId);
+        if (acc) {
+            acc.sum += node.bounds.y + dy;
+            acc.count++;
+        }
+    }
+    const sortedLanes = [...lanes].sort((a, b) => {
+        const accA = laneAccum.get(a.id);
+        const accB = laneAccum.get(b.id);
+        const mA = accA && accA.count > 0 ? accA.sum / accA.count : Number.POSITIVE_INFINITY;
+        const mB = accB && accB.count > 0 ? accB.sum / accB.count : Number.POSITIVE_INFINITY;
+        return mA - mB;
+    });
+    const tileH = Math.round(poolHeight / sortedLanes.length);
+    return sortedLanes.map((lane, i) => ({
+        id: `${lane.id}_di`,
+        bpmnElement: lane.id,
+        isHorizontal: true,
+        bounds: {
+            x: Math.round(poolHeaderWidth),
+            y: Math.round(poolY + i * tileH),
+            width: Math.round(laneContentWidth),
+            height: Math.round(i === sortedLanes.length - 1 ? poolHeight - i * tileH : tileH),
+        },
+        unknownAttributes: {},
+    }));
+}
+/**
+ * Apply auto-layout to all processes in a BpmnDefinitions, replacing the
+ * diagram interchange (BPMNDi) with freshly computed positions.
+ *
+ * - Handles plain processes (no collaboration) and collaborations with pools.
+ * - When pools have lanes, lane shapes are tiled vertically around the process content.
+ */
+export function applyAutoLayout(defs) {
+    if (defs.processes.length === 0)
+        return defs;
+    const collab = defs.collaborations[0];
+    // Build processId → participantId map
+    const processToParticipant = new Map();
+    if (collab) {
+        for (const p of collab.participants) {
+            if (p.processRef)
+                processToParticipant.set(p.processRef, p.id);
+        }
+    }
+    const allShapes = [];
+    const allEdges = [];
+    let poolY = 0;
+    for (const process of defs.processes) {
+        const participantId = processToParticipant.get(process.id);
+        const lanes = process.laneSet?.lanes ?? [];
+        const hasLanes = lanes.length > 0;
+        const result = layoutProcess(process);
+        if (result.nodes.length === 0)
+            continue;
+        const { minX, minY, maxX, maxY } = contentBbox(result.nodes);
+        const contentW = maxX - minX;
+        const contentH = maxY - minY;
+        if (participantId) {
+            // Elements sit inside pool content area:
+            // x starts at: POOL_HEADER + optional LANE_HEADER + PADDING
+            // y starts at: poolY + PADDING
+            const elemX = POOL_HEADER + (hasLanes ? LANE_HEADER : 0) + PADDING;
+            const elemY = poolY + PADDING;
+            const dx = elemX - minX;
+            const dy = elemY - minY;
+            for (const node of result.nodes)
+                allShapes.push(nodeToShape(node, dx, dy));
+            for (const edge of result.edges)
+                allEdges.push(edgeToShape(edge, dx, dy));
+            const innerW = (hasLanes ? LANE_HEADER : 0) + contentW + 2 * PADDING;
+            const innerH = contentH + 2 * PADDING;
+            const poolW = POOL_HEADER + innerW;
+            // Pool (participant) shape
+            allShapes.push({
+                id: `${participantId}_di`,
+                bpmnElement: participantId,
+                isHorizontal: true,
+                bounds: { x: 0, y: poolY, width: poolW, height: innerH },
+                unknownAttributes: {},
+            });
+            if (hasLanes) {
+                const laneShapes = buildLaneShapes(lanes, result.nodes, dx, dy, poolY, POOL_HEADER, innerW, innerH);
+                allShapes.push(...laneShapes);
+            }
+            poolY += innerH + POOL_GAP;
+        }
+        else {
+            // No collaboration — layout at (PADDING, PADDING)
+            const dx = PADDING - minX;
+            const dy = PADDING - minY;
+            for (const node of result.nodes)
+                allShapes.push(nodeToShape(node, dx, dy));
+            for (const edge of result.edges)
+                allEdges.push(edgeToShape(edge, dx, dy));
+        }
+    }
+    const planeBpmnElement = collab?.id ?? defs.processes[0]?.id ?? "plane";
+    const existingDiagram = defs.diagrams[0];
+    return {
+        ...defs,
+        diagrams: [
+            {
+                id: existingDiagram?.id ?? "BPMNDiagram_1",
+                plane: {
+                    id: existingDiagram?.plane.id ?? "BPMNPlane_1",
+                    bpmnElement: planeBpmnElement,
+                    shapes: allShapes,
+                    edges: allEdges,
+                },
+            },
+        ],
+    };
+}
+//# sourceMappingURL=auto-layout.js.map