vizmatic 0.1.13 → 0.1.15
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 +28 -8
- package/README.md +14 -2
- package/dist/cli.js +222 -63
- package/dist/index.cjs +85 -27
- package/dist/index.d.cts +10 -6
- package/dist/index.d.ts +10 -6
- package/dist/index.js +85 -27
- package/docs/PROMPT.md +28 -8
- package/docs/assets/examples/agent-pipeline_dark.png +0 -0
- package/docs/assets/examples/agent-pipeline_light.png +0 -0
- package/docs/assets/examples/animated-pipeline_dark.png +0 -0
- package/docs/assets/examples/animated-pipeline_light.png +0 -0
- package/docs/assets/examples/attention-head_dark.png +0 -0
- package/docs/assets/examples/attention-head_light.png +0 -0
- package/docs/assets/examples/embedding-map_dark.png +0 -0
- package/docs/assets/examples/embedding-map_light.png +0 -0
- package/docs/assets/examples/eval-dashboard_dark.png +0 -0
- package/docs/assets/examples/eval-dashboard_light.png +0 -0
- package/docs/assets/examples/manifest.json +16 -0
- package/docs/assets/examples/model-router_dark.png +0 -0
- package/docs/assets/examples/model-router_light.png +0 -0
- package/docs/assets/examples/presentation-frame_dark.png +0 -0
- package/docs/assets/examples/presentation-frame_light.png +0 -0
- package/docs/assets/examples/rag-graph_dark.png +0 -0
- package/docs/assets/examples/rag-graph_light.png +0 -0
- package/docs/assets/examples/release-card_dark.png +0 -0
- package/docs/assets/examples/release-card_light.png +0 -0
- package/docs/assets/examples/research-landscape_dark.png +0 -0
- package/docs/assets/examples/research-landscape_light.png +0 -0
- package/docs/assets/examples/sources.json +26 -6
- package/docs/assets/examples/spec-anatomy_dark.png +0 -0
- package/docs/assets/examples/spec-anatomy_light.png +0 -0
- package/docs/assets/examples/theme-background_dark.png +0 -0
- package/docs/assets/examples/theme-background_light.png +0 -0
- package/docs/assets/examples/theme-system_dark.png +0 -0
- package/docs/assets/examples/theme-system_light.png +0 -0
- package/docs/assets/examples/token-matrix_dark.png +0 -0
- package/docs/assets/examples/token-matrix_light.png +0 -0
- package/docs/assets/examples/transparent-badge_dark.png +0 -0
- package/docs/assets/examples/transparent-badge_light.png +0 -0
- package/examples/README.md +2 -0
- package/examples/model-router.tsx +1 -1
- package/examples/research-landscape.tsx +1 -1
- package/examples/theme-background.tsx +15 -0
- package/examples/transparent-badge.tsx +15 -0
- package/examples/vizmatic-bare.d.ts +1 -0
- package/package.json +2 -1
package/docs/PROMPT.md
CHANGED
|
@@ -105,7 +105,23 @@ Render it:
|
|
|
105
105
|
vizmatic frames --out public/vizmatic --theme dark,light --watermark "Your Product" --watermark-image ./logo.svg --watermark-position top-right
|
|
106
106
|
```
|
|
107
107
|
|
|
108
|
-
|
|
108
|
+
PNG and SVG renders use alpha-transparent canvas backgrounds by default. Use the actual theme background when the host needs a full-frame image:
|
|
109
|
+
|
|
110
|
+
```bash
|
|
111
|
+
vizmatic frames --out public/vizmatic --theme dark,light --background theme
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
Or set it in the frame:
|
|
115
|
+
|
|
116
|
+
```tsx
|
|
117
|
+
<Scene background={c.bg} title="Opaque article figure">
|
|
118
|
+
<Flow stages={[{ title: "Theme fill", tone: "purple" }]} />
|
|
119
|
+
</Scene>
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
If a direct CLI frame omits `width` or `height`, Vizmatic starts at `960x540` and grows omitted axes when overflow is detected. Explicit dimensions stay strict and should be used when exact output size matters.
|
|
123
|
+
|
|
124
|
+
For direct CLI frames, skip imports, `defineIllustration`, and `c` props by default. The CLI injects Vizmatic primitives and theme colors. Reference `c` only when you need explicit theme tokens such as `background={c.bg}`. Use the full module form when you need custom dependencies, direct renderer APIs, advanced reusable JSX helpers, or animation exports.
|
|
109
125
|
|
|
110
126
|
Frame modules can also export a watermark element when code-owned branding is clearer than CLI flags:
|
|
111
127
|
|
|
@@ -204,16 +220,18 @@ Shared values:
|
|
|
204
220
|
- `ColorName`: `"primary" | "secondary" | "positive" | "warning" | "critical" | "info" | "accent" | "neutral"`.
|
|
205
221
|
- `FlexAlign`: `"start" | "center" | "end" | "stretch"`.
|
|
206
222
|
- `FlexJustify`: `"start" | "center" | "end" | "space-between" | "space-around"`.
|
|
207
|
-
- In bare CLI frames, omit `c
|
|
223
|
+
- In bare CLI frames, omit `c` props; the CLI injects theme colors into Vizmatic components. The local `c` token object is still available for explicit values like `background={c.bg}`.
|
|
208
224
|
- In full modules, most visual components require `c: ThemeColors`; inside `defineIllustration((c) => ...)`, pass that same `c` down.
|
|
225
|
+
- PNG/SVG renders are alpha-transparent by default. Use `--background theme`, `background: "theme"`, or `<Scene background={c.bg}>` for opaque theme fill.
|
|
226
|
+
- Omitted CLI dimensions auto-grow on overflow. Explicit `width` / `height` remain fixed and fail on clipping.
|
|
209
227
|
|
|
210
228
|
## Component API
|
|
211
229
|
|
|
212
230
|
Frame helpers:
|
|
213
231
|
|
|
214
232
|
- `defineIllustration(build, defaultTheme?)`: `build: (c: ThemeColors) => ReactElement`, `defaultTheme?: ThemeMode = "dark"`. Returns `{ create(theme), default }`.
|
|
215
|
-
- `Canvas`: `children?`, `c`, `padding?: number = 40`, `justify?: "center" | "flex-start" | "space-between" | "space-around" = "center"`, `background?: string`.
|
|
216
|
-
- `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: Canvas.justify = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`.
|
|
233
|
+
- `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.
|
|
234
|
+
- `Scene`: `c`, `children`, `title?`, `subtitle?`, `padding?: number = 40`, `gap?: number = 24`, `justify?: Canvas.justify = "flex-start"`, `align?: FlexAlign = "stretch"`, `contentWidth?: number | string = "100%"`, `background?`, `contentStyle?: React.CSSProperties`. Use `background={c.bg}` for an opaque theme frame.
|
|
217
235
|
- `TitleBar`: `title`, `subtitle?`, `c`.
|
|
218
236
|
|
|
219
237
|
Layout primitives:
|
|
@@ -315,12 +333,12 @@ Theme and render APIs:
|
|
|
315
333
|
- `WatermarkInput`: `boolean | string | WatermarkOptions | ReactElement<WatermarkElementProps>`. `true` uses Vizmatic defaults. A string sets the watermark text. A React element can be `<Watermark>...</Watermark>` or any custom element.
|
|
316
334
|
- `WatermarkImageOptions`: `src`, `width?: number`, `height?: number`, `alt?: string`. Programmatic `src` should be a URL or data URI. CLI `--watermark-image` accepts URL, data URI, or local path.
|
|
317
335
|
- `WatermarkOptions`: `text?: string | false`, `image?: string | WatermarkImageOptions`, `icon?: ReactNode | string | false`, `element?: ReactNode`, `position?: "top-left" | "top-right" | "bottom-left" | "bottom-right" = "top-right"`, `opacity?: number`, `color?: string`.
|
|
318
|
-
- `RenderOptions`: `width`, `height`, `outputPath`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean = true`, `scale?: number = 2`.
|
|
319
|
-
- `renderToBuffer(element, width, height, options?)`: `options` supports `watermark?`, `brand?`, `scale?`.
|
|
320
|
-
- `renderToSvg(element, width, height, options?)`: `options` supports `watermark?`, `brand?`.
|
|
336
|
+
- `RenderOptions`: `width`, `height`, `outputPath`, `background?: "transparent" | "theme" | CSS color = "transparent"`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `crop?: boolean = true`, `scale?: number = 2`.
|
|
337
|
+
- `renderToBuffer(element, width, height, options?)`: `options` supports `background?`, `watermark?`, `brand?`, `scale?`.
|
|
338
|
+
- `renderToSvg(element, width, height, options?)`: `options` supports `background?`, `watermark?`, `brand?`.
|
|
321
339
|
- `renderAnimatedGif(scenes, options)`: `scenes: AnimatedScene[]`, `options: AnimationOptions`.
|
|
322
340
|
- `AnimatedScene`: `element`, `duration` in ms, `transition?: "none" | "fade" | "appear"`, `transitionDuration?`, `label?`.
|
|
323
|
-
- `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`.
|
|
341
|
+
- `AnimationOptions`: `width`, `height`, `outputPath`, `loop?: number = 0`, `scale?: number = 1`, `background?: "theme" | "transparent" | CSS color = "theme"` for GIF reliability, `watermark?: WatermarkInput`, `brand?: boolean | string` as a compatibility alias, `theme?: "dark" | "light" = "dark"`.
|
|
324
342
|
|
|
325
343
|
## Prop-aware examples
|
|
326
344
|
|
|
@@ -400,6 +418,8 @@ height = 560;
|
|
|
400
418
|
|
|
401
419
|
- Use semantic tones, not hard-coded colors: `blue`, `purple`, `green`, `warm`, `cyan`, `pink`, `critical`, `ocean`, `neutral`.
|
|
402
420
|
- Keep canvas sizes explicit. Good defaults: `1040x560` for article figures, `1280x720` for slide frames, `900x520` for compact diagrams.
|
|
421
|
+
- For exploratory direct CLI frames, dimensions may be omitted; Vizmatic auto-grows omitted axes if content overflows.
|
|
422
|
+
- 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.
|
|
403
423
|
- Use `width`, `minWidth`, `height`, `minHeight`, `gap`, and `padding` props to stabilize layout.
|
|
404
424
|
- Keep text short. Use `TextLabel`, `Panel`, `StepCard`, `MetricCard`, `DataTable`, and `Grid` for wrapping-safe labels.
|
|
405
425
|
- Render both dark and light when shipping reusable assets: `--theme dark,light`.
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
@@ -89,6 +89,14 @@
|
|
|
89
89
|
"spec-anatomy_light.png"
|
|
90
90
|
]
|
|
91
91
|
},
|
|
92
|
+
{
|
|
93
|
+
"name": "theme-background",
|
|
94
|
+
"source": "examples/theme-background.tsx",
|
|
95
|
+
"outputs": [
|
|
96
|
+
"theme-background_dark.png",
|
|
97
|
+
"theme-background_light.png"
|
|
98
|
+
]
|
|
99
|
+
},
|
|
92
100
|
{
|
|
93
101
|
"name": "theme-system",
|
|
94
102
|
"source": "examples/theme-system.tsx",
|
|
@@ -104,5 +112,13 @@
|
|
|
104
112
|
"token-matrix_dark.png",
|
|
105
113
|
"token-matrix_light.png"
|
|
106
114
|
]
|
|
115
|
+
},
|
|
116
|
+
{
|
|
117
|
+
"name": "transparent-badge",
|
|
118
|
+
"source": "examples/transparent-badge.tsx",
|
|
119
|
+
"outputs": [
|
|
120
|
+
"transparent-badge_dark.png",
|
|
121
|
+
"transparent-badge_light.png"
|
|
122
|
+
]
|
|
107
123
|
}
|
|
108
124
|
]
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|
|
Binary file
|