vizmatic 0.2.0 → 0.3.1
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 +13 -0
- package/README.md +76 -1
- package/ROADMAP.md +4 -2
- package/assets/THIRD_PARTY_LICENSES.md +3 -0
- package/dist/cli.js +33 -12433
- package/dist/index.cjs +1095 -189
- package/dist/index.d.cts +80 -7
- package/dist/index.d.ts +80 -7
- package/dist/index.js +1088 -188
- package/examples/README.md +4 -0
- package/examples/orthogonal-routing.tsx +25 -0
- package/examples/pareto-bar-chart.tsx +44 -0
- package/examples/pie-chart.tsx +46 -0
- package/examples/website-workflow.tsx +38 -0
- package/package.json +11 -8
package/PROMPT.md
CHANGED
|
@@ -39,6 +39,8 @@ vizmatic check ./frame.tsx --theme dark,light --json
|
|
|
39
39
|
|
|
40
40
|
Fix all errors before the final render. Warnings report low contrast, text below 11px, overlapping labels, uneven panel whitespace, connector congestion, and asset fallbacks. Overflow errors name the affected edges and suggest dimensions.
|
|
41
41
|
|
|
42
|
+
The [browser playground](https://bvolpato.github.io/vizmatic/playground.html) supports component composition, inline text edits, undo/redo, and local drafts. Choose Freeform canvas for positioned `Board` / `CanvasItem` editing with move and resize handles and snapping. Structured editors cover pie segments, bar categories, scatter points, table cells, line series, interval data, and graph nodes/edges/groups; computed data stays in TSX. Save project writes a named `.vizmatic.json` file containing source, output theme, and canvas background, and Open project restores it. PNG/SVG exports preserve the full canvas.
|
|
43
|
+
|
|
42
44
|
For scenes already created inside a build or editor, use the typed `checkFrame` API instead of writing a frame file and launching the CLI. Pass a React element as `scene` or use `create(theme)` for theme-specific scenes. Set `failOn` to `"warning"` when warnings should fail CI. Reports include per-theme dimensions and diagnostics with stable codes plus element IDs or rendered locations where available. Use `vizmatic check <files> --json` when the CLI should discover and load frame modules.
|
|
43
45
|
|
|
44
46
|
## Install in a project
|
|
@@ -134,6 +136,8 @@ vizmatic frames --out public/vizmatic --theme dark,light --watermark "Your Produ
|
|
|
134
136
|
|
|
135
137
|
Generated `manifest.json` includes each output file plus its theme, path, width, and height.
|
|
136
138
|
|
|
139
|
+
The static CLI defaults to PNG. Add `--format svg` for vector output or `--format both` to render PNG and SVG together in every requested theme.
|
|
140
|
+
|
|
137
141
|
PNG and SVG renders have transparent backgrounds by default. Use the theme background when the image needs an opaque canvas:
|
|
138
142
|
|
|
139
143
|
```bash
|
|
@@ -262,6 +266,8 @@ Frame helpers:
|
|
|
262
266
|
|
|
263
267
|
- `defineIllustration(build, defaultTheme?)`: `build: (c: ThemeColors) => ReactElement`, `defaultTheme?: ThemeMode = "dark"`. Returns `{ create(theme), default }`.
|
|
264
268
|
- `Canvas`: `children?`, `c`, `padding?: number = 40`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "center"`, `background?: string`. Default root background is alpha-transparent during PNG/SVG rendering.
|
|
269
|
+
- `Board`: `children?`, `c`, `width?: number = 960`, `height?: number = 540`, `background?: string`. Fixed relative canvas with a transparent default background; clips content outside its bounds. Match frame dimensions to the board. Dimensions must be finite, greater than zero, and at most 8192.
|
|
270
|
+
- `CanvasItem`: `children?`, `x: number`, `y: number`, `width?: number`, `height?: number`. Absolute position in logical board pixels. Coordinates must be finite. Explicit dimensions must be greater than zero and at most 8192; they supply the child's width/height props. With both dimensions set, chart primitives scale proportionally to fit their complete plotting layer, headings, legends, and footer inside the item. Use literal coordinates and dimensions for preview move/resize controls.
|
|
265
271
|
- `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`. Title/subtitle are optional and the title bar is omitted when no title is provided. Use `background={c.bg}` for an opaque theme frame.
|
|
266
272
|
- `TitleBar`: `title`, `subtitle?`, `c`.
|
|
267
273
|
|
|
@@ -318,10 +324,15 @@ Flows and process diagrams:
|
|
|
318
324
|
Graphs and networks:
|
|
319
325
|
|
|
320
326
|
- `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?`.
|
|
327
|
+
- `GraphDiagram` routing options: `routing?: "dagre" | "straight" | "orthogonal" = "dagre"`, `routingClearance?: number = 12`. Dagre preserves existing routes; straight connects facing node sides; orthogonal avoids node boxes and group headers with right-angle paths. Node layout remains automatic or manual independently of routing. `GraphDiagramNode` additionally accepts `ports?: GraphDiagramPort[]`; a port is `{ id: string, side: "top" | "right" | "bottom" | "left", offset?: number = 0.5 }`. Offset is finite and in `[0, 1]`, running left to right or top to bottom. `GraphDiagramEdge` additionally accepts `fromPort?`, `toPort?`, `fromSide?`, and `toSide?`. An endpoint cannot combine a port reference with a side. Explicit anchors opt an edge into orthogonal geometry even in Dagre mode. Missing references, duplicate port IDs, and invalid offsets fail validation.
|
|
328
|
+
|
|
329
|
+
- Orthogonal routing separates parallel relationships, supports self-loops with distinct endpoint anchors, and uses `edgeGap` for lane spacing. It runs offline with limits of 64 node/header obstacles, 256 edges, 18,000 grid points per search, 54,000 search states per search, and 160,000 search states per diagram. A blocked path, unavailable separate lane, same-anchor self-loop, or exhausted limit omits that connector and emits a checker error with code `layout.connector_unroutable`. Increase canvas size or spacing, choose different sides/ports, or reduce clearance; do not publish missing connectors. See `examples/orthogonal-routing.tsx`.
|
|
330
|
+
|
|
321
331
|
- `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`, `id?`, `ariaLabel?`, `title?`, `description?`. `GraphDiagramNode`: `id`, `label`, `detail?`, `href?`, `title?`, `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`: `id?`, `from`, `to`, `tone?`, `muted?`, `dashed?`, `label?`, `href?`, `title?`, `kind?: "sync" | "async" | "event" | "data" | "dependency" | "association"`, `style?: "solid" | "dashed" | "dotted"`, `arrow?: "forward" | "backward" | "both" | "none"`. Association edges default to no arrow. `title`, `description`, and `id` add structured SVG metadata and deterministic graph, node, and edge IDs. Nodes and edges can link to HTTP(S), `mailto:`, `tel:`, fragment, or relative URLs; unsupported schemes fail. Use these properties for `renderToSvg` and playground SVG downloads.
|
|
322
332
|
- `SequenceDiagram`: `participants`, ordered `items`, `c`, and optional `width`, `height`, spacing, title, subtitle, and `ariaLabel`. Participants have `id`, `label`, optional `detail`, `tone`, `kind`, and `icon`. Items are messages (`from`, `to`, `label`, `kind?: "sync" | "async" | "return"`), notes, activations, or recursive fragments with `kind: "alt" | "loop" | "parallel"` and labeled branches.
|
|
323
333
|
- `DataflowDiagram`: `nodes`, `edges`, optional nested `boundaries`, `c`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Nodes require `id`, `label`, and `kind: "source" | "transform" | "store" | "sink"`; optional schema metadata renders in node detail, with optional `href` and `title` for SVG links and tooltips. Edges use `mode?: "batch" | "stream"`, optional schema/label metadata, and optional `id`, `href`, and `title`.
|
|
324
334
|
- `DeploymentDiagram`: `nodes`, `connections`, optional nested `boundaries`, `c`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Boundaries distinguish region, zone, VPC, subnet, namespace, host, cluster, and trust scopes. Nodes declare infrastructure kind, boundary, and ports, with optional `href` and `title`. Connections declare ingress, egress, internal, or cross-boundary direction plus protocol and port references; `id`, `href`, and `title` add stable SVG identity and links.
|
|
335
|
+
- `DeploymentPort`: `id`, `port?`, `protocol?`, `label?`, `direction?: "ingress" | "egress" | "bidirectional"`, `side?: GraphPortSide`, `offset?: number`. With explicit `routing="straight"` or `routing="orthogonal"`, connection `fromPort` / `toPort` references require declared node ports and anchor geometrically. Side defaults follow graph direction and ingress/egress use; explicit side/offset overrides them. Default Dagre deployment rendering keeps the existing label-only behavior.
|
|
325
336
|
- `TransformerTopology`: `blocks`, optional `routes`, `c`, `expandRepeats?`, GraphDiagram sizing/layout props including `id`, `title`, and `description`, and `ariaLabel`. Blocks use embedding, attention, norm, MLP, residual, router, output, or custom kinds with tensor shapes and repeat counts, plus optional `href` and `title`. Routes use activation, residual, KV-cache, expert, or collective semantics, plus optional `id`, `href`, and `title`. `formatTensorShape(shape)` formats reusable shape metadata.
|
|
326
337
|
- `defineDiagramIcon(id, render)`: defines a reusable custom graph icon. `render` receives `c`, `color`, `size`, and optional `label`.
|
|
327
338
|
- `defineIconRegistry(icons)`: preserves typed names for a set of custom or provider icons without global mutable state.
|
|
@@ -336,8 +347,10 @@ Matrices and heatmaps:
|
|
|
336
347
|
Charts and plots:
|
|
337
348
|
|
|
338
349
|
- `ChartFrame`: `children`, `c`, `title?`, `subtitle?`, `legend?: ChartLegendItem[]`, `footer?`, `width?: number | string = "100%"`, `height?`, `padding?: number = 16`. `ChartLegendItem`: `label`, `color: ColorName | string`.
|
|
350
|
+
- `PieChart`: `segments: DonutChartSegment[]`, `c`, `title?`, `subtitle?`, `width?: number = 360`, `height?: number = 240`, `size?`, `format?: ChartValueFormat = "decimal"`, `showLegend?: boolean = true`, `footer?`. Each segment has `label`, `value`, optional `color`, and optional `valueLabel`. Values must be finite and non-negative; zero slices are omitted. The full-circle pie shows part-to-whole proportions, with values and shares in the legend. Use `examples/pie-chart.tsx` for a complete frame.
|
|
339
351
|
- `DonutChart`: `segments: DonutChartSegment[]`, `c`, `title?`, `subtitle?`, `width?: number = 360`, `height?: number = 230`, `size?`, `thickness?`, `format?: ChartValueFormat = "decimal"`, `centerLabel?`, `centerValue?`, `showLegend?: boolean = true`, `footer?`. `DonutChartSegment`: `label`, `value`, `color?`, `valueLabel?`.
|
|
340
352
|
- `BarChart`: `data: BarChartDatum[]`, `c`, `title?`, `subtitle?`, `width?: number = 320`, `height?: number = 220`, `min?`, `max?`, `format?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `showValues?: boolean = true`, `yAxisLabel?`, `footer?`. `BarChartDatum`: `label`, `value`, `color?`, `valueLabel?`.
|
|
353
|
+
- `ParetoBarChart`: `data: BarChartDatum[]`, `c`, `title?`, `subtitle?`, `width?: number = 520`, `height?: number = 300`, `format?: ChartValueFormat = "integer"`, `showGrid?: boolean = true`, `showValues?: boolean = true`, `footer?`. A classic categorical Pareto chart with descending bars and a cumulative percentage line, separate value/share axes, and stable tie order. Values must be finite and non-negative. Sorting preserves the input array. A positive total ends at 100%; an all-zero total stays at 0%. Use this for the causes behind a total, and `ParetoChart` for a non-dominated scatter frontier. See `examples/pareto-bar-chart.tsx`.
|
|
341
354
|
- `LineChart`: `series: LineChartSeries[]`, `c`, `title?`, `subtitle?`, `width?: number = 420`, `height?: number = 240`, `labels?`, `min?`, `max?`, `format?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `showPoints?: boolean = true`, `yAxisLabel?`, `footer?`. `LineChartSeries`: `name`, `points`, `color?`, `area?`.
|
|
342
355
|
- `ScatterPlot`: `points: ScatterPoint[]`, `c`, `title?`, `subtitle?`, `width?: number = 380`, `height?: number = 260`, `xMin?`, `xMax?`, `yMin?`, `yMax?`, `xAxisLabel?`, `yAxisLabel?`, `formatX?: ChartValueFormat = "decimal"`, `formatY?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `footer?`. `ScatterPoint`: `x`, `y`, `label?`, `color?`, `size?`.
|
|
343
356
|
- `ParetoChart`: `points: ScatterPoint[]`, `c`, `title?`, `subtitle?`, `width?: number = 640`, `height?: number = 360`, `xMin?`, `xMax?`, `yMin?`, `yMax?`, `xAxisLabel?`, `yAxisLabel?`, `formatX?: ChartValueFormat = "decimal"`, `formatY?: ChartValueFormat = "decimal"`, `showGrid?: boolean = true`, `xScale?: "linear" | "log" = "linear"`, `xObjective?: "minimize" | "maximize" = "minimize"`, `yObjective?: "minimize" | "maximize" = "maximize"`, `frontierColor?`, `showGoal?: boolean = true`, `goalLabel?`, `footer?`. It detects non-dominated points automatically; logarithmic x scales omit non-positive points.
|
package/README.md
CHANGED
|
@@ -21,6 +21,8 @@
|
|
|
21
21
|
<p align="center">
|
|
22
22
|
<a href="https://bvolpato.github.io/vizmatic/">Website</a> ·
|
|
23
23
|
<a href="https://bvolpato.github.io/vizmatic/playground.html">Playground</a> ·
|
|
24
|
+
<a href="https://bvolpato.github.io/vizmatic/components.html">Components</a> ·
|
|
25
|
+
<a href="https://bvolpato.github.io/vizmatic/agents.html">For agents</a> ·
|
|
24
26
|
<a href="examples">Examples</a> ·
|
|
25
27
|
<a href="PROMPT.md">Agent Prompt</a> ·
|
|
26
28
|
<a href="#api">API</a>
|
|
@@ -121,6 +123,8 @@ Use the Vizmatic skill to turn this release workflow into an animated GIF for do
|
|
|
121
123
|
|
|
122
124
|
Skill source lives in [`.agents/skills/vizmatic`](.agents/skills/vizmatic). Review it before installing with `npx skills add bvolpato/vizmatic --list`.
|
|
123
125
|
|
|
126
|
+
The [agent guide](https://bvolpato.github.io/vizmatic/agents.html) explains installation and the check/render workflow. Agents can discover instructions through [llms.txt](https://bvolpato.github.io/vizmatic/llms.txt), load the [full context bundle](https://bvolpato.github.io/vizmatic/llms-full.txt), or read [runnable component examples as JSON](https://bvolpato.github.io/vizmatic/components.json).
|
|
127
|
+
|
|
124
128
|
Codex and Claude Code can also install Vizmatic as a plugin:
|
|
125
129
|
|
|
126
130
|
```bash
|
|
@@ -143,6 +147,12 @@ vizmatic ./frame.tsx --out ./dist/frames --theme dark,light --watermark "Acme" -
|
|
|
143
147
|
|
|
144
148
|
Each output directory includes `manifest.json`. `outputs` lists generated files, and `outputDetails` records theme, path, and pixel dimensions.
|
|
145
149
|
|
|
150
|
+
Static CLI renders default to PNG. Use `--format svg` for vector output or `--format both` to export PNG and SVG together. Each manifest output detail includes its `format`; both formats support themes, backgrounds, watermarks, cropping, and automatic canvas growth.
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
vizmatic ./frame.tsx --out ./visuals --theme dark,light --format both
|
|
154
|
+
```
|
|
155
|
+
|
|
146
156
|
Render an animation:
|
|
147
157
|
|
|
148
158
|
```bash
|
|
@@ -278,11 +288,32 @@ Use these primitives before writing raw SVG or absolute-positioned layouts.
|
|
|
278
288
|
|---|---|
|
|
279
289
|
| `defineIllustration` | Wraps a theme-aware frame builder and exports `create(theme)` plus a default element. |
|
|
280
290
|
| `Canvas` | Low-level full-frame root with alpha-transparent default background, optional background fill, padding, and vertical alignment. |
|
|
291
|
+
| `Board` | Fixed canvas for freely positioned components, with explicit dimensions and an optional background. |
|
|
292
|
+
| `CanvasItem` | Positions and sizes a component at logical-pixel `x` / `y` coordinates. Charts fit their complete plotting layers, labels, and frame inside the item. |
|
|
281
293
|
| `Scene` | Standard frame wrapper with optional title/subtitle, content column, and theme-aware typography. |
|
|
282
294
|
| `TitleBar` | Shared title/subtitle block used by `Scene`. |
|
|
283
295
|
| `Row` / `Column` | Flex layout primitives with gap, alignment, wrapping, width, and height props. |
|
|
284
296
|
| `Stack` | Layered vertical stack for repeated cards, tokens, or processing layers. |
|
|
285
297
|
|
|
298
|
+
Use `Board` with `CanvasItem` for layouts that people can move and resize in the browser builder. Coordinates and sizes remain in the TSX source. Set the frame dimensions to match the board; the board clips content outside its bounds. With both item dimensions set, chart primitives scale proportionally to fit the complete chart, including wrapped headings, legends, and footers.
|
|
299
|
+
|
|
300
|
+
```tsx
|
|
301
|
+
width = 960;
|
|
302
|
+
height = 540;
|
|
303
|
+
|
|
304
|
+
<Board width={960} height={540}>
|
|
305
|
+
<CanvasItem x={40} y={40} width={280} height={160}>
|
|
306
|
+
<MetricCard label="Requests" value="1,240" tone="green" />
|
|
307
|
+
</CanvasItem>
|
|
308
|
+
<CanvasItem x={360} y={40} width={540} height={340}>
|
|
309
|
+
<PieChart title="Requests by outcome" format="integer" segments={[
|
|
310
|
+
{ label: "Successful", value: 82, color: "positive" },
|
|
311
|
+
{ label: "Retried", value: 18, color: "warning" },
|
|
312
|
+
]} />
|
|
313
|
+
</CanvasItem>
|
|
314
|
+
</Board>
|
|
315
|
+
```
|
|
316
|
+
|
|
286
317
|
#### Surfaces, labels, and cards
|
|
287
318
|
|
|
288
319
|
| Component | Use |
|
|
@@ -372,6 +403,12 @@ Set `id`, `title`, and `description` for accessible SVG exports. Nodes and edges
|
|
|
372
403
|
|
|
373
404
|
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.
|
|
374
405
|
|
|
406
|
+
Connector routing is separate from node layout. The default `routing="dagre"` preserves existing geometry. Choose `routing="straight"` for direct connectors or `routing="orthogonal"` for right-angle routes that avoid node boxes and group headers. `routingClearance` defaults to 12 logical pixels; `edgeGap` separates parallel traffic. Orthogonal routing supports automatic and manual node positions, self-loops with distinct anchors, and separated parallel routes.
|
|
407
|
+
|
|
408
|
+
Declare node `ports` as `{ id, side, offset? }`, then reference them with edge `fromPort` / `toPort`. Sides are `top`, `right`, `bottom`, or `left`; offsets run from 0 to 1 along the side and default to 0.5. An edge can instead specify `fromSide` / `toSide`. Use either a port reference or a side for each endpoint. Explicit anchors also opt an edge into orthogonal geometry when the routing mode is Dagre. With explicit straight or orthogonal routing, `DeploymentDiagram` anchors declared port references and accepts port `side` / `offset` overrides.
|
|
409
|
+
|
|
410
|
+
Routing runs synchronously offline with limits of 64 node/header obstacles and 256 edges, plus bounded grid and search work. A blocked route, repeated route with no separate lane, or exhausted limit omits the affected connector and makes the checker report `layout.connector_unroutable` as an error. Increase spacing or canvas size, change anchors, or reduce clearance before publishing. Missing port references fail validation. See the [routed graph example](examples/orthogonal-routing.tsx).
|
|
411
|
+
|
|
375
412
|
The [import guide](docs/import.md) documents the supported Mermaid and D2 subsets and their structured source diagnostics.
|
|
376
413
|
|
|
377
414
|
#### Matrices, tables, and grids
|
|
@@ -390,17 +427,21 @@ The [import guide](docs/import.md) documents the supported Mermaid and D2 subset
|
|
|
390
427
|
|---|---|
|
|
391
428
|
| `ChartFrame` | Shared chart wrapper with title, subtitle, footer, and theme-aware shell. |
|
|
392
429
|
| `AxisPlot` | Low-level axis plot for custom lines, paths, and plotted values. |
|
|
430
|
+
| `PieChart` | Full-circle part-to-whole chart with segment values, percentages, and a legend. |
|
|
393
431
|
| `DonutChart` | Part-to-whole chart with center label/value, segment labels, and shared chart styling. |
|
|
394
432
|
| `MiniBarChart` | Small bar chart for cards and dashboards. |
|
|
395
433
|
| `StackedBar` | Segmented horizontal bar with labels and percentages. |
|
|
396
434
|
| `BarChart` | Full bar chart with ticks, labels, values, grids, and formats. |
|
|
397
435
|
| `LineChart` | Multi-series line chart with optional area fill, points, labels, and grid. |
|
|
398
436
|
| `ScatterPlot` | Labeled scatter plot with axes, ticks, point sizing, and collision-aware labels. |
|
|
437
|
+
| `ParetoBarChart` | Categories sorted by descending count with a cumulative percentage line and separate count/share axes. |
|
|
399
438
|
| `ParetoChart` | Automatic non-dominated frontier for competing objectives, including log-scaled cost axes. |
|
|
400
439
|
| `QuadrantChart` | 2x2 decision matrix with numeric axes, configurable thresholds, labeled points, and optional region emphasis. |
|
|
401
440
|
| `IntervalPlot` | Timeline/range plot for spans, phases, latencies, and schedules. |
|
|
402
441
|
|
|
403
|
-
`
|
|
442
|
+
Use `PieChart` for category shares, `BarChart` for category values, `ScatterPlot` for paired numeric observations, and `ParetoBarChart` to identify the categories behind most of a total. Pie and Pareto bar values must be finite and non-negative; zero-valued pie slices are omitted. Pareto bars sort descending without changing the input array and preserve input order for equal values. The cumulative line reaches 100% when the total is positive. See the [pie](examples/pie-chart.tsx) and [Pareto bar](examples/pareto-bar-chart.tsx) examples.
|
|
443
|
+
|
|
444
|
+
`ParetoChart` shows a non-dominated scatter frontier for competing objectives. It defaults to minimizing x and maximizing y, which fits cost-versus-score comparisons. Set `xObjective` or `yObjective` for other tradeoffs. Non-positive x values are omitted on a logarithmic x-axis. `QuadrantChart` accepts raw numeric domains, threshold values, tick formats, and optional grid lines; omit them to keep normalized 0-1 coordinates and centered splits. Regions accept `emphasis: true` to give one decision region a stronger fill and border.
|
|
404
445
|
|
|
405
446
|
#### Rendering and verification
|
|
406
447
|
|
|
@@ -543,6 +584,40 @@ pnpm verify
|
|
|
543
584
|
pnpm site:serve
|
|
544
585
|
```
|
|
545
586
|
|
|
587
|
+
The homepage, Components page, and Playground share a live component explorer. Choose a component to open its focused example, or use Add to scene to compose several components. Select an element to edit its literal props, add optional properties, duplicate or remove it, and move it within its group. Controls follow inline text and TSX edits. Computed props and expression-generated structure stay editable in the TSX. Preview framing and zoom preserve the full canvas in downloaded PNG and SVG files.
|
|
588
|
+
|
|
589
|
+
Choose the Freeform canvas template for a positioned builder. Move and resize `CanvasItem` components through the preview handles, use grid snapping, or adjust their literal coordinates in the inspector. Arrow keys nudge a focused handle; Shift makes a larger move and Alt bypasses snapping. The layout remains ordinary `Board` / `CanvasItem` TSX.
|
|
590
|
+
|
|
591
|
+
Structured data editors let you add, remove, and change pie segments, bar categories, scatter points, and table cells. Nested styles, arrays, and objects also have JSON editors. Invalid shapes and missing graph node references report an error before changing the source. Computed data remains editable in TSX.
|
|
592
|
+
|
|
593
|
+
Open Canvas and palette to change the frame dimensions, style preset, and any theme color. Choose a transparent, theme, or custom CSS background. These settings are saved in the TSX and participate in undo, project files, share links, and exports. Bare CLI frames support the same metadata:
|
|
594
|
+
|
|
595
|
+
```tsx
|
|
596
|
+
width = 960;
|
|
597
|
+
height = 540;
|
|
598
|
+
preset = "default";
|
|
599
|
+
background = "#101827";
|
|
600
|
+
themeColors = {"primary":"#22c55e","primaryLight":"hsl(140, 70%, 65%)"};
|
|
601
|
+
|
|
602
|
+
<Board width={960} height={540}>
|
|
603
|
+
<CanvasItem x={40} y={40} width={300} height={120}>
|
|
604
|
+
<CalloutCard title="Your palette" detail="Colors travel with the frame." />
|
|
605
|
+
</CanvasItem>
|
|
606
|
+
</Board>
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
Copy block copies the selected element as reusable bare TSX, including its setup and canvas settings. Inside a Board it keeps the enclosing CanvasItem and its geometry, so the copied block renders on its own. Ctrl/Command+C copies a block when its canvas handle is focused. Copy source copies the complete composition.
|
|
610
|
+
|
|
611
|
+
Edits are saved locally in this browser and restore after reload. Component, shared-source, and gallery links open their own examples. Editing clears the original example or source bookmark so reload can recover your draft. Undo and redo cover source typing, controls, inline text, and scene operations, with up to 100 source snapshots for the current session. Use the buttons or Ctrl/Command+Z and Ctrl/Command+Shift+Z. Drafts do not sync between devices; use Save project to download a named `.vizmatic.json` file containing source, output theme, and canvas background, then Open project to restore it. Share and Copy source also let you move your TSX between tools.
|
|
612
|
+
|
|
613
|
+
Double-click a text label in the preview to edit its literal TSX value. Press Enter or click outside to save, Shift+Enter for a new line, or Escape to cancel. Keyboard users can focus a label and press Enter or F2. Labels derived from computed expressions or ambiguous source values stay editable in the TSX editor.
|
|
614
|
+
|
|
615
|
+
Choose the Animation scene template to play, pause, scrub time, and export a GIF in the browser. Bare animated source declares `animationDuration = 3` and optionally `animationFps = 10` before setup code. The injected `t` variable is time in seconds; Vizmatic timeline helpers continue to use milliseconds. Gallery timeline animations are adapted to the same browser workflow. Browser GIFs use an opaque canvas fill, with limits of 120 frames, 2 million pixels per frame, and 60 million pixels total. Static CLI render and check evaluate these snippets at `t=0`. Use a CLI animation module for larger animations or transparent GIF output.
|
|
616
|
+
|
|
617
|
+
The generated `components.json` includes compiler-derived prop types, requiredness, and finite allowed-value references. Shared value lists live in `propEnums`; defaults are not inferred. Full TypeScript definitions remain the contract for structured data and React values.
|
|
618
|
+
|
|
619
|
+
The website is generated from `docs/*.template.html`, the shared shell in `scripts/site-shell.ts`, and the component registry. Run `pnpm site:build` after editing these sources, then `pnpm docs:check`. Use `pnpm site:serve` for browser validation. The generated agent references, property controls, and example adapters update with the same build. If the bundled fonts change, regenerate the website's WOFF2 files with `pnpm site:fonts` using uv.
|
|
620
|
+
|
|
546
621
|
## Publishing
|
|
547
622
|
|
|
548
623
|
Prepare release commit locally, push it to protected `main`, and wait for required CI before pushing its tag:
|
package/ROADMAP.md
CHANGED
|
@@ -12,6 +12,7 @@ Benchmarks: [Diagrams](https://diagrams.mingrammer.com/), [D2](https://d2lang.co
|
|
|
12
12
|
- Reusable custom icon definitions and typed icon registries.
|
|
13
13
|
- Labeled synchronous, asynchronous, event, data, dependency, and association relationships.
|
|
14
14
|
- Solid, dashed, and dotted connectors with forward, backward, bidirectional, or no arrows.
|
|
15
|
+
- Named ports and endpoint sides, with straight or obstacle-aware orthogonal routing and separated parallel connectors.
|
|
15
16
|
- Manual positioning for ungrouped editorial diagrams.
|
|
16
17
|
- Connector diagnostics for crossings, label collisions, crowded endpoints, and parallel routes.
|
|
17
18
|
- Typed in-process visual checks with stable diagnostic codes, element locations where available, and configurable failure policy.
|
|
@@ -25,6 +26,8 @@ Benchmarks: [Diagrams](https://diagrams.mingrammer.com/), [D2](https://d2lang.co
|
|
|
25
26
|
- Transformer topology views with tensor shapes, repeated blocks, residual/cache/expert routes, and collectives.
|
|
26
27
|
- Cadence-boundary animation sampling, per-frame overflow detection, and opaque delta-frame GIF encoding.
|
|
27
28
|
- Compressed offline Twemoji bundle instead of thousands of package entries.
|
|
29
|
+
- Positioned browser builder with editable text and chart data, drag/resize, undo/redo, local drafts, and portable project files.
|
|
30
|
+
- Pie, donut, bar, line, scatter, classic Pareto bar, Pareto frontier, quadrant, and interval charts.
|
|
28
31
|
|
|
29
32
|
## Next capability batches
|
|
30
33
|
|
|
@@ -57,8 +60,7 @@ Specialized APIs remain declarative and reusable. Examples contain complete scen
|
|
|
57
60
|
|
|
58
61
|
### Layout and rendering
|
|
59
62
|
|
|
60
|
-
-
|
|
61
|
-
- Orthogonal, curved, and user-routed connectors with parallel-edge separation.
|
|
63
|
+
- Curved and user-routed connectors with editable waypoints.
|
|
62
64
|
- Layout adapter interface with Dagre as default and ELK as optional backend.
|
|
63
65
|
- Per-boundary direction, collapsed groups, named scenarios, and reusable animation compositions.
|
|
64
66
|
- Extend structured SVG accessibility beyond graph diagrams to charts and other visual primitives.
|
|
@@ -20,6 +20,9 @@ runtime fetches.
|
|
|
20
20
|
|
|
21
21
|
Full license: [`licenses/OFL-1.1.txt`](licenses/OFL-1.1.txt).
|
|
22
22
|
|
|
23
|
+
The website uses WOFF2 copies of the same Inter and JetBrains Mono font files.
|
|
24
|
+
Regenerate them with `pnpm site:fonts`; the original font licenses apply.
|
|
25
|
+
|
|
23
26
|
## Emoji
|
|
24
27
|
|
|
25
28
|
- Twemoji SVG assets from `@twemoji/svg@15.0.0`: MIT.
|