@formicoidea/labre-framework-uml 0.42.0

package/dist/background.d.ts

@@ -0,0 +1,153 @@
+import type { FrameworkBackgroundDef } from '@formicoidea/labre-core/blocks/surface';
+/**
+ * The four UML frames, DECLARED (the `FrameworkBackgroundDef` primitive): the
+ * diagram sheet of Annex A, the use case subject of §18.1.4, the activity
+ * partition of §15.6.4 (in its two orientations) and the composite state of
+ * §14.2.4.
+ *
+ * There is no UML drawing code for either of them: the primitive paints these
+ * declarations, and would paint any other framework's the same way
+ * (`docs/adr/0009` on why a framework declares rather than draws). The ONE thing
+ * UML asks for that the primitive has no vocabulary for — the cut-corner heading
+ * tag of Annex A — is a decorator over the renderer these produce, and it lives
+ * in `frame-tag.ts` rather than in a new field of the declaration language.
+ */
+/**
+ * The UML diagram frame: a white card with a square border and a heading band
+ * across its top.
+ *
+ * **No axes and no zones**, like the C4 board this is modelled on and for the
+ * same reason: a UML diagram is a GRAPH. A class drawn top left says nothing
+ * more than one drawn bottom right, and graduating the card would invent a frame
+ * of reference UML does not have — and then judge people against it.
+ *
+ * ## The heading is `heading`, not `name` — and that is the whole difference
+ *
+ * A C4 board writes its title, which is free text. Annex A writes `<kind>
+ * <name>`: a class diagram called Orders reads `class Orders`, and only the
+ * second word is the author's. So the label binds the model's DERIVED
+ * {@link UmlDiagramElementModel.heading} — the two halves joined — and the
+ * rename gesture writes `name` alone (`element-view.ts`). Binding `heading`
+ * directly would let an editor write the joined string back into a getter, which
+ * would either throw or, worse, re-prefix the kind on every rename.
+ *
+ * ## Why the band paints NOTHING
+ *
+ * It declares no fill and no divider, which is not an oversight: Annex A draws a
+ * frame as one rectangle with a tag in its corner, and a rule ruled across the
+ * sheet under the heading would be a line the notation does not have. The band
+ * exists to place the words and to reserve the top margin; what a reader SEES
+ * there is the tag, and what a user AIMS at is the tag — which is the affordance
+ * the C4 board needed its painted strip for.
+ *
+ * The model's own carve-out (`UmlDiagramElementModel.includesPoint`) still picks
+ * the whole band, so a click anywhere along the top margin selects the sheet
+ * rather than falling through to the canvas. That is deliberately WIDER than
+ * what is painted, and it is the one place the two disagree: the alternative is
+ * a frame whose corner tag is the only selectable part of a 44-unit strip that
+ * is plainly part of the sheet.
+ */
+export declare const UML_DIAGRAM_FRAME: FrameworkBackgroundDef;
+/**
+ * The use case SUBJECT (§18.1.4): a plain rectangle with its name written inside
+ * the top-left corner, drawn round the use cases a system offers.
+ *
+ * TRANSPARENT, like the C4 boundary and for the same reason: it is drawn OVER a
+ * diagram, round elements that are already there, and an opaque card would hide
+ * the very thing it is pointing at. So it declares a border and no fill, which
+ * the primitive paints as an unfilled frame — and the consequence is the reverse
+ * of the usual one: a subject dropped over existing use cases does NOT cover
+ * them, and is hit nowhere but on its own frame band and its name.
+ *
+ * SOLID, unlike that boundary, and this is where the two notations part company:
+ * C4's stencil dashes its boundary, §18.1.4 draws one unbroken rectangle. A dash
+ * here would say "logical grouping" in a notation where a subject is a
+ * SYSTEM — the thing whose behaviour the use cases are, with the actors
+ * deliberately outside it.
+ *
+ * The name is written TOP-left rather than the boundary's bottom-left: that is
+ * where the specification's figures put it, and it is also the corner a use case
+ * ellipse is least likely to reach into, ellipses having no corners of their own.
+ *
+ * No variant and no second tier: §18.1.4 gives the subject one rectangle and one
+ * name — no dashed flavour, no keyword line — so there is nothing here for a
+ * variant to select between.
+ */
+export declare const UML_SUBJECT_FRAME: FrameworkBackgroundDef;
+/** A VERTICAL partition — a column, its name written across the top. */
+export declare const UML_PARTITION_FRAME_V: FrameworkBackgroundDef;
+/** A HORIZONTAL partition — a row, its name written down the left edge. */
+export declare const UML_PARTITION_FRAME_H: FrameworkBackgroundDef;
+/**
+ * The declaration a partition element is painted and hit-tested by — the one
+ * place the `orientation` prop is turned into a picture.
+ *
+ * A function rather than a lookup repeated at each call site, so the renderer,
+ * the view and the band helpers cannot disagree about which of the two a lane
+ * is: all three ask this.
+ *
+ * An orientation this build has never heard of falls back to the VERTICAL
+ * declaration rather than painting nothing — the same promise
+ * `UmlDiagramElementModel.heading` makes about an unknown kind: a document
+ * written by a newer build still draws a lane.
+ */
+export declare function umlPartitionFrame(model: {
+    orientation?: string;
+}): FrameworkBackgroundDef;
+/**
+ * The COMPOSITE STATE (§14.2.4): the round-cornered rectangle drawn round the
+ * sub-states of a state that has a machine of its own inside it.
+ *
+ * Transparent, band on the top, and ROUNDED — which is the whole point of it.
+ * §14.2.4 draws every state with rounded corners, simple or composite, and a
+ * square frame round a sub-machine would read as a partition or as a subject.
+ * `surface.border.radius` is in MODEL UNITS here (the primitive draws the card
+ * in the units the element is), unlike the node preset's fractional `radius`,
+ * so the number comes from `UML_REGION_RADIUS` rather than from
+ * `UML_NODE_RADIUS`.
+ *
+ * ## One region, and the ceiling stated
+ *
+ * ORTHOGONAL regions — a composite state cut into concurrent regions by dashed
+ * separators (§14.2.4, Figure 14.8) — are not drawn. That is an INSTANCE
+ * PARTITION in the declaration language (`instanceZones`, the mechanism the
+ * BPMN pool's lanes use), and it arrives the day the notation is asked for
+ * rather than as a field added here in a hurry. See `UmlRegionElementModel`.
+ */
+export declare const UML_REGION_FRAME: FrameworkBackgroundDef;
+/**
+ * The COMBINED FRAGMENT (§17.6.4): the rectangle drawn round part of a
+ * conversation with `alt`, `loop` or `opt` in its corner — and, under the `ref`
+ * operator, §17.7.4's InteractionUse.
+ *
+ * TRANSPARENT, like the subject and the partition and for exactly the same
+ * reason: it is drawn over lifelines and messages that are already there, and
+ * an opaque card would hide the conversation it is qualifying. SOLID border,
+ * because §17.6.4 draws one unbroken rectangle — the only dashed lines in the
+ * picture are the ones BETWEEN the operands.
+ *
+ * ## The band paints nothing, like the diagram frame's
+ *
+ * And for the same reason: §17.6.4 draws the operator in Annex A's own
+ * cut-corner pentagon, and a rule ruled right across the fragment under it
+ * would be a line the notation does not have. The band exists to place the word
+ * and to reserve the top margin; what a reader sees is the pentagon, drawn by
+ * `withUmlFrameTag` over this declaration's own label — which is why the label
+ * binds `operator` and why the tag carries no words of its own.
+ *
+ * ## The guard, and the one contract the operands keep
+ *
+ * `name` is the guard of the fragment's FIRST operand — `[x > 0]`, `[else]` —
+ * or, under `ref`, the name of the interaction referred to. It is written in
+ * the plot's top-left corner, which is where §17.6.4 puts an operand's guard,
+ * and it is a declared ZONE label so the frame view's rename gesture reaches
+ * it exactly as it reaches the subject's name.
+ *
+ * Once the fragment is SPLIT, the guards live in `operands` and nowhere else:
+ * the instance-zone label below writes each operand's own, and the first of
+ * them occupies the very corner `name` is written in. The contract the "add
+ * operand" action keeps (`actions.ts`) is therefore that splitting a fragment
+ * MOVES `name` into `operands[0].name` and clears it — one guard, one place,
+ * and no corner with two strings in it.
+ */
+export declare const UML_FRAGMENT_FRAME: FrameworkBackgroundDef;