@formicoidea/labre-framework-uml 0.42.0

package/dist/element-view.js

@@ -0,0 +1,430 @@
+import { backgroundLabelHits, DeclaredBackgroundView, EdgelessCRUDIdentifier, hitTestBackgroundLabel, } from '@formicoidea/labre-core/blocks/surface';
+import { TranslationProvider } from '@formicoidea/labre-core/shared/services';
+import { UML_DIAGRAM_FRAME, UML_FRAGMENT_FRAME, UML_REGION_FRAME, UML_SUBJECT_FRAME, umlPartitionFrame, } from './background.js';
+import { umlFragmentOperands, umlInDiagramBand, umlInPartitionBand, umlInRegionBand, umlOperandBoundaryAt, umlOperandGuardAt, } from './board-hit.js';
+import { UML_OPERAND_MIN_HEIGHT } from './consts.js';
+import { umlFragmentAsPainted } from './element-renderer.js';
+/**
+ * The one gesture every UML frame carries: a double-click on the name edits it
+ * in place.
+ *
+ * The gesture itself — the rotation arithmetic, the widened `includesPoint`,
+ * the double-click handler and the `<input>` — is the library's shared one,
+ * `DeclaredBackgroundView` (issue #355, R14: extend, never copy). What this
+ * class adds is only what UML answers differently: WHICH words a double-click
+ * aims at, and the model those words are read from.
+ *
+ * Which labels exist, where they sit and what they SAY all come from the
+ * declaration the renderer paints (`backgroundLabelHits`), so a label can never
+ * be drawn in one place and clicked in another — which is why this class has no
+ * coordinates of its own.
+ *
+ * ponytail: like every other framework view in the library, only `name` may be
+ * written — see {@link UmlDiagramView} for what that costs the diagram frame,
+ * whose drawn label is not `name`.
+ */
+class UmlFrameView extends DeclaredBackgroundView {
+    /**
+     * The model this view hit-tests against — the one the RENDERER was handed.
+     *
+     * The stored model for every frame but one, and the hook exists for that one:
+     * a combined fragment paints through `umlFragmentAsPainted`, which hides a
+     * declared `name` that operand zero's guard already covers. The boxes
+     * `backgroundLabelHits` derives are only the drawn words if they are derived
+     * from the same declaration — otherwise the suppressed corner stays clickable
+     * and opens an editor on a string nothing paints.
+     *
+     * A getter and not a cached value: the props it reads are the document's, and
+     * a view outlives every edit to them.
+     */
+    get _painted() {
+        return this.model;
+    }
+    /**
+     * The declaration's editable labels, element-local, derived from the PAINTED
+     * model — see {@link _painted}. This is `DeclaredBackgroundView.labelAt`'s
+     * own walk with that one substitution, which is why the frames below do not
+     * call `super.labelAt`.
+     */
+    _hits(w, h) {
+        return backgroundLabelHits(this.def, this._painted, w, h, this.gfx.std.getOptional(TranslationProvider));
+    }
+    /**
+     * Which region of the frame aims at the name, given an ELEMENT-LOCAL point.
+     *
+     * The DRAWN WORDS by default — the box `backgroundLabelHits` derives from the
+     * very anchor the renderer paints at. That is the right answer for a name
+     * written INSIDE the plot, over the drawing, where anything wider would
+     * swallow clicks meant for the elements around it: the subject's name sits in
+     * its top-left corner, and this is its whole story.
+     *
+     * A frame whose name has a band of its own overrides this — see
+     * {@link UmlDiagramView}.
+     */
+    labelAt(lx, ly, w, h) {
+        const hit = hitTestBackgroundLabel(this._hits(w, h), lx, ly);
+        return hit && hit.prop === 'name' ? { prop: 'name', text: hit.text } : null;
+    }
+    /**
+     * The name label, answered over a whole BAND rather than over its words —
+     * for the frames whose name has a strip of its own.
+     *
+     * @param inBand whether the point is in the frame's band, as the frame's own
+     * band helper (`board-hit.ts`) decides.
+     */
+    _nameInBand(inBand, w, h) {
+        if (!inBand)
+            return null;
+        const name = this._hits(w, h).find(hit => hit.prop === 'name');
+        return name ? { prop: 'name', text: name.text } : null;
+    }
+}
+/**
+ * The sheet a UML diagram is drawn on. Double-click ANYWHERE in its heading band
+ * to rename it.
+ *
+ * The band and not the words, which is the first thing this subclass changes —
+ * the same call the C4 board and the BPMN pool's participant band both make: a
+ * strip you may only double-click the eleven characters of is a target that lies
+ * about where it is. Here it also buys something they do not need: the tag is
+ * drawn round the words with padding on either side, so a user aiming at the
+ * pentagon they can see is inside the zone whether or not they hit a glyph.
+ *
+ * The second is what the editor opens on, and that is the one place UML parts
+ * company with the C4 board it is modelled on. Annex A's heading is
+ * `<kind> <name>` — a derived string, joined from a closed discriminant the
+ * picker owns and a name the author owns — so opening on the drawn words would
+ * hand the user `class Orders` to edit, and committing it would write the kind
+ * INTO the name, to be prefixed again on the next paint. The editor therefore
+ * opens on `name` — the author's half — and writes `name` back, never the drawn
+ * label's own prop: `heading` is a getter, and a getter is not somewhere a
+ * rename can land.
+ */
+export class UmlDiagramView extends UmlFrameView {
+    static { this.type = 'umlDiagram'; }
+    get def() {
+        return UML_DIAGRAM_FRAME;
+    }
+    labelAt(lx, ly, w, h) {
+        if (!umlInDiagramBand(this.model, [lx, ly]))
+            return null;
+        const heading = this._hits(w, h).some(hit => hit.prop === 'heading');
+        return heading ? { prop: 'name', text: this.model.name } : null;
+    }
+}
+/** The rectangle drawn round a system's use cases. Double-click its name. */
+export class UmlSubjectView extends UmlFrameView {
+    static { this.type = 'umlSubject'; }
+    get def() {
+        return UML_SUBJECT_FRAME;
+    }
+}
+/**
+ * An activity swimlane (§15.6.4). Double-click ANYWHERE in its name band to
+ * rename it — across the top of a vertical lane, down the left edge of a
+ * horizontal one.
+ *
+ * The band and not the words, the same call the diagram frame makes: a strip you
+ * may only double-click the eight characters of is a target that lies about
+ * where it is. It matters more here than on the sheet, because a partition is
+ * TRANSPARENT: every point that is not its own furniture falls through to the
+ * actions drawn inside it, so the header is the only place a user can take hold
+ * of the lane at all.
+ *
+ * The declaration this hit-tests against is chosen by the element's own
+ * `orientation`, through the one function that makes that choice — so the view,
+ * the renderer and the band helper cannot disagree about which edge the band is
+ * on.
+ */
+export class UmlPartitionView extends UmlFrameView {
+    static { this.type = 'umlPartition'; }
+    get def() {
+        return umlPartitionFrame(this.model);
+    }
+    labelAt(lx, ly, w, h) {
+        return this._nameInBand(umlInPartitionBand(this.model, [lx, ly]), w, h);
+    }
+}
+/**
+ * A composite state (§14.2.4). Double-click anywhere in its name band to rename
+ * it.
+ *
+ * The partition's story with no orientation to turn: the band is across the top,
+ * always, because that is where §14.2.4 writes a state's name.
+ */
+export class UmlRegionView extends UmlFrameView {
+    static { this.type = 'umlRegion'; }
+    get def() {
+        return UML_REGION_FRAME;
+    }
+    labelAt(lx, ly, w, h) {
+        return this._nameInBand(umlInRegionBand(this.model, [lx, ly]), w, h);
+    }
+}
+/**
+ * A COMBINED FRAGMENT (§17.6.4). Two gestures of its own, on top of the rename
+ * every UML frame carries:
+ *
+ * - **dblclick on a GUARD** — the `[condition]` written in an operand's
+ *   top-left corner — edits that guard in place. On an unsplit fragment there
+ *   is one, and it is the element's own `name`; once the box has been cut into
+ *   operands each of them carries its own, in `operands[i].name`;
+ * - **drag on an internal operand SEPARATOR** moves the dashed line, taking
+ *   from one operand and giving to the other.
+ *
+ * ## The operator is NOT renamed here
+ *
+ * Double-clicking the pentagon does nothing, deliberately. `operator` is a
+ * closed discriminant of thirteen values (§17.6.4 plus §17.7.4's `ref`) and it
+ * is picked from the toolbar; a free-text editor over it would let an author
+ * type `altt` and lose every rule, every reading and every export that keys on
+ * the word. The same call the diagram frame's `kind` already makes.
+ *
+ * ## How the separator drag takes the gesture
+ *
+ * Armed, exactly as `BpmnPoolView`'s is and for the reason stated there:
+ * `GfxElementModelView.dispatch` reports a drag as handled whenever a handler
+ * is REGISTERED, so a permanent `dragstart` would make the fragment
+ * undraggable. The handlers are attached while the pointer is over a separator
+ * of a SELECTED fragment and detached the moment it is not.
+ *
+ * ponytail: a ROTATED fragment is not accounted for by the separator drag —
+ * its pointer is converted to element-local coordinates by subtraction, so the
+ * separator boxes assume an upright frame (the guards do not: the shared base
+ * de-rotates before {@link labelAt}). The same reserve `board-hit.ts`
+ * documents; nothing rotates a framework background today.
+ */
+export class UmlFragmentView extends UmlFrameView {
+    constructor() {
+        super(...arguments);
+        /** The separator the pointer is over, and the handlers armed for it. */
+        this._armed = null;
+        /** Everything a separator drag needs, frozen at `dragstart`. */
+        this._drag = null;
+    }
+    static { this.type = 'umlFragment'; }
+    get def() {
+        return UML_FRAGMENT_FRAME;
+    }
+    /**
+     * The suppression the renderer applies, read back here so the rename boxes
+     * are the drawn words and nothing else.
+     *
+     * On a SPLIT fragment written by an older build the stored model carries both
+     * `name` and `operands`, and the canvas paints operand zero's guard over the
+     * declared one's corner — i.e. paints `name` nowhere. `umlFragmentAsPainted`
+     * is the single statement of which of the two wins; calling it here is what
+     * keeps {@link labelAt}'s fallback from opening an editor on the invisible
+     * corner. The operand branch of that method is unaffected: it reads
+     * `operands`, which the suppression never touches.
+     */
+    get _painted() {
+        return umlFragmentAsPainted(this.model);
+    }
+    onCreated() {
+        super.onCreated();
+        this.on('pointermove', e => this._updateHover(e));
+        this.on('pointerdown', e => this._updateHover(e));
+        this.on('pointerleave', () => this._leave());
+    }
+    onDestroyed() {
+        this._leave();
+        super.onDestroyed();
+    }
+    /* ── The rename targets ────────────────────────────────────────────── */
+    /**
+     * The operand guards first, the declaration's own label second.
+     *
+     * The order is the order the gestures win in, and it only matters on a SPLIT
+     * fragment: the first operand's corner is the very corner the declared
+     * `guard` label is anchored in. The operand takes it, because on a split
+     * fragment the guards live in `operands` and `name` has been moved into the
+     * first of them (`background.ts` states the contract) — handing the
+     * double-click to `name` would open an editor on a string nothing paints.
+     */
+    labelAt(lx, ly, w, h) {
+        const index = umlOperandGuardAt(this.model, [lx, ly]);
+        if (index !== null) {
+            const operand = this._operands()[index];
+            if (operand) {
+                // A guard lives INSIDE `operands`, which no `{ [prop]: value }` patch
+                // can reach — hence the label's own `commit`, the base's one write
+                // hook. `prop` names the prop the hook rewrites; the base never writes
+                // it itself.
+                return {
+                    prop: 'operands',
+                    text: operand.name ?? '',
+                    commit: value => this._writeGuard(index, value),
+                };
+            }
+        }
+        return super.labelAt(lx, ly, w, h);
+    }
+    _operands() {
+        const stored = this.model.operands;
+        return Array.isArray(stored) ? stored : [];
+    }
+    /**
+     * Write one operand's guard, dropping the key entirely when it is cleared.
+     *
+     * The same shape `renameBpmnLane` writes: an absent `name` is an unguarded
+     * operand — which is what an `else` branch with no condition is — and an
+     * empty string left in the array would be a key that means nothing and
+     * paints nothing.
+     *
+     * No undo boundary here: the shared editor captures one before it calls a
+     * label's `commit`.
+     */
+    _writeGuard(index, value) {
+        const operands = this._operands();
+        const operand = operands[index];
+        if (!operand)
+            return;
+        const trimmed = value.trim();
+        if ((operand.name ?? '') === trimmed)
+            return;
+        const next = operands.map((entry, i) => i === index
+            ? {
+                id: entry.id,
+                ...(trimmed ? { name: trimmed } : {}),
+                size: entry.size,
+            }
+            : entry);
+        this.gfx.std
+            .get(EdgelessCRUDIdentifier)
+            .updateElement(this.model.id, { operands: next });
+    }
+    /* ── The separator drag ────────────────────────────────────────────── */
+    /**
+     * A fragment is SELECTED by its border and its operator band — but the
+     * internal operand separators are twelve-unit strips in the middle of the
+     * plot, and they must still receive their pointer events.
+     *
+     * Not a selection zone: a click between two messages still goes to whatever
+     * is under it, because picking asks the MODEL. This only decides where the
+     * fragment's own gestures are heard.
+     */
+    includesPoint(x, y, options, host) {
+        if (super.includesPoint(x, y, options, host))
+            return true;
+        const [ex, ey] = this.model.deserializedXYWH;
+        return umlOperandBoundaryAt(this.model, [x - ex, y - ey]) !== null;
+    }
+    /** Whether this fragment may be written to at all. */
+    get _writable() {
+        return !this.gfx.std.store.readonly && !this.model.isLocked();
+    }
+    _leave() {
+        this._disarm();
+        if (!this._drag)
+            this.gfx.cursor$.value = 'default';
+    }
+    _localPoint(e) {
+        const [mx, my] = this.gfx.viewport.toModelCoord(e.x, e.y);
+        const [ex, ey] = this.model.deserializedXYWH;
+        return [mx - ex, my - ey];
+    }
+    /** One pass over the pointer: the cursor, and whether a drag is armed. */
+    _updateHover(e) {
+        const local = this._localPoint(e);
+        const selected = this.gfx.selection.selectedIds.includes(this.model.id);
+        if (this._writable && selected) {
+            const index = umlOperandBoundaryAt(this.model, local);
+            if (index !== null) {
+                // Reasserted on every move rather than only on arrival: the cursor is
+                // shared with the resize handles and the tools, and whoever set it last
+                // wins — so the one that is still true says so again.
+                this.gfx.cursor$.value = 'ns-resize';
+                if (this._armed?.index !== index) {
+                    this._disarm();
+                    this._armed = {
+                        index,
+                        disposers: [
+                            this.on('dragstart', () => this._onDragStart()),
+                            this.on('dragmove', evt => this._onDragMove(evt)),
+                            this.on('dragend', () => this._onDragEnd()),
+                        ],
+                    };
+                }
+                return;
+            }
+        }
+        this._disarm();
+        // A guard announces itself, selected or not: finding out that a condition
+        // can be changed should not cost a click first.
+        const overGuard = this._writable && umlOperandGuardAt(this.model, local) !== null;
+        this.gfx.cursor$.value = overGuard ? 'text' : 'default';
+    }
+    _disarm() {
+        // Never mid-gesture: the pointer leaves the separator as soon as the drag
+        // starts moving, and disarming there would drop it on its first step.
+        if (this._drag)
+            return;
+        if (!this._armed)
+            return;
+        this._armed.disposers.forEach(dispose => dispose());
+        this._armed = null;
+    }
+    _onDragStart() {
+        const index = this._armed?.index;
+        const geometry = umlFragmentOperands(this.model);
+        if (index === undefined || !geometry || !this._writable)
+            return;
+        const operands = this._operands();
+        if (!operands[index - 1] || !operands[index])
+            return;
+        const total = operands.reduce((sum, operand) => sum + operand.size, 0);
+        if (!(total > 0))
+            return;
+        this._drag = {
+            index,
+            operands: operands.map(operand => ({ ...operand })),
+            total,
+            plotHeight: geometry.plot.height,
+            // The floor is a HEIGHT the user can see, stated in the model units of a
+            // fragment at its reference height and converted to a weight against this
+            // fragment's own total — so a fragment stretched to twice the height
+            // keeps the same visible floor, which is the point of weights.
+            minWeight: (UML_OPERAND_MIN_HEIGHT / geometry.plot.height) * total,
+        };
+        // Local writes until the release: the intermediate weights repaint the
+        // canvas but never reach the document, so the whole drag is ONE undo step.
+        this.model.stash('operands');
+    }
+    _onDragMove(e) {
+        const drag = this._drag;
+        if (!drag)
+            return;
+        // The travel SINCE the drag started, in view pixels (`e.delta` is the step
+        // since the last move, which is not the same thing), converted to model
+        // units. Always recomputed from the FROZEN pair rather than nudged: a nudge
+        // would accumulate the clamp and drift away from the pointer.
+        const dy = (e.y - e.start.y) / (this.gfx.viewport.zoom || 1);
+        const perUnit = drag.total / drag.plotHeight;
+        const above = drag.operands[drag.index - 1];
+        const below = drag.operands[drag.index];
+        const pair = above.size + below.size;
+        // The pair's total is invariant: the separator takes from one and gives to
+        // the other, so no operand the user is not touching changes size.
+        const wanted = above.size + dy * perUnit;
+        const floor = Math.min(drag.minWeight, pair / 2);
+        const nextAbove = Math.max(floor, Math.min(pair - floor, wanted));
+        this.model.operands = drag.operands.map((operand, i) => i === drag.index - 1
+            ? { ...operand, size: nextAbove }
+            : i === drag.index
+                ? { ...operand, size: pair - nextAbove }
+                : operand);
+    }
+    _onDragEnd() {
+        const drag = this._drag;
+        this._drag = null;
+        if (!drag)
+            return;
+        // Before the commit, not after: `pop` writes straight into the Y.Map, and
+        // without a boundary here a separator moved within half a second of the
+        // previous edit would be undone together with it.
+        this.gfx.std.store.captureSync();
+        this.model.pop('operands');
+        this._disarm();
+    }
+}

package/dist/export.d.ts

@@ -0,0 +1,61 @@
+import type { UmlModel } from './model.js';
+/**
+ * The glue between the models and the two writers — what the interchange
+ * capabilities and the commands both call.
+ *
+ * Twenty lines and no cleverness, which is the point: there is ONE place that
+ * decides what several selected diagrams mean for each format, so the command
+ * and the registry cannot produce different bytes. The formats answer that
+ * question differently, and the difference is theirs rather than ours:
+ *
+ *  - **PlantUML renders one diagram per document.** `@startuml … @enduml` is a
+ *    picture; two of them in one file is two pictures, which every renderer in
+ *    the ecosystem handles by drawing them in sequence. So several diagrams are
+ *    several documents, concatenated.
+ *  - **XMI carries one model.** Four sheets of one architecture are four
+ *    packages of one `uml:Model`, not four files — and writing them as four
+ *    would lose the fact that a class on one sheet is the class on another.
+ *
+ * Pure: models in, a string and its warnings out. No `std`, no DOM, no clock —
+ * `docs/adr/0012` P3.
+ */
+/** A document, plus what the writer could not say about the drawing. */
+export interface UmlExportResult {
+    text: string;
+    /**
+     * One line each, in the user's words, deduplicated.
+     *
+     * Deduplicated because the warnings are a SENTENCE about a kind of loss, not
+     * a row per element: three untyped connectors on one board produce one line
+     * telling the author what to do about all three. A per-element list would need
+     * names the exporter does not have (a connector has no name) and would read as
+     * a stack trace.
+     */
+    warnings: string[];
+}
+export interface UmlExportOptions {
+    /** The name the document takes — the board's title, already sanitized. */
+    name?: string;
+}
+/**
+ * The diagrams as PlantUML — one `@startuml … @enduml` document each.
+ *
+ * Takes no name, where the XMI writer does: a PlantUML `title` is the DIAGRAM's
+ * own heading — `class Orders`, the frame tag of Annex A — and the file's name
+ * is a different fact about a different thing. Overriding one with the other
+ * would drop the kind tag, which is the half of the heading a `.puml` has
+ * nowhere else to put.
+ *
+ * No diagram is not an error: it is a selection nobody made a statement with,
+ * and the honest answer is the smallest document that still parses. The same
+ * reading `exportC4Mermaid` gives an empty board.
+ */
+export declare function exportUmlPlantuml(models: readonly UmlModel[]): UmlExportResult;
+/**
+ * The diagrams as one XMI document — one `uml:Model`, one package per diagram.
+ *
+ * The caller's `name` names the MODEL rather than any package, because that is
+ * what it is: the document's own name, the board title the user exported under.
+ * Each package keeps the name of the diagram it was drawn as.
+ */
+export declare function exportUmlXmi(models: readonly UmlModel[], options?: UmlExportOptions): UmlExportResult;

package/dist/export.js

@@ -0,0 +1,41 @@
+import { exportPlantuml } from './plantuml.js';
+import { exportXmi } from './xmi.js';
+/** Every warning the models collected, in order, without repeats. */
+function warningsOf(models) {
+    return [...new Set(models.flatMap(model => model.warnings))];
+}
+/**
+ * The diagrams as PlantUML — one `@startuml … @enduml` document each.
+ *
+ * Takes no name, where the XMI writer does: a PlantUML `title` is the DIAGRAM's
+ * own heading — `class Orders`, the frame tag of Annex A — and the file's name
+ * is a different fact about a different thing. Overriding one with the other
+ * would drop the kind tag, which is the half of the heading a `.puml` has
+ * nowhere else to put.
+ *
+ * No diagram is not an error: it is a selection nobody made a statement with,
+ * and the honest answer is the smallest document that still parses. The same
+ * reading `exportC4Mermaid` gives an empty board.
+ */
+export function exportUmlPlantuml(models) {
+    if (models.length === 0) {
+        return { text: '@startuml\n@enduml\n', warnings: [] };
+    }
+    return {
+        text: models.map(model => exportPlantuml(model)).join('\n'),
+        warnings: warningsOf(models),
+    };
+}
+/**
+ * The diagrams as one XMI document — one `uml:Model`, one package per diagram.
+ *
+ * The caller's `name` names the MODEL rather than any package, because that is
+ * what it is: the document's own name, the board title the user exported under.
+ * Each package keeps the name of the diagram it was drawn as.
+ */
+export function exportUmlXmi(models, options = {}) {
+    return {
+        text: exportXmi(models, options),
+        warnings: warningsOf(models),
+    };
+}

package/dist/filename.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A name a file system will accept, minus the extension.
+ *
+ * The same transformations `c4SafeFilename` and `bpmnSafeFilename` apply, and
+ * for the same reasons — reserved characters become `-`, whitespace runs
+ * collapse, the result is capped, and the Windows tail of dots and spaces is
+ * trimmed AFTER the cap so the extension is not the thing that gets eaten.
+ *
+ * Duplicated rather than imported, which is the trade the two packs before this
+ * one made explicitly: a filename rule is not API, and coupling three frameworks
+ * so they can share eight lines buys nothing and costs a shared thing to break.
+ *
+ * `fallback` is a parameter here where the other two hard-code theirs, because
+ * UML writes two formats out of one pack and the word a nameless document should
+ * take is the FORMAT's rather than the framework's.
+ */
+export declare function umlSafeFilename(raw: string | undefined, fallback?: string): string;

package/dist/filename.js

@@ -0,0 +1,26 @@
+/**
+ * A name a file system will accept, minus the extension.
+ *
+ * The same transformations `c4SafeFilename` and `bpmnSafeFilename` apply, and
+ * for the same reasons — reserved characters become `-`, whitespace runs
+ * collapse, the result is capped, and the Windows tail of dots and spaces is
+ * trimmed AFTER the cap so the extension is not the thing that gets eaten.
+ *
+ * Duplicated rather than imported, which is the trade the two packs before this
+ * one made explicitly: a filename rule is not API, and coupling three frameworks
+ * so they can share eight lines buys nothing and costs a shared thing to break.
+ *
+ * `fallback` is a parameter here where the other two hard-code theirs, because
+ * UML writes two formats out of one pack and the word a nameless document should
+ * take is the FORMAT's rather than the framework's.
+ */
+export function umlSafeFilename(raw, fallback = 'diagram') {
+    const safe = (raw ?? '')
+        .trim()
+        .replaceAll(/[\\/:*?"<>|]/g, '-')
+        .replaceAll(/\s+/g, ' ')
+        .trim()
+        .slice(0, 120)
+        .replace(/[. ]+$/, '');
+    return safe || fallback;
+}

package/dist/frame-tag.d.ts

@@ -0,0 +1,70 @@
+import type { BackgroundRect, ElementRenderer, FrameworkBackgroundDef } from '@formicoidea/labre-core/blocks/surface';
+import type { GfxPrimitiveElementModel } from '@formicoidea/labre-core/std/gfx';
+/**
+ * The cut-corner heading tag of UML 2.5.1 Annex A, as a DECORATOR over a
+ * framework-background renderer.
+ *
+ * ## Why a decorator and not a new field of the declaration language
+ *
+ * The background primitive draws cards, bands, washes, zones, axes and labels.
+ * The pentagon Annex A pins to the top-left corner of every diagram frame is
+ * none of those: it is one shape, in one notation, and teaching
+ * `FrameworkBackgroundDef` to describe a polygon with a bitten corner would put
+ * a UML-shaped hole in a language six other frameworks share. So the frame keeps
+ * declaring its band and its label exactly like every other background, and this
+ * wrapper adds the outline after the fact — the same seam the BPMN pool's lane
+ * separators and the C4 node's glyphs use, one level up.
+ *
+ * The tag carries NO words of its own. The heading is drawn by the declaration,
+ * from the declaration's anchor, in the declaration's font; this file only
+ * measures it and draws a box round it. A tag that wrote its own text would be
+ * the same string painted twice, by two files, which is how a heading comes to
+ * be drawn in one place and clicked in another.
+ *
+ * ## The matrix trap
+ *
+ * `createFrameworkBackgroundRenderer` composes the element-local frame by
+ * MUTATING the matrix it is handed (`matrix.translateSelf(...).rotateSelf(...)`)
+ * and then calls `setTransform` with it. Reading the matrix after the base has
+ * run therefore yields a frame that has already been translated and rotated
+ * once, and composing on top of it rotates the tag twice — which is invisible on
+ * an upright frame and wildly wrong on a rotated one. The copy below is taken
+ * BEFORE the base renderer is called, which is the same precaution
+ * `gfx/c4/src/node/node-renderer.ts` documents for the shape renderer.
+ */
+export interface UmlFrameTagOptions {
+    /**
+     * The model prop the heading is read from — the same one the declaration's
+     * band label binds, so the tag measures the string that is actually painted.
+     */
+    prop: string;
+    /** The band the tag is drawn in: the frame's top margin. */
+    bandHeight: number;
+    /** How much shorter than the band the tag is — the air under it. */
+    foot: number;
+    /** Horizontal padding either side of the measured heading. */
+    padding: number;
+    /** The bite out of the bottom-right corner. */
+    cut: number;
+    /** Ink and weight of the outline — the frame's own. */
+    stroke: string;
+    lineWidth: number;
+}
+/**
+ * The tag's box, in ELEMENT-LOCAL model units — everything but the corner bite.
+ *
+ * Split out and exported so the geometry can be asserted without a canvas, and
+ * so a future gesture (aim at the tag, not at the band) has one place to ask.
+ * `null` when there is nothing to draw: a frame dragged to nothing, or a heading
+ * of no words at all.
+ */
+export declare function umlFrameTagRect(width: number, height: number, textWidth: number, opts: UmlFrameTagOptions): BackgroundRect | null;
+/**
+ * Wrap a frame declaration's renderer so the heading is drawn inside Annex A's
+ * pentagon.
+ *
+ * Stroke only, in the frame's own ink: the tag is an outline pinned to the
+ * sheet's corner, and filling it would hide the card behind the words — which
+ * matters the moment a user drags an element under the heading.
+ */
+export declare function withUmlFrameTag<T extends GfxPrimitiveElementModel>(def: FrameworkBackgroundDef, opts: UmlFrameTagOptions): ElementRenderer<T>;