@vkcha/svg-core 0.1.2 → 1.1.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**