@formicoidea/labre-framework-uml 0.42.0

package/dist/drawio-import.d.ts

@@ -0,0 +1,133 @@
+import type { InterchangeNote } from '@formicoidea/labre-core/blocks/surface';
+import type { UmlBox } from './component.js';
+import type { UmlModel } from './model.js';
+/**
+ * A draw.io drawing, read as a UML model — the **visual** tier of
+ * `docs/adr/0012` (see `docs/adr/0019`).
+ *
+ * ## Why this reader is `visual` where the other two are `semantic`
+ *
+ * A `.drawio` file carries no UML metamodel. What it carries is a list of
+ * boxes, each with a `style` string and a blob of HTML, so "this box is a
+ * Class" is a GUESS made out of `<hr />` separators and `endArrow=block`. It is
+ * a good guess — every UML shape library in draw.io writes the same handful of
+ * style tokens, and the corpus this was written against is draw.io's own UML
+ * class example — but it is a guess, and ADR 0012 P2 is explicit that the tier
+ * is a promise made to the user BEFORE the file is read. So: no round-trip
+ * promise, and anything this reader does not recognise becomes a `carried` note
+ * naming the cell and the style that defeated it. Nothing here throws and
+ * nothing is dropped in silence.
+ *
+ * ## Decoded XML in, and nothing else (ADR 0019, the compressed-payload split)
+ *
+ * A `.drawio` file's `<diagram>` usually holds base64 of a raw-deflate of
+ * URI-encoded XML. Inflating it needs `DecompressionStream` — a platform API,
+ * and asynchronous — so it is NOT done here. This function is pure and
+ * synchronous per P3, which is what makes it callable from labre-mcp and
+ * testable with neither an editor nor a browser; the COMMAND decodes first
+ * (`drawio-decode.ts`, `actions.ts`). What arrives here is either a plain
+ * `<mxGraphModel>` or an `<mxfile>` whose `<diagram>` already holds one, and a
+ * payload that is still compressed comes back as an empty model carrying one
+ * `warning` note rather than as an exception. {@link isCompressedDrawio} is the
+ * same test, exported so the capability can say so before it reads.
+ *
+ * ## The XML comes off the shared reader
+ *
+ * `DOMParser` is a DOM API and a pure function has no DOM, so the tree comes
+ * from `xml-reader.ts` — the same tolerant reader the XMI importer walks. One
+ * reader for the two XML formats this framework reads means one set of
+ * entity-decoding bugs rather than two.
+ */
+/**
+ * Where the source drew every cell, in MODEL units, relative to the drawing's
+ * own top-left corner.
+ *
+ * One draw.io unit is one model unit — both are CSS-pixel-shaped, and both
+ * frameworks draw a class box at a couple of hundred of them — so the only
+ * transform is a TRANSLATION: the minimum corner of the drawing becomes
+ * `(0, 0)` here, and the materializer adds the frame's plot origin and its own
+ * margin. That way round keeps this function free of the one number it cannot
+ * know (where the frame will land) and the materializer free of the one it
+ * cannot know (how far from the origin somebody had dragged their diagram).
+ *
+ * Keyed by the SOURCE cell id, which is the id every element also carries under
+ * `interchange.drawio.id` (`docs/adr/0012` D3) — so a box is resolved the same
+ * way a connector end is.
+ */
+export interface UmlDrawioLayout {
+    boxes: Record<string, UmlBox>;
+}
+/** What {@link importDrawio} read: the model, the remarks, and the geometry. */
+export interface UmlDrawioImport {
+    model: UmlModel;
+    notes: InterchangeNote[];
+    layout: UmlDrawioLayout;
+}
+/** The format id foreign draw.io matter rides under (`docs/adr/0012` D2). */
+export declare const UML_DRAWIO_FORMAT_ID = "drawio";
+/**
+ * Whether this text is an `<mxfile>` whose payload still needs inflating.
+ *
+ * The test is the honest one — "there is a `<diagram>` and no `<mxGraphModel>`
+ * anywhere in it" — rather than a guess at what base64 looks like: draw.io
+ * writes the uncompressed form under the very same element (File › Properties ›
+ * Compressed: off), and a reader that refused those would refuse half the files
+ * in the wild for the sake of a heuristic.
+ */
+export declare function isCompressedDrawio(text: string): boolean;
+/**
+ * A cell's `value` as COMPARTMENTS of lines — draw.io's UML class template,
+ * read.
+ *
+ * The template is `<p>Name</p><hr />attributes<hr />operations`, each member
+ * separated by `<br />`, and the whole of it HTML-escaped inside the `value`
+ * attribute. So: split on the rules, turn every block boundary into a newline,
+ * drop what is left of the markup, and decode what the markup was hiding.
+ *
+ * The second decode pass, after the tags come off, is deliberate rather than
+ * belt-and-braces: draw.io escapes the HTML into an XML attribute, so a `<` the
+ * author typed in a label is `&amp;lt;` in the file and one pass would leave
+ * them looking at `&lt;`.
+ *
+ * Blank lines and §9.2.4's elision marker are dropped, exactly as
+ * `parseCompartment` drops them for a compartment the author typed on the
+ * canvas: a file that wrote `...` back as a property named `...` would turn
+ * "there are more features, not shown" into "one of them is called dot dot
+ * dot".
+ */
+export declare function drawioCompartments(value: string | undefined): string[][];
+/**
+ * The one remark this reader raises whose wording is FIXED, as a
+ * `[key, English]` pair — the same table, the same shape and the same reasons
+ * as `UML_PLANTUML_REMARKS` (`plantuml-import.ts`, where the contract is
+ * written out): one entry per SHAPE of sentence, the `{{kind}}` hole filled at
+ * the call site by `InterchangeNote.messageParams`, the English kept here as
+ * the fallback.
+ *
+ * The reader's refusals ({@link importDrawio}'s `refused`) and its two
+ * {@link carried} fragments are deliberately NOT here: a remark that names
+ * something out of the file with no sentence shape worth sharing — a raw style
+ * dump, a one-off diagnostic — carries no key and stays English, which is what
+ * `InterchangeNote.messageKey`'s own contract asks for.
+ */
+export declare const UML_DRAWIO_REMARKS: {
+    readonly ambiguousBlockHead: readonly ["com.labre.uml.import.drawio.ambiguous-block-head", "read as a {{kind}}, but the arrowhead is drawn filled; UML draws the generalization triangle hollow (endFill=0)."];
+};
+/**
+ * A draw.io drawing as a UML model.
+ *
+ * Never throws. A file that is not a draw.io document at all comes back as an
+ * empty model with one `warning` note, which is the same answer as for a
+ * payload that is still compressed: this is the visual tier, the tier's promise
+ * is recognition, and "I recognised nothing" is an answer rather than a
+ * failure.
+ *
+ * @param xml a decoded `<mxGraphModel>`, or an `<mxfile>` whose `<diagram>`
+ *   already holds one. See the module docblock for why the compressed form is
+ *   the command's problem and not this function's.
+ * @param options.name what to call the sheet when the file names nothing — the
+ *   importer's context name, which is the file's own name in practice.
+ */
+export declare function importDrawio(xml: string, options?: {
+    name?: string;
+}): UmlDrawioImport;