cytoscape-canvas-underlay 1.2.3 → 1.3.0

package/README.md

@@ -8,7 +8,7 @@ A [Cytoscape.js](https://js.cytoscape.org) plugin for rendering image/PDF backgr
 - **Pan clamping** — hard boundary or iOS-style rubber-band with spring-back
 - **Minimap** — DOM-based crisp image rendering, two viewport styles (`dim` / `rect`), auto-hide, full customization
 - **Adaptive PDF quality** — low-quality render during interaction, high-quality on idle
-- **Rich navigation** — `fit`, `fitAll`, `panToElement`, `panToRegion`, coordinate conversion
+- **Rich navigation** — `fit`, `fitAll`, `panToRegion`, coordinate conversion
 - **Layer visibility** — independently show/hide drawing background and graph layer
 - **CSS filters** — invert, brightness, contrast, saturate, grayscale (invert applied first so brightness/contrast work correctly on inverted images)
 - **Rotation** — rotate main or additional drawings (0, 90, 180, 270 degrees)
@@ -147,13 +147,14 @@ api.off('zoom');               // remove all zoom handlers
 ### Navigation
 
 ```js
-api.fit();                              // fit main drawing
+api.fit();                              // fit main drawing (instant)
+api.fit({ animate: true });            // fit with animation (300ms)
+api.fit({ padding: 50 });             // fit with 50px padding
+api.fit({ animate: true, duration: 500, easing: 'ease-out' });
 api.fitToDrawing('trace-1');            // fit specific drawing
 api.fitAll();                           // fit all drawings
 api.panTo(500, 300);                    // center on world coordinate
 api.panTo(500, 300, 2.0);              // center + set zoom
-api.panToElement('node-id');            // center on cytoscape element
-api.panToElement(cy.$('#node-id'));     // also accepts element reference
 api.panToRegion(100, 100, 400, 300);   // fit a world-coordinate region
 ```
 
@@ -255,7 +256,7 @@ const inside = api.isPointInDrawing(world.x, world.y);
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `fitOnLoad` | `boolean` | `true` | Auto-fit drawing to viewport on load |
-| `fitPadding` | `number` | `50` | Default padding for fit operations (px) |
+| `fitPadding` | `number` | `0` | Default padding for fit operations (px) |
 
 ### Pan Clamping
 
@@ -368,11 +369,10 @@ These still work but the `on()`/`off()` event emitter is preferred.
 
 | Method | Description |
 |--------|-------------|
-| `fit(padding?)` | Fit main drawing to viewport |
+| `fit(opts?)` | Fit main drawing to viewport. Options: `{ animate, padding, duration, easing }` |
 | `fitToDrawing(id, padding?)` | Fit a specific additional drawing to viewport |
 | `fitAll(padding?)` | Fit all drawings (main + additional) to viewport |
 | `panTo(x, y, zoom?)` | Center viewport on world coordinate, optionally set zoom |
-| `panToElement(eleOrId, padding?)` | Fit a cytoscape element in viewport (accepts ID string or element) |
 | `panToRegion(x, y, w, h, padding?)` | Fit a world-coordinate region in viewport |
 
 ### Visibility
@@ -440,6 +440,14 @@ These still work but the `on()`/`off()` event emitter is preferred.
 
 ## Changelog
 
+### 1.3.0
+
+- **Breaking**: `fit()` now accepts an options object instead of a padding number: `fit({ animate, padding, duration, easing })`. Calling `fit()` with no arguments still works (uses defaults).
+- **Breaking**: Removed `panToElement()` — use application-level implementation for element navigation with custom zoom/animation logic.
+- **Changed**: Default `fitPadding` changed from `50` to `0`.
+- **Added**: `fit()` now supports `animate` option with configurable `duration` (default 300ms) and `easing` (default `ease-in-out-cubic`).
+- **Added**: `fit()` now calls `cy.resize()` before calculating dimensions.
+
 ### 1.2.3
 
 - **Fix**: `_springBackIfNeeded` now respects `panClamp: false`. Previously, setting `panClamp: false` at runtime disabled hard clamping but the soft spring-back animation on mouse release still fired, snapping the viewport back to drawing bounds. This made it impossible to programmatically disable pan clamping (e.g., during `panToElement` animations).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cytoscape-canvas-underlay",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "Cytoscape.js plugin for rendering image/PDF canvas underlay behind graph nodes with synchronized zoom and pan",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/DrawingOverlay.js

@@ -24,7 +24,7 @@ const DEFAULTS = {
   // ── Layout ──
   zIndex: 0,                 // Canvas z-index within overlay container
   fitOnLoad: true,           // Auto-fit drawing to viewport on load
-  fitPadding: 50,            // Padding (px) for fit operations
+  fitPadding: 0,             // Padding (px) for fit operations
 
   // ── Pan Clamping ──
   panClamp: false,           // Prevent panning too far from drawing bounds
@@ -295,6 +295,15 @@ export class DrawingOverlay {
       this._enforceLimits();
       this._draw();
       if (this._minimap) this._minimap.render();
+
+      // Schedule high-quality PDF re-render at current zoom level
+      const hasPdf = this._main.isPdf || [...this._drawings.values()].some(d => d.isPdf && d.visible);
+      if (hasPdf) {
+        if (this._qualityTimer) clearTimeout(this._qualityTimer);
+        this._qualityTimer = setTimeout(() => {
+          this._reRenderAllPdfs().then(() => this._draw());
+        }, this.opts.qualityDelay);
+      }
     };
     this._onResize = () => {
       this._setupCanvas();
@@ -712,22 +721,31 @@ export class DrawingOverlay {
      ═══════════════════════════════════════ */
 
   /** Fit the main drawing to viewport. */
-  fit(padding) {
+  fit({
+    animate = false,
+    padding = this.opts.fitPadding,
+    duration = 300,
+    easing = 'ease-in-out-cubic',
+  } = {}) {
     if (!this._main.w || !this._main.h) return;
-    const pad = padding ?? this.opts.fitPadding;
-    const container = this.cy.container().getBoundingClientRect();
-    const scaleX = (container.width - pad * 2) / this._main.w;
-    const scaleY = (container.height - pad * 2) / this._main.h;
-    const zoom = Math.max(this.cy.minZoom(), Math.min(this.cy.maxZoom(),Math.min(scaleX, scaleY)));
+    const cy = this.cy;
 
-    this.cy.zoom({
-      level: zoom,
-      renderedPosition: { x: container.width / 2, y: container.height / 2 },
-    });
-    this.cy.pan({
-      x: (container.width - this._main.w * zoom) / 2,
-      y: (container.height - this._main.h * zoom) / 2,
-    });
+    cy.resize();
+
+    const container = cy.container().getBoundingClientRect();
+    const cw = container.width - padding * 2;
+    const ch = container.height - padding * 2;
+    if (cw <= 0 || ch <= 0) return;
+
+    const scale = Math.min(cw / this._main.w, ch / this._main.h);
+    const panX = Math.round(padding + (cw - this._main.w * scale) / 2);
+    const panY = Math.round(padding + (ch - this._main.h * scale) / 2);
+
+    if (animate) {
+      cy.animate({ zoom: scale, pan: { x: panX, y: panY }, duration, easing });
+    } else {
+      cy.viewport({ zoom: scale, pan: { x: panX, y: panY } });
+    }
   }
 
   /** Fit a specific additional drawing to viewport. */
@@ -793,34 +811,6 @@ export class DrawingOverlay {
     });
   }
 
-  /** Pan to center a cytoscape element in viewport. */
-  panToElement(eleOrId, padding) {
-    const cy = this.cy;
-    const ele = typeof eleOrId === 'string' ? cy.getElementById(eleOrId) : eleOrId;
-    if (!ele || ele.empty?.()) return;
-
-    const bb = ele.boundingBox();
-    const pad = padding ?? this.opts.fitPadding;
-    const container = cy.container().getBoundingClientRect();
-
-    // Calculate zoom to fit element
-    const scaleX = (container.width - pad * 2) / bb.w;
-    const scaleY = (container.height - pad * 2) / bb.h;
-    const zoom = Math.max(this.cy.minZoom(), Math.min(this.cy.maxZoom(),Math.min(scaleX, scaleY)));
-
-    const cx = (bb.x1 + bb.x2) / 2;
-    const cy_ = (bb.y1 + bb.y2) / 2;
-
-    this.cy.zoom({
-      level: zoom,
-      renderedPosition: { x: container.width / 2, y: container.height / 2 },
-    });
-    this.cy.pan({
-      x: container.width / 2 - cx * zoom,
-      y: container.height / 2 - cy_ * zoom,
-    });
-  }
-
   /** Pan to a specific region of the drawing. */
   panToRegion(x, y, w, h, padding) {
     const pad = padding ?? this.opts.fitPadding;

package/src/index.js

@@ -38,11 +38,10 @@ function register(cytoscape) {
       getRotation() { return overlay.getRotation(); },
 
       // ── Navigation ──
-      fit(padding) { overlay.fit(padding); },
+      fit(opts) { overlay.fit(opts); },
       fitToDrawing(id, padding) { overlay.fitToDrawing(id, padding); },
       fitAll(padding) { overlay.fitAll(padding); },
       panTo(x, y, zoom) { overlay.panTo(x, y, zoom); },
-      panToElement(eleOrId, padding) { overlay.panToElement(eleOrId, padding); },
       panToRegion(x, y, w, h, padding) { overlay.panToRegion(x, y, w, h, padding); },
 
       // ── Visibility ──