Constrain Nodes to Clusters

docs/demos/Cluster.story.tsx

@@ -1,43 +1,107 @@
-import React from 'react';
+import React, { useCallback, useState } from 'react';
 import { GraphCanvas, lightTheme } from '../../src';
-import { clusterNodes, clusterEdges, random, singleNodeClusterNodes, imbalancedClusterNodes, manyClusterNodes } from '../assets/demo';
+import {
+  clusterNodes,
+  clusterEdges,
+  random,
+  singleNodeClusterNodes,
+  imbalancedClusterNodes,
+  manyClusterNodes
+} from '../assets/demo';
 
 export default {
   title: 'Demos/Cluster',
   component: GraphCanvas
 };
 
-export const Simple = () => (
-  <GraphCanvas nodes={clusterNodes} draggable edges={[]} clusterAttribute="type" />
-);
+export const Simple = () => {
+  const [nodes, setNodes] = useState(clusterNodes);
+
+  const addNode = useCallback(() => {
+    const next = nodes.length + 2;
+    setNodes(prev => [
+      ...prev,
+      {
+        id: `${next}`,
+        label: `Node ${next}`,
+        fill: '#3730a3',
+        data: {
+          type: 'IP',
+          segment: next % 2 === 0 ? 'A' : undefined
+        }
+      }
+    ]);
+  }, [nodes]);
+
+  return (
+    <>
+      <GraphCanvas nodes={nodes} draggable edges={[]} clusterAttribute="type" constrainDragging />
+      <div style={{ zIndex: 9, position: 'absolute', top: 15, right: 15 }}>
+        <button type="button" onClick={addNode}>
+          Add node
+        </button>
+      </div>
+    </>
+  );
+};
 
 const clusterNodesWithSizes = clusterNodes.map(node => ({
   ...node,
   size: random(0, 50)
 }));
 
 export const Sizes = () => (
-  <GraphCanvas nodes={clusterNodesWithSizes} draggable edges={[]} clusterAttribute="type" />
+  <GraphCanvas
+    nodes={clusterNodesWithSizes}
+    draggable
+    edges={[]}
+    clusterAttribute="type"
+  />
 );
 
 export const SingleNodeClusters = () => (
-  <GraphCanvas nodes={singleNodeClusterNodes} draggable edges={[]} clusterAttribute="type" />
+  <GraphCanvas
+    nodes={singleNodeClusterNodes}
+    draggable
+    edges={[]}
+    clusterAttribute="type"
+  />
 );
 
 export const ImbalancedClusters = () => (
-  <GraphCanvas nodes={imbalancedClusterNodes} draggable edges={[]} clusterAttribute="type" />
+  <GraphCanvas
+    nodes={imbalancedClusterNodes}
+    draggable
+    edges={[]}
+    clusterAttribute="type"
+  />
 );
 
 export const LargeDataset = () => (
-  <GraphCanvas nodes={manyClusterNodes} draggable edges={[]} clusterAttribute="type" />
+  <GraphCanvas
+    nodes={manyClusterNodes}
+    draggable
+    edges={[]}
+    clusterAttribute="type"
+  />
 );
 
 export const Edges = () => (
-  <GraphCanvas nodes={clusterNodes} draggable edges={clusterEdges} clusterAttribute="type" />
+  <GraphCanvas
+    nodes={clusterNodes}
+    draggable
+    edges={clusterEdges}
+    clusterAttribute="type"
+  />
 );
 
 export const Selections = () => (
-  <GraphCanvas nodes={clusterNodes} selections={[clusterNodes[0].id]} edges={clusterEdges} clusterAttribute="type" />
+  <GraphCanvas
+    nodes={clusterNodes}
+    selections={[clusterNodes[0].id]}
+    edges={clusterEdges}
+    clusterAttribute="type"
+  />
 );
 
 export const Events = () => (
@@ -47,7 +111,9 @@ export const Events = () => (
     edges={clusterEdges}
     clusterAttribute="type"
     onClusterPointerOut={cluster => console.log('cluster pointer out', cluster)}
-    onClusterPointerOver={cluster => console.log('cluster pointer over', cluster)}
+    onClusterPointerOver={cluster =>
+      console.log('cluster pointer over', cluster)
+    }
     onClusterClick={cluster => console.log('cluster click', cluster)}
   />
 );
@@ -100,15 +166,20 @@ export const LabelsOnly = () => (
 export const ThreeDimensions = () => (
   <GraphCanvas
     nodes={clusterNodesWithSizes}
-    draggable edges={[]}
+    draggable
+    edges={[]}
     layoutType="forceDirected3d"
     clusterAttribute="type"
   >
     <directionalLight position={[0, 5, -4]} intensity={1} />
   </GraphCanvas>
 );
 
-
 export const Partial = () => (
-  <GraphCanvas nodes={clusterNodes} draggable edges={[]} clusterAttribute="segment" />
-);
+  <GraphCanvas
+    nodes={clusterNodes}
+    draggable
+    edges={[]}
+    clusterAttribute="segment"
+  />
+);

src/GraphScene.tsx

@@ -148,6 +148,11 @@ export interface GraphSceneProps {
    */
   draggable?: boolean;
 
+  /**
+   * Constrain dragging to the cluster bounds. Default is `false`.
+   */
+  constrainDragging?: boolean;
+
   /**
    * Render a custom node
    */
@@ -322,6 +327,7 @@ export const GraphScene: FC<GraphSceneProps & { ref?: Ref<GraphSceneRef> }> =
         animated,
         disabled,
         draggable,
+        constrainDragging,
         edgeLabelPosition,
         edgeArrowPosition,
         edgeInterpolation,
@@ -384,6 +390,7 @@ export const GraphScene: FC<GraphSceneProps & { ref?: Ref<GraphSceneRef> }> =
               id={n?.id}
               labelFontUrl={labelFontUrl}
               draggable={draggable}
+              constrainDragging={constrainDragging}
               disabled={disabled}
               animated={animated}
               contextMenu={contextMenu}
@@ -397,6 +404,7 @@ export const GraphScene: FC<GraphSceneProps & { ref?: Ref<GraphSceneRef> }> =
             />
           )),
         [
+          constrainDragging,
           animated,
           contextMenu,
           disabled,
@@ -503,5 +511,6 @@ export const GraphScene: FC<GraphSceneProps & { ref?: Ref<GraphSceneRef> }> =
   );
 
 GraphScene.defaultProps = {
-  edgeInterpolation: 'linear'
+  edgeInterpolation: 'linear',
+  constrainDragging: false
 };

src/symbols/Node.tsx

@@ -52,6 +52,11 @@ export interface NodeProps {
    */
   draggable?: boolean;
 
+  /**
+   * Constrain dragging to the cluster bounds.
+   */
+  constrainDragging?: boolean;
+
   /**
    * The url for the label font.
    */
@@ -127,7 +132,8 @@ export const Node: FC<NodeProps> = ({
   onDragged,
   onPointerOut,
   onContextMenu,
-  renderNode
+  renderNode,
+  constrainDragging
 }) => {
   const cameraControls = useCameraControls();
   const theme = useStore(state => state.theme);
@@ -143,6 +149,7 @@ export const Node: FC<NodeProps> = ({
   const isSelected = useStore(state => state.selections?.includes(id));
   const hasSelections = useStore(state => state.selections?.length > 0);
   const center = useStore(state => state.centerPosition);
+  const cluster = useStore(state => state.clusters.get(node.cluster));
 
   const isDragging = draggingId === id;
   const {
@@ -211,6 +218,8 @@ export const Node: FC<NodeProps> = ({
   const bind = useDrag({
     draggable,
     position,
+    // If dragging is constrained to the cluster, use the cluster's position as the bounds
+    bounds: constrainDragging ? cluster?.position : undefined,
     // @ts-ignore
     set: pos => setNodePosition(id, pos),
     onDragStart: () => {

src/types.ts

@@ -48,6 +48,11 @@ export interface GraphNode extends GraphElementBaseAttributes {
    * Fill color for the node.
    */
   fill?: string;
+
+  /**
+   * Cluster ID for the node.
+   */
+  cluster?: string;
 }
 
 export interface GraphEdge extends GraphElementBaseAttributes {

src/useGraph.ts

@@ -63,6 +63,7 @@ export const useGraph = ({
   const layoutMounted = useRef<boolean>(false);
   const layout = useRef<LayoutStrategy | null>(null);
   const camera = useThree(state => state.camera) as PerspectiveCamera;
+  const dragRef = useRef<DragReferences>(drags);
 
   // Calculate the visible entities
   const { visibleEdges, visibleNodes } = useMemo(
@@ -75,12 +76,6 @@ export const useGraph = ({
     [stateCollapsedNodeIds, nodes, edges]
   );
 
-  // Transient updates
-  const dragRef = useRef<DragReferences>(drags);
-  useEffect(() => {
-    dragRef.current = drags;
-  }, [drags]);
-
   const updateLayout = useCallback(
     async (curLayout?: any) => {
       // Cache the layout provider
@@ -106,7 +101,8 @@ export const useGraph = ({
         sizingAttribute,
         maxNodeSize,
         minNodeSize,
-        defaultNodeSize
+        defaultNodeSize,
+        clusterAttribute
       });
 
       // Calculate clusters
@@ -137,6 +133,11 @@ export const useGraph = ({
     ]
   );
 
+  // Transient updates
+  useEffect(() => {
+    dragRef.current = drags;
+  }, [drags, clusterAttribute, updateLayout]);
+
   useEffect(() => {
     // When the camera position/zoom changes, update the label visibility
     const nodes = stateNodes.map(node => ({

src/utils/cluster.ts

@@ -34,15 +34,17 @@ export interface CalculateClustersInput {
 
 export interface ClusterGroup {
   /**
-   * The nodes in the cluster.
+   * Nodes in the cluster.
    */
   nodes: InternalGraphNode[];
+
   /**
-   * The position of the cluster.
+   * Center position of the cluster.
    */
   position: CenterPositionVector;
+
   /**
-   * The label of the cluster.
+   * Label of the cluster.
    */
   label: string;
 }

src/utils/graph.ts

@@ -49,6 +49,7 @@ interface TransformGraphInput {
   minNodeSize?: number;
   maxNodeSize?: number;
   defaultNodeSize?: number;
+  clusterAttribute?: string;
 }
 
 /**
@@ -62,7 +63,8 @@ export function transformGraph({
   sizingAttribute,
   defaultNodeSize,
   minNodeSize,
-  maxNodeSize
+  maxNodeSize,
+  clusterAttribute
 }: TransformGraphInput) {
   const nodes: InternalGraphNode[] = [];
   const edges: InternalGraphEdge[] = [];
@@ -96,6 +98,7 @@ export function transformGraph({
       label,
       icon,
       fill,
+      cluster: clusterAttribute ? data[clusterAttribute] : undefined,
       parents,
       data: {
         ...rest,

src/utils/useDrag.ts

@@ -3,10 +3,12 @@ import { useMemo } from 'react';
 import { useGesture } from '@use-gesture/react';
 import { Vector2, Vector3, Plane } from 'three';
 import { InternalGraphPosition } from '../types';
+import { CenterPositionVector } from './layout';
 
 interface DragParams {
   draggable: boolean;
   position: InternalGraphPosition;
+  bounds?: CenterPositionVector;
   set: (position: Vector3) => void;
   onDragStart: () => void;
   onDragEnd: () => void;
@@ -16,6 +18,7 @@ export const useDrag = ({
   draggable,
   set,
   position,
+  bounds,
   onDragStart,
   onDragEnd
 }: DragParams) => {
@@ -86,6 +89,26 @@ export const useDrag = ({
           .copy(mouse3D)
           .add(offset);
 
+        // If there's a cluster, clamp the position within its circular bounds
+        if (bounds) {
+          const center = new Vector3(
+            (bounds.minX + bounds.maxX) / 2,
+            (bounds.minY + bounds.maxY) / 2,
+            (bounds.minZ + bounds.maxZ) / 2
+          );
+          const radius = (bounds.maxX - bounds.minX) / 2;
+
+          // Calculate direction from center to updated position
+          const direction = updated.clone().sub(center);
+          const distance = direction.length();
+
+          // If outside the circle, clamp to the circle's edge
+          if (distance > radius) {
+            direction.normalize().multiplyScalar(radius);
+            updated.copy(center).add(direction);
+          }
+        }
+
         return set(updated);
       },
       onDragEnd