@miragon/team-topologies-renderer

The browser layer of the Team Topologies Modeler: a framework-agnostic viewer and full editor for Team Topologies diagrams, built on diagram-js (MIT).

It renders the canonical document from @miragon/team-topologies-schema-model and gives you palette, move, resize, connect-by-overlap, multi-selection (lasso, select all) with group move, text annotations, context pad, in-place label editing and undo/redo — with no UI framework required. Mount it into any <div>; the web app (React) and the VS Code extension both wrap this exact package.

Install

npm install @miragon/team-topologies-renderer @miragon/team-topologies-schema-model

Three entry points

| Class | Use it for | | ----------------- | ------------------------------------------------------------------------------ | | Viewer | Read-only rendering, no interaction (thumbnails, static embeds). | | NavigatedViewer | Read-only + zoom (scroll), pan (drag) and selection. | | Modeler | The full editor: palette, move, resize, context pad, label editing, undo/redo. |

Editing gestures (Modeler)

| Gesture | Effect | | ---------------------------------- | ----------------------------------------------------------------------- | | Double-click an element | Edit its label in place (Enter commits, Shift+Enter breaks, Esc aborts) | | Ctrl/Cmd+A | Select every element | | Shift+drag on the canvas | Lasso-select (also the first palette tool) | | Shift+click | Add an element to / remove it from the selection | | Drag a selected element | Move the whole selection as one undo step | | Arrow keys (Shift: ×10) | Nudge the selection | | Ctrl/Cmd+C / V, Delete | Copy, paste, delete the selection | | Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z/Y | Undo / redo |

All three share a common base (TtBaseViewer) with the same import/export and lifecycle API.

Quick start

import { Modeler } from "@miragon/team-topologies-renderer";
import "@miragon/team-topologies-renderer/assets/team-topologies.css";
import { SAMPLE_DOCUMENT } from "@miragon/team-topologies-schema-model";

const modeler = new Modeler({ container: document.querySelector("#canvas")! });

// Load a document (auto-fits the viewport)
const { warnings } = modeler.importDocument(SAMPLE_DOCUMENT);

// Read the live canvas back as the canonical model
const doc = modeler.exportDocument();

// Export a standalone, self-contained SVG
const { svg } = modeler.saveSVG();

// Undo / redo are driven by the command stack
modeler.undo();
modeler.redo();

The CSS is required. Import @miragon/team-topologies-renderer/assets/team-topologies.css (it also pulls in diagram-js's own stylesheet and the Miragon --cd-* brand tokens) — without it the palette, context pad and label editor are unstyled.

Typeface. The canvas labels are drawn in the Miragon typeface Geist. The library does not ship the font; self-host it in the host app (e.g. @fontsource-variable/geist) so the on-screen canvas and exported SVG render in Geist. Without it, text falls back to a system sans.

API

Constructor — TtViewerOptions

new Modeler({
  container?: HTMLElement,            // host element (a detached <div> if omitted)
  width?: number | string,           // canvas width  (default "100%")
  height?: number | string,          // canvas height (default "100%", or "600px" with no container)
  additionalModules?: ModuleDeclaration[], // extra diagram-js modules
});

Shared methods (Viewer / NavigatedViewer / Modeler)

| Method | Returns | Purpose | | ---------------------------------- | ------------------------------- | ------------------------------------------------- | | importDocument(doc) | { warnings: ImportWarning[] } | Replace canvas content and auto-fit. | | exportDocument() | TtDocument | Rebuild the canonical model from the live canvas. | | saveSVG() | { svg: string } | Self-contained SVG snapshot (fitted viewBox). | | setMeta(partial) / getMeta() | — / RootBusinessObject | Read/write diagram-level metadata (e.g. title). | | attachTo(el) / detach() | void | Move the canvas in/out of the DOM (keeps state). | | clear() / destroy() | void | Empty the canvas / tear it down. | | on(event, cb) / off(event, cb) | void | Subscribe to diagram-js events. | | get<T>(name) | T | Resolve a diagram-js service (advanced). |

Modeler-only

undo(), redo(), canUndo(), canRedo().

Helpers & types

• Type guards: isTtElement, isTtTeam, isTtInteraction, isTtFlow, isTtAnnotation, isTtAssociation.
• Runtime element types: TtTeam, TtInteraction, TtFlow, TtAnnotation, TtElement, and TtAssociation (the connector from an annotation to the element it is attached to).
• Palette icon generators: teamIconSvg(type), interactionIconSvg(mode), flowIconSvg(), annotationIconSvg() — WYSIWYG SVG glyphs matching what the canvas draws.
• Other: TtViewerOptions, ImportWarning, RootBusinessObject, ROOT_ID, saveSVG.

How it's built

The package is a set of didi modules layered on diagram-js. Each is exported (e.g. ttDrawModule, ttPaletteModule, ttModelingModule) so you can compose your own viewer via additionalModules:

| Module | Responsibility | | ---------------------- | -------------------------------------------------------------------------------------- | | ttModelModule | Element factory with notation defaults (TtElementFactory). | | ttDrawModule | SVG rendering of teams, interactions, flow and annotations (TeamTopologiesRenderer). | | ioModule | Document ↔ canvas bridge (TtImporter, TtExporter, saveSVG). | | ttModelingModule | High-level mutations — label, type, mode, colours, description, annotations. | | ttRulesModule | Editing rules (what can move / resize / be created / be attached). | | ttBehaviorsModule | Keeps the model flat and annotation connectors cropped, one per annotation. | | ttPaletteModule | The lasso tool and the drag-to-create palette. | | ttContextPadModule | Per-element actions (rename, add/attach annotation, delete; delete a multi-selection). | | ttLabelEditingModule | Double-click in-place label editing. | | ttKeyboardModule | Undo / redo / select all / delete / copy / paste / nudge shortcuts. | | ttZOrderModule | Fixed stacking order (flow behind, teams, interactions, annotations on top). |

Rendering

A custom TeamTopologiesRenderer (priority 1500, beating diagram-js's default) draws each element from the spec in @miragon/team-topologies-schema-model: the four team outlines (octagon, vertical/horizontal rounded rectangles, square rectangle) drawn solid; the three interaction glyphs (parallelogram, triangle, circle) drawn dashed and translucent; the flow-of-change as a dashed left-to-right band; an annotation as a BPMN-style open bracket with left-aligned text, tied to its element by a dashed connector. Labels are word-wrapped (explicit line breaks are kept) and centred. Per-element fill/stroke overrides win over the spec defaults.

Import / export

The package reads and writes the canonical TtDocument (JSON) and exports a standalone SVG. PNG export and the embedded-scene round-trip (storing the document inside the exported image) live in the web app and the VS Code extension, which add the canvas rasterisation those formats need.

Development

Part of the Team Topologies Modeler monorepo; consumed from source by the apps. From the repo root:

npm run build -w packages/renderer   # Vite library build → dist/ (publish build)
npm test                             # Vitest unit tests
npm run test:browser                 # renderer integration tests in real Chromium
npm run typecheck

License

MIT. diagram-js and its dependencies are MIT / ISC / Apache-2.0.