[sigma] Adds more camera control settings

This commit fixes #1267.

Details:
- Adds camera.enableZooming and camera.enablePanning flags
- Adds camera.clean optional function, that is used as a middleware on
  camera states
- Adds new settings enableCameraZooming, enableCameraPanning and
  cameraPanBoundaries
- Adds new story on camera controls

Author: jacomyal

packages/sigma/src/core/camera.ts

@@ -31,7 +31,10 @@ export default class Camera extends TypedEventEmitter<CameraEvents> implements C
 
   minRatio: number | null = null;
   maxRatio: number | null = null;
+  enabledZooming = true;
+  enabledPanning = true;
   enabledRotation = true;
+  clean: ((state: CameraState) => CameraState) | null = null;
 
   private nextFrame: number | null = null;
   private previousState: CameraState | null = null;
@@ -120,11 +123,12 @@ export default class Camera extends TypedEventEmitter<CameraEvents> implements C
    */
   validateState(state: Partial<CameraState>): Partial<CameraState> {
     const validatedState: Partial<CameraState> = {};
-    if (typeof state.x === "number") validatedState.x = state.x;
-    if (typeof state.y === "number") validatedState.y = state.y;
+    if (this.enabledPanning && typeof state.x === "number") validatedState.x = state.x;
+    if (this.enabledPanning && typeof state.y === "number") validatedState.y = state.y;
+    if (this.enabledZooming && typeof state.ratio === "number")
+      validatedState.ratio = this.getBoundedRatio(state.ratio);
     if (this.enabledRotation && typeof state.angle === "number") validatedState.angle = state.angle;
-    if (typeof state.ratio === "number") validatedState.ratio = this.getBoundedRatio(state.ratio);
-    return validatedState;
+    return this.clean ? this.clean({ ...this.getState(), ...validatedState }) : validatedState;
   }
 
   /**
@@ -146,8 +150,8 @@ export default class Camera extends TypedEventEmitter<CameraEvents> implements C
     const validState = this.validateState(state);
     if (typeof validState.x === "number") this.x = validState.x;
     if (typeof validState.y === "number") this.y = validState.y;
-    if (this.enabledRotation && typeof validState.angle === "number") this.angle = validState.angle;
     if (typeof validState.ratio === "number") this.ratio = validState.ratio;
+    if (typeof validState.angle === "number") this.angle = validState.angle;
 
     // Emitting
     if (!this.hasState(this.previousState)) this.emit("updated", this.getState());

packages/sigma/src/settings.ts

@@ -20,7 +20,7 @@ import {
   drawDiscNodeLabel,
   drawStraightEdgeLabel,
 } from "./rendering";
-import { EdgeDisplayData, NodeDisplayData } from "./types";
+import { AtLeastOne, EdgeDisplayData, NodeDisplayData } from "./types";
 import { assign } from "./utils";
 
 /**
@@ -38,6 +38,7 @@ export interface Settings<
   renderLabels: boolean;
   renderEdgeLabels: boolean;
   enableEdgeEvents: boolean;
+
   // Component rendering
   defaultNodeColor: string;
   defaultNodeType: string;
@@ -89,7 +90,13 @@ export interface Settings<
   zIndex: boolean;
   minCameraRatio: null | number;
   maxCameraRatio: null | number;
+  enableCameraZooming: boolean;
+  enableCameraPanning: boolean;
   enableCameraRotation: boolean;
+  cameraPanBoundaries:
+    | null
+    | true
+    | AtLeastOne<{ tolerance: number; boundaries: { x: [number, number]; y: [number, number] } }>;
 
   // Lifecycle
   allowInvalidContainer: boolean;
@@ -159,7 +166,10 @@ export const DEFAULT_SETTINGS: Settings<Attributes, Attributes, Attributes> = {
   zIndex: false,
   minCameraRatio: null,
   maxCameraRatio: null,
+  enableCameraZooming: true,
+  enableCameraPanning: true,
   enableCameraRotation: true,
+  cameraPanBoundaries: null,
 
   // Lifecycle
   allowInvalidContainer: false,
@@ -201,7 +211,7 @@ export function resolveSettings<
   E extends Attributes = Attributes,
   G extends Attributes = Attributes,
 >(settings: Partial<Settings<N, E, G>>): Settings<N, E, G> {
-  const resolvedSettings = assign({}, DEFAULT_SETTINGS, settings);
+  const resolvedSettings = assign({}, DEFAULT_SETTINGS as Settings<N, E, G>, settings);
 
   resolvedSettings.nodeProgramClasses = assign({}, DEFAULT_NODE_PROGRAM_CLASSES, resolvedSettings.nodeProgramClasses);
   resolvedSettings.edgeProgramClasses = assign({}, DEFAULT_EDGE_PROGRAM_CLASSES, resolvedSettings.edgeProgramClasses);

packages/sigma/src/sigma.ts

@@ -878,7 +878,20 @@ export default class Sigma<
 
     this.camera.minRatio = settings.minCameraRatio;
     this.camera.maxRatio = settings.maxCameraRatio;
+    this.camera.enabledZooming = settings.enableCameraZooming;
+    this.camera.enabledPanning = settings.enableCameraPanning;
     this.camera.enabledRotation = settings.enableCameraRotation;
+    if (settings.cameraPanBoundaries) {
+      this.camera.clean = (state) =>
+        this.cleanCameraState(
+          state,
+          settings.cameraPanBoundaries && typeof settings.cameraPanBoundaries === "object"
+            ? settings.cameraPanBoundaries
+            : {},
+        );
+    } else {
+      this.camera.clean = null;
+    }
     this.camera.setState(this.camera.validateState(this.camera.getState()));
 
     if (oldSettings) {
@@ -920,6 +933,73 @@ export default class Sigma<
     return this;
   }
 
+  private cleanCameraState(
+    state: CameraState,
+    { tolerance = 0, boundaries }: { tolerance?: number; boundaries?: Record<"x" | "y", [number, number]> } = {},
+  ): CameraState {
+    const newState = { ...state };
+
+    // Extract necessary properties
+    const {
+      x: [xMinGraph, xMaxGraph],
+      y: [yMinGraph, yMaxGraph],
+    } = boundaries || this.nodeExtent;
+
+    // Transform the four corners of the graph rectangle using the provided camera state
+    const corners = [
+      this.graphToViewport({ x: xMinGraph, y: yMinGraph }, { cameraState: state }),
+      this.graphToViewport({ x: xMaxGraph, y: yMinGraph }, { cameraState: state }),
+      this.graphToViewport({ x: xMinGraph, y: yMaxGraph }, { cameraState: state }),
+      this.graphToViewport({ x: xMaxGraph, y: yMaxGraph }, { cameraState: state }),
+    ];
+
+    // Look for new extents, based on these four corners
+    let xMin = Infinity,
+      xMax = -Infinity,
+      yMin = Infinity,
+      yMax = -Infinity;
+    corners.forEach(({ x, y }) => {
+      xMin = Math.min(xMin, x);
+      xMax = Math.max(xMax, x);
+      yMin = Math.min(yMin, y);
+      yMax = Math.max(yMax, y);
+    });
+
+    // For each dimension, constraint the smaller element (camera or graph) to fit in the larger one:
+    const graphWidth = xMax - xMin;
+    const graphHeight = yMax - yMin;
+    const { width, height } = this.getDimensions();
+    let dx = 0;
+    let dy = 0;
+
+    if (graphWidth >= width) {
+      if (xMax < width - tolerance) dx = xMax - (width - tolerance);
+      else if (xMin > tolerance) dx = xMin - tolerance;
+    } else {
+      if (xMax > width + tolerance) dx = xMax - (width + tolerance);
+      else if (xMin < -tolerance) dx = xMin + tolerance;
+    }
+    if (graphHeight >= height) {
+      if (yMax < height - tolerance) dy = yMax - (height - tolerance);
+      else if (yMin > tolerance) dy = yMin - tolerance;
+    } else {
+      if (yMax > height + tolerance) dy = yMax - (height + tolerance);
+      else if (yMin < -tolerance) dy = yMin + tolerance;
+    }
+
+    if (dx || dy) {
+      // Transform [dx, dy] from viewport to graph (using two different point to transform that vector):
+      const origin = this.viewportToFramedGraph({ x: 0, y: 0 }, { cameraState: state });
+      const delta = this.viewportToFramedGraph({ x: dx, y: dy }, { cameraState: state });
+      dx = delta.x - origin.x;
+      dy = delta.y - origin.y;
+      newState.x += dx;
+      newState.y += dy;
+    }
+
+    return newState;
+  }
+
   /**
    * Method used to render labels.
    *
@@ -1575,6 +1655,7 @@ export default class Sigma<
    * Function used to create a canvas context and add the relevant DOM elements.
    *
    * @param  {string} id - Context's id.
+   * @param  options
    * @return {Sigma}
    */
   createCanvasContext(id: string, options: { style?: Partial<CSSStyleDeclaration> } = {}): this {
@@ -1875,6 +1956,21 @@ export default class Sigma<
     return this;
   }
 
+  /**
+   * Method setting multiple settings at once.
+   *
+   * @param  {Partial<Settings>} settings - The settings to set.
+   * @return {Sigma}
+   */
+  setSettings(settings: Partial<Settings<N, E, G>>): this {
+    const oldValues = { ...this.settings };
+    this.settings = { ...this.settings, ...settings };
+    validateSettings(this.settings);
+    this.handleSettingsUpdate(oldValues);
+    this.scheduleRefresh();
+    return this;
+  }
+
   /**
    * Method used to resize the renderer.
    *

packages/sigma/src/types.ts

@@ -21,6 +21,11 @@ export type PlainObject<T = any> = { [k: string]: T };
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type PartialButFor<T, K extends keyof T> = Pick<T, K> & Partial<Omit<T, K>> & { [others: string]: any };
 
+/**
+ * Returns a type similar to Partial<T>, but with at least one key set.
+ */
+export type AtLeastOne<T, U = { [K in keyof T]: Pick<T, K> }> = Partial<T> & U[keyof U];
+
 export type NonEmptyArray<T> = [T, ...T[]];
 
 export interface Coordinates {

packages/storybook/stories/1-core-features/7-camera-control/index.html

@@ -0,0 +1,84 @@
+<style>
+  html,
+  body,
+  #storybook-root,
+  #sigma-container {
+    width: 100%;
+    height: 100%;
+    margin: 0 !important;
+    padding: 0 !important;
+    overflow: hidden;
+    font-family: sans-serif;
+  }
+  #controls {
+    position: absolute;
+    top: 10px;
+    right: 10px;
+    background: #ffffffcc;
+    padding: 10px;
+  }
+
+  input[type="number"] {
+    width: 5em;
+  }
+  h4 {
+    margin: 0;
+  }
+  fieldset {
+    border: none;
+  }
+  h4,
+  fieldset > div {
+    margin-bottom: 0.2em;
+  }
+  button {
+    margin-right: 0.1em;
+    display: inline-block;
+    text-align: center;
+    background: white;
+    outline: none;
+    border: 1px solid dimgrey;
+    border-radius: 2px;
+    cursor: pointer;
+  }
+</style>
+<div id="sigma-container"></div>
+<form id="controls" action="#">
+  <fieldset>
+    <h4>Interactions</h4>
+    <div>
+      <input type="checkbox" id="enable-panning" name="enable-panning" checked />
+      <label for="enable-panning">Enable panning</label>
+    </div>
+    <div>
+      <input type="checkbox" id="enable-zooming" name="enable-zooming" checked />
+      <label for="enable-zooming">Enable zooming</label>
+    </div>
+    <div>
+      <input type="checkbox" id="enable-rotation" name="enable-rotation" checked />
+      <label for="enable-rotation">Enable camera rotations <br /><small>(for multitouch device only)</small></label>
+    </div>
+  </fieldset>
+  <fieldset>
+    <h4>Camera</h4>
+    <div>
+      <input type="number" id="min-ratio" name="min-ratio" value="0.08" min="0.001" step="0.001" />
+      <label for="min-ratio">Minimum camera zoom ratio <br /><small>(leave empty for no limit)</small></label>
+    </div>
+    <div>
+      <input type="number" id="max-ratio" name="max-ratio" value="3" min="0.001" step="0.001" />
+      <label for="max-ratio">Maximum camera zoom ratio <br /><small>(leave empty for no limit)</small></label>
+    </div>
+    <div>
+      <input type="checkbox" id="is-camera-bound" name="is-camera-bound" checked />
+      <label for="is-camera-bound">Bound camera</label>
+    </div>
+    <div>
+      <input type="number" id="tolerance" name="tolerance" min="0" step="1" value="500" />
+      <label for="tolerance">Tolerance (in pixels)</label>
+    </div>
+  </fieldset>
+  <fieldset>
+    <button type="submit" disabled>Update sigma settings</button>
+  </fieldset>
+</form>