vizcraft 0.2.2 → 1.0.0

package/dist/styles.d.ts

@@ -1 +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-node-label,\n.viz-edge-label {\n  text-anchor: middle;\n  dominant-baseline: middle;\n  alignment-baseline: middle;\n  transform: translateY(0);\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";
+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-node-label,\n.viz-edge-label {\n  text-anchor: middle;\n  dominant-baseline: middle;\n  alignment-baseline: middle;\n  transform: translateY(0);\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/* Edge base styling (path elements need explicit fill:none) */\n.viz-edge {\n  fill: none;\n  stroke: currentColor;\n}\n\n.viz-edge-hit {\n  fill: none;\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\n/* Connection ports (hidden by default, shown on node hover) */\n.viz-port {\n  fill: #3B82F6;\n  stroke: white;\n  stroke-width: 1.5;\n  opacity: 0;\n  pointer-events: all;\n  cursor: crosshair;\n  transition: opacity 0.15s ease-out;\n}\n.viz-node-group:hover .viz-port {\n  opacity: 1;\n}\n";

package/dist/styles.js

@@ -39,6 +39,16 @@ export const DEFAULT_VIZ_CSS = `
   animation: vizFlow var(--viz-anim-duration, 2s) linear infinite;
 }
 
+/* Edge base styling (path elements need explicit fill:none) */
+.viz-edge {
+  fill: none;
+  stroke: currentColor;
+}
+
+.viz-edge-hit {
+  fill: none;
+}
+
 /* Node Transition */
 .viz-node-group {
     transition: transform 0.3s ease-out, opacity 0.3s ease-out;
@@ -72,4 +82,18 @@ export const DEFAULT_VIZ_CSS = `
   fill: #F59E0B;
   transition: cx 0.3s ease-out, cy 0.3s ease-out;
 }
+
+/* Connection ports (hidden by default, shown on node hover) */
+.viz-port {
+  fill: #3B82F6;
+  stroke: white;
+  stroke-width: 1.5;
+  opacity: 0;
+  pointer-events: all;
+  cursor: crosshair;
+  transition: opacity 0.15s ease-out;
+}
+.viz-node-group:hover .viz-port {
+  opacity: 1;
+}
 `;

package/dist/types.d.ts

@@ -15,6 +15,89 @@ export type NodeShape = {
     kind: 'diamond';
     w: number;
     h: number;
+} | {
+    kind: 'cylinder';
+    w: number;
+    h: number;
+    arcHeight?: number;
+} | {
+    kind: 'hexagon';
+    r: number;
+    orientation?: 'pointy' | 'flat';
+} | {
+    kind: 'ellipse';
+    rx: number;
+    ry: number;
+} | {
+    kind: 'arc';
+    r: number;
+    startAngle: number;
+    endAngle: number;
+    closed?: boolean;
+} | {
+    kind: 'blockArrow';
+    length: number;
+    bodyWidth: number;
+    headWidth: number;
+    headLength: number;
+    direction?: 'right' | 'left' | 'up' | 'down';
+} | {
+    kind: 'callout';
+    w: number;
+    h: number;
+    rx?: number;
+    pointerSide?: 'bottom' | 'top' | 'left' | 'right';
+    pointerHeight?: number;
+    pointerWidth?: number;
+    pointerPosition?: number;
+} | {
+    kind: 'cloud';
+    w: number;
+    h: number;
+} | {
+    kind: 'cross';
+    size: number;
+    barWidth?: number;
+} | {
+    kind: 'cube';
+    w: number;
+    h: number;
+    depth?: number;
+} | {
+    kind: 'path';
+    d: string;
+    w: number;
+    h: number;
+} | {
+    kind: 'document';
+    w: number;
+    h: number;
+    waveHeight?: number;
+} | {
+    kind: 'note';
+    w: number;
+    h: number;
+    foldSize?: number;
+} | {
+    kind: 'parallelogram';
+    w: number;
+    h: number;
+    skew?: number;
+} | {
+    kind: 'star';
+    points: number;
+    outerR: number;
+    innerR?: number;
+} | {
+    kind: 'trapezoid';
+    topW: number;
+    bottomW: number;
+    h: number;
+} | {
+    kind: 'triangle';
+    w: number;
+    h: number;
+    direction?: 'up' | 'down' | 'left' | 'right';
 };
 export type NodeLabel = {
     text: string;
@@ -48,6 +131,48 @@ export type VizRuntimeEdgeProps = Partial<{
     strokeDashoffset: number;
     opacity: number;
 }>;
+export interface ContainerConfig {
+    /** Layout direction for children (default 'free') */
+    layout?: 'free' | 'vertical' | 'horizontal';
+    /** Padding inside the container */
+    padding?: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    /** Whether the container auto-resizes to fit children */
+    autoSize?: boolean;
+    /** Header height for swimlane-style headers */
+    headerHeight?: number;
+}
+/**
+ * A named connection port (anchor point) on a node.
+ *
+ * Ports let edges connect to specific positions on a shape rather than
+ * the generic boundary intersection.
+ */
+export interface NodePort {
+    /** Unique port id within the node (e.g. `'top'`, `'left'`, `'out-1'`). */
+    id: string;
+    /**
+     * Position **relative to the node center** (absolute pixel offset).
+     *
+     * For example, on a 120×60 rect centered at the node's `pos`:
+     * - top port: `{ x: 0, y: -30 }`
+     * - right port: `{ x: 60, y: 0 }`
+     */
+    offset: Vec2;
+    /**
+     * Optional direction hint for edge routing (outgoing tangent angle in **degrees**).
+     *
+     * - `0` = right
+     * - `90` = down
+     * - `180` = left
+     * - `270` = up
+     */
+    direction?: number;
+}
 export interface VizNode {
     id: string;
     pos: Vec2;
@@ -64,6 +189,21 @@ export interface VizNode {
     data?: unknown;
     onClick?: (id: string, node: VizNode) => void;
     animations?: VizAnimSpec[];
+    /**
+     * Named connection ports on this node.
+     *
+     * When an edge references a port via `fromPort` / `toPort`, the endpoint
+     * is resolved to `node.pos + port.offset` instead of the generic
+     * boundary intersection.
+     *
+     * If omitted, default ports for the node's shape are available automatically
+     * (see `getDefaultPorts`). Explicit ports override defaults entirely.
+     */
+    ports?: NodePort[];
+    /** If set, this node is a child of the node with this id. */
+    parentId?: string;
+    /** Container-specific configuration (only on parent nodes). */
+    container?: ContainerConfig;
 }
 export interface EdgeLabel {
     text: string;
@@ -72,20 +212,86 @@ export interface EdgeLabel {
     dx?: number;
     dy?: number;
 }
+/** Edge routing algorithm. */
+export type EdgeRouting = 'straight' | 'curved' | 'orthogonal';
+/**
+ * Edge marker/arrowhead types.
+ *
+ * - `'none'`: No marker
+ * - `'arrow'`: Filled triangle (default arrowhead)
+ * - `'arrowOpen'`: Open/unfilled triangle (V shape)
+ * - `'diamond'`: Filled diamond (UML composition)
+ * - `'diamondOpen'`: Open diamond (UML aggregation)
+ * - `'circle'`: Filled circle
+ * - `'circleOpen'`: Open circle
+ * - `'square'`: Filled square
+ * - `'bar'`: Perpendicular line (T shape, for cardinality)
+ * - `'halfArrow'`: Single-sided arrow (one wing)
+ */
+export type EdgeMarkerType = 'none' | 'arrow' | 'arrowOpen' | 'diamond' | 'diamondOpen' | 'circle' | 'circleOpen' | 'square' | 'bar' | 'halfArrow';
 export interface VizEdge {
     id: string;
     from: string;
     to: string;
+    /** @deprecated Use `labels` for multi-position support. Kept for backwards compatibility. */
     label?: EdgeLabel;
+    /** Multiple labels at different positions along the edge. */
+    labels?: EdgeLabel[];
     runtime?: VizRuntimeEdgeProps;
-    markerEnd?: 'arrow' | 'none';
+    /** Marker at the target (end) of the edge. */
+    markerEnd?: EdgeMarkerType;
+    /** Marker at the source (start) of the edge. */
+    markerStart?: EdgeMarkerType;
+    /** Port id on the source node. When set, the edge starts at the port's position instead of the boundary. */
+    fromPort?: string;
+    /** Port id on the target node. When set, the edge ends at the port's position instead of the boundary. */
+    toPort?: string;
     anchor?: 'center' | 'boundary';
+    /** Per-edge visual styling. Overrides the CSS defaults when set. */
+    style?: {
+        stroke?: string;
+        strokeWidth?: number;
+        fill?: string;
+        opacity?: number;
+    };
     className?: string;
     hitArea?: number;
     data?: unknown;
     onClick?: (id: string, edge: VizEdge) => void;
     animations?: VizAnimSpec[];
+    /** Routing algorithm for the edge path (default: 'straight'). */
+    routing?: EdgeRouting;
+    /** User-defined intermediate waypoints the edge must pass through. */
+    waypoints?: Vec2[];
+}
+/**
+ * Overlay kind -> params mapping.
+ *
+ * This interface is intentionally empty in core and is meant to be augmented by:
+ * - core overlays (in this repo)
+ * - downstream libraries/apps (via TS module augmentation)
+ */
+export interface OverlayKindRegistry {
 }
+/** Internal runtime flag used to mark overlays as needing a DOM update. */
+export declare const OVERLAY_RUNTIME_DIRTY: unique symbol;
+/** String overlay ids that are known/typed via `OverlayKindRegistry`. */
+export type KnownOverlayId = Extract<keyof OverlayKindRegistry, string>;
+/** Any overlay id (typed known ids + arbitrary custom ids). */
+export type OverlayId = KnownOverlayId | (string & {});
+/**
+ * Params type for a given overlay id.
+ * - Known ids resolve to their registered params type.
+ * - Unknown/custom ids fall back to `unknown` (escape hatch).
+ */
+export type OverlayParams<K extends string> = K extends KnownOverlayId ? OverlayKindRegistry[K] : unknown;
+/** A type-safe overlay spec keyed by overlay id. */
+export type TypedVizOverlaySpec<K extends OverlayId = OverlayId> = {
+    id: K;
+    key?: string;
+    params: OverlayParams<K>;
+    className?: string;
+};
 export type VizOverlaySpec<T = any> = {
     id: string;
     key?: string;

package/dist/types.js

@@ -1 +1,2 @@
-export {};
+/** Internal runtime flag used to mark overlays as needing a DOM update. */
+export const OVERLAY_RUNTIME_DIRTY = Symbol('vizcraft.overlay.runtimeDirty');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vizcraft",
-  "version": "0.2.2",
+  "version": "1.0.0",
   "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",

package/dist/anim/player.test.d.ts

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

package/dist/anim/player.test.js

@@ -1,49 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { createPlayer } from './player';
-describe('anim/player', () => {
-    it('chains sequential tweens on the same property', () => {
-        const state = new Map([['node:a|x', 120]]);
-        const adapter = {
-            get(target, prop) {
-                return state.get(`${target}|${prop}`);
-            },
-            set(target, prop, value) {
-                state.set(`${target}|${prop}`, value);
-            },
-            flush() {
-                // no-op
-            },
-        };
-        const spec = {
-            version: 'viz-anim/1',
-            tweens: [
-                {
-                    kind: 'tween',
-                    target: 'node:a',
-                    property: 'x',
-                    to: 320,
-                    duration: 1200,
-                    delay: 0,
-                    easing: 'linear',
-                },
-                {
-                    kind: 'tween',
-                    target: 'node:a',
-                    property: 'x',
-                    to: 120,
-                    duration: 1200,
-                    delay: 1800,
-                    easing: 'linear',
-                },
-            ],
-        };
-        const player = createPlayer(adapter);
-        player.load(spec);
-        player.seek(600);
-        // Halfway from 120 -> 320
-        expect(state.get('node:a|x')).toBeCloseTo(220, 5);
-        player.seek(2400);
-        // Halfway from 320 -> 120 (1200ms into the second tween)
-        expect(state.get('node:a|x')).toBeCloseTo(220, 5);
-    });
-});

package/dist/index.test.d.ts

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

package/dist/index.test.js

@@ -1,66 +0,0 @@
-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 });
-    });
-    it('supports data-only builder.animate(cb) and stores specs on the scene', () => {
-        const builder = viz();
-        builder.node('a').at(0, 0);
-        builder.node('b').at(10, 10);
-        builder.edge('a', 'b');
-        const spec = builder.animate((anim) => anim.node('a').to({ x: 200, opacity: 0.5 }, { duration: 600 }));
-        expect(spec.version).toBe('viz-anim/1');
-        expect(spec.tweens.length).toBe(2);
-        expect(spec.tweens[0]).toBeDefined();
-        expect(spec.tweens[0].target).toBe('node:a');
-        const scene = builder.build();
-        expect(scene.animationSpecs?.length).toBe(1);
-        expect(scene.animationSpecs?.[0]).toEqual(spec);
-    });
-    it('keeps legacy .animate("flow") behavior separate from data-only specs', () => {
-        const builder = viz();
-        builder.node('a').at(0, 0);
-        builder.node('b').at(10, 10);
-        builder.edge('a', 'b').animate('flow', { duration: '1s' });
-        const scene = builder.build();
-        expect(scene.animationSpecs).toBeUndefined();
-        expect(scene.edges[0]).toBeDefined();
-        expect(scene.edges[0].animations?.[0]?.id).toBe('flow');
-    });
-    it('supports element-level .animate(cb) and animateTo(...) sugar', () => {
-        const builder = viz();
-        builder.node('a').at(0, 0).animateTo({ x: 123 }, { duration: 400 });
-        builder.node('b').at(10, 10);
-        builder
-            .edge('a', 'b')
-            .animate((anim) => anim.to({ strokeDashoffset: -100 }, { duration: 1000 }));
-        const scene = builder.build();
-        expect(scene.animationSpecs?.length).toBe(2);
-        const nodeSpec = scene.animationSpecs?.[0];
-        const edgeSpec = scene.animationSpecs?.[1];
-        expect(nodeSpec).toBeDefined();
-        expect(edgeSpec).toBeDefined();
-        expect(nodeSpec.tweens[0]).toBeDefined();
-        expect(edgeSpec.tweens[0]).toBeDefined();
-        expect(nodeSpec.tweens[0].target).toBe('node:a');
-        expect(edgeSpec.tweens[0].target).toBe('edge:a->b');
-    });
-    it('allows animating edges with custom ids via anim.edge(from, to, id)', () => {
-        const builder = viz();
-        builder.node('a').at(0, 0);
-        builder.node('b').at(10, 10);
-        builder.edge('a', 'b', 'e1');
-        const spec = builder.animate((anim) => anim.edge('a', 'b', 'e1').to({ strokeDashoffset: -50 }, { duration: 250 }));
-        expect(spec.tweens.length).toBe(1);
-        expect(spec.tweens[0].target).toBe('edge:e1');
-    });
-});