@formicoidea/labre-framework-bpmn 0.32.0 → 0.34.1

package/dist/export.d.ts

@@ -0,0 +1,277 @@
+import type { BpmnNodeElementModel, BpmnNodeKind, BpmnPoolElementModel, ConnectorElementModel } from '@formicoidea/labre-core/model';
+/**
+ * The board, as a BPMN 2.0 interchange document (clause 15) — semantic model
+ * plus BPMN DI, in one `definitions` element.
+ *
+ * ## Pure by construction
+ *
+ * Element models in, string out. No `BlockStdScope`, no surface, no DOM, no
+ * clock and no randomness — the same discipline `facts.ts` holds itself to, and
+ * for the same three reasons: a host can call it, a test can call it with plain
+ * stubs, and the same board always serializes to the same bytes. The command
+ * that downloads the file is the only thing that knows what a canvas is.
+ *
+ * ## What it says, and what it refuses to say
+ *
+ * The export speaks the author's STATEMENTS and nothing else. A connector
+ * carrying no BPMN role relates nothing — `docs/adr/0010` is explicit that the
+ * role is the statement — so it is not a sequence flow that happens to be
+ * untyped, it is not a flow at all, and it is absent. A plain rectangle drawn
+ * beside a pool is likewise not an unnamed task. The alternative — guessing —
+ * would put words in an architect's mouth in a file they are about to hand to
+ * an execution engine.
+ *
+ * ## Conformance target
+ *
+ * The **Descriptive** sub-class of BPMN 2.0 (spec Table 2.1), which is exactly
+ * the vocabulary the pack draws: the seventeen artefacts map onto the
+ * seventeen-odd element names that table lists, and nothing here needs the
+ * executable half of the metamodel. Clause 15.1 explicitly licenses a partial
+ * model — implementers "disregard missing attributes marked required" — which
+ * is what lets a picture drawn for humans round-trip through bpmn.io without
+ * inventing an `ioSpecification` nobody asked for.
+ */
+/**
+ * The four namespaces an interchange file is written in, with the prefixes the
+ * spec's own schema uses (`bpmndi`, `di`, `dc`; §12.2.4 and Annex B).
+ *
+ * Prefixes are arbitrary and URIs are not — bpmn.io writes the same two DD
+ * namespaces as `omgdi` / `omgdc` — so the URIs are what is pinned by the tests
+ * and the prefixes merely have to be consistent with themselves. The MODEL
+ * namespace is given the explicit `bpmn` prefix rather than made the default,
+ * because a reader of the file should never have to work out which of two
+ * unprefixed vocabularies an element belongs to.
+ *
+ * The stale `.../BPMNDI/1.0.0` that appears in the spec's own clause 15.3.1
+ * example is a documented erratum and is NOT what the normative schema says.
+ */
+export declare const BPMN_NS: {
+    readonly model: "http://www.omg.org/spec/BPMN/20100524/MODEL";
+    readonly bpmndi: "http://www.omg.org/spec/BPMN/20100524/DI";
+    readonly di: "http://www.omg.org/spec/DD/20100524/DI";
+    readonly dc: "http://www.omg.org/spec/DD/20100524/DC";
+};
+/**
+ * The four declarations this library writes, as they appear on `definitions` —
+ * the PAIR, prefix and URI together, and the pair is the point.
+ *
+ * A reader carries a file's namespace declarations because a carried fragment
+ * is stored with the prefixes the file spelled it in, and a `camunda:property`
+ * or a `bpmn2:boundaryEvent` means nothing under a declaration nobody wrote.
+ * What it must NOT carry is a declaration this writer is going to make anyway,
+ * or the payload gains four permanent entries, every Labre file reports four
+ * things carried, and the "a file we wrote comes back with an empty middle
+ * column" property — the no-slow-leak property — stops being true.
+ *
+ * Keyed by the attribute NAME rather than by the URI, because the prefix is
+ * exactly what differs: bpmn.io writes the model namespace as `bpmn2:` and this
+ * library writes it as `bpmn:`, and a fragment carrying `bpmn2:` is unreadable
+ * unless `xmlns:bpmn2` comes back with it. Same URI, different prefix,
+ * different fate — which a set of URIs cannot express.
+ */
+export declare const BPMN_OWN_DECLARATIONS: Readonly<Record<string, string>>;
+/**
+ * The interchange format's id — the key under which foreign matter from a
+ * `.bpmn` rides on an element (`interchange.bpmn`, ADR 0012 D2), and the middle
+ * term of both capability ids.
+ *
+ * Declared here, in the module both directions already depend on, so that the
+ * writer, the reader and the registry entry cannot disagree about which key
+ * they are talking about.
+ */
+export declare const BPMN_FORMAT_ID = "bpmn";
+/**
+ * Which slot of `process` an artefact serializes into.
+ *
+ * Not decoration: the spec's `tProcess` sequence is `laneSet* → flowElement* →
+ * artifact*` in that order, and a `textAnnotation` written before a `task` is a
+ * document a validating parser rejects. It also decides what a LANE may point
+ * at — `flowNodeRef` is an IDREF to a flow NODE, and a data reference is a flow
+ * element that is not one, so a data object sitting in a lane is simply not
+ * referenced by it.
+ */
+type BpmnXmlSlot = 'flowNode' | 'data' | 'artifact';
+export interface BpmnXmlMapping {
+    /** The semantic element name, in the MODEL namespace. */
+    element: string;
+    slot: BpmnXmlSlot;
+    /** The child that says what TRIGGERS the event, for the four variants. */
+    eventDefinition?: 'messageEventDefinition' | 'timerEventDefinition' | 'terminateEventDefinition';
+}
+/**
+ * The whole notation, kind by kind — the table this module is really about.
+ *
+ * `Record<BpmnNodeKind, …>` and therefore COMPILE-TOTAL: a kind added to the
+ * pack without a BPMN element name to serialize it as fails the build here,
+ * which is the only place that failure is cheap. A kind that reached a
+ * document and had no mapping would be an artefact the author drew, saved, and
+ * then silently lost on export.
+ *
+ * Three of the seventeen do not map one-for-one and the reasons are the spec's:
+ *
+ * - the four TRIGGERED events are `startEvent` / `endEvent` carrying an event
+ *   definition child, never elements of their own — "message start event" is a
+ *   start event with a `messageEventDefinition` in it (§10.4.2);
+ * - a data object serializes as `dataObjectReference`, because DI attaches to
+ *   the REFERENCE and not to the `dataObject` it points at (§10.4.1, and the
+ *   spec's own rule that "Data Object Reference cannot specify item
+ *   definitions, and Data Objects cannot specify states"). The `dataObject`
+ *   itself is emitted alongside it;
+ * - a `group` carries no `name` at all. Its visible label is the `value` of the
+ *   `categoryValue` it points at, which is a ROOT element of the document — the
+ *   one place in this file where drawing a box round three tasks costs two
+ *   extra elements somewhere else entirely (§10.4, Table 8.30).
+ */
+export declare const BPMN_XML_OF_KIND: Record<BpmnNodeKind, BpmnXmlMapping>;
+/**
+ * Character DATA — the three characters that would otherwise start markup.
+ *
+ * A newline, a tab and a carriage return are left exactly as they are, which is
+ * what makes `<bpmn:text>` carry a multi-line annotation faithfully: inside an
+ * element, whitespace is content.
+ */
+export declare function escapeText(value: string): string;
+/**
+ * An attribute VALUE, which needs strictly more than character data does.
+ *
+ * The quotes are the obvious half. The other half is the one that loses data
+ * silently: XML 1.0 §3.3.3 makes every conformant parser replace a literal
+ * `#xA`, `#xD` or `#x9` in an attribute value with a SPACE before anyone sees
+ * it — attribute-value normalization, and it is not optional. Only a character
+ * reference survives it.
+ *
+ * That matters here because a multi-line label is ordinary on this canvas (it
+ * is how a task fits in its box) and `name` is where nearly all of them go:
+ * every flow node, the participant, the lane, the flows, and
+ * `categoryValue/@value`. Written raw, a two-line task name comes back as one
+ * line, with no warning and no way for the author to tell. Written as `&#10;`
+ * it comes back as it went in.
+ */
+export declare function escapeAttr(value: string): string;
+/**
+ * A surface id, as an XML NCName.
+ *
+ * `id` is `xsd:ID` throughout BPMN, which means NCName and means
+ * DOCUMENT-unique — a `BPMNShape` may not carry the id of the `task` it
+ * describes. Surface ids are nanoid-shaped: they routinely open on a digit and
+ * may carry a `-`, both of which a validating parser refuses on an `xsd:ID`.
+ *
+ * So: every disallowed character becomes `_`, and an id that does not open on a
+ * letter or `_` is prefixed with one. The transformation is lossy on purpose —
+ * two distinct surface ids can collapse onto the same NCName — which is what
+ * {@link IdMinter} is for.
+ */
+export declare function toNcName(raw: string): string;
+/** Whether a string is already an NCName, and can therefore be given back. */
+export declare function isNcName(value: string): boolean;
+/**
+ * `.bpmn`'s scope vocabulary — where a carried fragment came off, and therefore
+ * where this writer has to put it back (ADR 0012, D2 as amended in #157).
+ *
+ * Declared HERE, in the module both directions already depend on, for the same
+ * reason {@link BPMN_FORMAT_ID} is: the reader files a fragment under a scope
+ * and the writer looks it up under one, and a table written twice is a table
+ * that drifts. `import.ts` re-exports it.
+ *
+ * One Labre element stands for several source elements: a pool is a
+ * `participant` AND its `process`, plus a `laneSet`, every `lane`, the
+ * `BPMNShape` that draws it, and — on the first pool of a document — the
+ * `collaboration` and `definitions` themselves. Everything they carry lands in
+ * ONE payload, so what came off which is recorded, or two lanes with the same
+ * foreign attribute leave one value in a persisted field and a report that says
+ * two.
+ *
+ * A scope is either a source element's **id, verbatim** — every carried flow
+ * node, every lane, every carried root element — or one of the `@` keys below,
+ * for the parts of the document that have no id worth naming or whose identity
+ * is their relation to this element. `@` is not an XML NameStartChar, so no id
+ * in a conformant file can ever collide with one.
+ *
+ * The rule for a fragment is always the same: **the scope is the element it was
+ * a child of**. For an attribute it is the element that carried the attribute;
+ * for a `di` fragment, what that fragment draws.
+ */
+export declare const BPMN_SCOPE: {
+    /** The element this payload rides on: the participant, the flow node, the flow. */
+    readonly self: "@self";
+    /** Its `BPMNShape` or `BPMNEdge`. */
+    readonly shape: "@shape";
+    /** The `process` behind a participant — the pool's other half. */
+    readonly process: "@process";
+    /** The pool's `laneSet`. */
+    readonly laneSet: "@laneSet";
+    /** The `collaboration`, whose residue rides on the first pool (D6). */
+    readonly collaboration: "@collaboration";
+    /** `definitions` itself: its foreign attributes, its declarations, its roots. */
+    readonly definitions: "@definitions";
+};
+/**
+ * The board to serialize — everything on the surface, split by what it is.
+ *
+ * The whole board and not a selection: a BPMN document is a process, and half a
+ * process is not a smaller process. The pool whose toolbar launched the export
+ * decides the FILENAME and nothing else.
+ */
+export interface BpmnExportBoard {
+    /** In document order — which is the tie-break `bpmnPoolOf` breaks on. */
+    pools: readonly BpmnPoolElementModel[];
+    nodes: readonly BpmnNodeElementModel[];
+    connectors: readonly ConnectorElementModel[];
+}
+export interface BpmnExportOptions {
+    /** Names the `collaboration` / lone `process` and the `BPMNDiagram`. */
+    name?: string;
+}
+/**
+ * The document, plus what writing it could not say.
+ *
+ * Three things the board can hold have no honest place in a `.bpmn` file, and
+ * until now each of them was documented in a code comment and silent to the
+ * person who clicked Export. A warning is one line, in the user's words, and it
+ * names the fix rather than the mechanism. Nothing here is an error: the file
+ * is valid and the export succeeded — these are the sentences the format
+ * refused to carry.
+ */
+export interface BpmnExportOutcome {
+    text: string;
+    /** Empty when the board came out whole, which is the usual case. */
+    warnings: string[];
+}
+/**
+ * Serialize a board as a BPMN 2.0 XML interchange document.
+ *
+ * ## The shape of the document, and what decides it
+ *
+ * One `definitions`, always. Then:
+ *
+ * - **at least one pool** — a `collaboration` holding one `participant` per
+ *   pool, one `process` per pool, and the message flows (which are the
+ *   collaboration's, never a process's). Things drawn OUTSIDE every pool split
+ *   in two: ARTIFACTS (annotation, group, and the associations that tie them to
+ *   anything) become children of the collaboration itself, where
+ *   `tCollaboration` allows them and where bpmn-js draws them; FLOW OBJECTS get
+ *   ONE extra participant-less process, and only if there are any. See
+ *   {@link COLLABORATION} for what the live recette found out about the
+ *   difference, and the note on the orphan process for what it still cannot fix;
+ * - **no pool at all** — a single `process` and no collaboration, which is what
+ *   a process drawn without swimlanes IS. The `BPMNPlane` then points at that
+ *   process; with a collaboration it must point at the collaboration, or most
+ *   tools draw the flow and none of the pools (spec §12.3.2).
+ *
+ * Attribution is {@link bpmnPoolOf} and {@link bpmnLaneOf} — the CENTRE against
+ * the pool's PLOT, containment only, no nearest-pool fallback. Deliberately the
+ * same arithmetic the audit and the validation rules read, so a task the audit
+ * reports in "Back office" is in the `lane` named "Back office" here.
+ */
+export declare function exportBpmnXml(board: BpmnExportBoard, options?: BpmnExportOptions): string;
+/**
+ * The same serialization, with the loss channel attached — see
+ * {@link BpmnExportOutcome}.
+ *
+ * {@link exportBpmnXml} is the thin wrapper over it, kept because a caller that
+ * only wants the bytes should not have to reach past a report to get them, and
+ * because #149's forty-six tests and the live integration spec pin that
+ * signature. The interchange capability calls THIS one.
+ */
+export declare function exportBpmnXmlWithWarnings(board: BpmnExportBoard, options?: BpmnExportOptions): BpmnExportOutcome;
+export {};