@bpmnkit/core 1.14.0 → 1.16.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 (44) hide show
  1. package/AGENTS.md +5 -4
  2. package/agent-cards/bpmn.md +86 -80
  3. package/builder-reference.md +27 -8
  4. package/dist/bpmn/auto-layout.js +235 -42
  5. package/dist/bpmn/bpmn-builder.d.ts +171 -17
  6. package/dist/bpmn/bpmn-builder.js +792 -135
  7. package/dist/bpmn/bpmn-model.d.ts +15 -0
  8. package/dist/bpmn/bpmn-parser.js +32 -6
  9. package/dist/bpmn/bpmn-serializer.js +9 -2
  10. package/dist/bpmn/compact-stream.d.ts +7 -0
  11. package/dist/bpmn/compact-stream.js +7 -0
  12. package/dist/bpmn/compact.d.ts +126 -9
  13. package/dist/bpmn/compact.js +305 -30
  14. package/dist/bpmn/full-operations.d.ts +19 -0
  15. package/dist/bpmn/full-operations.js +191 -7
  16. package/dist/bpmn/make-room.d.ts +26 -0
  17. package/dist/bpmn/make-room.js +151 -0
  18. package/dist/bpmn/optimize/flow.js +8 -0
  19. package/dist/bpmn/place-new-shapes.d.ts +6 -1
  20. package/dist/bpmn/place-new-shapes.js +53 -2
  21. package/dist/bpmn/preserving-writer.d.ts +1 -1
  22. package/dist/bpmn/preserving-writer.js +1 -1
  23. package/dist/bpmn/process-delta.d.ts +32 -1
  24. package/dist/bpmn/process-delta.js +62 -1
  25. package/dist/bpmn/process-text-writer.d.ts +18 -7
  26. package/dist/bpmn/process-text-writer.js +105 -22
  27. package/dist/bpmn/process-text.d.ts +34 -2
  28. package/dist/bpmn/process-text.js +410 -7
  29. package/dist/bpmn/swimlanes.d.ts +178 -0
  30. package/dist/bpmn/swimlanes.js +774 -0
  31. package/dist/form/user-task-forms.d.ts +45 -0
  32. package/dist/form/user-task-forms.js +129 -0
  33. package/dist/index.d.ts +9 -4
  34. package/dist/index.js +5 -2
  35. package/dist/layout/collaboration/message-labels.d.ts +25 -0
  36. package/dist/layout/collaboration/message-labels.js +108 -0
  37. package/dist/layout/collaboration/ordering.d.ts +5 -1
  38. package/dist/layout/collaboration/ordering.js +24 -9
  39. package/dist/layout/semantic/graph.js +3 -0
  40. package/dist/layout/semantic/place.d.ts +2 -0
  41. package/dist/layout/semantic/place.js +77 -9
  42. package/dist/xml/xml-patch.d.ts +1 -1
  43. package/llms.txt +1 -1
  44. package/package.json +2 -2
@@ -0,0 +1,178 @@
1
+ /**
2
+ * Pure helpers for writing lanes and pools: every writer (builder, compact,
3
+ * process text, change scripts, editor) goes through these so they agree on
4
+ * one set of invariants. None of them mutates its input.
5
+ *
6
+ * Invariants a well-formed laned process meets (see {@link laneProblems}):
7
+ * every top-level flow node sits in exactly one leaf lane, a boundary event
8
+ * sits in its host's lane, sub-process children and data references sit in
9
+ * none. Ancestor lanes may or may not repeat their descendants' refs: Flowable
10
+ * and Camunda Modeler write the union, the editor writes leaves only, and both
11
+ * are accepted.
12
+ */
13
+ import type { BpmnDefinitions, BpmnLane, BpmnLaneSet, BpmnProcess } from "./bpmn-model.js";
14
+ /** A lane to build: a leaf when `lanes` is absent or empty. Same shape as compact's lane. */
15
+ export interface LaneSpec {
16
+ id: string;
17
+ name?: string;
18
+ lanes?: LaneSpec[];
19
+ }
20
+ /** The error a lane tree that loops back on itself is refused with. */
21
+ export declare function revisitMessage(laneId: string): string;
22
+ /**
23
+ * Every lane of `laneSet`, nested ones included, depth first (a parent before
24
+ * its children). Throws when the lane tree loops back on itself.
25
+ */
26
+ export declare function allLanes(laneSet?: BpmnLaneSet): BpmnLane[];
27
+ /**
28
+ * The lanes of `laneSet` that have no child lanes, depth first: the lanes a
29
+ * flow node is assigned to. Throws when the lane tree loops back on itself.
30
+ */
31
+ export declare function leafLanes(laneSet?: BpmnLaneSet): BpmnLane[];
32
+ /**
33
+ * The deepest lane of `process` whose refs list `nodeId`, so a union-convention
34
+ * ancestor never wins over the leaf. `undefined` when no lane lists it.
35
+ */
36
+ export declare function laneOf(process: BpmnProcess, nodeId: string): BpmnLane | undefined;
37
+ /**
38
+ * Returns a copy of `process` in which `nodeId` and the boundary events
39
+ * attached to it sit in leaf lane `laneId` and in no other lane.
40
+ *
41
+ * Ancestors of the target receive the node too only when the file already
42
+ * follows the union convention there; otherwise only the leaf is written.
43
+ * Whether `nodeId` exists is not checked ({@link laneProblems} reports it).
44
+ *
45
+ * @throws Error when `laneId` is not a lane of `process`, or has child lanes,
46
+ * or when `nodeId` is a boundary event whose host sits in another leaf lane:
47
+ * a boundary event goes where its host goes.
48
+ */
49
+ export declare function assignLane(process: BpmnProcess, nodeId: string, laneId: string): BpmnProcess;
50
+ /**
51
+ * Returns a copy of `process` whose lanes list only its top-level flow nodes:
52
+ * refs to missing ids, sub-process children and data references are dropped.
53
+ * A lane set without lanes is removed. A process without a lane set is
54
+ * returned as it is.
55
+ */
56
+ export declare function pruneLaneRefs(process: BpmnProcess): BpmnProcess;
57
+ /**
58
+ * Builds the lane set of `process` from `specs` and `leafOf` (flow node id to
59
+ * leaf lane id). Refs keep `leafOf`'s order and ids verbatim, so
60
+ * {@link laneProblems} can still report a ref to an unknown node. A boundary
61
+ * event always joins its host's lane when the host is mapped. Parent lanes list
62
+ * the union of their descendants' refs. Ids: `LaneSet_<processId>` for the set,
63
+ * `LaneSet_<laneId>` for a child set, with a numeric suffix when already in use.
64
+ *
65
+ * @throws Error listing every `leafOf` entry that names an undeclared lane or a
66
+ * lane with child lanes, or when `specs` loops back on itself or declares
67
+ * one id twice.
68
+ */
69
+ export declare function buildLaneSet(process: BpmnProcess, specs: readonly LaneSpec[], leafOf: ReadonlyMap<string, string>): BpmnLaneSet;
70
+ /**
71
+ * The leaf lane a node newly added to an already-laned `process` belongs in:
72
+ * its host's lane for a boundary event, else the lane of its first sequence-flow
73
+ * predecessor that has one, else of its first such successor, else the first
74
+ * leaf lane. `undefined` when the process has no lanes.
75
+ */
76
+ export declare function laneForNewNode(process: BpmnProcess, nodeId: string): BpmnLane | undefined;
77
+ /**
78
+ * The process a single-process writer edits: the first process, in the
79
+ * participant order of `collaborations[0]`, that is explicitly executable; else
80
+ * the first explicitly executable process; else the first process with flow
81
+ * elements or lanes. When every process is empty, the candidates are the ones
82
+ * not marked `isExecutable="false"` (Flowable reads an absent attribute as
83
+ * executable), or all of them when every one is; among them the one whose pool
84
+ * is drawn largest, else the first. Modeler files do not always put the
85
+ * executable pool first.
86
+ *
87
+ * {@link BpmnDefinitions.primaryProcessId}, while it names a process of
88
+ * `defs`, comes right after the explicitly executable process: it breaks the
89
+ * tie the semantics cannot, as an emptied own pool next to a partner's pool
90
+ * with content and `isExecutable="false"` reads exactly like a partner's empty
91
+ * pool next to a file's only process. An explicit `isExecutable="true"`, which
92
+ * another tool may have set since, is no tie and still wins.
93
+ */
94
+ export declare function primaryProcess(defs: Pick<BpmnDefinitions, "collaborations" | "processes"> & Partial<Pick<BpmnDefinitions, "diagrams" | "primaryProcessId">>): BpmnProcess | undefined;
95
+ /** The namespace of the `primaryProcess` attribute {@link pinnedPrimaryToWrite} puts on `<definitions>`. */
96
+ export declare const BPMNKIT_NAMESPACE = "https://bpmnkit.com/schema/bpmn";
97
+ /**
98
+ * `namespaces` with {@link BPMNKIT_NAMESPACE} declared, and its prefix: the one
99
+ * already declared, else `bpmnkit`, else the first free `bpmnkit<n>`.
100
+ */
101
+ export declare function withBpmnkitNamespace(namespaces: Record<string, string>): {
102
+ namespaces: Record<string, string>;
103
+ prefix: string;
104
+ };
105
+ /**
106
+ * `defs` with {@link BpmnDefinitions.primaryProcessId} set to `processId`, or
107
+ * cleared when it is `undefined`. Setting it also declares the bpmnkit
108
+ * namespace, and clearing it leaves the declaration: a document parsed from a
109
+ * pinned file keeps it too, so both write the same bytes whatever happens to
110
+ * the pin later.
111
+ */
112
+ export declare function pinPrimaryProcess(defs: BpmnDefinitions, processId: string | undefined): BpmnDefinitions;
113
+ /**
114
+ * The {@link BpmnDefinitions.primaryProcessId} a file must carry, or
115
+ * `undefined` when the file alone already leads {@link primaryProcess} there,
116
+ * so a document nobody emptied stays byte-identical.
117
+ */
118
+ export declare function pinnedPrimaryToWrite(defs: BpmnDefinitions): string | undefined;
119
+ /** What {@link documentIdList} reads; every part optional, so a builder can pass what it has. */
120
+ export type IdSource = Partial<Pick<BpmnDefinitions, "id" | "messages" | "errors" | "signals" | "escalations" | "processes" | "collaborations">>;
121
+ /**
122
+ * Every id the document uses, once per use, so an id listed twice is a clash:
123
+ * the definitions, root elements, processes with their flow elements, flows and
124
+ * artifacts at any depth, lane sets and lanes, and collaborations with what
125
+ * they hold. Duplicate checks and fresh ids both read this one list, so they
126
+ * cannot disagree about what is taken.
127
+ */
128
+ export declare function documentIdList(defs: IdSource): string[];
129
+ /** Every repeated use in {@link documentIdList}: an id used three times is listed twice. */
130
+ export declare function duplicateIds(defs: IdSource): string[];
131
+ /**
132
+ * `first` when free, else the first free `nth(2)`, `nth(3)`, …; claims it in `taken`.
133
+ * Bounded: at most `taken.size` candidates can be taken, so one of the first
134
+ * `taken.size + 1` distinct candidates is free.
135
+ */
136
+ export declare function freshId(first: string, nth: (n: number) => string, taken: Set<string>): string;
137
+ /**
138
+ * "Lanes imply a pool": auto-layout draws lanes only inside a participant, and
139
+ * once a collaboration exists a process without one is drawn pool-less.
140
+ *
141
+ * When any process has a lane set or any collaboration exists, returns a copy
142
+ * in which `collaborations[0]` exists (id `Collaboration_1` unless taken) and
143
+ * every process with flow elements or a lane set is referenced by a
144
+ * participant (`Participant_<processId>`, named after the process, else its
145
+ * id). A process pooled here that is not the {@link primaryProcess} and has no
146
+ * `isExecutable` gets `isExecutable: false`, because Flowable reads an absent
147
+ * attribute as executable. Otherwise returns `defs` itself.
148
+ */
149
+ export declare function poolLanedProcesses(defs: BpmnDefinitions): BpmnDefinitions;
150
+ /**
151
+ * Everything wrong with the lanes of `process`, one message per finding:
152
+ * duplicate lane ids, refs to missing ids, to sub-process children or to data
153
+ * references, a flow node in two leaf lanes, and — once lanes exist — a
154
+ * top-level flow node in no leaf lane (data references, and boundary events
155
+ * whose host is assigned, are exempt), and a boundary event in a leaf lane its
156
+ * host is not in. Whether parents repeat their children's refs is not checked.
157
+ * Empty for a process without lanes.
158
+ */
159
+ export declare function laneProblems(process: BpmnProcess): string[];
160
+ /**
161
+ * Why an element of `type` cannot be the `side` end of a message flow, or
162
+ * undefined when it can. `trigger` is an event's first event definition
163
+ * (`"message"`, `"timer"`, …), undefined for a plain event or anything else.
164
+ * A pool can be either end. One rule for every writer, so a change script, the
165
+ * process text reader and the editor refuse the same messages.
166
+ */
167
+ export declare function messageEndProblem(type: string, trigger: string | undefined, side: "source" | "target"): string | undefined;
168
+ /**
169
+ * Everything about the collaborations of `defs` that a modeler would refuse
170
+ * or open broken, one message per finding: duplicate participant or message
171
+ * flow ids, a participant naming a missing process, two participants claiming
172
+ * one process, a message-flow end that is neither a participant nor a flow node
173
+ * in one, a message flow that stays inside one pool, a message flow naming an
174
+ * undeclared message, and — once a collaboration exists — a process with
175
+ * content that no participant references. Empty without collaborations.
176
+ */
177
+ export declare function collaborationProblems(defs: Pick<BpmnDefinitions, "collaborations" | "processes" | "messages"> & IdSource): string[];
178
+ //# sourceMappingURL=swimlanes.d.ts.map