vizcraft 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './builder';
+export * from './styles';
+export * from './animations';
+export * from './overlays';

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './builder';
+export * from './styles';
+export * from './animations';
+export * from './overlays';

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,15 @@
+import { describe, it, expect } from 'vitest';
+import { viz } from './index';
+describe('vizcraft core', () => {
+    it('exports viz builder', () => {
+        expect(viz).toBeDefined();
+        expect(typeof viz).toBe('function');
+    });
+    it('creates a builder instance', () => {
+        const builder = viz();
+        expect(builder).toBeDefined();
+        // Verify default viewbox
+        const view = builder._getViewBox();
+        expect(view).toEqual({ w: 800, h: 600 });
+    });
+});

package/dist/overlays.d.ts

@@ -0,0 +1,38 @@
+import type { VizNode, VizEdge, VizOverlaySpec, VizScene } from './types';
+export interface CoreOverlayRenderContext<T = any> {
+    spec: VizOverlaySpec<T>;
+    nodesById: Map<string, VizNode>;
+    edgesById: Map<string, VizEdge>;
+    scene: VizScene;
+}
+export interface CoreOverlayRenderer<T = any> {
+    render: (ctx: CoreOverlayRenderContext<T>) => string;
+    update?: (ctx: CoreOverlayRenderContext<T>, container: SVGGElement) => void;
+}
+export declare class CoreOverlayRegistry {
+    private overlays;
+    register(id: string, renderer: CoreOverlayRenderer): this;
+    get(id: string): CoreOverlayRenderer<any> | undefined;
+}
+export declare const coreSignalOverlay: CoreOverlayRenderer<{
+    from: string;
+    to: string;
+    progress: number;
+    magnitude?: number;
+}>;
+export declare const coreGridLabelsOverlay: CoreOverlayRenderer<{
+    colLabels?: Record<number, string>;
+    rowLabels?: Record<number, string>;
+    yOffset?: number;
+    xOffset?: number;
+}>;
+interface DataPoint {
+    id: string;
+    currentNodeId: string;
+    [key: string]: any;
+}
+export declare const coreDataPointOverlay: CoreOverlayRenderer<{
+    points: DataPoint[];
+}>;
+export declare const defaultCoreOverlayRegistry: CoreOverlayRegistry;
+export {};

package/dist/overlays.js

@@ -0,0 +1,139 @@
+export class CoreOverlayRegistry {
+    overlays = new Map();
+    register(id, renderer) {
+        this.overlays.set(id, renderer);
+        return this;
+    }
+    get(id) {
+        return this.overlays.get(id);
+    }
+}
+// Built-in Overlay: Signal
+export const coreSignalOverlay = {
+    render: ({ spec, nodesById }) => {
+        const { from, to, progress } = spec.params;
+        const start = nodesById.get(from);
+        const end = nodesById.get(to);
+        if (!start || !end)
+            return '';
+        const x = start.pos.x + (end.pos.x - start.pos.x) * progress;
+        const y = start.pos.y + (end.pos.y - start.pos.y) * progress;
+        let v = Math.abs(spec.params.magnitude ?? 1);
+        if (v > 1)
+            v = 1;
+        const r = 2 + v * 4;
+        const className = spec.className ?? 'viz-signal';
+        return `
+            <g transform="translate(${x}, ${y})">
+                <g class="${className}">
+                    <circle r="10" fill="transparent" stroke="none" />
+                    <circle r="${r}" class="viz-signal-shape" />
+                </g>
+            </g>
+        `;
+    },
+};
+// Built-in Overlay: Grid Labels
+export const coreGridLabelsOverlay = {
+    render: ({ spec, scene }) => {
+        const grid = scene.grid;
+        if (!grid)
+            return '';
+        const { w, h } = scene.viewBox;
+        const { colLabels, rowLabels, yOffset = 20, xOffset = 20 } = spec.params;
+        // Safer string rendering for overlay to avoid weird spacing if grid missing
+        const cellW = (w - grid.padding.x * 2) / grid.cols;
+        const cellH = (h - grid.padding.y * 2) / grid.rows;
+        let output = '';
+        if (colLabels) {
+            Object.entries(colLabels).forEach(([colStr, text]) => {
+                const col = parseInt(colStr, 10);
+                const x = grid.padding.x + col * cellW + cellW / 2;
+                const cls = spec.className || 'viz-grid-label';
+                output += `<text x="${x}" y="${yOffset}" class="${cls}" text-anchor="middle">${text}</text>`;
+            });
+        }
+        if (rowLabels) {
+            Object.entries(rowLabels).forEach(([rowStr, text]) => {
+                const row = parseInt(rowStr, 10);
+                const y = grid.padding.y + row * cellH + cellH / 2;
+                const cls = spec.className || 'viz-grid-label';
+                output += `<text x="${xOffset}" y="${y}" dy=".35em" class="${cls}" text-anchor="middle">${text}</text>`;
+            });
+        }
+        return output;
+    },
+};
+// Built-in Overlay: Data Points
+export const coreDataPointOverlay = {
+    render: ({ spec, nodesById }) => {
+        const { points } = spec.params;
+        let output = '';
+        points.forEach((point) => {
+            const node = nodesById.get(point.currentNodeId);
+            if (!node)
+                return;
+            const idNum = parseInt(point.id.split('-')[1] || '0', 10);
+            const offsetX = ((idNum % 5) - 2) * 10;
+            const offsetY = ((idNum % 3) - 1) * 10;
+            const x = node.pos.x + offsetX;
+            const y = node.pos.y + offsetY;
+            const cls = spec.className ?? 'viz-data-point';
+            // Important: Add data-id so we can find it later in update()
+            output += `<circle data-id="${point.id}" cx="${x}" cy="${y}" r="6" class="${cls}" />`;
+        });
+        return output;
+    },
+    update: ({ spec, nodesById }, container) => {
+        const { points } = spec.params;
+        const svgNS = 'http://www.w3.org/2000/svg';
+        // 1. Map existing elements by data-id
+        const existingMap = new Map();
+        Array.from(container.children).forEach((child) => {
+            if (child.tagName === 'circle') {
+                const id = child.getAttribute('data-id');
+                if (id)
+                    existingMap.set(id, child);
+            }
+        });
+        const processedIds = new Set();
+        // 2. Create or Update Points
+        points.forEach((point) => {
+            const node = nodesById.get(point.currentNodeId);
+            if (!node)
+                return;
+            processedIds.add(point.id);
+            const idNum = parseInt(point.id.split('-')[1] || '0', 10);
+            const offsetX = ((idNum % 5) - 2) * 10;
+            const offsetY = ((idNum % 3) - 1) * 10;
+            const x = node.pos.x + offsetX;
+            const y = node.pos.y + offsetY;
+            let circle = existingMap.get(point.id);
+            if (!circle) {
+                // Create new
+                circle = document.createElementNS(svgNS, 'circle');
+                circle.setAttribute('data-id', point.id);
+                circle.setAttribute('r', '6');
+                container.appendChild(circle);
+            }
+            // Update attrs (this triggers CSS transition if class has it)
+            circle.setAttribute('cx', String(x));
+            circle.setAttribute('cy', String(y));
+            const cls = spec.className ?? 'viz-data-point';
+            // Only set class if different to avoid potential re-flows (though usually fine)
+            if (circle.getAttribute('class') !== cls) {
+                circle.setAttribute('class', cls);
+            }
+        });
+        // 3. Remove stale points
+        existingMap.forEach((el, id) => {
+            if (!processedIds.has(id)) {
+                el.remove();
+            }
+        });
+    },
+};
+export const defaultCoreOverlayRegistry = new CoreOverlayRegistry()
+    .register('signal', coreSignalOverlay)
+    .register('grid-labels', coreGridLabelsOverlay)
+    .register('data-points', coreDataPointOverlay);

package/dist/styles.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_VIZ_CSS = "\n.viz-canvas {\n  width: 100%;\n  height: 100%;\n  display: flex;\n  justify-content: center;\n  align-items: center;\n}\n\n.viz-canvas svg {\n  width: 100%;\n  height: 100%;\n  overflow: visible;\n}\n\n/* Keyframes */\n@keyframes vizFlow {\n  from {\n    stroke-dashoffset: 20;\n  }\n  to {\n    stroke-dashoffset: 0;\n  }\n}\n\n/* Animation Classes */\n\n/* Flow Animation (Dashed line moving) */\n.viz-anim-flow .viz-edge {\n  stroke-dasharray: 5, 5;\n  animation: vizFlow var(--viz-anim-duration, 2s) linear infinite;\n}\n\n/* Node Transition */\n.viz-node-group {\n    transition: transform 0.3s ease-out, opacity 0.3s ease-out;\n}\n\n/* Overlay Classes */\n.viz-grid-label {\n  fill: #6B7280;\n  font-size: 14px;\n  font-weight: 600;\n  opacity: 1;\n}\n\n.viz-signal {\n    fill: #3B82F6;\n    cursor: pointer;\n    pointer-events: all; \n    transition: transform 0.2s ease-out, fill 0.2s ease-out;\n}\n\n.viz-signal .viz-signal-shape {\n    fill: inherit;\n}\n\n.viz-signal:hover {\n    fill: #60A5FA;\n    transform: scale(1.5);\n}\n\n.viz-data-point {\n  fill: #F59E0B;\n  transition: cx 0.3s ease-out, cy 0.3s ease-out;\n}\n";

package/dist/styles.js

@@ -0,0 +1,67 @@
+export const DEFAULT_VIZ_CSS = `
+.viz-canvas {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}
+
+.viz-canvas svg {
+  width: 100%;
+  height: 100%;
+  overflow: visible;
+}
+
+/* Keyframes */
+@keyframes vizFlow {
+  from {
+    stroke-dashoffset: 20;
+  }
+  to {
+    stroke-dashoffset: 0;
+  }
+}
+
+/* Animation Classes */
+
+/* Flow Animation (Dashed line moving) */
+.viz-anim-flow .viz-edge {
+  stroke-dasharray: 5, 5;
+  animation: vizFlow var(--viz-anim-duration, 2s) linear infinite;
+}
+
+/* Node Transition */
+.viz-node-group {
+    transition: transform 0.3s ease-out, opacity 0.3s ease-out;
+}
+
+/* Overlay Classes */
+.viz-grid-label {
+  fill: #6B7280;
+  font-size: 14px;
+  font-weight: 600;
+  opacity: 1;
+}
+
+.viz-signal {
+    fill: #3B82F6;
+    cursor: pointer;
+    pointer-events: all; 
+    transition: transform 0.2s ease-out, fill 0.2s ease-out;
+}
+
+.viz-signal .viz-signal-shape {
+    fill: inherit;
+}
+
+.viz-signal:hover {
+    fill: #60A5FA;
+    transform: scale(1.5);
+}
+
+.viz-data-point {
+  fill: #F59E0B;
+  transition: cx 0.3s ease-out, cy 0.3s ease-out;
+}
+`;

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+export type Vec2 = {
+    x: number;
+    y: number;
+};
+export type NodeShape = {
+    kind: 'circle';
+    r: number;
+} | {
+    kind: 'rect';
+    w: number;
+    h: number;
+    rx?: number;
+} | {
+    kind: 'diamond';
+    w: number;
+    h: number;
+};
+export type NodeLabel = {
+    text: string;
+    dx?: number;
+    dy?: number;
+    className?: string;
+};
+export type AnimationDuration = `${number}s`;
+export interface AnimationConfig {
+    duration?: AnimationDuration;
+    [key: string]: any;
+}
+export interface VizAnimSpec<T = any> {
+    id: string;
+    params?: T;
+    when?: boolean;
+}
+export interface VizNode {
+    id: string;
+    pos: Vec2;
+    shape: NodeShape;
+    label?: NodeLabel;
+    className?: string;
+    data?: unknown;
+    onClick?: (id: string, node: VizNode) => void;
+    animations?: VizAnimSpec[];
+}
+export interface EdgeLabel {
+    text: string;
+    position: 'start' | 'mid' | 'end';
+    className?: string;
+    dx?: number;
+    dy?: number;
+}
+export interface VizEdge {
+    id: string;
+    from: string;
+    to: string;
+    label?: EdgeLabel;
+    markerEnd?: 'arrow' | 'none';
+    className?: string;
+    hitArea?: number;
+    data?: unknown;
+    onClick?: (id: string, edge: VizEdge) => void;
+    animations?: VizAnimSpec[];
+}
+export type VizOverlaySpec<T = any> = {
+    id: string;
+    key?: string;
+    params: T;
+    className?: string;
+};
+export interface VizGridConfig {
+    cols: number;
+    rows: number;
+    padding: {
+        x: number;
+        y: number;
+    };
+}
+export type VizScene = {
+    viewBox: {
+        w: number;
+        h: number;
+    };
+    grid?: VizGridConfig;
+    nodes: VizNode[];
+    edges: VizEdge[];
+    overlays?: VizOverlaySpec[];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "vizcraft",
+  "version": "0.1.1",
+  "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",
+    "svg",
+    "graph",
+    "diagram",
+    "animation",
+    "react",
+    "typescript"
+  ],
+  "author": {
+    "name": "Chipili Kafwilo",
+    "email": "ckafwilo@gmail.com",
+    "url": "https://chipilidev.com"
+  },
+  "homepage": "https://github.com/ChipiKaf/vizcraft#readme",
+  "bugs": {
+    "url": "https://github.com/ChipiKaf/vizcraft/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ChipiKaf/vizcraft.git"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint 'src/**/*.{ts,tsx}'",
+    "test": "vitest run"
+  }
+}

package/src/animations.ts

@@ -0,0 +1,53 @@
+/* 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);