umlimator 0.19.0 → 0.21.0

package/lib/umlimator-element.js

@@ -15,8 +15,6 @@
    Events: the map's select, open and viewchange as umlimator:select, umlimator:open and umlimator:viewchange, the map's
    event as `detail` (preventDefault() on umlimator:open keeps the view); load each time the map is drawn, error (an
    ErrorEvent, whose message says why) when it can't be, a model with no view to draw too (its children show again).
-   shapes: "box", "c4" or "uml", the notation every view is drawn in (0.15.0; without it each view's own); changing it
-   draws the cards again in the map drawn, with nothing laid out again.
    `el.map` is render()'s handle once drawn (toSVG(), highlight(), setView(), state ...), else null; `el.loading` is true
    while a draw waits for its model, when el.map is still the map drawn last. An attribute set to the value it has draws
    nothing again. */
@@ -25,7 +23,7 @@ import { render } from './umlimator.js';
 const Base = globalThis.HTMLElement || class {}; // importable where there is no DOM (a docs site's server render)
 
 export class UmlimatorMap extends Base {
-  static observedAttributes = ['src', 'view', 'minimap', 'controls', 'wheel', 'height', 'shapes'];
+  static observedAttributes = ['src', 'view', 'minimap', 'controls', 'wheel', 'height'];
   map = null;
   #drawn = 0; #due = false; #src = null; #model = null; #loading = false;
 
@@ -40,7 +38,6 @@ export class UmlimatorMap extends Base {
   attributeChangedCallback(name, was, now) {
     if (was === now) return; // set to the value it has: nothing to draw again (0.14.0)
     if (name === 'height') this.style.height = now == null ? '' : /^\d+(\.\d+)?$/.test(now) ? now + 'px' : now;
-    else if (name === 'shapes' && this.map && !this.#loading) this.map.shapes = now || null; // the map drawn, in another notation: no new draw
     else this.#soon();
   }
   #soon() { // attributes set together draw once
@@ -81,7 +78,7 @@ export class UmlimatorMap extends Base {
       if (!this.dispatchEvent(new CustomEvent('umlimator:' + t, { detail: e, bubbles: true, composed: true, cancelable: t === 'open' }))) e.preventDefault();
     }]));
     try {
-      this.map = render(box, model, { view: get('view') || undefined, minimap: this.hasAttribute('minimap') && get('minimap') !== 'false', controls: get('controls') !== 'false', wheel: get('wheel') === 'ctrl' ? 'ctrl' : 'zoom', shapes: get('shapes') || undefined, on });
+      this.map = render(box, model, { view: get('view') || undefined, minimap: this.hasAttribute('minimap') && get('minimap') !== 'false', controls: get('controls') !== 'false', wheel: get('wheel') === 'ctrl' ? 'ctrl' : 'zoom', on });
     } catch (err) { return this.#fail(err); }
     if (this.map.view == null) return this.#fail(new Error(`${src || 'the inline model'}: the model has no view to draw`)); // drawn, with nothing to see: an error, not a load (0.14.0)
     this.#loading = false;

package/lib/umlimator.d.ts

@@ -18,15 +18,11 @@ export interface MapModel {
   stories?: Story[];
   /** Saved ways to look at the map (#94): handle.lens(id), the standalone page's Lenses menu and #lens=<id>. */
   lenses?: Lens[];
-  /** The notation every view's cards are drawn in (0.15.0; a view's own `shapes` wins). Default 'box'. */
-  shapes?: Notation;
   [key: string]: unknown;
 }
-/** How cards are drawn (0.15.0): box (every card a rounded box, the default), c4 (people, browser apps, phones, databases,
- *  queues and files as the C4 model's tools draw them) or uml (UML 2.5's actor, node, artifact, package and data store,
- *  and the component icon on a box). Each shape keeps to its card's box: the layout is the same in every notation. */
-export type Notation = 'box' | 'c4' | 'uml';
-/** A card's shape (0.15.0). */
+/** A card's shape (0.15.0). A map draws each card in one style (0.21.0; the box/c4/uml choice and `shapes` are gone):
+ *  by its kind (people, browser apps, phones, terminals, queues, packages, hosts, robots, data stores, files and hooks),
+ *  a rounded box where no shape says more. Each shape keeps to its card's box: the layout is the same as a box's. */
 export type Shape = 'box' | 'person' | 'browser' | 'mobile' | 'cylinder' | 'pipe' | 'document' | 'hexagon' | 'robot' | 'terminal' | 'window' | 'folder' | 'node';
 /** A badge: its text, and optionally a palette name for its colour (green, amber, rose, accent, violet ... : --um-<tone>). */
 export type Badge = string | { text: string; tone?: string };
@@ -40,7 +36,7 @@ export interface MapNode {
   opensCount?: number;
   /** Who owns the card (a team, say): selectors pick by it, and a lens with color 'owner' rings the card in its owner's tone. */
   owner?: string;
-  /** The card's own shape, in every notation (0.15.0); without it, the notation draws the card by its kind. */
+  /** The card's own shape (0.15.0); without it, a map draws the card by its kind. */
   shape?: Shape;
   /** In schema version 2 (0.17.0) a node may also be a typed Element: type, parent, props, members. */
   [key: string]: unknown;
@@ -48,8 +44,8 @@ export interface MapNode {
 /** A typed element in schema version 2's envelope (docs/diagrams/model.md §1): a node, a member, a typed edge, a
  *  fragment. Nodes, edges, members and fragments share one id space; an id never contains "->". A typed edge is an
  *  Element with `from` and `to`, which may name a member. A typed view is a MapView with `diagram` (uml.class), and may
- *  have `subject`, `direction` ('right' | 'down'), `notation`, `present`, `fragments` and `timeline`. umlimator/all draws `uml.class` (0.18.0), `uml.object` and `uml.package` (0.19.0); other types draw as plain cards.
- *  From 0.19.0 those three draw a shown package that owns something the view shows as a box holding it (`parent`), and
+ *  have `subject`, `direction` ('right' | 'down'), `notation`, `present`, `fragments` and `timeline`. umlimator/all draws `uml.class` (0.18.0), `uml.object` and `uml.package` (0.19.0), `uml.sequence` and `uml.communication` (0.20.0), `uml.use-case`, `uml.activity`, `uml.state-machine` and `uml.interaction-overview` (0.21.0); other types draw as plain cards.
+ *  From 0.19.0 the class, object and package types draw a shown package that owns something the view shows as a box holding it (`parent`), and
  *  qualify names (`sales::Order`) from the nearest shown owner, the view's `subject`, or the top. */
 export interface Element {
   id: string; type: string; label?: string; parent?: string; props?: Record<string, unknown>; members?: Element[];
@@ -98,7 +94,69 @@ export type UmlPackageLineType = 'uml.PackageImport' | 'uml.PackageMerge' | 'uml
 export interface UmlPackageImportProps { visibility?: 'public' | 'private'; stereotypes?: string[]; [key: string]: unknown }
 /** What a typed view shows of one element, in its `present` by the element's id: compartments not drawn, divider and
  *  all, and at most `rows` rows in each, then "+k more". */
-export interface UmlPresent { collapsed?: ('attributes' | 'operations' | 'literals')[]; rows?: number }
+export interface UmlPresent { collapsed?: ('attributes' | 'operations' | 'literals' | 'activities')[]; rows?: number }
+/** The sequence diagram's vocabulary (a view with `diagram: 'uml.sequence'`, umlimator/all from 0.20.0;
+ *  docs/conformance/uml-sequence.md). Lifelines are model nodes the view lists in `nodeIds`, left to right. Messages and
+ *  interaction uses are inline in the view's `edges`, in time order; a fragment's content is one run there, operand by
+ *  operand. Combined fragments are in the view's `fragments`, each with its operands as `members`; an occurrence's or a
+ *  fragment's `parent` is the operand that holds it. Activations and message numbers are derived, never stored. */
+export type UmlSequenceElementType = 'uml.Lifeline' | 'uml.InteractionUse' | 'uml.CombinedFragment';
+export type UmlSequenceMemberType = 'uml.InteractionOperand';
+export type UmlSequenceLineType = 'uml.Message';
+/** A lifeline's props: what it represents, by name, as text (drawn `name : Type`); stereotype `actor` draws «actor». */
+export interface UmlLifelineProps { represents?: string; stereotypes?: string[]; [key: string]: unknown }
+/** A message's kind: a call (filled arrow, the default), async (open arrow), reply (dashed, open), create (dashed, open;
+ *  the receiver's head is lowered to it) or delete (the receiver's stem ends in a cross). */
+export type UmlMessageSort = 'call' | 'async' | 'reply' | 'create' | 'delete';
+/** A message's props: its sort; a reply's `replyTo`, the id of the earlier call it answers. */
+export interface UmlMessageProps { sort?: UmlMessageSort; replyTo?: string; stereotypes?: string[]; [key: string]: unknown }
+/** An interaction use's props: the lifelines it covers (next to each other in `nodeIds`), and the view it refers to. */
+export interface UmlInteractionUseProps { covers?: string[]; refersTo?: string; [key: string]: unknown }
+/** A combined fragment's operator; any other is drawn by its name, with a warning. opt, loop and break have one operand,
+ *  whose `label` is its guard. */
+export type UmlInteractionOperator = 'alt' | 'opt' | 'loop' | 'par' | 'break';
+export interface UmlCombinedFragmentProps { operator?: UmlInteractionOperator; [key: string]: unknown }
+/** The communication diagram's vocabulary (a view with `diagram: 'uml.communication'`, umlimator/all from 0.20.0;
+ *  docs/conformance/uml-communication.md): lifelines; connectors and messages are model edges the view's `edges` lists,
+ *  connectors first. Only the messages' order means anything; their numbers (1, 1.1, 1.1.2) are derived. A message's
+ *  props are UmlMessageProps; a message needs a connector between its two lifelines. */
+export type UmlCommunicationElementType = 'uml.Lifeline';
+export type UmlCommunicationLineType = 'uml.Connector' | 'uml.Message';
+/** The use case diagram's vocabulary (a view with `diagram: 'uml.use-case'`, umlimator/all from 0.21.0;
+ *  docs/conformance/uml-use-case.md). A use case's `parent` is a subject (drawn as a box holding it) or a package. An
+ *  extend runs from the extending use case to the one it extends; an include from the including one. */
+export type UmlUseCaseElementType = 'uml.Actor' | 'uml.UseCase' | 'uml.Subject' | 'uml.Comment';
+export type UmlUseCaseMemberType = 'uml.ExtensionPoint';
+export type UmlUseCaseLineType = 'uml.Association' | 'uml.Include' | 'uml.Extend' | 'uml.Generalization' | 'uml.CommentLink';
+/** An extend's props: the ids of the extended use case's extension points (one at least), and its condition, as text. */
+export interface UmlExtendProps { extensionPoints?: string[]; condition?: string; stereotypes?: string[]; [key: string]: unknown }
+/** The activity diagram's vocabulary (a view with `diagram: 'uml.activity'`, umlimator/all from 0.21.0;
+ *  docs/conformance/uml-activity.md). A node's `parent` is its partition, drawn as a lane; a partition's is the
+ *  partition it is nested in. A call behaviour action's `opensView` names an activity view. */
+export type UmlActivityElementType = 'uml.InitialNode' | 'uml.ActivityFinalNode' | 'uml.FlowFinalNode' | 'uml.Action' | 'uml.CallBehaviorAction'
+  | 'uml.SendSignalAction' | 'uml.AcceptEventAction' | 'uml.DecisionNode' | 'uml.MergeNode' | 'uml.ForkNode' | 'uml.JoinNode'
+  | 'uml.ObjectNode' | 'uml.DataStoreNode' | 'uml.ActivityPartition' | 'uml.Comment';
+export type UmlActivityLineType = 'uml.ControlFlow' | 'uml.ObjectFlow' | 'uml.CommentLink';
+/** A flow's props (activity and interaction overview): its guard, as text, drawn `name [guard]`; its label is its name. */
+export interface UmlFlowProps { guard?: string; stereotypes?: string[]; [key: string]: unknown }
+/** The state machine diagram's vocabulary (a view with `diagram: 'uml.state-machine'`, umlimator/all from 0.21.0;
+ *  docs/conformance/uml-state-machine.md). A substate's or pseudostate's `parent` is a state, or a region (a member) of
+ *  one; a state with shown substates is drawn as a box, each region that holds something shown as a box inside it. */
+export type UmlStateMachineElementType = 'uml.State' | 'uml.Pseudostate' | 'uml.FinalState' | 'uml.Comment';
+export type UmlStateMachineMemberType = 'uml.Region' | 'uml.InternalTransition';
+export type UmlStateMachineLineType = 'uml.Transition' | 'uml.CommentLink';
+export interface UmlStateProps { entry?: string; do?: string; exit?: string; stereotypes?: string[]; [key: string]: unknown }
+export type UmlPseudostateKind = 'initial' | 'choice' | 'junction' | 'fork' | 'join' | 'shallowHistory' | 'deepHistory' | 'terminate';
+export interface UmlPseudostateProps { kind?: UmlPseudostateKind; stereotypes?: string[]; [key: string]: unknown }
+/** A transition's or an internal transition's props, each text, drawn `trigger [guard] / effect`. */
+export interface UmlTransitionProps { trigger?: string; guard?: string; effect?: string; stereotypes?: string[]; [key: string]: unknown }
+/** The interaction overview diagram's vocabulary (a view with `diagram: 'uml.interaction-overview'`, umlimator/all from
+ *  0.21.0; docs/conformance/uml-interaction-overview.md): the activity's control nodes and flows (UmlFlowProps), and
+ *  interaction uses (drawn `ref`) and inline interactions (drawn `sd` with their content), whose `opensView` names a
+ *  `uml.sequence` view of the same model. */
+export type UmlInteractionOverviewElementType = 'uml.InitialNode' | 'uml.ActivityFinalNode' | 'uml.FlowFinalNode' | 'uml.DecisionNode'
+  | 'uml.MergeNode' | 'uml.ForkNode' | 'uml.JoinNode' | 'uml.InteractionUse' | 'uml.Interaction' | 'uml.Comment';
+export type UmlInteractionOverviewLineType = 'uml.ControlFlow' | 'uml.CommentLink';
 /** What a line means, drawn as its colour: calls (the default), feeds (hands work on), triggers (suggests, offers, fires),
  *  state (reads or writes a file, board or config: a thinner line, a muted label, no flow) and guard (a hook steps in).
  *  Colours are --um-w-<kind>. An edge's `style` (emphasis, dashed, security) wins over its kind's colour. */
@@ -139,7 +197,8 @@ export interface MapEdge {
 }
 export interface MapView {
   id: string; parent?: string | null; title?: string; nodeIds: string[];
-  edges?: (string | MapEdge)[]; layout?: Record<string, [number, number]>; repair?: boolean;
+  /** Model line ids or lines of its own; in a sequence view (0.20.0) its messages and interaction uses (Elements), in time order. */
+  edges?: (string | MapEdge | Element)[]; layout?: Record<string, [number, number]>; repair?: boolean;
   /** Cards 80 px tall that show their sub-line and then their chips (`verbs`) on a third line. Default: 64 px, and a card's
    *  chips take its sub-line's place. A script card (no kind) shows no sub-line either way. */
   subAndChips?: boolean;
@@ -149,8 +208,6 @@ export interface MapView {
   /** Boxes: badges are tabs on the box's border; tone, a palette name as a badge's (--um-<tone>), tints the region behind the
    *  box (as deep as --um-tint makes the cards), with its border dashed and its title in the tone. */
   containers?: { id: string; label?: string; nodeIds?: string[]; parent?: string; badges?: Badge[]; tone?: string }[];
-  /** The notation this view's cards are drawn in (0.15.0): it wins over the model's. */
-  shapes?: Notation;
   [key: string]: unknown;
 }
 
@@ -205,7 +262,6 @@ export interface MapState {
   paused: boolean;
   camera: { x: number; y: number; zoom: number };   // the centre in map units, and the zoom (1: actual size); a state event's: at rest
   flow: boolean;
-  shapes: Notation;               // the notation the view shown is drawn in (0.15.0)
   motion: 'full' | 'reduced' | 'instant';
   gesture: 'idle' | 'dragging' | 'connecting' | 'naming';   // an edit in progress (editable maps)
   destroyed: boolean;
@@ -234,8 +290,6 @@ export interface RenderOptions {
   wheel?: 'zoom' | 'ctrl';
   minimap?: boolean;             // default false
   flow?: boolean;                // animated flow along lines (default: on unless prefers-reduced-motion)
-  /** The notation every view is drawn in (0.15.0), over each view's and the model's own. */
-  shapes?: Notation;
   /** Text widths: default the host's font (--um-sans, measured on a canvas); false: a font-independent estimate. */
   measure?: false | ((text: string, px: number) => number);
   /** Edit gestures that emit `change` events: all of them, or only those set true. Off by default. */
@@ -308,10 +362,6 @@ export interface Handle {
   readonly destroyed: boolean;
   /** The animated flow along lines (the ≋ button and F), to read or set. */
   flow: boolean;
-  /** The notation the view shown is drawn in (0.15.0). Set it to draw every view in one (null: each view's own): the
-   *  cards are drawn again from the geometry they have, with the camera, selection, lens and marks; nothing is laid out. */
-  get shapes(): Notation;
-  set shapes(notation: Notation | null);
   /** How this map moves: 'instant' (drawn without animation, as the page's #check, #still and #shot are), 'reduced' (the
    *  reader's setting), else 'full'. */
   readonly motion: 'full' | 'reduced' | 'instant';