@bpmnkit/core 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,134 @@
1
+ /**
2
+ * Stable, content-derived ids for the parts of a model the caller does not name:
3
+ * sequence flows, and the root messages, errors, signals and escalations that
4
+ * event options declare.
5
+ *
6
+ * The fluent builder used to mint these with `generateId()`, so rebuilding an
7
+ * unchanged model produced different BPMN every time — noisy diffs, and a
8
+ * review that cannot tell a renamed edge from a new one. These ids come from
9
+ * the model instead: for a flow, the endpoints it connects plus a discriminator
10
+ * when one pair carries several flows; for a root definition, the name or code
11
+ * it is looked up by.
12
+ *
13
+ * Flow ids are assigned in a pass over a finished scope rather than at creation
14
+ * time, because a flow's endpoints are not final when it is created —
15
+ * `insertAfter()` re-points a flow's source, and `insertJoinGateways()`
16
+ * re-points its target.
17
+ */
18
+ import { slugify, uniqueId } from "../plan/slug.js";
19
+ /** Longest id this produces; anything longer is truncated and hashed. */
20
+ const MAX_ID_LENGTH = 200;
21
+ /**
22
+ * FNV-1a, base36. Not a checksum anyone verifies — just a short, stable
23
+ * discriminator for two flows the model distinguishes only by a long string.
24
+ */
25
+ function shortHash(text) {
26
+ let hash = 0x811c9dc5;
27
+ for (let i = 0; i < text.length; i++) {
28
+ hash ^= text.charCodeAt(i);
29
+ hash = Math.imul(hash, 0x01000193) >>> 0;
30
+ }
31
+ return hash.toString(36);
32
+ }
33
+ /** Keeps an id an XML NCName: letters, digits, `_` and `-`, never leading with a digit. */
34
+ function ncName(text) {
35
+ const cleaned = text.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/^[^A-Za-z_]+/, "");
36
+ return cleaned.length > 0 ? cleaned : "x";
37
+ }
38
+ /** Truncates over-long ids, keeping them distinct by appending a hash of what was dropped. */
39
+ function capLength(id) {
40
+ if (id.length <= MAX_ID_LENGTH)
41
+ return id;
42
+ const suffix = `_${shortHash(id)}`;
43
+ return id.slice(0, MAX_ID_LENGTH - suffix.length) + suffix;
44
+ }
45
+ /** The id a flow gets when it is the only one between its two endpoints. */
46
+ function baseId(flow) {
47
+ return capLength(`Flow_${ncName(flow.sourceRef)}_${ncName(flow.targetRef)}`);
48
+ }
49
+ /**
50
+ * What tells two flows between the same endpoints apart, in order of how
51
+ * readable it is: the branch name, then the condition, then nothing — leaving
52
+ * `uniqueId` to number genuinely identical edges.
53
+ */
54
+ function discriminator(flow) {
55
+ if (flow.name !== undefined && flow.name.trim().length > 0)
56
+ return ncName(slugify(flow.name));
57
+ const condition = flow.conditionExpression?.text;
58
+ if (condition !== undefined && condition.trim().length > 0)
59
+ return `c${shortHash(condition)}`;
60
+ return undefined;
61
+ }
62
+ /**
63
+ * Replaces generated sequence-flow ids in one scope (a process or a
64
+ * sub-process) with ids derived from the flows themselves, and rewrites the
65
+ * `default` attributes that name them.
66
+ *
67
+ * Run it after the topology is final — after join inference and any pending
68
+ * splice — and before `incoming`/`outgoing` are recomputed.
69
+ *
70
+ * @param elements - The scope's flow elements. Their ids are reserved, and
71
+ * gateway `default` references are rewritten.
72
+ * @param flows - The scope's sequence flows, mutated in place.
73
+ * @param preserve - Ids to leave alone, for flows the builder did not create:
74
+ * continuing a parsed document must not renumber what it was handed.
75
+ */
76
+ export function assignStableFlowIds(elements, flows, preserve) {
77
+ const renamable = preserve === undefined ? flows : flows.filter((flow) => !preserve.has(flow.id));
78
+ if (renamable.length === 0)
79
+ return;
80
+ // Reserved up front so a derived id can never land on an element id or on a
81
+ // flow id this pass is not allowed to touch.
82
+ const taken = new Set(elements.map((element) => element.id));
83
+ if (preserve !== undefined) {
84
+ for (const flow of flows)
85
+ if (preserve.has(flow.id))
86
+ taken.add(flow.id);
87
+ }
88
+ // Flows sharing a base id all get a discriminator, so which one was built
89
+ // first — and so the order branches were declared in — does not decide who
90
+ // keeps the short id.
91
+ const byBase = new Map();
92
+ for (const flow of renamable) {
93
+ const base = baseId(flow);
94
+ const group = byBase.get(base);
95
+ if (group)
96
+ group.push(flow);
97
+ else
98
+ byBase.set(base, [flow]);
99
+ }
100
+ const renamed = new Map();
101
+ for (const [base, group] of byBase) {
102
+ for (const flow of group) {
103
+ const qualifier = group.length > 1 ? discriminator(flow) : undefined;
104
+ const id = uniqueId(qualifier === undefined ? base : capLength(`${base}_${qualifier}`), taken);
105
+ if (id !== flow.id)
106
+ renamed.set(flow.id, id);
107
+ flow.id = id;
108
+ }
109
+ }
110
+ if (renamed.size === 0)
111
+ return;
112
+ for (const element of elements) {
113
+ if (!("default" in element) || element.default === undefined)
114
+ continue;
115
+ const replacement = renamed.get(element.default);
116
+ if (replacement !== undefined)
117
+ element.default = replacement;
118
+ }
119
+ }
120
+ /**
121
+ * Derives a root definition's id from what callers look it up by — a message or
122
+ * signal name, an error or escalation code — so the same declaration keeps the
123
+ * same id across rebuilds.
124
+ *
125
+ * @param prefix - Element kind, e.g. `"Message"`.
126
+ * @param source - The name or code the definition is resolved by.
127
+ * @param existing - Definitions of the same kind already declared, whose ids
128
+ * the result is deduped against.
129
+ */
130
+ export function rootDefinitionId(prefix, source, existing) {
131
+ const taken = new Set(existing.map((definition) => definition.id));
132
+ return uniqueId(capLength(`${prefix}_${ncName(slugify(source))}`), taken);
133
+ }
134
+ //# sourceMappingURL=stable-ids.js.map
@@ -1,4 +1,15 @@
1
1
  import { generateId } from "../types/id-generator.js";
2
+ /**
3
+ * Every generated component carries a layout. Camunda Modeler and the form-js importer
4
+ * treat a missing `layout` as a legacy schema and backfill a row/columns pair on open,
5
+ * which would show up as a spurious diff on a form this builder just produced.
6
+ */
7
+ function resolveLayout(layout) {
8
+ return {
9
+ row: layout?.row ?? generateId("Row"),
10
+ columns: layout?.columns ?? null,
11
+ };
12
+ }
2
13
  /** Builder for constructing Camunda Forms programmatically. */
3
14
  export class FormBuilder {
4
15
  _id;
@@ -51,8 +62,7 @@ export class FormBuilder {
51
62
  };
52
63
  if (options?.label !== undefined)
53
64
  component.label = options.label;
54
- if (options?.layout !== undefined)
55
- component.layout = options.layout;
65
+ component.layout = resolveLayout(options?.layout);
56
66
  this._components.push(component);
57
67
  return this;
58
68
  }
@@ -68,8 +78,7 @@ export class FormBuilder {
68
78
  component.validate = options.validate;
69
79
  if (options?.defaultValue !== undefined)
70
80
  component.defaultValue = options.defaultValue;
71
- if (options?.layout !== undefined)
72
- component.layout = options.layout;
81
+ component.layout = resolveLayout(options?.layout);
73
82
  this._components.push(component);
74
83
  return this;
75
84
  }
@@ -85,8 +94,7 @@ export class FormBuilder {
85
94
  component.validate = options.validate;
86
95
  if (options?.defaultValue !== undefined)
87
96
  component.defaultValue = options.defaultValue;
88
- if (options?.layout !== undefined)
89
- component.layout = options.layout;
97
+ component.layout = resolveLayout(options?.layout);
90
98
  this._components.push(component);
91
99
  return this;
92
100
  }
@@ -108,8 +116,7 @@ export class FormBuilder {
108
116
  component.searchable = options.searchable;
109
117
  if (options?.defaultValue !== undefined)
110
118
  component.defaultValue = options.defaultValue;
111
- if (options?.layout !== undefined)
112
- component.layout = options.layout;
119
+ component.layout = resolveLayout(options?.layout);
113
120
  this._components.push(component);
114
121
  return this;
115
122
  }
@@ -126,8 +133,7 @@ export class FormBuilder {
126
133
  component.validate = options.validate;
127
134
  if (options?.defaultValue !== undefined)
128
135
  component.defaultValue = options.defaultValue;
129
- if (options?.layout !== undefined)
130
- component.layout = options.layout;
136
+ component.layout = resolveLayout(options?.layout);
131
137
  this._components.push(component);
132
138
  return this;
133
139
  }
@@ -143,8 +149,7 @@ export class FormBuilder {
143
149
  component.validate = options.validate;
144
150
  if (options?.defaultValue !== undefined)
145
151
  component.defaultValue = options.defaultValue;
146
- if (options?.layout !== undefined)
147
- component.layout = options.layout;
152
+ component.layout = resolveLayout(options?.layout);
148
153
  this._components.push(component);
149
154
  return this;
150
155
  }
@@ -159,8 +164,7 @@ export class FormBuilder {
159
164
  };
160
165
  if (options?.validate !== undefined)
161
166
  component.validate = options.validate;
162
- if (options?.layout !== undefined)
163
- component.layout = options.layout;
167
+ component.layout = resolveLayout(options?.layout);
164
168
  this._components.push(component);
165
169
  return this;
166
170
  }
@@ -176,8 +180,7 @@ export class FormBuilder {
176
180
  };
177
181
  if (options?.showOutline !== undefined)
178
182
  component.showOutline = options.showOutline;
179
- if (options?.layout !== undefined)
180
- component.layout = options.layout;
183
+ component.layout = resolveLayout(options?.layout);
181
184
  this._components.push(component);
182
185
  return this;
183
186
  }
@@ -220,8 +223,7 @@ export class GroupBuilder {
220
223
  };
221
224
  if (options?.label !== undefined)
222
225
  component.label = options.label;
223
- if (options?.layout !== undefined)
224
- component.layout = options.layout;
226
+ component.layout = resolveLayout(options?.layout);
225
227
  this._components.push(component);
226
228
  return this;
227
229
  }
@@ -236,8 +238,7 @@ export class GroupBuilder {
236
238
  component.validate = options.validate;
237
239
  if (options?.defaultValue !== undefined)
238
240
  component.defaultValue = options.defaultValue;
239
- if (options?.layout !== undefined)
240
- component.layout = options.layout;
241
+ component.layout = resolveLayout(options?.layout);
241
242
  this._components.push(component);
242
243
  return this;
243
244
  }
@@ -252,8 +253,7 @@ export class GroupBuilder {
252
253
  component.validate = options.validate;
253
254
  if (options?.defaultValue !== undefined)
254
255
  component.defaultValue = options.defaultValue;
255
- if (options?.layout !== undefined)
256
- component.layout = options.layout;
256
+ component.layout = resolveLayout(options?.layout);
257
257
  this._components.push(component);
258
258
  return this;
259
259
  }
@@ -274,8 +274,7 @@ export class GroupBuilder {
274
274
  component.searchable = options.searchable;
275
275
  if (options?.defaultValue !== undefined)
276
276
  component.defaultValue = options.defaultValue;
277
- if (options?.layout !== undefined)
278
- component.layout = options.layout;
277
+ component.layout = resolveLayout(options?.layout);
279
278
  this._components.push(component);
280
279
  return this;
281
280
  }
@@ -291,8 +290,7 @@ export class GroupBuilder {
291
290
  component.validate = options.validate;
292
291
  if (options?.defaultValue !== undefined)
293
292
  component.defaultValue = options.defaultValue;
294
- if (options?.layout !== undefined)
295
- component.layout = options.layout;
293
+ component.layout = resolveLayout(options?.layout);
296
294
  this._components.push(component);
297
295
  return this;
298
296
  }
@@ -307,8 +305,7 @@ export class GroupBuilder {
307
305
  component.validate = options.validate;
308
306
  if (options?.defaultValue !== undefined)
309
307
  component.defaultValue = options.defaultValue;
310
- if (options?.layout !== undefined)
311
- component.layout = options.layout;
308
+ component.layout = resolveLayout(options?.layout);
312
309
  this._components.push(component);
313
310
  return this;
314
311
  }
@@ -322,8 +319,7 @@ export class GroupBuilder {
322
319
  };
323
320
  if (options?.validate !== undefined)
324
321
  component.validate = options.validate;
325
- if (options?.layout !== undefined)
326
- component.layout = options.layout;
322
+ component.layout = resolveLayout(options?.layout);
327
323
  this._components.push(component);
328
324
  return this;
329
325
  }
@@ -338,8 +334,7 @@ export class GroupBuilder {
338
334
  };
339
335
  if (options?.showOutline !== undefined)
340
336
  component.showOutline = options.showOutline;
341
- if (options?.layout !== undefined)
342
- component.layout = options.layout;
337
+ component.layout = resolveLayout(options?.layout);
343
338
  this._components.push(component);
344
339
  return this;
345
340
  }
package/dist/index.d.ts CHANGED
@@ -56,6 +56,9 @@ export type { BenchmarkResult, BoundingBox, ElementComparison, ElementPosition,
56
56
  export type { Bounds, LayoutEdge, LayoutNode, LayoutResult, Waypoint } from "./layout/index.js";
57
57
  export { ELEMENT_SIZES, GRID_CELL_HEIGHT, GRID_CELL_WIDTH } from "./layout/index.js";
58
58
  export { compactify, expand } from "./bpmn/compact.js";
59
+ export { ELEMENT_GROUP_ORDER, ELEMENT_TYPE_GROUPS, allElementTypes, elementTypesInGroup, } from "./bpmn/element-catalog.js";
60
+ export type { ElementTypeGroup } from "./bpmn/element-catalog.js";
61
+ export { createFlowElement, retypeElement } from "./bpmn/element-shape.js";
59
62
  export { applyOperations } from "./bpmn/operations.js";
60
63
  export type { BpmnOperation } from "./bpmn/operations.js";
61
64
  export { applyBpmnOperations, reconcileCompact, OperationError } from "./bpmn/full-operations.js";
package/dist/index.js CHANGED
@@ -30,6 +30,8 @@ export { layoutProcess, layoutFlowNodes } from "./layout/index.js";
30
30
  export { benchmarkLayout, compareLayouts, formatBenchmarkResult, generateAutoLayout, parseReferenceLayout, } from "./layout/index.js";
31
31
  export { ELEMENT_SIZES, GRID_CELL_HEIGHT, GRID_CELL_WIDTH } from "./layout/index.js";
32
32
  export { compactify, expand } from "./bpmn/compact.js";
33
+ export { ELEMENT_GROUP_ORDER, ELEMENT_TYPE_GROUPS, allElementTypes, elementTypesInGroup, } from "./bpmn/element-catalog.js";
34
+ export { createFlowElement, retypeElement } from "./bpmn/element-shape.js";
33
35
  export { applyOperations } from "./bpmn/operations.js";
34
36
  export { applyBpmnOperations, reconcileCompact, OperationError } from "./bpmn/full-operations.js";
35
37
  export { buildValidationDmn, findValidationStructure, getValidationInputNames, insertValidationStructure, removeValidationStructure, validationDecisionId, } from "./bpmn/input-validation.js";
@@ -24,6 +24,10 @@ export const ELEMENT_SIZES = {
24
24
  adHocSubProcess: { width: 100, height: 80 },
25
25
  eventSubProcess: { width: 100, height: 80 },
26
26
  transaction: { width: 100, height: 80 },
27
+ // Data elements are drawn as the page and cylinder glyphs, not as activities.
28
+ dataObject: { width: 36, height: 50 },
29
+ dataObjectReference: { width: 36, height: 50 },
30
+ dataStoreReference: { width: 50, height: 50 },
27
31
  };
28
32
  /** Virtual grid cell dimensions for element placement. */
29
33
  export const GRID_CELL_WIDTH = 150;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bpmnkit/core",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "type": "module",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
@@ -21,7 +21,7 @@
21
21
  "dist/**/*.d.ts"
22
22
  ],
23
23
  "dependencies": {
24
- "@bpmnkit/feel": "0.0.20"
24
+ "@bpmnkit/feel": "0.0.21"
25
25
  },
26
26
  "description": "TypeScript-first BPMN 2.0 SDK — parse, build, layout, and optimize diagrams",
27
27
  "keywords": [
@@ -52,6 +52,7 @@
52
52
  "check": "biome check .",
53
53
  "test": "vitest run",
54
54
  "check:descriptors": "tsx scripts/descriptor-report.ts",
55
+ "check:builder": "tsx scripts/builder-report.ts",
55
56
  "generate:placement": "tsx scripts/generate-zeebe-placement.ts",
56
57
  "check:placement": "tsx scripts/generate-zeebe-placement.ts --check",
57
58
  "format-bpmn": "node scripts/format-bpmn.mjs"