@bpmnkit/core 0.6.0 → 0.7.1

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.
package/README.md CHANGED
@@ -317,6 +317,7 @@ const { semanticHash, changes } = await writeBpmn(defs, { output: "flow.bpmn" })
317
317
  | [`@bpmnkit/api`](https://www.npmjs.com/package/@bpmnkit/api) | Camunda 8 REST API TypeScript client |
318
318
  | [`@bpmnkit/ascii`](https://www.npmjs.com/package/@bpmnkit/ascii) | Render BPMN diagrams as Unicode ASCII art |
319
319
  | [`@bpmnkit/docspack`](https://www.npmjs.com/package/@bpmnkit/docspack) | BPMN Kit docs as an offline docspack package for AI agents |
320
+ | [`@bpmnkit/camunda-docspack`](https://www.npmjs.com/package/@bpmnkit/camunda-docspack) | Camunda 8 docs as an offline docspack package for AI agents |
320
321
  | [`@bpmnkit/ui`](https://www.npmjs.com/package/@bpmnkit/ui) | Shared design tokens and UI components |
321
322
  | [`@bpmnkit/profiles`](https://www.npmjs.com/package/@bpmnkit/profiles) | Shared auth, profile storage, and client factories for CLI & proxy |
322
323
  | [`@bpmnkit/operate`](https://www.npmjs.com/package/@bpmnkit/operate) | Monitoring & operations frontend for Camunda clusters |
@@ -129,6 +129,11 @@ function collectNames(node, out) {
129
129
  for (const arg of node.args)
130
130
  collectNames(arg, out);
131
131
  break;
132
+ case "call-expr":
133
+ collectNames(node.target, out);
134
+ for (const arg of node.args)
135
+ collectNames(arg, out);
136
+ break;
132
137
  case "call-named":
133
138
  for (const arg of node.args)
134
139
  collectNames(arg.value, out);
@@ -1,4 +1,4 @@
1
- import type { FormComponent, FormDefinition, FormLayout, FormValidation, FormValueOption } from "./form-model.js";
1
+ import type { FormComponent, FormDefinition, FormLayoutInput, FormValidation, FormValueOption } from "./form-model.js";
2
2
  /** Builder for constructing Camunda Forms programmatically. */
3
3
  export declare class FormBuilder {
4
4
  private _id;
@@ -9,8 +9,17 @@ export declare class FormBuilder {
9
9
  private _schemaVersion?;
10
10
  private _generated?;
11
11
  private readonly _components;
12
+ private _names;
12
13
  constructor(id?: string);
13
- /** Sets the form ID. */
14
+ /**
15
+ * Sets the form ID.
16
+ *
17
+ * Set it before adding components. The form id is what scopes their generated
18
+ * ids and rows — so that one field key means different ids in two different
19
+ * forms — and components added earlier keep the names they were given under
20
+ * the previous id. Output stays deterministic either way; it just is not the
21
+ * same output as passing the id to the constructor.
22
+ */
14
23
  id(id: string): this;
15
24
  /** Sets the execution platform. */
16
25
  executionPlatform(platform: string): this;
@@ -26,7 +35,7 @@ export declare class FormBuilder {
26
35
  text(text: string, options?: {
27
36
  id?: string;
28
37
  label?: string;
29
- layout?: FormLayout;
38
+ layout?: FormLayoutInput;
30
39
  }): this;
31
40
  /** Adds a text field component. */
32
41
  textfield(label: string, key: string, options?: TextFieldOptions): this;
@@ -51,11 +60,19 @@ export declare class GroupBuilder {
51
60
  readonly _id: string;
52
61
  /** @internal */
53
62
  readonly _components: FormComponent[];
63
+ private readonly _names;
64
+ /**
65
+ * @param id - The group component's id, and the scope its children's generated
66
+ * ids and rows hang off. `FormBuilder.group()` passes the id it resolved for
67
+ * the group, which is itself derived from the form id, so a nested tree is
68
+ * deterministic all the way down. A group built standalone without an id
69
+ * gets a random one, and its children inherit that instability.
70
+ */
54
71
  constructor(id?: string);
55
72
  text(text: string, options?: {
56
73
  id?: string;
57
74
  label?: string;
58
- layout?: FormLayout;
75
+ layout?: FormLayoutInput;
59
76
  }): this;
60
77
  textfield(label: string, key: string, options?: TextFieldOptions): this;
61
78
  textarea(label: string, key: string, options?: TextFieldOptions): this;
@@ -70,7 +87,7 @@ export interface TextFieldOptions {
70
87
  id?: string;
71
88
  validate?: FormValidation;
72
89
  defaultValue?: string;
73
- layout?: FormLayout;
90
+ layout?: FormLayoutInput;
74
91
  }
75
92
  /** Options for select components. */
76
93
  export interface SelectOptions {
@@ -80,32 +97,32 @@ export interface SelectOptions {
80
97
  validate?: FormValidation;
81
98
  searchable?: boolean;
82
99
  defaultValue?: string;
83
- layout?: FormLayout;
100
+ layout?: FormLayoutInput;
84
101
  }
85
102
  /** Options for radio components. */
86
103
  export interface RadioOptions {
87
104
  id?: string;
88
105
  validate?: FormValidation;
89
106
  defaultValue?: string;
90
- layout?: FormLayout;
107
+ layout?: FormLayoutInput;
91
108
  }
92
109
  /** Options for checkbox components. */
93
110
  export interface CheckboxOptions {
94
111
  id?: string;
95
112
  validate?: FormValidation;
96
113
  defaultValue?: boolean;
97
- layout?: FormLayout;
114
+ layout?: FormLayoutInput;
98
115
  }
99
116
  /** Options for checklist components. */
100
117
  export interface ChecklistOptions {
101
118
  id?: string;
102
119
  validate?: FormValidation;
103
- layout?: FormLayout;
120
+ layout?: FormLayoutInput;
104
121
  }
105
122
  /** Options for group components. */
106
123
  export interface GroupOptions {
107
124
  id?: string;
108
125
  showOutline?: boolean;
109
- layout?: FormLayout;
126
+ layout?: FormLayoutInput;
110
127
  }
111
128
  //# sourceMappingURL=form-builder.d.ts.map
@@ -1,14 +1,51 @@
1
1
  import { generateId } from "../types/id-generator.js";
2
+ import { compositeKey, stableToken } from "../types/stable-key.js";
2
3
  /**
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.
4
+ * Mints the id and layout row for the components of one scope — a form, or a
5
+ * group inside it.
6
+ *
7
+ * Every generated component carries a layout because Camunda Modeler and the
8
+ * form-js importer read a missing `layout` as a legacy schema and backfill a
9
+ * row/columns pair on open, showing a spurious diff on a form this builder just
10
+ * produced. Both values are derived from the component's own identity — its
11
+ * field key, or its text for a static block — rather than from its position or
12
+ * from a random draw, so rebuilding an unchanged form is byte-identical and
13
+ * reordering two fields moves nothing but their order. The row lives in its own
14
+ * `"row"` namespace so it never equals the id derived from the same identity.
15
+ *
16
+ * `occurrences` covers the one case identity cannot: two components of a type
17
+ * that are genuinely indistinguishable. Nothing intrinsic separates them, so
18
+ * they are numbered in the order they were added.
6
19
  */
7
- function resolveLayout(layout) {
8
- return {
9
- row: layout?.row ?? generateId("Row"),
10
- columns: layout?.columns ?? null,
11
- };
20
+ class ScopeNames {
21
+ scope;
22
+ occurrences = new Map();
23
+ constructor(scope) {
24
+ this.scope = scope;
25
+ }
26
+ /**
27
+ * @param type - The component's `type` discriminator.
28
+ * @param identity - What the component is known by: its field key, or its
29
+ * text or label when it has no key.
30
+ */
31
+ resolve(type, identity, options) {
32
+ const segments = [this.scope, type, identity];
33
+ const key = compositeKey(segments);
34
+ const occurrence = (this.occurrences.get(key) ?? 0) + 1;
35
+ this.occurrences.set(key, occurrence);
36
+ if (occurrence > 1)
37
+ segments.push(`#${occurrence}`);
38
+ return {
39
+ id: options?.id ?? stableToken("Field", segments),
40
+ layout: {
41
+ // `??` is the whole null asymmetry documented on FormLayoutInput: a
42
+ // null row falls through to a generated one, a null columns lands on
43
+ // null and is kept.
44
+ row: options?.layout?.row ?? stableToken("Row", [...segments, "row"]),
45
+ columns: options?.layout?.columns ?? null,
46
+ },
47
+ };
48
+ }
12
49
  }
13
50
  /** Builder for constructing Camunda Forms programmatically. */
14
51
  export class FormBuilder {
@@ -20,12 +57,23 @@ export class FormBuilder {
20
57
  _schemaVersion;
21
58
  _generated;
22
59
  _components = [];
60
+ _names;
23
61
  constructor(id) {
24
62
  this._id = id ?? generateId("Form");
63
+ this._names = new ScopeNames(this._id);
25
64
  }
26
- /** Sets the form ID. */
65
+ /**
66
+ * Sets the form ID.
67
+ *
68
+ * Set it before adding components. The form id is what scopes their generated
69
+ * ids and rows — so that one field key means different ids in two different
70
+ * forms — and components added earlier keep the names they were given under
71
+ * the previous id. Output stays deterministic either way; it just is not the
72
+ * same output as passing the id to the constructor.
73
+ */
27
74
  id(id) {
28
75
  this._id = id;
76
+ this._names = new ScopeNames(id);
29
77
  return this;
30
78
  }
31
79
  /** Sets the execution platform. */
@@ -55,22 +103,24 @@ export class FormBuilder {
55
103
  }
56
104
  /** Adds a static text component. */
57
105
  text(text, options) {
106
+ const names = this._names.resolve("text", text, options);
58
107
  const component = {
59
108
  type: "text",
60
- id: options?.id ?? generateId("Field"),
109
+ id: names.id,
61
110
  text,
62
111
  };
63
112
  if (options?.label !== undefined)
64
113
  component.label = options.label;
65
- component.layout = resolveLayout(options?.layout);
114
+ component.layout = names.layout;
66
115
  this._components.push(component);
67
116
  return this;
68
117
  }
69
118
  /** Adds a text field component. */
70
119
  textfield(label, key, options) {
120
+ const names = this._names.resolve("textfield", key, options);
71
121
  const component = {
72
122
  type: "textfield",
73
- id: options?.id ?? generateId("Field"),
123
+ id: names.id,
74
124
  label,
75
125
  key,
76
126
  };
@@ -78,15 +128,16 @@ export class FormBuilder {
78
128
  component.validate = options.validate;
79
129
  if (options?.defaultValue !== undefined)
80
130
  component.defaultValue = options.defaultValue;
81
- component.layout = resolveLayout(options?.layout);
131
+ component.layout = names.layout;
82
132
  this._components.push(component);
83
133
  return this;
84
134
  }
85
135
  /** Adds a textarea component. */
86
136
  textarea(label, key, options) {
137
+ const names = this._names.resolve("textarea", key, options);
87
138
  const component = {
88
139
  type: "textarea",
89
- id: options?.id ?? generateId("Field"),
140
+ id: names.id,
90
141
  label,
91
142
  key,
92
143
  };
@@ -94,15 +145,16 @@ export class FormBuilder {
94
145
  component.validate = options.validate;
95
146
  if (options?.defaultValue !== undefined)
96
147
  component.defaultValue = options.defaultValue;
97
- component.layout = resolveLayout(options?.layout);
148
+ component.layout = names.layout;
98
149
  this._components.push(component);
99
150
  return this;
100
151
  }
101
152
  /** Adds a select dropdown component. */
102
153
  select(label, key, options) {
154
+ const names = this._names.resolve("select", key, options);
103
155
  const component = {
104
156
  type: "select",
105
- id: options?.id ?? generateId("Field"),
157
+ id: names.id,
106
158
  label,
107
159
  key,
108
160
  };
@@ -116,15 +168,16 @@ export class FormBuilder {
116
168
  component.searchable = options.searchable;
117
169
  if (options?.defaultValue !== undefined)
118
170
  component.defaultValue = options.defaultValue;
119
- component.layout = resolveLayout(options?.layout);
171
+ component.layout = names.layout;
120
172
  this._components.push(component);
121
173
  return this;
122
174
  }
123
175
  /** Adds a radio button group component. */
124
176
  radio(label, key, values, options) {
177
+ const names = this._names.resolve("radio", key, options);
125
178
  const component = {
126
179
  type: "radio",
127
- id: options?.id ?? generateId("Field"),
180
+ id: names.id,
128
181
  label,
129
182
  key,
130
183
  values,
@@ -133,15 +186,16 @@ export class FormBuilder {
133
186
  component.validate = options.validate;
134
187
  if (options?.defaultValue !== undefined)
135
188
  component.defaultValue = options.defaultValue;
136
- component.layout = resolveLayout(options?.layout);
189
+ component.layout = names.layout;
137
190
  this._components.push(component);
138
191
  return this;
139
192
  }
140
193
  /** Adds a checkbox component. */
141
194
  checkbox(label, key, options) {
195
+ const names = this._names.resolve("checkbox", key, options);
142
196
  const component = {
143
197
  type: "checkbox",
144
- id: options?.id ?? generateId("Field"),
198
+ id: names.id,
145
199
  label,
146
200
  key,
147
201
  };
@@ -149,28 +203,30 @@ export class FormBuilder {
149
203
  component.validate = options.validate;
150
204
  if (options?.defaultValue !== undefined)
151
205
  component.defaultValue = options.defaultValue;
152
- component.layout = resolveLayout(options?.layout);
206
+ component.layout = names.layout;
153
207
  this._components.push(component);
154
208
  return this;
155
209
  }
156
210
  /** Adds a checklist component. */
157
211
  checklist(label, key, values, options) {
212
+ const names = this._names.resolve("checklist", key, options);
158
213
  const component = {
159
214
  type: "checklist",
160
- id: options?.id ?? generateId("Field"),
215
+ id: names.id,
161
216
  label,
162
217
  key,
163
218
  values,
164
219
  };
165
220
  if (options?.validate !== undefined)
166
221
  component.validate = options.validate;
167
- component.layout = resolveLayout(options?.layout);
222
+ component.layout = names.layout;
168
223
  this._components.push(component);
169
224
  return this;
170
225
  }
171
226
  /** Adds a group component with nested children built via a callback. */
172
227
  group(label, builder, options) {
173
- const groupBuilder = new GroupBuilder(options?.id);
228
+ const names = this._names.resolve("group", label, options);
229
+ const groupBuilder = new GroupBuilder(names.id);
174
230
  builder(groupBuilder);
175
231
  const component = {
176
232
  type: "group",
@@ -180,7 +236,7 @@ export class FormBuilder {
180
236
  };
181
237
  if (options?.showOutline !== undefined)
182
238
  component.showOutline = options.showOutline;
183
- component.layout = resolveLayout(options?.layout);
239
+ component.layout = names.layout;
184
240
  this._components.push(component);
185
241
  return this;
186
242
  }
@@ -212,25 +268,36 @@ export class GroupBuilder {
212
268
  _id;
213
269
  /** @internal */
214
270
  _components = [];
271
+ _names;
272
+ /**
273
+ * @param id - The group component's id, and the scope its children's generated
274
+ * ids and rows hang off. `FormBuilder.group()` passes the id it resolved for
275
+ * the group, which is itself derived from the form id, so a nested tree is
276
+ * deterministic all the way down. A group built standalone without an id
277
+ * gets a random one, and its children inherit that instability.
278
+ */
215
279
  constructor(id) {
216
280
  this._id = id ?? generateId("Field");
281
+ this._names = new ScopeNames(this._id);
217
282
  }
218
283
  text(text, options) {
284
+ const names = this._names.resolve("text", text, options);
219
285
  const component = {
220
286
  type: "text",
221
- id: options?.id ?? generateId("Field"),
287
+ id: names.id,
222
288
  text,
223
289
  };
224
290
  if (options?.label !== undefined)
225
291
  component.label = options.label;
226
- component.layout = resolveLayout(options?.layout);
292
+ component.layout = names.layout;
227
293
  this._components.push(component);
228
294
  return this;
229
295
  }
230
296
  textfield(label, key, options) {
297
+ const names = this._names.resolve("textfield", key, options);
231
298
  const component = {
232
299
  type: "textfield",
233
- id: options?.id ?? generateId("Field"),
300
+ id: names.id,
234
301
  label,
235
302
  key,
236
303
  };
@@ -238,14 +305,15 @@ export class GroupBuilder {
238
305
  component.validate = options.validate;
239
306
  if (options?.defaultValue !== undefined)
240
307
  component.defaultValue = options.defaultValue;
241
- component.layout = resolveLayout(options?.layout);
308
+ component.layout = names.layout;
242
309
  this._components.push(component);
243
310
  return this;
244
311
  }
245
312
  textarea(label, key, options) {
313
+ const names = this._names.resolve("textarea", key, options);
246
314
  const component = {
247
315
  type: "textarea",
248
- id: options?.id ?? generateId("Field"),
316
+ id: names.id,
249
317
  label,
250
318
  key,
251
319
  };
@@ -253,14 +321,15 @@ export class GroupBuilder {
253
321
  component.validate = options.validate;
254
322
  if (options?.defaultValue !== undefined)
255
323
  component.defaultValue = options.defaultValue;
256
- component.layout = resolveLayout(options?.layout);
324
+ component.layout = names.layout;
257
325
  this._components.push(component);
258
326
  return this;
259
327
  }
260
328
  select(label, key, options) {
329
+ const names = this._names.resolve("select", key, options);
261
330
  const component = {
262
331
  type: "select",
263
- id: options?.id ?? generateId("Field"),
332
+ id: names.id,
264
333
  label,
265
334
  key,
266
335
  };
@@ -274,14 +343,15 @@ export class GroupBuilder {
274
343
  component.searchable = options.searchable;
275
344
  if (options?.defaultValue !== undefined)
276
345
  component.defaultValue = options.defaultValue;
277
- component.layout = resolveLayout(options?.layout);
346
+ component.layout = names.layout;
278
347
  this._components.push(component);
279
348
  return this;
280
349
  }
281
350
  radio(label, key, values, options) {
351
+ const names = this._names.resolve("radio", key, options);
282
352
  const component = {
283
353
  type: "radio",
284
- id: options?.id ?? generateId("Field"),
354
+ id: names.id,
285
355
  label,
286
356
  key,
287
357
  values,
@@ -290,14 +360,15 @@ export class GroupBuilder {
290
360
  component.validate = options.validate;
291
361
  if (options?.defaultValue !== undefined)
292
362
  component.defaultValue = options.defaultValue;
293
- component.layout = resolveLayout(options?.layout);
363
+ component.layout = names.layout;
294
364
  this._components.push(component);
295
365
  return this;
296
366
  }
297
367
  checkbox(label, key, options) {
368
+ const names = this._names.resolve("checkbox", key, options);
298
369
  const component = {
299
370
  type: "checkbox",
300
- id: options?.id ?? generateId("Field"),
371
+ id: names.id,
301
372
  label,
302
373
  key,
303
374
  };
@@ -305,26 +376,28 @@ export class GroupBuilder {
305
376
  component.validate = options.validate;
306
377
  if (options?.defaultValue !== undefined)
307
378
  component.defaultValue = options.defaultValue;
308
- component.layout = resolveLayout(options?.layout);
379
+ component.layout = names.layout;
309
380
  this._components.push(component);
310
381
  return this;
311
382
  }
312
383
  checklist(label, key, values, options) {
384
+ const names = this._names.resolve("checklist", key, options);
313
385
  const component = {
314
386
  type: "checklist",
315
- id: options?.id ?? generateId("Field"),
387
+ id: names.id,
316
388
  label,
317
389
  key,
318
390
  values,
319
391
  };
320
392
  if (options?.validate !== undefined)
321
393
  component.validate = options.validate;
322
- component.layout = resolveLayout(options?.layout);
394
+ component.layout = names.layout;
323
395
  this._components.push(component);
324
396
  return this;
325
397
  }
326
398
  group(label, builder, options) {
327
- const groupBuilder = new GroupBuilder(options?.id);
399
+ const names = this._names.resolve("group", label, options);
400
+ const groupBuilder = new GroupBuilder(names.id);
328
401
  builder(groupBuilder);
329
402
  const component = {
330
403
  type: "group",
@@ -334,7 +407,7 @@ export class GroupBuilder {
334
407
  };
335
408
  if (options?.showOutline !== undefined)
336
409
  component.showOutline = options.showOutline;
337
- component.layout = resolveLayout(options?.layout);
410
+ component.layout = names.layout;
338
411
  this._components.push(component);
339
412
  return this;
340
413
  }
@@ -3,6 +3,22 @@ export interface FormLayout {
3
3
  row?: string;
4
4
  columns?: number | null;
5
5
  }
6
+ /**
7
+ * A layout as a caller hands it to the builder. Both fields accept `null`, and
8
+ * the two mean opposite things — deliberately, and worth reading twice, because
9
+ * they are siblings in one object and easy to treat alike by mistake:
10
+ *
11
+ * - `row: null` is **not set**. A generated row is filled in. Renderers collapse
12
+ * every `row: null` field into one shared row, which is essentially never what
13
+ * a caller who declined to name a row was asking for, so `null` is not trusted
14
+ * here as an intentional value.
15
+ * - `columns: null` **is** intentional — the field spans its own row, which is
16
+ * the Camunda default — and is preserved as given.
17
+ */
18
+ export interface FormLayoutInput {
19
+ row?: string | null;
20
+ columns?: number | null;
21
+ }
6
22
  /** Validation constraints for a form field. */
7
23
  export interface FormValidation {
8
24
  required?: boolean;
@@ -1,4 +1,4 @@
1
- export type { FormComponent, FormButtonComponent, FormCheckboxComponent, FormChecklistComponent, FormDatetimeComponent, FormDefinition, FormDocumentPreviewComponent, FormDynamicListComponent, FormExporter, FormExpressionComponent, FormFilepickerComponent, FormGroupComponent, FormHtmlComponent, FormIframeComponent, FormImageComponent, FormLayout, FormNumberComponent, FormRadioComponent, FormSelectComponent, FormSeparatorComponent, FormSpacerComponent, FormTableComponent, FormTaglistComponent, FormTextAreaComponent, FormTextComponent, FormTextFieldComponent, FormUnknownComponent, FormValidation, FormValueOption, } from "./form-model.js";
1
+ export type { FormComponent, FormButtonComponent, FormCheckboxComponent, FormChecklistComponent, FormDatetimeComponent, FormDefinition, FormDocumentPreviewComponent, FormDynamicListComponent, FormExporter, FormExpressionComponent, FormFilepickerComponent, FormGroupComponent, FormHtmlComponent, FormIframeComponent, FormImageComponent, FormLayout, FormLayoutInput, FormNumberComponent, FormRadioComponent, FormSelectComponent, FormSeparatorComponent, FormSpacerComponent, FormTableComponent, FormTaglistComponent, FormTextAreaComponent, FormTextComponent, FormTextFieldComponent, FormUnknownComponent, FormValidation, FormValueOption, } from "./form-model.js";
2
2
  export { parseForm } from "./form-parser.js";
3
3
  export { exportForm } from "./form-serializer.js";
4
4
  export { FormBuilder, GroupBuilder } from "./form-builder.js";
package/dist/index.d.ts CHANGED
@@ -14,6 +14,7 @@ export type { PreservingWriteResult } from "./bpmn/preserving-writer.js";
14
14
  export { exportDmnPreserving, preserveDmnFormatting } from "./dmn/preserving-writer.js";
15
15
  export type { BpmnDiffCategory, BpmnDiffPlaneSummary, BpmnDiffResult, } from "./bpmn/diagram-diff.js";
16
16
  export { sha256Hex } from "./bpmn/sha256.js";
17
+ export { compositeKey, stableToken } from "./types/stable-key.js";
17
18
  export { checkDiCompleteness } from "./bpmn/di-check.js";
18
19
  export type { DiCompleteness } from "./bpmn/di-check.js";
19
20
  export { planeForElement, listPlaneElementIds } from "./bpmn/di-planes.js";
@@ -32,7 +33,7 @@ export { Form, compactifyForm, expandForm } from "./form/index.js";
32
33
  export type { CompactForm, CompactFormField } from "./form/index.js";
33
34
  export { FormBuilder, GroupBuilder } from "./form/form-builder.js";
34
35
  export type { TextFieldOptions, SelectOptions, RadioOptions, CheckboxOptions, ChecklistOptions, GroupOptions, } from "./form/form-builder.js";
35
- export type { FormComponent, FormCheckboxComponent, FormChecklistComponent, FormDefinition, FormExporter, FormGroupComponent, FormLayout, FormRadioComponent, FormSelectComponent, FormTextAreaComponent, FormTextComponent, FormTextFieldComponent, FormValidation, FormValueOption, FormNumberComponent, FormDatetimeComponent, FormButtonComponent, FormTaglistComponent, FormTableComponent, FormImageComponent, FormDynamicListComponent, FormIframeComponent, FormSeparatorComponent, FormSpacerComponent, FormDocumentPreviewComponent, FormHtmlComponent, FormExpressionComponent, FormFilepickerComponent, FormUnknownComponent, } from "./form/form-model.js";
36
+ export type { FormComponent, FormCheckboxComponent, FormChecklistComponent, FormDefinition, FormExporter, FormGroupComponent, FormLayout, FormLayoutInput, FormRadioComponent, FormSelectComponent, FormTextAreaComponent, FormTextComponent, FormTextFieldComponent, FormValidation, FormValueOption, FormNumberComponent, FormDatetimeComponent, FormButtonComponent, FormTaglistComponent, FormTableComponent, FormImageComponent, FormDynamicListComponent, FormIframeComponent, FormSeparatorComponent, FormSpacerComponent, FormDocumentPreviewComponent, FormHtmlComponent, FormExpressionComponent, FormFilepickerComponent, FormUnknownComponent, } from "./form/form-model.js";
36
37
  export type { DecisionTableBuilder, InputOptions, OutputOptions, RuleOptions, } from "./dmn/dmn-builder.js";
37
38
  export type { DmnDefinitions, DmnDecision, DmnDecisionTable, DmnInput, DmnOutput, DmnRule, DmnInputEntry, DmnOutputEntry, DmnDiagram, DmnDiagramShape, DmnDiagramEdge, DmnWaypoint, DmnTypeRef, DmnAggregation, HitPolicy, DmnInformationRequirement, DmnKnowledgeRequirement, DmnAuthorityRequirement, DmnInputData, DmnKnowledgeSource, DmnBusinessKnowledgeModel, DmnTextAnnotation, DmnAssociation, } from "./dmn/dmn-model.js";
38
39
  export type { XmlElement } from "./types/xml-element.js";
package/dist/index.js CHANGED
@@ -9,6 +9,7 @@ export { diffDiagram } from "./bpmn/diagram-diff.js";
9
9
  export { exportPreserving, exportPreservingResult, preserveBpmnFormatting, } from "./bpmn/preserving-writer.js";
10
10
  export { exportDmnPreserving, preserveDmnFormatting } from "./dmn/preserving-writer.js";
11
11
  export { sha256Hex } from "./bpmn/sha256.js";
12
+ export { compositeKey, stableToken } from "./types/stable-key.js";
12
13
  export { checkDiCompleteness } from "./bpmn/di-check.js";
13
14
  export { planeForElement, listPlaneElementIds } from "./bpmn/di-planes.js";
14
15
  export { DiagramBuilder, ProcessBuilder } from "./bpmn/bpmn-builder.js";
@@ -0,0 +1,20 @@
1
+ /**
2
+ * Assembles the composite key {@link stableToken} hashes.
3
+ *
4
+ * Exported so callers that group or count by key — numbering entities that are
5
+ * genuinely indistinguishable, say — use the same escaping the hash does rather
6
+ * than a second, subtly different join.
7
+ */
8
+ export declare function compositeKey(segments: readonly string[]): string;
9
+ /**
10
+ * Derives a stable token from an entity's identity.
11
+ *
12
+ * @param prefix - The kind of thing named, e.g. `"Field"` or `"Row"`. It also
13
+ * keeps the result a valid NCName, which a bare digest — free to start with a
14
+ * digit — is not.
15
+ * @param segments - The composite key, most general first: the scope, the
16
+ * entity's type, its own identity, and then any namespace separating this
17
+ * token from another derived for the same entity.
18
+ */
19
+ export declare function stableToken(prefix: string, segments: readonly string[]): string;
20
+ //# sourceMappingURL=stable-key.d.ts.map
@@ -0,0 +1,51 @@
1
+ /**
2
+ * Deterministic tokens derived from what an entity *is*, never from where it
3
+ * sits or when it was generated.
4
+ *
5
+ * Generated documents are rebuilt constantly and reviewed as a diff, so the one
6
+ * property that matters is that an unchanged model produces byte-identical
7
+ * output. The two obvious sources both fail it: an incrementing counter moves
8
+ * the moment generation order or array order changes, and `crypto` moves on
9
+ * every run. Hashing a composite key assembled only from the entity's own
10
+ * identity moves when — and only when — that identity does.
11
+ *
12
+ * The key reads `scope:type:identity`, with any further segments distinguishing
13
+ * several tokens derived for one entity — an id *and* a row, say, which must
14
+ * not come out equal. `scope` is the enclosing document or container, so the
15
+ * same field key in two different forms does not collide.
16
+ */
17
+ import { sha256Hex } from "../bpmn/sha256.js";
18
+ /** Hex digits kept from the digest: 48 bits, far past collision at document scale. */
19
+ const TOKEN_LENGTH = 12;
20
+ /**
21
+ * Escapes the separator, so `["a:b", "c"]` and `["a", "b:c"]` cannot assemble
22
+ * the same key. Without it the composite is ambiguous and two entities that
23
+ * share nothing can still hash alike.
24
+ */
25
+ function escapeSegment(segment) {
26
+ return segment.replace(/\\/g, "\\\\").replace(/:/g, "\\:");
27
+ }
28
+ /**
29
+ * Assembles the composite key {@link stableToken} hashes.
30
+ *
31
+ * Exported so callers that group or count by key — numbering entities that are
32
+ * genuinely indistinguishable, say — use the same escaping the hash does rather
33
+ * than a second, subtly different join.
34
+ */
35
+ export function compositeKey(segments) {
36
+ return segments.map(escapeSegment).join(":");
37
+ }
38
+ /**
39
+ * Derives a stable token from an entity's identity.
40
+ *
41
+ * @param prefix - The kind of thing named, e.g. `"Field"` or `"Row"`. It also
42
+ * keeps the result a valid NCName, which a bare digest — free to start with a
43
+ * digit — is not.
44
+ * @param segments - The composite key, most general first: the scope, the
45
+ * entity's type, its own identity, and then any namespace separating this
46
+ * token from another derived for the same entity.
47
+ */
48
+ export function stableToken(prefix, segments) {
49
+ return `${prefix}_${sha256Hex(compositeKey(segments)).slice(0, TOKEN_LENGTH)}`;
50
+ }
51
+ //# sourceMappingURL=stable-key.js.map
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bpmnkit/core",
3
- "version": "0.6.0",
3
+ "version": "0.7.1",
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.21"
24
+ "@bpmnkit/feel": "0.1.0"
25
25
  },
26
26
  "description": "TypeScript-first BPMN 2.0 SDK — parse, build, layout, and optimize diagrams",
27
27
  "keywords": [