vizcraft 0.2.2 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # vizcraft
 
+## 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
+
+- [`c5ffe75`](https://github.com/ChipiKaf/vizcraft/commit/c5ffe7546a2e2148618db057c24aea01ecf097e0) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - Add improved overlay api
+
 ## 0.2.2
 
 ### Patch 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

@@ -101,15 +101,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 +156,65 @@ 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);
+
+// 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).                                                                                                                    |
+
+**`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 +361,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/anim/animationBuilder.d.ts

@@ -38,6 +38,8 @@ export declare class AnimationBuilder {
     extendAdapter(cb: ExtendAdapter): this;
     /** Select a node by id (compiles to target `node:<id>`). */
     node(id: string): this;
+    /** Select an overlay by key (compiles to target `overlay:<key>`). */
+    overlay(key: string): this;
     /**
      * Select an edge.
      *

package/dist/anim/animationBuilder.js

@@ -30,6 +30,11 @@ export class AnimationBuilder {
         this.currentTarget = toTarget('node', id);
         return this;
     }
+    /** Select an overlay by key (compiles to target `overlay:<key>`). */
+    overlay(key) {
+        this.currentTarget = toTarget('overlay', key);
+        return this;
+    }
     edge(a, b, c) {
         const id = b === undefined ? a : (c ?? `${a}->${b}`);
         this.currentTarget = toTarget('edge', id);
@@ -56,7 +61,7 @@ export class AnimationBuilder {
      */
     to(props, opts) {
         if (!this.currentTarget) {
-            throw new Error('AnimationBuilder.to(): no target selected (call node(...) or edge(...))');
+            throw new Error('AnimationBuilder.to(): no target selected (call node(...), edge(...), or overlay(...))');
         }
         const duration = Math.max(0, opts.duration);
         const easing = opts.easing;

package/dist/anim/spec.d.ts

@@ -1,4 +1,4 @@
-export type AnimationTarget = (`node:${string}` | `edge:${string}`) | (string & {});
+export type AnimationTarget = (`node:${string}` | `edge:${string}` | `overlay:${string}`) | (string & {});
 export type CoreAnimProperty = 'x' | 'y' | 'opacity' | 'scale' | 'rotation' | 'strokeDashoffset';
 export type AnimProperty = CoreAnimProperty | (string & {});
 export type Ease = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';

package/dist/anim/vizcraftAdapter.js

@@ -1,13 +1,21 @@
+import { OVERLAY_RUNTIME_DIRTY } from '../types';
 import { createRegistryAdapter } from './registryAdapter';
 export function createVizCraftAdapter(scene, requestRender) {
     const nodesById = new Map(scene.nodes.map((n) => [n.id, n]));
     const edgesById = new Map(scene.edges.map((e) => [e.id, e]));
+    const overlays = scene.overlays ?? [];
+    const overlaysByKey = new Map();
+    for (const spec of overlays) {
+        const key = spec.key ?? spec.id;
+        overlaysByKey.set(key, spec);
+    }
     const adapter = createRegistryAdapter({
         flush: requestRender,
     });
     // register node/edge target resolvers and props using ergonomic handles
     const node = adapter.kind('node', (id) => nodesById.get(id));
     const edge = adapter.kind('edge', (id) => edgesById.get(id));
+    const overlay = adapter.kind('overlay', (key) => overlaysByKey.get(key));
     node
         .prop('x', {
         get: (el) => {
@@ -75,5 +83,64 @@ export function createVizCraftAdapter(scene, requestRender) {
             e.runtime.strokeDashoffset = v;
         },
     });
-    return adapter;
+    // Overlay params: allow animating arbitrary numeric fields on `spec.params`.
+    //
+    // This intentionally uses a generic reader/writer so users can animate
+    // custom overlays without needing adapter extensions.
+    const overlayParamReader = (el, prop) => {
+        const spec = el;
+        const params = spec.params;
+        const v = params?.[prop];
+        return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+    };
+    const overlayParamWriter = (el, prop, value) => {
+        const spec = el;
+        const existing = spec.params;
+        const params = existing && typeof existing === 'object' && !Array.isArray(existing)
+            ? existing
+            : {};
+        params[prop] = value;
+        // Ensure we keep reference stable in case params was undefined or non-object.
+        spec.params = params;
+        // Mark dirty so patchRuntime can avoid re-rendering unaffected overlays.
+        spec[OVERLAY_RUNTIME_DIRTY] = true;
+    };
+    const resolveOverlayFromTarget = (target) => {
+        const t = String(target);
+        if (!t.startsWith('overlay:'))
+            return undefined;
+        const key = t.slice('overlay:'.length);
+        return overlaysByKey.get(key);
+    };
+    // Register core overlay props we know are numeric today.
+    // Users can still register more via adapter extensions if they prefer explicitness.
+    overlay.prop('progress', {
+        get: (el) => overlayParamReader(el, 'progress'),
+        set: (el, v) => overlayParamWriter(el, 'progress', v),
+    });
+    // Make overlays fully generic: any numeric `spec.params[prop]` is animatable.
+    //
+    // `createRegistryAdapter` requires per-prop registration; for overlays we provide
+    // a fallback so custom overlays don't need adapter extensions.
+    const baseGet = adapter.get;
+    const baseSet = adapter.set;
+    return {
+        ...adapter,
+        get(target, prop) {
+            const v = baseGet(target, prop);
+            if (v !== undefined)
+                return v;
+            const spec = resolveOverlayFromTarget(target);
+            if (!spec)
+                return undefined;
+            return overlayParamReader(spec, String(prop));
+        },
+        set(target, prop, value) {
+            baseSet(target, prop, value);
+            const spec = resolveOverlayFromTarget(target);
+            if (!spec)
+                return;
+            overlayParamWriter(spec, String(prop), value);
+        },
+    };
 }

package/dist/builder.d.ts

@@ -1,4 +1,5 @@
-import type { VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, AnimationConfig, VizGridConfig } from './types';
+import type { VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, AnimationConfig, OverlayId, OverlayParams, VizGridConfig, ContainerConfig, EdgeRouting, EdgeMarkerType } 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';
@@ -13,6 +14,9 @@ interface VizBuilder {
      * The compiled spec is also stored on the built scene as `scene.animationSpecs`.
      */
     animate(cb: (anim: AnimationBuilder) => unknown): AnimationSpec;
+    /** Fluent overlay authoring (compiles to overlay specs and stores on the built scene). */
+    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;
     node(id: string): NodeBuilder;
     edge(from: string, to: string, id?: string): EdgeBuilder;
@@ -53,6 +57,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;
@@ -64,18 +90,58 @@ 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;
     edge(from: string, to: string, id?: string): EdgeBuilder;
+    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;
 }
 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;
     class(name: string): EdgeBuilder;
     hitArea(px: number): EdgeBuilder;
     animate(type: string, config?: AnimationConfig): EdgeBuilder;
@@ -87,6 +153,8 @@ interface EdgeBuilder {
     done(): VizBuilder;
     node(id: string): NodeBuilder;
     edge(from: string, to: string, id?: string): EdgeBuilder;
+    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;