vizcraft 0.1.4 → 0.1.5

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # 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

package/README.md

@@ -27,12 +27,10 @@ yarn add vizcraft
 You can use the core library directly to generate SVG content or mount to a DOM element.
 
 ```typescript
-import { VizBuilderImpl } from 'vizcraft';
+import { viz } from 'vizcraft';
 
-// Create a builder instance
-const builder = new VizBuilderImpl();
+const builder = viz().view(800, 600);
 
-// Define your scene
 builder
   .view(500, 500)
   .node('a')
@@ -46,12 +44,8 @@ builder
   .edge('a', 'b')
   .arrow();
 
-// Build the scene model
-const scene = builder.build();
-
-// Mount to a container
-const container = document.getElementById('viz');
-builder.mount(container);
+const container = document.getElementById('viz-basic');
+if (container) builder.mount(container);
 ```
 
 ## 📖 Core Concepts

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.4",
+  "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",