vizcraft 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # vizcraft
 
+## 0.2.0
+
+### Minor Changes
+
+- [`c3984f2`](https://github.com/ChipiKaf/vizcraft/commit/c3984f200af3a3388b3a52f38fb068c8bc955ba1) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - Implemented the animation builder api
+
 ## 0.1.5
 
 ### Patch Changes

package/README.md

@@ -8,7 +8,7 @@ VizCraft is designed to make creating beautiful, animated node-link diagrams and
 
 - **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.
+- **Two Animation Systems**: Lightweight registry/CSS animations (e.g. edge `flow`) and data-only timeline animations (`AnimationSpec`).
 - **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.
 
@@ -48,6 +48,25 @@ const container = document.getElementById('viz-basic');
 if (container) builder.mount(container);
 ```
 
+## 📚 Documentation (Topics)
+
+For a guided walkthrough, the repo docs are organized like this:
+
+- [Introduction](../../packages/docs/docs/intro.md)
+- [Examples](../../packages/docs/docs/examples.mdx)
+- [Essentials](../../packages/docs/docs/essentials.mdx)
+- [Animations](../../packages/docs/docs/animations/index.mdx)
+  - [Animation Builder API](../../packages/docs/docs/animations/animation-builder-api.mdx)
+- [Advanced](../../packages/docs/docs/advanced.mdx)
+- [Types](../../packages/docs/docs/types.mdx)
+
+Run the docs locally (monorepo):
+
+```bash
+pnpm install
+pnpm -C packages/docs start
+```
+
 ## 📖 Core Concepts
 
 ### The Builder (`VizBuilder`)
@@ -90,11 +109,128 @@ b.edge('n1', 'n2')
 
 ### Animations
 
-VizCraft supports declarative animations. You define _what_ happens, and the renderer handles the interpolation.
+VizCraft supports **two complementary animation approaches**:
+
+1. **Registry/CSS animations** (simple, reusable effects)
+
+Attach an animation by name to a node/edge. The default core registry includes:
+
+- `flow` (edge)
+
+```ts
+import { viz } from 'vizcraft';
+
+const b = viz().view(520, 160);
+
+b.node('a')
+  .at(70, 80)
+  .circle(18)
+  .label('A')
+  .node('b')
+  .at(450, 80)
+  .rect(70, 44, 10)
+  .label('B')
+  .edge('a', 'b')
+  .arrow()
+  .animate('flow', { duration: '1s' })
+  .done();
+```
+
+2. **Data-only timeline animations (`AnimationSpec`)** (sequenced tweens)
+
+- Author with `builder.animate((anim) => ...)`.
+- VizCraft stores compiled specs on the scene as `scene.animationSpecs`.
+- Play them with `builder.play()`.
+
+```ts
+import { viz } from 'vizcraft';
+
+const b = viz().view(520, 240);
+
+b.node('a')
+  .at(120, 120)
+  .circle(20)
+  .label('A')
+  .node('b')
+  .at(400, 120)
+  .rect(70, 44, 10)
+  .label('B')
+  .edge('a', 'b')
+  .arrow()
+  .done();
+
+b.animate((anim) =>
+  anim
+    .node('a')
+    .to({ x: 200, opacity: 0.35 }, { duration: 600 })
+    .node('b')
+    .to({ x: 440, y: 170 }, { duration: 700 })
+    .edge('a->b')
+    .to({ strokeDashoffset: -120 }, { duration: 900 })
+);
+
+const container = document.getElementById('viz-basic');
+if (container) {
+  b.mount(container);
+  b.play();
+}
+```
+
+#### Animating edges with custom ids
+
+If you create an edge with a custom id (third arg), target it explicitly in animations:
+
+```ts
+const b = viz().view(520, 240);
+b.node('a')
+  .at(120, 120)
+  .circle(20)
+  .node('b')
+  .at(400, 120)
+  .rect(70, 44, 10)
+  .edge('a', 'b', 'e1')
+  .done();
+
+b.animate((anim) =>
+  anim.edge('a', 'b', 'e1').to({ strokeDashoffset: -120 }, { duration: 900 })
+);
+```
+
+#### Custom animatable properties (advanced)
+
+Specs can carry adapter extensions so you can animate your own numeric properties:
+
+```ts
+b.animate((anim) =>
+  anim
+    .extendAdapter((adapter) => {
+      adapter.register?.('node', 'r', {
+        get: (target) => adapter.get(target, 'r'),
+        set: (target, v) => adapter.set(target, 'r', v),
+      });
+    })
+    .node('a')
+    .to({ r: 42 }, { duration: 500 })
+);
+```
+
+### Playback controls
+
+`builder.play()` returns a controller with `pause()`, `play()` (resume), and `stop()`.
+
+```ts
+const controller = b.play();
+controller?.pause();
+controller?.play();
+controller?.stop();
+```
+
+### Supported properties (core adapter)
+
+Out of the box, timeline playback supports these numeric properties:
 
-- **`stream`**: Particles flowing along an edge.
-- **`pulse`**: Rhythmic scaling or opacity changes.
-- **Transition**: Moving a node from one position to another.
+- Node: `x`, `y`, `opacity`, `scale`, `rotation`
+- Edge: `opacity`, `strokeDashoffset`
 
 ## 🎨 Styling
 
@@ -130,4 +266,4 @@ Contributions are welcome! This is a monorepo managed with Turbo.
 
 ## 📄 License
 
-MIT License © Chipili Kafwilo
+MIT License

package/dist/anim/adapter.d.ts

@@ -0,0 +1,15 @@
+import type { AnimationTarget, AnimProperty } from './spec';
+export type PropReader = (el: unknown) => number | undefined;
+export type PropWriter = (el: unknown, value: number) => void;
+export interface PropHandlers {
+    get?: PropReader;
+    set?: PropWriter;
+}
+export interface AnimationHostAdapter {
+    get(target: AnimationTarget, prop: AnimProperty): number | undefined;
+    set(target: AnimationTarget, prop: AnimProperty, value: number): void;
+    flush?: () => void;
+}
+export interface RegistrableAdapter {
+    register(kind: string, prop: string, handlers: PropHandlers): void;
+}

package/dist/anim/adapter.js

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

package/dist/anim/animationBuilder.d.ts

@@ -0,0 +1,67 @@
+import type { AnimationSpec, AnimProperty, CoreAnimProperty, Ease } from './spec';
+import type { ExtendAdapter } from './extendAdapter';
+export type TweenOptions = {
+    duration: number;
+    easing?: Ease;
+    /** Optional per-property starting values. If omitted, the player captures from runtime/base. */
+    from?: Partial<Record<AnimProperty, number>>;
+};
+/**
+ * Properties that VizCraft core knows how to animate by default.
+ *
+ * Note: `AnimationSpec` supports arbitrary string properties, but core adapters
+ * only register these by default.
+ */
+export type CoreAnimatableProps = Partial<Record<CoreAnimProperty, number>>;
+/**
+ * A loose prop bag that still hints core properties in TS.
+ *
+ * Example: `{ x: 10, opacity: 0.5 }`.
+ */
+export type AnimatableProps = CoreAnimatableProps & Partial<Record<string, number>>;
+/**
+ * Fluent, authoring API that compiles to a portable `AnimationSpec`.
+ *
+ * - Data only: no callbacks stored as animation state.
+ * - Sequential by default via an internal cursor time.
+ */
+export declare class AnimationBuilder {
+    private cursorMs;
+    private currentTarget;
+    private readonly tweens;
+    private readonly adapterExtensions;
+    /**
+     * Register custom animated properties for this spec.
+     *
+     * This avoids needing to thread an `extendAdapter` callback into playback helpers.
+     */
+    extendAdapter(cb: ExtendAdapter): this;
+    /** Select a node by id (compiles to target `node:<id>`). */
+    node(id: string): this;
+    /**
+     * Select an edge.
+     *
+     * - `edge('a->b')` (id form)
+     * - `edge('a', 'b')` (convenience; compiles to `edge:a->b`)
+     * - `edge('a', 'b', 'custom-id')` (explicit id; compiles to `edge:custom-id`)
+     */
+    edge(id: string): this;
+    edge(from: string, to: string, id?: string): this;
+    /**
+     * Set the internal cursor time (ms). Next `.to(...)` uses this as its delay.
+     */
+    at(ms: number): this;
+    /**
+     * Advance the internal cursor time (ms) without adding tweens.
+     */
+    wait(ms: number): this;
+    /**
+     * Tween properties on the current target.
+     *
+     * Emits one `TweenSpec` per property.
+     */
+    to(props: AnimatableProps, opts: TweenOptions): this;
+    build(): AnimationSpec;
+}
+/** Convenience helper for one-off compilation. */
+export declare function buildAnimationSpec(cb: (anim: AnimationBuilder) => unknown): AnimationSpec;

package/dist/anim/animationBuilder.js

@@ -0,0 +1,101 @@
+import { ADAPTER_EXTENSIONS, } from './specExtensions';
+function isNumber(v) {
+    return typeof v === 'number' && Number.isFinite(v);
+}
+function toTarget(kind, id) {
+    return `${kind}:${id}`;
+}
+/**
+ * Fluent, authoring API that compiles to a portable `AnimationSpec`.
+ *
+ * - Data only: no callbacks stored as animation state.
+ * - Sequential by default via an internal cursor time.
+ */
+export class AnimationBuilder {
+    cursorMs = 0;
+    currentTarget = null;
+    tweens = [];
+    adapterExtensions = [];
+    /**
+     * Register custom animated properties for this spec.
+     *
+     * This avoids needing to thread an `extendAdapter` callback into playback helpers.
+     */
+    extendAdapter(cb) {
+        this.adapterExtensions.push(cb);
+        return this;
+    }
+    /** Select a node by id (compiles to target `node:<id>`). */
+    node(id) {
+        this.currentTarget = toTarget('node', id);
+        return this;
+    }
+    edge(a, b, c) {
+        const id = b === undefined ? a : (c ?? `${a}->${b}`);
+        this.currentTarget = toTarget('edge', id);
+        return this;
+    }
+    /**
+     * Set the internal cursor time (ms). Next `.to(...)` uses this as its delay.
+     */
+    at(ms) {
+        this.cursorMs = Math.max(0, ms);
+        return this;
+    }
+    /**
+     * Advance the internal cursor time (ms) without adding tweens.
+     */
+    wait(ms) {
+        this.cursorMs = Math.max(0, this.cursorMs + Math.max(0, ms));
+        return this;
+    }
+    /**
+     * Tween properties on the current target.
+     *
+     * Emits one `TweenSpec` per property.
+     */
+    to(props, opts) {
+        if (!this.currentTarget) {
+            throw new Error('AnimationBuilder.to(): no target selected (call node(...) or edge(...))');
+        }
+        const duration = Math.max(0, opts.duration);
+        const easing = opts.easing;
+        const froms = opts.from;
+        for (const [property, value] of Object.entries(props)) {
+            if (!isNumber(value))
+                continue;
+            const tween = {
+                kind: 'tween',
+                target: this.currentTarget,
+                property: property,
+                to: value,
+                duration,
+                delay: this.cursorMs,
+                easing,
+            };
+            const from = froms?.[property];
+            if (isNumber(from))
+                tween.from = from;
+            this.tweens.push(tween);
+        }
+        // Sequential by default.
+        this.cursorMs += duration;
+        return this;
+    }
+    build() {
+        const spec = {
+            version: 'viz-anim/1',
+            tweens: [...this.tweens],
+        };
+        if (this.adapterExtensions.length > 0) {
+            spec[ADAPTER_EXTENSIONS] = [...this.adapterExtensions];
+        }
+        return spec;
+    }
+}
+/** Convenience helper for one-off compilation. */
+export function buildAnimationSpec(cb) {
+    const anim = new AnimationBuilder();
+    cb(anim);
+    return anim.build();
+}

package/dist/anim/extendAdapter.d.ts

@@ -0,0 +1,2 @@
+import type { AnimationHostAdapter, RegistrableAdapter } from './adapter';
+export type ExtendAdapter = (adapter: AnimationHostAdapter & Partial<RegistrableAdapter>) => void;

package/dist/anim/extendAdapter.js

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

package/dist/anim/playback.d.ts

@@ -0,0 +1,47 @@
+import type { VizScene } from '../types';
+import { type AnimationController } from './player';
+import type { AnimationSpec } from './spec';
+import type { ExtendAdapter } from './extendAdapter';
+/**
+ * A player that can be (re)loaded with specs.
+ *
+ * Note: `createPlayer()` returns a controller that also has `.load(...)`, but the
+ * exported `AnimationController` interface does not include it.
+ */
+export type PlaybackController = AnimationController & {
+    load(spec: AnimationSpec): AnimationController;
+};
+export type { ExtendAdapter };
+export declare function createScenePlayback(opts: {
+    scene: VizScene;
+    requestRender: () => void;
+    extendAdapter?: ExtendAdapter;
+}): PlaybackController;
+/**
+ * Convenience helper for the common "builder + mounted container" case.
+ *
+ * - Uses `builder.build()` once to get stable node/edge references for runtime updates.
+ * - Uses `builder.patchRuntime(container)` as the render flush, so animations patch
+ *   the existing SVG in-place (fast path).
+ */
+export declare function createBuilderPlayback(opts: {
+    builder: {
+        build(): VizScene;
+        patchRuntime(container: HTMLElement): void;
+    };
+    container: HTMLElement;
+    extendAdapter?: ExtendAdapter;
+}): PlaybackController;
+/**
+ * Loads (and optionally auto-plays) a spec against a mounted builder.
+ */
+export declare function playAnimationSpec(opts: {
+    builder: {
+        build(): VizScene;
+        patchRuntime(container: HTMLElement): void;
+    };
+    container: HTMLElement;
+    spec: AnimationSpec;
+    autoPlay?: boolean;
+    extendAdapter?: ExtendAdapter;
+}): PlaybackController;

package/dist/anim/playback.js

@@ -0,0 +1,46 @@
+import { createPlayer } from './player';
+import { createVizCraftAdapter } from './vizcraftAdapter';
+import { getAdapterExtensions } from './specExtensions';
+export function createScenePlayback(opts) {
+    const adapter = createVizCraftAdapter(opts.scene, opts.requestRender);
+    opts.extendAdapter?.(adapter);
+    return createPlayer(adapter);
+}
+/**
+ * Convenience helper for the common "builder + mounted container" case.
+ *
+ * - Uses `builder.build()` once to get stable node/edge references for runtime updates.
+ * - Uses `builder.patchRuntime(container)` as the render flush, so animations patch
+ *   the existing SVG in-place (fast path).
+ */
+export function createBuilderPlayback(opts) {
+    const scene = opts.builder.build();
+    const requestRender = () => opts.builder.patchRuntime(opts.container);
+    return createScenePlayback({
+        scene,
+        requestRender,
+        extendAdapter: opts.extendAdapter,
+    });
+}
+/**
+ * Loads (and optionally auto-plays) a spec against a mounted builder.
+ */
+export function playAnimationSpec(opts) {
+    const adapterExtensions = getAdapterExtensions(opts.spec);
+    const extendAdapter = adapterExtensions.length > 0 || opts.extendAdapter
+        ? (adapter) => {
+            for (const ext of adapterExtensions)
+                ext(adapter);
+            opts.extendAdapter?.(adapter);
+        }
+        : undefined;
+    const controller = createBuilderPlayback({
+        builder: opts.builder,
+        container: opts.container,
+        extendAdapter,
+    });
+    controller.load(opts.spec);
+    if (opts.autoPlay !== false)
+        controller.play();
+    return controller;
+}

package/dist/anim/player.d.ts

@@ -0,0 +1,14 @@
+import type { AnimationHostAdapter } from './adapter';
+import type { AnimationSpec } from './spec';
+export interface AnimationController {
+    play(): void;
+    pause(): void;
+    seek(ms: number): void;
+    stop(): void;
+    isPlaying(): boolean;
+    time(): number;
+    duration(): number;
+}
+export declare function createPlayer(adapter: AnimationHostAdapter): AnimationController & {
+    load(spec: AnimationSpec): AnimationController;
+};

package/dist/anim/player.js

@@ -0,0 +1,204 @@
+function clamp(v, a = 0, b = 1) {
+    return Math.max(a, Math.min(b, v));
+}
+const easingFns = {
+    linear: (t) => t,
+    easeIn: (t) => t * t,
+    easeOut: (t) => 1 - (1 - t) * (1 - t),
+    easeInOut: (t) => (t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2),
+};
+export function createPlayer(adapter) {
+    let spec = null;
+    let tracks = [];
+    let total = 0;
+    let timeMs = 0;
+    let playing = false;
+    let rafId = null;
+    let lastFrameTime = 0;
+    let captured = false;
+    function buildInternal(s) {
+        const list = s.tweens.map((t, i) => {
+            const start = t.delay ?? 0;
+            const end = start + t.duration;
+            return Object.assign({}, t, { start, end, _from: t.from ?? 0, _i: i });
+        });
+        const byKey = new Map();
+        for (const t of list) {
+            const key = `${String(t.target)}|${String(t.property)}`;
+            let track = byKey.get(key);
+            if (!track) {
+                track = {
+                    key,
+                    target: t.target,
+                    property: t.property,
+                    base: 0,
+                    tweens: [],
+                };
+                byKey.set(key, track);
+            }
+            track.tweens.push(t);
+        }
+        const trackList = Array.from(byKey.values());
+        for (const tr of trackList) {
+            tr.tweens.sort((a, b) => a.start !== b.start ? a.start - b.start : a._i - b._i);
+        }
+        const dur = list.reduce((mx, t) => Math.max(mx, t.end), 0);
+        return {
+            tracks: trackList,
+            dur,
+        };
+    }
+    function captureFromsIfNeeded() {
+        if (captured || !spec)
+            return;
+        // Capture base values once per track and chain sequential tweens.
+        for (const tr of tracks) {
+            const got = adapter.get(tr.target, tr.property);
+            tr.base = typeof got === 'number' ? got : 0;
+            let prior = null;
+            for (const t of tr.tweens) {
+                if (t.from !== undefined) {
+                    t._from = t.from;
+                }
+                else if (prior && prior.end <= t.start) {
+                    // Common case: sequential tweens on the same prop should chain.
+                    t._from = prior.to;
+                }
+                else {
+                    // Fallback: capture from the base value.
+                    t._from = tr.base;
+                }
+                prior = t;
+            }
+        }
+        captured = true;
+    }
+    function applyAt(ms) {
+        // Evaluate one active tween per target+property.
+        // This avoids "future" tweens overwriting current motion.
+        for (const tr of tracks) {
+            const list = tr.tweens;
+            // Find the last tween that has started.
+            let lo = 0;
+            let hi = list.length - 1;
+            let idx = -1;
+            while (lo <= hi) {
+                const mid = (lo + hi) >> 1;
+                if (list[mid].start <= ms) {
+                    idx = mid;
+                    lo = mid + 1;
+                }
+                else {
+                    hi = mid - 1;
+                }
+            }
+            let value;
+            if (idx === -1) {
+                value = tr.base;
+            }
+            else {
+                const t = list[idx];
+                const local = ms - t.start;
+                if (local <= 0) {
+                    value = t._from;
+                }
+                else if (t.duration <= 0) {
+                    value = t.to;
+                }
+                else if (local >= t.duration) {
+                    value = t.to;
+                }
+                else {
+                    const p = clamp(local / t.duration, 0, 1);
+                    const fn = easingFns[t.easing ?? 'linear'];
+                    const eased = fn(p);
+                    value = t._from + (t.to - t._from) * eased;
+                }
+            }
+            adapter.set(tr.target, tr.property, value);
+        }
+        adapter.flush?.();
+    }
+    function tick(now) {
+        if (!playing)
+            return;
+        const delta = now - lastFrameTime;
+        lastFrameTime = now;
+        timeMs = Math.min(total, timeMs + delta);
+        applyAt(timeMs);
+        if (timeMs >= total) {
+            playing = false;
+            rafId = null;
+            return;
+        }
+        rafId = globalThis.requestAnimationFrame(tick);
+    }
+    const controller = {
+        load(s) {
+            spec = s;
+            const built = buildInternal(s);
+            tracks = built.tracks;
+            total = built.dur;
+            timeMs = 0;
+            captured = false;
+            if (rafId != null) {
+                globalThis.cancelAnimationFrame(rafId);
+                rafId = null;
+            }
+            playing = false;
+            // apply initial state
+            captureFromsIfNeeded();
+            applyAt(0);
+            return controller;
+        },
+        play() {
+            if (!spec)
+                return;
+            captureFromsIfNeeded();
+            if (playing)
+                return;
+            playing = true;
+            lastFrameTime = performance.now();
+            rafId = globalThis.requestAnimationFrame(tick);
+        },
+        pause() {
+            if (!playing)
+                return;
+            playing = false;
+            if (rafId != null) {
+                globalThis.cancelAnimationFrame(rafId);
+                rafId = null;
+            }
+        },
+        seek(ms) {
+            if (!spec)
+                return;
+            captureFromsIfNeeded();
+            timeMs = clamp(ms, 0, total);
+            applyAt(timeMs);
+        },
+        stop() {
+            if (!spec)
+                return;
+            if (rafId != null) {
+                globalThis.cancelAnimationFrame(rafId);
+                rafId = null;
+            }
+            playing = false;
+            timeMs = 0;
+            // restore to from state (froms are captured or defined)
+            captureFromsIfNeeded();
+            applyAt(0);
+        },
+        isPlaying() {
+            return playing;
+        },
+        time() {
+            return timeMs;
+        },
+        duration() {
+            return total;
+        },
+    };
+    return controller;
+}

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

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