Playground
Everything below runs the published @liminis/diagrams — it is a real registry
dependency of this documentation site, exactly as it would be in your project. What you
drag here is what npm install gives you.
Parse, lay out, render
Section titled “Parse, lay out, render”Edit the source and the diagram follows. Parsing happens on every keystroke; there is no build step and no server involved.
Drag a node and the arrows re-route around it. Turn the checkbox off and the drag layer
disappears entirely — that is isEditMode, and it is the host’s decision, not the
library’s.
The diagram is anchored to the top of the pane and centred horizontally. While you drag, the canvas does not resize, so the node stays under the pointer and nothing else moves, even past the top or left edge. When you let go the canvas is resized once to contain the node, and the picture shifts once if it grew at the top or left.
Adding elements and relationships
Section titled “Adding elements and relationships”From 0.2.0, a host that passes onEdit also gets an add-element menu
(right-click the canvas, or long-press on touch) and a connect handle on each element.
Choosing a kind in the menu places a new element where you opened it (name it inline);
dragging from an element’s handle to another adds a Rel (label it inline, “Uses” by default). The menu also
has a separate Boundaries group that adds an empty boundary you can then right-click into
and fill. Each is reported to the host as a small insertion into the source (one line, or a
two-line block for a boundary), which applyC4Edit produces. Double-clicking
an element (on touch: tap it, then Rename), or a relationship’s label (long-press on touch), opens the label for renaming; only that
label argument changes in the source. Dropping an element or boundary on another boundary moves it in,
and ⌥-dragging a child out (on touch: tap it, then Move out) lifts it to the top level or into the boundary
you drop it on; the source line, or the boundary’s whole block, moves and nothing else changes —
see Recipe 4.
The playground below is built from the published package, so it does not offer these yet.
Positions are yours to keep
Section titled “Positions are yours to keep”The renderer is controlled. It takes positions in and calls back with new ones; it never writes anywhere. The counter above the diagram is this page’s own state — reload and it is gone, because a docs page chose not to persist it.
A real host decides differently. @liminis/editor writes positions into the markdown
code fence’s own meta string, which leaves a hand-arranged diagram sitting in plain,
diffable text. See Recipes for that pattern in full.
Errors are data, not exceptions
Section titled “Errors are data, not exceptions”Break the syntax — delete a closing brace, misspell Rel — and the parser returns
errors rather than throwing. This is C4ErrorDisplay rendering
ParseResult.errors directly.