umlimator 0.18.0 → 0.20.0

package/README.md

@@ -49,7 +49,25 @@ drill-down, a data pipeline, an AI agent's skills, and host pages for embedding,
   itself, pinned where you pin it. Edited on the canvas (members as one line of UML text, a palette, a relationship
   picker), each gesture an `edit` event the host applies with `apply()`; checked by the class diagram's rules; read from
   and written to Mermaid's `classDiagram` ([`examples/sales-classes.json`](examples/sales-classes.json),
-  [what it covers](docs/conformance/uml-class.md)).
+  [what it covers](docs/conformance/uml-class.md)). From 0.19.0 a package owning classes the view shows is a box holding
+  them, and names are qualified (`sales::Order`).
+- **UML object and package diagrams** (0.19.0): instances with their slots (`order1042 : Order`, underlined;
+  `status = placed`) and links with names and roles ([`examples/order-objects.json`](examples/order-objects.json),
+  [what it covers](docs/conformance/uml-object.md)); packages as boxes holding what they own, at any depth, or as
+  closed folders, with «import», «access», «merge» and dependencies between them
+  ([`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.
 - **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`).
@@ -72,7 +90,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.18.0"`. npm 12 refuses git
+Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.20.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
@@ -121,7 +139,7 @@ function MapView({ model, onSelect }) {
   `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 diagram, whose gestures emit
+- `import { render, apply, history } from 'umlimator/all'` draws diagram types too: a class, object, package, sequence or communication 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,
@@ -200,7 +218,8 @@ 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"` is a UML class 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"` or `"uml.communication"` is a UML class, object,
+package, sequence or communication 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.
 
@@ -238,18 +257,36 @@ kinds such as `public`, `lane`, `script`, `hook` and `board` work too). Fields b
 | 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 |
 
 In a version-2 model, a class diagram (`examples/sales-classes.json`; every field in
-[`docs/conformance/uml-class.md`](docs/conformance/uml-class.md)):
+[`docs/conformance/uml-class.md`](docs/conformance/uml-class.md)), an object diagram (`examples/order-objects.json`,
+[`uml-object.md`](docs/conformance/uml-object.md)) and a package diagram (`examples/bookshop-packages.json`,
+[`uml-package.md`](docs/conformance/uml-package.md)):
 
 | On | Field | What it does |
 |---|---|---|
 | node, member, edge | `type` | what it is: `uml.Class`, `uml.Interface`, `uml.Enumeration`, `uml.DataType`, `uml.PrimitiveType`, `uml.Package`, `uml.Comment`; members `uml.Property`, `uml.Operation`, `uml.EnumerationLiteral`; lines `uml.Association`, `uml.Generalization`, `uml.InterfaceRealization`, `uml.Dependency`, `uml.CommentLink` |
 | node | `members` | its attributes, operations or literals, in order, each `{ id, type, label, props }` |
-| node | `parent` | the package that owns it |
+| node, member, edge | `type`, from 0.19.0 | an object diagram's `uml.InstanceSpecification`, its members `uml.Slot`, lines `uml.Link`; a package diagram's `uml.Package` and the classifiers above, lines `uml.PackageImport`, `uml.PackageMerge`, `uml.Dependency` |
+| node | `parent` | the package that owns it: from 0.19.0 drawn as a box holding it when the view shows both |
+| node, member, edge | `props`, from 0.19.0 | an instance's `classifier` (a name, as text); a slot's `value`; a link's `association` and its ends' `role`; a package import's `visibility`, `public` («import») or `private` («access») |
 | node, member, edge | `props` | the type's own fields: `isAbstract`, `stereotypes`; a member's `visibility`, `valueType`, `multiplicity`, `default`, `isStatic`, `isDerived`, `parameters`, `returnType`; an association's `ends.from` and `ends.to` (`role`, `multiplicity`, `aggregation`, `navigable`) |
-| view | `diagram` | `"uml.class"`: the view is a class diagram |
+| view | `diagram` | `"uml.class"`, `"uml.object"` or `"uml.package"`: the view is a class, object or package diagram |
+| view | `subject` | the package the view shows the inside of: names are qualified from it |
 | 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 |
+
 ## Command line
 
 ```bash
@@ -265,11 +302,13 @@ 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 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)
 ```
 
@@ -277,7 +316,8 @@ 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 and a `sequenceDiagram` a UML sequence
+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
@@ -328,7 +368,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: zintaen/umlimator@v0.18.0
+      - uses: zintaen/umlimator@v0.20.0
         with:
           models: "docs/*.json"   # optional: where the models are (default: every .json that is a map model)
 ```
@@ -426,7 +466,7 @@ action.yml                   the diff Action: what a pull request changes in its
 src/                         the module's sources, by layer: core, draw, layout, map, canvas, page (tools/build.mjs joins them)
 lib/                         the module (umlimator.js; umlimator-all.js with every diagram family; both built and committed), its types, the default theme, <umlimator-map> and the docs plugins
 engine/                      the page templates the CLI inlines the module into; the upstream renderer and schema
-docs/                        the module's API and the editing design; docs/diagrams/: the plan for 28 diagram types (not built yet)
+docs/                        the module's API and the editing design; docs/conformance/: what each diagram type covers; docs/diagrams/: the plan for 28 diagram types
 tests/, bench/               tests, benchmark models and results
 icons/                       line icons and the logo manifest (sources and hashes only)
 examples/                    made-up systems: models, host pages and a Node script (live: zintaen.github.io/umlimator)