@formicoidea/labre-framework-uml 0.42.0

package/dist/morph.d.ts

@@ -0,0 +1,178 @@
+import { type MorphSpec } from '@formicoidea/labre-core/blocks/surface';
+import { UmlNodeElementModel, type UmlNodeKind } from '@formicoidea/labre-core/model';
+import type { GfxPrimitiveElementModel } from '@formicoidea/labre-core/std/gfx';
+/**
+ * What a UML artefact may BECOME — the declaration behind the "Change type"
+ * dropdown on a selected component's contextual toolbar.
+ *
+ * ## Six families, and the kinds that are alone
+ *
+ * A class, an interface and an enumeration are THE SAME PICTURE: §9.5.4 draws
+ * one divided rectangle for all three and tells them apart by the keyword
+ * written above the name — `«interface»`, `«enumeration»`, nothing at all. That
+ * is the strongest statement of "the same artefact, said more precisely" any
+ * notation in this library makes.
+ *
+ * Phase 2 adds the second, and it is the same statement in a different clause:
+ * a **node**, a **device** and an **execution environment** are ONE 3D box
+ * (§19.4.4), told apart by `«device»` / `«executionEnvironment»` above the name
+ * and by nothing else. A deployment diagram is drawn coarse and then made
+ * precise — "this runs on a server", then "on that server's application
+ * container" — so the swap is the modelling act itself rather than a repair.
+ *
+ * Everything else is declared alone, and each singleton is a REFUSAL written
+ * down rather than an omission to be discovered later:
+ *
+ *  - an **object** is an InstanceSpecification (§11.6), a thing that exists at
+ *    run time. A class is a type. Offering the swap would invite a diagram that
+ *    confuses the two levels, and its name compartment is `object : Class`
+ *    underlined — different words as well as a different meaning;
+ *  - a **package** is a namespace (§12.2), not a classifier in it;
+ *  - a **note** is a Comment (Annex A) and carries no semantics at all;
+ *  - an **actor** and a **use case** belong to a behaviour diagram (§18.1) and
+ *    are not structural classifiers;
+ *  - a **component** is a Class (§11.6) and would in principle join the first
+ *    family, but it is the one classifier the notation draws with a MARK of its
+ *    own — the two-tab icon in the corner — rather than with a keyword, and a
+ *    component diagram is a different conversation from a class diagram. Left
+ *    alone until a PO asks for the swap;
+ *  - an **artifact** is a physical file (§19.3) — a `.war`, a script, a
+ *    document. Offering to turn one into a class would invite a diagram that
+ *    confuses what a thing IS with what it is deployed AS, which is the very
+ *    distinction the `«manifest»` arrow exists to draw;
+ *  - a **port** is a property of its owner (§11.3), not a classifier standing
+ *    beside it, and it is the only artefact in the pack whose position is part
+ *    of its meaning: it sits ON a border;
+ *  - a **provided interface** and a **required interface** are the ball and the
+ *    socket of §10.4.4 — two DIFFERENT drawings, unlike every family above, and
+ *    a phase-2 pack should not decide by itself that a modeller who drew one
+ *    meant the other. The pair is the obvious candidate for a third family and
+ *    is deliberately left for a product decision.
+ *
+ * The declaration is therefore TOTAL over `UmlNodeKind` — every kind is named
+ * exactly once — which is what lets the unit suite prove that a kind added to
+ * the pack cannot be silently left out of this decision. The MENU is a different
+ * question, and {@link UML_MORPH_SPEC} answers it: a family of one has nothing
+ * to offer, so it is not offered.
+ *
+ * Families are DATA. Nothing derives them, and the role tree would have been the
+ * wrong source in the same way it is for BPMN and C4: `roleIsA` makes
+ * `uml:interface` a `uml:classifier` and thence reaches `uml:class`, but it says
+ * nothing about whether a reader would ACCEPT the swap — which is the only
+ * question this table answers.
+ */
+export declare const UML_MORPH_FAMILIES: readonly (readonly UmlNodeKind[])[];
+/**
+ * The `umlNode` shape a selected GROUP is the component of — `undefined` when
+ * the group is not one.
+ *
+ * A UML artefact is a native `group` holding the shape and its tiers of words
+ * (`actions.ts`), so what a click selects is the group and what carries `kind`
+ * is the shape. This is the whole of the indirection, and it is also the gate: a
+ * plain group somebody lassoed round three rectangles, a C4 component (a group
+ * of a shape and three lines) and a group of two UML classifiers all answer
+ * `undefined`, so none of them is ever offered the menu.
+ *
+ * TWO shapes is a refusal rather than a first-wins pick. A group holding two
+ * classifiers is a group somebody made of two classifiers — morphing "it" would
+ * mean picking one of them by document order, and the honest answer to an
+ * ambiguous selection is the same one the generic module gives to a mixed
+ * family: nothing.
+ *
+ * ## Why this is not `component.ts`'s `umlNodeOfComponent`
+ *
+ * Because that one answers a different question with a different vocabulary: it
+ * takes a RESOLVED `UmlComponent` — the pure, Yjs-free shape the exporter
+ * and the renderer build out of ids and roles — and reads a field off it. This
+ * one takes a live model and walks `childElements`, because that is what the
+ * toolbar hands over and `instanceof` is what makes the refusals above real. The
+ * two are deliberately not merged: one is the pure half of the pack and must
+ * stay free of the model classes, and this one exists to touch them.
+ */
+export declare function umlNodeOfGroup(model: GfxPrimitiveElementModel): UmlNodeElementModel | undefined;
+/**
+ * What a name compartment should say once its shape has morphed — or `null` when
+ * nothing about it is the notation's to change.
+ *
+ * ## Two rewrites, and the one rule they share
+ *
+ * The rule is the same for both and it is deliberately timid: rewrite ONLY what
+ * the notation itself wrote, and never what an author typed. A morph is not
+ * allowed to take away words somebody put on the picture.
+ *
+ * - **The keyword line.** `«interface»` is not a name, it is what makes the same
+ *   rectangle mean a different metaclass (§9.5.4) — so a class morphed to an
+ *   interface that kept an unmarked name compartment would be an interface drawn
+ *   exactly as a class, which is to say not drawn at all. The SOURCE kind's own
+ *   keyword is dropped and the target's is put in its place; a first line an
+ *   author wrote themselves (`«service»`, `«entity»` — Annex C is explicit that
+ *   not every word in guillemets is a keyword) is not the source kind's, so it
+ *   survives and the new keyword is written above it.
+ * - **The name.** Placeholder→placeholder and nothing else: the name is
+ *   rewritten only when it is EXACTLY the source kind's own seed, which is what
+ *   a classifier nobody has named still carries. A class called `Payments` is
+ *   called that whatever keyword it ends up wearing, which is the PO's "the
+ *   label is intact" for every name that is real content.
+ *
+ * Pure and total over every string, because the input is a canvas text element
+ * somebody may have typed anything into.
+ */
+export declare function umlMorphedName(from: UmlNodeKind, to: UmlNodeKind, rawText: string | null | undefined): string | null;
+/**
+ * UML's morph declaration, handed to the generic `morphToolbarConfig`.
+ *
+ * `modelType` is the native `GroupElementModel` and not `UmlNodeElementModel`,
+ * because the group is what a click on a component selects. Everything that
+ * makes that safe is in {@link umlNodeOfGroup}: the toolbar's own homogeneity
+ * test only proves that every selected element is A group, and the resolution
+ * proves that every one of them is one of OURS.
+ *
+ * `propsOf` is the shipped creation builder minus `type` / `xywh` / `text`
+ * ({@link umlMorphProps}), so the toolbox and the morph cannot disagree about
+ * what an interface looks like; `clearOf` is empty on today's table and derived
+ * rather than assumed so (`presets.ts`).
+ */
+export declare const UML_MORPH_SPEC: MorphSpec<UmlNodeKind>;
+/**
+ * The SAME dropdown, on a UML shape that is not inside a group.
+ *
+ * ## Why a second spec exists at all
+ *
+ * Because phase 2 made the pack's own rule about composites untrue for a third
+ * of its artefacts. Until then every UML artefact was a `group` — a shape and
+ * the canvas texts grouped with it — so `modelType: GroupElementModel` was the
+ * whole selection filter. The behaviour vocabulary is not: §15.3.4 and §14.2.4
+ * name none of their routing marks, so a bullseye, a bar, a diamond and a
+ * crossed circle are created as the SHAPE alone (`actions.ts`), and what a
+ * click selects for them is a `umlNode`, never a group.
+ *
+ * `umlNodeOfGroup` refuses a bare shape by design — it is the gate that keeps a
+ * plain lasso and another framework's component out of the menu — so the group
+ * spec resolves nothing for them and three whole families (`activity-final` /
+ * `flow-final`, `shallow-history` / `deep-history`, `entry-point` /
+ * `exit-point`) had a dropdown nobody could ever open.
+ *
+ * ## Why not one spec with a widened `modelType`
+ *
+ * Because the selection filter is not the only thing that differs: the two
+ * specs are registered under two DIFFERENT toolbar flavours. A bare `umlNode`'s
+ * contextual row is `affine:surface:umlNode`'s (the widget derives the flavour
+ * from `model.type`), and a grouped artefact's is `affine:surface:group`'s.
+ * Widening `modelType` to the abstract base would leave the group registration
+ * answering for shapes it will never be handed, and would make its homogeneity
+ * gate — the thing that refuses a group holding two classifiers — apply to a
+ * selection it was not written about. Two registrations, two keys, one table.
+ *
+ * Everything that decides what the menu SAYS and what a pick WRITES is shared
+ * with {@link UML_MORPH_SPEC} by reference, so the two can never offer
+ * different families or write different props.
+ *
+ * `resolveTarget` is absent, which is identity: a bare mark is one element —
+ * what the user selects, what carries the kind and what the patch lands on are
+ * the same object, exactly as they are for a connector. `afterMorph` is absent
+ * too, and that is the notation's doing rather than an omission: `rewriteName`
+ * exists to keep a `uml:name` tier saying what the shape now is, and these
+ * kinds have no tier at all — there is nothing to rewrite, and reaching for one
+ * would be looking for words the specification says are not there.
+ */
+export declare const UML_BARE_MORPH_SPEC: MorphSpec<UmlNodeKind>;