umlimator 0.14.0 → 0.16.0

package/README.md

@@ -22,6 +22,11 @@ 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)).
 - **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
@@ -60,7 +65,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.14.0"`. npm 12 refuses git
+Or from GitHub, at a tag or any commit: `"umlimator": "github:zintaen/umlimator#v0.16.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
@@ -95,7 +100,8 @@ function MapView({ model, onSelect }) {
 - `map.expand(id)` unfolds a stacked card in place and `map.collapse(id)` folds it; `layout(model, view, { expand })`
   draws the same in Node.
 - Colours are `--um-*` CSS variables, fonts are the host's (`--um-sans`, `--um-mono`), text is measured in that font,
-  and nothing is fetched.
+  and nothing is fetched. `--um-tint` sets how deep the cards' and the boxes' tints are: 1 by default, 0 for none, 2 for
+  twice as deep (a tint stops at 18% of its colour, so text on it keeps 4.5:1).
 - `layout(model, viewId)` returns a view's geometry without a DOM, in Node too; `check(model, viewId)` runs the layout
   check on it, and `validate(model)` finds dangling or repeated ids before anything is drawn. `rules(model)` lists every
   rule the model breaks, view by view.
@@ -104,6 +110,9 @@ 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).
 - `diff(before, after)` returns `after` with each card and line marked added, changed or removed, what changed in words,
   and the views that show it; `drift(model, observed)` marks the lines traffic ran on that nobody drew, and the drawn ones
@@ -145,7 +154,8 @@ 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.
+  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.
 - **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.
@@ -190,9 +200,11 @@ 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, 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 |
+| edge | `step` | a number (2, or 2.1) or text of up to 3 characters (2a), in a circle on the line in any view (a pill for 2 or 3 characters): the order things happen, shown as written in the line's name and title. A numbered view numbers its lines in run order instead |
 | edge | `sublabel` | a second, smaller line under the label |
 | edge | `fromSide`, `toSide` | the card sides the line uses |
 | edge | `from`, `to` | may name a container of the view: the line ends on its box |
@@ -204,7 +216,9 @@ 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) |
 | 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 |
@@ -239,7 +253,10 @@ views), C4-PlantUML (its element, relationship and boundary macros), Mermaid (`f
 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).
+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
+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`.
 
 `pdf` prints the map through Chrome's own print, as a document to hand in for a review
 ([bike-share's](https://zintaen.github.io/umlimator/examples/bike-share.pdf), as CI builds it). A cover has the title,
@@ -251,7 +268,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, and `#lens=<id>`), stories, lenses, and export. For
+(`#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
 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,
@@ -281,7 +299,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: zintaen/umlimator@v0.14.0
+      - uses: zintaen/umlimator@v0.16.0
         with:
           models: "docs/*.json"   # optional: where the models are (default: every .json that is a map model)
 ```
@@ -376,7 +394,7 @@ umlimator_mcp.py             the MCP server that `umlimator.py mcp` runs
 action.yml                   the diff Action: what a pull request changes in its maps, posted on it
 lib/                         the module (umlimator.js), 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/                        the module's API and the editing design; docs/diagrams/: the plan for 28 diagram types (not built yet)
 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)

package/lib/umlimator-element.js

@@ -15,6 +15,8 @@
    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. */
@@ -23,7 +25,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'];
+  static observedAttributes = ['src', 'view', 'minimap', 'controls', 'wheel', 'height', 'shapes'];
   map = null;
   #drawn = 0; #due = false; #src = null; #model = null; #loading = false;
 
@@ -38,6 +40,7 @@ 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
@@ -78,7 +81,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', 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', shapes: get('shapes') || undefined, 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-theme.css

@@ -39,13 +39,17 @@
   --um-sans: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif;
   --um-mono: "JetBrains Mono", ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
 }
+/* How deep the map's tints are, in either theme: a card's kind colour, and a box's tone (containers[].tone). 1 is as
+   drawn here, 0 is none (plain panels), 2 twice as deep. The map stops a tint at 18% of its colour, where a card's
+   sub-line would fall below 4.5:1. Set it on the map or any ancestor; on :root only, so a map's own setting wins. */
+:root { --um-tint: 1; }
 @media (prefers-color-scheme: dark) {
   :root:not([data-theme="light"]) {
   --um-stage-bg: var(--um-bg-2); --um-edited: #d29922;
   --um-bg: #0d1117; --um-bg-2: #010409; --um-panel: #0d1117; --um-panel-2: #151b23; --um-border: #262c36; --um-border-2: #3d444d;
   --um-text: #f0f6fc; --um-muted: #9198a1; --um-dim: #656c76; --um-grid: rgba(240,246,252,.05); --um-mask: #0d1117; --um-arrow: #656c76;
   --um-shadow: 0 10px 30px rgba(1,4,9,.55); --um-dot: #161b22; --um-gridline: transparent; --um-chrome: rgba(13,17,23,.92);
-  --um-accent: #4493f8; --um-accent-fg: #ffffff; --um-lane: rgba(240,246,252,.025);
+  --um-accent: #4493f8; --um-accent-fg: #0d1117; --um-lane: rgba(240,246,252,.025);
   --um-cyan: #4493f8; --um-green: #3fb950; --um-violet: #ab7df8; --um-amber: #d29922; --um-rose: #f85149; --um-orange: #db6d28; --um-slate: #9198a1; --um-fuchsia: #db61a2;
   --um-k-public: #4493f8; --um-k-lane: #2dd4bf; --um-k-ext: #ab7df8; --um-k-verb: #f778ba; --um-k-script: #9198a1; --um-k-hook: #f85149; --um-k-board: #d29922;
   --um-w-calls: #b7bdc8; --um-w-feeds: #4493f8; --um-w-triggers: #ab7df8; --um-w-state: #59626e; --um-w-guard: #f85149;
@@ -59,7 +63,7 @@
   --um-bg: #0d1117; --um-bg-2: #010409; --um-panel: #0d1117; --um-panel-2: #151b23; --um-border: #262c36; --um-border-2: #3d444d;
   --um-text: #f0f6fc; --um-muted: #9198a1; --um-dim: #656c76; --um-grid: rgba(240,246,252,.05); --um-mask: #0d1117; --um-arrow: #656c76;
   --um-shadow: 0 10px 30px rgba(1,4,9,.55); --um-dot: #161b22; --um-gridline: transparent; --um-chrome: rgba(13,17,23,.92);
-  --um-accent: #4493f8; --um-accent-fg: #ffffff; --um-lane: rgba(240,246,252,.025);
+  --um-accent: #4493f8; --um-accent-fg: #0d1117; --um-lane: rgba(240,246,252,.025);
   --um-cyan: #4493f8; --um-green: #3fb950; --um-violet: #ab7df8; --um-amber: #d29922; --um-rose: #f85149; --um-orange: #db6d28; --um-slate: #9198a1; --um-fuchsia: #db61a2;
   --um-k-public: #4493f8; --um-k-lane: #2dd4bf; --um-k-ext: #ab7df8; --um-k-verb: #f778ba; --um-k-script: #9198a1; --um-k-hook: #f85149; --um-k-board: #d29922;
   --um-w-calls: #b7bdc8; --um-w-feeds: #4493f8; --um-w-triggers: #ab7df8; --um-w-state: #59626e; --um-w-guard: #f85149;

package/lib/umlimator.d.ts

@@ -15,8 +15,16 @@ 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). */
+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 };
 export interface MapNode {
@@ -29,6 +37,8 @@ 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. */
+  shape?: Shape;
   [key: string]: unknown;
 }
 /** What a line means, drawn as its colour: calls (the default), feeds (hands work on), triggers (suggests, offers, fires),
@@ -45,6 +55,13 @@ export interface MapEdge {
    *  hit line growing with it. The host picks the bucket (say under 10, under 100, 100 or more relations); anything else is 1.
    *  A line that stands for several edges takes the largest. */
   weight?: 1 | 2 | 3;
+  /** Its place in the order things happen, drawn in a circle on the line before its label, as a numbered view draws its
+   *  steps, in any view: 2, 2.1 for a step within step 2, or text of up to 3 characters such as "2a" (a pill for 2 or 3
+   *  characters). The line's name and title say it as written ("Step 2a: …"); in order, 2 < 2a < 2b < 3. A numbered view
+   *  (`render: 'sequence'`) numbers its lines in run order instead. A line that stands for several edges shows the first
+   *  one's step (a view's `keepPairs` draws each edge as its own line). A step on a model edge shows in every view that
+   *  draws the edge; a view's own edge numbers it in that view only. */
+  step?: number | string;
   /** A second, smaller line under the label (a technology, say), placed with it and counted in the room left for labels.
    *  Shown only with a label. A line that stands for several edges shows each of their sublabels, joined by " / ". */
   sublabel?: string;
@@ -71,7 +88,11 @@ export interface MapView {
   /** Guess a line's kind from the words of its label ("reads" is state, "triggers" is triggers ...) when its edges name
    *  none. Off in render() and layout(), which draw no legend; the standalone page (mountPage) always guesses. */
   kindsFromLabels?: boolean;
-  containers?: { id: string; label?: string; nodeIds?: string[]; parent?: string; badges?: Badge[] }[];   // badges: tabs on the box's border
+  /** 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;
 }
 
@@ -114,11 +135,15 @@ export interface MapState {
   expanded: string[];             // as `expanded`
   lens: string | null;
   overlays: string[];             // the layers on the map, in stack order ('lens', 'highlight', 'replay', 'story', 'tour', a host's)
-  story: { id: string; step: number; steps: number; playing: boolean } | null;
-  tour: boolean;                  // a tour's dot is riding
-  replay: { playing: boolean } | null;   // a replay under way: playing, or paused
+  story: { id: string; step: number; steps: number; playing: boolean } | null;   // playing: the player's own (it goes on by itself)
+  tour: boolean;                  // a tour's dot is on the map, riding or held (by paused, or by its story's pause); a path lit at rest: false
+  replay: { playing: boolean } | null;   // a replay under way: playing, or paused by its own pause()
+  /** The standalone page's ❚❚ is on (0.15.0): it holds every clock (a tour's or a replay's dot, a story's step, the flow)
+   *  and leaves each one's own state as it is, so story.playing or replay.playing true under it means "would play, held". */
+  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;
@@ -147,6 +172,8 @@ 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. */
@@ -219,6 +246,10 @@ 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';