vizmatic 0.1.35 → 0.1.36
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.
- package/PROMPT.md +56 -45
- package/README.md +57 -16
- package/ROADMAP.md +66 -0
- package/dist/cli.js +709 -61
- package/dist/index.cjs +694 -48
- package/dist/index.d.cts +112 -6
- package/dist/index.d.ts +112 -6
- package/dist/index.js +683 -48
- package/examples/README.md +6 -0
- package/examples/_shared/nccl-collective.tsx +420 -0
- package/examples/catalog-diagrams.tsx +13 -9
- package/examples/nccl-all-gather.tsx +14 -0
- package/examples/nccl-all-reduce.tsx +14 -0
- package/examples/nccl-all-to-all.tsx +14 -0
- package/examples/nccl-broadcast.tsx +14 -0
- package/examples/nccl-reduce-scatter.tsx +14 -0
- package/examples/system-architecture.tsx +68 -0
- package/examples/vizmatic-bare.d.ts +2 -0
- package/package.json +3 -2
package/PROMPT.md
CHANGED
|
@@ -173,69 +173,69 @@ export const watermark = (
|
|
|
173
173
|
)
|
|
174
174
|
```
|
|
175
175
|
|
|
176
|
-
Render
|
|
176
|
+
Render a sampled state timeline with `createAnimation(theme)`:
|
|
177
177
|
|
|
178
178
|
```bash
|
|
179
|
-
vizmatic gif frames/animated-pipeline.tsx --out public/vizmatic --theme dark,light --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right --scale 1
|
|
179
|
+
vizmatic gif frames/animated-pipeline.tsx --out public/vizmatic --theme dark,light --fps 20 --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right --scale 1
|
|
180
180
|
```
|
|
181
181
|
|
|
182
182
|
## Animated frames
|
|
183
183
|
|
|
184
|
-
An animated module exports `
|
|
184
|
+
An animated module exports `createAnimation(theme)` for GIF output and keeps `create(theme)` for a static or reduced-motion fallback. Define state once, then describe holds, eased transitions, instant keyframes, and parallel property tracks. Vizmatic samples absolute timeline time and renders every GIF frame.
|
|
185
185
|
|
|
186
186
|
```tsx
|
|
187
187
|
import React from "react"
|
|
188
|
-
import {
|
|
189
|
-
CalloutCard,
|
|
190
|
-
defineIllustration,
|
|
191
|
-
Flow,
|
|
192
|
-
Scene,
|
|
193
|
-
getThemeColors,
|
|
194
|
-
type AnimatedScene,
|
|
195
|
-
type ThemeColors,
|
|
196
|
-
type ThemeMode,
|
|
197
|
-
} from "vizmatic"
|
|
188
|
+
import { Scene, defineAnimation, getThemeColors, hold, keyframe, tween, type ThemeMode } from "vizmatic"
|
|
198
189
|
|
|
199
190
|
export const width = 1040
|
|
200
191
|
export const height = 560
|
|
201
192
|
|
|
202
|
-
|
|
203
|
-
{ title: "Prompt", tone: "blue" as const },
|
|
204
|
-
{ title: "Scene spec", tone: "purple" as const },
|
|
205
|
-
{ title: "PNG / GIF", tone: "green" as const },
|
|
206
|
-
]
|
|
193
|
+
type State = { operation: number; progress: number }
|
|
207
194
|
|
|
208
|
-
function buildFrame(
|
|
195
|
+
function buildFrame(theme: ThemeMode, state: State) {
|
|
196
|
+
const c = getThemeColors(theme)
|
|
209
197
|
return (
|
|
210
|
-
<Scene c={c} title="
|
|
211
|
-
<
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
198
|
+
<Scene c={c} title={state.operation === 0 ? "Broadcast" : "AllReduce"}>
|
|
199
|
+
<div style={{ display: "flex", width: "100%", height: 260, position: "relative" }}>
|
|
200
|
+
<div style={{
|
|
201
|
+
display: "flex",
|
|
202
|
+
position: "absolute",
|
|
203
|
+
left: 40 + state.progress * 720,
|
|
204
|
+
top: 90,
|
|
205
|
+
padding: "10px 16px",
|
|
206
|
+
borderRadius: 8,
|
|
207
|
+
background: c.accent,
|
|
208
|
+
color: c.textOnColor,
|
|
209
|
+
}}>chunk</div>
|
|
210
|
+
</div>
|
|
220
211
|
</Scene>
|
|
221
212
|
)
|
|
222
213
|
}
|
|
223
214
|
|
|
224
|
-
|
|
215
|
+
export function createAnimation(theme: ThemeMode) {
|
|
216
|
+
return defineAnimation<State>({
|
|
217
|
+
initial: { operation: 0, progress: 0 },
|
|
218
|
+
timeline: [
|
|
219
|
+
hold(500, "Broadcast input"),
|
|
220
|
+
tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "Broadcast" }),
|
|
221
|
+
hold(500, "Broadcast output"),
|
|
222
|
+
keyframe({ operation: 1, progress: 0 }),
|
|
223
|
+
tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "AllReduce" }),
|
|
224
|
+
],
|
|
225
|
+
fps: 20,
|
|
226
|
+
render: (state) => buildFrame(theme, state),
|
|
227
|
+
})
|
|
228
|
+
}
|
|
225
229
|
|
|
226
|
-
export function
|
|
227
|
-
|
|
228
|
-
return stages.map((_, index) => ({
|
|
229
|
-
element: buildFrame(c, index),
|
|
230
|
-
duration: index === stages.length - 1 ? 1000 : 700,
|
|
231
|
-
transition: index === 0 ? "appear" : "fade",
|
|
232
|
-
}))
|
|
230
|
+
export function create(theme: ThemeMode = "dark") {
|
|
231
|
+
return buildFrame(theme, { operation: 1, progress: 1 })
|
|
233
232
|
}
|
|
234
233
|
|
|
235
|
-
export
|
|
236
|
-
export default frame.default
|
|
234
|
+
export default create("dark")
|
|
237
235
|
```
|
|
238
236
|
|
|
237
|
+
Top-level timeline steps run sequentially. Properties inside one `tween` move together. Use `parallel({ x: [...], opacity: [...] })` when property tracks need different delays or durations. Default interpolation supports finite numbers; use a custom `interpolate(from, to, progress)` for colors, points, or other values. `createScenes(theme)` remains supported for deliberate scene cuts and pixel `fade`/`appear` transitions.
|
|
238
|
+
|
|
239
239
|
## Choose primitives
|
|
240
240
|
|
|
241
241
|
Use Vizmatic primitives for common layouts. Use raw SVG only for geometry the component set cannot express.
|
|
@@ -274,7 +274,7 @@ Cards, labels, and compact UI:
|
|
|
274
274
|
- `TextLabel`: `text`, `c`, `variant?: keyof typography = "body"`, `color?`, `fontSize?`, `fontWeight?`, `width?`, `align?: "left" | "center" | "right" = "left"`, `math?: boolean = false`, `mono?: boolean = false`.
|
|
275
275
|
- `MathText`: `text`. Returns formatted unicode-ish math text for simple `_` and `^` notation.
|
|
276
276
|
- `formatMathText(text)`: `text: string`.
|
|
277
|
-
- `Icon`: `name`, `c`, `tone?: ToneName = "blue"`, `color?`, `size?: number = 24`, `strokeWidth?: number = 2`, `label?`, `muted?: boolean = false`. `IconName
|
|
277
|
+
- `Icon`: `name`, `c`, `tone?: ToneName = "blue"`, `color?`, `size?: number = 24`, `strokeWidth?: number = 2`, `label?`, `muted?: boolean = false`. `IconName` includes presentation icons plus architecture icons: `browser`, `bucket`, `cache`, `cloud`, `cluster`, `container`, `database`, `firewall`, `gateway`, `load-balancer`, `mobile`, `monitor`, `network`, `queue`, `server`, `storage`, `stream`, and `user`.
|
|
278
278
|
- `ToneStrip`: `tone`, `width?: number = 34`, `height?: number = 4`.
|
|
279
279
|
- `StepCard`: `title`, `c`, `subtitle?`, `eyebrow?`, `tone?: ToneName = "blue"`, `width?: number | string = 210`, `minWidth?`, `minHeight?: number | string = 74`, `padding?: number | string = "12px 14px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "center"`, `math?: boolean = false`.
|
|
280
280
|
- `MetricCard`: `label`, `value`, `c`, `tone?: ToneName = "blue"`, `detail?`, `width?`, `minWidth?`, `minHeight?: number | string = 74`, `padding?: number | string = "10px 12px"`, `radius?: number = 8`, `shadow?: boolean = true`, `align?: "left" | "center" = "center"`, `math?: boolean = false`, `valueMono?: boolean = true`, `valueFontSize?: number = 22`, `valueColor?`.
|
|
@@ -314,7 +314,9 @@ Flows and process diagrams:
|
|
|
314
314
|
Graphs and networks:
|
|
315
315
|
|
|
316
316
|
- `LayeredNetwork`: `c`, `layers: LayeredNetworkLayer[]`, `activePath?: number[] = []`, `annotations?: string[] = []`, `formula?`, `legend?: string = "highlighted path"`, `width?: number = 900`, `height?: number = 400`, `nodeSize?: number = 56`, `showFormula?: boolean = true`. `LayeredNetworkLayer`: `title`, `nodes: string[]`, `tone?`.
|
|
317
|
-
- `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `labelFontSize?: number = 14`, `detailFontSize?: number = 11`, `arrowSize?: number = 5`, `padding?: number = 28`, `layout?: "auto" | "manual"`, `direction?: "LR" | "RL" | "TB" | "BT" = "LR"`, `nodeGap?: number = 34`, `rankGap?: number = 64`, `edgeGap?: number = 14`, `sizing?: "content" | "fixed" = "content"
|
|
317
|
+
- `GraphDiagram`: `nodes: GraphDiagramNode[]`, `edges: GraphDiagramEdge[]`, `groups?: GraphDiagramGroup[]`, `c`, `width?: number = 520`, `height?: number = 420`, `nodeWidth?: number = 150`, `nodeHeight?: number = 66`, `labelFontSize?: number = 14`, `detailFontSize?: number = 11`, `arrowSize?: number = 5`, `padding?: number = 28`, `layout?: "auto" | "manual"`, `direction?: "LR" | "RL" | "TB" | "BT" = "LR"`, `nodeGap?: number = 34`, `rankGap?: number = 64`, `edgeGap?: number = 14`, `sizing?: "content" | "fixed" = "content"`, `iconSize?: number = 20`, `ariaLabel?`. `GraphDiagramNode`: `id`, `label`, `detail?`, `x?`, `y?`, `tone?`, `muted?`, `width?`, `height?`, `group?`, `icon?: IconName | DiagramIconDefinition | ReactElement`, `iconSize?`. Icon size is clamped inside its node; custom React elements own their theme colors and accessible label. `GraphDiagramGroup`: `id`, `label`, `detail?`, `parent?`, `tone?`, `muted?`. Groups nest through `parent` and require automatic layout. Omit coordinates on every node for automatic layout; array order is the stable tie-breaker and dimensions expand to fit unless `sizing="fixed"`. Set both coordinates on every node for manual normalized positioning when no groups are present. Mixed coordinate modes fail. `GraphDiagramEdge`: `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`, `kind?: "sync" | "async" | "event" | "data" | "dependency" | "association"`, `style?: "solid" | "dashed" | "dotted"`, `arrow?: "forward" | "backward" | "both" | "none"`. Association edges default to no arrow.
|
|
318
|
+
- `defineDiagramIcon(id, render)`: defines a reusable custom graph icon. `render` receives `c`, `color`, `size`, and optional `label`.
|
|
319
|
+
- `defineIconRegistry(icons)`: preserves typed names for a set of custom or provider icons without global mutable state.
|
|
318
320
|
- `TreeDiagram`: `root: TreeNodeSpec`, `c`, `title?`, `subtitle?`, `width?`, `height?`, `nodeWidth?: number = 156`, `nodeHeight?: number = 64`, `levelGap?: number = 58`, `siblingGap?: number = 24`, `padding?: number = 28`, `math?: boolean = false`. `TreeNodeSpec`: `label`, `id?`, `detail?`, `tone?`, `muted?`, `children?`.
|
|
319
321
|
|
|
320
322
|
Matrices and heatmaps:
|
|
@@ -376,10 +378,19 @@ Theme and render APIs:
|
|
|
376
378
|
- `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `theme?: "dark" | "light" = "dark"` for direct-render watermark defaults, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean | "height" | "both" = true`, `scale?: number = 2`. Default autocrop retains 24 source pixels around detected content. Use `crop: "height"` when host layouts require stable width but should still trim extra vertical whitespace.
|
|
377
379
|
- `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`, `scale?`.
|
|
378
380
|
- `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `theme?`, `watermark?`, `brand?`.
|
|
379
|
-
- `
|
|
381
|
+
- `defineAnimation({ initial, timeline, render, fps? })`: creates deterministic typed state animation. `fps` defaults to `20` and accepts integers from `1` to `50`.
|
|
382
|
+
- `hold(duration, label?)`: keep current state for milliseconds.
|
|
383
|
+
- `tween(to, { duration, easing?, interpolate?, label? })`: transition listed properties together. Easing is `"linear" | "ease-in" | "ease-out" | "ease-in-out"` or pure progress function.
|
|
384
|
+
- `keyframe(value, label?)`: apply instant partial state update.
|
|
385
|
+
- `parallel(tracks, label?)`: run property tracks concurrently; each track accepts `hold`, `tween`, and `keyframe` steps.
|
|
386
|
+
- `sampleAnimation(animation, time)`: evaluate state at exact millisecond.
|
|
387
|
+
- `sampleAnimationFrames(animation, { fps? })`: return deterministic state/frame samples with GIF-compatible delays.
|
|
388
|
+
- `renderAnimationGif(animation, options)`: stream timeline samples into GIF.
|
|
389
|
+
- `renderAnimationGifWithOutput(animation, options)`: same arguments and returns physical `width` and `height`.
|
|
390
|
+
- `renderAnimatedGif(scenes, options)`: legacy `AnimatedScene[]` renderer for scene cuts and pixel transitions. It also accepts a defined animation.
|
|
380
391
|
- `renderAnimatedGifWithOutput(scenes, options)`: same arguments as `renderAnimatedGif`; returns physical `width` and `height`.
|
|
381
392
|
- `AnimatedScene`: `element`, `duration` in ms, `transition?: "none" | "fade" | "appear"`, `transitionDuration?`, `label?`.
|
|
382
|
-
- `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `background?: "theme" | "transparent" | CSS color = "theme"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`. Transparent GIFs use one-bit transparency; use PNG/SVG when smooth alpha edges matter.
|
|
393
|
+
- `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `fps?: number`, `background?: "theme" | "transparent" | CSS color = "theme"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`. Transparent GIFs use one-bit transparency; use PNG/SVG when smooth alpha edges matter.
|
|
383
394
|
|
|
384
395
|
## Prop-aware examples
|
|
385
396
|
|
|
@@ -464,10 +475,10 @@ height = 560;
|
|
|
464
475
|
- Prefer alpha-transparent PNG/SVG backgrounds for blog embeds and docs cards. Use theme backgrounds only when the host surface is unknown or needs full-frame fill.
|
|
465
476
|
- Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` to keep layout stable.
|
|
466
477
|
- Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
|
|
467
|
-
- Omit `x` and `y` from `GraphDiagram` nodes for automatic layered layout. Add both only when
|
|
478
|
+
- Omit `x` and `y` from `GraphDiagram` nodes for automatic layered layout and nested groups. Add both only when an ungrouped graph needs editorial manual control.
|
|
468
479
|
- Render reusable assets in both themes with `--theme dark,light`.
|
|
469
480
|
- Run `vizmatic check <frame> --theme dark,light --json` before final render and fix every error.
|
|
470
|
-
- Use GIF only when motion explains state change.
|
|
481
|
+
- Use GIF only when motion explains state change. Prefer `createAnimation(theme)` with `hold` and `tween`, keep timelines short, and keep static `create(theme)` fallback. Use `createScenes(theme)` only for deliberate cuts or crossfades.
|
|
471
482
|
- If render fails with `Canvas overflow detected`, increase the canvas, reduce content, or remove strict sizing. Do not ignore the error.
|
|
472
483
|
- Confirm generated files exist and open at least one image before finishing.
|
|
473
484
|
|
package/README.md
CHANGED
|
@@ -134,7 +134,7 @@ Each output directory includes `manifest.json`. `outputs` lists generated files,
|
|
|
134
134
|
Render an animation:
|
|
135
135
|
|
|
136
136
|
```bash
|
|
137
|
-
vizmatic gif ./animated-frame.tsx --out ./dist/frames --theme dark,light --watermark "Acme" --watermark-image ./logo.svg
|
|
137
|
+
vizmatic gif ./animated-frame.tsx --out ./dist/frames --theme dark,light --fps 20 --watermark "Acme" --watermark-image ./logo.svg
|
|
138
138
|
```
|
|
139
139
|
|
|
140
140
|
Or call the renderer directly:
|
|
@@ -180,13 +180,19 @@ Vizmatic provides reusable layout, diagram, and chart primitives:
|
|
|
180
180
|
| Headless rendering | Node produces assets directly in local workflows and CI |
|
|
181
181
|
| Theme variants | One command renders dark and light output from semantic color tokens |
|
|
182
182
|
| Layout checks | Overflow, contrast, small text, label overlap, uneven panel whitespace, and connector congestion |
|
|
183
|
-
| Animation |
|
|
183
|
+
| Animation | Typed state timelines, tweens, easing, holds, keyframes, and parallel tracks export as GIFs |
|
|
184
184
|
|
|
185
185
|
## Gallery
|
|
186
186
|
|
|
187
187
|
<p>
|
|
188
188
|
<img src="https://bvolpato.github.io/vizmatic/assets/examples/animated-pipeline_dark.gif" alt="Animated pipeline" width="380" />
|
|
189
|
-
<img src="https://bvolpato.github.io/vizmatic/assets/examples/
|
|
189
|
+
<img src="https://bvolpato.github.io/vizmatic/assets/examples/nccl-broadcast_dark.gif" alt="Animated NCCL Broadcast: root rank sends one buffer to every rank" width="300" />
|
|
190
|
+
<img src="https://bvolpato.github.io/vizmatic/assets/examples/nccl-all-reduce_dark.gif" alt="Animated NCCL AllReduce: every rank reduces values and receives the sum" width="300" />
|
|
191
|
+
</p>
|
|
192
|
+
<p>
|
|
193
|
+
<img src="https://bvolpato.github.io/vizmatic/assets/examples/nccl-all-gather_dark.gif" alt="Animated NCCL AllGather: every rank receives concatenated tensors" width="300" />
|
|
194
|
+
<img src="https://bvolpato.github.io/vizmatic/assets/examples/nccl-reduce-scatter_dark.gif" alt="Animated NCCL ReduceScatter: each rank receives one reduced chunk" width="300" />
|
|
195
|
+
<img src="https://bvolpato.github.io/vizmatic/assets/examples/nccl-all-to-all_dark.gif" alt="Animated NCCL AllToAll: every rank exchanges one chunk with every rank" width="300" />
|
|
190
196
|
</p>
|
|
191
197
|
<p>
|
|
192
198
|
<img src="https://bvolpato.github.io/vizmatic/assets/examples/rag-graph_dark.png" alt="RAG graph" width="380" />
|
|
@@ -197,10 +203,13 @@ Vizmatic provides reusable layout, diagram, and chart primitives:
|
|
|
197
203
|
<img src="https://bvolpato.github.io/vizmatic/assets/examples/theme-system_dark.png" alt="Theme system" width="380" />
|
|
198
204
|
</p>
|
|
199
205
|
<p>
|
|
206
|
+
<img src="https://bvolpato.github.io/vizmatic/assets/examples/system-architecture_dark.png" alt="System architecture" width="380" />
|
|
200
207
|
<img src="https://bvolpato.github.io/vizmatic/assets/examples/presentation-frame_dark.png" alt="Presentation frame" width="380" />
|
|
201
208
|
</p>
|
|
202
209
|
|
|
203
|
-
|
|
210
|
+
NCCL gallery examples cover five operations: Broadcast, AllReduce, AllGather, ReduceScatter, and AllToAll. Their diagrams follow NVIDIA's documented [collective operation semantics](https://docs.nvidia.com/deeplearning/nccl/user-guide/docs/usage/collectives.html): rooted transfer, reduction, rank-ordered gathering, reduced chunk ownership, and pairwise exchange.
|
|
211
|
+
|
|
212
|
+
More examples live in [`examples/`](examples). The website has a searchable [component catalog](https://bvolpato.github.io/vizmatic/components.html) with a rendered preview and source for every public component. [`PROMPT.md`](PROMPT.md) contains the full install, syntax, component, and verification reference for coding agents. [`ROADMAP.md`](ROADMAP.md) tracks C4, provider packs, sequence, UML, deployment, network, dataflow, layout, and interoperability work.
|
|
204
213
|
|
|
205
214
|
## Repository checks
|
|
206
215
|
|
|
@@ -317,26 +326,33 @@ Use these primitives before writing raw SVG or absolute-positioned layouts.
|
|
|
317
326
|
| `Flow` | Horizontal or vertical staged process diagram with optional detail rows. |
|
|
318
327
|
| `Pipeline` | Process pipeline with stage labels and a shared title. |
|
|
319
328
|
| `LayeredNetwork` | Neural-network/DAG diagram with layers, nodes, active path, annotations, and formula. |
|
|
320
|
-
| `GraphDiagram` | Auto-laid
|
|
329
|
+
| `GraphDiagram` | Auto-laid architecture graph with nested boundaries, technical icons, typed relationships, and custom icon definitions. |
|
|
321
330
|
| `TreeDiagram` | Auto-laid parent/child hierarchy for ownership, routing, taxonomy, and decision trees. |
|
|
322
331
|
|
|
323
|
-
`GraphDiagram` uses deterministic layered layout when node coordinates are omitted:
|
|
332
|
+
`GraphDiagram` uses deterministic layered layout when node coordinates are omitted. Groups become nested system boundaries, while built-in technical icons keep common architecture nodes concise:
|
|
324
333
|
|
|
325
334
|
```tsx
|
|
326
335
|
<GraphDiagram
|
|
336
|
+
ariaLabel="Checkout architecture"
|
|
337
|
+
groups={[
|
|
338
|
+
{ id: "prod", label: "Production", tone: "blue" },
|
|
339
|
+
{ id: "data", label: "Data", parent: "prod", tone: "green" },
|
|
340
|
+
]}
|
|
327
341
|
nodes={[
|
|
328
|
-
{ id: "
|
|
329
|
-
{ id: "
|
|
330
|
-
{ id: "
|
|
342
|
+
{ id: "client", label: "Client", icon: "browser", tone: "cyan" },
|
|
343
|
+
{ id: "api", label: "API", icon: "server", group: "prod", tone: "purple" },
|
|
344
|
+
{ id: "db", label: "Postgres", icon: "database", group: "data", tone: "green" },
|
|
331
345
|
]}
|
|
332
346
|
edges={[
|
|
333
|
-
{ from: "
|
|
334
|
-
{ from: "
|
|
347
|
+
{ from: "client", to: "api", label: "HTTPS", kind: "sync" },
|
|
348
|
+
{ from: "api", to: "db", label: "SQL", kind: "data", arrow: "both" },
|
|
335
349
|
]}
|
|
336
350
|
/>
|
|
337
351
|
```
|
|
338
352
|
|
|
339
|
-
|
|
353
|
+
Groups support unlimited nesting in automatic layout, reserve a boundary-header gutter, and clip long headers inside the boundary. Set `icon` to a built-in `IconName`, a React element, or a reusable icon from `defineDiagramIcon`; `defineIconRegistry` groups provider packs without a runtime registry. Icon size stays inside its node. Custom React elements own their theme colors and accessible label. Relationship `kind` selects solid, dashed, or dotted defaults, `style` overrides them, and `arrow` accepts `forward`, `backward`, `both`, or `none`. Associations default to no arrow.
|
|
354
|
+
|
|
355
|
+
Set `x` and `y` on every node for normalized manual positioning when no groups are present. Mixed coordinate modes fail with a clear error. Automatic layout treats node and edge array order as its stable tie-breaker and expands `width` or `height` when needed. Set `sizing="fixed"` to keep exact graph dimensions and let overflow checks report a canvas that is too small. Use `direction`, `nodeGap`, `rankGap`, and `edgeGap` to tune the result.
|
|
340
356
|
|
|
341
357
|
#### Matrices, tables, and grids
|
|
342
358
|
|
|
@@ -371,6 +387,10 @@ Set `x` and `y` on every node for normalized manual positioning. Mixed coordinat
|
|
|
371
387
|
| `renderToPngWithOutput` | Render PNG and return logical plus physical pixel dimensions. |
|
|
372
388
|
| `renderAnimatedGif` | Render ordered `AnimatedScene[]` states to GIF with `fade`, `appear`, or no transition. |
|
|
373
389
|
| `renderAnimatedGifWithOutput` | Render GIF and return its physical pixel dimensions. |
|
|
390
|
+
| `defineAnimation` | Define a typed state timeline rendered at deterministic sample times. |
|
|
391
|
+
| `hold`, `tween`, `keyframe`, `parallel` | Compose sequential pauses, eased property transitions, instant state changes, and staggered concurrent tracks. |
|
|
392
|
+
| `sampleAnimation` | Evaluate timeline state at an exact millisecond without rendering. |
|
|
393
|
+
| `renderAnimationGif` | Stream sampled timeline frames into a GIF without retaining every RGBA frame. |
|
|
374
394
|
| `renderToBuffer` | Render PNG to memory for tests and pipelines. |
|
|
375
395
|
| `renderToSvg` | Render SVG markup directly. |
|
|
376
396
|
| `Watermark` | JSX marker component for expressive frame-module watermarks. |
|
|
@@ -389,7 +409,7 @@ Theme and chart helpers are public for custom primitives: `getReadableColor(name
|
|
|
389
409
|
### Rendering
|
|
390
410
|
|
|
391
411
|
```ts
|
|
392
|
-
import { renderAnimatedGif, renderToPng, renderToBuffer, renderToSvg } from "vizmatic"
|
|
412
|
+
import { renderAnimatedGif, renderAnimationGif, renderToPng, renderToBuffer, renderToSvg } from "vizmatic"
|
|
393
413
|
```
|
|
394
414
|
|
|
395
415
|
`renderToPng` renders at 2x scale, checks for clipping, and crops extra whitespace while keeping 24 source pixels around detected content. Output stays transparent unless `background` is set.
|
|
@@ -423,19 +443,40 @@ export const watermark = (
|
|
|
423
443
|
)
|
|
424
444
|
```
|
|
425
445
|
|
|
426
|
-
`
|
|
446
|
+
Prefer `defineAnimation` when values should move, resize, or fade continuously. Timeline array runs sequentially; every property in one `tween` moves in parallel. `parallel` adds independent property tracks for staggered or overlapping motion. Renderer samples absolute time deterministically and includes exact terminal state. Keep `create(theme)` as static fallback for PNG, docs previews, and reduced-motion users.
|
|
447
|
+
|
|
448
|
+
```tsx
|
|
449
|
+
import { defineAnimation, hold, keyframe, tween } from "vizmatic"
|
|
450
|
+
|
|
451
|
+
export function createAnimation(theme: ThemeMode) {
|
|
452
|
+
return defineAnimation({
|
|
453
|
+
initial: { operation: 0, progress: 0 },
|
|
454
|
+
timeline: [
|
|
455
|
+
hold(500, "Broadcast input"),
|
|
456
|
+
tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "Transfer" }),
|
|
457
|
+
hold(500, "Broadcast output"),
|
|
458
|
+
keyframe({ operation: 1, progress: 0 }),
|
|
459
|
+
tween({ progress: 1 }, { duration: 900, easing: "ease-in-out", label: "AllReduce" }),
|
|
460
|
+
],
|
|
461
|
+
fps: 20,
|
|
462
|
+
render: (state, frame) => buildFrame(theme, state, frame),
|
|
463
|
+
})
|
|
464
|
+
}
|
|
465
|
+
```
|
|
427
466
|
|
|
428
467
|
```ts
|
|
429
|
-
await
|
|
468
|
+
await renderAnimationGif(createAnimation("dark"), {
|
|
430
469
|
width: 1040,
|
|
431
470
|
height: 560,
|
|
432
|
-
outputPath: "dist/
|
|
471
|
+
outputPath: "dist/collective.gif",
|
|
433
472
|
watermark: { text: "Your Product", image: "data:image/png;base64,...", position: "bottom-right" },
|
|
434
473
|
theme: "dark",
|
|
435
474
|
scale: 1,
|
|
436
475
|
})
|
|
437
476
|
```
|
|
438
477
|
|
|
478
|
+
`createScenes(theme)` and `renderAnimatedGif(AnimatedScene[])` remain supported for intentional scene cuts and pixel crossfades. GIF output uses centisecond timing, at most 256 colors per frame, and one-bit transparency. Use PNG/SVG for smooth alpha edges.
|
|
479
|
+
|
|
439
480
|
## Development
|
|
440
481
|
|
|
441
482
|
```bash
|
package/ROADMAP.md
ADDED
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
# Technical diagram roadmap
|
|
2
|
+
|
|
3
|
+
Vizmatic aims to make polished technical diagrams easy from TSX while keeping rendering deterministic, offline-capable, theme-aware, and composable with charts or presentation frames.
|
|
4
|
+
|
|
5
|
+
Benchmarks: [Diagrams](https://diagrams.mingrammer.com/), [D2](https://d2lang.com/), [Structurizr](https://docs.structurizr.com/), [Mermaid](https://mermaid.js.org/), and [PlantUML](https://plantuml.com/).
|
|
6
|
+
|
|
7
|
+
## Available now
|
|
8
|
+
|
|
9
|
+
- Deterministic Dagre layout in four directions.
|
|
10
|
+
- Nested system boundaries through `GraphDiagram.groups`.
|
|
11
|
+
- Built-in generic icons for users, clients, services, infrastructure, data, networks, and operations.
|
|
12
|
+
- Reusable custom icon definitions and typed icon registries.
|
|
13
|
+
- Labeled synchronous, asynchronous, event, data, dependency, and association relationships.
|
|
14
|
+
- Solid, dashed, and dotted connectors with forward, backward, bidirectional, or no arrows.
|
|
15
|
+
- Manual positioning for ungrouped editorial diagrams.
|
|
16
|
+
- Connector diagnostics for crossings, label collisions, crowded endpoints, and parallel routes.
|
|
17
|
+
- Dark, light, and Engineering visual presets with PNG, SVG, and GIF output.
|
|
18
|
+
- Typed state timelines with holds, eased tweens, keyframes, parallel tracks, deterministic sampling, and streamed GIF encoding.
|
|
19
|
+
|
|
20
|
+
## Next capability batches
|
|
21
|
+
|
|
22
|
+
### Architecture model and views
|
|
23
|
+
|
|
24
|
+
- C4 person, software system, container, component, and deployment semantics.
|
|
25
|
+
- One reusable model with context, container, component, deployment, and dynamic views.
|
|
26
|
+
- Named views, filtered views, legends, tags, and technology metadata.
|
|
27
|
+
- Drill-down links and stable element identifiers in SVG output.
|
|
28
|
+
|
|
29
|
+
### Technical icon packs
|
|
30
|
+
|
|
31
|
+
- Build-time generated GCP and Kubernetes packs from pinned Apache-2.0 Iconify data.
|
|
32
|
+
- Optional provider modules so unused icons do not increase core bundle size.
|
|
33
|
+
- Asset metadata with source, version, license, and trademark notice.
|
|
34
|
+
- User-supplied AWS and Azure adapters until redistribution terms support bundled packs.
|
|
35
|
+
- No default runtime icon API or network dependency.
|
|
36
|
+
|
|
37
|
+
### Interaction and software design
|
|
38
|
+
|
|
39
|
+
- Sequence diagrams with participants, lifelines, activations, sync/async/return messages, notes, and `alt`/`loop`/`parallel` fragments.
|
|
40
|
+
- UML class and component diagrams with compartments, inheritance, aggregation, composition, multiplicity, and stereotypes.
|
|
41
|
+
- State machines with nested states, guards, entry/exit actions, and parallel regions.
|
|
42
|
+
- ER diagrams with tables, fields, keys, data types, and cardinality-aware relationships.
|
|
43
|
+
|
|
44
|
+
### Infrastructure and data systems
|
|
45
|
+
|
|
46
|
+
- Deployment and network views with regions, zones, VPCs, subnets, namespaces, hosts, ports, protocols, trust boundaries, and ingress/egress.
|
|
47
|
+
- Dataflow and lineage views with sources, sinks, stores, transformations, schemas, and batch/stream semantics.
|
|
48
|
+
- Swimlanes and activity diagrams for ownership, handoffs, conditions, and parallel work.
|
|
49
|
+
|
|
50
|
+
### Layout and rendering
|
|
51
|
+
|
|
52
|
+
- Named ports and endpoint anchors.
|
|
53
|
+
- Orthogonal, curved, and user-routed connectors with parallel-edge separation.
|
|
54
|
+
- Layout adapter interface with Dagre as default and ELK as optional backend.
|
|
55
|
+
- Per-boundary direction, collapsed groups, named scenarios, and reusable animation compositions.
|
|
56
|
+
- Tooltips, links, and accessible structured descriptions in SVG.
|
|
57
|
+
- Import/export adapters for Mermaid, D2, Structurizr, Kubernetes, and Terraform where semantics map safely.
|
|
58
|
+
|
|
59
|
+
## Design constraints
|
|
60
|
+
|
|
61
|
+
- Keep current `GraphDiagram` input backward compatible.
|
|
62
|
+
- Compile specialized diagram APIs into shared typed models instead of separate rendering stacks.
|
|
63
|
+
- Keep default rendering deterministic and offline.
|
|
64
|
+
- Treat provider licensing and trademarks as product requirements.
|
|
65
|
+
- Add tests for behavior contracts and regressions, not source-text presence.
|
|
66
|
+
- Ship each capability with dark/light reference renders, docs, and diagnostics.
|