@formicoidea/labre-framework-uml 0.42.0

package/dist/actions.d.ts

@@ -0,0 +1,430 @@
+import { type UmlDiagramKind, UmlDiagramElementModel, type UmlFragmentOperator } from '@formicoidea/labre-core/model';
+import type { BlockStdScope } from '@formicoidea/labre-core/std';
+import { type GfxPrimitiveElementModel } from '@formicoidea/labre-core/std/gfx';
+import { type UmlEdgeRole } from './edge-styles.js';
+/**
+ * Create a UML diagram frame centred on the viewport — the sheet one diagram is
+ * drawn on (Annex A).
+ *
+ * The KIND is written here and it is not optional: Annex A's heading is
+ * `<kind> <name>`, so a frame with no kind has nothing to write in its tag. It
+ * defaults to `class`, which is the diagram an architect reaches for first and
+ * the only one Annex A gives no abbreviation for — and the kind picker on the
+ * frame's own toolbar changes it afterwards.
+ *
+ * The NAME is seeded through the translation seam rather than left to the
+ * model's default, so a diagram drawn in a French host does not start out called
+ * "Diagram" (#183). The key is the diagram ROLE's: the two are the same noun,
+ * and a second key would ask a host to word it twice. It is content from that
+ * moment on — the heading is editable on a double-click — so it is asked for
+ * once and never re-resolved.
+ */
+export declare function createUmlDiagram(std: BlockStdScope, kind?: UmlDiagramKind): void;
+/**
+ * Create a use case SUBJECT centred on the viewport (§18.1.4) — the rectangle
+ * drawn around the use cases a system offers, with the actors left outside it.
+ *
+ * No variant and no kind, unlike a C4 boundary: §18.1.4 draws ONE rectangle with
+ * ONE name, so there is nothing for a discriminant to discriminate.
+ */
+export declare function createUmlSubject(std: BlockStdScope): void;
+/**
+ * Create an activity PARTITION — a swimlane (§15.6.4), the band an activity
+ * diagram draws round the steps one participant is responsible for.
+ *
+ * ## Why a background and not a field on the frame
+ *
+ * Because membership is GEOMETRIC and partitions nest and overlap: §15.6.4 lets
+ * a diagram be cut vertically by role and horizontally by phase at the same
+ * time, and an action belongs to whichever bands its centre falls in. A list of
+ * lane names on `umlDiagram` could express neither, and adding a field to a
+ * shipped model is the red zone `docs/adr/0009` guards. So a partition is an
+ * element like the subject beside it, read at audit and export time by centre
+ * containment (R11).
+ *
+ * ## VERTICAL, and it is a default rather than a preference
+ *
+ * §15.6.4's own figures are drawn as vertical columns, which is also the way a
+ * left-to-right flow reads: the steps travel across the lanes rather than down
+ * them. The model's own default says so, and this site deliberately writes no
+ * `orientation` at all — a creation that restated the default would be a second
+ * place for it to be changed, and the band's own toolbar is where an author
+ * turns a column into a row.
+ */
+export declare function createUmlPartition(std: BlockStdScope): void;
+/**
+ * Create a REGION — the rounded, named rectangle a composite state is drawn as
+ * (§14.2.4), and the container its sub-states sit inside.
+ *
+ * A composite state IS a region here rather than a `state` node holding
+ * regions, and the simplification is deliberate and has a ceiling worth
+ * stating: §14.2.4 draws a composite state as a rounded rectangle with its name
+ * in a band at the top and its sub-machine below, which is exactly this
+ * element. What it does NOT give is a state with two or more ORTHOGONAL regions
+ * separated by dashed lines — that is one state drawn as several boxes, and it
+ * is a phase-3 refinement rather than something this element can be stretched
+ * into.
+ */
+export declare function createUmlRegion(std: BlockStdScope): void;
+/**
+ * Create a COMBINED FRAGMENT — the box §17.6.4 draws round the part of an
+ * interaction that only happens sometimes, or happens repeatedly, or happens in
+ * parallel with something else.
+ *
+ * ## Why the operator is a parameter and the name is not a title
+ *
+ * §17.6.4 draws the fragment as a rectangle with a pentagon tag in its
+ * top-left corner holding the INTERACTION OPERATOR — `alt`, `opt`, `loop`,
+ * `par` — and that word is what the frame IS. It is written here rather than
+ * left to the model's default for the same reason `createUmlDiagram` writes a
+ * kind: the tag has to have something in it from the first frame the author
+ * draws, and the picker on the fragment's own row is what changes it
+ * afterwards.
+ *
+ * ## Nothing is NAMED, which is the one place this frame differs from the other
+ * three
+ *
+ * A diagram, a subject, a partition and a region are all seeded with a default
+ * name through the translation seam. This one is not, and the model says why in
+ * as many words: its `name` is the GUARD of the first operand — §17.6.4's
+ * `[condition]` — or, under `ref`, the name of the interaction being referred
+ * to (§17.7.4), and the notation draws a guard only where there is one. An
+ * `alt` born carrying `[condition]` would be a condition the author never
+ * wrote, sitting on the picture until somebody noticed and deleted it. So the
+ * field is left at the model's empty default and the author writes the guard
+ * into the band on a double-click, exactly as a state's behaviour compartment
+ * is seeded empty for the same reason (§14.2.4).
+ *
+ * ## One frame, no operands
+ *
+ * A fresh fragment has ONE zone and therefore no `operands` at all — the same
+ * promise a BPMN pool makes about its lanes, and the same bytes: nothing is
+ * written until the author asks for a second operand from the row, and the
+ * dashed separator §17.6.4 draws appears with it. An `alt` with one branch is
+ * the honest first draft of an `alt`, and a stencil that seeded two would be
+ * putting a branch on the sheet nobody asked for.
+ */
+export declare function createUmlFragment(std: BlockStdScope, operator?: UmlFragmentOperator): void;
+/**
+ * Create an INTERACTION USE — §17.7.4's `ref` frame, the box that says "and
+ * here the sequence described on another sheet happens".
+ *
+ * The same element as {@link createUmlFragment} with a different operator, and
+ * that is §17.7.4's own doing rather than an economy: an InteractionUse is
+ * drawn as the very rectangle a combined fragment is, with `ref` in the
+ * pentagon instead of `alt`, and the name of the referenced interaction in the
+ * fragment's own `name` — which this pack anchors where every other guard is
+ * written, at the top-left of the plot, rather than centred as §17.7.4's figure
+ * draws it. Giving it an element of its own would mean two things to
+ * select, two rows, two sets of rules and two exporters for one picture.
+ *
+ * It has a COMMAND of its own all the same, because it is a different modelling
+ * act: an author reaching for `ref` is pointing at another diagram, not
+ * branching this one, and making them draw an `alt` and then change the
+ * operator would be hiding a gesture behind a dropdown.
+ */
+export declare function createUmlInteractionUse(std: BlockStdScope): void;
+/**
+ * The kinds drawn as a divided rectangle (§9.2.4, §9.8.4, §11.6.4, §19.3.4).
+ *
+ * Phase 2 adds two, and both are boxes rather than pictures for the reason the
+ * first four are: a **component** is a Class (§11.6) drawn as a classifier
+ * rectangle with the two-tab mark in its corner, and an **artifact** is a
+ * classifier drawn as a rectangle with a document mark in the same corner and
+ * `«artifact»` over the name (§19.3.4). Neither mark replaces the box — they
+ * are stamped ON it — so both walk the compartment path and arrive with the
+ * tiers their kind is worth.
+ */
+export type UmlClassifierKind = 'class' | 'interface' | 'enumeration' | 'object' | 'component' | 'artifact' | 'state';
+/**
+ * The kinds the notation draws as a picture rather than as a box.
+ *
+ * Phase 2 adds six, and each earns its place here by having no compartment to
+ * divide: a **port** is a filled square on a border (§11.3.4), a **provided**
+ * and a **required interface** are the ball and the socket on a stub (§10.4.4),
+ * and a **node**, a **device** and an **execution environment** are the 3D box
+ * of §19.4.4 — a drawing with a front face, a top and a side, not a rectangle
+ * with lines across it.
+ */
+export type UmlGlyphKind = 'package' | 'note' | 'actor' | 'use-case' | 'port' | 'provided-interface' | 'required-interface' | 'node' | 'device' | 'execution-environment' | 'action' | 'initial' | 'activity-final' | 'flow-final' | 'decision' | 'fork' | 'object-node' | 'send-signal' | 'accept-event' | 'time-event' | 'final-state' | 'choice' | 'junction' | 'shallow-history' | 'deep-history' | 'entry-point' | 'exit-point' | 'terminate' | 'lifeline' | 'execution' | 'destruction';
+/**
+ * Create one of the SINGLE-LABEL artefacts — a package, a note, an actor, a use
+ * case, and since phase 2 a port, the two interface marks and the three
+ * deployment cubes — as the shape, its one word-bearing child, and the group
+ * that makes the two one thing.
+ *
+ * ## Why three elements and not one shape carrying text
+ *
+ * R16: a label is a free text element grouped with the shape, never text ON the
+ * shape. The pack has to obey it here even though these have only one tier,
+ * because a classifier next door has three — and two mechanisms for "the words
+ * on a UML artefact" would mean two editors, two toolbars and two sets of rules
+ * for the same gesture. One click selects the artefact, a second descends into
+ * its label.
+ *
+ * ## `uml:name` for five of them, `uml:label` for the rest
+ *
+ * See {@link NAMED_GLYPHS}: a package, a note and the three cubes carry a NAME
+ * the grammar parses a keyword off; a port, a ball and a socket carry a LABEL.
+ * Keeping them apart is what lets the exporter read a tier without first asking
+ * what shape it is under.
+ *
+ * ## The label is where the notation puts it, and that is not this file's call
+ *
+ * The box comes out of {@link umlCompartmentBoxes}, which is where every
+ * "beside the glyph" and "inside the front face" decision is written down: a
+ * port's label sits next to the square rather than on it (the square is 16
+ * units, and words do not fit in it), an interface mark's sits beside the ball
+ * or the socket, and a cube's sits in its FRONT FACE, which is the only part of
+ * a 3D box §19.4.4 writes in. Creation reads the answer; it does not have one.
+ *
+ * ## The alignments
+ *
+ * Centred, except the NOTE. A note holds a sentence rather than a title (Annex
+ * A), and a centred paragraph of three lines is the one thing on a UML diagram
+ * that reads as a poem.
+ *
+ * ## The kinds that get no words at all, and no group either
+ *
+ * Phase 2's behaviour vocabulary is the first in this pack with artefacts that
+ * carry NOTHING: a filled disc, a bullseye, a bar, a cross. §15.3.4 and §14.2.4
+ * name none of them — an initial node has no name, a fork has no name, a
+ * history mark is an `H` and a final state is a target — and a stencil that
+ * seeded one would be putting a word on the picture that the notation says is
+ * not there, which the `label-presence` audits would then be right to complain
+ * about forever.
+ *
+ * {@link UML_UNLABELLED_KINDS} is that list, and creation READS it rather than
+ * restating it: those kinds arrive as the shape and nothing else — no text, and
+ * therefore no group, because a group of one element is a wrapper round nothing
+ * that a user would have to descend through to reach the mark it holds. The
+ * SHAPE is what the gesture produced, so the shape is what is selected.
+ *
+ * Every kind that IS labelled here takes exactly one tier, and the one that
+ * would have been the exception does not travel this path at all: a **state**
+ * is a divided box (§14.2.4) and is built by {@link createUmlClassifier}, whose
+ * walk gives it the name compartment and the behaviour compartment the renderer
+ * rules off and the exporter reads.
+ */
+export declare function createUmlNode(std: BlockStdScope, kind: UmlGlyphKind): void;
+/**
+ * Create one of the COMPARTMENTED artefacts — a class, an interface, an
+ * enumeration, an object, and since phase 2 a component, an artifact or a
+ * state — as the shape, its compartments, and the group.
+ *
+ * ## How many tiers is the LAYOUT's answer, not this file's
+ *
+ * The walk below writes a tier for each box `umlCompartmentBoxes` returns and
+ * for no other, which is what lets two kinds be added to the notation without a
+ * line changing here: a component and an artifact arrive with the name tier and
+ * the one body tier §11.6.4 and §19.3.4 draw them with, because that is what the
+ * layout hands over. The alternative — a table of tier counts in this file —
+ * would be a second statement of the geometry, and the first one to drift.
+ *
+ * ## Four or five elements, and the object is the four
+ *
+ * A class, an interface and an enumeration arrive as shape + name + attributes +
+ * operations + group. An OBJECT arrives with no operations compartment at all,
+ * and that is §9.8.4 rather than an economy: an instance specification has
+ * SLOTS — values its attributes hold — and no behaviour of its own. Its second
+ * tier is stamped `uml:attributes` all the same, because a slot is what an
+ * attribute is worth on an instance, and giving it a fifth role would make every
+ * reader of the vocabulary handle two spellings of one idea.
+ *
+ * ## Seeded, not empty
+ *
+ * Every tier carries the stencil's own prompt from the moment the artefact is
+ * drawn: the kind's name line (`«interface»\nInterface` for an interface —
+ * §9.5.4's keyword, which is what tells the reader it is not a class),
+ * `+ attribute : Type`, `+ operation() : Type`. The author meets a worked
+ * example of the notation rather than an empty box, and the grammar can be read
+ * back off it immediately.
+ *
+ * ## The name is the one bold tier, and the features are read LEFT
+ *
+ * A compartment of attributes is a LIST of signatures, and a list is read down
+ * its left edge: centring `+ attribute : Type` over `+ operation() : Type` would
+ * put the `+` of every line in a different column and cost the reader the one
+ * visual cue UML gives for visibility (§9.5.4).
+ */
+export declare function createUmlClassifier(std: BlockStdScope, kind: UmlClassifierKind): void;
+/**
+ * The edges the toolbox arms, and the style each wears, are ONE table — and it
+ * lives in `./edge-styles.js` so the morph that retypes a connector somebody
+ * already drew reads the very rows this tool writes. Re-exported here because
+ * the union is what {@link activateUmlEdge} takes, and a caller holding this
+ * module should not have to know which file it was written in.
+ */
+export type { UmlEdgeRole };
+/**
+ * Arm the native connector tool, pre-styled for one UML relationship.
+ *
+ * ## One function for every edge, where C4 and BPMN wrote one each
+ *
+ * Because UML has twelve of them and they differ on three props out of a table
+ * that is otherwise identical — the same mode, the same ink, the same weight. A
+ * dozen near-identical functions would be a dozen places for a stroke width to
+ * drift, and {@link UML_EDGE_STYLE} is the notation itself, which is the thing
+ * worth reading. It is also what made phase 2 free: `deploy`, `manifest` and
+ * `communication-path` arm through this function without a line changing in it.
+ *
+ * ## STRAIGHT, always
+ *
+ * A class diagram is a graph, not a process laid out in lanes: the elbows an
+ * orthogonal router adds would read as a route through the diagram that nobody
+ * drew. BPMN routes orthogonally because a sequence flow really does travel
+ * through a layout; UML's lines state a relationship between two classifiers and
+ * the shortest one says it best.
+ *
+ * The role is carried by the TOOL, so the connector is born with it rather than
+ * acquiring one afterwards (`docs/adr/0010`) — and the look rides on the
+ * activation, never through the last-props store: the plain connector tool must
+ * keep the user's own style (#144 M1).
+ */
+export declare function activateUmlEdge(std: BlockStdScope, role: UmlEdgeRole): void;
+/**
+ * The diagram frames of the current selection, on an EDITABLE document.
+ *
+ * The read-only filter is here rather than delegated to the caller because it
+ * belongs to what this list is FOR: generating a legend writes elements onto the
+ * canvas, so it is offered only where writing is possible. The export's own
+ * {@link umlDiagramsForExport} deliberately has no such filter — reading a
+ * diagram and handing the reader a file is exactly what a published, read-only
+ * document is for.
+ */
+export declare function umlDiagramsSelected(std: BlockStdScope): UmlDiagramElementModel[];
+/**
+ * Draw the legend of what is actually on the selected frame, bottom-left of it.
+ *
+ * The FIRST selected frame and no other: a legend is placed relative to one
+ * background, and two of them would put two boxes on top of whatever sits in
+ * that corner. Everything about the gesture — the scan, the placement, the box —
+ * is `createBoardLegend`'s; UML contributes nothing but the rows its own
+ * commands subscribe (`commands.ts`, `docs/adr/0026`).
+ *
+ * The one action in this file with no command behind it, exactly as in C4: the
+ * legend is reached from the selected frame's contextual toolbar and from
+ * nowhere else (PO arbitration, 27/08/2026 — see `toolbar/config.ts`). It is a
+ * legend OF something you have in front of you, not an artefact to pick off a
+ * palette. Kept here beside its siblings all the same, because it is the same
+ * kind of thing — a gesture that writes elements — and because a unit test can
+ * drive it without a toolbar.
+ *
+ * A legend earns its place in UML more than in most packs: the notation's dozen
+ * relationships differ by a diamond's fill and a triangle's outline, and a
+ * reader who is not fluent in §11.5.4 cannot tell a shared aggregation from a
+ * composition without a key on the sheet.
+ */
+export declare function createUmlLegend(std: BlockStdScope): void;
+/**
+ * The diagrams the export speaks about: the SELECTED ones, or every diagram on
+ * the surface when nothing is selected.
+ *
+ * ## Why the fallback, where C4 has none
+ *
+ * `c4BoardsForExport` returns the selection and stops there, because a C4 board
+ * is one LEVEL of one model and merging three of them produces the picture C4
+ * exists to stop people drawing. UML is the opposite object: ADR 0017 ships the
+ * four diagram kinds as ONE framework precisely because they are views of one
+ * model — the classes in a class diagram are the classifiers the objects in the
+ * object diagram instantiate — and both target formats are built to hold all of
+ * them. An XMI `uml:Model` is a single model element holding every packaged
+ * element; a `.puml` file is one document. So a document with four frames on it
+ * and nothing selected exports as the model it is.
+ *
+ * Selecting a frame narrows it, which is the gesture an author makes when they
+ * want one diagram out of a page of them.
+ *
+ * No read-only filter: an export WRITES nothing. A diagram published read-only
+ * is precisely the one somebody wants to take away.
+ */
+export declare function umlDiagramsForExport(std: BlockStdScope): UmlDiagramElementModel[];
+/**
+ * The elements the export speaks about, as ONE list the declared capability
+ * takes: the diagrams in scope, then everything else on the surface in document
+ * order.
+ *
+ * The scope is expressed by which DIAGRAMS are in the list — that is the
+ * capability's contract for this framework (`interchange.ts`) — so an unselected
+ * frame is the one thing left out, and the exporter's own geometric attribution
+ * reads back exactly what {@link umlDiagramsForExport} says.
+ *
+ * Document order matters and is preserved for the same reason it does in BPMN
+ * and C4: it is the tie-break attribution breaks on — a centre inside two
+ * overlapping subjects goes to the first — and sorting here would make the file
+ * disagree with the badge the user can see.
+ *
+ * The compartment texts and the groups that say whose words they are ride along
+ * untouched: a tier belongs to its node through the GROUP rather than through
+ * the geometry, so both lists cross the seam whole and unfiltered.
+ */
+export declare function umlExportElementsOf(std: BlockStdScope): readonly GfxPrimitiveElementModel[];
+/**
+ * What the downloaded file is called, minus the extension.
+ *
+ * The document's own title first — a diagram is what the file is OF — then the
+ * name of the frame whose toolbar launched the export, then a last resort.
+ * Making the answer safe to write to disk is {@link umlSafeFilename}'s job, so
+ * the command and the interchange capability cannot name the same diagram
+ * differently.
+ */
+export declare function umlExportFilename(std: BlockStdScope): string;
+/**
+ * Serialize the diagrams in scope as PlantUML and hand the file 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 `UML_PLANTUML_EXPORT.run`, so
+ * the command and the registry cannot describe the same diagram differently.
+ * There is one door; the registry is the label on it.
+ */
+export declare function exportUmlPlantumlFile(std: BlockStdScope): void;
+/**
+ * Serialize the diagrams in scope as XMI 2.5.1 and hand the file to the browser.
+ *
+ * The same three steps as {@link exportUmlPlantumlFile}, against the other
+ * capability. Two formats because they answer different questions: PlantUML is
+ * what a reader diffs and commits next to the code, XMI is what another UML tool
+ * reads back — the OMG's own interchange format, and the reason this pack
+ * implements 2.5.1 rather than a dialect.
+ */
+export declare function exportUmlXmiFile(std: BlockStdScope): void;
+/**
+ * Read a PlantUML source the user picks, draw it, and say what it cost.
+ *
+ * The whole gesture is {@link runInterchangeImportFile}, over the capability
+ * UML declares: pick the file, run the DECLARED reader, write what it returned,
+ * fit the drawing, report. `UML_PLANTUML_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 `UML_PLANTUML_FORMAT` rather than a table of file types, so
+ * `.plantuml` is offered beside `.puml` because the declaration says both.
+ *
+ * Three commands and three one-line bodies, which is the point of the seam: a
+ * second format costs a declaration and a command, never a pipeline. What
+ * differs between them is the PROMISE, and the promise is made by each
+ * command's own label and description before the picker ever opens (ADR 0012
+ * P2) — two semantic readers that carry the model, and one visual reader that
+ * recognises a drawing.
+ */
+export declare function importUmlPlantumlFile(std: BlockStdScope): Promise<void>;
+/** Read an XMI 2.5.1 document the user picks. The same four steps. */
+export declare function importUmlXmiFile(std: BlockStdScope): Promise<void>;
+/**
+ * Read a draw.io drawing the user picks — the one import with a step before the
+ * reader (`docs/adr/0019`).
+ *
+ * A `.drawio` file holds its `<mxGraphModel>` as base64 of a raw deflate, and
+ * inflating it needs `DecompressionStream`: a platform API, asynchronous, and
+ * therefore forbidden inside a reader that ADR 0012 P3 makes pure. So the
+ * unwrapping rides on the pipeline's `decode` hook, which runs here — where
+ * there is already an editor and an `await` — and `UML_DRAWIO_IMPORT.run` still
+ * takes decoded XML and still answers a compressed payload with a remark rather
+ * than a guess.
+ *
+ * {@link decodeDrawio} is identity for a file that is already plain XML, so the
+ * `.drawio.xml` case and the "Compressed: off" case cost nothing and take the
+ * same path.
+ */
+export declare function importUmlDrawioFile(std: BlockStdScope): Promise<void>;