@vkcha/svg-core 0.1.2 → 1.0.0

package/src/canvas/PanZoomCanvas.ts

@@ -10,6 +10,19 @@ export type PanZoomListener = (state: Readonly<PanZoomState>) => void;
 
 export type PanZoomWheelMode = "zoom" | "pan";
 
+export type WorldGroupConfig = {
+  /** Custom ID for the world group (e.g., "canvasgroup"). */
+  id?: string;
+  /** Static attributes to set on the world group. */
+  attributes?: Record<string, string>;
+  /**
+   * Dynamic attribute that updates with zoom level.
+   * The callback receives the current zoom and returns the attribute value.
+   * Example: { "data-canvas-zoom": (zoom) => String(Math.round(zoom)) }
+   */
+  dynamicAttributes?: Record<string, (zoom: number) => string>;
+};
+
 export type PanZoomOptions = {
   /** Default: "pan" (current behavior). Figma/Mac trackpad feel often uses "pan". */
   wheelMode: PanZoomWheelMode;
@@ -22,10 +35,14 @@ export type PanZoomOptions = {
   maxZoom: number;
   /** Zoom speed multiplier for wheel (higher = faster). */
   zoomSpeed: number;
+  /** Extra zoom speed multiplier when ctrl/cmd is held (pinch on macOS). */
+  pinchZoomSpeed: number;
   /** If true, invert wheel direction for zoom. */
   invertZoom: boolean;
   /** If true, invert wheel direction for pan. */
   invertPan: boolean;
+  /** Configuration for the world group element. */
+  worldGroup?: WorldGroupConfig;
 };
 
 export const DEFAULT_PANZOOM_OPTIONS: PanZoomOptions = {
@@ -35,6 +52,7 @@ export const DEFAULT_PANZOOM_OPTIONS: PanZoomOptions = {
   minZoom: 0.2,
   maxZoom: 8,
   zoomSpeed: 1,
+  pinchZoomSpeed: 2,
   invertZoom: false,
   invertPan: false,
 };
@@ -59,8 +77,12 @@ export class PanZoomCanvas {
 
   private dragPointerId: number | null = null;
   private panStart: { panX: number; panY: number; x: number; y: number } | null = null;
+  private isPanning = false;
   private isSpaceDown = false;
 
+  private static readonly DRAG_THRESHOLD_PX = 5;
+  private animationFrameId: number | null = null;
+
   private windowKeyDownHandler: ((e: KeyboardEvent) => void) | null = null;
   private windowKeyUpHandler: ((e: KeyboardEvent) => void) | null = null;
   private svgWheelHandler: ((e: WheelEvent) => void) | null = null;
@@ -77,17 +99,68 @@ export class PanZoomCanvas {
     this.svg.replaceChildren(this.world);
 
     this.setOptions(opts);
+    this.applyWorldGroupConfig();
 
-    // Disable browser gestures on the SVG surface.
+    // Disable browser gestures, focus outline, and selection highlight on the SVG surface.
     this.svg.style.touchAction = "none";
     this.svg.style.userSelect = "none";
+    const svgStyle = this.svg.style as CSSStyleDeclaration & {
+      webkitUserSelect?: string;
+      webkitTapHighlightColor?: string;
+    };
+    svgStyle.webkitUserSelect = "none";
+    svgStyle.webkitTapHighlightColor = "transparent";
+    this.svg.style.outline = "none";
+    this.svg.setAttribute("tabindex", "-1");
+
+    // Also disable outline on the world group.
+    this.world.style.outline = "none";
 
     this.attach();
     this.render();
   }
 
+  private applyWorldGroupConfig() {
+    const cfg = this.options.worldGroup;
+    if (!cfg) return;
+
+    if (cfg.id) {
+      this.world.id = cfg.id;
+    }
+
+    if (cfg.attributes) {
+      for (const [key, value] of Object.entries(cfg.attributes)) {
+        this.world.setAttribute(key, value);
+      }
+    }
+  }
+
+  /**
+   * Create a new <g> layer inside the world.
+   * Useful when you want pan/zoom only and manage your own SVG content.
+   */
+  createLayer(
+    name?: string,
+    opts?: { position?: "front" | "back"; pointerEvents?: string },
+  ): SVGGElement {
+    const layer = svgEl("g");
+    if (name) layer.dataset.layer = name;
+    if (opts?.pointerEvents) layer.style.pointerEvents = opts.pointerEvents;
+    if (opts?.position === "back" && this.world.firstChild) {
+      this.world.insertBefore(layer, this.world.firstChild);
+    } else {
+      this.world.appendChild(layer);
+    }
+    return layer;
+  }
+
   setOptions(next: Partial<PanZoomOptions>) {
     this.options = { ...DEFAULT_PANZOOM_OPTIONS, ...this.options, ...next };
+
+    if (next.worldGroup) {
+      this.applyWorldGroupConfig();
+      this.render();
+    }
   }
 
   /**
@@ -116,6 +189,66 @@ export class PanZoomCanvas {
     this.scheduleNotify();
   }
 
+  /**
+   * Animate to a target state over a duration.
+   * Uses linear easing by default. Pass a custom easing function for different curves.
+   * Example: `(t) => 1 - Math.pow(1 - t, 3)` for ease-out cubic.
+   */
+  animateTo(
+    target: Partial<PanZoomState>,
+    durationMs = 300,
+    easing: (t: number) => number = (t) => t,
+  ): Promise<void> {
+    return new Promise((resolve) => {
+      if (this.animationFrameId !== null) {
+        cancelAnimationFrame(this.animationFrameId);
+        this.animationFrameId = null;
+      }
+
+      const start = {
+        zoom: this.state.zoom,
+        panX: this.state.panX,
+        panY: this.state.panY,
+      };
+      const end = {
+        zoom: target.zoom ?? start.zoom,
+        panX: target.panX ?? start.panX,
+        panY: target.panY ?? start.panY,
+      };
+
+      const startTime = performance.now();
+
+      const step = (now: number) => {
+        const elapsed = now - startTime;
+        const t = Math.min(1, elapsed / durationMs);
+        const eased = easing(t);
+
+        this.setState({
+          zoom: start.zoom + (end.zoom - start.zoom) * eased,
+          panX: start.panX + (end.panX - start.panX) * eased,
+          panY: start.panY + (end.panY - start.panY) * eased,
+        });
+
+        if (t < 1) {
+          this.animationFrameId = requestAnimationFrame(step);
+        } else {
+          this.animationFrameId = null;
+          resolve();
+        }
+      };
+
+      this.animationFrameId = requestAnimationFrame(step);
+    });
+  }
+
+  /** Stop any running animation. */
+  stopAnimation() {
+    if (this.animationFrameId !== null) {
+      cancelAnimationFrame(this.animationFrameId);
+      this.animationFrameId = null;
+    }
+  }
+
   reset() {
     this.setState({ zoom: 1, panX: 0, panY: 0 });
   }
@@ -125,6 +258,9 @@ export class PanZoomCanvas {
    * Call this when the canvas is no longer needed to prevent memory leaks.
    */
   destroy() {
+    // Cancel any running animation
+    this.stopAnimation();
+
     // Remove window listeners
     if (this.windowKeyDownHandler) {
       window.removeEventListener("keydown", this.windowKeyDownHandler);
@@ -173,6 +309,7 @@ export class PanZoomCanvas {
 
     // Clear state
     this.panStart = null;
+    this.isPanning = false;
     this.isSpaceDown = false;
     this.listeners.clear();
   }
@@ -204,6 +341,7 @@ export class PanZoomCanvas {
       const { wheelMode, zoomRequiresCtrlKey, invertZoom, invertPan } = this.options;
 
       const ctrl = e.ctrlKey || e.metaKey;
+      const isPinchGesture = e.ctrlKey && !e.metaKey;
 
       // Desired behavior:
       // - wheelMode="zoom" (default): wheel zooms. If zoomRequiresCtrlKey=true, only zoom when ctrl/cmd is pressed.
@@ -223,7 +361,11 @@ export class PanZoomCanvas {
 
       const worldBefore = this.screenToWorld(pt.x, pt.y);
       const dy = invertZoom ? -e.deltaY : e.deltaY;
-      const zoomFactor = Math.exp(-dy * 0.001 * this.options.zoomSpeed);
+      const pinchBoost =
+        isPinchGesture && e.deltaMode === WheelEvent.DOM_DELTA_PIXEL
+          ? this.options.pinchZoomSpeed
+          : 1;
+      const zoomFactor = Math.exp(-dy * 0.001 * this.options.zoomSpeed * pinchBoost);
       const nextZoom = clamp(
         this.state.zoom * zoomFactor,
         this.options.minZoom,
@@ -240,10 +382,12 @@ export class PanZoomCanvas {
     this.svg.addEventListener("wheel", this.svgWheelHandler, { passive: false });
 
     this.svgPointerDownHandler = (e: PointerEvent) => {
+      if (e.button !== 0) return;
       if (this.dragPointerId !== null) return;
       if (this.options.panRequiresSpaceKey && !this.isSpaceDown) return;
+
       this.dragPointerId = e.pointerId;
-      this.svg.setPointerCapture(e.pointerId);
+      this.isPanning = false;
 
       const pt = this.svgPoint(e.clientX, e.clientY);
       this.panStart = { panX: this.state.panX, panY: this.state.panY, x: pt.x, y: pt.y };
@@ -258,6 +402,15 @@ export class PanZoomCanvas {
       const pt = this.svgPoint(e.clientX, e.clientY);
       const dx = pt.x - this.panStart.x;
       const dy = pt.y - this.panStart.y;
+
+      if (!this.isPanning) {
+        if (Math.hypot(dx, dy) < PanZoomCanvas.DRAG_THRESHOLD_PX) {
+          return;
+        }
+        this.isPanning = true;
+        this.svg.setPointerCapture(e.pointerId);
+      }
+
       this.setState({ panX: this.panStart.panX + dx, panY: this.panStart.panY + dy });
     };
     this.svg.addEventListener("pointermove", this.svgPointerMoveHandler);
@@ -265,15 +418,33 @@ export class PanZoomCanvas {
     const end = (e: PointerEvent) => {
       if (this.dragPointerId === null) return;
       if (e.pointerId !== this.dragPointerId) return;
+
+      if (this.isPanning) {
+        try {
+          this.svg.releasePointerCapture(e.pointerId);
+        } catch {
+          // Ignore if already released
+        }
+      }
+
       this.dragPointerId = null;
       this.panStart = null;
+      this.isPanning = false;
     };
 
     this.svgPointerUpHandler = end;
     this.svgPointerCancelHandler = end;
     this.svgPointerLeaveHandler = () => {
+      if (this.isPanning && this.dragPointerId !== null) {
+        try {
+          this.svg.releasePointerCapture(this.dragPointerId);
+        } catch {
+          // Ignore
+        }
+      }
       this.dragPointerId = null;
       this.panStart = null;
+      this.isPanning = false;
     };
 
     this.svg.addEventListener("pointerup", this.svgPointerUpHandler);
@@ -284,6 +455,13 @@ export class PanZoomCanvas {
   private render() {
     const { zoom, panX, panY } = this.state;
     this.world.setAttribute("transform", `matrix(${zoom} 0 0 ${zoom} ${panX} ${panY})`);
+
+    const dynamicAttrs = this.options.worldGroup?.dynamicAttributes;
+    if (dynamicAttrs) {
+      for (const [key, fn] of Object.entries(dynamicAttrs)) {
+        this.world.setAttribute(key, fn(zoom));
+      }
+    }
   }
 
   private svgPoint(clientX: number, clientY: number) {

package/src/index.ts

@@ -1,8 +1,13 @@
 export { SvgCore } from "./SvgCore";
-export type { CullingOptions, CullingStats, InitOptions } from "./SvgCore";
+export type { CullingOptions, CullingStats, InitOptions, WorldLayerPosition } from "./SvgCore";
 
 export { PanZoomCanvas } from "./canvas/PanZoomCanvas";
-export type { PanZoomOptions, PanZoomState, PanZoomWheelMode } from "./canvas/PanZoomCanvas";
+export type {
+  PanZoomOptions,
+  PanZoomState,
+  PanZoomWheelMode,
+  WorldGroupConfig,
+} from "./canvas/PanZoomCanvas";
 
 export { Node } from "./scene/Node";
 export type { NodeId, NodeOptions } from "./scene/Node";