vizcraft 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # vizcraft
 
+## 0.1.5
+
+### Patch Changes
+
+- [`ecb5ade`](https://github.com/ChipiKaf/vizcraft/commit/ecb5adef774e30589a0714699ccdb7839530bd50) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - update docs with correct code snippets
+
+## 0.1.4
+
+### Patch Changes
+
+- [`10926fc`](https://github.com/ChipiKaf/vizcraft/commit/10926fcce211d00dfba2697eaac62948ac0ef69d) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - update readme
+
 ## 0.1.3
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,133 @@
+# VizCraft
+
+**A declarative, builder-based library for creating animated SVG network visualizations and algorithm demos.**
+
+VizCraft is designed to make creating beautiful, animated node-link diagrams and complex visualizations intuitive and powerful. Whether you are building an educational tool, explaining an algorithm, or just need a great looking graph, VizCraft provides the primitives you need.
+
+## ✨ Features
+
+- **Fluent Builder API**: Define your visualization scene using a readable, chainable API.
+- **Grid System**: Built-in 2D grid system for easy, structured layout of nodes.
+- **Declarative Animations**: Animate layout changes, edge flow, and node states with a simple declarative config.
+- **Framework Agnostic**: The core logic is pure TypeScript and can be used with any framework or Vanilla JS.
+- **Custom Overlays**: Create complex, custom UI elements that float on top of your visualization.
+
+## 📦 Installation
+
+```bash
+npm install vizcraft
+# or
+pnpm add vizcraft
+# or
+yarn add vizcraft
+```
+
+## 🚀 Getting Started
+
+You can use the core library directly to generate SVG content or mount to a DOM element.
+
+```typescript
+import { viz } from 'vizcraft';
+
+const builder = viz().view(800, 600);
+
+builder
+  .view(500, 500)
+  .node('a')
+  .at(100, 100)
+  .circle(15)
+  .label('A')
+  .node('b')
+  .at(400, 100)
+  .circle(15)
+  .label('B')
+  .edge('a', 'b')
+  .arrow();
+
+const container = document.getElementById('viz-basic');
+if (container) builder.mount(container);
+```
+
+## 📖 Core Concepts
+
+### The Builder (`VizBuilder`)
+
+The heart of VizCraft is the `VizBuilder`. It allows you to construct a `VizScene` which acts as the blueprint for your visualization.
+
+```typescript
+b.view(width, height) // Set the coordinate space
+  .grid(cols, rows) // (Optional) Define layout grid
+  .node(id) // Start defining a node
+  .edge(from, to); // Start defining an edge
+```
+
+### Nodes
+
+Nodes are the primary entities in your graph. They can have shapes, labels, and styles.
+
+```typescript
+b.node('n1')
+ .at(x, y)               // Absolute position
+ // OR
+ .cell(col, row)         // Grid position
+ .circle(radius)         // Shape definition
+ .label('Text', { dy: 5 }) // Label with offset
+ .class('css-class')     // Custom CSS class
+ .data({ ... })          // Attach custom data
+```
+
+### Edges
+
+Edges connect nodes and can be styled, directed, or animated.
+
+```typescript
+b.edge('n1', 'n2')
+  .arrow() // Add an arrowhead
+  .straight() // (Default) Straight line
+  .label('Connection')
+  .animate('flow'); // Add animation
+```
+
+### Animations
+
+VizCraft supports declarative animations. You define _what_ happens, and the renderer handles the interpolation.
+
+- **`stream`**: Particles flowing along an edge.
+- **`pulse`**: Rhythmic scaling or opacity changes.
+- **Transition**: Moving a node from one position to another.
+
+## 🎨 Styling
+
+VizCraft generates standard SVG elements with predictable classes, making it easy to style with CSS.
+
+```css
+/* Custom node style */
+.viz-node-shape {
+  fill: #fff;
+  stroke: #333;
+  stroke-width: 2px;
+}
+
+/* Specific node class */
+.my-node .viz-node-shape {
+  fill: #ff6b6b;
+}
+
+/* Edge styling */
+.viz-edge {
+  stroke: #ccc;
+  stroke-width: 2;
+}
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! This is a monorepo managed with Turbo.
+
+1. Clone the repo
+2. Install dependencies: `pnpm install`
+3. Run dev server: `pnpm dev`
+
+## 📄 License
+
+MIT License © Chipili Kafwilo

package/dist/builder.d.ts

@@ -24,6 +24,9 @@ interface NodeBuilder {
     rect(w: number, h: number, rx?: number): NodeBuilder;
     diamond(w: number, h: number): NodeBuilder;
     label(text: string, opts?: Partial<NodeLabel>): NodeBuilder;
+    fill(color: string): NodeBuilder;
+    stroke(color: string, width?: number): NodeBuilder;
+    opacity(value: number): NodeBuilder;
     class(name: string): NodeBuilder;
     animate(type: string, config?: AnimationConfig): NodeBuilder;
     data(payload: unknown): NodeBuilder;
@@ -39,6 +42,7 @@ interface EdgeBuilder {
     straight(): EdgeBuilder;
     label(text: string, opts?: Partial<EdgeLabel>): EdgeBuilder;
     arrow(enabled?: boolean): EdgeBuilder;
+    connect(anchor: 'center' | 'boundary'): EdgeBuilder;
     class(name: string): EdgeBuilder;
     hitArea(px: number): EdgeBuilder;
     animate(type: string, config?: AnimationConfig): EdgeBuilder;

package/dist/builder.js

@@ -1,6 +1,63 @@
 import { DEFAULT_VIZ_CSS } from './styles';
 import { defaultCoreAnimationRegistry } from './animations';
 import { defaultCoreOverlayRegistry } from './overlays';
+function setSvgAttributes(el, attrs) {
+    Object.entries(attrs).forEach(([key, value]) => {
+        if (value === undefined) {
+            el.removeAttribute(key);
+        }
+        else {
+            el.setAttribute(key, String(value));
+        }
+    });
+}
+function svgAttributeString(attrs) {
+    return Object.entries(attrs)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => ` ${key}="${String(value)}"`)
+        .join('');
+}
+function computeNodeAnchor(node, target, anchor) {
+    if (anchor === 'center') {
+        return { x: node.pos.x, y: node.pos.y };
+    }
+    const dx = target.x - node.pos.x;
+    const dy = target.y - node.pos.y;
+    if (dx === 0 && dy === 0) {
+        return { x: node.pos.x, y: node.pos.y };
+    }
+    if (node.shape.kind === 'circle') {
+        const dist = Math.hypot(dx, dy) || 1;
+        const scale = node.shape.r / dist;
+        return {
+            x: node.pos.x + dx * scale,
+            y: node.pos.y + dy * scale,
+        };
+    }
+    if (node.shape.kind === 'rect') {
+        const hw = node.shape.w / 2;
+        const hh = node.shape.h / 2;
+        const scale = Math.min(hw / Math.abs(dx || 1e-6), hh / Math.abs(dy || 1e-6));
+        return {
+            x: node.pos.x + dx * scale,
+            y: node.pos.y + dy * scale,
+        };
+    }
+    const hw = node.shape.w / 2;
+    const hh = node.shape.h / 2;
+    const denom = Math.abs(dx) / hw + Math.abs(dy) / hh;
+    const scale = denom === 0 ? 0 : 1 / denom;
+    return {
+        x: node.pos.x + dx * scale,
+        y: node.pos.y + dy * scale,
+    };
+}
+function computeEdgeEndpoints(start, end, edge) {
+    const anchor = edge.anchor ?? 'boundary';
+    const startAnchor = computeNodeAnchor(start, end.pos, anchor);
+    const endAnchor = computeNodeAnchor(end, start.pos, anchor);
+    return { start: startAnchor, end: endAnchor };
+}
 class VizBuilderImpl {
     _viewBox = { w: 800, h: 600 };
     _nodes = new Map();
@@ -217,12 +274,13 @@ class VizBuilderImpl {
                 });
             }
             group.setAttribute('class', classes);
+            const endpoints = computeEdgeEndpoints(start, end, edge);
             // Update Line
             const line = group.querySelector('.viz-edge');
-            line.setAttribute('x1', String(start.pos.x));
-            line.setAttribute('y1', String(start.pos.y));
-            line.setAttribute('x2', String(end.pos.x));
-            line.setAttribute('y2', String(end.pos.y));
+            line.setAttribute('x1', String(endpoints.start.x));
+            line.setAttribute('y1', String(endpoints.start.y));
+            line.setAttribute('x2', String(endpoints.end.x));
+            line.setAttribute('y2', String(endpoints.end.y));
             line.setAttribute('stroke', 'currentColor');
             if (edge.markerEnd === 'arrow') {
                 line.setAttribute('marker-end', 'url(#viz-arrow)');
@@ -236,10 +294,10 @@ class VizBuilderImpl {
             if (edge.hitArea || edge.onClick) {
                 const hit = document.createElementNS(svgNS, 'line');
                 hit.setAttribute('class', 'viz-edge-hit'); // Add class for selection
-                hit.setAttribute('x1', String(start.pos.x));
-                hit.setAttribute('y1', String(start.pos.y));
-                hit.setAttribute('x2', String(end.pos.x));
-                hit.setAttribute('y2', String(end.pos.y));
+                hit.setAttribute('x1', String(endpoints.start.x));
+                hit.setAttribute('y1', String(endpoints.start.y));
+                hit.setAttribute('x2', String(endpoints.end.x));
+                hit.setAttribute('y2', String(endpoints.end.y));
                 hit.setAttribute('stroke', 'transparent');
                 hit.setAttribute('stroke-width', String(edge.hitArea || 10));
                 hit.style.cursor = edge.onClick ? 'pointer' : '';
@@ -257,8 +315,8 @@ class VizBuilderImpl {
                 oldLabel.remove();
             if (edge.label) {
                 const text = document.createElementNS(svgNS, 'text');
-                const mx = (start.pos.x + end.pos.x) / 2 + (edge.label.dx || 0);
-                const my = (start.pos.y + end.pos.y) / 2 + (edge.label.dy || 0);
+                const mx = (endpoints.start.x + endpoints.end.x) / 2 + (edge.label.dx || 0);
+                const my = (endpoints.start.y + endpoints.end.y) / 2 + (edge.label.dy || 0);
                 text.setAttribute('x', String(mx));
                 text.setAttribute('y', String(my));
                 text.setAttribute('class', `viz-edge-label ${edge.label.className || ''}`);
@@ -375,13 +433,17 @@ class VizBuilderImpl {
                 const pts = `${x},${y - hh} ${x + hw},${y} ${x},${y + hh} ${x - hw},${y}`;
                 shape.setAttribute('points', pts);
             }
+            setSvgAttributes(shape, {
+                fill: node.style?.fill ?? 'none',
+                stroke: node.style?.stroke ?? '#111',
+                'stroke-width': node.style?.strokeWidth ?? 2,
+                opacity: node.style?.opacity,
+            });
             // Label (Recreate for simplicity as usually just text/pos changes)
             let label = group.querySelector('.viz-node-label');
             if (!label && node.label) {
                 label = document.createElementNS(svgNS, 'text');
                 label.setAttribute('class', 'viz-node-label');
-                label.setAttribute('text-anchor', 'middle');
-                label.setAttribute('dominant-baseline', 'middle');
                 group.appendChild(label);
             }
             if (node.label) {
@@ -389,8 +451,15 @@ class VizBuilderImpl {
                 const ly = y + (node.label.dy || 0);
                 label.setAttribute('x', String(lx));
                 label.setAttribute('y', String(ly));
+                label.setAttribute('text-anchor', node.label.textAnchor || 'middle');
+                label.setAttribute('dominant-baseline', node.label.dominantBaseline || 'middle');
                 // Update class carefully to preserve 'viz-node-label'
                 label.setAttribute('class', `viz-node-label ${node.label.className || ''}`);
+                setSvgAttributes(label, {
+                    fill: node.label.fill,
+                    'font-size': node.label.fontSize,
+                    'font-weight': node.label.fontWeight,
+                });
                 label.textContent = node.label.text;
             }
             else if (label) {
@@ -498,12 +567,13 @@ class VizBuilderImpl {
                 });
             }
             const markerEnd = edge.markerEnd === 'arrow' ? 'marker-end="url(#viz-arrow)"' : '';
+            const endpoints = computeEdgeEndpoints(start, end, edge);
             svgContent += `<g class="viz-edge-group ${edge.className || ''} ${animClasses}" style="${animStyleStr}">`;
-            svgContent += `<line x1="${start.pos.x}" y1="${start.pos.y}" x2="${end.pos.x}" y2="${end.pos.y}" class="viz-edge" ${markerEnd} stroke="currentColor" />`;
+            svgContent += `<line x1="${endpoints.start.x}" y1="${endpoints.start.y}" x2="${endpoints.end.x}" y2="${endpoints.end.y}" class="viz-edge" ${markerEnd} stroke="currentColor" />`;
             // Edge Label
             if (edge.label) {
-                const mx = (start.pos.x + end.pos.x) / 2 + (edge.label.dx || 0);
-                const my = (start.pos.y + end.pos.y) / 2 + (edge.label.dy || 0);
+                const mx = (endpoints.start.x + endpoints.end.x) / 2 + (edge.label.dx || 0);
+                const my = (endpoints.start.y + endpoints.end.y) / 2 + (edge.label.dy || 0);
                 const labelClass = `viz-edge-label ${edge.label.className || ''}`;
                 svgContent += `<text x="${mx}" y="${my}" class="${labelClass}" text-anchor="middle" dominant-baseline="middle">${edge.label.text}</text>`;
             }
@@ -536,25 +606,38 @@ class VizBuilderImpl {
             }
             const className = `viz-node-group ${node.className || ''} ${animClasses}`;
             svgContent += `<g class="${className}" style="${animStyleStr}">`;
+            const shapeStyleAttrs = svgAttributeString({
+                fill: node.style?.fill ?? 'none',
+                stroke: node.style?.stroke ?? '#111',
+                'stroke-width': node.style?.strokeWidth ?? 2,
+                opacity: node.style?.opacity,
+            });
             // Shape
             if (shape.kind === 'circle') {
-                svgContent += `<circle cx="${x}" cy="${y}" r="${shape.r}" class="viz-node-shape" />`;
+                svgContent += `<circle cx="${x}" cy="${y}" r="${shape.r}" class="viz-node-shape"${shapeStyleAttrs} />`;
             }
             else if (shape.kind === 'rect') {
-                svgContent += `<rect x="${x - shape.w / 2}" y="${y - shape.h / 2}" width="${shape.w}" height="${shape.h}" rx="${shape.rx || 0}" class="viz-node-shape" />`;
+                svgContent += `<rect x="${x - shape.w / 2}" y="${y - shape.h / 2}" width="${shape.w}" height="${shape.h}" rx="${shape.rx || 0}" class="viz-node-shape"${shapeStyleAttrs} />`;
             }
             else if (shape.kind === 'diamond') {
                 const hw = shape.w / 2;
                 const hh = shape.h / 2;
                 const pts = `${x},${y - hh} ${x + hw},${y} ${x},${y + hh} ${x - hw},${y}`;
-                svgContent += `<polygon points="${pts}" class="viz-node-shape" />`;
+                svgContent += `<polygon points="${pts}" class="viz-node-shape"${shapeStyleAttrs} />`;
             }
             // Label
             if (node.label) {
                 const lx = x + (node.label.dx || 0);
                 const ly = y + (node.label.dy || 0);
                 const labelClass = `viz-node-label ${node.label.className || ''}`;
-                svgContent += `<text x="${lx}" y="${ly}" class="${labelClass}" text-anchor="middle" dominant-baseline="middle">${node.label.text}</text>`;
+                const labelAttrs = svgAttributeString({
+                    fill: node.label.fill,
+                    'font-size': node.label.fontSize,
+                    'font-weight': node.label.fontWeight,
+                    'text-anchor': node.label.textAnchor || 'middle',
+                    'dominant-baseline': node.label.dominantBaseline || 'middle',
+                });
+                svgContent += `<text x="${lx}" y="${ly}" class="${labelClass}"${labelAttrs}>${node.label.text}</text>`;
             }
             svgContent += '</g>';
         });
@@ -626,6 +709,28 @@ class NodeBuilderImpl {
         this.nodeDef.label = { text, ...opts };
         return this;
     }
+    fill(color) {
+        this.nodeDef.style = {
+            ...(this.nodeDef.style || {}),
+            fill: color,
+        };
+        return this;
+    }
+    stroke(color, width) {
+        this.nodeDef.style = {
+            ...(this.nodeDef.style || {}),
+            stroke: color,
+            strokeWidth: width ?? this.nodeDef.style?.strokeWidth,
+        };
+        return this;
+    }
+    opacity(value) {
+        this.nodeDef.style = {
+            ...(this.nodeDef.style || {}),
+            opacity: value,
+        };
+        return this;
+    }
     class(name) {
         if (this.nodeDef.className) {
             this.nodeDef.className += ` ${name}`;
@@ -682,13 +787,17 @@ class EdgeBuilderImpl {
         return this;
     }
     label(text, opts) {
-        this.edgeDef.label = { position: 'mid', text, ...opts };
+        this.edgeDef.label = { position: 'mid', text, dy: -10, ...opts };
         return this;
     }
     arrow(enabled = true) {
         this.edgeDef.markerEnd = enabled ? 'arrow' : 'none';
         return this;
     }
+    connect(anchor) {
+        this.edgeDef.anchor = anchor;
+        return this;
+    }
     class(name) {
         if (this.edgeDef.className) {
             this.edgeDef.className += ` ${name}`;

package/dist/types.d.ts

@@ -20,6 +20,11 @@ export type NodeLabel = {
     dx?: number;
     dy?: number;
     className?: string;
+    fill?: string;
+    fontSize?: number | string;
+    fontWeight?: number | string;
+    textAnchor?: 'start' | 'middle' | 'end';
+    dominantBaseline?: string;
 };
 export type AnimationDuration = `${number}s`;
 export interface AnimationConfig {
@@ -36,6 +41,12 @@ export interface VizNode {
     pos: Vec2;
     shape: NodeShape;
     label?: NodeLabel;
+    style?: {
+        fill?: string;
+        stroke?: string;
+        strokeWidth?: number;
+        opacity?: number;
+    };
     className?: string;
     data?: unknown;
     onClick?: (id: string, node: VizNode) => void;
@@ -54,6 +65,7 @@ export interface VizEdge {
     to: string;
     label?: EdgeLabel;
     markerEnd?: 'arrow' | 'none';
+    anchor?: 'center' | 'boundary';
     className?: string;
     hitArea?: number;
     data?: unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vizcraft",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "A fluent, type-safe SVG scene builder for composing nodes, edges, animations, and overlays with incremental DOM updates and no framework dependency.",
   "keywords": [
     "visualization",
@@ -28,6 +28,11 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "devDependencies": {
     "typescript": "^5.9.3"
   },

package/.turbo/turbo-build.log

@@ -1,4 +0,0 @@
-
-> vizcraft@0.1.3 build /home/runner/work/vizcraft/vizcraft/packages/core
-> tsc
-

package/src/animations.ts

@@ -1,53 +0,0 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
-import type { VizNode, VizEdge, VizAnimSpec } from './types';
-
-export interface CoreAnimRendererContext<T = any> {
-  spec: VizAnimSpec<T>;
-  element: VizNode | VizEdge;
-}
-
-export interface CoreAnimRenderer<T = any> {
-  getClass?: (ctx: CoreAnimRendererContext<T>) => string;
-  getStyle?: (
-    ctx: CoreAnimRendererContext<T>
-  ) => Record<string, string | number>;
-}
-
-export class CoreAnimationRegistry {
-  private nodeAnims = new Map<string, CoreAnimRenderer>();
-  private edgeAnims = new Map<string, CoreAnimRenderer>();
-
-  constructor() {}
-
-  registerNode(id: string, renderer: CoreAnimRenderer) {
-    this.nodeAnims.set(id, renderer);
-    return this;
-  }
-
-  registerEdge(id: string, renderer: CoreAnimRenderer) {
-    this.edgeAnims.set(id, renderer);
-    return this;
-  }
-
-  getNodeRenderer(id: string): CoreAnimRenderer | undefined {
-    return this.nodeAnims.get(id);
-  }
-
-  getEdgeRenderer(id: string): CoreAnimRenderer | undefined {
-    return this.edgeAnims.get(id);
-  }
-}
-
-// Default Implementations
-export const coreFlowAnimation: CoreAnimRenderer<{ duration?: string }> = {
-  getClass: () => 'viz-anim-flow',
-  getStyle: ({ spec }) => {
-    const duration = spec.params?.duration ?? '2s';
-    return {
-      '--viz-anim-duration': duration,
-    };
-  },
-};
-
-export const defaultCoreAnimationRegistry =
-  new CoreAnimationRegistry().registerEdge('flow', coreFlowAnimation);