vizcraft 0.3.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # vizcraft
 
+## 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
+
+- [`73ee1fb`](https://github.com/ChipiKaf/vizcraft/commit/73ee1fbd204bf1ba0447c764eba2c1b9d6981ee5) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - Added new shapes, connection ports, path based edges, Edge marker types, Multi-position edge labels, Containers and The overlay builder
+
 ## 0.3.0
 
 ### Minor Changes

package/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chipili Kafwilo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -92,6 +92,25 @@ b.view(width, height) // Set the coordinate space
   .edge(from, to); // Start defining an edge
 ```
 
+### 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.
@@ -101,15 +120,54 @@ b.node('n1')
  .at(x, y)               // Absolute position
  // OR
  .cell(col, row)         // Grid position
- .circle(radius)         // Shape definition
+ .circle(radius)         // Circle shape
+ .rect(w, h, [rx])       // Rectangle (optional corner radius)
+ .diamond(w, h)          // Diamond shape
+ .cylinder(w, h, [arcHeight]) // Cylinder (database symbol)
+ .hexagon(r, [orientation])   // Hexagon ('pointy' or 'flat')
+ .ellipse(rx, ry)        // Ellipse / oval
+ .arc(r, start, end, [closed]) // Arc / pie slice
+ .blockArrow(len, bodyW, headW, headLen, [dir]) // Block arrow
+ .callout(w, h, [opts])   // Speech bubble / callout
+ .cloud(w, h)             // Cloud / thought bubble
+ .cross(size, [barWidth])  // Cross / plus sign
+ .cube(w, h, [depth])      // 3D isometric cube
+ .path(d, w, h)            // Custom SVG path
+ .document(w, h, [wave])   // Document (wavy bottom)
+ .note(w, h, [foldSize])   // Note (folded corner)
+ .parallelogram(w, h, [skew]) // Parallelogram (I/O)
+ .star(points, outerR, [innerR]) // Star / badge
+ .trapezoid(topW, bottomW, h) // Trapezoid
+ .triangle(w, h, [direction]) // Triangle
  .label('Text', { dy: 5 }) // Label with offset
  .class('css-class')     // Custom CSS class
  .data({ ... })          // Attach custom data
+ .port('out', { x: 50, y: 0 }) // Named connection port
+ .container(config?)     // Mark as container / group node
+ .parent('containerId')  // Make child of a container
+```
+
+### Container / Group Nodes
+
+Group related nodes into visual containers (swimlanes, sub-processes, etc.).
+
+```typescript
+b.node('lane')
+  .at(250, 170)
+  .rect(460, 300)
+  .label('Process Phase')
+  .container({ headerHeight: 36 });
+
+b.node('step1').at(150, 220).rect(100, 50).parent('lane');
+b.node('step2').at(350, 220).rect(100, 50).parent('lane');
 ```
 
+Container children are nested inside the container `<g>` in the SVG and follow the container when moved at runtime.
+
 ### Edges
 
 Edges connect nodes and can be styled, directed, or animated.
+All edges are rendered as `<path>` elements supporting three routing modes.
 
 ```typescript
 b.edge('n1', 'n2')
@@ -117,8 +175,73 @@ b.edge('n1', 'n2')
   .straight() // (Default) Straight line
   .label('Connection')
   .animate('flow'); // Add animation
+
+// Curved edge
+b.edge('a', 'b').curved().arrow();
+
+// Orthogonal (right-angle) edge
+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();
+
+// 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();
+
+// 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
+b.edge('a', 'b').markerEnd('bar'); // ER cardinality
+
+// Connection ports — edges attach to specific points on nodes
+b.node('srv')
+  .at(100, 100)
+  .rect(80, 60)
+  .port('out-1', { x: 40, y: -15 })
+  .port('out-2', { x: 40, y: 15 });
+b.node('db').at(400, 100).cylinder(80, 60).port('in', { x: -40, y: 0 });
+b.edge('srv', 'db').fromPort('out-1').toPort('in').arrow();
+
+// Default ports (no .port() needed) — every shape has built-in ports
+b.edge('a', 'b').fromPort('right').toPort('left').arrow();
 ```
 
+| Method                   | Description                                                                                                                           |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `.straight()`            | Direct line (default). With waypoints → polyline.                                                                                     |
+| `.curved()`              | Smooth bezier curve. With waypoints → Catmull-Rom spline.                                                                             |
+| `.orthogonal()`          | Right-angle elbows.                                                                                                                   |
+| `.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'`.    |
+| `.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`.                                                                              |
+| `.fromPort(portId)`      | Connect from a specific named port on the source node.                                                                                |
+| `.toPort(portId)`        | Connect to a specific named port on the target node.                                                                                  |
+| `.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'`.
+
 ### Animations
 
 See the full Animations guide [docs here](https://vizcraft-docs.vercel.app/docs/animations).
@@ -265,13 +388,19 @@ VizCraft generates standard SVG elements with predictable classes, making it eas
   fill: #ff6b6b;
 }
 
-/* Edge styling */
+/* Edge styling (CSS defaults) */
 .viz-edge {
   stroke: #ccc;
   stroke-width: 2;
 }
 ```
 
+Edges can also be styled **per-edge** via the builder (inline SVG attributes override CSS):
+
+```ts
+b.edge('a', 'b').stroke('#e74c3c', 3).fill('none').opacity(0.8);
+```
+
 ## 🤝 Contributing
 
 Contributions are welcome! This is a monorepo managed with Turbo.

package/dist/builder.d.ts

@@ -1,9 +1,9 @@
-import type { VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, AnimationConfig, OverlayId, OverlayParams, VizGridConfig } from './types';
+import type { VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, AnimationConfig, OverlayId, OverlayParams, VizGridConfig, ContainerConfig, EdgeRouting, EdgeMarkerType, NodeOptions, EdgeOptions, PanZoomOptions, PanZoomController, VizSceneMutator } 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 {
     view(w: number, h: number): VizBuilder;
     grid(cols: number, rows: number, padding?: {
         x: number;
@@ -18,8 +18,16 @@ 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(): {
@@ -27,11 +35,11 @@ interface VizBuilder {
         h: number;
     };
     svg(): string;
-    mount(container: HTMLElement): void;
+    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,6 +53,14 @@ 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.
@@ -57,6 +73,28 @@ interface NodeBuilder {
     circle(r: number): NodeBuilder;
     rect(w: number, h: number, rx?: number): NodeBuilder;
     diamond(w: number, h: number): NodeBuilder;
+    cylinder(w: number, h: number, arcHeight?: number): NodeBuilder;
+    hexagon(r: number, orientation?: 'pointy' | 'flat'): NodeBuilder;
+    ellipse(rx: number, ry: number): NodeBuilder;
+    arc(r: number, startAngle: number, endAngle: number, closed?: boolean): NodeBuilder;
+    blockArrow(length: number, bodyWidth: number, headWidth: number, headLength: number, direction?: 'right' | 'left' | 'up' | 'down'): NodeBuilder;
+    callout(w: number, h: number, opts?: {
+        rx?: number;
+        pointerSide?: 'bottom' | 'top' | 'left' | 'right';
+        pointerHeight?: number;
+        pointerWidth?: number;
+        pointerPosition?: number;
+    }): NodeBuilder;
+    cloud(w: number, h: number): NodeBuilder;
+    cross(size: number, barWidth?: number): NodeBuilder;
+    cube(w: number, h: number, depth?: number): NodeBuilder;
+    path(d: string, w: number, h: number): NodeBuilder;
+    document(w: number, h: number, waveHeight?: number): NodeBuilder;
+    note(w: number, h: number, foldSize?: number): NodeBuilder;
+    parallelogram(w: number, h: number, skew?: number): 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;
     label(text: string, opts?: Partial<NodeLabel>): NodeBuilder;
     fill(color: string): NodeBuilder;
     stroke(color: string, width?: number): NodeBuilder;
@@ -68,9 +106,23 @@ interface NodeBuilder {
     animateTo(props: AnimatableProps, opts: TweenOptions): NodeBuilder;
     data(payload: unknown): NodeBuilder;
     onClick(handler: (id: string, node: VizNode) => void): NodeBuilder;
+    /**
+     * Define a named connection port on the node.
+     * @param id   Unique port id (e.g. `'top'`, `'out-1'`)
+     * @param offset Position relative to the node center `{ x, y }`
+     * @param direction Optional outgoing tangent in degrees (0=right, 90=down, 180=left, 270=up)
+     */
+    port(id: string, offset: {
+        x: number;
+        y: number;
+    }, direction?: number): NodeBuilder;
+    container(config?: ContainerConfig): 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;
@@ -79,9 +131,41 @@ interface NodeBuilder {
 }
 interface EdgeBuilder {
     straight(): EdgeBuilder;
+    curved(): EdgeBuilder;
+    orthogonal(): EdgeBuilder;
+    routing(mode: EdgeRouting): EdgeBuilder;
+    via(x: number, y: number): EdgeBuilder;
     label(text: string, opts?: Partial<EdgeLabel>): EdgeBuilder;
-    arrow(enabled?: boolean): EdgeBuilder;
+    /**
+     * Set arrow markers. Convenience method.
+     * - `arrow(true)` or `arrow()` sets markerEnd to 'arrow'
+     * - `arrow(false)` sets markerEnd to 'none'
+     * - `arrow('both')` sets both markerStart and markerEnd to 'arrow'
+     * - `arrow('start')` sets markerStart to 'arrow'
+     * - `arrow('end')` sets markerEnd to 'arrow'
+     */
+    arrow(enabled?: boolean | 'both' | 'start' | 'end'): EdgeBuilder;
+    /** Set the marker type at the end (target) of the edge. */
+    markerEnd(type: EdgeMarkerType): EdgeBuilder;
+    /** Set the marker type at the start (source) of the edge. */
+    markerStart(type: EdgeMarkerType): EdgeBuilder;
+    /** Connect the edge to a specific port on the source node. */
+    fromPort(portId: string): EdgeBuilder;
+    /** Connect the edge to a specific port on the target node. */
+    toPort(portId: string): EdgeBuilder;
     connect(anchor: 'center' | 'boundary'): EdgeBuilder;
+    /** Sets the fill color of the edge path. */
+    fill(color: string): EdgeBuilder;
+    /** Sets the stroke color and optional width of the edge path. */
+    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;
@@ -92,7 +176,9 @@ interface EdgeBuilder {
     onClick(handler: (id: string, edge: VizEdge) => void): 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;