vizcraft 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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
+
+- [`86655bf`](https://github.com/ChipiKaf/vizcraft/commit/86655bf59c9641af18416b79d0775212a9ecd15e) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - Added support for incremental scene updates, node resizing, JSON serialization/deserialization, viewport pan and zoom functionality, multi-line labels with text wrapping, declarative API options for nodes and edges, and custom dashed/dotted edge line styles.
+
 ## 1.0.0
 
 ### Major 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,71 @@ 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:
+
+```typescript
+// Declarative — pass all options at once, returns VizBuilder
+b.node('a', {
+  at: { x: 100, y: 100 },
+  rect: { w: 80, h: 40 },
+  fill: 'steelblue',
+  label: 'A',
+})
+  .node('b', { circle: { r: 20 }, at: { x: 300, y: 100 }, label: 'B' })
+  .edge('a', 'b', { arrow: true, stroke: 'red', dash: 'dashed' })
+  .build();
+```
+
+Both `NodeOptions` and `EdgeOptions` types are exported for full type-safety. See the [Essentials docs](https://vizcraft.dev/docs/essentials) for the complete options reference.
+
 ### Nodes
 
 Nodes are the primary entities in your graph. They can have shapes, labels, and styles.
@@ -121,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
@@ -155,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
@@ -166,21 +242,45 @@ 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);
 
+// Dashed, dotted, and custom dash patterns
+b.edge('a', 'b').dashed().stroke('#6c7086'); // dashed line
+b.edge('a', 'b').dotted(); // dotted line
+b.edge('a', 'b').dash('12, 3, 3, 3').stroke('#cba6f7'); // custom pattern
+
 // Multi-position edge labels (start / mid / end)
 b.edge('a', 'b')
   .label('1', { position: 'start' })
   .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
@@ -204,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`.                                                                              |
@@ -212,6 +313,9 @@ b.edge('a', 'b').fromPort('right').toPort('left').arrow();
 | `.stroke(color, width?)` | Set stroke color and optional width.                                                                                                  |
 | `.fill(color)`           | Set fill color.                                                                                                                       |
 | `.opacity(value)`        | Set opacity (0–1).                                                                                                                    |
+| `.dashed()`              | Dashed stroke (`8, 4`).                                                                                                               |
+| `.dotted()`              | Dotted stroke (`2, 4`).                                                                                                               |
+| `.dash(pattern)`         | Custom SVG dasharray or preset (`'dashed'`, `'dotted'`, `'dash-dot'`, `'solid'`).                                                     |
 
 **`EdgeMarkerType`** values: `'none'`, `'arrow'`, `'arrowOpen'`, `'diamond'`, `'diamondOpen'`, `'circle'`, `'circleOpen'`, `'square'`, `'bar'`, `'halfArrow'`.
 

package/dist/builder.d.ts

@@ -1,9 +1,37 @@
-import type { VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, AnimationConfig, OverlayId, OverlayParams, VizGridConfig, ContainerConfig, EdgeRouting, EdgeMarkerType } 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';
-interface VizBuilder {
+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;
@@ -18,20 +46,28 @@ interface VizBuilder {
     overlay(cb: (overlay: OverlayBuilder) => unknown): VizBuilder;
     overlay<K extends OverlayId>(id: K, params: OverlayParams<K>, key?: string): VizBuilder;
     overlay<T>(id: string, params: T, key?: string): VizBuilder;
+    /** Create a node and return the NodeBuilder for fluent chaining. */
     node(id: string): NodeBuilder;
+    /** Create a fully-configured node declaratively and return the parent VizBuilder. */
+    node(id: string, opts: NodeOptions): VizBuilder;
+    /** Create an edge and return the EdgeBuilder for fluent chaining. */
     edge(from: string, to: string, id?: string): EdgeBuilder;
+    /** Create a fully-configured edge declaratively and return the parent VizBuilder. */
+    edge(from: string, to: string, opts: EdgeOptions): VizBuilder;
+    /** Hydrates the builder from an existing VizScene. */
+    fromScene(scene: VizScene): VizBuilder;
     build(): VizScene;
     _getGridConfig(): VizGridConfig | null;
     _getViewBox(): {
         w: number;
         h: number;
     };
-    svg(): string;
-    mount(container: HTMLElement): void;
+    svg(opts?: SvgExportOptions): string;
+    mount(container: HTMLElement): PanZoomController | undefined;
     mount(container: HTMLElement, opts: {
         autoplay?: boolean;
         css?: string | string[];
-    }): void;
+    } & PanZoomOptions): PanZoomController | undefined;
     /**
      * Plays animation specs against a mounted container.
      *
@@ -45,11 +81,59 @@ interface VizBuilder {
     play(container: HTMLElement): PlaybackController | null;
     play(container: HTMLElement, spec: AnimationSpec): PlaybackController;
     play(container: HTMLElement, spec: AnimationSpec[]): PlaybackController;
+    /**
+     * Resizes a node at runtime, overriding its initial shape dimensions.
+     */
+    resizeNode(id: string, dims: {
+        w?: number;
+        h?: number;
+        r?: number;
+    }): VizBuilder;
     /**
      * Applies runtime-only patches (node.runtime / edge.runtime) to the mounted SVG.
      * 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;
@@ -79,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(...))`. */
@@ -104,12 +231,14 @@ interface NodeBuilder {
     parent(parentId: string): NodeBuilder;
     done(): VizBuilder;
     node(id: string): NodeBuilder;
+    node(id: string, opts: NodeOptions): VizBuilder;
     edge(from: string, to: string, id?: string): EdgeBuilder;
+    edge(from: string, to: string, opts: EdgeOptions): VizBuilder;
     overlay(cb: (overlay: OverlayBuilder) => unknown): VizBuilder;
     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;
@@ -118,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'
@@ -142,22 +277,42 @@ interface EdgeBuilder {
     stroke(color: string, width?: number): EdgeBuilder;
     /** Sets the opacity of the edge. */
     opacity(value: number): EdgeBuilder;
+    /** Apply a dashed stroke pattern (`8, 4`). */
+    dashed(): EdgeBuilder;
+    /** Apply a dotted stroke pattern (`2, 4`). */
+    dotted(): EdgeBuilder;
+    /** Apply a custom SVG `stroke-dasharray` value, or a preset name (`'dashed'`, `'dotted'`, `'dash-dot'`). */
+    dash(pattern: 'solid' | 'dashed' | 'dotted' | 'dash-dot' | string): EdgeBuilder;
     class(name: string): EdgeBuilder;
     hitArea(px: number): EdgeBuilder;
     animate(type: string, config?: AnimationConfig): 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;
     edge(from: string, to: string, id?: string): EdgeBuilder;
+    edge(from: string, to: string, opts: EdgeOptions): VizBuilder;
     overlay(cb: (overlay: OverlayBuilder) => unknown): VizBuilder;
     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 {};