@bpmnkit/core 0.2.0 → 0.4.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.
Files changed (42) hide show
  1. package/dist/bpmn/bpmn-builder.d.ts +71 -0
  2. package/dist/bpmn/bpmn-builder.js +240 -106
  3. package/dist/bpmn/bpmn-serializer.js +70 -0
  4. package/dist/bpmn/builder-coverage.d.ts +59 -0
  5. package/dist/bpmn/builder-coverage.js +62 -0
  6. package/dist/bpmn/compact.d.ts +6 -0
  7. package/dist/bpmn/compact.js +37 -2
  8. package/dist/bpmn/diagram-diff.d.ts +71 -0
  9. package/dist/bpmn/diagram-diff.js +124 -0
  10. package/dist/bpmn/element-catalog.d.ts +31 -0
  11. package/dist/bpmn/element-catalog.js +50 -0
  12. package/dist/bpmn/element-shape.d.ts +49 -0
  13. package/dist/bpmn/element-shape.js +182 -0
  14. package/dist/bpmn/lint.d.ts +97 -0
  15. package/dist/bpmn/lint.js +135 -0
  16. package/dist/bpmn/preserving-writer.d.ts +64 -0
  17. package/dist/bpmn/preserving-writer.js +70 -0
  18. package/dist/bpmn/stable-ids.d.ts +30 -0
  19. package/dist/bpmn/stable-ids.js +134 -0
  20. package/dist/dmn/dmn-serializer.js +7 -2
  21. package/dist/dmn/preserving-writer.d.ts +31 -0
  22. package/dist/dmn/preserving-writer.js +36 -0
  23. package/dist/form/preserving-writer.d.ts +47 -0
  24. package/dist/form/preserving-writer.js +50 -0
  25. package/dist/index.d.ts +15 -1
  26. package/dist/index.js +9 -1
  27. package/dist/json/index.d.ts +5 -0
  28. package/dist/json/index.js +3 -0
  29. package/dist/json/json-patch.d.ts +65 -0
  30. package/dist/json/json-patch.js +416 -0
  31. package/dist/json/json-spans.d.ts +48 -0
  32. package/dist/json/json-spans.js +153 -0
  33. package/dist/layout/types.js +4 -0
  34. package/dist/xml/index.d.ts +5 -1
  35. package/dist/xml/index.js +2 -0
  36. package/dist/xml/xml-parser.d.ts +39 -0
  37. package/dist/xml/xml-parser.js +43 -2
  38. package/dist/xml/xml-patch.d.ts +109 -0
  39. package/dist/xml/xml-patch.js +459 -0
  40. package/dist/xml/xml-spans.d.ts +45 -0
  41. package/dist/xml/xml-spans.js +74 -0
  42. package/package.json +2 -1
@@ -0,0 +1,153 @@
1
+ /**
2
+ * A JSON document parsed into a tree that remembers where everything was.
3
+ *
4
+ * `JSON.parse` gives values with the source thrown away, which is right for
5
+ * everything that reads a document. Rewriting one in place needs the opposite:
6
+ * the exact offsets of each value and each member, so an edit can replace one
7
+ * string instead of regenerating the file.
8
+ *
9
+ * Deliberately not a validator. It accepts what `JSON.parse` accepts and does
10
+ * not try to describe what is wrong with anything else — the caller has already
11
+ * decided this is JSON, and a document that will not parse simply gets no tree.
12
+ *
13
+ * @packageDocumentation
14
+ */
15
+ const WHITESPACE = new Set([" ", "\t", "\n", "\r"]);
16
+ class JsonScanner {
17
+ source;
18
+ i = 0;
19
+ constructor(source) {
20
+ this.source = source;
21
+ }
22
+ parse() {
23
+ this.skipWhitespace();
24
+ const node = this.value();
25
+ this.skipWhitespace();
26
+ if (this.i !== this.source.length) {
27
+ throw new Error(`Unexpected trailing content at position ${this.i}`);
28
+ }
29
+ return node;
30
+ }
31
+ skipWhitespace() {
32
+ while (this.i < this.source.length && WHITESPACE.has(this.source[this.i])) {
33
+ this.i += 1;
34
+ }
35
+ }
36
+ expect(character) {
37
+ if (this.source[this.i] !== character) {
38
+ throw new Error(`Expected "${character}" at position ${this.i}`);
39
+ }
40
+ this.i += 1;
41
+ }
42
+ value() {
43
+ const start = this.i;
44
+ const character = this.source[this.i];
45
+ if (character === "{")
46
+ return this.object(start);
47
+ if (character === "[")
48
+ return this.array(start);
49
+ if (character === '"') {
50
+ const decoded = this.string();
51
+ return { kind: "string", value: decoded, start, end: this.i };
52
+ }
53
+ if (this.source.startsWith("true", this.i)) {
54
+ this.i += 4;
55
+ return { kind: "boolean", value: true, start, end: this.i };
56
+ }
57
+ if (this.source.startsWith("false", this.i)) {
58
+ this.i += 5;
59
+ return { kind: "boolean", value: false, start, end: this.i };
60
+ }
61
+ if (this.source.startsWith("null", this.i)) {
62
+ this.i += 4;
63
+ return { kind: "null", value: null, start, end: this.i };
64
+ }
65
+ return this.number(start);
66
+ }
67
+ object(start) {
68
+ this.expect("{");
69
+ const members = [];
70
+ this.skipWhitespace();
71
+ if (this.source[this.i] === "}") {
72
+ this.i += 1;
73
+ return { kind: "object", members, start, end: this.i };
74
+ }
75
+ for (;;) {
76
+ this.skipWhitespace();
77
+ const memberStart = this.i;
78
+ const key = this.string();
79
+ this.skipWhitespace();
80
+ this.expect(":");
81
+ this.skipWhitespace();
82
+ const value = this.value();
83
+ members.push({ key, value, start: memberStart, end: value.end });
84
+ this.skipWhitespace();
85
+ if (this.source[this.i] === ",") {
86
+ this.i += 1;
87
+ continue;
88
+ }
89
+ this.expect("}");
90
+ return { kind: "object", members, start, end: this.i };
91
+ }
92
+ }
93
+ array(start) {
94
+ this.expect("[");
95
+ const items = [];
96
+ this.skipWhitespace();
97
+ if (this.source[this.i] === "]") {
98
+ this.i += 1;
99
+ return { kind: "array", items, start, end: this.i };
100
+ }
101
+ for (;;) {
102
+ this.skipWhitespace();
103
+ items.push(this.value());
104
+ this.skipWhitespace();
105
+ if (this.source[this.i] === ",") {
106
+ this.i += 1;
107
+ continue;
108
+ }
109
+ this.expect("]");
110
+ return { kind: "array", items, start, end: this.i };
111
+ }
112
+ }
113
+ /** Reads a quoted string, leaving `i` past the closing quote. */
114
+ string() {
115
+ const start = this.i;
116
+ this.expect('"');
117
+ while (this.i < this.source.length) {
118
+ const character = this.source[this.i];
119
+ if (character === "\\") {
120
+ this.i += 2;
121
+ continue;
122
+ }
123
+ if (character === '"') {
124
+ this.i += 1;
125
+ // Let `JSON.parse` own the escape rules rather than repeating them.
126
+ return JSON.parse(this.source.slice(start, this.i));
127
+ }
128
+ this.i += 1;
129
+ }
130
+ throw new Error(`Unterminated string at position ${start}`);
131
+ }
132
+ number(start) {
133
+ while (this.i < this.source.length && /[-+0-9.eE]/.test(this.source[this.i])) {
134
+ this.i += 1;
135
+ }
136
+ const text = this.source.slice(start, this.i);
137
+ const parsed = Number(text);
138
+ if (text === "" || Number.isNaN(parsed)) {
139
+ throw new Error(`Expected a value at position ${start}`);
140
+ }
141
+ return { kind: "number", value: parsed, start, end: this.i };
142
+ }
143
+ }
144
+ /**
145
+ * Parses a document into a tree that knows its own offsets.
146
+ *
147
+ * @param text - A JSON document.
148
+ * @throws Error when it is not one.
149
+ */
150
+ export function parseJsonSpans(text) {
151
+ return new JsonScanner(text).parse();
152
+ }
153
+ //# sourceMappingURL=json-spans.js.map
@@ -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;
@@ -1,4 +1,8 @@
1
1
  export { parseXml, scanXml, serializeXml } from "./xml-parser.js";
2
2
  export { Visit } from "./xml-parser.js";
3
- export type { XmlSink } from "./xml-parser.js";
3
+ export type { XmlCursor, XmlSink } from "./xml-parser.js";
4
+ export { parseXmlSpans } from "./xml-spans.js";
5
+ export type { SpannedAttribute, SpannedElement } from "./xml-spans.js";
6
+ export { preserveFormatting, preserveFormattingVerified } from "./xml-patch.js";
7
+ export type { PreserveOptions, SiblingOrder, VerifiedPreserve } from "./xml-patch.js";
4
8
  //# sourceMappingURL=index.d.ts.map
package/dist/xml/index.js CHANGED
@@ -1,3 +1,5 @@
1
1
  export { parseXml, scanXml, serializeXml } from "./xml-parser.js";
2
2
  export { Visit } from "./xml-parser.js";
3
+ export { parseXmlSpans } from "./xml-spans.js";
4
+ export { preserveFormatting, preserveFormattingVerified } from "./xml-patch.js";
3
5
  //# sourceMappingURL=index.js.map
@@ -13,8 +13,43 @@ export declare const Visit: {
13
13
  readonly ElementsOnly: 2;
14
14
  };
15
15
  export type Visit = (typeof Visit)[keyof typeof Visit];
16
+ /**
17
+ * Where the tag currently being reported sits in the source.
18
+ *
19
+ * A sink that wants source positions asks for them once, by implementing
20
+ * {@link XmlSink.cursor}; the scanner then records offsets as it goes. Sinks
21
+ * that do not ask pay nothing — recording attribute spans in particular costs
22
+ * a map write per attribute, and parsing is the hottest path in this toolkit.
23
+ *
24
+ * The values are only meaningful inside the `start` or `end` call they were
25
+ * reported for; the scanner overwrites them on the next tag.
26
+ */
27
+ export interface XmlCursor {
28
+ /** Offset of the `<` opening the start tag reported by `start`. */
29
+ readonly tagStart: number;
30
+ /** Offset just past the `>` closing that start tag. */
31
+ readonly tagEnd: number;
32
+ /** Offset of the `<` opening the end tag reported by `end`. */
33
+ readonly endTagStart: number;
34
+ /** Offset just past the `>` closing that end tag. */
35
+ readonly endTagEnd: number;
36
+ /**
37
+ * Where an attribute's value sits, between its quotes and excluding them.
38
+ * Only valid during the `start` call that reported the attribute.
39
+ */
40
+ attributeSpan(name: string): {
41
+ readonly start: number;
42
+ readonly end: number;
43
+ } | undefined;
44
+ }
16
45
  /** Receives the events of one XML document from {@link scanXml}. */
17
46
  export interface XmlSink {
47
+ /**
48
+ * Called once before scanning, when implemented, to hand the sink a cursor
49
+ * onto the source. Implementing it switches the scanner into recording
50
+ * source offsets; leaving it out is the fast path.
51
+ */
52
+ cursor?(cursor: XmlCursor): void;
18
53
  /**
19
54
  * @param name qualified name, e.g. "bpmn:task"
20
55
  * @param local name without its prefix, e.g. "task" (same string as `name` when unprefixed)
@@ -42,4 +77,8 @@ export declare function parseXml(xml: string): XmlElement;
42
77
  * Produces a well-formed XML document with declaration.
43
78
  */
44
79
  export declare function serializeXml(element: XmlElement): string;
80
+ /** Escapes a value for use between attribute quotes. */
81
+ export declare function escapeAttr(value: string): string;
82
+ /** Escapes a value for use as character data. */
83
+ export declare function escapeText(value: string): string;
45
84
  //# sourceMappingURL=xml-parser.d.ts.map
@@ -79,11 +79,26 @@ class XmlScanner {
79
79
  colon = -1;
80
80
  /** Position of the next "&" at or after the last place we looked, or -1 for none. */
81
81
  nextAmp = 0;
82
+ // ── Source positions, recorded only for a sink that asked (XmlCursor) ────
83
+ wantSpans = false;
84
+ tagStart = 0;
85
+ tagEnd = 0;
86
+ endTagStart = 0;
87
+ endTagEnd = 0;
88
+ /** Attribute name → value span, rebuilt for each start tag. */
89
+ attrSpans = new Map();
90
+ attributeSpan(name) {
91
+ return this.attrSpans.get(name);
92
+ }
82
93
  constructor(source) {
83
94
  this.s = source;
84
95
  this.n = source.length;
85
96
  }
86
97
  scan(sink) {
98
+ if (sink.cursor !== undefined) {
99
+ this.wantSpans = true;
100
+ sink.cursor(this);
101
+ }
87
102
  while (this.i < this.n) {
88
103
  this.skipWhitespace();
89
104
  if (this.i >= this.n)
@@ -131,6 +146,7 @@ class XmlScanner {
131
146
  }
132
147
  const next = s.charCodeAt(this.i + 1);
133
148
  if (next === SLASH) {
149
+ const endTagStart = this.i;
134
150
  this.i += 2;
135
151
  const closing = this.readName();
136
152
  const name = open[open.length - 1];
@@ -141,6 +157,10 @@ class XmlScanner {
141
157
  this.expectChar(GT, ">");
142
158
  open.pop();
143
159
  wantText.pop();
160
+ if (this.wantSpans) {
161
+ this.endTagStart = endTagStart;
162
+ this.endTagEnd = this.i;
163
+ }
144
164
  sink.end(name);
145
165
  }
146
166
  else if (next === BANG) {
@@ -173,19 +193,34 @@ class XmlScanner {
173
193
  */
174
194
  openTag(sink, open, wantText) {
175
195
  const s = this.s;
196
+ const tagStart = this.i;
176
197
  this.i++; // <
177
198
  const name = this.readName();
178
199
  const local = this.colon >= 0 ? s.substring(this.colon + 1, this.i) : name;
179
200
  const attributes = {};
201
+ if (this.wantSpans)
202
+ this.attrSpans.clear();
180
203
  this.readAttributes(attributes);
181
204
  this.skipWhitespace();
182
205
  if (s.charCodeAt(this.i) === SLASH && s.charCodeAt(this.i + 1) === GT) {
183
206
  this.i += 2;
207
+ if (this.wantSpans) {
208
+ this.tagStart = tagStart;
209
+ // A self-closing tag is its own end tag; both spans name the same text
210
+ // so a sink does not have to special-case it.
211
+ this.tagEnd = this.i;
212
+ this.endTagStart = this.i;
213
+ this.endTagEnd = this.i;
214
+ }
184
215
  if (sink.start(name, local, attributes, true) !== Visit.Skip)
185
216
  sink.end(name);
186
217
  return open.length;
187
218
  }
188
219
  this.expectChar(GT, ">");
220
+ if (this.wantSpans) {
221
+ this.tagStart = tagStart;
222
+ this.tagEnd = this.i;
223
+ }
189
224
  const visit = sink.start(name, local, attributes, false);
190
225
  if (visit === Visit.Skip) {
191
226
  this.skipContent(name);
@@ -281,7 +316,11 @@ class XmlScanner {
281
316
  this.skipWhitespace();
282
317
  this.expectChar(EQ, "=");
283
318
  this.skipWhitespace();
319
+ const valueStart = this.i + 1;
284
320
  attrs[key] = this.readAttrValue();
321
+ // `readAttrValue` leaves `i` just past the closing quote.
322
+ if (this.wantSpans)
323
+ this.attrSpans.set(key, { start: valueStart, end: this.i - 1 });
285
324
  }
286
325
  }
287
326
  /** Like readAttributes, but validates only; nothing is built. */
@@ -514,12 +553,14 @@ const ESCAPES = {
514
553
  function escapeChar(ch) {
515
554
  return ESCAPES[ch] ?? ch;
516
555
  }
517
- function escapeAttr(value) {
556
+ /** Escapes a value for use between attribute quotes. */
557
+ export function escapeAttr(value) {
518
558
  if (!ATTR_ESCAPE_RE.test(value))
519
559
  return value;
520
560
  return value.replace(ATTR_ESCAPE_ALL_RE, escapeChar);
521
561
  }
522
- function escapeText(value) {
562
+ /** Escapes a value for use as character data. */
563
+ export function escapeText(value) {
523
564
  if (!TEXT_ESCAPE_RE.test(value))
524
565
  return value;
525
566
  return value.replace(TEXT_ESCAPE_ALL_RE, escapeChar);
@@ -0,0 +1,109 @@
1
+ /**
2
+ * Rewriting a document in place, so an edit reads as an edit.
3
+ *
4
+ * A serializer given a model produces its own formatting: its indentation, its
5
+ * attribute order, its choice of `&#10;` over `&#xA;`. That is correct output
6
+ * and a terrible diff. Move one element in a visual editor and every line of
7
+ * the file changes, so the commit says "the whole diagram" when it means "a box
8
+ * moved forty pixels" — and a reviewer has no way to tell those apart.
9
+ *
10
+ * {@link preserveFormatting} closes that gap without either side having to know
11
+ * about the other. It takes the document as it was and the document as the
12
+ * serializer would write it, and returns a third: the *content* of the second
13
+ * carried by the *bytes* of the first, everywhere the two agree. No model is
14
+ * involved, which is why it serves BPMN, DMN, forms and anything else this
15
+ * toolkit learns to write.
16
+ *
17
+ * @packageDocumentation
18
+ */
19
+ /** How to treat children that appear in both documents in a different order. */
20
+ export type SiblingOrder =
21
+ /**
22
+ * Reorder to match `updated`. Correct for any document, and the default:
23
+ * sibling order carries meaning in plenty of XML, and nothing here can tell
24
+ * which document that is.
25
+ */
26
+ "follow"
27
+ /**
28
+ * Leave matched children where the original had them, patching each in
29
+ * place. Only correct where sibling order says nothing — which is a fact
30
+ * about a *schema*, so a caller choosing this should check the result rather
31
+ * than assume it. `exportPreserving` in the BPMN module is the worked
32
+ * example: it tries this, verifies the parsed model is unchanged, and falls
33
+ * back when it is not.
34
+ */
35
+ | "keep";
36
+ export interface PreserveOptions {
37
+ /** Default `"follow"`. */
38
+ readonly siblingOrder?: SiblingOrder;
39
+ /**
40
+ * What to do about an attribute the original has and the update does not.
41
+ *
42
+ * - `"remove"` (default) — take it out, because the update says so.
43
+ * - `"keep"` — leave it. A serializer omits an attribute set to its schema
44
+ * default, so `isExecutable="false"` disappears from a file that said it
45
+ * out loud. Keeping it is only safe when re-reading the result gives the
46
+ * same model, which is a check the caller has to make; see
47
+ * `exportPreserving` in the BPMN module.
48
+ */
49
+ readonly droppedAttributes?: "remove" | "keep";
50
+ }
51
+ /**
52
+ * Rewrites `original` to say what `updated` says, changing as little as it can.
53
+ *
54
+ * The result is `updated`'s document — the same elements, attributes and text —
55
+ * written with `original`'s formatting wherever the two agree. An element
56
+ * nobody touched comes back byte for byte, comments and all; a moved shape
57
+ * comes back as two changed numbers.
58
+ *
59
+ * Falls back to returning `updated` unchanged whenever it cannot do better:
60
+ * either document failing to parse, a different root element, or an alignment
61
+ * that would produce overlapping edits. The result is then exactly what the
62
+ * caller would have written anyway, so calling this is never worse than not.
63
+ *
64
+ * @param original - The document as it stands.
65
+ * @param updated - The same document as the serializer would write it now.
66
+ * @param options - `siblingOrder` decides what happens to children that appear
67
+ * in both documents in a different order. See {@link SiblingOrder}.
68
+ *
69
+ * @example
70
+ * ```typescript
71
+ * const onDisk = await readFile("order.bpmn", "utf8");
72
+ * const next = preserveFormatting(onDisk, Bpmn.export(edited));
73
+ * // `next` differs from `onDisk` only where `edited` differs from what it held.
74
+ * ```
75
+ */
76
+ export declare function preserveFormatting(original: string, updated: string, options?: PreserveOptions): string;
77
+ /** How a verified preserve turned out, for a caller that wants to know. */
78
+ export interface VerifiedPreserve {
79
+ /** The document to write. */
80
+ readonly xml: string;
81
+ /**
82
+ * Which rung produced it.
83
+ *
84
+ * - `preserved` — the file's own order and formatting were kept.
85
+ * - `reordered` — formatting kept, children reordered as the update wants.
86
+ * Reached when the document really does depend on sibling order.
87
+ * - `rewritten` — the update itself, because neither of the above survived
88
+ * the check. Nothing is lost; the file is simply reformatted.
89
+ */
90
+ readonly outcome: "preserved" | "reordered" | "rewritten";
91
+ }
92
+ /**
93
+ * Preserves as much of `original` as a reader of the document will allow.
94
+ *
95
+ * The choices {@link preserveFormatting} cannot make safely on its own —
96
+ * whether sibling order carries meaning, whether an attribute the update
97
+ * dropped was a schema default — are made here by *trying and checking*. Each
98
+ * candidate is parsed with the caller's own reader and compared against the
99
+ * update; the first that reads the same is used, and the update itself is the
100
+ * floor. So the aggressive strategies are never assumed to be safe for a
101
+ * particular schema, only observed to be safe for a particular document.
102
+ *
103
+ * @param original - The document as it stands.
104
+ * @param updated - The same document as the serializer would write it now.
105
+ * @param read - Parses a document into something comparable with
106
+ * `JSON.stringify`. Anything it cannot parse counts as a failed check.
107
+ */
108
+ export declare function preserveFormattingVerified(original: string, updated: string, read: (xml: string) => unknown): VerifiedPreserve;
109
+ //# sourceMappingURL=xml-patch.d.ts.map