vizcraft 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # vizcraft
 
+## 1.2.0
+
+### Minor Changes
+
+- [`f72dc04`](https://github.com/ChipiKaf/vizcraft/commit/f72dc0405ccd752ad13eb746349b6a5945448c79) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - Added rich text labels to VizCraft with support for mixed formatting and line breaks. Introduced fluent .richLabel() APIs and declarative label.rich support. Improved runtime updates to keep animations stable, extended React rendering, and added test coverage. Docs and READMEs now include a live example.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -85,6 +85,12 @@ pnpm -C packages/docs start
 
 The heart of VizCraft is the `VizBuilder`. It allows you to construct a `VizScene` which acts as the blueprint for your visualization.
 
+For exporting frame snapshots during data-only playback, you can export an SVG that includes runtime overrides:
+
+```ts
+const svg = builder.svg({ includeRuntime: true });
+```
+
 ```typescript
 b.view(width, height) // Set the coordinate space
   .grid(cols, rows) // (Optional) Define layout grid
@@ -92,6 +98,52 @@ b.view(width, height) // Set the coordinate space
   .edge(from, to); // Start defining an edge
 ```
 
+### Plugins
+
+Extend the builder's functionality seamlessly using `.use()`. Plugins are functions that take the builder instance and optional configuration, allowing you to encapsulate reusable behaviors, export utilities, or composite nodes.
+
+```typescript
+import { viz, VizPlugin } from 'vizcraft';
+
+const watermarkPlugin: VizPlugin<{ text: string }> = (builder, opts) => {
+  builder.node('watermark', {
+    at: { x: 50, y: 20 },
+    rect: { w: 100, h: 20 },
+    label: opts?.text ?? 'Draft',
+    opacity: 0.5,
+  });
+};
+
+viz()
+  .view(800, 600)
+  .node('n1', { circle: { r: 20 } })
+  .use(watermarkPlugin, { text: 'Confidential' })
+  .build();
+```
+
+**Event Hooks**
+
+Plugins (or your own code) can also tap into the builder's lifecycle using `.on()`. This is particularly useful for interactive plugins that need to append HTML elements (like export buttons or tooltips) after VizCraft mounts the SVG to the DOM.
+
+```typescript
+const exportUiPlugin: VizPlugin = (builder) => {
+  // Listen for the 'mount' event to inject a button next to the SVG
+  builder.on('mount', ({ container }) => {
+    const btn = document.createElement('button');
+    btn.innerText = 'Download PNG';
+    btn.onclick = () => {
+      /* export logic */
+    };
+
+    // Position the button absolutely over the container
+    btn.style.position = 'absolute';
+    btn.style.top = '10px';
+    btn.style.right = '10px';
+    container.appendChild(btn);
+  });
+};
+```
+
 ### Declarative Options Overloads
 
 You can also configure nodes and edges in a single declarative call by passing an options object:
@@ -140,6 +192,10 @@ b.node('n1')
  .trapezoid(topW, bottomW, h) // Trapezoid
  .triangle(w, h, [direction]) // Triangle
  .label('Text', { dy: 5 }) // Label with offset
+ .richLabel((l) => l.text('Hello ').bold('World')) // Rich / mixed-format label
+ .image(href, w, h, opts?) // Embed an <image> inside the node
+ .icon(id, opts?)         // Embed an icon from the icon registry (see registerIcon)
+ .svgContent(svg, opts)   // Embed inline SVG content inside the node
  .class('css-class')     // Custom CSS class
  .data({ ... })          // Attach custom data
  .port('out', { x: 50, y: 0 }) // Named connection port
@@ -174,6 +230,7 @@ b.edge('n1', 'n2')
   .arrow() // Add an arrowhead
   .straight() // (Default) Straight line
   .label('Connection')
+  .richLabel((l) => l.text('p').sup('95').text(' = ').bold('10ms'))
   .animate('flow'); // Add animation
 
 // Curved edge
@@ -185,6 +242,18 @@ b.edge('a', 'c').orthogonal().arrow();
 // Waypoints — intermediate points the edge passes through
 b.edge('x', 'y').curved().via(150, 50).via(200, 100).arrow();
 
+// Arbitrary edge metadata (for routing flags, categories, etc.)
+b.edge('a', 'b').meta({ customRouting: true, padding: 10 });
+
+// Override edge path computation with a resolver hook
+b.setEdgePathResolver((edge, scene, defaultResolver) => {
+  if (edge.meta?.customRouting) {
+    // Return an SVG path `d` string
+    return `M 0 0 L 10 10`;
+  }
+  return defaultResolver(edge, scene);
+});
+
 // Per-edge styling (overrides CSS defaults)
 b.edge('a', 'b').stroke('#ff0000', 3).fill('none').opacity(0.8);
 
@@ -199,12 +268,19 @@ b.edge('a', 'b')
   .label('*', { position: 'end' })
   .arrow();
 
+// Rich text labels (mixed formatting)
+b.edge('a', 'b')
+  .richLabel((l) => l.text('p').sup('95').text(' ').bold('12ms'))
+  .arrow();
+
 // Edge markers / arrowhead types
 b.edge('a', 'b').markerEnd('arrowOpen'); // Open arrow (inheritance)
 b.edge('a', 'b').markerStart('diamond').markerEnd('arrow'); // UML composition
 b.edge('a', 'b').markerStart('diamondOpen').markerEnd('arrow'); // UML aggregation
 b.edge('a', 'b').arrow('both'); // Bidirectional arrows
 b.edge('a', 'b').markerStart('circleOpen').markerEnd('arrow'); // Association
+// Self-loops (exits and enters the same node)
+b.edge('n1', 'n1').loopSide('right').loopSize(40).arrow();
 b.edge('a', 'b').markerEnd('bar'); // ER cardinality
 
 // Connection ports — edges attach to specific points on nodes
@@ -228,6 +304,7 @@ b.edge('a', 'b').fromPort('right').toPort('left').arrow();
 | `.routing(mode)`         | Set mode programmatically.                                                                                                            |
 | `.via(x, y)`             | Add an intermediate waypoint (chainable).                                                                                             |
 | `.label(text, opts?)`    | Add a text label. Chain multiple calls for multi-position labels. `opts.position` can be `'start'`, `'mid'` (default), or `'end'`.    |
+| `.richLabel(cb, opts?)`  | Add a rich / mixed-format label (nested SVG `<tspan>`s). Use `.newline()` in the callback to control line breaks.                     |
 | `.arrow([enabled])`      | Shorthand for arrow markers. `true`/no-arg → markerEnd arrow. `'both'` → both ends. `'start'`/`'end'` → specific end. `false` → none. |
 | `.markerEnd(type)`       | Set marker type at the target end. See `EdgeMarkerType`.                                                                              |
 | `.markerStart(type)`     | Set marker type at the source end. See `EdgeMarkerType`.                                                                              |

package/dist/builder.d.ts

@@ -1,9 +1,37 @@
-import type { VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, AnimationConfig, OverlayId, OverlayParams, VizGridConfig, ContainerConfig, EdgeRouting, EdgeMarkerType, NodeOptions, EdgeOptions, PanZoomOptions, PanZoomController, VizSceneMutator } from './types';
+import type { VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, RichText, RichTextToken, AnimationConfig, OverlayId, OverlayParams, VizGridConfig, ContainerConfig, EdgeRouting, EdgeMarkerType, EdgePathResolver, NodeOptions, EdgeOptions, PanZoomOptions, PanZoomController, VizSceneMutator, VizPlugin, VizEventMap, LayoutAlgorithm, SvgExportOptions } from './types';
 import { OverlayBuilder } from './overlayBuilder';
 import type { AnimationSpec } from './anim/spec';
 import { type AnimationBuilder, type AnimatableProps, type TweenOptions } from './anim/animationBuilder';
 import { type PlaybackController } from './anim/playback';
 export interface VizBuilder extends VizSceneMutator {
+    /**
+     * Applies a plugin to the builder fluently.
+     * @param plugin The plugin function to execute
+     * @param options Optional configuration for the plugin
+     * @returns The builder, for fluent chaining
+     */
+    use<O>(plugin: VizPlugin<O>, options?: O): VizBuilder;
+    /**
+     * Applies a layout algorithm to the current nodes and edges.
+     * @param algorithm The layout function to execute
+     * @param options Optional configuration for the layout algorithm
+     * @returns The builder, for fluent chaining
+     */
+    layout<O>(algorithm: LayoutAlgorithm<O>, options?: O): VizBuilder;
+    /**
+     * Listen for lifecycle events (e.g. 'build', 'mount').
+     * @param event The event name
+     * @param callback The callback to execute when the event fires
+     * @returns An unsubscribe function
+     */
+    on<K extends keyof VizEventMap>(event: K, callback: (ev: VizEventMap[K]) => void): () => void;
+    /**
+     * Override edge SVG path computation.
+     *
+     * Intended to be installed before `mount()`. Applies to DOM reconciliation and
+     * `patchRuntime()`.
+     */
+    setEdgePathResolver(resolver: EdgePathResolver | null): VizBuilder;
     view(w: number, h: number): VizBuilder;
     grid(cols: number, rows: number, padding?: {
         x: number;
@@ -34,7 +62,7 @@ export interface VizBuilder extends VizSceneMutator {
         w: number;
         h: number;
     };
-    svg(): string;
+    svg(opts?: SvgExportOptions): string;
     mount(container: HTMLElement): PanZoomController | undefined;
     mount(container: HTMLElement, opts: {
         autoplay?: boolean;
@@ -66,6 +94,46 @@ export interface VizBuilder extends VizSceneMutator {
      * This avoids full DOM reconciliation and is intended for animation frame updates.
      */
     patchRuntime(container: HTMLElement): void;
+    /**
+     * Tear down a previously mounted scene.
+     *
+     * - Removes the SVG tree from the container.
+     * - Destroys the PanZoomController (if created).
+     * - Cancels any pending requestAnimationFrame / animation loops.
+     * - Removes any internal event listeners (resize, mutation, etc.).
+     *
+     * Safe to call multiple times (no-op after first call).
+     * Safe to call even if `mount()` was never called.
+     */
+    destroy(): void;
+}
+export interface RichLabelBuilder {
+    text(text: string, opts?: Partial<Omit<Extract<RichTextToken, {
+        kind: 'span';
+    }>, 'kind' | 'text'>>): RichLabelBuilder;
+    bold(text: string, opts?: Partial<Omit<Extract<RichTextToken, {
+        kind: 'span';
+    }>, 'kind' | 'text'>>): RichLabelBuilder;
+    italic(text: string, opts?: Partial<Omit<Extract<RichTextToken, {
+        kind: 'span';
+    }>, 'kind' | 'text'>>): RichLabelBuilder;
+    code(text: string, opts?: Partial<Omit<Extract<RichTextToken, {
+        kind: 'span';
+    }>, 'kind' | 'text'>>): RichLabelBuilder;
+    color(text: string, fill: string, opts?: Partial<Omit<Extract<RichTextToken, {
+        kind: 'span';
+    }>, 'kind' | 'text' | 'fill'>>): RichLabelBuilder;
+    link(text: string, href: string, opts?: Partial<Omit<Extract<RichTextToken, {
+        kind: 'span';
+    }>, 'kind' | 'text' | 'href'>>): RichLabelBuilder;
+    sup(text: string, opts?: Partial<Omit<Extract<RichTextToken, {
+        kind: 'span';
+    }>, 'kind' | 'text' | 'baselineShift'>>): RichLabelBuilder;
+    sub(text: string, opts?: Partial<Omit<Extract<RichTextToken, {
+        kind: 'span';
+    }>, 'kind' | 'text' | 'baselineShift'>>): RichLabelBuilder;
+    newline(): RichLabelBuilder;
+    build(): RichText;
 }
 interface NodeBuilder {
     at(x: number, y: number): NodeBuilder;
@@ -95,11 +163,54 @@ interface NodeBuilder {
     star(points: number, outerR: number, innerR?: number): NodeBuilder;
     trapezoid(topW: number, bottomW: number, h: number): NodeBuilder;
     triangle(w: number, h: number, direction?: 'up' | 'down' | 'left' | 'right'): NodeBuilder;
+    /** Embed an SVG <image> inside/around the node. */
+    image(href: string, w: number, h: number, opts?: {
+        dx?: number;
+        dy?: number;
+        position?: 'center' | 'above' | 'below' | 'left' | 'right';
+        preserveAspectRatio?: string;
+    }): NodeBuilder;
+    image(href: string, opts: {
+        w: number;
+        h: number;
+        dx?: number;
+        dy?: number;
+        position?: 'center' | 'above' | 'below' | 'left' | 'right';
+        preserveAspectRatio?: string;
+    }): NodeBuilder;
+    /** Render a registered SVG icon inside/around the node. */
+    icon(id: string, opts: {
+        size: number;
+        color?: string;
+        dx?: number;
+        dy?: number;
+        position?: 'center' | 'above' | 'below' | 'left' | 'right';
+    }): NodeBuilder;
+    /** Render inline SVG content inside/around the node. */
+    svgContent(content: string, w: number, h: number, opts?: {
+        dx?: number;
+        dy?: number;
+        position?: 'center' | 'above' | 'below' | 'left' | 'right';
+    }): NodeBuilder;
+    svgContent(content: string, opts: {
+        w: number;
+        h: number;
+        dx?: number;
+        dy?: number;
+        position?: 'center' | 'above' | 'below' | 'left' | 'right';
+    }): NodeBuilder;
     label(text: string, opts?: Partial<NodeLabel>): NodeBuilder;
+    /**
+     * Create a rich text label (mixed formatting) using nested SVG <tspan> spans.
+     *
+     * Note: Rich labels currently support explicit newlines via `l.newline()`.
+     */
+    richLabel(cb: (l: RichLabelBuilder) => unknown, opts?: Partial<Omit<NodeLabel, 'text' | 'rich'>>): NodeBuilder;
     fill(color: string): NodeBuilder;
     stroke(color: string, width?: number): NodeBuilder;
     opacity(value: number): NodeBuilder;
     class(name: string): NodeBuilder;
+    zIndex(value: number): NodeBuilder;
     animate(type: string, config?: AnimationConfig): NodeBuilder;
     animate(cb: (anim: AnimationBuilder) => unknown): NodeBuilder;
     /** Sugar for `animate(a => a.to(...))`. */
@@ -127,7 +238,7 @@ interface NodeBuilder {
     overlay<K extends OverlayId>(id: K, params: OverlayParams<K>, key?: string): VizBuilder;
     overlay<T>(id: string, params: T, key?: string): VizBuilder;
     build(): VizScene;
-    svg(): string;
+    svg(opts?: SvgExportOptions): string;
 }
 interface EdgeBuilder {
     straight(): EdgeBuilder;
@@ -136,6 +247,12 @@ interface EdgeBuilder {
     routing(mode: EdgeRouting): EdgeBuilder;
     via(x: number, y: number): EdgeBuilder;
     label(text: string, opts?: Partial<EdgeLabel>): EdgeBuilder;
+    /**
+     * Create a rich text label (mixed formatting) using nested SVG <tspan> spans.
+     *
+     * Note: Rich labels currently support explicit newlines via `l.newline()`.
+     */
+    richLabel(cb: (l: RichLabelBuilder) => unknown, opts?: Partial<Omit<EdgeLabel, 'text' | 'rich'>>): EdgeBuilder;
     /**
      * Set arrow markers. Convenience method.
      * - `arrow(true)` or `arrow()` sets markerEnd to 'arrow'
@@ -172,8 +289,20 @@ interface EdgeBuilder {
     animate(cb: (anim: AnimationBuilder) => unknown): EdgeBuilder;
     /** Sugar for `animate(a => a.to(...))`. */
     animateTo(props: AnimatableProps, opts: TweenOptions): EdgeBuilder;
+    /** Attach arbitrary consumer-defined metadata to the edge. */
+    meta(meta: Record<string, unknown>): EdgeBuilder;
     data(payload: unknown): EdgeBuilder;
     onClick(handler: (id: string, edge: VizEdge) => void): EdgeBuilder;
+    /**
+     * For self-loops: which side the loop exits from.
+     * @default 'top'
+     */
+    loopSide(side: 'top' | 'right' | 'bottom' | 'left'): EdgeBuilder;
+    /**
+     * For self-loops: how far the loop extends from the shape boundary.
+     * @default 30
+     */
+    loopSize(size: number): EdgeBuilder;
     done(): VizBuilder;
     node(id: string): NodeBuilder;
     node(id: string, opts: NodeOptions): VizBuilder;
@@ -183,7 +312,7 @@ interface EdgeBuilder {
     overlay<K extends OverlayId>(id: K, params: OverlayParams<K>, key?: string): VizBuilder;
     overlay<T>(id: string, params: T, key?: string): VizBuilder;
     build(): VizScene;
-    svg(): string;
+    svg(opts?: SvgExportOptions): string;
 }
 export declare function viz(): VizBuilder;
 export {};