@vkcha/svg-core 0.1.2 → 1.0.0

package/README.md

@@ -7,8 +7,9 @@ Lightweight **SVG scene rendering core** for the web (TypeScript):
 - **Viewport culling** (removes offscreen nodes from DOM for performance)
 - **Hit-testing + node events** (`click`, “double click”, right click)
 - **SVG fragment utilities** (sanitize/measure/parse fragments)
+- **Smooth animations** (`animateTo` with custom easing)
 
-**Live demo:** `https://vkcha.com`
+**Live demo:** [vkcha.com](https://vkcha.com) | **Docs:** [vkcha.com/#docs](https://vkcha.com/#docs)
 
 ---
 
@@ -111,6 +112,150 @@ export function SvgScene() {
 }
 ```
 
+If you prefer a ready-made component wrapper, use `@vkcha/svg-core-react`:
+
+```tsx
+import { useMemo } from "react";
+import { SvgCoreView } from "@vkcha/svg-core-react";
+
+export function SvgScene() {
+  const nodes = useMemo(
+    () => [
+      { id: "a", x: 0, y: 0, fragment: `<rect width="120" height="60" rx="10" fill="#10b981"/>` },
+    ],
+    [],
+  );
+
+  return (
+    <SvgCoreView
+      init={{
+        panZoom: { wheelMode: "pan", zoomRequiresCtrlKey: true },
+        culling: { enabled: true },
+      }}
+      nodes={nodes}
+      style={{ width: "100%", height: "100%" }}
+    />
+  );
+}
+```
+
+---
+
+### Pan/zoom only (no nodes)
+
+If you just want pan/zoom and plan to manage your own SVG content:
+
+```ts
+import { PanZoomCanvas } from "@vkcha/svg-core";
+
+const svg = document.querySelector("#canvas") as SVGSVGElement;
+const canvas = new PanZoomCanvas(svg, { wheelMode: "pan" });
+
+// Add your own SVG elements under the world layer:
+const layer = canvas.createLayer("custom");
+layer.innerHTML = `
+  <rect x="0" y="0" width="200" height="120" fill="#60a5fa" />
+  <circle cx="240" cy="80" r="40" fill="#f59e0b" />
+`;
+```
+
+If you want the same thing in React, use `@vkcha/svg-core-react`:
+
+```tsx
+import { useEffect, useRef } from "react";
+import { PanZoomCanvasView } from "@vkcha/svg-core-react";
+
+export function PanZoomOnly() {
+  const viewRef = useRef<React.ElementRef<typeof PanZoomCanvasView> | null>(null);
+
+  useEffect(() => {
+    const world = viewRef.current?.getWorld();
+    if (!world) return;
+    world.innerHTML = `
+      <rect x="0" y="0" width="200" height="120" fill="#60a5fa" />
+      <circle cx="240" cy="80" r="40" fill="#f59e0b" />
+    `;
+  }, []);
+
+  return (
+    <PanZoomCanvasView
+      ref={viewRef}
+      options={{ wheelMode: "pan" }}
+      style={{ width: "100%", height: "100%" }}
+    />
+  );
+}
+```
+
+If you prefer to initialize `SvgCore` and still add custom content:
+
+```ts
+import { SvgCore } from "@vkcha/svg-core";
+
+const svg = document.querySelector("#canvas") as SVGSVGElement;
+const core = new SvgCore(svg, { panZoom: { wheelMode: "pan" } });
+
+const layer = core.createWorldLayer("custom", { position: "below-nodes" });
+layer.innerHTML = `<path d="M10 10H200V60Z" fill="#34d399" />`;
+```
+
+#### `PanZoomCanvas` API (concise reference)
+
+**State**
+
+- `canvas.state: { zoom, panX, panY }` — current state
+- `canvas.setState(partial)` — set state immediately
+- `canvas.reset()` — reset to `{ zoom: 1, panX: 0, panY: 0 }`
+
+**Animation**
+
+- `canvas.animateTo(target, durationMs?, easing?)` — animate to a target state (returns `Promise<void>`)
+- `canvas.stopAnimation()` — cancel any running animation
+
+Example: smooth zoom with ease-out cubic:
+
+```ts
+await canvas.animateTo(
+  { zoom: 2, panX: 100, panY: 50 },
+  400,
+  (t) => 1 - Math.pow(1 - t, 3), // ease-out cubic
+);
+```
+
+**Layers**
+
+- `canvas.createLayer(name?, opts?)` — create a `<g>` inside the world
+  - `opts.position`: `"front"` (default) or `"back"`
+  - `opts.pointerEvents`: CSS `pointer-events` value (e.g., `"none"`)
+
+**Subscription**
+
+- `canvas.subscribe(fn)` — listen to state changes (returns unsubscribe function)
+
+**Options**
+
+- `canvas.setOptions(partial)` — update options at runtime
+
+**World Group Configuration**
+
+Configure the world `<g>` element with custom attributes:
+
+```ts
+const canvas = new PanZoomCanvas(svg, {
+  worldGroup: {
+    id: "canvas-world",
+    attributes: { "data-testid": "world" },
+    dynamicAttributes: {
+      "data-zoom": (zoom) => String(Math.round(zoom * 100)),
+    },
+  },
+});
+```
+
+**Cleanup**
+
+- `canvas.destroy()` — remove all listeners, cancel animations
+
 ---
 
 ### Core concepts
@@ -129,6 +274,7 @@ Useful properties:
 - `core.world`: a `<g>` for “world space” content
 - `core.state`: `{ zoom, panX, panY }`
 - `core.panZoomOptions`: merged pan/zoom options (min/max, wheel mode, etc.)
+- `core.createWorldLayer(...)`: create a custom `<g>` inside the world layer
 
 Pan/zoom can be configured **on init** via `new SvgCore(svg, { panZoom: ... })` and **any time later** via `core.configurePanZoom(...)`.
 
@@ -148,8 +294,10 @@ Pan/zoom can be configured **on init** via `new SvgCore(svg, { panZoom: ... })`
 - `minZoom: 0.2`
 - `maxZoom: 8`
 - `zoomSpeed: 1`
+- `pinchZoomSpeed: 2` — extra speed multiplier for trackpad pinch gestures
 - `invertZoom: false`
 - `invertPan: false`
+- `worldGroup: undefined` — optional configuration for the world `<g>` element (id, attributes, dynamic attributes)
 
 **Culling defaults**
 

package/dist/compat.js

@@ -0,0 +1,391 @@
+import { createEngine } from './index.js';
+import { attachDomInput } from './input-dom.js';
+import { createSvgDomRenderer, measureFragmentMetrics } from './renderer-svg-dom.js';
+export { parseFragmentElements, sanitizeFragment } from './renderer-svg-dom.js';
+
+class SvgCore {
+    engine;
+    input;
+    renderer;
+    worldEl;
+    nodesLayerEl;
+    nodes = [];
+    nodeById = new Map();
+    cullingListeners = new Set();
+    lastCullingStats = { visible: 0, hidden: 0, total: 0 };
+    get svg() {
+        return this.input.host;
+    }
+    get world() {
+        return this.worldEl;
+    }
+    get state() {
+        const c = this.engine.getCamera();
+        return { zoom: c.zoom, panX: c.panX, panY: c.panY };
+    }
+    get panZoomOptions() {
+        const o = this.input.getOptions();
+        return {
+            wheelMode: o.wheelMode,
+            zoomRequiresCtrlKey: o.zoomRequiresCtrlKey,
+            panRequiresSpaceKey: o.panRequiresSpaceKey,
+            minZoom: o.minZoom,
+            maxZoom: o.maxZoom,
+            zoomSpeed: o.zoomSpeed,
+            invertZoom: o.invertZoom,
+            invertPan: o.invertPan,
+        };
+    }
+    constructor(svg, opts) {
+        const c = opts?.culling;
+        const cullingEnabled = typeof c === "boolean" ? c : c?.enabled ?? true;
+        const overscanPx = Math.max(0, typeof c === "object" && c ? (c.overscanPx ?? 30) : 30);
+        this.engine = createEngine({
+            culling: { enabled: cullingEnabled, overscanPx },
+            getNodeBounds: (node) => this.getNodeBounds(node),
+            order: (a, b) => {
+                const za = a.zIndex ?? 0;
+                const zb = b.zIndex ?? 0;
+                if (za !== zb)
+                    return za - zb;
+                return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+            },
+        });
+        const renderer = createSvgDomRenderer({
+            getFragment: (n) => n.data?.fragment ?? "",
+            getNodeKey: (n) => n.data?.key ?? n.id,
+        });
+        this.renderer = renderer;
+        renderer.mount(svg);
+        this.engine.attachRenderer(renderer);
+        const world = svg.querySelector(`g[data-layer="world"]`);
+        const nodesLayer = svg.querySelector(`g[data-layer="nodes"]`);
+        if (!(world instanceof SVGGElement) || !(nodesLayer instanceof SVGGElement)) {
+            throw new Error("SvgCore renderer mount failed");
+        }
+        this.worldEl = world;
+        this.nodesLayerEl = nodesLayer;
+        this.worldEl.style.pointerEvents = "none";
+        this.nodesLayerEl.style.pointerEvents = "none";
+        svg.style.touchAction = "none";
+        svg.style.userSelect = "none";
+        this.input = attachDomInput(svg, this.engine, {
+            ...(opts?.panZoom ?? {}),
+            clickDelayMs: 300,
+            dragThresholdPx: 5,
+            onClick: (hit) => {
+                const node = hit ? this.nodeById.get(hit.id) ?? null : null;
+                node?.onClick?.(node);
+            },
+            onDoubleClick: (hit) => {
+                const node = hit ? this.nodeById.get(hit.id) ?? null : null;
+                node?.onDoubleClick?.(node);
+            },
+            onRightClick: (hit) => {
+                const node = hit ? this.nodeById.get(hit.id) ?? null : null;
+                node?.onRightClick?.(node);
+            },
+        });
+        this.engine.onCullingStatsChange((s) => {
+            const next = { visible: s.visible, hidden: s.hidden, total: s.total };
+            this.lastCullingStats = next;
+            for (const fn of this.cullingListeners)
+                fn(next);
+        });
+        this.engine.start();
+    }
+    setZoom(nextZoom, anchor) {
+        const o = this.panZoomOptions;
+        const z = clamp(nextZoom, o.minZoom, o.maxZoom);
+        const vp = this.engine.getViewport();
+        const ax = anchor?.x ?? Math.max(1, vp.width) / 2;
+        const ay = anchor?.y ?? Math.max(1, vp.height) / 2;
+        this.engine.zoomAt({ x: ax, y: ay }, z);
+    }
+    zoomBy(factor, anchor) {
+        const f = Number.isFinite(factor) ? factor : 1;
+        if (f <= 0)
+            return;
+        this.setZoom(this.state.zoom * f, anchor);
+    }
+    setState(next) {
+        this.engine.setCamera(next);
+    }
+    resetView() {
+        this.engine.setCamera({ zoom: 1, panX: 0, panY: 0 });
+    }
+    configurePanZoom(next) {
+        this.input.setOptions({
+            wheelMode: next.wheelMode,
+            zoomRequiresCtrlKey: next.zoomRequiresCtrlKey,
+            panRequiresSpaceKey: next.panRequiresSpaceKey,
+            minZoom: next.minZoom,
+            maxZoom: next.maxZoom,
+            zoomSpeed: next.zoomSpeed,
+            invertZoom: next.invertZoom,
+            invertPan: next.invertPan,
+        });
+    }
+    clientToCanvas(clientX, clientY) {
+        const r = this.svg.getBoundingClientRect();
+        const sx = clientX - r.left;
+        const sy = clientY - r.top;
+        return this.engine.screenToWorld(sx, sy);
+    }
+    hitTestVisibleNodeAtClient(clientX, clientY) {
+        const r = this.svg.getBoundingClientRect();
+        const sx = clientX - r.left;
+        const sy = clientY - r.top;
+        const hit = this.engine.hitTestScreenPoint(sx, sy);
+        return hit ? this.nodeById.get(hit.id) ?? null : null;
+    }
+    setNodes(nodes) {
+        const seenIds = new Set();
+        const duplicateIds = new Set();
+        for (let i = 0; i < nodes.length; i++) {
+            const id = nodes[i].id;
+            if (seenIds.has(id))
+                duplicateIds.add(id);
+            else
+                seenIds.add(id);
+        }
+        if (duplicateIds.size > 0) {
+            console.warn(`Duplicate node ids found: ${Array.from(duplicateIds)
+                .map((id) => `"${id}"`)
+                .join(", ")}. Each node should have a unique id.`);
+        }
+        this.nodes = nodes;
+        this.nodeById.clear();
+        for (const n of nodes)
+            this.nodeById.set(n.id, n);
+        this.engine.setScene(nodes.map((n) => this.toSceneNode(n)));
+        this.engine.renderOnce();
+    }
+    redraw(ids) {
+        if (!ids || ids.length === 0) {
+            this.engine.setScene(this.nodes.map((n) => this.toSceneNode(n)));
+            this.engine.renderOnce();
+            return;
+        }
+        for (const id of ids) {
+            const n = this.nodeById.get(id);
+            if (!n)
+                continue;
+            this.engine.updateNode(id, this.toSceneNode(n));
+        }
+        this.engine.renderOnce();
+    }
+    setCullingEnabled(enabled) {
+        this.engine.setCulling({ enabled });
+        this.engine.renderOnce();
+    }
+    setCullingOverscanPx(px) {
+        this.engine.setCulling({ overscanPx: Math.max(0, px) });
+        this.engine.renderOnce();
+    }
+    onCullingStatsChange(fn) {
+        this.cullingListeners.add(fn);
+        fn(this.lastCullingStats);
+        return () => this.cullingListeners.delete(fn);
+    }
+    onPanZoomChange(fn) {
+        let first = true;
+        return this.engine.onCameraChange((c) => {
+            if (first) {
+                first = false;
+                return;
+            }
+            fn({ zoom: c.zoom, panX: c.panX, panY: c.panY });
+        });
+    }
+    remove(ids) {
+        if (!ids || ids.length === 0) {
+            this.nodes = [];
+            this.nodeById.clear();
+            this.engine.removeNodes();
+            this.engine.renderOnce();
+            return;
+        }
+        const idSet = new Set(ids);
+        this.nodes = this.nodes.filter((n) => !idSet.has(n.id));
+        for (const id of ids)
+            this.nodeById.delete(id);
+        this.engine.removeNodes(ids);
+        this.engine.renderOnce();
+    }
+    destroy() {
+        this.input.detach();
+        this.engine.stop();
+        this.engine.detachRenderer();
+        this.renderer.unmount();
+        this.nodesLayerEl.replaceChildren();
+        this.nodeById.clear();
+        this.nodes = [];
+        this.cullingListeners.clear();
+    }
+    toSceneNode(n) {
+        const width = n.width === null ? undefined : n.width;
+        const height = n.height === null ? undefined : n.height;
+        const fragment = n.fragment ?? "";
+        const key = `${n.id}:${fragment}`;
+        return {
+            id: n.id,
+            x: n.x,
+            y: n.y,
+            width,
+            height,
+            zIndex: n.zIndex,
+            data: { fragment, key },
+        };
+    }
+    getNodeBounds(node) {
+        const d = node.data;
+        const fragment = d?.fragment ?? "";
+        const metrics = measureFragmentMetrics(fragment);
+        const bbox = metrics?.bbox ?? { width: 240, height: 160 };
+        const pad = metrics?.pad ?? 0;
+        const ww = typeof node.width === "number" && Number.isFinite(node.width) && node.width > 0
+            ? node.width
+            : Math.max(1, bbox.width + pad * 2);
+        const hh = typeof node.height === "number" && Number.isFinite(node.height) && node.height > 0
+            ? node.height
+            : Math.max(1, bbox.height + pad * 2);
+        return { x0: node.x, y0: node.y, x1: node.x + ww, y1: node.y + hh };
+    }
+}
+function clamp(v, min, max) {
+    const n = Number.isFinite(v) ? v : min;
+    return Math.max(min, Math.min(max, n));
+}
+
+const DEFAULT_PANZOOM_OPTIONS = {
+    wheelMode: "pan",
+    zoomRequiresCtrlKey: false,
+    panRequiresSpaceKey: false,
+    minZoom: 0.2,
+    maxZoom: 8,
+    zoomSpeed: 1,
+    invertZoom: false,
+    invertPan: false,
+};
+class PanZoomCanvas {
+    svg;
+    world;
+    engine;
+    options = { ...DEFAULT_PANZOOM_OPTIONS };
+    input = null;
+    listeners = new Set();
+    notifyScheduled = false;
+    unsubEngine = null;
+    constructor(svg, opts = {}) {
+        this.svg = svg;
+        this.world = document.createElementNS("http://www.w3.org/2000/svg", "g");
+        this.world.dataset.layer = "world";
+        this.svg.replaceChildren(this.world);
+        this.engine = createEngine({ culling: { enabled: false, overscanPx: 0 } });
+        this.setOptions(opts);
+        this.svg.style.touchAction = "none";
+        this.svg.style.userSelect = "none";
+        this.unsubEngine = this.engine.onCameraChange((c) => {
+            this.world.setAttribute("transform", `matrix(${c.zoom} 0 0 ${c.zoom} ${c.panX} ${c.panY})`);
+            this.scheduleNotify();
+        });
+        this.input = attachDomInput(this.svg, this.engine, {
+            wheelMode: this.options.wheelMode,
+            zoomRequiresCtrlKey: this.options.zoomRequiresCtrlKey,
+            panRequiresSpaceKey: this.options.panRequiresSpaceKey,
+            minZoom: this.options.minZoom,
+            maxZoom: this.options.maxZoom,
+            zoomSpeed: this.options.zoomSpeed,
+            invertZoom: this.options.invertZoom,
+            invertPan: this.options.invertPan,
+            clickDelayMs: 0,
+            dragThresholdPx: 0,
+        });
+        this.engine.start();
+    }
+    get state() {
+        const c = this.engine.getCamera();
+        return { zoom: c.zoom, panX: c.panX, panY: c.panY };
+    }
+    setOptions(next) {
+        this.options = { ...DEFAULT_PANZOOM_OPTIONS, ...this.options, ...next };
+        this.input?.setOptions({
+            wheelMode: this.options.wheelMode,
+            zoomRequiresCtrlKey: this.options.zoomRequiresCtrlKey,
+            panRequiresSpaceKey: this.options.panRequiresSpaceKey,
+            minZoom: this.options.minZoom,
+            maxZoom: this.options.maxZoom,
+            zoomSpeed: this.options.zoomSpeed,
+            invertZoom: this.options.invertZoom,
+            invertPan: this.options.invertPan,
+        });
+    }
+    subscribe(fn) {
+        this.listeners.add(fn);
+        return () => this.listeners.delete(fn);
+    }
+    setState(next) {
+        this.engine.setCamera(next);
+    }
+    reset() {
+        this.engine.setCamera({ zoom: 1, panX: 0, panY: 0 });
+    }
+    destroy() {
+        this.unsubEngine?.();
+        this.unsubEngine = null;
+        this.listeners.clear();
+        this.input?.detach();
+        this.input = null;
+        this.engine.stop();
+    }
+    scheduleNotify() {
+        if (this.notifyScheduled)
+            return;
+        this.notifyScheduled = true;
+        requestAnimationFrame(() => {
+            this.notifyScheduled = false;
+            const s = this.state;
+            for (const fn of this.listeners)
+                fn(s);
+        });
+    }
+}
+
+/**
+ * A scene-graph "node" for the SVG core.
+ */
+class Node {
+    id;
+    fragment;
+    x;
+    y;
+    width;
+    height;
+    zIndex;
+    data;
+    onClick;
+    onDoubleClick;
+    onRightClick;
+    constructor(opts) {
+        if (!opts || typeof opts.id !== "string" || opts.id === "") {
+            throw new Error("Node requires a non-empty 'id' property");
+        }
+        this.id = opts.id;
+        this.fragment = opts.fragment ?? "";
+        this.x = Number.isFinite(opts?.x) ? opts?.x : 0;
+        this.y = Number.isFinite(opts?.y) ? opts?.y : 0;
+        const w = opts?.width;
+        const h = opts?.height;
+        this.width = typeof w === "number" && Number.isFinite(w) && w > 0 ? w : null;
+        this.height = typeof h === "number" && Number.isFinite(h) && h > 0 ? h : null;
+        const z = opts?.zIndex;
+        this.zIndex = typeof z === "number" && Number.isFinite(z) ? z : 0;
+        this.data = opts?.data;
+        this.onClick = opts?.onClick;
+        this.onDoubleClick = opts?.onDoubleClick;
+        this.onRightClick = opts?.onRightClick;
+    }
+}
+
+export { Node, PanZoomCanvas, SvgCore, measureFragmentMetrics };