@bpmn-io/diagram-js-canvas-lock 0.1.0

package/README.md

@@ -0,0 +1,141 @@
+# diagram-js-canvas-lock
+
+[![CI](https://github.com/bpmn-io/diagram-js-canvas-lock/actions/workflows/CI.yml/badge.svg)](https://github.com/bpmn-io/diagram-js-canvas-lock/actions/workflows/CI.yml)
+
+This module extends [diagram-js](https://github.com/bpmn-io/diagram-js)-based editors with a canvas lock feature.
+
+## Features
+
+* lock and unlock canvas programmatically
+
+## Installation
+
+Install via npm:
+
+```sh
+npm install @bpmn-io/diagram-js-canvas-lock
+```
+
+## Usage
+
+Use as an extension for [bpmn-js](https://github.com/bpmn-io/bpmn-js):
+
+```javascript
+import CanvasLockModule from '@bpmn-io/diagram-js-canvas-lock';
+
+const modeler = new BpmnModeler({
+  additionalModules: [
+    CanvasLockModule
+  ]
+});
+```
+
+Lock and unlock the canvas through the `canvasLock` service:
+
+```javascript
+const canvasLock = modeler.get('canvasLock');
+
+canvasLock.lock();
+
+canvasLock.isLocked(); // true
+
+canvasLock.unlock();
+```
+
+## Integrating with diagram-js-canvas-lock
+
+By design, this module has no knowledge of the other diagram-js plugins running
+alongside it. Instead it exposes a small, stable contract that any plugin can
+integrate with. If your plugin adds interactive UI (pads, overlays, menus, ...),
+respect the lock through one or more of the following.
+
+### 1. Query the lock state (pull)
+
+Guard your own entry points with `canvasLock.isLocked()`:
+
+```javascript
+MyPad.prototype.canOpen = function(target) {
+  if (this._canvasLock.isLocked()) {
+    return false;
+  }
+
+  // ...
+};
+```
+
+`canvasLock` is an optional dependency – resolve it via the injector so your
+plugin keeps working in editors without canvas lock:
+
+```javascript
+function MyPad(injector) {
+  this._canvasLock = injector.get('canvasLock', false);
+}
+
+MyPad.prototype.isLocked = function() {
+  return this._canvasLock && this._canvasLock.isLocked();
+};
+
+MyPad.$inject = [ 'injector' ];
+```
+
+### 2. React to lock changes (push)
+
+Subscribe to the `canvasLock.changed` event to tear down or restore UI when the
+lock is toggled:
+
+```javascript
+eventBus.on('canvasLock.changed', function(event) {
+  if (event.locked) {
+    myPad.close();
+  }
+});
+```
+
+### 3. Make an interaction vetoable (`*.allowed` convention)
+
+Following the diagram-js convention, fire an `<x>.allowed` event before opening
+and bail if any listener returns `false`. Canvas lock (and other features) can
+then veto the interaction without knowing about your plugin:
+
+```javascript
+MyPad.prototype.open = function(target) {
+  if (this._eventBus.fire('myPad.open.allowed', { target: target }) === false) {
+    return;
+  }
+
+  // ...
+};
+```
+
+### 4. Style locked state (CSS hook)
+
+While locked, the canvas container carries the `djs-canvas-locked` class. Use it
+to hide or dim plugin UI purely visually:
+
+```css
+.djs-canvas-locked .my-pad {
+  display: none;
+}
+```
+
+### Public contract summary
+
+| Surface | Type | Description |
+| --- | --- | --- |
+| `canvasLock.lock()` / `unlock()` | API | Toggle the lock. |
+| `canvasLock.isLocked()` | API | Query the current lock state. |
+| `canvasLock.changed` | Event | Fired with `{ locked }` whenever the lock toggles. |
+| `djs-canvas-locked` | CSS class | Added to the canvas container while locked. |
+
+## Development
+
+```sh
+npm install
+
+npm start
+```
+
+
+## License
+
+MIT

package/assets/canvas-lock.css

@@ -0,0 +1,31 @@
+.djs-canvas-locked {
+  user-select: none;
+}
+
+.djs-canvas-locked .djs-connection.selected .djs-outline {
+  display: initial;
+}
+
+.djs-canvas-locked .djs-palette .entry {
+  opacity: 0.4;
+  pointer-events: none;
+}
+
+.djs-canvas-locked .djs-palette .djs-palette-toggle {
+  pointer-events: none;
+}
+
+.djs-canvas-locked .djs-element .djs-hit-stroke,
+.djs-canvas-locked .djs-element .djs-hit-click-stroke,
+.djs-canvas-locked .djs-element .djs-hit-all {
+  cursor: unset;
+}
+
+.djs-canvas-locked .djs-resizer {
+  display: none;
+}
+
+.djs-canvas-locked .djs-segment-dragger,
+.djs-canvas-locked .djs-bendpoint {
+  display: none !important;
+}

package/lib/CanvasLock.js

@@ -0,0 +1,62 @@
+/**
+ * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
+ * @typedef {import('diagram-js/lib/core/Canvas').default} Canvas
+ */
+
+/**
+ * A service that allows to temporarily lock user interactions
+ * while still allowing programmatic changes via modeling APIs.
+ *
+ * Pan/zoom (navigation) remains enabled even while locked.
+ *
+ * @param {EventBus} eventBus
+ * @param {Canvas} canvas
+ */
+export default function CanvasLock(eventBus, canvas) {
+  this._eventBus = eventBus;
+  this._canvas = canvas;
+  this._locked = false;
+}
+
+CanvasLock.$inject = [ 'eventBus', 'canvas' ];
+
+/**
+ * Lock user interactions.
+ */
+CanvasLock.prototype.lock = function() {
+  if (this._locked) {
+    return;
+  }
+
+  this._locked = true;
+
+  var container = this._canvas.getContainer();
+  container.classList.add('djs-canvas-locked');
+
+  this._eventBus.fire('canvasLock.changed', { locked: true });
+};
+
+/**
+ * Unlock user interactions.
+ */
+CanvasLock.prototype.unlock = function() {
+  if (!this._locked) {
+    return;
+  }
+
+  this._locked = false;
+
+  var container = this._canvas.getContainer();
+  container.classList.remove('djs-canvas-locked');
+
+  this._eventBus.fire('canvasLock.changed', { locked: false });
+};
+
+/**
+ * Check whether interactions are currently locked.
+ *
+ * @return {boolean}
+ */
+CanvasLock.prototype.isLocked = function() {
+  return this._locked;
+};

package/lib/CanvasLockBehavior.js

@@ -0,0 +1,108 @@
+/**
+ * @typedef {import('diagram-js/lib/core/EventBus').default} EventBus
+ * @typedef {import('./CanvasLock').default} CanvasLock
+ * @typedef {import('didi').Injector} Injector
+ */
+
+var VERY_HIGH_PRIORITY = 10000;
+
+/**
+ * Blocked interaction events.
+ *
+ * These are events that initiate user-driven interactions
+ * but should be suppressed when the canvas lock is active.
+ */
+var BLOCKED_EVENTS = [
+
+  // block any user-initiated drag, including move, create, connect, etc.
+  'drag.init',
+
+  // block any user-initiated open of context pad or popup menu
+  'contextPad.open.allowed',
+  'popupMenu.open.allowed',
+
+  // block direct editing activation
+  'directEditing.activate.allowed'
+];
+
+/**
+ * Editor actions that are allowed while locked
+ * because they only affect navigation, not diagram content.
+ */
+var ALLOWED_EDITOR_ACTIONS = [
+  'stepZoom',
+  'zoom',
+  'moveCanvas'
+];
+
+
+/**
+ * A behavior that blocks user-initiated interaction events
+ * when the canvas lock is active.
+ *
+ * Navigation events (canvas.move, canvas.zoom) are explicitly
+ * not blocked to allow pan/zoom while locked. Keyboard-triggered
+ * navigation editor actions (stepZoom, zoom, moveCanvas) are also
+ * allowed through.
+ *
+ * @param {EventBus} eventBus
+ * @param {CanvasLock} canvasLock
+ * @param {Injector} injector
+ */
+export default function CanvasLockBehavior(eventBus, canvasLock, injector) {
+
+  BLOCKED_EVENTS.forEach(function(event) {
+    eventBus.on(event, VERY_HIGH_PRIORITY, function(e) {
+      if (canvasLock.isLocked()) {
+        return false;
+      }
+    });
+  });
+
+  // block non-navigation editor actions when locked
+  eventBus.on('editorActions.allowed', VERY_HIGH_PRIORITY, function(event) {
+    if (canvasLock.isLocked() && !ALLOWED_EDITOR_ACTIONS.includes(event.action)) {
+      return false;
+    }
+  });
+
+  // close open overlays when locking; restore context pad on unlock
+  eventBus.on('canvasLock.changed', function(event) {
+    var contextPad = injector.get('contextPad', false);
+    var directEditing = injector.get('directEditing', false);
+    var dragging = injector.get('dragging', false);
+    var popupMenu = injector.get('popupMenu', false);
+
+    if (event.locked) {
+      if (contextPad && contextPad.isOpen()) {
+        contextPad.close();
+      }
+
+      if (directEditing && directEditing.isActive()) {
+        directEditing.cancel();
+      }
+
+      if (dragging && dragging.context()) {
+        dragging.cancel();
+      }
+
+      if (popupMenu && popupMenu.isOpen()) {
+        popupMenu.close();
+      }
+    } else {
+
+      // restore context pad for current selection
+      var selection = injector.get('selection', false);
+
+      if (contextPad && selection) {
+        var selectedElements = selection.get();
+
+        if (selectedElements.length) {
+          contextPad.open(selectedElements.length === 1 ? selectedElements[0] : selectedElements);
+        }
+      }
+    }
+  });
+}
+
+CanvasLockBehavior.$inject = [ 'eventBus', 'canvasLock', 'injector' ];

package/lib/index.js

@@ -0,0 +1,11 @@
+import CanvasLock from './CanvasLock.js';
+import CanvasLockBehavior from './CanvasLockBehavior.js';
+
+/**
+ * @type { import('didi').ModuleDeclaration }
+ */
+export default {
+  __init__: [ 'canvasLock', 'canvasLockBehavior' ],
+  canvasLock: [ 'type', CanvasLock ],
+  canvasLockBehavior: [ 'type', CanvasLockBehavior ]
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@bpmn-io/diagram-js-canvas-lock",
+  "version": "0.1.0",
+  "description": "A diagram-js plugin for locking the canvas",
+  "main": "lib/index.js",
+  "module": "lib/index.js",
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js",
+    "./lib/*": "./lib/*",
+    "./assets/*": "./assets/*",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "all": "run-s lint test",
+    "test": "karma start karma.config.cjs",
+    "lint": "eslint .",
+    "dev": "npm test -- --auto-watch --no-single-run",
+    "start": "cross-env SINGLE_START=modeler npm run dev"
+  },
+  "keywords": [
+    "diagram-js",
+    "canvas",
+    "lock"
+  ],
+  "author": "Philipp Fromme <philipp.fromme@camunda.com>",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "assets",
+    "lib"
+  ],
+  "peerDependencies": {
+    "diagram-js": ">= 15.16.0",
+    "diagram-js-direct-editing": ">= 3.4.0"
+  },
+  "peerDependenciesMeta": {
+    "diagram-js-direct-editing": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "babel-loader": "^10.1.1",
+    "babel-plugin-istanbul": "^8.0.0",
+    "bpmn-js": "^18.19.0",
+    "chai": "^6.2.2",
+    "cross-env": "^10.1.0",
+    "eslint": "^9.39.4",
+    "eslint-plugin-bpmn-io": "^2.2.0",
+    "karma": "^6.4.4",
+    "karma-chrome-launcher-2": "^3.3.0",
+    "karma-coverage": "^2.2.1",
+    "karma-debug-launcher": "^0.0.5",
+    "karma-env-preprocessor": "^0.1.1",
+    "karma-mocha": "^2.0.1",
+    "karma-tldr-reporter": "^1.0.0",
+    "karma-webpack": "^5.0.1",
+    "mocha": "^11.7.5",
+    "mocha-test-container-support": "^0.2.0",
+    "npm-run-all2": "^9.0.2",
+    "sinon": "^22.0.0",
+    "sinon-chai": "^4.0.1",
+    "webpack": "^5.106.2"
+  }
+}