umlimator 0.19.0 → 0.21.0

package/README.md

@@ -22,11 +22,10 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
   straight; orthogonal lines that never run through a card, room for every label, containers kept apart, and cards with
   no lines in a row of their own, under the view or at the bottom of their box. The same model gives the same picture.
 - **Reading**: animated flow, neighbours lit on selection, numbered steps, tours, minimap, light and dark themes.
-- **Card shapes**: three notations. `box` (the default) draws every card as a rounded box, as before. `c4` draws people,
-  browser apps, phones, databases, queues and files as the C4 model's tools do. `uml` draws UML 2.5's actors, nodes,
-  artifacts, packages and data stores, with UML's component icon on a box. A card's own `shape` wins in any notation.
-  The notation comes from the model, a view, `render()`, the page's toggle or the link; switching it draws the cards
-  again and lays nothing out ([`examples/notations.html`](examples/notations.html)).
+- **Card shapes**: one style, the union of what the C4 model's tools and UML 2.5 draw: people, robots, browser apps,
+  phones, terminals, queues, packages, hosts, data stores, files and hooks, each by its card's kind, and a rounded box
+  where no shape says more. A card's own `shape` wins. Each shape keeps to its card's box, so the layout is the same
+  ([`examples/notations.html`](examples/notations.html)).
 - **Exploring**: every path between two cards, or everything a card reaches, lit on the map; a view in plain sentences
   (`describe()`); a tour along any path the host names.
 - **Live data**: marks over the map without touching the model (`overlay()`): flow as fast as the traffic, errors that
@@ -58,6 +57,31 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
   ([`examples/bookshop-packages.json`](examples/bookshop-packages.json), [what it covers](docs/conformance/uml-package.md)).
   Ownership is edited by dropping an element into a box, or with the Owner field; both are checked by their types'
   rules, and the PDF's tables list slots and element kinds.
+- **UML sequence and communication diagrams** (0.20.0): lifelines on a time axis with calls, async messages, replies,
+  creates and deletes, activation bars derived from the messages, `alt`, `opt`, `loop`, `par` and `break` frames with
+  their guards, and interaction uses ([`examples/checkout-sequence.json`](examples/checkout-sequence.json),
+  [what it covers](docs/conformance/uml-sequence.md)); the same interaction as lifelines joined by connectors, each
+  link's messages a stack of numbered rows (1, 1.1, 1.1.2) ([`examples/checkout-communication.json`](examples/checkout-communication.json),
+  [what it covers](docs/conformance/uml-communication.md)). Messages are inserted, moved in time, wrapped in a frame and
+  deleted on the canvas, by pointer and by key, each gesture an `edit` event; checked by the types' rules; a sequence
+  diagram is read from and written to Mermaid's `sequenceDiagram`, and an OpenTelemetry trace becomes one
+  (`umlimator.py trace --diagram uml.sequence`). The MCP server, the `map-repo` skill and the diff Action learn these
+  types in one package after 0.20.0; until then a reorder of a view's messages shows in a diff as changed, not moved.
+- **UML use case, activity, state machine and interaction overview diagrams** (0.21.0): actors as stick figures, use
+  cases as ellipses with their extension points, a subject as a box holding its use cases, include, extend and
+  generalization ([`examples/shopping-use-cases.json`](examples/shopping-use-cases.json),
+  [what it covers](docs/conformance/uml-use-case.md)); actions, object nodes, data stores, send and accept actions, call
+  behaviour actions that open the activity they call, and the control nodes, in lanes (partitions, nested)
+  ([`examples/fulfil-activity.json`](examples/fulfil-activity.json), [what it covers](docs/conformance/uml-activity.md));
+  states with their entry, do and exit activities and internal transitions, composite states as boxes, orthogonal
+  regions with dashed dividers, every pseudostate, and transitions written `trigger [guard] / effect`
+  ([`examples/order-states.json`](examples/order-states.json), [what it covers](docs/conformance/uml-state-machine.md));
+  interaction uses and inline interactions, drawn with their sequence diagram inside, joined by the activity's control
+  nodes ([`examples/buy-book-overview.json`](examples/buy-book-overview.json),
+  [what it covers](docs/conformance/uml-interaction-overview.md)). Lines end on the outline of a circle, a diamond, a
+  bar or an ellipse. F2 edits a transition's or a flow's label through its parts; a drop changes a node's lane or a
+  state's region. A state machine is read from and written to Mermaid's `stateDiagram`. The MCP server's read tools and
+  the diff Action are tested on all four.
 - **Export**: any view as a stand-alone SVG or PNG, in the browser or from the CLI; the whole map as one PDF to hand in
   for a review: a cover with the contents, each view with its legend and tables of its cards, lines and boxes, then the
   rules (`umlimator.py pdf`).
@@ -80,7 +104,7 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
 npm install umlimator
 ```
 
-Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.19.0"`. npm 12 refuses git
+Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.21.0"`. npm 12 refuses git
 dependencies unless the project opts in, so that also needs `allow-git=root` in the `.npmrc` next to `package.json`.
 
 ## Embed
@@ -125,11 +149,8 @@ function MapView({ model, onSelect }) {
 - `map.lens(id)` puts one of the model's lenses on the map. `critical(model, view, { from, to, by })` finds the slowest
   or costliest path, `whatIf(model, view, { remove })` what loses its way when cards go down, and
   `sequenceFromTrace(model, spans, { view, match })` keeps a trace as a numbered view; all three in Node too.
-- `shapes: 'box' | 'c4' | 'uml'` draws every view in that notation, over each view's own (and the model's).
-  `map.shapes` reads the notation shown and sets another (`null`: each view's own again); the cards are drawn again from
-  the geometry they have, with the camera, selection and marks kept, and nothing is laid out.
 - `editable: true` turns on editing gestures ([docs/editing.md](docs/editing.md); `examples/edit.html` is a working host).
-- `import { render, apply, history } from 'umlimator/all'` draws diagram types too: a class, object or package diagram, whose gestures emit
+- `import { render, apply, history } from 'umlimator/all'` draws diagram types too: a class, object, package, sequence, communication, use case, activity, state machine or interaction overview diagram, whose gestures emit
   `edit` transactions that `apply(model, e.commands)` turns into the next model (`examples/class-editor.html` is a
   working host). `umlimator` alone draws maps, and a typed view as plain cards with a warning.
 - `diff(before, after)` returns `after` with each card and line marked added, changed or removed, what changed in words,
@@ -172,8 +193,7 @@ the map is drawn, and stay where scripts don't run ([`examples/element.html`](ex
 - **Attributes**: `view`, `minimap`, `controls="false"`, `wheel="ctrl"` (the wheel zooms only with Ctrl or ⌘, and scrolls
   the page otherwise, as a map in a document should), `height` (a number is pixels; 480 by default, or size it in CSS)
   and `theme` (`light` or `dark`: theme.css's palette for that map, whatever the page's). Changing one draws the map
-  again, and removing the element destroys it. `shapes` (`box`, `c4` or `uml`) is the notation; changing it draws the
-  cards again in the map drawn, with nothing loaded or laid out again.
+  again, and removing the element destroys it.
 - **Events**: `umlimator:select`, `umlimator:open` (cancel it to stay) and `umlimator:viewchange`, the map's event as
   `detail`; `load` once it is drawn, `error` when it can't be. `el.map` is the `render()` handle.
 - **Colours**: theme.css, as above, or your own `--um-*` variables. The element fetches nothing but its model.
@@ -208,8 +228,9 @@ path. The full schema is `engine/references/schema.md` (§ Map model); `examples
 A model file that starts with `"$schema": "<path to>/umlimator.schema.json"` (exported as `umlimator/schema.json`)
 gets completion and checks in editors, and `validate(model)` lists its errors and warnings, each with where it is.
 `"schemaVersion": 2` marks a model that may hold typed elements and typed views (`docs/diagrams/model.md`). A view whose
-`diagram` is `"uml.class"`, `"uml.object"` or `"uml.package"` is a UML class, object or package diagram, drawn by
-`umlimator/all` and the CLI; a type not drawn yet shows its
+`diagram` is `"uml.class"`, `"uml.object"`, `"uml.package"`, `"uml.sequence"`, `"uml.communication"`, `"uml.use-case"`,
+`"uml.activity"`, `"uml.state-machine"` or `"uml.interaction-overview"` is a UML class, object, package, sequence,
+communication, use case, activity, state machine or interaction overview diagram, drawn by `umlimator/all` and the CLI; a type not drawn yet shows its
 nodes as plain cards, with a warning. A model with no `schemaVersion` is a map, as always, and a version newer than the
 module reads is an error.
 
@@ -223,7 +244,7 @@ kinds such as `public`, `lane`, `script`, `hook` and `board` work too). Fields b
 | node | `noSub` | the name only; the description stays in the details panel |
 | node | `opensView`, `opensCount` | the view the card opens, which may not be loaded yet, and the ⤢ number for it |
 | node | `owner` | who owns the card (a team): rules and lenses pick by it, and a lens can ring cards by owner |
-| node | `shape` | the card's own shape in every notation: `box`, `person`, `browser`, `mobile`, `cylinder`, `pipe`, `document`, `hexagon`, `robot`, `terminal`, `window`, `folder` or `node` |
+| node | `shape` | the card's own shape, over the one its kind draws: `box`, `person`, `browser`, `mobile`, `cylinder`, `pipe`, `document`, `hexagon`, `robot`, `terminal`, `window`, `folder` or `node` |
 | node, edge | `edited` | a marker on the card or line |
 | edge | `kind` | what the line means, drawn as its colour: `calls` (default), `feeds`, `triggers`, `state`, `guard` |
 | edge | `weight` | 1, 2 or 3: how much the line stands for, drawn as its width |
@@ -239,9 +260,8 @@ kinds such as `public`, `lane`, `script`, `hook` and `board` work too). Fields b
 | view | `repair: false` | no port repair |
 | view | `subAndChips` | cards 80 px tall that show their sub-line, then their chips |
 | view | `kindsFromLabels` | a line whose edges name no `kind` takes one guessed from its label |
-| view, model | `shapes` | the notation the cards are drawn in: `box` (default), `c4` or `uml`; a view's wins over the model's ([what each draws](docs/module-api.md#card-shapes-box-c4-and-uml)) |
 | container | `badges` | tabs on the box's border |
-| container | `tone` | a palette name, as a badge's: the region behind the box tinted in it, its border dashed and its title in the tone (in `c4`, every box is dashed) |
+| container | `tone` | a palette name, as a badge's: the region behind the box tinted in it, its border dashed and its title in the tone |
 | model | `rules` | what must hold: no line `from` some cards `to` others (picked by id, kind, box or owner), or `noCycles` between boxes |
 | model | `stories` | walk-throughs: steps that each set the view, camera, selection, highlight, tour and caption |
 | model | `lenses` | ways to look at the map: what `pick` picks (by id, kind, box, owner or `line` kind) lit, the rest dimmed; `color: "owner"` rings cards by owner |
@@ -264,6 +284,35 @@ In a version-2 model, a class diagram (`examples/sales-classes.json`; every fiel
 | view | `direction` | `"down"` lays it out top to bottom, the general class above (default `"right"`) |
 | view | `present` | per element: `collapsed` compartments, and at most `rows` rows each, then "+k more" |
 
+A sequence diagram (`examples/checkout-sequence.json`, [`docs/conformance/uml-sequence.md`](docs/conformance/uml-sequence.md))
+and a communication diagram (`examples/checkout-communication.json`,
+[`docs/conformance/uml-communication.md`](docs/conformance/uml-communication.md)), from 0.20.0:
+
+| On | Field | What it does |
+|---|---|---|
+| node | `type` | `uml.Lifeline`; its `props.represents` is what it is an instance of, drawn `name : Type` |
+| edge | `type` | `uml.Message`; on a communication view also `uml.Connector`, the link messages are sent along |
+| edge | `props` | a message's `sort` (`call`, `async`, `reply`, `create`, `delete`) and a reply's `replyTo`, the call it answers |
+| view | `diagram` | `"uml.sequence"` or `"uml.communication"` |
+| view | `edges` | a sequence view's messages and interaction uses (`uml.InteractionUse`, `props.covers`), inline and in time order; a communication view's connectors, then its messages, by id, in order. Bars and numbers are derived |
+| view | `fragments` | a sequence view's combined fragments (`uml.CombinedFragment`, `props.operator`), each with its operands as `members` (`label` the guard); a message's or fragment's `parent` is its operand |
+
+A use case diagram, an activity diagram, a state machine diagram and an interaction overview diagram
+(`examples/shopping-use-cases.json`, `fulfil-activity.json`, `order-states.json` and `buy-book-overview.json`; each
+type's note in [`docs/conformance/`](docs/conformance/)), from 0.21.0:
+
+| On | Field | What it does |
+|---|---|---|
+| node, member, edge | `type` | use case: `uml.Actor`, `uml.UseCase` (members `uml.ExtensionPoint`), `uml.Subject`; lines `uml.Association`, `uml.Include`, `uml.Extend`, `uml.Generalization` |
+| node, edge | `type` | activity: `uml.Action`, `uml.CallBehaviorAction`, `uml.SendSignalAction`, `uml.AcceptEventAction`, `uml.ObjectNode`, `uml.DataStoreNode`, `uml.InitialNode`, `uml.ActivityFinalNode`, `uml.FlowFinalNode`, `uml.DecisionNode`, `uml.MergeNode`, `uml.ForkNode`, `uml.JoinNode`, `uml.ActivityPartition`; lines `uml.ControlFlow`, `uml.ObjectFlow` |
+| node, member, edge | `type` | state machine: `uml.State` (members `uml.Region`, `uml.InternalTransition`), `uml.Pseudostate`, `uml.FinalState`; lines `uml.Transition` |
+| node, edge | `type` | interaction overview: the activity's control nodes, `uml.InteractionUse`, `uml.Interaction` (an inline interaction); lines `uml.ControlFlow` |
+| node | `parent` | a use case's subject; an activity node's partition (its lane), a partition's enclosing partition; a substate's state or region |
+| node | `opensView` | the activity a call behaviour action calls; the sequence view an interaction use or inline interaction shows |
+| node | `props` | a state's `entry`, `do`, `exit`; a pseudostate's `kind` (`initial`, `choice`, `junction`, `fork`, `join`, `shallowHistory`, `deepHistory`, `terminate`) |
+| edge, member | `props` | an extend's `extensionPoints` (ids) and `condition`; a flow's `guard` (its `label` is its name); a transition's or internal transition's `trigger`, `guard` and `effect`, drawn `trigger [guard] / effect` |
+| view | `diagram` | `"uml.use-case"`, `"uml.activity"`, `"uml.state-machine"` or `"uml.interaction-overview"` |
+
 ## Command line
 
 ```bash
@@ -279,11 +328,14 @@ python3 umlimator.py check page.html --expand                          # also ea
 python3 umlimator.py record bike-share.html --story ride --out ride.png   # bike-share's story as an animated PNG, its tours riding
 python3 umlimator.py import workspace.dsl --out model.json            # a diagram you have already, as a model
 python3 umlimator.py import classes.mmd --out classes.json            # a Mermaid classDiagram, as a UML class diagram (needs Node)
+python3 umlimator.py import checkout.mmd --out checkout.json          # a Mermaid sequenceDiagram, as a UML sequence diagram (needs Node)
+python3 umlimator.py import order.mmd --out order.json                # a Mermaid stateDiagram, as a UML state machine diagram (needs Node)
 python3 umlimator.py render examples/sales-classes.json --out classes.html   # a class diagram's page; stills, check and pdf take it too
 docker compose config --format json > compose.json && python3 umlimator.py import compose.json --out model.json
 kubectl get deploy,sts,svc,ing -A -o json > cluster.json && python3 umlimator.py import cluster.json --out model.json
 python3 umlimator.py pdf page.html --out map.pdf                       # every view in one PDF: a cover, each view with its tables, the rules
 python3 umlimator.py trace model.json trace.json --view ride-end --match match.json --out model.json   # an OTLP trace kept as a numbered view
+python3 umlimator.py trace model.json trace.json --view ride-end --match match.json --diagram uml.sequence --out traced.json  # ... as a UML sequence diagram, in a version-2 model
 python3 umlimator.py mcp model.json                                    # an MCP server over stdio, for an AI assistant (below)
 ```
 
@@ -291,13 +343,14 @@ python3 umlimator.py mcp model.json                                    # an MCP
 
 `import` reads Structurizr DSL (people, systems, containers and components, their relationships, and the workspace's
 views), C4-PlantUML (its element, relationship and boundary macros), Mermaid (`flowchart` or `graph`, and `C4Context`,
-`C4Container` or `C4Component`; a `classDiagram` becomes a UML class diagram, read through Node), and the JSON of `docker compose config` (services, `depends_on`, networks) and of
+`C4Container` or `C4Component`; a `classDiagram` becomes a UML class diagram, a `sequenceDiagram` a UML sequence
+diagram and a `stateDiagram` a UML state machine diagram, each read through Node), and the JSON of `docker compose config` (services, `depends_on`, networks) and of
 `kubectl get` (workloads, Services, Ingresses). It tells the format from the content, then the extension; `--format`
 decides. Groups, boundaries, subgraphs, networks and namespaces become boxes; Structurizr's views stay views, a card
 opening the view below it; `examples/clinic.json` is `examples/clinic.dsl`, imported. What each element becomes, and
 what is left out: [docs/module-api.md § Import](docs/module-api.md#import-90). Whatever the file holds that `import`
-doesn't read is listed on stderr with its line (in JSON, its path). A Structurizr, C4-PlantUML or Mermaid C4 source is
-drawn in the `c4` notation: its people as people (`person`, or `user` outside the system), its phone apps as phones. A
+doesn't read is listed on stderr with its line (in JSON, its path). A Structurizr, C4-PlantUML or Mermaid C4 source's
+people are people (`person`, or `user` outside the system), and its phone apps phones. A
 Structurizr workspace's `styles` give its elements their shapes (`shape Person`, `Cylinder`, `WebBrowser`, ...), in
 Structurizr's own order; a shape the map has no counterpart for is listed in `notImported`.
 
@@ -311,8 +364,8 @@ the title and "page N of M". It takes `--views` and `--theme`, as `stills` does,
 default; both across).
 
 The page has breadcrumbs, a details panel per card (with the slowest path from it and what-if), ⌘K search, deep links
-(`#view=<id>&node=<id>`, `#story=<id>&step=<n>` for a story's step, `#lens=<id>` and `#shapes=c4`), stories, lenses, a
-card shapes toggle next to ◐ (box, c4, uml; the page keeps the reader's choice), and export. For
+(`#view=<id>&node=<id>`, `#story=<id>&step=<n>` for a story's step, `#lens=<id>`), stories, lenses, a
+light and dark toggle (◐), and export. For
 scripts and tests, it keeps its map's handle on `window.umlimatorMap`: the `Handle` that `render()` returns (`setView()`,
 `highlight()`, `tour()`, `play()` ...).
 `stills` skips a view whose inputs have not changed since its last export (`--all` exports every view), and exits 1,
@@ -342,7 +395,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: zintaen/umlimator@v0.19.0
+      - uses: zintaen/umlimator@v0.21.0
         with:
           models: "docs/*.json"   # optional: where the models are (default: every .json that is a map model)
 ```
@@ -415,7 +468,7 @@ With `UMLIMATOR_OFFLINE=1` the CLI fetches nothing: a logo not in the cache keep
 
 ```bash
 npm run build               # src/ into lib/umlimator.js and lib/umlimator-all.js: edit the sources, commit all three
-node --test                 # layout() in Node: the bench views' geometry and the layout rules
+node --test                 # layout() in Node: the bench views' geometry and the layout rules; npm test runs the "(timed)" tests apart, one file at a time
 python3 tests/embed.py      # render() in headless Chrome: events, keyboard, colours, contrast, editing, the element
 python3 bench/bench.py --check-determinism --expect bench/expected.json --max-ms m50=2000
 ```