API reference
umlimator is one ES module with no dependencies, no build step and no network calls. It draws a map model into any element, and its functions that read a model run in Node as well as in a browser. The types are hand-written in lib/umlimator.d.ts; these pages explain each export. The history of every change is in the changelog.
bash
npm install umlimatorjs
import { render } from 'umlimator';
import 'umlimator/theme.css';
const map = render(document.getElementById('map'), model, {
on: { select: e => console.log(e.target) },
});Entry points
| Import | File | What it gives you |
|---|---|---|
umlimator | lib/umlimator.js | Maps: every function below. A typed view (a diagram type) draws as plain cards, with a warning. |
umlimator/all | lib/umlimator-all.js | The same exports, and every diagram type drawn in its own notation. See Typed diagrams. |
umlimator/theme.css | lib/umlimator-theme.css | The default --um-* palette, light and dark, and the fonts. Optional: a host may set the variables itself. |
umlimator/schema.json | lib/umlimator.schema.json | The model's JSON Schema, for editors and validators. See Model and schema. |
umlimator/element | lib/umlimator-element.js | The <umlimator-map> custom element. See Element and plugins. |
umlimator/markdown-it | lib/umlimator-markdown-it.js | A markdown-it plugin (VitePress) for umlimator fenced blocks. |
umlimator/remark | lib/umlimator-remark.js | A remark plugin (Docusaurus, MDX) for the same blocks. |
umlimator and umlimator/all share one set of types and one API: switch the import to draw diagram types, and nothing else changes.
From a CDN, with no install:
html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/umlimator@0.44.0/lib/umlimator-theme.css">
<script type="module">
import { render } from 'https://cdn.jsdelivr.net/npm/umlimator@0.44.0/lib/umlimator.js';
</script>Functions
| Function | Needs a browser | What it does | Page |
|---|---|---|---|
render(container, model, options?) | yes | Draws a model into an element and returns a Handle. | render |
mountPage(container, model, options?) | yes | The whole standalone viewer the CLI writes. | render |
layout(model, viewId, options?) | no | One view's geometry: card boxes and line routes. | render |
check(model, viewId, options?) | no | The layout check on that geometry: overlaps, crossings, detours, misplaced labels. | render |
validate(model) | no | The model's own errors and warnings, each with where it is. | apply and commands |
migrate(model) | no | The model at the schema version this release reads. | model and schema |
apply(model, commands) | no | The next model after a transaction of commands. | apply and commands |
history(model, limit?) | no | Undo and redo for a host that applies models. | apply and commands |
references(model, id) | no | Every place a model names an element. | apply and commands |
rules(model) | no | Every rule in model.rules the model breaks, view by view. | apply and commands |
diff(before, after) | no | What changed between two models, as one model to draw. | apply and commands |
drift(model, observed) | no | The map against the traffic seen: lines nobody drew, lines that carried nothing. | apply and commands |
describe(model, viewId) | no | A view in plain sentences. | apply and commands |
paths(model, viewId, from, to) | no | Every card and line on a path between two cards. | apply and commands |
reach(model, viewId, from, options?) | no | What a card leads to, or what leads to it. | apply and commands |
critical(model, viewId, options?) | no | The slowest or costliest path along a view's lines. | apply and commands |
whatIf(model, viewId, options) | no | What loses its way when cards are taken out. | apply and commands |
otlpSpans(otlp) | no | The spans of an OpenTelemetry trace, ready for replay(). | events and state |
sequenceFromTrace(model, spans, options?) | no | A trace kept as a numbered view of the model. | events and state |
None of them changes the model it is given: each one that returns a model returns a new one.
Types
| Group | Types | Page |
|---|---|---|
| Drawing | RenderOptions, Handle, ExportOptions, Geometry, CheckIssue | render |
| The model | MapModel, MapNode, MapEdge, MapView, Shape, Badge, WireKind, Element, Ref, Selector, LensSelector, Lens, Rule, Story, StoryStep | model and schema |
| Changing and reading a model | Command, History, Reference, Problem, RuleBreak, DiffResult, Observed, DriftResult | apply and commands |
| Events, state and marks | Events, Change, Hint, MapState, StoryPlayer, Overlay, CardMark, LineMark, Lit, Span, Replay | events and state |
| The element | UmlimatorMap | element and plugins |
| Diagram types | UmlClassElementType, C4ViewType, BpmnElementProps and the rest of each type's vocabulary | typed diagrams |
Pages
- render:
render(), theHandleit returns,mountPage(), andlayout()andcheck()in Node. - Model and schema: what a model holds, the JSON Schema, and
migrate(). - Apply and commands: changing a model with
apply()andhistory(), and reading it withvalidate(),rules(),diff(),drift(),describe(),paths(),reach(),critical()andwhatIf(). - Events and state: the events a map emits,
MapState, layers of marks, stories, tours and trace replays. - Element and plugins:
<umlimator-map>, and the markdown-it and remark plugins. - Typed diagrams:
umlimator/all, the typed element envelope and each diagram type's vocabulary.