@vkcha/svg-core 0.1.2 → 1.0.0

package/dist/index.d.ts

@@ -5,6 +5,18 @@ type PanZoomState = {
 };
 type PanZoomListener = (state: Readonly<PanZoomState>) => void;
 type PanZoomWheelMode = "zoom" | "pan";
+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>;
+};
 type PanZoomOptions = {
     /** Default: "pan" (current behavior). Figma/Mac trackpad feel often uses "pan". */
     wheelMode: PanZoomWheelMode;
@@ -17,10 +29,14 @@ 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;
 };
 /**
  * Minimal SVG "canvas" with pan/zoom.
@@ -39,7 +55,10 @@ declare class PanZoomCanvas {
     private notifyScheduled;
     private dragPointerId;
     private panStart;
+    private isPanning;
     private isSpaceDown;
+    private static readonly DRAG_THRESHOLD_PX;
+    private animationFrameId;
     private windowKeyDownHandler;
     private windowKeyUpHandler;
     private svgWheelHandler;
@@ -49,6 +68,15 @@ declare class PanZoomCanvas {
     private svgPointerCancelHandler;
     private svgPointerLeaveHandler;
     constructor(svg: SVGSVGElement, opts?: Partial<PanZoomOptions>);
+    private applyWorldGroupConfig;
+    /**
+     * 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;
     setOptions(next: Partial<PanZoomOptions>): void;
     /**
      * Subscribe to pan/zoom state changes (event-driven, no polling).
@@ -58,6 +86,14 @@ declare class PanZoomCanvas {
      */
     subscribe(fn: PanZoomListener): () => void;
     setState(next: Partial<PanZoomState>): void;
+    /**
+     * 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?: number, easing?: (t: number) => number): Promise<void>;
+    /** Stop any running animation. */
+    stopAnimation(): void;
     reset(): void;
     /**
      * Clean up all event listeners and resources.
@@ -125,6 +161,7 @@ type InitOptions = {
     panZoom?: Partial<PanZoomOptions>;
     culling?: boolean | CullingOptions;
 };
+type WorldLayerPosition = "below-nodes" | "above-nodes";
 /**
  * SvgCore entrypoint.
  *
@@ -152,11 +189,20 @@ declare class SvgCore {
     get svg(): SVGSVGElement;
     /** World layer (<g>) that you draw into. */
     get world(): SVGGElement;
+    /**
+     * Create a custom <g> layer inside the world.
+     * Useful when you want to add your own SVG content.
+     */
+    createWorldLayer(name?: string, opts?: {
+        position?: WorldLayerPosition;
+        pointerEvents?: string;
+    }): SVGGElement;
     /** Current pan/zoom state. */
     get state(): PanZoomState;
     /** Current pan/zoom options (includes minZoom/maxZoom). */
     get panZoomOptions(): Readonly<PanZoomOptions>;
     constructor(svg: SVGSVGElement, opts?: InitOptions);
+    constructor(canvas: PanZoomCanvas, opts?: InitOptions);
     /**
      * Set zoom while keeping a chosen screen-space anchor stable.
      * By default anchors at the viewport center.
@@ -231,4 +277,4 @@ type FragmentMetrics = {
 declare function measureFragmentMetrics(markup: string): FragmentMetrics | null;
 
 export { Node, PanZoomCanvas, SvgCore, measureFragmentMetrics };
-export type { CullingOptions, CullingStats, FragmentMetrics, InitOptions, NodeId, NodeOptions, PanZoomOptions, PanZoomState, PanZoomWheelMode };
+export type { CullingOptions, CullingStats, FragmentMetrics, InitOptions, NodeId, NodeOptions, PanZoomOptions, PanZoomState, PanZoomWheelMode, WorldGroupConfig, WorldLayerPosition };