@formicoidea/labre-framework-bpmn 0.32.0 → 0.34.1

package/dist/actions.d.ts

@@ -1,10 +1,7 @@
+import { type InterchangeReport, type SerializedElementProps } from '@formicoidea/labre-core/blocks/surface';
+import { type BpmnLane, type BpmnNodeKind, BpmnPoolElementModel } from '@formicoidea/labre-core/model';
 import type { BlockStdScope } from '@formicoidea/labre-core/std';
-/**
- * Standalone creation/activation actions for the BPMN toolbox — lifted out of
- * `toolbar/bpmn-menu.ts` by PF3 so the menu becomes a pure renderer over the
- * command registry. Telemetry is emitted once, by `runCommand`.
- */
-export type BpmnNodeKind = 'startEvent' | 'endEvent' | 'task' | 'gatewayExclusive';
+import { type BpmnExportBoard } from './export.js';
 /** Create a flow-object node (native shape) centred on the viewport. */
 export declare function createBpmnNode(std: BlockStdScope, kind: BpmnNodeKind): void;
 /** Create a pool (background container) centred on the viewport. */
@@ -15,3 +12,202 @@ export declare function createBpmnPool(std: BlockStdScope): void;
  * one node to another (endpoints attach to centers).
  */
 export declare function activateBpmnSequenceFlow(std: BlockStdScope): void;
+/**
+ * Arm the native connector tool, pre-styled for a BPMN message flow:
+ * orthogonal, DASHED, an open circle where the message leaves and an open
+ * arrowhead where it lands.
+ *
+ * ## The two endpoint styles, and why these two
+ *
+ * The spec's message flow starts on a small hollow circle and ends on a hollow
+ * (line-drawn) arrowhead — never the solid triangle the sequence flow uses,
+ * which is the whole visual difference between "then this happens" and "and
+ * this is what I told them". `PointStyle` offers `Circle` and `Arrow`, and they
+ * are exactly those two shapes: `Arrow` is drawn as an unfilled V
+ * (`renderRoundedPolygon(…, false)`), against `Triangle`'s filled one. The only
+ * deviation is that `Circle` is painted with the connector's `fillColor` rather
+ * than left transparent — the shape, the size and the position are the spec's.
+ */
+export declare function activateBpmnMessageFlow(std: BlockStdScope): void;
+/**
+ * Arm the native connector tool, pre-styled for a BPMN association: dashed, and
+ * with NO endpoint marker at either end.
+ *
+ * The missing arrowheads are the point, not an omission. An association names
+ * no relation — `bpmn:association` is the one edge role in this vocabulary
+ * declared without a `direction` block — so "this note is about that task"
+ * reads identically from either end, and an arrowhead would be the picture
+ * claiming a direction the role explicitly refuses to have. See the role's own
+ * doc comment in `./roles.ts`.
+ *
+ * On the dash (there is no dotted stroke to ask for) see
+ * {@link ASSOCIATION_STROKE}'s neighbours in `./consts.ts`.
+ */
+export declare function activateBpmnAssociation(std: BlockStdScope): void;
+/**
+ * The lanes a pool carries, as an array that is safe to read.
+ *
+ * The value comes out of a Y.Map, so it is whatever a peer wrote: a client that
+ * got it wrong must not break the gesture on this one. Same defensive read the
+ * validation engine does on `validationExceptions`, for the same reason.
+ */
+export declare function bpmnLanesOf(model: BpmnPoolElementModel): readonly BpmnLane[];
+/**
+ * The pools a lane gesture acts on: every pool of the current selection that is
+ * not locked.
+ *
+ * EVERY one, not the single one — `some`, not `every`, in the same spirit as
+ * the typed-edge inversion (`docs/adr/0010` M3): lassoing two pools used to be
+ * a way to lose an affordance, and a gesture that says what it did on each of
+ * them beats an entry that vanishes. With one pool selected — the ordinary
+ * case, and the only one the toolbar offers — it is exactly "the selected pool".
+ */
+export declare function bpmnPoolsForLaneEdit(std: BlockStdScope): BpmnPoolElementModel[];
+/**
+ * Append a lane to every selected pool.
+ *
+ * ## One lane, not two
+ *
+ * Adding the FIRST lane creates ONE lane, covering the whole pool. Seeding two
+ * would invent a subdivision the user did not ask for and then make them delete
+ * half of it. One lane is the honest reading of "add a lane": the pool now has
+ * a lane, it happens to be all of it, and the second click gives them the
+ * second one.
+ *
+ * Since the lane title band (PO recette, 2026-08-26) that first click is also
+ * VISIBLE: a named strip appears down the leading edge of a pool that had none.
+ * Before it, a single lane was indistinguishable from no lane at all, and the
+ * gesture looked broken until the second click.
+ *
+ * ## `Lane N` is DOCUMENT DATA, not vocabulary
+ *
+ * The default name is a plain persisted string, exactly like the pool's own
+ * `'Pool'` default: it is written into the document by this action and is the
+ * user's to rewrite from that moment on. It is deliberately NOT a `labelKey`
+ * through the translation seam — a host that ships a French catalogue must not
+ * silently retitle a lane an author named, and a name that changed language
+ * when the reader's locale did would be a document that says different things
+ * to different people. `N` is the count AFTER this lane, so the first is
+ * `Lane 1`.
+ */
+export declare function addBpmnLane(std: BlockStdScope): void;
+/**
+ * Remove the LAST lane of every selected pool.
+ *
+ * The last one and not the selected one, because a lane is not selectable: it
+ * is a slice of the pool's plot, painted by the background primitive, with no
+ * element of its own. Removing from the end is the gesture that undoes the one
+ * that added it.
+ *
+ * ## Nothing moves
+ *
+ * Elements sitting in the removed lane do NOT move. Containment here is
+ * geometric — a task is "in" a lane because its centre falls in that rectangle,
+ * which is how the audit reports it — so the lane below simply grows over them
+ * and they are in that one now. Nothing on the canvas jumps under the user's
+ * hand, and the sequence flow they drew still lands where they drew it.
+ */
+export declare function removeBpmnLane(std: BlockStdScope): void;
+/**
+ * The pools of the current selection, WITHOUT the two filters a lane gesture
+ * applies.
+ *
+ * `bpmnPoolsForLaneEdit` refuses a read-only document and a locked pool because
+ * it is about to write to them. An export writes nothing: it reads the board
+ * and hands the reader a file. A process published read-only, or a pool an
+ * author locked precisely because it is finished, is exactly the board somebody
+ * wants to take to bpmn.io — refusing it there would be a filter copied for the
+ * shape of it rather than for the reason.
+ */
+export declare function bpmnPoolsSelected(std: BlockStdScope): BpmnPoolElementModel[];
+/**
+ * Everything on the surface the exporter speaks about, in document order.
+ *
+ * The half that needs an editor, and only that half: reading the surface. The
+ * picking is {@link bpmnBoardFrom}, which the interchange capability calls with
+ * the same elements and no `std` at all (`docs/adr/0012`, P3).
+ */
+export declare function bpmnBoardOf(std: BlockStdScope): BpmnExportBoard;
+/**
+ * What the downloaded file is called, minus the extension.
+ *
+ * The document's own title first — a board is what the file is OF — then the
+ * name of the pool whose toolbar launched the export, then a last resort. Which
+ * of the three it is, is the only thing this function decides; making the
+ * answer safe to write to disk is {@link bpmnSafeFilename}, so the command and
+ * the interchange capability cannot name the same board differently.
+ */
+export declare function bpmnExportFilename(std: BlockStdScope): string;
+/**
+ * Serialize the whole board as BPMN 2.0 XML and hand it to the browser.
+ *
+ * Three steps, and only the first and the last know what an editor is: read the
+ * surface, run the DECLARED capability (`docs/adr/0012`), download what it
+ * produced. The middle step is not re-implemented here — the document, the
+ * filename and the content type all come out of `BPMN_XML_EXPORT.run`, so the
+ * command and the registry cannot describe the same board differently. There is
+ * one door; the registry is the label on it.
+ *
+ * A plain import rather than a DI lookup: the capability is a pure function and
+ * a value, resolving it through the container would buy nothing here, and P3 is
+ * explicit that the registry is the editor's view of these functions, not a
+ * gate in front of them.
+ */
+export declare function exportBpmnXmlFile(std: BlockStdScope): void;
+/**
+ * Write an imported board onto the surface, and give back the ids it minted.
+ *
+ * BPMN's name for {@link materializeInterchangeImport}, which is where the two
+ * passes live and are documented (`docs/adr/0012`, D3). Nothing in them was
+ * ever about BPMN except the payload key the source ids ride under, so the
+ * function moved to the surface package when the second format asked for it and
+ * this name stayed: it is what the chromium round trip calls, and a test that
+ * proves the shipped command has to keep calling the shipped function.
+ */
+export declare function materializeBpmnImport(std: BlockStdScope, elements: readonly SerializedElementProps[]): string[];
+/**
+ * Say what the import did — the summary, and the remarks.
+ *
+ * BPMN's name for {@link reportInterchangeImport}, which is where the argument
+ * for a toast plus a console table lives (ADR 0012's open question 4, v1). The
+ * format is a word in the sentence now rather than a wording per format, so
+ * what a user reads is unchanged: the counts, and `BPMN` before the version the
+ * reader actually read.
+ */
+export declare function reportBpmnImport(std: BlockStdScope, report: InterchangeReport): void;
+/**
+ * Read a `.bpmn` file the user picks, draw it, and say what it cost.
+ *
+ * The whole gesture is {@link runInterchangeImportFile}, over the capability
+ * BPMN declares: pick the file, run the DECLARED reader, write what it
+ * returned, fit the drawing, report. `BPMN_XML_IMPORT.run` is the same function
+ * labre-mcp calls, so the command and the registry cannot read the same file
+ * differently — one door, and the registry is the label on it. The picker's
+ * filter comes off `BPMN_XML_FORMAT` rather than off the shared `FileTypes`
+ * table, which is why `.xml` is declared there: half the tools in the wild
+ * write a process under the generic extension, and what the file actually IS is
+ * decided by the reader, which throws on anything that is not a BPMN
+ * `<definitions>`.
+ */
+export declare function importBpmnXmlFile(std: BlockStdScope): Promise<void>;
+/**
+ * Read an SVG the user picks as a SKETCH, and say what it cost.
+ *
+ * The same four steps as the `.bpmn` import, over a different declared
+ * capability — which is the whole point of the seam: a second format costs a
+ * declaration and a command, not a pipeline. What differs is the PROMISE, and
+ * the promise is made by the command's own label and description before the
+ * picker ever opens (`docs/adr/0012`, P2): recognition, best effort, no
+ * round-trip, and a level-1 sketch the author then promotes.
+ */
+export declare function importBpmnSvgFile(std: BlockStdScope): Promise<void>;
+/**
+ * Rename one lane of one pool. Called by the in-place editor
+ * (`element-view.ts`); exported so a unit test can assert the write without an
+ * editor around it.
+ *
+ * An empty name REMOVES the key rather than storing `''`: the renderer already
+ * treats both as "no name", and one of the two would be a second way to say the
+ * same thing that only the bytes can tell apart.
+ */
+export declare function renameBpmnLane(std: BlockStdScope, model: BpmnPoolElementModel, index: number, name: string): void;