@formicoidea/labre-framework-uml 0.42.0

package/dist/import.d.ts

@@ -0,0 +1,306 @@
+import type { InterchangeNote, SerializedElementProps } from '@formicoidea/labre-core/blocks/surface';
+import { type UmlBox } from './component.js';
+import { type UmlModel, type UmlNodeBase, type UmlRelation, type UmlRelationKind } from './model.js';
+/**
+ * The **one materializer** every UML importer ends on — a model in, the
+ * serialized props of a board out (`docs/adr/0012`, P3).
+ *
+ * ## Why the pipeline forks at the PARSER and nowhere else
+ *
+ * Three formats read UML into Labre — PlantUML, XMI 2.5.1 and draw.io — and the
+ * only thing they disagree about is how a file spells a class. What a class IS
+ * on this canvas is five elements written in painting order, with three seeded
+ * compartments, one role per tier and a group over them (`actions.ts`), and that
+ * answer belongs to the pack rather than to any file format. Written three
+ * times it would be wrong in three different ways, and a class imported from a
+ * `.drawio` would not be the class the toolbox draws.
+ *
+ * So each parser produces a {@link UmlModel} — the same IR the two WRITERS
+ * already take — and this file turns it into elements. The pivot is the phase-1
+ * model and not a shape of its own, which is what makes the round trip
+ * checkable: read our own export, materialize it, read the board back with
+ * `umlModelFrom`, and the model is the one we started with.
+ *
+ * ## Never a size, never a colour, never a seed
+ *
+ * Every prop below comes out of {@link umlNodeProps}, {@link umlTextProps} and
+ * {@link umlCompartmentBoxes} — the very three functions the creation site calls
+ * (R17). Not one measurement is restated here, so an imported class and a drawn
+ * one are the same element down to the stroke width, and a restyle that moves
+ * the pack moves the import with it.
+ *
+ * ## The two names an element carries, and they are not the same name
+ *
+ * - `interchange[formatId].id` is the SOURCE file's id, verbatim: D3's fixed
+ *   point, what an export prefers back, and what a support thread quotes.
+ * - `id` is this reader's OWN provisional name — `uml-import-<n>`, minted in
+ *   document order. `surface.addElement` overwrites it with a nanoid and is
+ *   documented to, so it reaches no document: it exists so that a connector can
+ *   say which shape it runs to and a group can say which tiers it holds, before
+ *   the surface has minted an id for either. `materializeInterchangeImport`
+ *   resolves both.
+ *
+ * A source id is NOT usable for the second job: a tier and a group are elements
+ * Labre mints and no file ever named, two sheets may spell one class the same
+ * way, and PlantUML's own identifiers are aliases rather than ids. Minting is
+ * the only answer that is always available and always unique.
+ *
+ * ## Layout (D4)
+ *
+ * Geometry when the source carried some — `opts.layout.boxes` for a format that
+ * reads coordinates out of the file (draw.io's `mxGeometry`, XMI's `umldi`), or
+ * the `bounds` a parser already wrote onto the IR. Otherwise a layered layout is
+ * INVENTED, in rows by generalization depth, and the caller says so with an
+ * `invented-layout` note: D4 forbids claiming a position came from a file that
+ * never had one.
+ *
+ * ## Pure
+ *
+ * Models in, props out. No `std`, no surface, no DOM, no clock, no randomness —
+ * every id and every coordinate is a function of document order alone, so the
+ * same file always lands the same board.
+ */
+/**
+ * One cell of the layered layout — the module a diagram nobody positioned is
+ * measured in.
+ *
+ * Wider and shallower than a class box (200 × 120) on purpose: the gap has to
+ * leave room for the name of the relationship drawn across it, and a row of
+ * boxes packed edge to edge reads as one band rather than as five classifiers.
+ */
+export declare const UML_IMPORT_SLOT: {
+    readonly w: 240;
+    readonly h: 140;
+};
+/** The space between two slots, in both directions. */
+export declare const UML_IMPORT_GUTTER = 60;
+/** The margin between the drawing and the frame drawn round it. */
+export declare const UML_IMPORT_MARGIN = 60;
+/**
+ * The distance between two lifeline SPINES on a sheet nobody positioned.
+ *
+ * Wide enough that a 160-unit head has 40 units of air on either side of it, and
+ * that a message label written over the gap is legible. It is also comfortably
+ * more than twice {@link UML_SPINE_TOLERANCE}, which is what stops a bar dropped
+ * on one spine from being claimed by its neighbour.
+ */
+export declare const UML_SD_COLUMN_GAP = 200;
+/**
+ * The height of ONE SLOT — the vertical distance between two consecutive things
+ * that happen.
+ *
+ * A slot per EVENT and not per message, and that is the whole trick of the
+ * sequence importers: a `.puml` and an XMI fragment list state an ORDER and no
+ * heights, the canvas states heights and no order, and `model.ts` reads the
+ * order back off the heights. Giving every event — an arrow, the start of a bar,
+ * the end of one, an `alt`, an `else`, an `end` — a slot of its own is what makes
+ * that round trip exact: no two events tie, so nothing can come back reordered.
+ */
+export declare const UML_SD_EVENT_STEP = 40;
+/** Where the first event sits: one slot below the bottom of the heads. */
+export declare const UML_SD_FIRST_EVENT: number;
+/** How far outside the spines it covers a combined fragment is drawn. */
+export declare const UML_SD_FRAGMENT_PADDING = 20;
+/** The height of the nth slot of an invented sequence layout. */
+export declare function umlSequenceSlot(index: number): number;
+/**
+ * The COLUMN box of the nth lifeline — the narrow tall element, not the head.
+ *
+ * `UmlNodeElementModel` makes a lifeline the spine and paints the head across
+ * the top of it, so what is laid out here is the spine: its centre is the line
+ * the conversation is measured against, and the head overflows it on both sides
+ * by the same amount.
+ */
+export declare function umlSequenceColumn(index: number, height: number): UmlBox;
+/** The bar §17.2.4 draws on a spine between two occurrences. */
+export declare function umlSequenceExecution(column: UmlBox, y0: number, y1: number): UmlBox;
+/** The cross §17.2.4 ends a lifeline with, centred on the spine. */
+export declare function umlSequenceDestruction(column: UmlBox, y: number): UmlBox;
+/**
+ * The rectangle §17.6.4 draws round the spines a fragment covers.
+ *
+ * {@link UML_SD_FRAGMENT_PADDING} outside the outermost two, which is what makes
+ * the box cover the spines rather than end on them — `model.ts` reads coverage
+ * as "the spine runs through the box", and a rectangle whose edge lands exactly
+ * on a spine is a coin toss.
+ */
+export declare function umlSequenceFragment(columns: readonly UmlBox[], y0: number, y1: number): UmlBox;
+/** What one artefact asks the layout for. */
+export interface UmlLayoutNode {
+    id: string;
+    /** Its own footprint, before anything it contains is measured. */
+    size: {
+        w: number;
+        h: number;
+    };
+    /** What is drawn INSIDE it, in document order. Containers only. */
+    children?: readonly string[];
+}
+/**
+ * A layered layout for a diagram that carried no geometry (D4).
+ *
+ * ## Rows by generalization depth
+ *
+ * Because that is the one ordering a class diagram has of its own: §9.2.4 draws
+ * the general classifier above the specific one, so a hierarchy read top to
+ * bottom is a hierarchy drawn top to bottom, and a sheet laid out this way is
+ * legible the moment it opens instead of being a grid somebody has to untangle.
+ * A classifier that specializes nothing is a root and sits in the first row;
+ * everything else sits one row below the deepest thing it specializes.
+ *
+ * Containers are laid out RECURSIVELY and sized to fit, because containment on
+ * this canvas IS geometry: a class is in a package when it is drawn inside it
+ * (`model.ts`, `plantuml.ts`, `xmi.ts` all read it that way), so a layout that
+ * placed a package's contents outside it would lose the nesting the file stated.
+ *
+ * Deterministic by construction: document order within a row, document order
+ * inside a container, and no measurement that depends on anything but the sizes
+ * handed in.
+ */
+export declare function umlInventLayout(nodes: readonly UmlLayoutNode[], relations?: readonly UmlRelation[]): Map<string, UmlBox>;
+/**
+ * A name compartment, written back the way the grammar reads it.
+ *
+ * The exact inverse of `stereotypesOf`: the Annex C keywords on their own line
+ * above the name — which is where §9.2.4 draws them and what the stencils seed —
+ * and §9.2.4's `{abstract}` modifier after it, which is the alternative that
+ * same clause allows a canvas with no italic name compartment. Read back, the
+ * three facts come out exactly as they went in.
+ */
+export declare function umlNameTierText(node: UmlNodeBase): string;
+/** One line on the board: its role, its two ends and its three labels. */
+export interface UmlDrawnEdge {
+    kind: UmlRelationKind;
+    sourceId: string;
+    targetId: string;
+    label?: string;
+    /**
+     * §11.5.4's adornments beside the source end, already SPELLED.
+     *
+     * A string rather than the {@link UmlAssociationEnd} record, because what the
+     * connector holds is a label — one line of text an author goes on to edit by
+     * hand. The printing is `formatEndLabel`'s, which is the same one the PlantUML
+     * writer uses, so an association imported from XMI and one exported to a
+     * `.puml` spell their ends identically.
+     */
+    sourceEnd?: string;
+    /** The same, beside the target end. */
+    targetEnd?: string;
+    /**
+     * The HEIGHT a message is drawn at (§17.4.4), for the five kinds that have
+     * one.
+     *
+     * Present only for a message, and it is what makes a sequence diagram
+     * readable at all: every other UML line is anchored at the centre of the two
+     * boxes it joins, and a message anchored at the centre of a 600-unit spine
+     * would put the whole conversation on one horizontal line. See
+     * {@link messageAnchors}.
+     */
+    y?: number;
+}
+/**
+ * Every line one model draws — `relations`, plus the behaviour edges that live
+ * on the Activity and the StateMachine.
+ *
+ * ## Why there are two places to look, and neither can be dropped
+ *
+ * `umlModelFrom` reads a canvas and fills BOTH: a transition is a relation (one
+ * pass over the connectors resolves every end) and it is projected onto the
+ * machine, where the label grammar is parsed. The PlantUML reader mirrors that.
+ * The XMI reader cannot: `<edge>` and `<transition>` are children of the
+ * Activity and the StateMachine in the file, so it fills
+ * {@link UmlActivity.edges} and {@link UmlStateMachine.transitions} and leaves
+ * `relations` for the structural arrows. A materializer that walked only
+ * `relations` imported every XMI activity and every state machine with ZERO
+ * arrows on it — the defect this function exists to close.
+ *
+ * So: walk both, and DEDUPE, because a model may legitimately hold a line in
+ * each. The dedupe is a count per (kind, source, target) rather than a set, so
+ * two parallel transitions between one pair stay two — `relations` claims the
+ * first, the machine's second one is drawn, and nothing is drawn twice.
+ *
+ * The labels are printed with `grammar.ts`'s own printers, which is what the
+ * PlantUML writer uses: a guard imported from XMI and one exported to a `.puml`
+ * are then spelled identically, and `parseTransition` reads back exactly what
+ * was written.
+ */
+export declare function umlDrawnEdges(model: UmlModel): UmlDrawnEdge[];
+/** Where a source that carried coordinates says its artefacts are drawn. */
+export interface UmlLayoutHints {
+    /**
+     * Boxes by SOURCE id, in model units and in one coordinate space.
+     *
+     * Whatever the file drew, translated as a block so its top-left corner lands
+     * at the frame's plot origin — the caller need not do the arithmetic, only
+     * agree with itself about which corner is which.
+     */
+    boxes?: Readonly<Record<string, UmlBox>>;
+    /**
+     * What the file says is drawn INSIDE what — child source id → container
+     * source id.
+     *
+     * For a format that states containment structurally and carries no geometry:
+     * XMI's `packagedElement` and `ownedUseCase` are the cases, and without this
+     * an imported package comes back empty and every class in it beside it. Read
+     * only where {@link boxes} gave no box — a file that drew the nesting has
+     * already said where everything is. See {@link containmentOf}.
+     */
+    containment?: Readonly<Record<string, string>>;
+}
+export interface UmlMaterializeOptions {
+    /**
+     * The interchange format whose payload key carries the source ids (D2) —
+     * `'plantuml'`, `'xmi'`, `'drawio'`. The same string the capability's
+     * {@link InterchangeFormat} declares, because
+     * `materializeInterchangeImport` looks the ids back up under it.
+     */
+    formatId: string;
+    layout?: UmlLayoutHints;
+    /**
+     * The top-left corner the first frame is drawn at. `(0, 0)` by default.
+     *
+     * An import is a NEW board beside whatever is already there, never a merge
+     * (`interchange-import.ts`) — and a materializer that always started at the
+     * origin made two imports into one heap. The caller knows what the surface
+     * already holds; this is where it says so.
+     *
+     * `materializeInterchangeImport` does the same thing one layer up, for every
+     * framework at once and out of the surface's own bounds, so a command need not
+     * pass this. It is here for the callers that have no surface to ask — a
+     * labre-mcp tool writing a document, a test — and so that the property is
+     * checkable without one.
+     */
+    origin?: {
+        x: number;
+        y: number;
+    };
+}
+export interface UmlMaterializeResult {
+    elements: SerializedElementProps[];
+    /** What the materializer had to invent — D4's `invented-layout`, and only it. */
+    notes: InterchangeNote[];
+}
+/**
+ * The MATERIALIZER's own two remarks, as `[key, English]` pairs — raised by
+ * {@link umlElementsFromModel} whichever reader produced the model, which is
+ * why they are declared here rather than in any one reader's table.
+ *
+ * Same shape and same reasons as `UML_PLANTUML_REMARKS`
+ * (`plantuml-import.ts`, where the contract is written out): one entry per
+ * SHAPE of sentence, the `{{count}}` / `{{heading}}` holes filled at the call
+ * site by `InterchangeNote.messageParams`, the English kept here as the
+ * fallback so a report drawn with no host catalogue reads exactly as before.
+ */
+export declare const UML_LAYOUT_REMARKS: {
+    readonly allInvented: readonly ["com.labre.uml.import.layout.all-invented", "This source carries no coordinates, so the {{count}} artefacts of \"{{heading}}\" were laid out by Labre, in rows by generalization depth. The positions are ours, not the file's."];
+    readonly someInvented: readonly ["com.labre.uml.import.layout.some-invented", "{{count}} of the artefacts of \"{{heading}}\" were drawn nowhere in the source, so Labre laid them out below the rest. Their positions are ours, not the file's."];
+};
+/**
+ * Every model as the elements of a board — one `umlDiagram` frame per model,
+ * the artefacts drawn on it, and the connectors between them.
+ *
+ * The frames are stacked down the canvas rather than overlaid, because a UML
+ * document with four diagrams in it is four sheets (ADR 0017) and two frames
+ * sharing a box is two diagrams neither of which can be attributed.
+ */
+export declare function umlElementsFromModel(models: readonly UmlModel[], options: UmlMaterializeOptions): UmlMaterializeResult;