jupyterlab_advanced_image_viewer_extension 1.0.2 → 1.0.4

package/lib/controller.d.ts

@@ -1,6 +1,6 @@
 export declare class ViewerController {
     private host;
-    private img;
+    private layer;
     private s;
     private tx;
     private ty;

package/lib/controller.js

@@ -1,10 +1,11 @@
 // ViewerController adds zoom + pan ON TOP of JupyterLab's stock image viewer.
-// The stock viewer already fits the image with CSS (object-fit: contain,
-// max-width/height: 100%), so the identity transform IS the correct
-// fit-to-screen view for both raster and SVG. We never read naturalWidth /
-// naturalHeight (an SVG with only a viewBox reports a bogus intrinsic size).
-// Zoom is a single relative factor s (s = 1 is fit); pan is a translate.
-// transform-origin is the host centre, matching the centred object-fit layout.
+// The stock viewer OWNS the <img> transform - it writes rotate / flip / its own
+// scale there for its keybindings (], [, h, v, 0). If we also wrote the <img>
+// transform we would clobber that (and it would clobber ours). Instead we wrap
+// the <img> in a pan layer and apply our translate+scale to the LAYER; the two
+// transforms then compose. The stock CSS (object-fit: contain, max-width/height:
+// 100%) still fits the image inside the layer, so the identity layer transform
+// equals the correct fit-to-screen view, and stock rotate/flip keeps working.
 const MIN_SCALE = 0.05;
 const MAX_SCALE = 40;
 export class ViewerController {
@@ -48,10 +49,20 @@ export class ViewerController {
             window.removeEventListener('mouseup', this.onUp);
         };
         this.host = host;
-        this.img = img;
         this.zoomStep = zoomStep;
         this.host.style.overflow = 'hidden';
-        this.img.style.transformOrigin = 'center center';
+        // Wrap the image so our zoom/pan compose with the stock rotate/flip
+        // transform that the viewer writes onto the <img> element itself. The
+        // layer fills the host (which is a positioned widget), so the stock
+        // object-fit/max-width CSS fits the image exactly as before.
+        const layer = document.createElement('div');
+        layer.className = 'jp-AdvancedImageViewer-panlayer';
+        const parent = img.parentNode;
+        if (parent) {
+            parent.insertBefore(layer, img);
+        }
+        layer.appendChild(img);
+        this.layer = layer;
         this.host.addEventListener('wheel', this.onWheel, { passive: false });
         this.host.addEventListener('mousedown', this.onDown);
         this.ro = new ResizeObserver(() => this.onResize());
@@ -119,8 +130,8 @@ export class ViewerController {
         this.host.style.cursor = this.canPan() ? 'grab' : 'default';
     }
     apply() {
-        this.img.style.transformOrigin = 'center center';
-        this.img.style.transform = `translate(${this.tx}px, ${this.ty}px) scale(${this.s})`;
+        this.layer.style.transformOrigin = 'center center';
+        this.layer.style.transform = `translate(${this.tx}px, ${this.ty}px) scale(${this.s})`;
         this.updateCursor();
     }
     dispose() {
@@ -133,5 +144,12 @@ export class ViewerController {
         this.host.removeEventListener('mousedown', this.onDown);
         window.removeEventListener('mousemove', this.onMove);
         window.removeEventListener('mouseup', this.onUp);
+        // Unwrap: restore the <img> as a direct child and drop the layer.
+        const img = this.layer.querySelector('img');
+        const parent = this.layer.parentNode;
+        if (img && parent) {
+            parent.insertBefore(img, this.layer);
+        }
+        this.layer.remove();
     }
 }

package/lib/index.js

@@ -1,7 +1,8 @@
-import { ToolbarButton } from '@jupyterlab/apputils';
+import { Dialog, showDialog, Toolbar, ToolbarButton } from '@jupyterlab/apputils';
 import { PathExt } from '@jupyterlab/coreutils';
 import { IImageTracker } from '@jupyterlab/imageviewer';
 import { ISettingRegistry } from '@jupyterlab/settingregistry';
+import { Widget } from '@lumino/widgets';
 import { ViewerController } from './controller';
 const PLUGIN_ID = 'jupyterlab_advanced_image_viewer_extension:plugin';
 const CommandIDs = {
@@ -43,6 +44,32 @@ const plugin = {
             }
             return (_a = controllers.get(widget.content)) !== null && _a !== void 0 ? _a : null;
         };
+        const showHelp = () => {
+            const body = new Widget();
+            body.addClass('jp-AdvancedImageViewer-help');
+            body.node.innerHTML = [
+                '<p>Interactive viewing layered on the standard image viewer.</p>',
+                '<p class="jp-AdvancedImageViewer-help-section">This extension</p>',
+                '<ul>',
+                '<li><b>Wheel up / down</b> - zoom in / out at the cursor</li>',
+                '<li><b>Click and drag</b> - pan a zoomed-in image</li>',
+                '<li><b>+ / - / Fit</b> - zoom in, zoom out, reset to fit</li>',
+                '<li><b>Left / Right arrows</b> - previous / next image in the folder</li>',
+                '</ul>',
+                '<p class="jp-AdvancedImageViewer-help-section">Standard viewer keys (compose with the above)</p>',
+                '<ul>',
+                '<li><b>] / [</b> - rotate clockwise / counter-clockwise</li>',
+                '<li><b>H / V</b> - flip horizontal / vertical</li>',
+                '<li><b>I</b> - invert colours</li>',
+                '<li><b>= / - / 0</b> - zoom in / out / reset</li>',
+                '</ul>'
+            ].join('');
+            void showDialog({
+                title: 'Advanced Image Viewer',
+                body,
+                buttons: [Dialog.okButton({ label: 'Close' })]
+            });
+        };
         const attach = (widget) => {
             const viewer = widget.content;
             if (controllers.has(viewer)) {
@@ -74,6 +101,18 @@ const plugin = {
                 tooltip: 'Reset to fit',
                 onClick: () => app.commands.execute(CommandIDs.resetFit)
             }));
+            widget.toolbar.addItem('advanced-spacer', Toolbar.createSpacerItem());
+            const helpLink = new Widget({ node: document.createElement('a') });
+            const helpAnchor = helpLink.node;
+            helpAnchor.textContent = 'help';
+            helpAnchor.href = '#';
+            helpAnchor.title = 'Keybindings and help';
+            helpAnchor.className = 'jp-AdvancedImageViewer-help-link';
+            helpAnchor.addEventListener('click', event => {
+                event.preventDefault();
+                showHelp();
+            });
+            widget.toolbar.addItem('advanced-help', helpLink);
         };
         tracker.forEach(widget => attach(widget));
         tracker.widgetAdded.connect((_, widget) => attach(widget));

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "jupyterlab_advanced_image_viewer_extension",
-    "version": "1.0.2",
+    "version": "1.0.4",
     "description": "JupyterLab extension for advanced image viewing: fit-to-screen, cursor-anchored wheel zoom, drag-to-pan, and Left/Right arrow keys to move to the previous and next image in a folder",
     "keywords": [
         "jupyter",
@@ -62,7 +62,8 @@
         "@jupyterlab/docregistry": "^4.0.0",
         "@jupyterlab/imageviewer": "^4.0.0",
         "@jupyterlab/settingregistry": "^4.0.0",
-        "@lumino/disposable": "^2.0.0"
+        "@lumino/disposable": "^2.0.0",
+        "@lumino/widgets": "^2.0.0"
     },
     "devDependencies": {
         "@jupyterlab/builder": "^4.0.0",

package/src/__tests__/controller.spec.ts

@@ -0,0 +1,84 @@
+import { ViewerController } from '../controller';
+
+// jsdom has no ResizeObserver; provide a no-op stub.
+class MockResizeObserver {
+  observe(): void {
+    /* no-op */
+  }
+  unobserve(): void {
+    /* no-op */
+  }
+  disconnect(): void {
+    /* no-op */
+  }
+}
+
+describe('ViewerController', () => {
+  let host: HTMLElement;
+  let img: HTMLImageElement;
+
+  beforeAll(() => {
+    (window as any).ResizeObserver = MockResizeObserver;
+  });
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    img = document.createElement('img');
+    host.appendChild(img);
+    document.body.appendChild(host);
+  });
+
+  afterEach(() => {
+    host.remove();
+  });
+
+  it('wraps the image in a pan layer so the stock viewer keeps the img transform', () => {
+    const c = new ViewerController(host, img, 0.1);
+    const layer = host.querySelector('.jp-AdvancedImageViewer-panlayer');
+    expect(layer).not.toBeNull();
+    expect(img.parentElement).toBe(layer);
+    c.dispose();
+  });
+
+  it('applies the transform to the layer, never to the image', () => {
+    const c = new ViewerController(host, img, 0.1);
+    const layer = host.querySelector(
+      '.jp-AdvancedImageViewer-panlayer'
+    ) as HTMLElement;
+    expect(layer.style.transform).toBe('translate(0px, 0px) scale(1)');
+    expect(img.style.transform).toBe('');
+    c.dispose();
+  });
+
+  it('zooms the layer in, allows zoom-out below fit, and resets to identity', () => {
+    const c = new ViewerController(host, img, 0.1);
+    const layer = host.querySelector(
+      '.jp-AdvancedImageViewer-panlayer'
+    ) as HTMLElement;
+    c.zoomIn();
+    expect(layer.style.transform).toContain('scale(1.1)');
+    c.reset();
+    expect(layer.style.transform).toBe('translate(0px, 0px) scale(1)');
+    c.zoomOut();
+    const scale = parseFloat(
+      /scale\(([0-9.]+)\)/.exec(layer.style.transform)![1]
+    );
+    expect(scale).toBeLessThan(1);
+    c.dispose();
+  });
+
+  it('never writes the image transform even after zooming (no clobber of rotate/flip)', () => {
+    const c = new ViewerController(host, img, 0.1);
+    c.zoomIn();
+    c.zoomIn();
+    expect(img.style.transform).toBe('');
+    c.dispose();
+  });
+
+  it('unwraps the image on dispose', () => {
+    const c = new ViewerController(host, img, 0.1);
+    c.dispose();
+    expect(host.querySelector('.jp-AdvancedImageViewer-panlayer')).toBeNull();
+    expect(img.parentElement).toBe(host);
+  });
+});

package/src/controller.ts

@@ -1,17 +1,18 @@
 // ViewerController adds zoom + pan ON TOP of JupyterLab's stock image viewer.
-// The stock viewer already fits the image with CSS (object-fit: contain,
-// max-width/height: 100%), so the identity transform IS the correct
-// fit-to-screen view for both raster and SVG. We never read naturalWidth /
-// naturalHeight (an SVG with only a viewBox reports a bogus intrinsic size).
-// Zoom is a single relative factor s (s = 1 is fit); pan is a translate.
-// transform-origin is the host centre, matching the centred object-fit layout.
+// The stock viewer OWNS the <img> transform - it writes rotate / flip / its own
+// scale there for its keybindings (], [, h, v, 0). If we also wrote the <img>
+// transform we would clobber that (and it would clobber ours). Instead we wrap
+// the <img> in a pan layer and apply our translate+scale to the LAYER; the two
+// transforms then compose. The stock CSS (object-fit: contain, max-width/height:
+// 100%) still fits the image inside the layer, so the identity layer transform
+// equals the correct fit-to-screen view, and stock rotate/flip keeps working.
 
 const MIN_SCALE = 0.05;
 const MAX_SCALE = 40;
 
 export class ViewerController {
   private host: HTMLElement;
-  private img: HTMLImageElement;
+  private layer: HTMLElement;
   private s = 1;
   private tx = 0;
   private ty = 0;
@@ -23,10 +24,20 @@ export class ViewerController {
 
   constructor(host: HTMLElement, img: HTMLImageElement, zoomStep: number) {
     this.host = host;
-    this.img = img;
     this.zoomStep = zoomStep;
     this.host.style.overflow = 'hidden';
-    this.img.style.transformOrigin = 'center center';
+    // Wrap the image so our zoom/pan compose with the stock rotate/flip
+    // transform that the viewer writes onto the <img> element itself. The
+    // layer fills the host (which is a positioned widget), so the stock
+    // object-fit/max-width CSS fits the image exactly as before.
+    const layer = document.createElement('div');
+    layer.className = 'jp-AdvancedImageViewer-panlayer';
+    const parent = img.parentNode;
+    if (parent) {
+      parent.insertBefore(layer, img);
+    }
+    layer.appendChild(img);
+    this.layer = layer;
     this.host.addEventListener('wheel', this.onWheel, { passive: false });
     this.host.addEventListener('mousedown', this.onDown);
     this.ro = new ResizeObserver(() => this.onResize());
@@ -142,8 +153,8 @@ export class ViewerController {
   }
 
   private apply(): void {
-    this.img.style.transformOrigin = 'center center';
-    this.img.style.transform = `translate(${this.tx}px, ${this.ty}px) scale(${this.s})`;
+    this.layer.style.transformOrigin = 'center center';
+    this.layer.style.transform = `translate(${this.tx}px, ${this.ty}px) scale(${this.s})`;
     this.updateCursor();
   }
 
@@ -157,5 +168,12 @@ export class ViewerController {
     this.host.removeEventListener('mousedown', this.onDown);
     window.removeEventListener('mousemove', this.onMove);
     window.removeEventListener('mouseup', this.onUp);
+    // Unwrap: restore the <img> as a direct child and drop the layer.
+    const img = this.layer.querySelector('img');
+    const parent = this.layer.parentNode;
+    if (img && parent) {
+      parent.insertBefore(img, this.layer);
+    }
+    this.layer.remove();
   }
 }

package/src/index.ts

@@ -3,7 +3,12 @@ import {
   JupyterFrontEndPlugin
 } from '@jupyterlab/application';
 
-import { ToolbarButton } from '@jupyterlab/apputils';
+import {
+  Dialog,
+  showDialog,
+  Toolbar,
+  ToolbarButton
+} from '@jupyterlab/apputils';
 
 import { PathExt } from '@jupyterlab/coreutils';
 
@@ -15,6 +20,8 @@ import { ISettingRegistry } from '@jupyterlab/settingregistry';
 
 import { IDisposable } from '@lumino/disposable';
 
+import { Widget } from '@lumino/widgets';
+
 import { ViewerController } from './controller';
 
 const PLUGIN_ID = 'jupyterlab_advanced_image_viewer_extension:plugin';
@@ -74,6 +81,33 @@ const plugin: JupyterFrontEndPlugin<void> = {
       return controllers.get(widget.content) ?? null;
     };
 
+    const showHelp = (): void => {
+      const body = new Widget();
+      body.addClass('jp-AdvancedImageViewer-help');
+      body.node.innerHTML = [
+        '<p>Interactive viewing layered on the standard image viewer.</p>',
+        '<p class="jp-AdvancedImageViewer-help-section">This extension</p>',
+        '<ul>',
+        '<li><b>Wheel up / down</b> - zoom in / out at the cursor</li>',
+        '<li><b>Click and drag</b> - pan a zoomed-in image</li>',
+        '<li><b>+ / - / Fit</b> - zoom in, zoom out, reset to fit</li>',
+        '<li><b>Left / Right arrows</b> - previous / next image in the folder</li>',
+        '</ul>',
+        '<p class="jp-AdvancedImageViewer-help-section">Standard viewer keys (compose with the above)</p>',
+        '<ul>',
+        '<li><b>] / [</b> - rotate clockwise / counter-clockwise</li>',
+        '<li><b>H / V</b> - flip horizontal / vertical</li>',
+        '<li><b>I</b> - invert colours</li>',
+        '<li><b>= / - / 0</b> - zoom in / out / reset</li>',
+        '</ul>'
+      ].join('');
+      void showDialog({
+        title: 'Advanced Image Viewer',
+        body,
+        buttons: [Dialog.okButton({ label: 'Close' })]
+      });
+    };
+
     const attach = (widget: IDocumentWidget<ImageViewer>): void => {
       const viewer = widget.content;
       if (controllers.has(viewer)) {
@@ -119,6 +153,18 @@ const plugin: JupyterFrontEndPlugin<void> = {
           onClick: () => app.commands.execute(CommandIDs.resetFit)
         })
       );
+      widget.toolbar.addItem('advanced-spacer', Toolbar.createSpacerItem());
+      const helpLink = new Widget({ node: document.createElement('a') });
+      const helpAnchor = helpLink.node as HTMLAnchorElement;
+      helpAnchor.textContent = 'help';
+      helpAnchor.href = '#';
+      helpAnchor.title = 'Keybindings and help';
+      helpAnchor.className = 'jp-AdvancedImageViewer-help-link';
+      helpAnchor.addEventListener('click', event => {
+        event.preventDefault();
+        showHelp();
+      });
+      widget.toolbar.addItem('advanced-help', helpLink);
     };
 
     tracker.forEach(widget => attach(widget));

package/style/base.css

@@ -3,3 +3,45 @@
 
     https://jupyterlab.readthedocs.io/en/stable/developer/css.html
 */
+
+/* Pan/zoom layer wrapping the <img> so our transform composes with the stock
+   viewer's rotate/flip transform on the image itself. Fills the host. */
+.jp-AdvancedImageViewer-panlayer {
+  position: absolute;
+  inset: 0;
+  transform-origin: center center;
+}
+
+/* Help shown as an accent-coloured link at the right end of the toolbar.
+   The selector is scoped under .jp-Toolbar to beat JupyterLab's toolbar `a`
+   rule (otherwise the link renders in the default muted toolbar colour). */
+.jp-Toolbar a.jp-AdvancedImageViewer-help-link {
+  align-self: center;
+  margin: 0 8px;
+  color: var(--jp-brand-color1);
+  font-size: var(--jp-ui-font-size1);
+  text-decoration: underline;
+  cursor: pointer;
+}
+
+.jp-Toolbar a.jp-AdvancedImageViewer-help-link:hover {
+  color: var(--jp-brand-color0);
+}
+
+.jp-AdvancedImageViewer-help {
+  max-width: 380px;
+}
+
+.jp-AdvancedImageViewer-help-section {
+  margin: 12px 0 0;
+  font-weight: 600;
+}
+
+.jp-AdvancedImageViewer-help ul {
+  margin: 8px 0 0;
+  padding-left: 18px;
+}
+
+.jp-AdvancedImageViewer-help li {
+  margin: 2px 0;
+}