Add dolly camera controls

docs/Centering.mdx → docs/CameraControls.mdx

@@ -1,12 +1,13 @@
 import { Meta, Story, ArgsTable } from '@storybook/blocks';
 import { GraphCanvas } from '../src';
 
-<Meta title="Docs/Advanced/Centering" />
+<Meta title="Docs/Advanced/Camera Controls" />
+
+# Camera Controls
+Reagraph provides a set of camera controls that allow you to interact with the graph view. These controls include the ability to center the camera view around specific nodes, zoom in and out, and pan the camera view.
 
-# Centering
-Reagraph supports the ability to dynamically center nodes using the `centerGraph` and `fitNodesInView` methods from the `GraphCanvasRef`. These methods allows you to programmatically center the camera view around specific nodes or the entire graph.
 
-### Usage
+## Usage
 First, you need to get a reference to the `GraphRef`:
 
 ```jsx
@@ -16,8 +17,12 @@ return (
     <GraphCanvas ref={graphRef} {...} />
 )
 ```
+This ref will allow you to access the camera controls methods.
 
-Then, you can use the `fitNodesInView` method to center all nodes within view of the camera:
+## Centering
+Reagraph supports the ability to dynamically center nodes using the `centerGraph` and `fitNodesInView` methods from the `GraphCanvasRef`. These methods allows you to programmatically center the camera view around specific nodes or the entire graph.
+
+Use the `fitNodesInView` method to center all nodes within view of the camera:
 
 ```js
 graphRef.current?.fitNodesInView();
@@ -77,3 +82,63 @@ const MyComponent = ({ nodes }) => {
   return <GraphCanvas ref={graphRef} {...} />;
 };
 ```
+
+## Zooming/Dollying
+
+Use the `zoomIn` and `zoomOut` methods to zoom in and out of the graph. This will adjust the camera's zoom level, not the camera's position:
+
+```js
+graphRef.current?.zoomIn();
+graphRef.current?.zoomOut();
+```
+
+You can use the `dollyIn` and `dollyOut` methods to move the camera closer or further away from the graph:
+
+```js
+graphRef.current?.dollyIn();
+graphRef.current?.dollyOut();
+```
+
+### Examples
+In this example, clicking the "Zoom In" and "Zoom Out" buttons will zoom in and out of the graph:
+```jsx
+import React, { useRef } from 'react';
+import { GraphCanvas } from 'reagraph';
+
+const MyComponent = () => {
+  const graphRef = useRef<GraphCanvasRef | null>(null);
+
+  const zoomIn = () => {
+    graphRef.current?.zoomIn();
+  };
+
+  const zoomOut = () => {
+    graphRef.current?.zoomOut();
+  };
+
+  return (
+    <div>
+      <GraphCanvas ref={graphRef} {...} />
+      <button onClick={zoomIn}>Zoom In</button>
+      <button onClick={zoomOut}>Zoom Out</button>
+    </div>
+  );
+};
+```
+
+## Panning
+Use the `panUp`, `panDown`, `panLeft`, and `panRight` methods to pan the camera view:
+
+```js
+graphRef.current?.panUp();
+graphRef.current?.panDown();
+graphRef.current?.panLeft();
+graphRef.current?.panRight();
+```
+
+## Reset Controls
+Use the `resetCamera` method to reset the camera controls to their default values:
+
+```js
+graphRef.current?.resetCamera();
+```

docs/demos/Controls.story.tsx

@@ -19,6 +19,8 @@ export const All = () => {
         <br />
         <button style={{ display: 'block', width: '100%' }} onClick={() => ref.current?.zoomIn()}>Zoom In</button>
         <button style={{ display: 'block', width: '100%' }} onClick={() => ref.current?.zoomOut()}>Zoom Out</button>
+        <button style={{ display: 'block', width: '100%' }} onClick={() => ref.current?.dollyIn()}>Dolly In</button>
+        <button style={{ display: 'block', width: '100%' }} onClick={() => ref.current?.dollyOut()}>Dolly Out</button>
         <br />
         <button style={{ display: 'block', width: '100%' }} onClick={() => ref.current?.panDown()}>Pan Down</button>
         <button style={{ display: 'block', width: '100%' }} onClick={() => ref.current?.panUp()}>Pan Up</button>

src/CameraControls/CameraControls.tsx

@@ -137,6 +137,20 @@ export const CameraControls: FC<
       cameraRef.current?.zoom(-camera.zoom / 2, animated);
     }, [animated, camera.zoom]);
 
+    const dollyIn = useCallback(
+      distance => {
+        cameraRef.current?.dolly(distance, animated);
+      },
+      [animated]
+    );
+
+    const dollyOut = useCallback(
+      distance => {
+        cameraRef.current?.dolly(distance, animated);
+      },
+      [animated]
+    );
+
     const panRight = useCallback(
       event => {
         if (!isOrbiting) {
@@ -296,6 +310,8 @@ export const CameraControls: FC<
         controls: cameraRef.current,
         zoomIn: () => zoomIn(),
         zoomOut: () => zoomOut(),
+        dollyIn: (distance = 1000) => dollyIn(distance),
+        dollyOut: (distance = -1000) => dollyOut(distance),
         panLeft: (deltaTime = 100) => panLeft({ deltaTime }),
         panRight: (deltaTime = 100) => panRight({ deltaTime }),
         panDown: (deltaTime = 100) => panDown({ deltaTime }),

src/CameraControls/useCameraControls.ts

@@ -23,6 +23,16 @@ export interface CameraControlsContextProps {
    */
   zoomOut: () => void;
 
+  /**
+   * A function that dollies in the camera.
+   */
+  dollyIn: (distance?: number) => void;
+
+  /**
+   * A function that dollies out the camera.
+   */
+  dollyOut: (distance?: number) => void;
+
   /**
    * A function that pans the camera to the left.
    */
@@ -49,6 +59,8 @@ export const CameraControlsContext = createContext<CameraControlsContextProps>({
   resetControls: () => undefined,
   zoomIn: () => undefined,
   zoomOut: () => undefined,
+  dollyIn: () => undefined,
+  dollyOut: () => undefined,
   panLeft: () => undefined,
   panRight: () => undefined,
   panUp: () => undefined,

src/GraphCanvas.tsx

@@ -138,6 +138,8 @@ export const GraphCanvas: FC<GraphCanvasProps & { ref?: Ref<GraphCanvasRef> }> =
           rendererRef.current?.fitNodesInView(nodeIds, opts),
         zoomIn: () => controlsRef.current?.zoomIn(),
         zoomOut: () => controlsRef.current?.zoomOut(),
+        dollyIn: distance => controlsRef.current?.dollyIn(distance),
+        dollyOut: distance => controlsRef.current?.dollyOut(distance),
         panLeft: () => controlsRef.current?.panLeft(),
         panRight: () => controlsRef.current?.panRight(),
         panDown: () => controlsRef.current?.panDown(),