@formicoidea/labre-framework-uml 0.42.0

package/dist/roles.d.ts

@@ -0,0 +1,257 @@
+import type { UmlNodeKind } from '@formicoidea/labre-core/model';
+import type { RoleDefs, RoleId } from '@formicoidea/labre-core/std/gfx';
+/**
+ * UML role vocabulary.
+ *
+ * A role is the semantic identity of a UML artefact, and here — as in C4 — it is
+ * the only thing that carries it. Four of the sixteen node kinds are drawn as
+ * the SAME rectangle: a class, an interface, an enumeration and an object differ by
+ * the keyword written above the name, and a rule that read the shape would find
+ * a box and learn nothing. The `kind` discriminant answers a different question
+ * (which glyph to paint, which compartments to lay out); the role answers what
+ * the box MEANS.
+ *
+ * Hierarchy is DATA (`parent`), never TS inheritance, and only where UML 2.5.1
+ * itself makes the statement.
+ *
+ * ## The three specialisation chains, and why there are only three
+ *
+ * **`uml:classifier`** is the spec's own generalisation: §9.2 makes Class,
+ * Interface and DataType (of which Enumeration is one) all Classifiers, and the
+ * notation follows — the compartmented rectangle of §11.4.4 is drawn identically
+ * for the three, with the keyword line as the discriminator. So a rule written
+ * about "classifiers must be named" reaches all three for free through
+ * `roleIsA`.
+ *
+ * `uml:object` is deliberately NOT under it. An object is an
+ * InstanceSpecification (§9.8) — it is an INSTANCE of a classifier, not a kind
+ * of one — and filing it in the chain would make every rule about classifiers
+ * fall on instances, which is the opposite of what the spec says. It shares the
+ * rectangle and nothing else, which is exactly the trap this vocabulary exists
+ * to avoid.
+ *
+ * **`uml:association`** is the second, and it is §11.5.4: aggregation and
+ * composition ARE associations — the same solid line, with a diamond at the
+ * whole's end saying which flavour of part-of it is. `aggregationKind` is a
+ * property of an association end in the metamodel, not a different relationship,
+ * so a rule about associations must reach both.
+ *
+ * Generalization, realization, dependency, include and extend are FLAT, and not
+ * children of the association either. They are different metaclasses drawn with
+ * different lines (§9.9.4, §10.4.4, §7.8.4, §18.1.4) — a generalization is not a
+ * kind of association, and an include is not a kind of dependency for our
+ * purposes even though the metamodel derives it from DirectedRelationship:
+ * flattening what the reader sees as four distinct notations would let one rule
+ * silently police all of them.
+ *
+ * `uml:anchor` is the note attachment of Annex A — the dotted line that ties a
+ * comment to what it comments on. Flat, verbless and undirected.
+ *
+ * **`uml:node`** is the third, and it arrived with the deployment artefacts of
+ * phase 2. §19.4 derives both Device and ExecutionEnvironment from Node, and the
+ * notation follows: all three are the same 3-D cube, told apart by a keyword
+ * (`«device»`, `«executionEnvironment»`). So a rule written about what may be
+ * deployed on a node reaches the three for free.
+ *
+ * It differs from `uml:classifier` in one respect, and the difference is the
+ * spec's own: a Node is INSTANTIABLE, so unlike the abstract classifier this
+ * parent is ALSO stamped on elements — `kind: 'node'` maps onto it. A role that
+ * is both a parent and a drawing is unusual in this library, and it is exactly
+ * what §19.4 describes.
+ *
+ * The other phase-2 artefacts are flat, and each for a stated reason.
+ * `uml:component` is a structured Classifier in the metamodel (§11.6) and stays
+ * OUT of `uml:classifier` all the same: the notation draws it as its own figure
+ * — the two-tabbed icon of §11.6.4 — and the class-diagram rules written on
+ * classifiers (a name compartment, features, visibility) are not the sentences a
+ * component diagram is audited by. `uml:artifact` is flat for the reason
+ * `uml:object` is: it is a physical file, not a kind of anything else drawn
+ * here. `uml:port`, `uml:provided-interface` and `uml:required-interface` are
+ * parts and glyphs attached to a component (§11.3.4, §10.4.4), not
+ * specialisations of it.
+ *
+ * `uml:communication-path` is FLAT under nothing, and that is the one place this
+ * file knowingly departs from the metamodel: §19.4 derives CommunicationPath
+ * from Association. The same call the file already makes for include and extend,
+ * which the metamodel derives from DirectedRelationship — what a reader sees is
+ * a DIFFERENT NOTATION between different things (a line between two cubes, not
+ * between two classifiers), and filing it under the association would hand every
+ * class-diagram association rule a deployment diagram to police. Recorded here
+ * rather than left to be rediscovered.
+ *
+ * **`uml:control-node`** and **`uml:pseudostate`** are the fourth and fifth,
+ * and they arrived with the behaviour artefacts of phase 2. §15.3.4 groups the
+ * five shapes that ROUTE an activity's flow (initial, activity final, flow
+ * final, decision, fork) under ControlNode, and §14.2.4 groups the seven that
+ * route a state machine's transitions (choice, junction, the two histories,
+ * entry and exit points, terminate) under Pseudostate. Both parents are
+ * ABSTRACT — stamped on nothing, like `uml:classifier` and unlike `uml:node` —
+ * because the sentences they exist for ("carries no name", "is never where the
+ * machine rests") are true of all of them and of none of them in particular.
+ *
+ * `uml:initial` is filed under `uml:control-node` because §15.3.4 puts it
+ * there, and it is ALSO the role a state machine's initial pseudostate carries:
+ * §14.2.4 draws the identical filled disc and means the identical thing by it.
+ * That cross-family reading is deliberate — one rule, `uml.initial-single`,
+ * then polices both diagrams — and it is recorded on the def so nobody later
+ * "fixes" it by splitting the two.
+ *
+ * `uml:action` and `uml:state` are FLAT, and pointedly not each other's
+ * relatives although both are drawn as a round-cornered rectangle: an action is
+ * work that happens, a state is a condition that holds. `uml:object-node` is
+ * flat for the reason `uml:object` is, and is not the same role as it: an
+ * instance specification and a value flowing between actions are different
+ * metaclasses sharing a rectangle. `uml:final-state` is flat and drawn exactly
+ * like `uml:activity-final`, kept apart because a rule about one must never be
+ * handed the other.
+ *
+ * ## The frames
+ *
+ * `uml:diagram`, `uml:subject`, `uml:partition` (the swimlane of §15.6.4) and
+ * `uml:region` (the composite state of §14.2.4) are parent-less, the same call
+ * `c4:board`,
+ * `wardley:map` and `bpmn:pool` all make: they are the FRAME the elements are
+ * drawn in and drawn round, and a rule written on the artefacts must never fall
+ * on the sheet holding them. They are declared `kind: 'node'` for the same
+ * reason `c4:board` is — a frame is measured by its bounds — and
+ * `packages/affine/all/src/__tests__/reading-coverage.unit.spec.ts` records both
+ * as frames so that the reading-profile coverage test does not ask a sheet to
+ * read itself back as a sentence.
+ *
+ * ## Compatibility
+ *
+ * Nothing is backfilled. A diagram drawn before today carries no role, so it is
+ * never evaluated and never says a word (PRD principle 8).
+ */
+/** Every role this framework declares. */
+export type UmlRole = 'classifier' | 'class' | 'interface' | 'enumeration' | 'object' | 'package' | 'note' | 'actor' | 'use-case' | 'component' | 'port' | 'provided-interface' | 'required-interface' | 'artifact' | 'node' | 'device' | 'execution-environment' | 'control-node' | 'action' | 'initial' | 'activity-final' | 'flow-final' | 'decision' | 'fork' | 'object-node' | 'send-signal' | 'accept-event' | 'time-event' | 'state' | 'final-state' | 'pseudostate' | 'choice' | 'junction' | 'shallow-history' | 'deep-history' | 'entry-point' | 'exit-point' | 'terminate' | 'lifeline' | 'execution' | 'destruction' | 'name' | 'attributes' | 'operations' | 'label' | 'lifeline-ident' | 'diagram' | 'subject' | 'partition' | 'region' | 'fragment' | 'operand' | 'association' | 'aggregation' | 'composition' | 'generalization' | 'realization' | 'dependency' | 'anchor' | 'include' | 'extend' | 'deploy' | 'manifest' | 'communication-path' | 'control-flow' | 'object-flow' | 'transition' | 'message' | 'message-sync' | 'message-async' | 'message-reply' | 'message-create' | 'message-delete';
+export type UmlRoleId = `uml:${UmlRole}`;
+/**
+ * Role ids, keyed by their own name.
+ *
+ * Keyed by the ROLE and not by the `kind`: UML has thirty-eight node kinds and
+ * forty-one node roles, because `uml:classifier`, `uml:control-node` and
+ * `uml:pseudostate` are parents nothing is ever drawn as. ({@link
+ * UML_ROLE.node} is a parent too, and IS drawn — §19.4 makes a Node
+ * instantiable — so it does not add a role of its own.)
+ * {@link UML_ROLE_OF_KIND} is the bridge, and it is the only place the two
+ * vocabularies meet.
+ */
+export declare const UML_ROLE: {
+    readonly classifier: "uml:classifier";
+    readonly class: "uml:class";
+    readonly interface: "uml:interface";
+    readonly enumeration: "uml:enumeration";
+    readonly object: "uml:object";
+    readonly package: "uml:package";
+    readonly note: "uml:note";
+    readonly actor: "uml:actor";
+    readonly 'use-case': "uml:use-case";
+    readonly component: "uml:component";
+    readonly port: "uml:port";
+    readonly 'provided-interface': "uml:provided-interface";
+    readonly 'required-interface': "uml:required-interface";
+    readonly artifact: "uml:artifact";
+    readonly node: "uml:node";
+    readonly device: "uml:device";
+    readonly 'execution-environment': "uml:execution-environment";
+    readonly 'control-node': "uml:control-node";
+    readonly action: "uml:action";
+    readonly initial: "uml:initial";
+    readonly 'activity-final': "uml:activity-final";
+    readonly 'flow-final': "uml:flow-final";
+    readonly decision: "uml:decision";
+    readonly fork: "uml:fork";
+    readonly 'object-node': "uml:object-node";
+    readonly 'send-signal': "uml:send-signal";
+    readonly 'accept-event': "uml:accept-event";
+    readonly 'time-event': "uml:time-event";
+    readonly state: "uml:state";
+    readonly 'final-state': "uml:final-state";
+    readonly pseudostate: "uml:pseudostate";
+    readonly choice: "uml:choice";
+    readonly junction: "uml:junction";
+    readonly 'shallow-history': "uml:shallow-history";
+    readonly 'deep-history': "uml:deep-history";
+    readonly 'entry-point': "uml:entry-point";
+    readonly 'exit-point': "uml:exit-point";
+    readonly terminate: "uml:terminate";
+    readonly lifeline: "uml:lifeline";
+    readonly execution: "uml:execution";
+    readonly destruction: "uml:destruction";
+    readonly name: "uml:name";
+    readonly attributes: "uml:attributes";
+    readonly operations: "uml:operations";
+    readonly label: "uml:label";
+    readonly 'lifeline-ident': "uml:lifeline-ident";
+    readonly diagram: "uml:diagram";
+    readonly subject: "uml:subject";
+    readonly partition: "uml:partition";
+    readonly region: "uml:region";
+    readonly fragment: "uml:fragment";
+    readonly operand: "uml:operand";
+    readonly association: "uml:association";
+    readonly aggregation: "uml:aggregation";
+    readonly composition: "uml:composition";
+    readonly generalization: "uml:generalization";
+    readonly realization: "uml:realization";
+    readonly dependency: "uml:dependency";
+    readonly anchor: "uml:anchor";
+    readonly include: "uml:include";
+    readonly extend: "uml:extend";
+    readonly deploy: "uml:deploy";
+    readonly manifest: "uml:manifest";
+    readonly 'communication-path': "uml:communication-path";
+    readonly 'control-flow': "uml:control-flow";
+    readonly 'object-flow': "uml:object-flow";
+    readonly transition: "uml:transition";
+    readonly message: "uml:message";
+    readonly 'message-sync': "uml:message-sync";
+    readonly 'message-async': "uml:message-async";
+    readonly 'message-reply': "uml:message-reply";
+    readonly 'message-create': "uml:message-create";
+    readonly 'message-delete': "uml:message-delete";
+};
+/**
+ * i18n key stem of a role id: `uml:class` → `com.labre.uml.role.class`.
+ *
+ * Exported because the creation sites seed an artefact's NAME from the same key
+ * a role labels itself with (a diagram drawn in a French host should not be
+ * called "Diagram"): one key for the role and for the seed, because they are the
+ * same noun and a host must not be asked to word it twice.
+ */
+export declare const umlRoleKey: (local: string) => string;
+/** The diagram frame's own key, read by `createUmlDiagram` to seed its name. */
+export declare const umlDiagramRoleKey: string;
+/** The subject's own key, read by `createUmlSubject` to seed its name. */
+export declare const umlSubjectRoleKey: string;
+/** The partition's own key, read by `createUmlPartition` to seed its name. */
+export declare const umlPartitionRoleKey: string;
+/** The composite state's own key, read by `createUmlRegion` to seed its name. */
+export declare const umlRegionRoleKey: string;
+/**
+ * The combined fragment's own key.
+ *
+ * Unlike the four above it seeds NO name — §17.6.4 writes a guard only where
+ * there is one, so `UmlFragmentElementModel.name` starts empty — and the key is
+ * exported for the toolbar and the templates, which still have to call the
+ * thing something in the user's language.
+ */
+export declare const umlFragmentRoleKey: string;
+export declare const UML_ROLES: RoleDefs;
+/**
+ * The `kind` discriminant → the role it means.
+ *
+ * `kind` drives the renderer and is what the palette writes; the ROLE is the
+ * semantic authority. The two are posted side by side at every creation site,
+ * the way C4, BPMN and Wardley already do it, and this table is the single place
+ * that says which kind means which role. Total over {@link UmlNodeKind} by its
+ * type, so a new kind cannot land without being given a meaning.
+ *
+ * One kind, one role, with none collapsed — unlike C4, where four kinds are a
+ * second DRAWING of a level. Here the thirty-eight kinds are thirty-eight
+ * different artefacts of the specification, and the three roles with no kind of
+ * their own — `uml:classifier`, `uml:control-node`, `uml:pseudostate` — are
+ * ancestors rather than any of them.
+ */
+export declare const UML_ROLE_OF_KIND: Record<UmlNodeKind, RoleId>;