@miragon/team-topologies-renderer 0.1.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +146 -0
  2. package/dist/index.js +835 -846
  3. package/dist/index.js.map +1 -1
  4. package/dist/team-topologies.css +2 -1
  5. package/package.json +10 -10
package/README.md ADDED
@@ -0,0 +1,146 @@
1
+ # @miragon/team-topologies-renderer
2
+
3
+ [![npm](https://img.shields.io/npm/v/@miragon/team-topologies-renderer)](https://www.npmjs.com/package/@miragon/team-topologies-renderer)
4
+ [![License: MIT](https://img.shields.io/github/license/Miragon/team-topologies-modeler)](https://github.com/Miragon/team-topologies-modeler/blob/main/LICENSE)
5
+
6
+ The **browser layer** of the [Team Topologies Modeler](../../README.md): a framework-agnostic viewer
7
+ and full editor for [Team Topologies](https://teamtopologies.com/) diagrams, built on
8
+ [diagram-js](https://github.com/bpmn-io/diagram-js) (MIT).
9
+
10
+ It renders the canonical document from
11
+ [`@miragon/team-topologies-schema-model`](../schema-model) and gives you palette, move, resize,
12
+ connect-by-overlap, context pad, inline label editing and undo/redo — with no UI framework required.
13
+ Mount it into any `<div>`; the web app (React) and the VS Code extension both wrap this exact package.
14
+
15
+ ## Install
16
+
17
+ ```bash
18
+ npm install @miragon/team-topologies-renderer @miragon/team-topologies-schema-model
19
+ ```
20
+
21
+ ## Three entry points
22
+
23
+ | Class | Use it for |
24
+ | ----------------- | ------------------------------------------------------------------------------ |
25
+ | `Viewer` | Read-only rendering, no interaction (thumbnails, static embeds). |
26
+ | `NavigatedViewer` | Read-only + zoom (scroll), pan (drag) and selection. |
27
+ | `Modeler` | The full editor: palette, move, resize, context pad, label editing, undo/redo. |
28
+
29
+ All three share a common base (`TtBaseViewer`) with the same import/export and lifecycle API.
30
+
31
+ ## Quick start
32
+
33
+ ```ts
34
+ import { Modeler } from "@miragon/team-topologies-renderer";
35
+ import "@miragon/team-topologies-renderer/assets/team-topologies.css";
36
+ import { SAMPLE_DOCUMENT } from "@miragon/team-topologies-schema-model";
37
+
38
+ const modeler = new Modeler({ container: document.querySelector("#canvas")! });
39
+
40
+ // Load a document (auto-fits the viewport)
41
+ const { warnings } = modeler.importDocument(SAMPLE_DOCUMENT);
42
+
43
+ // Read the live canvas back as the canonical model
44
+ const doc = modeler.exportDocument();
45
+
46
+ // Export a standalone, self-contained SVG
47
+ const { svg } = modeler.saveSVG();
48
+
49
+ // Undo / redo are driven by the command stack
50
+ modeler.undo();
51
+ modeler.redo();
52
+ ```
53
+
54
+ > **The CSS is required.** Import `@miragon/team-topologies-renderer/assets/team-topologies.css`
55
+ > (it also pulls in `diagram-js`'s own stylesheet) — without it the palette, context pad and label
56
+ > editor are unstyled.
57
+
58
+ ## API
59
+
60
+ ### Constructor — `TtViewerOptions`
61
+
62
+ ```ts
63
+ new Modeler({
64
+ container?: HTMLElement, // host element (a detached <div> if omitted)
65
+ width?: number | string, // canvas width (default "100%")
66
+ height?: number | string, // canvas height (default "100%", or "600px" with no container)
67
+ additionalModules?: ModuleDeclaration[], // extra diagram-js modules
68
+ });
69
+ ```
70
+
71
+ ### Shared methods (`Viewer` / `NavigatedViewer` / `Modeler`)
72
+
73
+ | Method | Returns | Purpose |
74
+ | ---------------------------------- | ------------------------------- | ------------------------------------------------- |
75
+ | `importDocument(doc)` | `{ warnings: ImportWarning[] }` | Replace canvas content and auto-fit. |
76
+ | `exportDocument()` | `TtDocument` | Rebuild the canonical model from the live canvas. |
77
+ | `saveSVG()` | `{ svg: string }` | Self-contained SVG snapshot (fitted viewBox). |
78
+ | `setMeta(partial)` / `getMeta()` | — / `RootBusinessObject` | Read/write diagram-level metadata (e.g. `title`). |
79
+ | `attachTo(el)` / `detach()` | `void` | Move the canvas in/out of the DOM (keeps state). |
80
+ | `clear()` / `destroy()` | `void` | Empty the canvas / tear it down. |
81
+ | `on(event, cb)` / `off(event, cb)` | `void` | Subscribe to diagram-js events. |
82
+ | `get<T>(name)` | `T` | Resolve a diagram-js service (advanced). |
83
+
84
+ ### Modeler-only
85
+
86
+ `undo()`, `redo()`, `canUndo()`, `canRedo()`.
87
+
88
+ ### Helpers & types
89
+
90
+ - **Type guards:** `isTtElement`, `isTtTeam`, `isTtInteraction`, `isTtFlow`.
91
+ - **Runtime element types:** `TtTeam`, `TtInteraction`, `TtFlow`, `TtElement`.
92
+ - **Palette icon generators:** `teamIconSvg(type)`, `interactionIconSvg(mode)`, `flowIconSvg()` —
93
+ WYSIWYG SVG glyphs matching what the canvas draws.
94
+ - **Other:** `TtViewerOptions`, `ImportWarning`, `RootBusinessObject`, `ROOT_ID`, `saveSVG`.
95
+
96
+ ## How it's built
97
+
98
+ The package is a set of [didi](https://github.com/nikku/didi) modules layered on diagram-js. Each is
99
+ exported (e.g. `ttDrawModule`, `ttPaletteModule`, `ttModelingModule`) so you can compose your own
100
+ viewer via `additionalModules`:
101
+
102
+ | Module | Responsibility |
103
+ | ---------------------- | -------------------------------------------------------------------------------- |
104
+ | `ttModelModule` | Element factory with notation defaults (`TtElementFactory`). |
105
+ | `ttDrawModule` | Custom SVG rendering of teams, interactions and flow (`TeamTopologiesRenderer`). |
106
+ | `ioModule` | Document ↔ canvas bridge (`TtImporter`, `TtExporter`, `saveSVG`). |
107
+ | `ttModelingModule` | High-level mutations — label, team type, interaction mode, colours, description. |
108
+ | `ttRulesModule` | Editing rules (what can move / resize / be created). |
109
+ | `ttBehaviorsModule` | Keeps the model **flat** — shapes never nest. |
110
+ | `ttPaletteModule` | The drag-to-create tool palette. |
111
+ | `ttContextPadModule` | Per-element actions (rename, delete). |
112
+ | `ttLabelEditingModule` | Double-click inline label editing. |
113
+ | `ttKeyboardModule` | Undo / redo / delete shortcuts. |
114
+ | `ttZOrderModule` | Fixed stacking order (flow behind, teams, interactions on top). |
115
+
116
+ ### Rendering
117
+
118
+ A custom `TeamTopologiesRenderer` (priority `1500`, beating diagram-js's default) draws each element
119
+ from the spec in [`@miragon/team-topologies-schema-model`](../schema-model): the four team outlines
120
+ (octagon, vertical/horizontal rounded rectangles, square rectangle) drawn solid; the three
121
+ interaction glyphs (parallelogram, triangle, circle) drawn dashed and translucent; the flow-of-change
122
+ as a dashed left-to-right band. Labels are word-wrapped and centred. Per-element `fill`/`stroke`
123
+ overrides win over the spec defaults.
124
+
125
+ ## Import / export
126
+
127
+ The package reads and writes the canonical `TtDocument` (JSON) and exports a standalone **SVG**.
128
+ PNG export and the embedded-scene round-trip (storing the document inside the exported image) live in
129
+ the [web app](../../apps/webapp) and the [VS Code extension](../../apps/vscode), which add the canvas
130
+ rasterisation those formats need.
131
+
132
+ ## Development
133
+
134
+ Part of the [Team Topologies Modeler](../../README.md) monorepo; consumed from source by the apps.
135
+ From the repo root:
136
+
137
+ ```bash
138
+ npm run build -w packages/renderer # Vite library build → dist/ (publish build)
139
+ npm test # Vitest unit tests
140
+ npm run test:browser # renderer integration tests in real Chromium
141
+ npm run typecheck
142
+ ```
143
+
144
+ ## License
145
+
146
+ [MIT](../../LICENSE). diagram-js and its dependencies are MIT / ISC / Apache-2.0.