@r74tech/docusaurus-plugin-panzoom 2.2.0 → 2.4.0

package/.prettierrc

@@ -0,0 +1,12 @@
+{
+  "semi": true,
+  "tabWidth": 2,
+  "printWidth": 120,
+  "singleQuote": true,
+  "trailingComma": "all",
+  "jsxSingleQuote": true,
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "endOfLine": "lf",
+  "proseWrap": "always"
+}

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [2.4.0](https://github.com/r74tech/docusaurus-plugin-panzoom/compare/v2.3.0...v2.4.0) (2025-07-19)
+
+
+### Features
+
+* add options to better control the zoom ([#7](https://github.com/r74tech/docusaurus-plugin-panzoom/issues/7)) ([4dc537c](https://github.com/r74tech/docusaurus-plugin-panzoom/commit/4dc537c8e059908cc2cae407fc78ae93de34c6dd))
+
+# [2.3.0](https://github.com/r74tech/docusaurus-plugin-panzoom/compare/v2.2.0...v2.3.0) (2025-07-17)
+
+
+### Features
+
+* add toolbar to control zooming (zoom in, zoom out, reset) ([a170e52](https://github.com/r74tech/docusaurus-plugin-panzoom/commit/a170e5253e2bf5b1ddb12bf7b0e648722b053bcb))
+* merge all toolbar props into a single object ([0c32e6c](https://github.com/r74tech/docusaurus-plugin-panzoom/commit/0c32e6c361563ad81517818c99693a9de717f33f))
+
 # [2.2.0](https://github.com/r74tech/docusaurus-plugin-panzoom/compare/v2.1.0...v2.2.0) (2025-07-12)
 
 

package/dist/PanZoom.d.ts

@@ -1,4 +1,5 @@
 import type { ClientModule } from '@docusaurus/types';
+import './styles/panzoom.css';
 /**
  * Client module implementation.  Wait a bit before trying this, some components like mermaid take a second to process / render
  */

package/dist/PanZoom.js

@@ -4,13 +4,113 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const panzoom_1 = __importDefault(require("@panzoom/panzoom"));
+const PanzoomPluginOptions_1 = require("./PanzoomPluginOptions");
+const zoom_in_1 = __importDefault(require("./img/zoom-in"));
+const zoom_out_1 = __importDefault(require("./img/zoom-out"));
+const zoom_reset_1 = __importDefault(require("./img/zoom-reset"));
+require("./styles/panzoom.css");
 const config = require('@generated/docusaurus.config').default;
 const { themeConfig } = config;
 const { zoom } = themeConfig;
-const { selectors = ['div.mermaid[data-processed="true"]', 'div.docusaurus-mermaid-container', '.drawio'], wrap = true, timeout = 1000, excludeClass = 'panzoom-exclude', ...panZoomConfig } = zoom;
+const { selectors = ['div.mermaid[data-processed="true"]', 'div.docusaurus-mermaid-container', '.drawio'], wrap = true, timeout = 1000, excludeClass = 'panzoom-exclude', toolbar: { enabled = false, position = PanzoomPluginOptions_1.PanZoomPluginToolbarPosition.TopRight, opacity = 0 } = {}, enableWheelZoom = true, enableWheelZoomWithShift = false, enableDoubleClickResetZoom = true, restrictZoomOutBeyondOrigin = false, ...panZoomConfig } = zoom;
+/**
+ * Creates a toolbar with zoom controls for a panzoom instance
+ *
+ * @param container The container element to append the toolbar to
+ * @param instance The panzoom instance to control
+ * @param position The position of the toolbar
+ */
+const createToolbar = (container, instance, position) => {
+    const toolbar = document.createElement('div');
+    toolbar.className = `panzoom-toolbar panzoom-toolbar-${position} ${excludeClass}`;
+    // Apply custom opacity from configuration
+    toolbar.style.opacity = opacity.toString();
+    // Prevent double-click events from bubbling up to the container
+    // By default the panzoom library will reset on double click
+    toolbar.addEventListener('dblclick', (e) => {
+        e.stopPropagation();
+    });
+    // Helper function to create toolbar buttons
+    const createButton = (svg, title, action) => {
+        const button = document.createElement('button');
+        button.innerHTML = svg;
+        button.title = title;
+        button.className = excludeClass;
+        button.addEventListener('click', (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            action();
+        });
+        return button;
+    };
+    // Create and append all buttons
+    const buttons = [
+        // Zoom in
+        createButton(zoom_in_1.default, 'Zoom in', () => {
+            instance.zoomIn();
+        }),
+        // Zoom out
+        createButton(zoom_out_1.default, 'Zoom out', () => {
+            if (!restrictZoomOutBeyondOrigin) {
+                instance.zoomOut();
+                return;
+            }
+            if (instance.getScale() > 1) {
+                instance.zoomOut();
+            }
+        }),
+        // Reset zoom
+        createButton(zoom_reset_1.default, 'Reset zoom', () => {
+            instance.reset();
+        }),
+    ];
+    buttons.forEach((button) => toolbar.appendChild(button));
+    container.appendChild(toolbar);
+};
+/**
+ * Attach event listeners to the element where panzoom is applied.
+ * The listeners to add are based on the configuration options provided.
+ *
+ * @param element The element to add event listeners to
+ * @param instance The panzoom instance to control
+ */
+const addEventListeners = (element, instance) => {
+    const handleZoomWithWheel = (event) => {
+        if (restrictZoomOutBeyondOrigin) {
+            // Allow zooming in or zooming out only to the original size
+            if (event.deltaY < 0 || (event.deltaY > 0 && instance.getScale() > 1)) {
+                instance.zoomWithWheel(event);
+            }
+        }
+        else {
+            instance.zoomWithWheel(event);
+        }
+    };
+    // Handle the wheel zoom functionality if at least one of the options is enabled
+    if (enableWheelZoom || enableWheelZoomWithShift) {
+        element.addEventListener('wheel', (event) => {
+            // Handle zoom with shift key
+            if (enableWheelZoomWithShift && event.shiftKey) {
+                handleZoomWithWheel(event);
+                return;
+            }
+            // Handle regular zoom
+            if (enableWheelZoom && !event.shiftKey) {
+                handleZoomWithWheel(event);
+            }
+        });
+    }
+    // Handle double-click reset zoom
+    if (enableDoubleClickResetZoom) {
+        element.addEventListener('dblclick', () => {
+            instance.reset();
+        });
+    }
+};
 /**
  * Main work method to zoom the set of elements.  You can pass in global options to the pan zoom component
  * as well as control whether the items will be wrapped.
+ *
  * @param selectors
  */
 const zoomElements = (selectors) => {
@@ -20,25 +120,23 @@ const zoomElements = (selectors) => {
     });
     foundElements.forEach((element) => {
         const instance = (0, panzoom_1.default)(element, { excludeClass, ...panZoomConfig });
+        let container;
         if (wrap) {
             const wrapper = document.createElement('div');
-            wrapper.setAttribute('style', "overflow: hidden");
+            wrapper.setAttribute('style', 'overflow: hidden; position: relative;');
             element.parentElement?.insertBefore(wrapper, element);
             wrapper.appendChild(element);
-            wrapper.addEventListener('wheel', (event) => {
-                instance.zoomWithWheel(event);
-            });
-            wrapper.addEventListener('dblclick', (event) => {
-                instance.reset();
-            });
+            container = wrapper;
         }
-        if (!wrap) {
-            element.addEventListener('wheel', (event) => {
-                instance.zoomWithWheel(event);
-            });
-            element.addEventListener('dblclick', (event) => {
-                instance.reset();
-            });
+        else {
+            const htmlElement = element;
+            htmlElement.style.position = 'relative';
+            container = htmlElement;
+        }
+        addEventListeners(container, instance);
+        // Add toolbar if enabled
+        if (enabled) {
+            createToolbar(container, instance, position);
         }
     });
 };

package/dist/PanZoomPlugin.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validatedThemeConfig = exports.PanZoomPlugin = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
+const PanzoomPluginOptions_1 = require("./PanzoomPluginOptions");
 const path_1 = require("path");
 /**
  * Main module for the PanZoom plugin
@@ -11,15 +12,15 @@ const path_1 = require("path");
  */
 const PanZoomPlugin = (context, options) => {
     return {
-        name: "docusaurus-plugin-panzoom",
+        name: 'docusaurus-plugin-panzoom',
         getClientModules() {
-            return [
-                (0, path_1.resolve)(__dirname, "./PanZoom")
-            ];
-        }
+            return [(0, path_1.resolve)(__dirname, './PanZoom'), (0, path_1.resolve)(__dirname, './styles/panzoom.css')];
+        },
     };
 };
 exports.PanZoomPlugin = PanZoomPlugin;
+// Extract the valid toolbar position values from the enum
+const validToolbarPositions = Object.values(PanzoomPluginOptions_1.PanZoomPluginToolbarPosition);
 /**
  * Theme validation rules for this plugin
  */
@@ -29,7 +30,12 @@ const panZoomValidator = utils_validation_1.Joi.object({
         wrap: utils_validation_1.Joi.boolean(),
         timeout: utils_validation_1.Joi.number(),
         excludeClass: utils_validation_1.Joi.string(),
-    })
+        toolbar: utils_validation_1.Joi.object({
+            enabled: utils_validation_1.Joi.boolean(),
+            position: utils_validation_1.Joi.string().valid(...validToolbarPositions),
+            opacity: utils_validation_1.Joi.number().min(0).max(1),
+        }),
+    }),
 });
 /**
  * Add a validation for the theme configuration

package/dist/PanzoomPluginOptions.d.ts

@@ -1,4 +1,10 @@
 import type { PanzoomOptions } from '@panzoom/panzoom';
+export declare enum PanZoomPluginToolbarPosition {
+    TopRight = "top-right",
+    TopLeft = "top-left",
+    BottomRight = "bottom-right",
+    BottomLeft = "bottom-left"
+}
 export type PanZoomPluginOptions = PanzoomOptions & {
     /**
      * A list of selectors to look for elements to enable pan and zoom
@@ -28,4 +34,60 @@ export type PanZoomPluginOptions = PanzoomOptions & {
      * default: 'panzoom-exclude'
      */
     excludeClass?: string;
+    /**
+     * Toolbar options for the Panzoom plugin.
+     */
+    toolbar?: {
+        /**
+         * Whether to enable and show a control toolbar with buttons for zoom in, zoom out, and reset.
+         *
+         * default: false
+         */
+        enabled?: boolean;
+        /**
+         * The toolbar position (top-right, top-left, bottom-right, bottom-left)
+         *
+         * default: 'top-right'
+         */
+        position?: PanZoomPluginToolbarPosition;
+        /**
+         * The toolbar opacity when not hovered (value between 0 and 1)
+         * The toolbar will become fully opaque (opacity: 1) when hovered.
+         *
+         * example: 0.5
+         * default: 0
+         */
+        opacity?: number;
+    };
+    /**
+     * Whether to enable zooming with the mouse wheel.
+     * If true, the user can zoom in and out using the mouse wheel.
+     *
+     * default: true
+     */
+    enableWheelZoom?: boolean;
+    /**
+     * Whether to enable zooming with the mouse wheel while holding the shift key.
+     * If true, the user can zoom in and out using the mouse wheel while holding the shift key.
+     *
+     * This option is independent of `enableWheelZoom`. Meaning, even if `enableWheelZoom` is false,
+     * and `enableWheelZoomWithShift` is true, the user can still zoom using shift + mouse whee.
+     * Also, `enableWheelZoom` and `enableWheelZoomWithShift` can be used together.
+     *
+     * default: false
+     */
+    enableWheelZoomWithShift?: boolean;
+    /**
+     * Whether to enable double-click to reset zoom.
+     * If true, double-clicking on the panzoom element will reset the zoom level.
+     *
+     * default: true
+     */
+    enableDoubleClickResetZoom?: boolean;
+    /**
+     * Whether to restrict zooming out beyond the original size of the element.
+     *
+     * default: false
+     */
+    restrictZoomOutBeyondOrigin?: boolean;
 };

package/dist/PanzoomPluginOptions.js

@@ -1,2 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.PanZoomPluginToolbarPosition = void 0;
+var PanZoomPluginToolbarPosition;
+(function (PanZoomPluginToolbarPosition) {
+    PanZoomPluginToolbarPosition["TopRight"] = "top-right";
+    PanZoomPluginToolbarPosition["TopLeft"] = "top-left";
+    PanZoomPluginToolbarPosition["BottomRight"] = "bottom-right";
+    PanZoomPluginToolbarPosition["BottomLeft"] = "bottom-left";
+})(PanZoomPluginToolbarPosition = exports.PanZoomPluginToolbarPosition || (exports.PanZoomPluginToolbarPosition = {}));

package/dist/img/zoom-in.d.ts

@@ -0,0 +1,2 @@
+declare const _default: "<svg xmlns=\"http://www.w3.org/2000/svg\" height=\"24px\" viewBox=\"0 -960 960 960\" width=\"24px\" fill=\"#000\"><path d=\"M450-450H220v-60h230v-230h60v230h230v60H510v230h-60v-230Z\"/></svg>";
+export default _default;

package/dist/img/zoom-in.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#000"><path d="M450-450H220v-60h230v-230h60v230h230v60H510v230h-60v-230Z"/></svg>';

package/dist/img/zoom-out.d.ts

@@ -0,0 +1,2 @@
+declare const _default: "<svg xmlns=\"http://www.w3.org/2000/svg\" height=\"24px\" viewBox=\"0 -960 960 960\" width=\"24px\" fill=\"#000\"><path d=\"M220-450v-60h520v60H220Z\"/></svg>";
+export default _default;

package/dist/img/zoom-out.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#000"><path d="M220-450v-60h520v60H220Z"/></svg>';

package/dist/img/zoom-reset.d.ts

@@ -0,0 +1,2 @@
+declare const _default: "<svg xmlns=\"http://www.w3.org/2000/svg\" height=\"24px\" viewBox=\"0 -960 960 960\" width=\"24px\" fill=\"#000\"><path d=\"M480-333.85v-91.92q0-22.6 15.82-38.41Q511.63-480 534.23-480h91.92v47.69h-98.46v98.46H480ZM534.23-100q-22.6 0-38.41-15.82Q480-131.64 480-154.23v-91.92h47.69v98.46h98.46V-100h-91.92Zm278.08-233.85v-98.46h-98.46V-480h91.92q22.59 0 38.41 15.82Q860-448.37 860-425.77v91.92h-47.69ZM713.85-100v-47.69h98.46v-98.46H860v91.92q0 22.59-15.82 38.41Q828.36-100 805.77-100h-91.92Zm94.07-467.69h-62.23q-27.54-84.54-99.57-138.43Q574.08-760 480-760q-117 0-198.5 81.5T200-480q0 78.15 38.46 141.81 38.46 63.65 101.54 99.34V-360h60v220H180v-60h113.23q-69.3-45-111.27-118.27Q140-391.54 140-480q0-70.8 26.77-132.63t72.77-107.83q46-46 107.83-72.77Q409.2-820 480-820q118.61 0 208.81 71.42Q779-677.15 807.92-567.69Z\"/></svg>";
+export default _default;

package/dist/img/zoom-reset.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = '<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#000"><path d="M480-333.85v-91.92q0-22.6 15.82-38.41Q511.63-480 534.23-480h91.92v47.69h-98.46v98.46H480ZM534.23-100q-22.6 0-38.41-15.82Q480-131.64 480-154.23v-91.92h47.69v98.46h98.46V-100h-91.92Zm278.08-233.85v-98.46h-98.46V-480h91.92q22.59 0 38.41 15.82Q860-448.37 860-425.77v91.92h-47.69ZM713.85-100v-47.69h98.46v-98.46H860v91.92q0 22.59-15.82 38.41Q828.36-100 805.77-100h-91.92Zm94.07-467.69h-62.23q-27.54-84.54-99.57-138.43Q574.08-760 480-760q-117 0-198.5 81.5T200-480q0 78.15 38.46 141.81 38.46 63.65 101.54 99.34V-360h60v220H180v-60h113.23q-69.3-45-111.27-118.27Q140-391.54 140-480q0-70.8 26.77-132.63t72.77-107.83q46-46 107.83-72.77Q409.2-820 480-820q118.61 0 208.81 71.42Q779-677.15 807.92-567.69Z"/></svg>';

package/dist/styles/panzoom.css

@@ -0,0 +1,48 @@
+.panzoom-toolbar {
+  position: absolute;
+  z-index: 10;
+  display: flex;
+  gap: 5px;
+  padding: 5px;
+  background: rgba(255, 255, 255, 0.5);
+  border-radius: 4px;
+  transition: opacity 0.2s ease-in-out;
+}
+
+*:hover > .panzoom-toolbar {
+  opacity: 1 !important;
+}
+
+.panzoom-toolbar-top-right {
+  top: 10px;
+  right: 10px;
+}
+
+.panzoom-toolbar-top-left {
+  top: 10px;
+  left: 10px;
+}
+
+.panzoom-toolbar-bottom-right {
+  bottom: 10px;
+  right: 10px;
+}
+
+.panzoom-toolbar-bottom-left {
+  bottom: 10px;
+  left: 10px;
+}
+
+.panzoom-toolbar button {
+  width: 30px;
+  height: 30px;
+  cursor: pointer;
+  border: 1px solid #ddd;
+  border-radius: 3px;
+  background-color: #fff;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}

package/eslint.config.mjs

@@ -0,0 +1,32 @@
+import js from '@eslint/js';
+import tsParser from '@typescript-eslint/parser';
+import tseslint from '@typescript-eslint/eslint-plugin';
+import globals from 'globals';
+import prettierPlugin from 'eslint-plugin-prettier';
+
+export default [
+  {
+    files: ['src/**/*.{ts,css}'],
+    ignores: ['**/dist/**', '**/node_modules/**'],
+    languageOptions: {
+      ecmaVersion: 2020,
+      sourceType: 'module',
+      globals: {
+        ...globals.node,
+        ...globals.browser,
+      },
+      parser: tsParser,
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+      prettier: prettierPlugin,
+    },
+    rules: {
+      ...js.configs.recommended.rules,
+      ...tseslint.configs.recommended.rules,
+      'prettier/prettier': 'error',
+      '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+      '@typescript-eslint/explicit-module-boundary-types': 'off',
+    },
+  },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@r74tech/docusaurus-plugin-panzoom",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "A plugin to enable the panzoom component on SVG and other elements",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -15,8 +15,12 @@
   "author": "r74tech",
   "license": "MIT",
   "scripts": {
-    "build": "tsc",
-    "prepublishOnly": "npm run build"
+    "build": "tsc && npm run copy-assets",
+    "copy-assets": "mkdir -p dist/styles && cp -r src/styles/* dist/styles/",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint 'src/**/*.{ts,css}' --report-unused-disable-directives --max-warnings 0",
+    "lint:fix": "eslint --fix 'src/**/*.{ts,css}'",
+    "format": "prettier --write --no-error-on-unmatched-pattern 'src/**/*.{ts,css}' --config ./.prettierrc"
   },
   "dependencies": {
     "@docusaurus/utils-validation": "^3.7.0",
@@ -24,6 +28,8 @@
   },
   "devDependencies": {
     "@docusaurus/types": "^3.7.0",
+    "@eslint/compat": "^1.2.3",
+    "@eslint/js": "^9.14.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/commit-analyzer": "^9.0.2",
     "@semantic-release/git": "^10.0.1",
@@ -32,10 +38,19 @@
     "@semantic-release/release-notes-generator": "^10.0.3",
     "@tsconfig/docusaurus": "^1.0.7",
     "@types/node": "^22.14.0",
+    "@typescript-eslint/eslint-plugin": "^8.36.0",
+    "@typescript-eslint/parser": "^8.13.0",
+    "eslint": "^9.14.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.5.1",
+    "globals": "^15.12.0",
+    "lint-staged": "^15.2.10",
+    "prettier": "^3.3.3",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "semantic-release": "^24.2.3",
-    "typescript": "^4.9.5"
+    "typescript": "^4.9.5",
+    "typescript-eslint": "^8.13.0"
   },
   "release": {
     "plugins": [
@@ -79,5 +94,10 @@
     "type": "git",
     "url": "git+https://github.com/r74tech/docusaurus-plugin-panzoom.git"
   },
-  "sideEffects": false
+  "sideEffects": false,
+  "lint-staged": {
+    "src/**/*.{ts,css}": [
+      "prettier --write --no-error-on-unmatched-pattern --config ./.prettierrc"
+    ]
+  }
 }